Skip to Content

REST JSON arrays (drill downs) in Jitterbit App Builder

Introduction

App Builder supports the transmission of complex, nested JSON arrays through the Drill Down feature. This allows developers to construct hierarchical data structures by specifying relationships between a root API call and its related sub-tables.

By using drill downs, you can navigate a JSON structure to ensure that parent records and their associated child records are processed in a single, unified operation.

JSON arrays in GET requests

A common use case for JSON arrays is a "One-to-Many" relationship, such as a customer with multiple addresses. In a standard GET request, App Builder interprets these as a collection where the root object contains an array of child objects.

The following JSON shows a customer record with multiple addresses:

"customers": [
    {
        "id": 1,
        "name": "Preston",
        "addresses": [
            {
                "street": "123 Broadway",
                "city": "NYC",
                "state": "NY"
            },
            {
                "street": "456 Multi-region Street",
                "city": "Boston",
                "state": "MA"
            }
        ]
    },
]

App Builder would create a root table with the ID and Name, and an additional Address table to contain the addresses, bound to the root table by the ID foreign key.

Configure POST requests with nested data

To send nested data to an external service, you must first organize your local data and then configure the corresponding API endpoint to accept the hierarchical structure.

Step 1: Organize local data

Ensure your local database reflects the structure you intend to send. For example, a local Customer table should be linked to an Address sub-table via a CustomerID foreign key.

Step 2: Configure the POST endpoint

Define the structure of the outgoing data within the REST data server configuration.

  1. Navigate to IDE > Data Servers.

  2. Open your REST data server and select Endpoints.

  3. Add or edit a POST endpoint.

  4. In Request Body, provide a sample JSON object that includes both the parent record and the child array.

  5. Verify that App Builder has generated the necessary tables for the REST endpoint.

Note

The Request Body field is only available for POST endpoints.

API Call configuration

To send nested data successfully, you must define hierarchical API Call rules that mirror the structure of your JSON.

Step 1: Define the root rule

Create a rule of type API Call that targets the root table (for instance, customers (post)). This rule is responsible for inserting primary fields like ID and Name.

Step 2: Define the nested rule

Create a secondary rule of type API Call that targets the nested path (for instance, customers (post)/addresses). This rule inserts the related child information into the array.

How to use Drill Down

The Drill Down setting is the mechanism that connects separate API Call rules into a single, nested operation. Follow these steps:

  1. Navigate to the top-level API Call rule.

  2. Open Advanced Settings and locate the Drill Downs panel.

  3. Click + Drill Down and specify the sub-rule to be executed (for instance, Customer_Address_POST).

  4. Configure the binding to ensure that the child data is correctly mapped to the parent record.