All Square 9 iPaaS nodes provide the same level of functionality. In some cases, a vendor specific integration may exist. Generally this is to handle specific requirements of the host API as it relates to authentication. For most scenarios, the universal iPaaS node is appropriate.
Before configuring an iPaaS node, it’s generally helpful to understand the API being leveraged. Use a tool like Postman to test request into the target API. Many API’s, including Square 9’s GlobalSearch API, include a Postman Collection for this specific purpose. At a minimum, you must understand the response to API requests to ensure GlobalCapture can map response data correctly.
Universal iPaaS is built to communicate with mondern Restful api’s and accepts JSON response formats.
Configuration
All iPaaS configuration can be broken down into three sections. These include connection (how to authenticate), request (the call to make and the data to send to it), and formatting (translating an API’s response to something the node can understand).
Connection Settings
Connection settings are grouped within a collapsable panel on the node. Expand the panel to access the settings. When multiple iPaaS nodes are used in a single workflow, the connection settings are common. Set them once and copy/paste additional versions of the node to minimize efforts. Authentication to an external API is generally the most technically demanding step, particularly for less technical users.
Authentication URL
In some cases, authentication to an API uses a different endpoint than the other calls to perform the API’s function. In these cases, provide the web address to the authentication endpoint here. Authentication URLs are used when authenticating to GlobalForms to query submission data.
Base URL
The Base URL represents the root of the API request. This is largely a helper element, allowing the actual API request to represent just the variable pieces in the Request setting. The value provided here is concatenated in front of the value in the Request setting to make a complete URL.
User Name / Password
Authentication to be used in credentialing to the target API. When just a user and password are provided, those credentials are added as a Basic authorization header. Specifically user and password are merged, separated by a colon, and then base64 encoded. That base64 encoded string is then prefixed with “Basic “ and added to an “Authorization” request header.
This is standard formatting to Basic Auth requests. Refer to the specific authentication requirements for your target API, but this approach will satisfy any Basic Auth approach.
JWT Auth
Enabling JWT Auth is required for authenticating to GlobalForms. When enabled, a parameterized authentication request is made to the Authentication URL, presumed to be a GlobalForms login form which will respond with a JWT token. That token is then added to the x-jwt-token header for the API request to be made. Future versions may extend JWT auth outside the scope of GlobalForms.
Additional Header Key / Value
In some cases, APIs may require specific headers, either for authorization, or some other variable purpose. Any data placed into the key and value settings for Additional Header will be injected into the request header for the call.
Requests
Calls to most modern APIs involve generating a URL with addressable components. There are various request settings available.
Request
The request, paired automatically with the Base URL, form a URL where the request is to be made. As an example, if one were to request from GlobalSearch a list of searches in a database, you would see:
Base URL: https://<yourGlobalSearchInstance>/Square9API/api/
Request: dbs/<databaseId>/searches
Every API is different, and will have different elements. For this example, “dbs” represents shorthand for “databases”. The request then expects the ID of the database you will to request information from. There are separate requests to understand what databases are available if needed. “searches” tells the request to return a data set that represents searches for the given database.
This is a high level overview of how a request works, but again, using a tool like Postman will allow you to craft and test requests and see their responses. In the case of GlobalSearch, the postman collection will allow you to understand all available requests, how they are formatted, and their responses.
Sometimes, requests can be statically defined, like “dbs/1012/searches”. In others, requests need to be more dynamic, and may even rely on data from other requests. In such cases, the request may contain Square 9 Notations (references to previously assigned process data), like “dbs/{p_DatabaseID}/searches”. In this example, {p_DatabaseID} is a reference to a process field that would contain the value of interest, per the previous example “1012”.
The specific documentation for your target API is the best resource for understanding how to get and set the data of interest.
Request Body
The body of the request allows you to provide additional data, outside the URL, in addition to specifying what type of request to make.
Universal iPaaS supports 3 different requests types. This may be extended in future revisions. Supported requests include GET, POST, and PATCH. The documentation for the target API will specify what type of request is required, and depending on the API, there could be variances to “expected” types of requests. Generally speaking:
GET - Requests data or a specific a resource
POST - Creates a new resource
PATCH - Applies partial modifications to a resource
The most common request types will be GET/POST.