Subflows
With Studio Subflows, you can break apart large, complex Flows into smaller Flows and link them together, enabling you to
- Reuse functionality across multiple branches and multiple Flows
- Transfer control of an Execution from one Flow to another
Common use cases for Subflows include encapsulation and reuse of common functionality, organizing complex Flows into logical subsets, and passing live Executions between Flows.
Examples:
- Create a reusable logging Subflow to POST data back to your own systems
- Transfer a Contact to another self-contained IVR or chatbot
- Encapsulate the gathering and verifying of a Contact's identity
- Pass a Contact's language preference to a Subflow to dynamically load the localized content
Beyond the use cases Subflows enable, there are secondary benefits that make building communications workflows with Studio an even more enjoyable experience:
- Reduces complexity for large Flows
- Removes the need to copy/paste widgets in multiple places
- Enables independent building and testing of new functionality
- Works with the Flows API , just like a regular Studio Flow!
Subflows are just like normal Flows except they use the new Subflow trigger type to attach widgets. Widgets connected to the Subflow trigger will only be executed when the Flow is being invoked as a Subflow.
A Subflow is invoked from another Flow, using the Run Subflow widget. The Flow that invokes a Subflow is called the parent Flow.
Execution control passes from the parent Flow to the Subflow. When the Subflow completes, control is passed back to the parent Flow.
Subflows Execute as part of the parent Flow
A Subflow's definition is loaded as part of the parent Flow at runtime, and all the steps of the Subflow and parent Flow are run as a single Execution. This means all your Subflow debugging logs are included in the parent logs, and there are no additional per-Execution fees for using Subflows!
To select the Subflow you wish to run, configure the Run Subflow widget to target an existing Flow where you've connected widgets to the Subflow trigger. Then, specify the Revision that should be executed at runtime. You can select an explicit revision number, or select the "Latest Draft Revision" or "Latest Published Revision," in which Studio will automatically select the correct revision at runtime.
The actual revision used at runtime is determined by the status of the parent Flow, the status of the target Subflow, and whether the Execution was started by a Test User. See Testing Subflows for details of runtime revision selection.
Note: Multiple references to the same Subflow within a parent Flow must all target the same Flow Revision.
To enhance the programmability of Subflows, Studio can pass variables into a Subflow, and the Subflow can pass variables back to the parent Flow.
A parent Flow can pass custom parameters into the Subflow at runtime as key/value pairs using the Run Subflow widget.
Note: Trigger data from the parent is automatically copied into the Subflow at runtime (e.g. {{trigger.call.CallSid}}).
Those parameters can then be referenced at runtime inside the Subflow via the trigger object: {{trigger.parent.parameters.foo}}
Similarly, a Subflow can pass variables back to the parent Flow upon completion using the Set Variables widget within the Subflow.
Those variables can then be referenced at runtime inside the parent Flow via the Run Subflow widget namespace: {{widgets.subflow_1.bar}}
Subflows can be tested from a parent Flow, or they can be tested independently of a parent Flow. To test a Subflow independently, just connect its widgets to one of the other trigger types (e.g. Incoming Call) and invoke the Flow using that trigger type:
When testing new drafts, only the Test Users of the parent Flow are used for Subflow execution. Test Users specified on a Subflow are ignored.
Drafts of a Subflow can be tested by selecting the Latest Draft Revision in the Run Subflow widget. Use a Test User to test the parent Flow and Studio will automatically select the latest draft of the Subflow. All other users will receive the latest published revision of the Subflow.
A Subflow executes as part of the parent Flow, so all the Subflow's Step logs are listed inline with the parent Flow's logs.
Tip: Use a Set Variables widget in the Subflow to expose a Subflow's internal context details to the parent Flow's logs for easier debugging.
To split out a set of widgets from an existing Flow into a Subflow, it's best to duplicate the Flow and use the new copy as the Subflow. In the newly created Subflow, delete the widgets from the original that aren't needed. Then connect the remaining widgets to the Subflow trigger.
In the parent Flow, delete the widgets that were copied to the Subflow and add a Run Subflow widget to connect the parent to the Subflow.
- Max of 50 Subflow widgets can be added to a parent Flow and those widgets can only reference up to 10 unique Subflow definitions
- Max of 2,000 total widgets can be defined between a parent Flow and all linked Subflow instances
- All Run Subflow widgets referencing the same underlying Flow definition must target the same Revision
- Only one level of Subflow nesting depth is allowed (i.e. Subflows can't call other Subflows)
- Subflow Flow SIDs and Flow Revisions do not support Liquid expressions; they must be statically defined in the parent Flow at design time
- Only simple values can be referenced when passing data in and back out of a Subflow
- The 1,000-step limit per Execution includes Subflow steps