Execute Subflow
execute_subflowExecute a ServiceNow Flow Designer subflow by scoped name, supporting foreground (blocking) and background (async) modes. Pass input variables as key-value pairs for testing or automation.
Instructions
Execute a ServiceNow Flow Designer subflow by scoped name. Subflows are reusable building blocks in Flow Designer — this is the primary tool for testing subflows during development.
In foreground mode (default), the call blocks until the subflow completes and returns outputs directly. In background mode, it returns a context ID for polling with get_flow_context_status.
Pass inputs as key-value pairs matching the subflow's input variables.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | The ServiceNow instance auth alias to use. This is the alias configured via `now-sdk auth --add` (e.g., "myinstance", "prod", "test"). The user will typically refer to this by name when saying things like "on my myinstance instance". If not provided, falls back to the SN_AUTH_ALIAS environment variable. | |
| scoped_name | Yes | Scoped name of the flow/subflow/action to execute (e.g., "global.my_flow", "x_myapp_custom.create_incident_subflow"). | |
| inputs | No | Input name-value pairs to pass to the flow/subflow/action. Keys are the input variable names defined in Flow Designer. | |
| mode | No | Execution mode. "foreground" (default) runs synchronously and returns outputs when complete. "background" returns immediately with a context ID — use get_flow_context_status to poll, then get_flow_outputs or get_flow_error to retrieve results. Use background for flows with approval/wait steps. | |
| timeout | No | Timeout in milliseconds for the execution. Only applies to foreground mode. Default is the ServiceNow server default (~30s). | |
| quick | No | Skip creation of execution detail records for better performance. Default false. Use true in CI/CD or when you don't need step-level detail. | |
| scope | No | Scope context for script execution. Can be a scope name (e.g., "x_myapp_custom") or sys_id. Use when the flow is in a scoped app. |