A Task state calls an API operation of an integrated service as a single unit of work within a workflow. Use Task states to invoke Function Compute functions, Alibaba Cloud service APIs, or third-party services over HTTP/HTTPS.
In Flow Definition Language (FDL), set Type to Task to define a Task state.
Supported service types
A Task state can call three categories of services. Specify the target in the Action field using the format <ServiceName>:<APIOperation>.
| Category | Action format | Description | Example |
|---|---|---|---|
| Function Compute | FC:<APIOperation> | Invoke a Function Compute function synchronously or asynchronously | FC:InvokeFunction |
| Alibaba Cloud service API | <ServiceName>:<APIOperation> | Call any Alibaba Cloud OpenAPI operation | ECS:DescribeInstances |
| Third-party HTTP endpoint | HTTP:Request | Send an HTTP/HTTPS request to an external service | HTTP:Request |
Integration modes
The TaskMode field controls how CloudFlow interacts with the target service:
| Mode | Behavior | When to use |
|---|---|---|
RequestComplete | Wait for the service to return a response, then proceed to the next state. | Standard synchronous calls where the response is immediate. |
WaitForCustomCallback | Pause the workflow until an external system sends a callback with the task token. | Human approvals, long-running external processes, or any scenario where the workflow must wait for an external signal. |
WaitForSystemCallback | Pause the workflow until the integrated service sends an automatic callback upon completion. | Long-running Alibaba Cloud operations that support system-level completion notifications. |
For details, see Service integration modes.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| Name | string | Yes | The state name. |
| Type | string | Yes | The state type. Set to Task. |
| Action | string | Yes | The service and operation to call. Format: <ServiceName>:<APIOperation>. |
| TaskMode | enum | No | The integration mode: RequestComplete, WaitForCustomCallback, or WaitForSystemCallback. |
| Parameters | map[string]any | No | The input parameters for the API call. Values can be constants or JSONPath expressions. |
| InputConstructor | map[string]any | No | Constructs the task input from the state input. See Inputs and outputs. |
| OutputConstructor | map[string]any | No | Constructs the state output from the task result. See Inputs and outputs. |
| Timeout | string | No | The timeout period in seconds. Valid values: 0 to 604800. 0 means no timeout. You can set the timeout dynamically from the execution input with a JSONPath expression (see example below). |
| Retry | map[string]any | No | The retry policy for errors. See Error handling. |
| Catch | map[string]any | No | The error catch policy. See Error handling. |
| Description | string | No | A description of the state. |
| Next | string | No | The next state to run after this state completes. Leave blank if End is true. |
| End | bool | No | Whether this state is the terminal state of the current scope. |
Set the timeout dynamically from the execution input with a JSONPath expression:
Timeout.$: $Input.timeoutExamples
Invoke a Function Compute function
This example defines two Task states that invoke a Function Compute function -- one synchronously and one asynchronously. Specify the function and invocation type in the Parameters field. For parameter details, see Configure invocation parameters.
Functions can be invoked in optimized integration mode or through the Alibaba Cloud OpenAPI.
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: an example of synchronous function invocation
States:
- Name: an example of synchronous function invocation
Type: Task
TaskMode: RequestComplete
Action: FC:InvokeFunction
Parameters:
resourceArn: acs:fc:::functions/myFunction1/LATEST
invocationType: Sync
body:
key: name
Next: an example of asynchronous function invocation
- Type: Task
Name: an example of asynchronous function invocation
Action: FC:InvokeFunction
TaskMode: RequestComplete
Parameters:
invocationType: Async
resourceArn: acs:fc:{region}:{accountID}:functions/myFunction/LATEST
body:
key: name
Next: SucceededExit
- Type: Pass
Name: SucceededExit
End: trueCall an Alibaba Cloud service API
Call any Alibaba Cloud service API by setting the Action field to the service and operation name. The following example calls ECS:DescribeInstances to list ECS instances in a specific VPC:
Type: StateMachine
SpecVersion: v1
Name: MyWorkflow
StartAt: DescribeInstances
States:
- Type: Task
Name: DescribeInstances
Action: ECS:DescribeInstances
TaskMode: RequestComplete
Parameters:
RegionId: cn-hangzhou
VpcId: vpc-bp11y195luy47h8****
VSwitchId: vsw-bp1wb297ekw7xyh****
End: trueCall an HTTP endpoint with timeout and error handling
This example sends an HTTP POST request and sets a dynamic timeout from the execution input. If the task does not complete within the timeout period, CloudFlow raises a FnF.TaskTimeout error. The Catch rule captures this error and routes the workflow to a notification state.
Type: StateMachine
Name: MyWorkflow
SpecVersion: v1
StartAt: SubmitTask
States:
- Type: Task
Name: SubmitTask
Action: HTTP:Request
TaskMode: RequestComplete
Timeout.$: $Input.timeout
Parameters:
method: POST
url: https://*****
body:
taskName: fly
headers:
Content-Type: multipart/form-data
Catch:
- Errors:
- FnF.TaskTimeout
Description: 'Error capture rule #1'
Next: NotifyOnTaskTimeout
OutputConstructor:
ErrorCode: TaskTimeout
ErrorMessage: Task timed out.
End: true
- Type: Task
Name: NotifyOnTaskTimeout
Action: HTTP:Request
TaskMode: RequestComplete
Parameters:
method: POST
url: https://******
body:
taskName: fly
errorCode.$: $Input.ErrorCode
errorMessage.$: $Input.ErrorMessage
headers:
Content-Type: multipart/form-data
End: trueThe execution input supplies the timeout value:
{
"timeout": 10
}If the task does not complete within 10 seconds, the FnF.TaskTimeout error is caught, and the workflow transitions to the NotifyOnTaskTimeout state to send a timeout notification.
