A multi-instance flow is a flow you build once and then run as many customized copies, called instances. Each instance inherits its configuration from the multi-instance flow and changes only the properties you allow it to change, such as a connection, an export's relative URI, or an import's mappings. Use multi-instance flows when you need the same integration for many stores, customers, or regions that differ only in a few settings. This article explains the key terms, how instances inherit and override configuration, and when multi-instance flows are and aren't a good fit.
Note: Multi-instance flows are available in Professional and Enterprise editions.
Key concepts
A multi-instance flow has four parts: the base flow, its customizable properties, its instances, and each instance's overrides.
Base flow
The base flow is the multi-instance flow itself. It holds the shared configuration for every instance: its exports, imports, lookups, branching, mappings, and hooks. In integrator.io, the base flow displays a Multi-instance label next to its name. You can't run or schedule a base flow directly; only its instances run.
Customizable properties
Customizable properties are the fields on the base flow that instances are allowed to change. You select them for each flow step in the Customizable properties panel, for example an export's Connection and Relative URI, or an import's Mapping. Instances configured in the Simple view can change only these properties.
Instance
An instance is a flow generated from the base flow's configuration. Each instance has its own name, schedule, on/off state, run history, and errors. An instance can't itself be a multi-instance flow.
Override
An override is a value an instance uses in place of the base flow's value. Overrides are optional. Any property an instance doesn't override uses the base flow's value.
How instances inherit configuration
Every instance starts from the base flow's configuration and then applies its own overrides. This gives you two places to make changes:
- Change the base flow to update every instance at once, for example to fix a mapping that's wrong for all stores.
- Change an instance to update only that instance, for example to point one store at a different connection.
Instances use the base flow's exports, imports, and lookups directly, so a change you save to the base flow applies to every instance the next time it runs. You don't need to update the instances.
You can configure overrides in two ways. The Simple view shows a form for the customizable properties you selected. The JSON view accepts an override structure that can reach fields beyond the customizable properties list, such as replacing an export or changing a router branch. The same JSON structure works in the integrator.io API.
Use case: Multiple Shopify or Magento stores
This use case is ideal for brand aggregators with multiple, similar Shopify or Magento “stores”. The stores may be identical, but use different connectors, store names, or slightly different mappings. In this case, you’d need 500 similar, but unique, integrations.
Traditionally, you’d need to create one integration and clone it 500 times. With multi-instance flows, you can create one integration, add 500 instances, and customize each instance quickly. The instances all use the same base flow, but each instance can be uniquely tailored to match the needs of each store.
If this integration uses webhooks, see Configure webhooks in multi-instance flows to determine which approach fits your store configuration.
When to use multi-instance flows
Multi-instance flows work best when every variant shares the same flow steps and differs only in a small set of values. Common examples include one integration per store, per customer, per subsidiary, or per region.
Use a standard flow instead in these situations:
- The variants differ in structure, such as different steps or different destination apps. A shared base flow would carry logic that most instances don't use.
- You need to run or schedule the flow itself. A base flow can't be run manually or scheduled.
- Every instance needs its own webhook URL and you have many instances. Maintaining a per-instance listener override for each instance can cost more effort than maintaining separate flows.
- Another flow needs to trigger this flow as its Run next flow. A multi-instance flow can't be the target of a run-next setting.
For the full list of constraints, see Multi-instance flow rules and limitations.