Flow Instances

To configure or run flows for a given customer and connection, you need to get a Flow Instance.

Flow Instance has the following properties:

id – Unique identifier of the instance.
parameters – Parameters (matching parametersSchema) for this particular flow instance.
nodes – nodes and their configurations for this particular flow instance.
isCustomized – whether this data source was customized by your customer (path was changed, etc.)

Each node has the following properties:

config: node configuration (you can update it when updating the flow instance)
inputSchema: auto-generated schema for the node input (output of all the previous nodes)
outputSchema: auto-generated schema for the node output (output of this node)

See details of how configuration looks for each node here: Flow Nodes.

See available operations on flow instances here: Flow API.

API

To run flows, you need to create a Flow Instance for a specific Customer Connection.

Each flow instance contains a copy of the flow with possible customization by your customers.

Whether a Flow Instance was customized could be determined by its isCustomized property.

Get

You can select or create a Flow Instance using the following parameters:

flowKey or flowId – a Flow you want to create the instance for.
integrationKey, integrationId, or connectionId – a Connection you want to create the instance for.
autoCreate (optional) – whether to create a flow instance if it does not exist yet.

await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}')
  .get()

Run

To run a flow, do the following:

await integrationApp
  .flowInstance('{FLOW_INSTANCE_ID}')
  .run({
    
    input: null
  })

The result will be a Flow Run.
If you use REST API, you will get the flow run immediately, and it will be in "Queued" or "Running" state. If you use a front-end SDK, it will return a promise that will resolve to a flow run when it is finished.

To get the output of the flow run, do the following:

await integrationApp
  .flowRun('{FLOW_RUN_ID}')
  .getOutput()

Read more about running flows here: Flow Runs

List

To list all the Flow Instances created for the current user, use the find method:

await integrationApp
  .connection('hubspot')
  .flows.list()

Update

To update some fields of a Flow Instance, use the patch method:

await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}')
  .patch('{INPUT}')

Enable or Disable

When a Flow Instance is created, it is enabled by default. You can disable or enable it back by patching the enabled property.

When a Flow Instance is disabled, it will not be launched automatically with triggers such as App Event Trigger.
It can still be launched via API or through management UI.

Set up / Refresh

Setting up a flow instance will re-fetch all the dependencies (data sources, schemas, etc.) and recalculate dynamic fields.

await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}')
  .setup()

Reset

Resetting a flow instance brings it to a default state, erasing all the customer configuration.

await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}')
  .reset()

Multiple Flow Instances per Connection

By default, each pair of Connection and Flow will have only one Flow Instance.

In some cases you may want to create multiple copies of the flow for a given connection.
This can be achieved by providing instanceKey. Each instanceKey will create a new Flow Instance.

await integrationApp
  .connection('hubspot')
  .flow('{FLOW_KEY}', { instanceKey: '{INSTANCE_KEY}' })
  .get({ autoCreate: true })

You can pass instanceKey to any API / SDK method that works with flow instances.

API

Get

Run