Overview

New Support Ticket

GETTING STARTED

BASICS

KNACKLY DESIGNERS

TRANSFORM DATA

ADMINISTRATION

PRACTICE AREA

Getting Started with the Knackly API

Before starting with Knackly’s API, it helps to understand Knackly’s use of the following terms:

  • Workspace = a given customer’s site on Knackly.
  • Catalog = a database / repository / table where a the customer’s data is stored and related documents are generated. One workspace can contain any number of catalogs.
    • A catalog is the boundary for data access permissions in Knackly: groups of users have rights to view/modify data, or see the documents produced from that data, based on whether they have access to the catalog or not.
    • API keys are also granted access on a per-Catalog basis.
  • Model = Knackly’s term for a schema. Each catalog has a (data) Model. Multiple different catalogs may be based on different models or the same model.  A model defines Variables, which in turn define the “shape” of an instance of that model.  Models are object-based.  Variables can be scalars or arrays; Knackly data types include “text”, “number”, “date”, “true/false”, and “object”. (Object-type variables also define which Model the object data must adhere to.)  There are also “selection” variables, where the answer is basically a foreign key (usually a text string) referring to some other object (which itself is stored in either a Table, an external Query, or elsewhere within the user data Record).
  • Record = a single item in a Catalog — a data object that adheres (more or less) to the Model of the catalog in which it is stored.  In other words, a data Record (in a catalog) is an instance of the catalog’s data Model.
  • Template = Knackly generates documents based on Templates. A template is created and maintained by an Admin user in Knackly. One Record (or other object), combined with one Template, will generate one document.
  • App = a process within Knackly, defined by an Admin user, that interactively gathers data from an end-user, stores it in a Record (in a Catalog), and generates some number of documents from that data. There is no limit to how many documents (based on templates) that a given app can produce; it can be dynamic based on the data provided.  Multiple Apps can also be run against the same Record at different times.

Some common use cases for the API include:

  1. Headless: Generate documents based purely on data you provide, bypassing the standard Knackly interactive app experienceHeadless: Generate documents based purely on data you provide, bypassing the standard Knackly interactive app experience
  2. Interactive: Provide data as a starting point for users who want to interactively review/modify that data, and potentially enter additional data, prior to documents being generated

 
Summary of Headless use case (generating documents non-interactively):

  1. Your application must “sign in” to a Knackly workspace by requesting an access token.  Before this can happen, an API key must be provisioned by the administrator of that workspace.
  2. Your application must specify which of the catalogs in that workspace you want to work with. You can discover the catalogs currently defined in a workspace (and that your API key has access to!) using the Get catalogs endpoint.
  3. Your application must specify which of the apps (which are associated with that catalog) you want to run, in order to produce documents.  You can discover the apps available for a given catalog using the Get apps for catalog endpoint.
  4. Your application should provide all the data needed for the selected app to run successfully. You can discover what data points the app cares about using the Get properties for app endpoint, OR by using the Get type information for app endpoint — whichever is a better fit for the way your particular application works.
  5. Your application provides the data to Knackly AND requests that documents be generated using the Create record in catalog by running app endpoint.  Data must be provided in JSON; it can be structured as nested objects and arrays (as described by Get type information for app) or as a single flat object (as described by Get properties for app).
  6. Document generation can take some time. Your application must poll using the Get status of an app on a record endpoint, to determine when the app has finished running and documents are ready.  Please do not poll more frequently than every few seconds.
  7. When documents are ready, the above endpoint will return the URLs your application can use to download the document(s) generated by the app.

 
Summary of Interactive use case (working with interactive user sessions):

(steps 1-3 are the same as above, and step 4 is similar)

  1. Your application must “sign in” to a Knackly workspace by requesting an access token.  Before this can happen, an API key must be provisioned by the administrator of that workspace.
  2. Your application must specify which of the catalogs in that workspace you want to work with. You can discover the catalogs currently defined in a workspace (and that your API key has access to!) using the Get catalogs endpoint.
  3. Your application must specify which of the apps (which are associated with that catalog) you want to run, in order to produce documents.  You can discover the apps available for a given catalog using the Get apps for catalog endpoint.
  4. Your application can provide relevant data to pre-fill the selected app’s inputs. You can discover what data points the app cares about using the Get properties for app endpoint, OR by using the Get type information for app endpoint — whichever is a better fit for the way your particular application works.
  5. Your application provides the data to Knackly using the Create record in catalog by running app endpoint.  Data must be provided in JSON; it can be structured as nested objects and arrays (as described by Get type information for app) or as a single flat object (as described by Get properties for app). Be sure to use the suspend option so documents are not immediately generated; you want the user to have a chance to run the app interactively.
  6. The above endpoint (Create record in catalog by running app) returns the metadata about the record that was created:
    { "id": "5e7d60758e7eda3138c41f5f", "detail": "", "status": "Needs Updating", "lastModified": "2020-03-27T02:09:57.968Z", "lastModifiedBy": "apitest", "data": { ... posted data ... }, "apps": , "url": "https://go.knackly.io/mycompany/Catalog1/5e7d60758e7eda3138c41f5f/App1" } ] }JavaScript . One of the properties of this record is an array of apps that have been used with this particular record. This array will include the app you just added to it.
  7. On that entry in the apps array, the “url” property gives you the URL to which you should redirect a user, in their browser, for them to be able to interactively review and update the data, and generate documents.

Here is the Postman URL to help in the process.

https://documenter.getpostman.com/view/6868588/SzS7QReU

Notes on potential API uses cases that are not yet supported, as of May 2021:

  • The API does not currently support dynamically creating or deleting Catalogs. These must be created (or deleted) by an Admin user in the web UI.
  • The API does not currently support deletion of Records within existing catalogs. Existing API use cases support only reading, modifying, or creating Records in catalogs.
  • The API does not currently support dynamically creating or modifying Apps, Templates, or Variables.  These must currently be maintained by an Admin user in the web UI.  However, the API can be used to query schema (Model) information for an existing app (for purposes of supplying relevant data when running the app).
  • The API does not currently support dynamically creating or modifying Users, Groups, Permissions, or API Keys.