Skip to main content

Workflow YAML

Workflows are a set of activities that are executed in a specific order. Workflows can be triggered by events or manually. Workflows can be used to automate business processes and integrate with external systems

YAML Manifest:​

workflow:
  workflowId: "00000000-0000-0000-0000-000000000000" # required
  name: "Send Order Confirmation Email" # required
  isActive: true # optional, default is true
  description: "Send Order Confirmation Email to the customer" # optional
  version: "1.0" # version of the workflow definition file (not the workflow)
  executionMode: "Async" # or 'Sync' (optional, default is Async)
  priority: 50 # optional, default is 50, higher number means higher priority
  logLevel: "Debug" # optional, default is Info. Logs will be returned to the client if the log level is set to Debug.
  enableTransaction: true # optional, default is true. If false, the workflow will not be executed in a transaction.
  enableAudit: true # optional, default is false
  runAs: "userName" # optional, default is current user
  tags:
    - "order"
    - "email"
  concurrency:
    group: "email-service" # optional, default is workflow.id
    waitTime: 30 # wait time to acquire a lock on the workflow in seconds. Break the workflow if the lock is not acquired.

  additionalProperties: # optional
    silent:
      expression: inputs.divisionId == 1 # UI Evaluation

variables:
  - name: "API_ENDPOINT" # Name of the variable
    value: "https://api.example.com/" # Value of the variable (String, Number, Boolean, Array, Object)
  - name: "DATABASE_PASSWORD" # Name of the variable
    fromConfig:
      configName: "db.config"
      key: "DB_PASS_KEY" # Name of the configuration key to get the value of the variable from. (optional)

triggers:
  - type: "Entity" # Entity, Schedule
    entityName: "Order" # Entity Name
    eventType: "Added" # Added, Modified, Deleted
    position: "After" # Before, After
    displayName: "Order Created"

schedules:
  - cron: "0 0 * * 1" # every Monday at midnight
    displayName: "Every Monday" # optional

activities:
  - name: "EmailActivity" # name of the activity
    conditions: # optional
      - expression: "[Order.Status] = 'Pick Up'"
    description: "Send Email to the customer"
    steps: # actions to execute. execution order is the same as the order of the steps
      - task: "Query/GraphQL" # task type
        name: "queryOrder" # name of the step
        runAs: "userName" # optional, default is current user
        inputs:
          query: "query { order(id: {{orderId}}) { orderId, customer { email } } }" # query to execute
          variables:
            orderId: "{{orderId}}" # variables to pass to the query
        outputs:
          - name: "order" # name of the output
            mapping: "order" # mapping of the output
      - task: "sendEmail"
        conditions: "[Order.Status] = 'Picked Up'"
        inputs:
          $order: "{{EmailActivity.queryOrder.order}}"
          to:
            - "{{$order.Customer.Email}}"
          template: "OrderTracking"
          templateVariables:
            orderId: "{{$order.orderId}}"
    events:
      - type: "onActivityCompleted"
        steps:
          - task: "ActivityEvent/Create"
            inputs:
              name: "EmailActivity"
              eventData:
                workflowName: "{{workflow.name}}"
                workflowId: "{{workflow.workflowId}}"
                orderId: "{{orderId}}"
                status: "Success"
      - type: "onActivityFailed"
        steps:
          - task: "ActivityEvent/Create"
            inputs:
              name: "EmailActivity"
              eventData:
                workflowName: "{{ workflow.name }}"
                workflowId: "{{ workflow.workflowId }}"
                orderId: "{{orderId}}"
                error: "{{ exception?.message }}"
                status: "Failed"
events:
  - type: "onWorkflowStarted"
    steps:
      - task: "ActivityEvent/Create"
        inputs:
          name: "Workflow"
          eventData:
            workflowName: "{{workflow.name}}"
            workflowId: "{{workflow.workflowId}}"
            orderId: "{{orderId}}"
            status: "Started"

Structure​

The manifest file is a YAML file. The manifest file is a collection of YAML documents. Each YAML document is a collection of YAML objects. The YAML objects are defined using key-value pairs. The key is a string and the value can be a string, number, boolean, array or another YAML object.

Sections​

The manifest file is divided into sections. Each section is a YAML object. The sections are: Workflow, Activities, Triggers

workflow: # required
inputs: # optional
outputs: # optional
activities: # required
triggers: # optional
schedules: # optional
events: # optional

Workflow​

The Workflow section is used to define the workflow. The workflow is a collection of activities. The workflow is triggered by a trigger. The workflow is executed when the trigger is fired. The workflow is executed in the order of the activities defined in the workflow.

  • name: This is a compulsory field. It's a string that defines the name of the workflow.
  • description: This is an optional field. It's a string that describes the purpose or functionality of the workflow.
  • version: This is an optional field. It's a string that indicates the version of the workflow definition file (not the workflow itself).
  • executionMode: This is an optional field. It's a string that specifies whether the workflow should be executed synchronously ('Sync') or asynchronously ('Async'). The default value is 'Async'. If workflow is triggered by a schedule then the execution mode is always 'Async'.
  • priority: This is an optional field. It's a number that specifies the priority of the workflow. The higher the number, the higher the priority. The default value is 50. Synchronous workflows are executed before asynchronous workflows. Priority is used to determine the order of execution when there are multiple workflows to execute.
  • logLevel: This is an optional field. It's a string that specifies the log level for the workflow. The possible values are 'Debug', 'Info', 'Warn', 'Error', 'Fatal'. The default value is 'Info'. Logs will be returned to the client if the log level is set to Debug.
  • enableTransaction: This is an optional field. It's a boolean that specifies whether the workflow should be executed in a transaction. The default value is true. If false, the workflow will not be executed in a transaction.
  • enableAudit: This is an optional field. It's a boolean that specifies whether the workflow should be audited. The default value is false.
  • runAs: This is an optional field. It's a string that specifies the user name under which the workflow should be executed. The default value is the current user.
  • tags: This is an optional field. It's an array of strings that specifies the tags of the workflow. Tags are used to categorize workflows.
  • concurrency: This is an optional field. It's an object that specifies the concurrency settings for the workflow.
    • group: This is an optional field. It's a string that specifies the group of the workflow. The default value is the workflow id.
    • waitTime: This is an optional field. It's a number that specifies the wait time to acquire a lock on the workflow in seconds. The default value is 15 seconds. Break the workflow if the lock is not acquired.

Example workflow:​

workflow:
  name: "Send Order Confirmation Email"
  description: "Send Order Confirmation Email to the customer"
  version: "1.0"
  executionMode: "Async"
  tags:
    - "order"
    - "email"
  concurrency:
    group: "email-service"
    waitTime: 0 # 0 means no waiting

Remember, the order of keys in each section doesn't affect the execution. However, it's good practice to follow the same order for readability and consistency.

Variables​

The Variables section is used to define the variables of the workflow. The variables are used to store data. The variables can be used in the workflow.

variables:
  - name: "API_ENDPOINT" # Name of the variable
    value: "https://api.example.com/" # Value of the variable (String, Number, Boolean, Array, Object)
  - name: "DATABASE_PASSWORD" # Name of the variable
    fromConfig:
      configName: "db.config"
      key: "DB_PASS_KEY" # Name of the configuration key to get the value of the variable from. (optional)

Variables structure​

The Variables section is a YAML object. The Variables section has the following keys:

  • name (required) - The Name key is a string. The Name key is used to define the name of the variable.
  • value (optional) - The Value key is a string. The Value key is used to define the value of the variable. The Value key can have the following values: String, Number, Boolean, Array, Object.
  • fromConfig (optional) - The FromConfig key is a string. The FromConfig key is used to define the name of the configuration key to get the value of the variable from.

Inputs​

Workflow Inputs are used to pass data to the workflow from UI. Inputs are defined in the Inputs section of the manifest file. Inputs are defined using the Inputs key.

Example:

inputs: # workflow inputs
  - name: "emailAddress"
    type: "text"
    props:
      multiple: true # optional, default is false
      displayName: "Email Address" # optional (used in the UI)
      description: "Email address to send the email to"
      required: true # optional, default is false
  - name: "orderId"
    type: "Order" # type of the input
    props:
      multiple: false # optional, default is false
      description: "Order to process"
      required: true # optional, default is false
      visible: true # optional, default is true
      mapping: "order.orderId" # optional, default is the name of the input

Inputs Props​

  • defaultValue (optional): Specifies the default value of the input. If not present, the input will not have a default value.
  • multiple (optional): Specifies whether the input should be an array of values. If not present, the input will not be an array of values.
  • visible (optional): Specifies whether the input should be visible in the UI. If not present, the input will be visible in the UI.
  • mapping (optional): Specifies the mapping of the input from UI props.
  • displayName (optional): Specifies the display name of the input in the UI. If not present, the name of the input will be used as the display name.
  • description (optional): Specifies the description of the input in the UI. If not present, the input will not have a description.
  • required (optional): Specifies whether the input is required. If not present, the input will not be required.
  • options (optional): Specifies the options of the input. If not present, the input will not have options.

Inputs Types​

Inputs can be of the following types:

  • text - Text input
  • number - Number input
  • options - Dropdown list of options (options are defined in the options key)
  • boolean - Checkbox
  • date - Date input
  • datetime - Date and time input
  • object - Object input
  • object[] - Entity input

Options Input Type​

Options output type is used to define a dropdown list of options. Options input type is defined using the Options key.

Example:

inputs:
  - name: "status"
    type: "options"
    props:
      control: "select" # optional, default is select
      options:
        - name: "Pending"
          value: 1
        - name: "Approved"
          value: 2
        - name: "Rejected"
          value: 3

Outputs​

Workflow Outputs are used to pass data from the workflow to consumer. Outputs are defined in the Outputs section of the manifest file. Outputs are defined using the Outputs key.

Variable map should have full path of the variable. [[Activity]].[[StepName]].[[VariableName]] for example: emailActivity.sendEmail.response

outputs:
  - name: "response"
    mapping: "activity.sendEmail.response"
    additionalProperties: # optional. additional properties for the output (used in the UI)
      displayName: "Response" # optional, default is the name of the output
      description: "Response from the API" # optional
      visible: true # optional, default is true
      type: "json" # optional, default is text
      multiple: false # optional, default is false. If true, the output will be an array of values.

  - name: "statusCode"
    mapping: "activity.sendEmail.statusCode"
  - name: "message"
    mapping: "{{sendEmail.message}} {{sendEmail.error}}"

Activities​

Activities define the actions that should be taken when certain conditions are met within a workflow. They are executed in the order they are defined.

Activity structure​

  • name (required): The name of the activity.
  • description (optional): Provides a human-readable explanation of the activity.
  • conditions (optional): Specifies when the activity should be executed. If not present, the activity will always be executed.
  • steps (required): Lists the actions that should be taken during this activity. Must have at least one action.
  • continueOnError (optional): Specifies whether the workflow should continue if an error occurs during mapping. If not present, the workflow will stop if an error occurs during mapping.
  • events (optional): Specifies the events that should trigger this activity. If not present, the activity will be triggered by all events. Supported events are: onActivityStarted, onActivityCompleted, onActivityFailed
name: "Send Email to the customer" # required
conditions: # optional
  - expression: "[Order.Status] = 'Pick Up'"
description: "Send Email to the customer"
steps: # actions to execute. execution order is the same as the order of the steps
continueOnError: true # optional, default is false
events: # handling of activity events (optional)

Example of an Activity section in YAML:

activities:
  - name: "Send Email to the customer"
    conditions: #
      - expression: "[Order.Status] = 'Pick Up'"
    description: "Send Email to the customer"
    steps:
      - task: "Utility/SendEmail"
        inputs:
          to: "{{Order.Customer.Email}}"
          templateName: "OrderConfirmation"
          data: '{"order": "{{Order}}"}'

Conditions​

Conditions are used to specify when an activity should be executed. Conditions are defined using the Conditions key. It's an array of conditions. Each condition is defined using the Expression key and uses the NCalc Expression Language.

Example:

activities:
 name: "Send Email to the customer"
  conditions:
    - expression: "[Order.Status] = 'Pick Up'"
    - expression: "[Order.OrderType] = 'Delivery'"

Events​

  • onWorkflowStarted (optional): Specifies the actions to take when the workflow is started.
  • onWorkflowExecuted (optional): Specifies the actions to take after the workflow is executed. Exception will be available in the exception variable if an error occurs during execution of the workflow.
  • onWorkflowFailed (optional): Specifies the actions to take if an error occurs during execution of the workflow. Exception will be available in the exception variable.

Activity Error Handling​

Activity error handling is used to define what should happen when an activity fails. Activity error handling is defined using the OnActivityFailed key.

Example:

Create an Action Event when an activity fails:

events:
  - type: "onWorkflowFailed"
    steps:
      - task: "ActionEvent/Create"
        inputs:
          name: "workflow.createOceanShipment"
          eventData:
            workflowName: "{{ workflow.name }}"
            workflowId: "{{ workflow.workflowId }}"
            orderId: "{{ orderId }}"
            error: "{{ exception?.message }}"
            status: "Failed"