iPaaS

Low code interface for requesting data from RESTful APIs external to the capture process. Use this node when no vendor specific integration (Netsuite, Dynamics 365, Quickbooks Online) exists.

Universal iPaaS is a licensed feature. Demo licenses can consume the feature, but fully licensed environments require the feature be available. Workflows using the node without a license will error.

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.

The request body’s text area allows for specification of raw data to be passed along with the request. Generally this would only be leveraged for POST and PATCH requests. Why not forbidden, it’s is generally considered bad practice for GET requests to include a request body. In most cases, you will find that GET requests will include any parameterized / variable data in the request URL itself.

The request body text area will generally (but is not required to) contain JSON formatted data, and may include notations. A basic request body might resemble:

{
    "vendorInvoiceNumber": "{p_Invoice Number}",
    "vendorNumber":"{p_selectedVendor}",
    "dueDate":"{p_Due Date}"
}

Note that the keys and values specified in any request body are dictated entirely by the host API. Refer to the API documentation for specifics on how to format requests.

Send document

Some APIs support the ability to receive a document file. This is common in ERP applications where you might create a new transaction (Bill) and then attach a PDF of the invoices to the transaction. With this option selected, the request body’s textarea is ignored. In it’s place, the file is sent to the API as multipart/form-data.

Add response (document)

With this option selected, the API request is expected to return a document. That document will be injected into the process, and would then follow any routing following that request. Use this option to retrieve a document form an external API and inject it into a capture workflow.

Formatting

Formatting options are available to manipulate response data.

Response Text Replacement

NOTE: This is a REQUEST formatter. It works against request data, prior to sending it to the API.

Use this option to perform simple full text replacements on API request values. This options accepts a regular expression that when matched, will replace a value with the regex match. Consider the pattern:

(?<=.*\s\--\s).*

This pattern will match any value that includes a space, two hyphens, and another space, then matches everything to the right of that sequence.

A request body of

{
  "vendorNumber":"Square 9 Softworks -- 77364"
}

would be translated to

{
  "77364"
}

Use this feature when working with data fields that are concatenated, like vendor lists. It’s common for vendor lists to include vendor name and vendor id. The user needs to see a vendor name for indexing purposes, and the ERP needs the vendor id for creating transactions. It would be possible to make additional API requests to perform runtime data lookups, but it’s generally best practice to minimize requests where possible.

Format Expression

NOTE: This is a RESPONSE formatter. It works against response data returned from an API.

The format expression is used to tune an API’s response to match an expected format by the iPaaS node. Each API can have it’s own response styling. Universal iPaaS attempts to automatically map header and table data from the response.

A single request may map header fields, or table fields, but not both. While it would be uncommon, you could map data required for a header from a table response and set those values to a header field later in the workflow.

Tables

For table mapping, repeating results are expected to be returned in an array with a key of “value”. Acceptable table response would resemble:

{
  "value":[
    {
      "vendorName":"Square 9 Softworks".
      "vendorId":"77364"
    },
    {
      "vendorName":"Microsoft",
      "vendorId":"77834"
    }
  ]
}

If would be impossible to document every variable response and how to reformat it. The comprehensive documentation on the formatting patterns may be found here. Specific reformatting examples may be found here.

Header / Summary Data

Header responses are slightly different. For GET requests, the response is inspected for a value array. If found, key mapping is performed from element 0 of that array. In the table example above, only the first vendor would map to the header fields if they were present. In other words, if your workflow had process fields for vendorName and vendorId respectively, given the response, those fields would be assigned the values “Square 9 Softworks” and “77364”.

For POST and PATCH requests, the top level response to mapped. For example:

{
  "count":25
}