Build Workflows

You can create workflows or edit existing workflows from the Workflows page in Datadog. The Workflows page lists existing workflows together with each workflow’s author and the dates that each workflow was last modified and executed.

• Hover over a workflow for the options to delete or clone the workflow.
• Toggle My workflows if you want to see only workflows that you created.

Build a workflow from a blueprint

1. Click the Blueprints tab.
2. If desired, use the search bar to narrow the list of blueprints by name, category, or integration.
3. Find the blueprint you would like to use, and click on it. The workflow canvas appears.
4. Click the pencil icon (Edit) to update the workflow name. If desired, type a new name in the text box and click Save.
5. Workflow steps that require updates are marked with exclamation mark icons.
6. Click on each workflow step you would like to modify and fill in any empty fields on the Configure tab.
7. When you are finished modifying the workflow, click Create From Blueprint. The workflow canvas updates to show your newly created workflow.

Create a custom workflow

To create a workflow:

1. Click New workflow.
2. Enter a name for the workflow, and click Create.
3. Click Add a step to get started to start adding steps to your workflow. Alternatively, click Edit JSON Spec if you want to build a workflow using the JSON editor.

Build a workflow with the workflow builder

1. Click Add a step to get started to add the first step to your workflow.
2. Search for an action using the search bar or browse through the integrations and their related actions to find the action you’re looking for. Click an action to add it as a step on your workflow canvas.

3. Click on the step in the workflow canvas to configure it or view its outputs or context variables. For more information on outputs and context variables, see Context variables.
4. After you’ve configured the step, click the plus (+) icon to add another step, or save the workflow if you’re done.

You can edit a step in the workflow at any time by clicking on it. Click and drag steps on your workflow to rearrange them.

Build a workflow with JSON

Build or edit a workflow in JSON by clicking Edit JSON Spec on your workflow page. The JSON editor also allows you to:

• Format JSON: Beautify your JSON.
• Export JSON: Download the workflow.

A typical workflow contains three top-level keys:

• "steps": An array of “step” objects. Each step defines a step in the workflow and includes a name, the action ID, and the step parameters. The steps object also includes a key for outbound connection data.
• "startStepName": The name of the first step in the workflow.
• "connectionEnvs": Connection data and environment variables.

An example of a workflow with a single step that sends a message to a Slack channel named #workflows-test:

{
    "steps": [
        {
            "outboundConnections": [],
            "name": "Send_message",
            "actionId": "com.datadoghq.slack.send_simple_message",
            "parameters": [
                {
                    "name": "teamId",
                    "value": "ABC1234"
                },
                {
                    "name": "channel",
                    "value": "#workflows-test"
                },
                {
                    "name": "mentionTargets",
                    "value": [
                        "@Bits"
                    ]
                },
                {
                    "name": "text",
                    "value": "Hello world!"
                }
            ]
        }
    ],
    "startStepName": "Send_message",
    "connectionEnvs": [
        {
            "env": "default",
            "connections": []
        }
    ]
}

Context variables

Creating useful workflows sometimes necessitates passing data from one step to another, or configuring steps that act on data from the workflow’s trigger source. You can perform this kind of data interpolation with context variables.

Context variables come in the following varieties:

• A small collection of standard workflow variables are present in all workflows.
• Some steps come with built-in step output variables that allow you to pass data from that step to a subsequent step in your workflow.
• Trigger variables are passed into the workflow by the triggering event.
• Source object variables are passed into the workflow by the triggering event.

The Context Variables tab for each step provides a map of all context variables available to that step.

Access a context variable in a step by enclosing it in double braces ({{). Context variables are available in fields marked with the {{ notation.

Workflow variables

All workflows have three standard variables:

• WorkflowName: The name of the workflow. Accessed with {{ WorkflowName }}.
• WorkflowId: The workflow ID. Accessed with {{ WorkflowId }}.
• InstanceId: Each workflow run receives a unique instance ID. Access the instance ID with {{ InstanceId }}.

Step output variables

Some steps create outputs that are available to subsequent steps in a workflow. Access a step variable with the syntax: Steps.<step_name>.<variable>. For example, to retrieve the pull request status variable (state) from the GitHub pull request status step (Get_pull_request_status), you’d use the following context variable:

{{ Steps.Get_pull_request_status.state }}

If you’re not sure what variable you’re looking for, Datadog suggests existing steps as you type. Alternatively, you can consult the Context Variables tab for a list of available variables.

Trigger variables

You can pass trigger variables into a workflow as inputs. Workflows accept a JSON object of comma-separated key-value pairs. Access a trigger variable in workflow steps using the syntax {{ Trigger.key }}. For example, to access the trigger variable { "user": "Bits" }, use {{ Trigger.user }} in the step.

• If you add a trigger variable that doesn’t exist, the variable is automatically added as a workflow input.
• If you’re not sure what variable you’re looking for, Datadog suggests existing steps as you type. Alternatively, you can consult the Context Variables tab for a list of available variables.

For more information on triggering workflows, see Trigger a workflow.

Source object variables

Source object variables are properties of the triggering event that are resolved at execution. The variables available in the workflow depend on the type of trigger that initiated the workflow instance. For example, if the workflow instance is triggered by a monitor, the monitor ID variable is available using {{Source.monitor.id}}. If the workflow is triggered by a security signal detection or notification rule, the signal ID is available using {{Source.securitySignal.id}}.

All the variables of the Source object are visible in the Context Variables tab.

Error handling and fallbacks

In the event that a step fails, you can specify the number of times you want your workflow to retry the step and at what interval, before moving on to an optional fallback step. If no fallback step is provided, the workflow terminates after all retries have been exhausted.

To configure error handling for a step:

1. Click on the step in the workflow canvas.
2. Click the + icon next to the Error Handling & Retries section.
3. Adjust the Interval and Max retries values.
4. Optionally, add a fallback step.
5. Save your workflow to apply the changes.

Add a fallback

To handle a step failure, you can add a downstream workflow step as a fallback by selecting it from the Fallback dropdown menu.

Alternatively, you can create a fallback step that branches from the main workflow tree:

1. From the Fallback dropdown menu, select Add a new fallback. The workflow canvas is replaced with a fallback tree.
2. Click the + icon on the fallback tree to add a step.
3. Add steps using the workflow builder. You can add as many steps as needed to the fallback tree.
4. When you’re done configuring your fallback steps, click Save to apply your changes.

To get back to the main workflow canvas, click Main above the fallback tree. From the workflow canvas, a fallback icon appears next to steps with a fallback. Click the icon and select the fallback step to open the fallback tree. Alternatively, you can access the fallback tree by clicking Edit Fallback Tree in the Error Handling & Retries section of a step. The Edit Fallback Tree button only appears if the fallback step is not an existing downstream step in the main workflow.

Remove a fallback

1. From the main workflow canvas, click on the step with the fallback you wish to remove.
2. In the Error Handling & Retries section, click Clear.

Further reading

Additional helpful documentation, links, and articles:

Browse the available actions in the Actions CatalogDOCUMENTATION