Important
Celigo recommends that you customize your properties and configure your instance using integrator.io's interface. Customizing your instances using JSON requires a working knowledge of JSON and Celigo's standard APIs.
Before configuring an instance with JSON, it's important to understand how exports, imports, and connections are structured in the base flow. Instance overrides are applied by referencing the corresponding multi-instance flow's resource IDs and specifying the values to be overridden. You must be comfortable with JSON to use this feature. To learn more about JSON, see Work with JSON data in integrator.io.
There are requirements and valuable tips you should learn about before using integrator.io APIs to override your base flow. It's recommended that you read this article before you begin, even if you're using integrator.io APIs.
Important
Exports are called pageGenerators (PG) in the JSON structure of your integration flow. Imports and lookups are called pageProcessors (PP).
Before you begin, you must retrieve your API tokens and resource IDs. It's recommended that you read the following sections of this article first, since there are essential rules to follow before you begin overriding your base flow:
After selecting your customizable properties, use the GET /v1/flows/:_id endpoint to retrieve your base flow's properties. Don't forget to save the resource IDs for your flow's exports, imports, and connections. Once you've retrieved the base flow structure, copy and edit it as necessary. Then, POST the updated structure using the appropriate API endpoint.
The _abstractId always represents your base flow's resource IDs. When configuring your fields, you only have to add the fields you'd like overridden.
Important guidelines:
-
Some fields can't be overridden. While there is no comprehensive list of fields that can't be overridden, any invalid field overrides will be ignored.
-
Overrides cannot be defined for multi-instance base flows or standard flows — only for flow instances.
-
Overrides are optional — if not defined, the flow's configurations default to the multi-instance base flow.
-
You can override an export by replacing the
_exportId. -
You cannot override an import or lookup, but you can edit various fields within them.
-
To remove a value inherited from the multi-instance flow, set it to
null, an empty string '""', or 'undefined' in theoverridesstructure, depending on the field type.
|
Override structure |
{
"_id": "686•••••••••f84",
"name": "abstract flow",
"pageGenerators": [
{
"_exportId": "686••••••ce7",
"skipRetries": false
}
],
"routers": [
{
"_id": "routerId",
"branches": [
{
"pageProcessors": [
{
"type": "import",
"_importId": "686•••••••e6c",
"responseMapping": {
"fields": [],
"lists": []
}
}
]
}
]
}
],
"autoResolveMatchingTraceKeys": true,
"aiDescription": {
"summary": "This is an abstract flow",
"generatedOn": "2025-06-24T04:31:15.257Z"
}
}
|
|
Editable flow-level properties |
{
"aiDescription": {
"summary": "This is an instance flow"
},
"_runNextFlowIds": [
"nextFlowId"
]
}
|
Use the GET /v1/connections/:_id endpoint to retrieve your base flow's connection details. After you've retrieved the connection details, copy the IDs as necessary.
The _abstractId field represents the connection ID for your base flow (the connection you'd like to replace). The _id field represents the connection ID you want your instance to use.
|
Override body structure |
{
"connections": [
{
"_abstractId": "abstractFlowConnectionId",
"_id": "instanceFlowConnectionId"
}
]
}
|
Use the GET /v1/imports/:_id endpoint to retrieve your base flow's import configurations. After you've retrieved the import body structure, copy and edit it as necessary. Then, POST the updated structure using the appropriate API endpoint.
Important guidelines:
You can't replace your lookup or import step, but you can override most configuration details within the lookup or import. This includes mappings and hooks, along with most other import or lookup fields.
Note
You must provide import mappings for every field you want to keep. Unmapped import fields are ignored rather than falling back to the base flow’s mappings. There is a specific format you must use to remove all import mappings. See the Override structure in the table below to learn more.
|
Base flow structure |
NetSuite import mappings {
"_id": "67b••••••••••5a4",
"createdAt": "2025-02-26T12:00:40.392Z",
"lastModified": "2025-08-04T12:59:37.256Z",
"name": "netsuite import",
"_connectionId": "673••••••••••bb9",
"distributed": true,
"apiIdentifier": "i90067ac93",
"ignoreExisting": false,
"ignoreMissing": false,
"oneToMany": false,
"sandbox": false,
"lookups": [],
"netsuite_da": {
"restletVersion": "suiteapp2.0",
"operation": "update",
"recordType": "customer",
"internalIdLookup": {
"expression": "[\"internalid\",\"is\",\"{{{id}}}\"]"
},
"lookups": [],
"mapping": {
"fields": [
{
"extract": "[Keyword Search]",
"generate": "defaultaddress",
"internalId": false
},
{
"extract": "Medium",
"generate": "comments",
"internalId": false
}
],
"lists": [
{
"generate": "contact",
"fields": [
{
"extract": "Email",
"generate": "email",
"internalId": false
},
{
"extract": "Alt. Email",
"generate": "entityid",
"internalId": false
}
]
},
{
"generate": "_billing_addressbook",
"fields": [
{
"extract": "Name",
"generate": "addrphone",
"internalId": false
}
]
}
]
}
},
"adaptorType": "NetSuiteDistributedImport"
}
HTTP import mappings {
"_id": "680•••••••••17b",
"createdAt": "2025-04-28T06:49:34.471Z",
"lastModified": "2025-08-04T13:37:08.278Z",
"name": "http import requeue",
"requeue": true,
"_connectionId": "680••••••••6bd",
"_sourceId": "67f••••••••7a1",
"apiIdentifier": "ib85d257e6",
"ignoreExisting": false,
"ignoreMissing": false,
"oneToMany": false,
"mappings": [ // mapping 2.0
{
"extract": "$.itemIntId",
"generate": "itemId",
"dataType": "string",
"status": "Active",
"sourceDataType": "number"
}
],
"http": {
"relativeURI": [
"/workers/postData?delay=100"
],
"method": [
"POST"
],
"body": [],
"batchSize": 1,
"sendPostMappedData": true,
"isRest": false,
"formType": "http"
},
"adaptorType": "HTTPImport"
}
|
|
Override structure |
NetSuite override body structure {
"imports": [
{
"_abstractId": "67b•••••••••5a4",
"netsuite_da": {
"mapping": {
"lists": [
{
"generate": "contact",
"fields": [
{
"extract": "Email",
"generate": "name",
"internalId": false
},
{
"extract": "Alt. Email",
"generate": "emailid",
"internalId": false
}
]
}
]
}
}
}
]
}
HTTP override body structure {
"imports": [
{
"_abstractId": "680••••••17b",
"mappings": [
{
"extract": "$.internalId",
"generate": "itemInternalId",
"dataType": "string",
"status": "Active",
"sourceDataType": "number"
}
]
}
]
}
Override or remove all mappings {
"imports": [
{
"_abstractId": "680••••••17b",
"netsuite_da": {
"mapping": {
"fields": [
{}
],
"lists": [
{
"fields": []
}
]
}
}
}
]
}
|
|
Post-override body structure |
NetSuite body structure after the override {
"_id": "67b••••5a4",
"createdAt": "2025-02-26T12:00:40.392Z",
"lastModified": "2025-08-04T12:59:37.256Z",
"name": "netsuite import",
"_connectionId": "673••••••bb9",
"distributed": true,
"apiIdentifier": "i90067ac93",
"ignoreExisting": false,
"ignoreMissing": false,
"oneToMany": false,
"sandbox": false,
"lookups": [],
"netsuite_da": {
"restletVersion": "suiteapp2.0",
"operation": "update",
"recordType": "customer",
"internalIdLookup": {
"expression": "[\"internalid\",\"is\",\"{{{id}}}\"]"
},
"lookups": [],
"mapping": {
"fields": [//Retained from abstract export
{
"extract": "[Keyword Search]",
"generate": "defaultaddress",
"internalId": false
},
{
"extract": "Medium",
"generate": "comments",
"internalId": false
}
],
"lists": [ // Completely override lists from abstract import, as it is an array field
{
"generate": "contact",
"fields": [
{
"extract": "Email",
"generate": "name",
"internalId": false
},
{
"extract": "Alt. Email",
"generate": "emailid",
"internalId": false
}
]
}
]
}
},
"adaptorType": "NetSuiteDistributedImport"
}
HTTP body structure after the override {
"_id": "680•••••17b",
"createdAt": "2025-04-28T06:49:34.471Z",
"lastModified": "2025-08-04T13:37:08.278Z",
"name": "http import requeue",
"requeue": true,
"_connectionId": "680•••••6bd",
"_sourceId": "67f•••••••7a1",
"apiIdentifier": "ib85d257e6",
"ignoreExisting": false,
"ignoreMissing": false,
"oneToMany": false,
"mappings": [
{
"extract": "$.internalId",
"generate": "itemInternalId",
"dataType": "string",
"status": "Active",
"sourceDataType": "number"
}
],
"http": {
"relativeURI": [
"/workers/postData?delay=100"
],
"method": [
"POST"
],
"body": [],
"batchSize": 1,
"sendPostMappedData": true,
"isRest": false,
"formType": "http"
},
"adaptorType": "HTTPImport"
}
|
Use the GET /v1/exports/:_id endpoint to retrieve your base flow's configurations. Once you've retrieved the export body structure, copy and edit it as necessary. Then, POST the updated structure using the appropriate API endpoint.
Important guidelines:
-
For all non-flow resources—such as exports, imports, routers, and connections—you must reference the corresponding resource ID (
resourceId) along with the fields to override. -
Any matching fields from the multi-instance flow (at the flow, export, or import level) will be replaced by values specified in the instance flow’s overrides.
-
You can replace an entire export step with a new export by replacing the
_exportIdwhen overriding your flow details.
|
Multi-instance export structure |
{
"_id": "a5s•••••••39d",
"_connectionId": "h65••••••••k86",
"salesforce": {
"type": "soql",
"api": "rest",
"soql": {
"query": "SELECT Id, Name FROM Account"
}
}
}
|
|
Override structure |
{
"exports": [
{
"_abstractId": "a5s••••••39d",
"salesforce": {
"soql": {
"query": "SELECT Id, Name, Industry FROM Account"
}
}
}
]
}
Override exports {
"exports": [
{
"_abstractId": "690•••••••••914",
"_id": "690••••••••7ff"
}
]
}
Override listeners {
"exports": [
{
"_abstractId": "690•••••••••914",
"_id": "690•••••••••••7ff"
}
],
"_listenerIdsToIndex": [
"690••••••7ff"
]
}
|
There are several branch definition configurations you can override. Use the GET /v1/flows/:_id endpoint to retrieve your base flow's configurations. Don't forget to save the resource IDs for your flow's exports, imports, and connections. Once you've retrieved the branching structure, copy and edit it as necessary. Then, POST the updated structure using the appropriate API endpoint.
Important guidelines:
-
To override branch-level properties within a router, use the branch index as the
resourceId. Branches do not have unique IDs, so the index must be used instead of an ID. -
For router-level overrides, use the
resourceIdto reference the router’s ID and provide the relevant override fields. -
For all non-flow resources—such as exports, imports, routers, and connections—you must reference the corresponding resource ID (
resourceId) along with the fields to override.
|
Override structure |
{
"routers": [
{
"_abstractId": "abstractFlowRouterId",
"branches": [
{
"_abstractId": "1", // index of the branch
"inputFilter": {
"rules": [
"equals",
[
"number",
[
"extract",
"matches"
]
],
"1"
]
}
}
]
}
]
}
|
Use the GET /v1/flows/:_id endpoint to retrieve your base flow's configurations. After you've retrieved the import structure, copy and edit it as necessary. Then, POST the updated structure using the appropriate API endpoint.
Important guidelines:
You cannot edit your hook's script, but you can override configurations like the function and scriptId.
|
Override structure |
Override the postResponseMap hook {
imports: [{
_abstractId: abstractImportId,
hooks: {
postResponseMap: {
function: 'prm',
_scriptId: script._id
}
}
}]
}
|
You can use the GET /v1/flows/:_id endpoint to retrieve your base flow's configurations. Don't forget to save the resource IDs for your base flow's exports, imports, and connections. After retrieving the multi-instance flow structure, copy it as needed. Then, POST the updated structure using the appropriate API endpoint.
|
Example multi-instance flow body |
{
"_id": "686•••••••••f84",
"name": "abstract flow",
"pageGenerators": [
{
"_exportId": "686••••••ce7",
"skipRetries": false
}
],
"routers": [
{
"_id": "routerId",
"branches": [
{
"pageProcessors": [
{
"type": "import",
"_importId": "686•••••••e6c",
"responseMapping": {
"fields": [],
"lists": []
}
}
]
}
]
}
],
"autoResolveMatchingTraceKeys": true,
"aiDescription": {
"summary": "This is an abstract flow",
"generatedOn": "2025-06-24T04:31:15.257Z"
}
}
|
There are a few rules when overriding objects and arrays in your instance configuration:
-
Any override field that is an array will completely replace the corresponding array in the multi-instance flow.
-
Any override field that is an object will result in a shallow merge: only the specified properties will be overridden, and the rest will be inherited from the multi-instance flow.
-
To remove a value inherited from the multi-instance flow, set it to
null, an empty string '""', or 'undefined' in theoverridesstructure, depending on the field type.
The examples below model the behavior your instance configurations will follow.
Multi-instance flow – This is the multi-instance flow configuration. It includes both objects and arrays. If you were configuring an instance, this would be the "base" flow you're configuring from. To retrieve this data, see Retrieve your multi-instance flow's structure.
{
a: [{x: '1}, {y: '2'}...],
b: {
c: '1'
d: { e: '2', f: '3'}
}
}
Example A: Override field a and b.c – In this example, you're overriding all of field a because it's an array, and only b.c because it's an object. All other b fields are inherited from the multi-instance flow. The data below is what you'd paste into your Instance configuration field.
// Instance configuration overrides
{
a: [{z: '3'}],
b: { c: '2'}
}
The data below depicts the overriden instance or "final" version of the instance flow.
// Overridden instance
{ a: [{z: '3'}],
b: {
c: '2',
d: {
e: '2',
f: '3'}
}
}
}
Example B: Override only b.d.e – In this example, you're only overriding the b.d.e field. The d and b fields are inherited from the multi-instance flow.
// Instance configuration overrides
{
b: {d: {e:'5'}}
}
The data below depicts the the overriden instance or "final" version of the instance flow.
// Overridden flow instance
{
a: [{x: '1', {y: '2'}]
b: {c: '1', d: {e: '5', f: '3' }
}