Trigger a workflow using an API

Use any API client to trigger a CloudBees platform workflow run. Users with the appropriate permissions can start a workflow that contains a workflow_dispatch trigger. The following instructions describe how to invoke the API to trigger a workflow using a curl command.

To invoke a CloudBees platform API using any API client:

Acquire the following information.
- CloudBees platform personal access token. Refer to Generate a personal access token
- CloudBees platform workflow information.
  1. Access details for the component that contains the workflow to be triggered remotely.
    
    Use the to select an organization or sub-organization.
    
    Select Components from the left panel. The components in the selected organization display.
    
    Select the component name or COMPONENT DETAILS link. The details for the component display.
  2. Copy the identifier for the component located in the browser address bar after componentId=.
  3. Access the details for the workflow to trigger by selecting the workflow in the Name column of the Workflows tab.
  4. Copy the following workflow information.
    
    The workflow branch name.
    
    The workflow yaml file name.
    
    To be triggered using an API a workflow must contain a workflow_dispatch trigger. Refer to: Create a manual workflow trigger
    
    Applicable parameter names and values for the workflow_dispatch trigger.

Use the copied data and code below to form a curl command.

curl --location 'https://api.cloudbees.io/v2/components/<COMPONENT_ID>/trigger' \ (1)
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer <PERSONAL_ACCESS_TOKEN>' \ (2)
 --data '{
  "branchName": "<REPOSITORY_BRANCH>", (3)
  "workflowFileName": "<WORKFLOW_FILENAME.yaml>", (4)
\\ (5)
 "inputs": {
    "<str_param_name>": "<test string value>",
    "<num_param_name>": "<1>",
    "<bool_param>": "<true>",
    "<choice_param>": "<option_two>"
  }
}'▼

1	Replace `<COMPONENT_ID>` with the CloudBees platform component identifier to form the endpoint URL.
2	Replace `<PERSONAL_ACCESS_TOKEN>` with a generated personal access token.
3	Replace `<REPOSITORY_BRANCH>` with the repository branch name.
4	Replace `<WORKFLOW_FILENAME>` with the workflow yaml filename.
5	Add applicable parameter names and a valid values for the `workflow_dispatch` trigger in the `inputs`.

View workflow input and curl example:

Example block turns into collapsible summary / details.

workflow_dispatch inputs

on:
  workflow_dispatch:
    inputs:
      str_param:
        type: string
      num_param:
        type: number
      boolean_param:
        type: boolean
        default: false
      choice_param:
        type: choice
        options:
          - option_one
          - option_two
          - option_three▼

  "inputs": {
    "str_param": "test string",
    "num_param": "1.5",
    "bool_param": "true",
    "choice_param": "option_two"
  }▼

Trigger a run of the workflow by executing the curl command in an external tool.