JSON overrides let you configure a multi-instance flow instance beyond the customizable properties shown in the Simple view. With JSON, you can replace a connection or an export, change a router branch, point a hook at a different script, or override any overridable field on an import. You can enter the same override structure in an instance's JSON view or send it through the integrator.io API. This article is for builders who are comfortable reading and editing JSON. If you only need to change customizable properties, use the Simple view instead, as described in Create and configure instances.
Prerequisites:
- You're familiar with JSON. For an introduction, see Work with JSON data in integrator.io.
- You have the resource IDs of the base flow and of its connections, exports, imports, and routers. See Get the base flow's resource IDs in this article.
- To use the API, you have an API token. See Create and manage API and Personal Access tokens.
How overrides work
An instance override is a JSON object that lists only the values the instance changes. Every value you leave out comes from the base flow.
The base flow is referred to as the abstract flow in the JSON structure. To target a resource in the base flow, add its resource ID as _abstractId. For example, an export override with "_abstractId": "6861a2b3c4d5e6f7a8b9c0d1" changes the base flow export with that ID.
Overrides follow three merge rules:
- Objects merge. When an override value is an object, only the properties you include replace the base flow's properties. Every other property in that object comes from the base flow.
- Arrays replace. When an override value is an array, it replaces the base flow's entire array. Include every array item you want to keep, not only the items you change.
- Empty values remove. To remove a value the instance would inherit, set it to
nullor an empty string (""), depending on the field type.
Some fields can't be overridden. integrator.io ignores an override for these fields without returning an error. See Verify that overrides took effect in this article.
Merge rule example
The following base flow configuration contains an array (a) and a nested object (b):
{
"a": [{ "x": "1" }, { "y": "2" }],
"b": {
"c": "1",
"d": { "e": "2", "f": "3" }
}
}
This override changes the array a and the property b.c:
{
"a": [{ "z": "3" }],
"b": { "c": "2" }
}
The instance uses this result. The array a is replaced entirely, and b.d is inherited from the base flow:
{
"a": [{ "z": "3" }],
"b": {
"c": "2",
"d": { "e": "2", "f": "3" }
}
}
This second override changes only b.d.e:
{
"b": { "d": { "e": "5" } }
}
The instance uses this result. Everything except b.d.e is inherited:
{
"a": [{ "x": "1" }, { "y": "2" }],
"b": {
"c": "1",
"d": { "e": "5", "f": "3" }
}
}
Get the base flow's resource IDs
Every override except flow-level fields needs the resource ID of the base flow resource it changes. Get these IDs from the base flow's configuration.
- Send a
GETrequest to/v1/flows/{baseFlowId}. For details, see Flows API reference. - In the response, record these IDs:
-
pageGenerators[]._exportIdfor each export or listener. The JSON structure calls exports page generators. -
routers[].branches[].pageProcessors[]._importIdfor each import, and_exportIdon the same entries for each lookup. The JSON structure calls imports and lookups page processors. A base flow always stores its steps inside routers, even when the flow has no branching. -
routers[].idfor each router. Router IDs are stored inid, not_id.
-
- To get connection IDs, send a
GETrequest to/v1/exports/{exportId}or/v1/imports/{importId}and record_connectionId.
The following example shows the parts of a base flow response you need:
{
"_id": "6861a2b3c4d5e6f7a8b9cf84",
"name": "Shopify orders to NetSuite",
"pageGenerators": [
{ "_exportId": "6861a2b3c4d5e6f7a8b9cce7" }
],
"routers": [
{
"id": "6861a2b3c4d5e6f7a8b9c111",
"branches": [
{
"pageProcessors": [
{ "type": "import", "_importId": "6861a2b3c4d5e6f7a8b9ce6c" }
]
}
]
}
]
}
Apply overrides in the JSON view
The JSON view on an instance accepts the full override structure.
- Go to Build
, and then select Flows.
- Open the multi-instance flow, and then select the Instances tab.
- Open the instance:
- To create a new instance with JSON, select Create with JSON. If the base flow already has instances, select Create instance, and then select JSON.
- To edit an existing instance, select Instance configuration in the instance's row.
- Select JSON.
- Enter the override structure. For a new instance, the editor opens empty. For an existing instance, it shows the instance's current overrides.
- Select Save.
Apply overrides through the API
An instance is a flow resource with two additional properties: _abstractFlowId, which holds the base flow's ID, and overrides, which holds the override structure described in this article. You create and update instances with the standard Flows API endpoints. There's no separate multi-instance endpoint. For the full schema, see Flows on developer.celigo.com.
Create an instance
Send a POST request to /v1/flows. Include the instance name, the integration ID, the base flow ID in _abstractFlowId, and the overrides. _abstractFlowId can't be changed after the instance is created.
{
"name": "Denver store orders",
"_integrationId": "6851a2b3c4d5e6f7a8b9c001",
"_abstractFlowId": "6861a2b3c4d5e6f7a8b9cf84",
"overrides": {
"connections": [
{
"_abstractId": "6731a2b3c4d5e6f7a8b9cbb9",
"_id": "6731a2b3c4d5e6f7a8b9c345"
}
]
}
}
Update an instance
PUT /v1/flows/{_id} replaces the entire flow, so retrieve the instance first and send back the complete object.
- Send a
GETrequest to/v1/flows/{instanceId}. The response contains the instance's own fields,_abstractFlowId, andoverrides. - Edit the
overridesobject. - Send the complete object in a
PUTrequest to/v1/flows/{instanceId}. Any field you leave out is reset to its default.
You can't change overrides with PATCH /v1/flows/{_id}. PATCH accepts only a fixed list of paths, and /overrides isn't one of them.
Override structure reference
An override object can contain these top-level properties. Include only the ones you need.
-
connections— An array of connection replacements. -
exports— An array of export and lookup overrides or replacements. -
imports— An array of import overrides. -
routers— An array of router and branch overrides. -
name,description,settings, andtimezone— Flow-level values for the instance. -
_runNextFlowIds— An array of flow IDs that run after the instance finishes. -
_runNextExportIds— An array of specific exports, in other flows, that run after the instance finishes.
The AI-generated description (aiDescription) can't be overridden. An aiDescription value in an override is ignored without an error.
Flow-level properties
You can override flow-level values such as the instance's timezone and the flows that run after it.
{
"timezone": "America/Denver",
"_runNextFlowIds": ["6861a2b3c4d5e6f7a8b9d222"]
}
An instance can trigger other flows through _runNextFlowIds. A multi-instance flow can't be the target of another flow's run-next setting.
Connections
To replace a base flow connection, add the base flow connection ID as _abstractId and the replacement connection ID as _id.
{
"connections": [
{
"_abstractId": "6731a2b3c4d5e6f7a8b9cbb9",
"_id": "6731a2b3c4d5e6f7a8b9c345"
}
]
}
Exports
You can override fields on a base flow export, or replace the export with a different export.
To override fields, add the export ID as _abstractId and include only the fields to change. This example changes a Salesforce SOQL query:
{
"exports": [
{
"_abstractId": "6861a2b3c4d5e6f7a8b9cce7",
"salesforce": {
"soql": {
"query": "SELECT Id, Name, Industry FROM Account"
}
}
}
]
}
To replace the export, add the base flow export ID as _abstractId and the replacement export ID as _id:
{
"exports": [
{
"_abstractId": "6901a2b3c4d5e6f7a8b9c914",
"_id": "6901a2b3c4d5e6f7a8b9c7ff"
}
]
}
To replace a webhook listener, see Configure webhooks in multi-instance flows.
Lookups
A lookup is an export resource, so lookup overrides go in the exports array, not the imports array. Add the lookup's _exportId as _abstractId. As with exports, you can override individual fields, or add a replacement lookup's ID as _id to replace the lookup.
Imports
You can override most fields on an import, including mappings and hooks. You can't replace an import with a different one.
Mappings are arrays, so a mapping override replaces the entire array it targets. Include every mapping in that array that the instance needs, not only the mappings you change. Mapping arrays you don't include are inherited from the base flow.
This example overrides the mappings on an HTTP import that uses Mapper 2.0:
{
"imports": [
{
"_abstractId": "6801a2b3c4d5e6f7a8b9c17b",
"mappings": [
{
"extract": "$.internalId",
"generate": "itemInternalId",
"dataType": "string",
"sourceDataType": "number",
"status": "Active"
}
]
}
]
}
This example overrides the lists mappings on a NetSuite import. The import's fields mappings aren't included, so the instance inherits them from the base flow:
{
"imports": [
{
"_abstractId": "67b1a2b3c4d5e6f7a8b9c5a4",
"netsuite_da": {
"mapping": {
"lists": [
{
"generate": "contact",
"fields": [
{ "extract": "Email", "generate": "name", "internalId": false },
{ "extract": "Alt. Email", "generate": "emailid", "internalId": false }
]
}
]
}
}
}
]
}
To remove all fields and lists mappings from a NetSuite import, use this structure:
{
"imports": [
{
"_abstractId": "6801a2b3c4d5e6f7a8b9c17b",
"netsuite_da": {
"mapping": {
"fields": [{}],
"lists": [{ "fields": [] }]
}
}
}
]
}
Routers and branches
To override a router, add the router's id as _abstractId. To override a branch, add the branch's index in the router as its _abstractId, as a string.
This example changes the input filter on the branch with index "1":
{
"routers": [
{
"_abstractId": "6861a2b3c4d5e6f7a8b9c111",
"branches": [
{
"_abstractId": "1",
"inputFilter": {
"version": "1",
"rules": ["equals", ["number", ["extract", "matches"]], "1"]
}
}
]
}
]
}
Hooks
You can change which script and function a hook calls. You can't edit the script's code in an override. To change the code, edit the script or create a new script.
This example points an import's post-response map hook at a different script:
{
imports: [{
_abstractId: abstractImportId,
hooks: {
postResponseMap: {
function: 'prm',
_scriptId: script._id
}
}
}]
}
Verify that overrides took effect
integrator.io ignores overrides for fields that can't be overridden and doesn't display an error. After you save an override, retrieve the instance's merged configuration to confirm it uses the value you expect.
Send a GET request to /v1/flows/{instanceId}?mergeInstance=true. The response combines the base flow's configuration with the instance's overrides, so it shows the configuration the instance runs with. Without mergeInstance=true, the response contains only the instance's own fields and overrides.