CloudBees action: Dispatch multiple workflows

Use this action to dispatch multiple workflows in the CloudBees platform.

All CloudBees action repositories are listed at CloudBees, Inc. on GitHub.

Prerequisites

You must generate a personal access token in the CloudBees platform before invoking this action.
All workflows to be dispatched must be manually triggered workflows.

Inputs

YAML file specifications

The following inputs are for the YAML file:

Table 1. YAML file specifications
Input name	Data type	Required	Description
`workflows-dispatch-file`	String	Yes	Path to the JSON file containing workflow dispatch requests.
`token`	String	Yes	Authorization token to authenticate workflow dispatch requests. CloudBees recommends that you pass the token as a secret reference to ensure security.
`execution-mode`	String	No	Whether to dispatch all the workflows in parallel or sequentially. Supported values: 'parallel' (default) or 'serial'.
`wait-for-completion`	Boolean	No	Whether to wait for workflow executions to complete. Defaults to false when `execution-mode: parallel` is set. When `execution-mode: serial` is set, is only considered to be true.

JSON file specifications

The following inputs are for the JSON file:

Table 2. JSON file specifications
Field	Data type	Required	Description
`component_id`	String	Yes	The ID of the component containing the manually triggered workflow.
`branch_name`	String	Yes	The branch name containing the workflow to dispatch.
`workflow_file_name`	String	Yes	The name of the workflow file to dispatch.
`inputs`	Object	No	Input parameters to be passed to dispatch the workflow. Represented as key-value pairs, where keys and values are both strings.
`ignore_failures`	Boolean	No	Whether to ignore workflow trigger or execution failures. Default is false. When both `execution-mode: parallel` and `wait-for-completion: false` are set, is only considered to be true.

Locate the component ID in your browser address bar, displayed as <COMPONENT_ID> in the example below:

https://cloudbees.io/orgs/<YOUR_ORGANIZATION>/components/runs?componentId=<COMPONENT_ID>&organizationId=<ORGANIZATION_ID>▼

Usage examples

The following summarizes the expected results of using different YAML and JSON specifications in this action.

Table 3. Input examples and results in response to workflow executions.
When the following inputs are specified:		The following results are observed:
`execution-mode:`	`wait-for-completion:`
`parallel`	`false`	The action triggers all workflows in parallel. Once triggered, the action step passes regardless of any failures. The `ignore-failures` parameter is always considered false for this scenario.
`parallel`	`true`	The action triggers all workflows in parallel, and waits for all triggered runs to complete. If all runs are successful, the action step passes. If a dispatched workflow fails in being triggered or executed and has: `ignore-failures: true` specified, it does not affect the action step result. `ignore-failures: false` specified, the action step fails.
`serial`	`true` ^[1]	The action triggers each workflow sequentially, so as soon as a workflow run is complete, the next workflow is triggered to execute. If all runs are successful, the action step passes. If a dispatched workflow fails in being triggered or executed and has: `ignore-failures: true` specified, the action step result is not affected by this run, and the action continues on to trigger the next workflow in the series. `ignore-failures: false` specified, the action step fails on first failure and subsequent workflows are not triggered.

^[1] The wait-for-completion parameter is always considered true when execution-mode: serial is set.

Usage example: Default settings

The following example uses the default settings (execution mode: parallel, wait-for-completion: false).

    - name: Dispatch workflows
      uses: https://github.com/cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"▼

The dispatch_requests.json file for the YAML file above:

[
  {
    "component_id": "12345678-9abc-defg-h123-456789abcdef",
    "branch_name": "branch-1",
    "workflow_file_name": "workflow-1.yaml"
  },
  {
    "component_id": "abcdefgh-1234-5678-9abc-defgh1234567",
    "branch_name": "branch-2",
    "workflow_file_name": "workflow-2.yaml"
  }
]▼

Usage example: Await completion of workflow execution

The following action example executes workflows in parallel and waits for completion of all:

    - name: Dispatch workflows and wait for completion
      uses: https://github.com/cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"
        execution-mode: "parallel"
        wait-for-completion: true▼

The dispatch_requests.json file for the example above:

[
  {
    "component_id": "12345678-9abc-defg-h123-456789abcdef",
    "branch_name": "branch-1",
    "workflow_file_name": "workflow-1.yaml",
    "inputs": {
      "testkey1": "value",
      "testkey2": "50"
    }
  },
  {
    "component_id": "abcdefgh-1234-5678-9abc-defgh1234567",
    "branch_name": "branch-2",
    "workflow_file_name": "workflow-2.yaml"
  }
]▼

Usage example: Ignore workflow execution failures

The following action example executes workflows sequentially and ignores failures for one but not the other workflow:

    - name: Dispatch workflows sequentially and ignore failures
      uses: https://github.com/cloudbees-io/workflows-dispatch@v1
      with:
        workflows-dispatch-file: dispatch_requests.json
        token: "${{ secrets.TOKEN }}"
        execution-mode: "serial"▼

The dispatch_requests.json file for the action example above:

[
  {
    "component_id": "12345678-9abc-defg-h123-456789abcdef",
    "branch_name": "branch-1",
    "workflow_file_name": "workflow-1.yaml",
    "inputs": {
      "testkey1": "value",
      "testkey2": "50"
    },
    "ignore_failures": true
  },
  {
    "component_id": "abcdefgh-1234-5678-9abc-defgh1234567",
    "branch_name": "branch-2",
    "workflow_file_name": "workflow-2.yaml",
    "ignore_failures": false
  }
]▼

In the example above, workflow-2 is executed regardless if workflow-1 execution has failed, and if workflow-2 is completed successfully, the action step is passed. If workflow-2 fails, the action step is failed.