Integrate a CloudFlow workflow as a child flow-CloudFlow(CloudFlow)-阿里云帮助中心

CloudFlow supports nesting -- a parent flow can invoke one or more child flows as task nodes through the FNF:StartExecution action. This lets you:

Design modularly -- Separate high-level orchestration from lower-level, task-specific flows.
Reuse flows -- Call a shared flow from multiple parent flows instead of duplicating steps.
Debug independently -- Keep each flow small enough to inspect and troubleshoot on its own.

Important

The parent and child flows must be in the same region. Cross-region invocation is not supported.

Quick start

The following flow definition invokes a child flow using the RequestComplete integration mode. The task completes as soon as the child flow starts.

Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: StartExecution
States:
  - Type: Task
    Name: StartExecution
    Action: FNF:StartExecution
    TaskMode: RequestComplete
    Description: an example of workflow invocation
    Parameters:
      resourceArn: acs:fnf:cn-hangzhou::flow/test-workflow
      executionName: theExecutionName
      input:
        key: value1
    End: true

Key fields:

Field	Description
`Action`	Set to `FNF:StartExecution` to invoke a child flow.
`TaskMode`	The integration mode. Valid values: RequestComplete, WaitForSystemCallback, WaitForCustomCallback.
`Name`, `Description`	A name and description for the task. Set values appropriate for your use case.

Parameters

Parameter	Required	Description	Example
`resourceArn`	Yes	The Alibaba Cloud Resource Name (ARN) of the child flow. Find the ARN on the flow details page in the CloudFlow console.	`acs:fnf:::flow/test-workflow`
`executionName`	No	A name for the execution. If omitted, the system assigns a unique value automatically. If specified, the name must be unique within the flow.	`test-execution-name`
`input`	No	Business data to pass to the child flow. The value must be an object.	See the example below.

Pass dynamic input

Use the .$ suffix to reference values from the parent flow's input:

input.$:
  key1: val1
  key2: $Input.age

Return value

Starting a child flow returns a JSON object:

{
    "FlowName": "test-workflow",
    "ExecutionName": "36cc6107-26cc-495f-b80b-d9fadff13fdd",
    "RequestID": "12423452346y345634"
}

Integration modes

Three integration modes control how the parent flow interacts with the child flow after invocation. Choose the mode that matches your orchestration needs.

Mode	Behavior	Use when
`RequestComplete`	Task completes as soon as the child flow starts.	The parent does not depend on the child flow's result (fire-and-forget).
`WaitForSystemCallback`	Parent pauses until the child flow finishes, then resumes automatically.	The parent depends on the child flow's completion but no custom reporting logic is needed.
`WaitForCustomCallback`	Parent pauses and passes a callback token to the child flow. The child (or an external system) must report the result to advance the parent.	Custom logic determines whether the child flow succeeded or failed.

RequestComplete

The task completes as soon as the request to start the child flow succeeds. The parent does not wait for the child flow to finish.

TaskMode: RequestComplete

WaitForSystemCallback

The parent flow pauses automatically after starting the child flow. When the child flow finishes, the system resumes the parent flow.

TaskMode: WaitForSystemCallback

WaitForCustomCallback

The parent flow passes a callback token to the child flow and enters the Pending state. The child flow (or an external system) must report the result by calling the ReportTaskSucceeded or ReportTaskFailed API operation with the token. Only then does the parent flow advance.

To pass the callback token to the child flow, add a token field in the input section and reference the token value with the $Context.Current.TaskToken expression:

Parameters:
  resourceArn: acs:fnf:cn-hangzhou::flow/test-workflow
  executionName: theExecutionName
  input:
    key: value1
    token.$: $Context.Current.TaskToken

In the child flow, retrieve the callback token from the token field in the input. Use token.key to access the token name. The token value is populated by the $Context.Current.TaskToken expression. Call the ReportTaskSucceeded or ReportTaskFailed API operation with this token to report the result and advance the parent flow.

Error codes

Error code	Description	Action
`FNF.ResourceThrottled`	The flow execution is throttled.	Retry after a short delay.
`FNF.FlowNotExists`	The specified flow does not exist.	Verify the `resourceArn` value.
`FNF.AccessDenied`	The current user or role does not have permission to run the flow.	Grant the required permissions to the user or role.
`FNF.ExecutionAlreadyExists`	An execution with the same name already exists in the flow.	Use a unique `executionName`.
`FNF.InternalServerError`	An internal server error occurred.	Retry the request.