JSON Handler details

The main purpose of the JSON Handler channel is to consume a JSON response and loop over the data.

To break that down further, the channel allows you to make an API call, consume the JSON response, loop over each object in the JSON response, parse each of those objects, and also react to an incoming HTTP request using the Incoming JSON trigger step. This enables you to easily pass an incoming API response to another system using either the Quick Base channel or one of our integration channels.

In order to iterate over the JSON response you must use the Incoming JSON trigger step or the action step Fetch JSON prior to using the Iterate over JSON query step, within the your pipeline. For information about connecting with Pipelines Agent, see Quickbase Pipelines Agent connections.

Note: You cannot run the Iterate over JSON step against a Webhooks channel request.

JSON features

Objects

All responses beginning with a { (curly brace) at root level are called Objects. This is an example of a typical expected JSON response with objects.

Example 1

Arrays

Any lines in the response that start with [ (a bracket) are called Arrays. The following is an example of a typical JSON response with Array at the root level:

Example 2

Both Example 1 and 2 above can be fetched and consumed by the JSON Handler channel and also use it to iterate over the records.

Records

In the above examples, a record refers to the part of the response in this format:

JSON Handler Sources category

Incoming JSON (Trigger step)

This step will activate when you make an HTTP request (with a JSON response) to an auto-generated webhook endpoint.

Available step fields

Authentication Schema - supports Basic Auth and can restrict (set username and password option fields) who can hit the autogenerated endpoint.
Incoming request's method type - You can ignore incoming requests that do not match the method type by selecting Add Conditions in the step. Then select Method and select POST, PUT, PATCH, or ANY BELOW in the Method field. This filtering will not trigger the pipeline. By using this condition, the trigger will ignore any incoming requests that match. This is done even before the pipeline is executed, so no step runs will be charged.

Fetch JSON (Action step)

This step, when configured by the fields below, will retrieve the file for use with other steps in your pipeline.

Note: HTTP responses are limited to 32MB to help prevent memory issues. Requests larger than 32MB will return an error.

Available step fields

Authentication Schema - supports Basic and Digest Authentication and Quickbase Usertoken, based on selected Auth Schema username and password or token fields are marked as required.
Note: If you are going to use the Quickbase RESTful API (https://api.quickbase.com/v1/) in combination with a Quickbase Usertoken Authentication schema you will need to specify this header QB-Realm-Hostname and set your realm hostname.
Outgoing request's method type - select the type of the request from a list of supported ones
Headers - use this field to add extra headers to the fetching request
Request Body - some API endpoints are expecting to receive a specific request body like this one: https://developer.quickbase.com/operation/runQuery
JSON URL - API endpoint or URL which points to a JSON file. The link should be publicly available or behind Authentication schema which the channels supports. File channels (those channels that work with files. e.g. Dropbox, Onedrive, Box, etc. ) are also supported (pipelines:// protocol) and JSON files can be fetched using file_transfer_url filed.
Force Content Encoding - Force the encoding used to decode the JSON document. If left blank - Content-type header is taken into account, or if header is not presented utf-8 encoding is assumed. If specified - we will try to decode JSON response using the selected one.

Limits

We have a response size maximum of 1MB and because of that the Incoming JSON step and Fetch JSON step have limited export fields. Broken down the calculation used for the JSON response size is compress(raw json) + headers =(< 1MB) OK / (>=1MB) Fail.

JSON Objects category

Iterate over JSON (Query step)

Use this step to work with your data. The Iterate over JSON step is used in a pipeline only after using the Incoming JSON request step or the Fetch JSON step.

Available step fields

JSON Schema Sample (optional) - Sample JSON of the record iterating over. Used to generate user friendly fields used in subsequent steps during design time. If not specified, by default the record structure will be stored in the field raw_record.
JSON Records Path (optional) - used for nested arrays within JSON object on root level.

Using loop when iterating

You can loop over records, or an array of JSON objects. Use the following options, which are helpful for JSON record processing.

(A) JSON response (Incoming or Fetch JSON step) → (B) Iterate over JSON Records loop options:

JSON Source target can point to a previous step, but limited to Incoming or Fetch JSON step

JSON Records Path This will point to where the records are located. When your JSON records are nested, use this field to specify the location. For example: { 'result': 100, 'data': { 'type': 'Orders', 'records': [ JSON records, ... ] } } would use the path /data/records

Using Example 1, you can see an object and the records are stored under the field contacts,( /contacts )

If the root object is an array, as with Example 2, we don’t need to specify a JSON Records Path. You would also do this if your record location is at the root level.

JSON Schema sample optional field - used for generating user friendly fields (based on the JSON structure) for easier usages in next steps in the designer

If the option is not specified, then the records will be stored in {{b.raw_record}} and can be accessible only by writing a Jinja expression manually with prefix raw_record
You can not use the word type in your schema. Instead, use type1 or another word for example.
If the option is configured, then auto generated fields will be available for the next steps in the designer window. You can use a sample with fields you are interested in or all of them:

Example 2 should be typical since it is an array of objects/records.

The only thing you need to configure, but it is not important, is to specify the JSON Schema Sample.
You don’t need to use or specify something in JSON Records Path because at root level we have an array.

Example 3 (NOT SUPPORTED)

There is a specific JSON response standard called JSON lines which is currently not supported. See this community article and http://jsonlines.org/ for more information.

Differences between JSON Handler and Webhooks channels

If you want to use raw JSON body (without compression and consuming it with Jinja) you can use the Webhooks channel step Make Request. Both channels are similar but with some extra feature and limitations:

Webhooks/Make Request has support for OAuth 2.0 Client Credentials, JSON-Handler does not have it for now.
Webhooks/Make Request can access the raw JSON response using special field json, {{b.json['contacts'][0]['full_name']}}, the JSON Handler channel won't show you the field without the use of the Iterate over JSON Records step.
Webhooks/Make Request will fail if the response is larger than a 1MB raw JSON response + the extra export fields. Broken down the calculation is raw json + headers =(< 1MB) OK / (>=1MB) Fail.
Webhooks/Make Request does not have easy way to iterate over the records stored under {{b.json['contacts']}} field.

Capture a JSON response

You can use a third party tool to capture text returned in a JSON response. You can view these results for a complex JSON object to help you filter out data you don't need for your specific purposes.

For example, using the tool Postman, you'd perform a SEND API request to build the new request, from the Postman launch screen, click New > Request, or click the + button to open a new tab. Name your new request and then specify the details you need for your request. You will need to know the URL, method, and other optional values such as auth and parameters. Once your request has been authorized, you can view what has been returned by clicking on the Postman Body tab and clicking the Pretty option.

For example, this is a response of a contact record from the Quick Book RESTful API:

Did this page help?