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 Copy linkLink copied!
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, andWait. These simple, universally understood terms make your workflow simple to read and understand.
- Use imperative verbs such as
- 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, andWait. - 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
WorkflowResultschema. 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.resultproperty. - Schema reference
- Your output schema file (
schemas/workflow-output-schema.json) must reference theWorkflowResultschema. - Outputs definition
-
Include an
outputssection 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 Copy linkLink copied!
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-01Invalid 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.yamlor.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-v1implements and deploys version 1workflow-name-v2implements and deploys version 2workflow-name-v3implements and deploys version 3Example workflow ID evolution:
id: customer-onboarding-v1 version: "1.0" name: Customer Onboarding WorkflowWhen you need to deploy an updated version:
id: customer-onboarding-v2 version: "2.0" name: Customer Onboarding WorkflowThis 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.
- Deploy the new workflow version with a unique ID (for example,