Differences and compatibility between old and new CloudFlow versions-CloudFlow(CloudFlow)-阿里云帮助中心

CloudFlow is a fully managed service that coordinates distributed tasks. The new version provides more stable and reliable features, introducing state machine-based orchestration, an upgraded YAML syntax (Spec), Express mode for low-latency execution, and a visual Workflow Studio. All existing APIs and SDKs remain fully compatible.

What changed

Category	Change
Orchestration model	Follows state machine design specifications for general-purpose workflow logic.
Ecosystem integration	Orchestrates nearly all Alibaba Cloud products. Calls up to 10,000 Alibaba Cloud API operations directly, without additional packaging.
YAML syntax	Upgraded Spec syntax reduces learning cost. Aligns with industry-leading abstraction for orchestration, execution units, and data operators.
Developer experience	Workflow Studio with drag-and-drop editing, online debugging, and YAML preview.
Express mode	Lower end-to-end latency for high-traffic, high-concurrency workloads.

API and SDK compatibility

The new version of CloudFlow is fully compatible with the old version in terms of APIs and SDKs.

SDK version	Behavior
Latest	Supports all features of the new version, including Express mode.
Older versions	Cannot use new capabilities such as Express mode.

For the complete API reference, see OpenAPI Portal.

New features

Feature	Related API operations	Description
Express execution mode	CreateFlow, UpdateFlow, DescribeFlow, ListFlows	Low-latency mode optimized for API orchestration in online business scenarios.
StartSyncExecution	StartSyncExecution	Synchronously starts a workflow execution in Express mode.
Spec definition	CreateFlow, UpdateFlow, DescribeFlow, ListFlows	Creates and runs workflows using the new YAML syntax.
Input and output construction	-	InputConstructor, OutputConstructor, and built-in functions for flexible data construction. See Inputs and outputs, OutputConstructor, and Built-in functions.
Execution event types	GetExecutionHistory	New event types for detailed execution tracking. See Execution event types.
Workflow Studio	-	Visual workflow builder with drag-and-drop editing. See Interface overview.
Online debugging	-	Pre-debug workflows in the CloudFlow console. See Debug workflows.
Optimized service integrations	-	Improved integration with Object Storage Service, EventBridge, Short Message Service (SMS), High-speed Service Framework (HSF), and HTTP.
Alibaba Cloud service API integration	-	Calls up to 10,000 Alibaba Cloud service API operations without the need to package or optimize the API operations.
Built-in functions	-	The flow definition language (FDL) includes built-in functions for basic data processing. See Built-in functions.

Execution event types

The Type parameter in GetExecutionHistory supports these values:

Event type	Description
StateEntered	The input sent to the current step from the previous step.
StateStarted	The system is ready to run the step after processing inputs.
StateSucceeded	The step completed successfully. The output, processed by OutputConstructor, is passed to the next step.
StateFailed	The step failed.
StateTimedOut	The step failed due to a timeout.
StateAborted	The step failed due to cancellation.
TaskSucceeded	The integrated service call succeeded.
TaskFailed	The integrated service call failed.

Migrate from the old version

The primary difference between versions is the YAML syntax. You can migrate workflows by replacing old YAML files with new YAML files.

The migration workflow is:

Convert old YAML to the new format with the conversion tool.
Review and fix <TODO> labels in the output.
Validate the converted workflow in Workflow Studio.
Deploy to production.

YAML syntax changes

Concept	Old syntax	New syntax
Top-level type	`type: flow`	`Type: StateMachine`
Version field	`version` (values: `v1`, `v1beta1`)	`SpecVersion` (value: `v1`)
Custom version	Not available	`Version` (user-defined for workflow management)
Step container	`steps`	`States` with `StartAt`
Data mapping (input)	`inputMappings`	`InputConstructor`
Data mapping (output)	`outputMappings`	`OutputConstructor`
Navigation	`goto`	`Next`
Iteration	`foreach`	`Map`
Error state fields	`error` / `cause`	`Code` / `Detail`
Retry backoff	`multiplier`	`BackoffRate`

Note

The version field in old YAML maps to SpecVersion in the new format. The old field accepts v1 or v1beta1; the new SpecVersion only accepts v1. The Version field in the new format is a separate, user-defined value for workflow management.

Side-by-side example

Old version YAML

version: v1beta1
type: flow
steps:
  - type: task
    name: APIParseFace
    action: imageseg:ParseFace
    inputMappings:
      - target: image
        source: $input.faceURL
    outputMappings:
      - target: parseFace_OriginImageURL
        source: $local.Data.OriginImageURL
    serviceParams:
      ImageURL: $.image
    retry:
      - errors:
          - ErrorNeedsRetry
        intervalSeconds: 10
        maxAttempts: 3
        multiplier: 2
      - errors:
          - FC.ResourceThrottled
          - FC.ResourceExhausted
          - FC.InternalServerError
          - FnF.TaskTimeout
          - FC.Unknown
        intervalSeconds: 3
        maxAttempts: 10
        multiplier: 2
    catch:
      - errors:
          - ErrorNeedsRetry
        goto: final

  - type: choice
    name: mychoice0
    choices:
      - condition: $.status == "ready"
        steps:
          - type: pass
            name: pass11
      - condition: $.status == "failed"
        goto: final
    default:
      steps:
        - type: pass
          name: pass12
      goto: final
  - type: parallel
    name: myparallel
    branches:
      - steps:
          - type: pass
            name: pass21
            outputMappings:
              - target: result
                source: pass1
      - steps:
          - type: pass
            name: pass22
            outputMappings:
              - target: result
                source: pass21
    outputMappings:
      - target: result
        source: $local[*].result
  - type: foreach
    name: myforeach
    iterationMapping:
      collection: $.names
      item: name
    steps:
      - type: task
        name: toUpperCase11
        resourceArn: acs:fc:{region}:{account}:services/fnf_test/functions/toUpperCase
    outputMappings:
      - target: names
        source: $local[*].name
  - type: fail
    name: handle_failure
    error: StatusIsNotReady
    cause: status is not ready
  - type: pass
    name: final

New version YAML

Type: StateMachine
Version: v1beta1
SpecVersion: v1
StartAt: APIParseFace
States:
  - Type: Task
    Name: APIParseFace
    Action: <TODO> imageseg:ParseFace
    TaskMode: RequestComplete
    InputConstructor:
      image.$: <TODO> $Input.faceURL
    OutputConstructor:
      parseFace_OriginImageURL.$: <TODO> $Output.Data.OriginImageURL
    Parameters:
      resourceArn: ""
    Retry:
      - Errors:
          - ErrorNeedsRetry
        BackoffRate: 2
        IntervalSeconds: 10
        MaxAttempts: 3
      - Errors:
          - FC.ResourceThrottled
          - FC.ResourceExhausted
          - FC.InternalServerError
          - FnF.TaskTimeout
          - FC.Unknown
        BackoffRate: 2
        IntervalSeconds: 3
        MaxAttempts: 10
    Catch:
      - Errors:
          - ErrorNeedsRetry
        Next: final
    Next: mychoice0
  - Type: Choice
    Name: mychoice0
    Branches:
      - Condition: <TODO> $.status == "ready"
        Name: $.status == "ready"
        Next: pass11
      - Condition: <TODO> $.status == "failed"
        Name: $.status == "failed"
        Next: final
      Default: pass12
    Next: myparallel
  - Type: Parallel
    Name: myparallel
    Branches:
      - Type: ParallelBranch
        StartAt: pass21
        States:
          - Type: Pass
            Name: pass21
            End: true
            OutputConstructor:
              result: pass1
      - Type: ParallelBranch
        StartAt: pass22
        States:
          - Type: Pass
            Name: pass22
            End: true
            OutputConstructor:
              result: pass21
    OutputConstructor:
      result.$: <TODO> $Output[*].result
    Next: myforeach
  - Type: Map
    Name: myforeach
    ItemKey: name
    ItemsPath: <TODO> $Input.names
    OutputConstructor:
      names.$: <TODO> $Output[*].name
    Processor:
      Type: MapProcessor
      StartAt: toUpperCase11
      States:
        - Type: Task
          Name: toUpperCase11
          Action: FC:InvokeFunction
          Parameters:
            resourceArn: acs:fc:{region}:{account}:services/fnf_test/functions/toUpperCase
          TaskMode: RequestComplete
          End: true
    Next: handle_failure
  - Type: Fail
    Name: handle_failure
    Code: StatusIsNotReady
    Detail: status is not ready
  - Type: Pass
    Name: final
    End: true
  - Type: Pass
    Name: pass12
  - Type: Pass
    Name: pass11

Convert old YAML to the new format

Download the conversion tool:
- Linux: Convert-linux-amd64
- macOS: Convert-macos-aarch64

Run the converter: The converted YAML is printed to stdout.

   # macOS (Apple Silicon)
   ./Converter-macos-aarch64 --action=v2tov3 -f source.yaml

   # Linux (x86_64)
   ./converter-linux-amd64 --action=v2tov3 -f source.yaml

Review the output for <TODO> labels. These mark expressions that require manual adjustment. The following expression types typically need updates:

Expression type	What to adjust
`Action`	Map old service actions to the new Action format.
`InputConstructor` paths	Convert `$input.` references to `$Input.` syntax.
`OutputConstructor` paths	Convert `$local.` references to `$Output.` syntax.
`Condition` expressions	Update condition syntax to the new format.
`ItemsPath`	Update collection path references.

Validate the converted workflow in Workflow Studio. Use the YAML preview to check the workflow structure, then run online debugging to verify execution before deploying to production.

Migrate from AWS Step Functions

CloudFlow provides a conversion tool that transforms AWS Step Functions definitions (JSON) into the CloudFlow YAML format.

Syntax mapping

Step Functions (JSON)	CloudFlow (YAML)
`Resource`	`Action`
`InputPath` / `OutputPath`	`InputConstructor` / `OutputConstructor`
`Parameters`	`InputConstructor`
`ErrorEquals`	`Errors`
`Succeed` (state type)	`Succeed`

Side-by-side example

AWS Step Functions definition (JSON)

{
  "Comment": "A Hello World example",
  "StartAt": "Parallel",
  "States": {
    "Parallel": {
      "Type": "Parallel",
      "Branches": [
        {
          "StartAt": "Success",
          "States": {
            "Success": {
              "Type": "Succeed"
            }
          }
        },
        {
          "StartAt": "Lambda Invoke",
          "States": {
            "Lambda Invoke": {
              "Type": "Task",
              "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
              "OutputPath": "$.Payload",
              "Parameters": {
                "FunctionName.$": "$.a.b",
                "Payload": {
                  "sampleKey1": "sampleValue1",
                  "key2.$": "$.myStateInput.key",
                  "key3": 100
                }
              },
              "Retry": [
                {
                  "ErrorEquals": [
                    "Lambda.ServiceException",
                    "Lambda.TooManyRequestsException",
                    "States.ALL"
                  ],
                  "IntervalSeconds": 2,
                  "MaxAttempts": 6,
                  "BackoffRate": 2,
                  "Comment": "aaa"
                }
              ],
              "Next": "Pass (3)",
              "Catch": [
                {
                  "ErrorEquals": [
                    "States.ALL"
                  ],
                  "Comment": "bbb",
                  "Next": "Fail"
                }
              ],
              "InputPath": "$.a.b"
            },
            "Pass (3)": {
              "Type": "Pass",
              "End": true
            }
          }
        }
      ],
      "Next": "Pass (4)"
    },
    "Pass (4)": {
      "Type": "Pass",
      "End": true
    }
  }
}

CloudFlow definition (YAML)

Type: StateMachine
SpecVersion: v1
StartAt: Parallel
States:
  - Type: Parallel
    Name: Parallel
    Next: Pass (4)
    Branches:
      - Type: ParallelBranch
        StartAt: Success
        States:
          - Type: Succeed
            Name: Success
      - Type: ParallelBranch
        StartAt: Lambda Invoke
        States:
          - Type: Task
            Name: Lambda Invoke
            Action: <TODO> arn:aws:states:::lambda:invoke.waitForTaskToken
            InputConstructor:
              $: <TODO> $Input.a.b
              FunctionName.$: <TODO> $Input.a.b
            Payload:
              key2.$: $.myStateInput.key
              key3: 100
              sampleKey1: sampleValue1
            OutputConstructor:
              $: <TODO> $Input.Payload
            Retry:
              - Errors:
                  - Lambda.ServiceException
                  - Lambda.TooManyRequestsException
                  - States.ALL
                BackoffRate: 2
                IntervalSeconds: 2
                MaxAttempts: 6
            Catch:
              - Errors:
                  - States.ALL
                Next: Fail
            Next: Pass (3)
          - Type: Pass
            Name: Pass (3)
            End: true
  - Type: Pass
    Name: Pass (4)
    End: true

Convert a Step Functions definition

Download the conversion tool:
- Linux: Convert-linux-amd64
- macOS: Convert-macos-aarch64

Run the converter with the awstov3 action: The converted YAML is printed to stdout.

   # macOS (Apple Silicon)
   ./Converter-macos-aarch64 --action=awstov3 -f source.json

   # Linux (x86_64)
   ./Converter-linux-amd64 --action=awstov3 -f source.json

Review the output for <TODO> labels. The Action field and data path expressions (InputConstructor, OutputConstructor) typically require manual updates -- replace AWS resource ARNs with the corresponding Alibaba Cloud service actions.
Test the converted workflow in Workflow Studio using online debugging before deploying.