Workflow design best practices

Follow best practices when creating serverless workflows, including maintaining unique workflow IDs to prevent duplicates.

Best practices when creating serverless workflows

Create effective serverless workflows using thoughtful approaches to design, handle data, and manage error by following these best practices based on the Serverless Workflow Domain Specific Language (DSL) principles. These principles help you to build robust workflows.

Workflow design principles

The Serverless Workflow DSL prioritizes clarity and ease of use when writing workflows.

Priority of constituencies

When developing workflows or APIs, ensure the needs of the author (workflow writer) come first. The constituencies are prioritized in the following order: Authors > Operators > Implementers > Specifications writers.

Linguistic fluency and clarity
  • Use imperative verbs such as Call, Emit, For, Fork, Raise, Run, Set, Switch, and Wait. These simple, universally understood terms make your workflow simple to read and understand.
Structure and extensibility
  • Use implicit default behaviors to reduce redundancy.
  • Declare components inline if they are not reusable to keep the definition self-contained.
  • Use external references to import and reuse shared components, which promotes a modular design.
  • Prioritize flexibility over strict enumerations to ensure extensibility and adaptability across different runtime environments.
Data flow and runtime management

Controlling data flow is critical for efficient workflows. Tasks are the fundamental computing units of a workflow. The Domain Specific Language (DSL) defines several default task types that runtimes must do. These include Do, Listen, Raise, Run, Try, and Wait.

Security and error handling
Secrets
Use Secrets with caution. Avoid passing them directly in call inputs as this might expose sensitive information.
Fault tolerance and error handling
Serverless Workflow is designed with resilience in mind to recover from failures.
Orchestrator UI integration best practices

For your workflow results to be effectively displayed in the Orchestrator UI and to facilitate chaining of workflows, you must structure the output data according to the WorkflowResult schema. Additionally, include any error information as part of the workflow output so the UI and subsequent workflows can handle them accordingly.

Workflow output schema
Results placement
The primary output intended for subsequent processing must be placed under the data.result property.
Schema reference
Your output schema file (schemas/workflow-output-schema.json) must reference the WorkflowResult schema.
Outputs definition

Include an outputs section in your workflow definition. This section contains human-readable key/value pairs that the UI will display.

Structure of workflow:

id: my-workflow
version: "0.8"
specVersion: "0.8"
name: My Workflow
start: ImmediatelyEnd
dataInputSchema: schemas/basic__main-schema.json
extensions:
  - extensionid: workflow-output-schema
    outputSchema: schemas/workflow-output-schema.json
functions:
  - name: print
    type: custom
    operation: sysout
  - name: successResult
    type: expression
    operation: '{
      "result": {
      "message": "Project " + .projectName + " active",
      "outputs":[]
      }
      }'
start: "successResult"
states:
  - name: successResult
    type: operation
    actions:
      - name: setOutput
        functionRef:
          refName: successResult
    end: true

Unique workflow ID requirements

Unique workflow IDs prevent duplicate entries in RHDH. You must use distinct IDs for each deployment to avoid tracking conflicts and maintain clear workflow visibility.

Understand how RHDH identifies workflows

RHDH identifies each workflow by using its unique ID. When you deploy or update workflows, the system uses this ID to track, display, and manage workflow instances. If multiple workflows share the same ID, RHDH cannot distinguish between them, resulting in unexpected behavior.

Follow workflow ID format requirements

Workflow identifiers must comply with RFC 1123 DNS label standards to function correctly across all deployment configurations. Your workflow IDs must meet these format requirements:

  • Contain only lowercase letters (a-z), digits (0-9), and hyphens (-)
  • Start and end with a lowercase letter or digit
  • Not contain underscores, uppercase letters, or leading or trailing hyphens

    Valid workflow ID examples:

  • order-processing
  • invoice123
  • customer-onboarding-flow
  • flow-01

    Invalid workflow ID examples:

  • OrderProcessing (contains uppercase letters)
  • order_processing (contains underscore)
  • -orderflow (starts with hyphen)
  • orderflow- (ends with hyphen)
Maintain workflow ID consistency across configurations

You must use the same workflow identifier consistently across all configurations when you build and deploy your workflow. This requirement proves essential for operator-driven deployments that use the gitops profile.

For gitops profile deployments, the Kubernetes resource name must match the workflow ID field in your workflow definition file (.sw.yaml or .sw.json). This consistency prevents deployment failures and maintains proper workflow tracking in RHDH.

Recognize version field limitations

Although the Serverless workflow specification allows you to define a workflow version attribute in your workflow definition, the current SonataFlow and RHDH ecosystem does not support multiple versions of a workflow that share the same ID.

Important

Deploying multiple workflows with the same ID and different versions is not supported and results in unexpected behavior. Each workflow ID must be unique across all deployments.

The version field serves as metadata and appears in the RHDH UI for informational purposes to help you identify workflow definitions. The backend retrieves version information from the Data Index GraphQL schema and displays it in both the workflow list view and on individual workflow details pages. If you do not specify a version in your workflow definition, the field appears empty in the UI.

The system does not use the version field to differentiate between workflows or manage workflow versions. All workflow operations, including execution, deletion, and API calls, rely solely on the workflow ID.

Avoid deploying workflows with duplicate IDs

Each workflow ID must be unique across all deployments, regardless of the configured version attribute. Deploying multiple workflows with the same ID and different versions is not supported and can result in the following issues:

  • Duplicate workflow entries appear in the RHDH Orchestrator UI.
  • Workflow deletion operations become unpredictable.
  • Historical workflow data becomes difficult to interpret.
  • Workflow instance tracking becomes unreliable.

    Duplicate entries can occur when you deploy workflows with the same ID to different runtime servers over time, or when you redeploy a workflow with a new version by using the same ID. Because the Data Index records all workflow executions regardless of which runtime server executed them, historical records from multiple deployments with the same ID appear as duplicate entries in the RHDH UI.

Apply workflow version management best practices

To maintain different versions of a workflow, assign a new workflow ID for each version. Incorporate the version identifier into the workflow ID itself using a consistent naming convention.

Recommended naming pattern: Use a naming convention that clearly links related versions of the same workflow:

  • workflow-name-v1 implements and deploys version 1
  • workflow-name-v2 implements and deploys version 2
  • workflow-name-v3 implements and deploys version 3

    Example workflow ID evolution:

    id: customer-onboarding-v1
    version: "1.0"
    name: Customer Onboarding Workflow

    When you need to deploy an updated version:

    id: customer-onboarding-v2
    version: "2.0"
    name: Customer Onboarding Workflow

    This approach provides clarity and prevents conflicts when you manage multiple iterations of a workflow.

Manage workflow transitions between versions

When you transition from one workflow version to another:

  • Deploy the new workflow version with a unique ID (for example, workflow-name-v2).
  • Verify the new workflow operates correctly.
  • Monitor running instances of the old workflow version.
  • After all instances of the old workflow complete, remove the old workflow deployment.

    This process helps you maintain workflow history and prevents disruption to running workflow instances.