The three types of service integration modes - CloudFlow

CloudFlow uses Task states to invoke Alibaba Cloud services and external resources within a workflow. The integration mode controls how a Task state handles the service response -- whether it waits synchronously, waits for an asynchronous job to finish, or pauses until an external system sends a callback.

Three integration modes are available:

RequestComplete -- Send a request and wait for the response (default).
WaitForSystemCallback -- Send an asynchronous request and wait for the system to report completion.
WaitForCustomCallback -- Send a request with a task token and pause until an external system calls back with the result.

Choose an integration mode

Use the following table to determine which mode fits your use case.

Criteria	RequestComplete	WaitForSystemCallback	WaitForCustomCallback
When to use	The target service returns a synchronous response	The target service runs an asynchronous job and reports completion on its own	An external system or human action must complete before the workflow continues
How the state advances	After the response arrives	After the job completes	After `ReportTaskSucceeded` or `ReportTaskFailed` is called
Typical scenario	Invoke a Function Compute function synchronously	Submit a long-running batch job	Wait for human approval or an external microservice
`invocationType` value	`Sync`	`Async`	`Sync` or `Async`

Not all services support all three modes. For a per-service compatibility list, see Integration modes.

RequestComplete

RequestComplete is the default integration mode. The Task state sends a request to the target service and waits for the response before advancing to the next state. Because the call is synchronous, the workflow receives the result as soon as the invocation completes.

Set TaskMode to RequestComplete (or omit it, since this is the default):

Type: StateMachine
Name: myWorkFlow
SpecVersion: v1
StartAt: InvokeFunction
States:
  - Type: Task
    Name: an example of function invocation.
    Action: FC:InvokeFunction
    TaskMode: RequestComplete
    Parameters:
      resourceArn: acs:fc:{regionId}:{accountId}:functions/dataji/LATEST
      invocationType: Sync
      body: xxxx
    End: true

WaitForSystemCallback

Use WaitForSystemCallback for asynchronous invocations where the target service reports completion on its own. The Task state submits the request and then waits -- the workflow does not advance until the job finishes.

Set TaskMode to WaitForSystemCallback and invocationType to Async:

Type: StateMachine
Name: myWorkFlow
SpecVersion: v1
StartAt: InvokeFunction
States:
  - Type: Task
    Name: an example of function invocation.
    Action: FC:InvokeFunction
    TaskMode: WaitForSystemCallback
    Parameters:
      resourceArn: acs:fc:{regionId}:{accountId}:functions/dataji/LATEST
      invocationType: Async
      body: xxxx
    End: true

For a list of services that support this mode, see Alibaba Cloud services that support normal integration.

Task cancellation behavior

If a WaitForSystemCallback task is terminated, CloudFlow may not be able to cancel the underlying job. Uncanceled jobs continue to run and may incur charges. To avoid unexpected costs, cancel the integration task manually.

When CloudFlow attempts automatic cancellation

CloudFlow makes a best-effort cancellation attempt in these scenarios:

The workflow execution is stopped.
Another branch in a Parallel state fails with a caught error.
An iteration of a Map state fails with an uncaught error.

For example, if the workflow contains asynchronous tasks with child flows or Function Compute functions, call the StopExecution API operation to stop the workflow. CloudFlow stops the child flows first and then the asynchronous task-related functions in the workflow.

Why cancellation may fail

The execution role lacks the permissions required to call the corresponding API operation.
The target service is temporarily unavailable.

WaitForCustomCallback

WaitForCustomCallback pauses the workflow and waits for an external system to report the result. When the Task state runs, it generates a task token that you pass to the external system. After the external system finishes processing, it calls the ReportTaskSucceeded or ReportTaskFailed API operation with the token and the result. The workflow then advances to the next state.

Compared with polling, callbacks reduce latency and eliminate unnecessary load on the server. Combined with message queues, callbacks extend the orchestration scope of CloudFlow to all types of computing resources -- not just Function Compute.

Set TaskMode to WaitForCustomCallback:

Type: StateMachine
Name: myWorkFlow
SpecVersion: v1
StartAt: InvokeFunction
States:
  - Type: Task
    Name: an example of function invocation.
    Action: FC:InvokeFunction
    TaskMode: WaitForCustomCallback
    Parameters:
      resourceArn: acs:fc:{regionId}:{accountId}:functions/dataji/LATEST
      invocationType: Sync
      body: xxxx
    End: true

Access the task token

Inside the Parameters field, use the expression $Context.Current.TaskToken to access the task token for the current task. The $Context prefix points to the runtime context object.

Parameters:
  resourceArn: acs:fc:{regionId}:{accountId}:functions/dataji/LATEST
  invocationType: Async
  body:
    payload.$: $Input
    taskToken.$: $Context.Current.TaskToken

Example: credit check with an external microservice

This example demonstrates how CloudFlow integrates with an external microservice to perform a credit check. The workflow:

Invokes a Function Compute function using WaitForCustomCallback. The function sends a message -- including the task token -- to Simple Message Queue (formerly MNS).
The external microservice pulls the message from the queue and runs the credit check.
The microservice calls ReportTaskSucceeded or ReportTaskFailed with the token and the credit check result.
CloudFlow resumes the workflow and advances to the next state.

Type: StateMachine
Name: myWorkFlow
SpecVersion: v1
StartAt: InvokeFunction
States:
  - Type: Task
    Name: an example of function invocation.
    Action: FC:InvokeFunction
    TaskMode: WaitForCustomCallback
    Parameters:
      resourceArn: acs:fc:{regionId}:{accountId}:functions/dataji/LATEST
      invocationType: Async
      body:
        payload.$: $Input
        taskToken.$: $Context.Current.TaskToken
    End: true

Example: integrate with a self-managed service

Use Simple Message Queue (formerly MNS) and API callbacks to integrate CloudFlow with a self-managed service. In this pattern, Simple Message Queue acts as the intermediary between CloudFlow and the external service. The external service polls the queue for tasks, processes them, and calls back CloudFlow with the result.

This pattern is not limited to Simple Message Queue -- any intermediate messaging or storage service works as the communication channel.

What's next

Integration modes -- Per-service compatibility list for each integration mode.
Alibaba Cloud services that support normal integration -- Services that support WaitForSystemCallback.
ReportTaskSucceeded API -- Report a successful callback result.
ReportTaskFailed API -- Report a failed callback result.
StopExecution API -- Stop a running workflow execution.