Basics and examples of FDL - CloudFlow - Alibaba Cloud Documentation Center

CloudFlow uses Flow Definition Language (FDL) to define workflows as state machines in YAML. Each flow is a set of states that run in sequence, in parallel, or conditionally, depending on how you connect them. During execution, the state relationships defined in the flow and the execution results of child flows drive state transitions.

A minimal flow with a single state:

Type: StateMachine
Name: hello-world
SpecVersion: v1
StartAt: Greet
States:
  - Type: Pass
    Name: Greet
    End: true

When CloudFlow runs this flow, it starts at the Greet state (specified by StartAt), runs the Pass state, and ends because End is set to true. If End were not set, CloudFlow would look for a Next field to determine which state to run next.

State types

A flow is built from eight state types, divided into two categories:

Atomic states handle single operations:

State	Purpose
Task	Call API operations of other integrated services to complete a job
Pass	Debug flows as blank nodes and data preprocessing nodes
Wait	Pause execution for a specified duration
Succeed	End a flow or child flow early based on a condition
Fail	Handle expected or unexpected errors that occur during flow execution

Control states manage branching and iteration:

State	Purpose
Choice	Route to different states based on conditions
Parallel	Run multiple branches at the same time. All branches share the same input
Map	Apply the same operation to each element in an array. This facilitates the processing of large amounts of data and management of flows

Combine and nest these states to build complex logic. For example, a branch inside a Parallel state can itself be a Choice state.

Data passing

States work like functions in a program. Each state receives Input, produces Output, and stores intermediate data in a Context variable. Data flows between states through Input and Output, similar to passing arguments between function calls.

Error handling

If a state fails, the OnError capability lets you retry it or redirect to a different state. For details, see Error handling.

Flow attributes

Every flow definition requires the following top-level attributes:

Attribute	Type	Required	Description	Example
Type	String	Yes	Flow definition type. Must be `StateMachine`.	`StateMachine`
SpecVersion	String	Yes	FDL version.	`v1`
Name	String	Yes	Unique name for the flow.	`my-wkfl`
StartAt	String	Yes	Name of the first state to run.	`my start task`
States	Array	Yes	Array of state definitions that make up the flow.	See example below
Description	String	No	Human-readable description.	`test workflow definition`
Timeout	Int	No	Maximum execution time in seconds.	`600`

Common state attributes

All states share these attributes:

Attribute	Type	Required	Description	Example
Name	String	Yes	Unique name for the state. Must be unique across the entire flow definition, including the flow name itself.	`my-state-name`
Type	String	Yes	State type: `Task`, `Pass`, `Wait`, `Choice`, `Parallel`, `Map`, `Succeed`, or `Fail`.	`Task`
Next	String	No	State to run after this one completes. Mutually exclusive with `End`.	`my-next-state`
End	Boolean	No	Set to `true` to mark this as the final state in its scope. Mutually exclusive with `Next`.	`true`
Description	String	No	Human-readable description.	`describe it here`

Important

The Name field must be unique across the entire flow definition. No two states -- and no state and the flow itself -- can share the same name.

Scopes and nesting

States nest in unlimited levels through scopes. If a state contains other states, the outer state is the scope of the inner states. States at the same level share the same scope.

When a state with End: true completes, its scope is marked as complete.

The following example shows three scope levels:

Type: StateMachine
Name: my-wkfl
SpecVersion: v1
StartAt: Parallel1
States:
  - Type: Parallel
    Name: Parallel1
    Next: Pass4
    Branches:
      - StartAt: Pass1
        States:
          - Type: Pass
            Name: Pass1
            Next: Pass2
            OutputConstructor:
              FieldA: 123
          - Type: Pass
            Name: Pass2
            End: true
      - StartAt: Pass3
        States:
          - Type: Pass
            InputConstructor:
              FieldA: 321
            Name: Pass3
            End: true
  - Type: Pass
    Name: Pass4
    End: true

This definition creates the following scopes:

Scope	States
`my-wkfl`	Parallel1, Pass4
Parallel branch 0	Pass1, Pass2
Parallel branch 1	Pass3

Completion order:

Pass2 finishes (End: true) -- branch 0 is complete.
Pass3 finishes (End: true) -- branch 1 is complete.
Both branches complete -- Parallel1 is complete. Execution moves to Pass4.
Pass4 finishes (End: true) -- the flow is complete.

Example: flow with parallel branches

This flow starts at Pass1, runs two parallel branches, and ends at Pass4:

Pass1 --> Parallel1 --> Pass4 --> End
            |
            +-- Branch 0: Pass2
            +-- Branch 1: Pass3

Type: StateMachine
Name: my-wkfl
SpecVersion: v1
StartAt: Pass1
States:
  - Type: Pass
    Name: Pass1
    Next: Parallel1
  - Type: Parallel
    Name: Parallel1
    Next: Pass4
    Branches:
      - StartAt: Pass2
        States:
          - Type: Pass
            Name: Pass2
            End: true
      - StartAt: Pass3
        States:
          - Type: Pass
            Name: Pass3
            End: true
  - Type: Pass
    Name: Pass4
    End: true

CloudFlow:Flow Definition Language (FDL)