Workflows

Overview

The Workflows tool in Cortex allow you to automate running sequential actions and development workflows based on contextual data that exist inside your workspace. This tool supports both simple workflows, like granting permissions to a database, and sophisticated ones, like creating a Jira ticket for an incident detected in Cortex.

Workflow RBAC

It is possible to configure specific users, teams, or roles who are allowed to run a Workflow, or you can require the user to be an Owner or Editor of an entity in order to run the workflow. This is described in more detail under Step 2: Configure your workflow settings.

It is also possible to create a "Manual approval" action that requires approval from specific team members. Read more about configuring this under Add actions to your workflow.

View Workflows and run history

To see your workflows, click Workflows in the lefthand navigation menu. To view existing workflows, you must have the View Workflows permission.

For auditing and debugging purposes, Cortex stores run history, which includes the initiator, run context, and the inputs/outputs of each action, for 30 days. To view previous Workflow runs, you must have the View Workflow runs permission.

• In the Workflows tab, view all existing workflows, including each workflow's name, description, and last update. If a workflow is in draft mode, you'll also see a Draft tag next to its name. From this page, you can edit, run, delete, or create a workflow.
• In the Runs tab, view historic runs for each Workflow, as well as each run's status: In Progress, Paused, Successful, Canceled, or Error. Click any of the individual actions to view the action's inputs, outputs, and run context in the side panel.

Creating a workflow

note

You must have the Edit Workflows permission in order to complete these steps.

You can choose to create a workflow from a template or you can choose to create one from scratch.

There are templates available for the following common workflows:

• Create AWS S3 bucket
• Create AWS EC2 instance
• Create ServiceNow incident
• Create Azure function
• Create Jira issue

Step 1: Choose a template or a blank workflow

1. In the lefthand navigation menu of Cortex, click Workflows.
2. On the right side of the search bar, click Create workflow.
3. Choose whether to start with a template or start from scratch.
   • Workflow Template: Click the tile for the template you wish to use, then click Continue at the bottom of the page.
     • Note: Each tile displays the requirements for secrets you must define before using the template; make sure to follow the template's requirements before you proceed.
   • Start from Scratch: Click Start from Scratch, then click Continue at the bottom of the page.

Step 2: Configure your workflow settings

1. On the Create Workflow page, fill in the fields to configure your workflow. The name, slug, and description are prepopulated for templates.
   • Name: Enter a descriptive name for your workflow.
   • Slug: Enter a unique slug. If you have previously used a template, make sure to update the prepopulated slug when you use the template again.
   • Description: Optionally enter a description of the workflow.
   • Response template: Optionally enter a response template.
     • See more information about templating in the Actions docs.
   • Scope: Select Entity to narrow the workflow's scope to a specific entity, or select Global if the workflow should not be scoped to a specific entity.
     • If you choose Entity:
       • User relation to entities: Specify the relation to the entity that the user running the workflow must have in order to run the workflow. You can require the user to be an Owner or an Editor of the entity in order to run the workflow. If you choose Editor, you must have the Team ownership entity setting enabled.
       • Entity Type: Select the entity type that this workflow applies to.
       • Optionally, you can also choose groups to include or exclude.
   • The toggle for Everyone can run this workflow is enabled by default.
     • If you disable this toggle, you can select specific users, teams, or roles who are allowed to run the workflow.
     • In order for a user to run the workflow, they must have the Workflow runs execute permission and they must match at least one of the users, teams, or roles that you specify here.
2. Optionally, if you want to first save this workflow as a draft, toggle the Draft setting on.
   • When a workflow is saved as a draft, it is only visible to users with the Workflow edit permission.
3. Click Save Workflow.

Step 3: Add actions to your workflow

To add an action to your workflow, click + in the workflow visual in the center of the page.

You can create the following action types:

• Branch
• Data transformation
• HTTP request
• Manual approval
• Scaffolder
• Slack
• User input

Action types

caution

The slug for each action must be unique across a workflow.

See the tabs below for instructions specific to each type of action that you can add to a workflow.

Branch

The Branch action allows you to set up to five conditional paths for a workflow.

Configure a branch action

To configure a branch action:

1. Click Branch from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Click +Add Path.
4. In the dialog that appears, enter a name, a slug, and a path expression.
   • The path expression is compatible with CEL syntax. The path expression does not accept dashed values; if you reference an action's slug that contains a dash, wrap the slug in quotes and square brackets.
     • For example, if you want to reference an action with the slug example-action, the expression would begin with actions["example-action"].
       

tip

Autocomplete will provide correctly formatted options based on the actions defined in your workflow.

5. Click Add path.
   • You will be redirected to the action editor page, showing your newly-added path in the workflow visual.
6. Optionally, add additional paths and a fallback path.
   • Click + under a path to add the next type of action. You can add any action type, including another branch.
7. When you are finished adding paths, click Save Workflow at the bottom of the action editor.
8. If you want to add additional actions that occur after the paths within your branch action, click + below the branch action box in the workflow editor.

How paths work

The paths defined run sequentially. The first path that returns true will execute, even if subsequent paths would also return true. The workflow will then continue performing actions in that path. You can also set a fallback path that will run if all other paths fail.

Primary and nested branches function the same way.

Nested branches

You can nest a branch under any or all of the original paths, but you cannot nest further.

To nest a branch:

1. In the visual workflow, click the + that is branched off your original branch.
2. On the right side of the page in the workflow editor, select Branch.
3. Enter a name for your branch, then click Save action.
   

There are no limits on how many branches you can nest.

Data transformation

The Data transformation action performs data transformations using jq. Except for the action name and slug, the only field required is the jq expression.

Configure a data transformation action

To configure a data transformation action:

1. Click Data transformation from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Enter a jq expression. This field can pass any sort of jq expression, as long as the variables and context are referenced differently.
   • Although you would typically use {} to template the context of your workflow, in this field you’ll need to reference such values as jq query values.
4. Click Save action.

HTTP request

The HTTP request action makes and records a request to a given URL.

Configure an HTTP request action

To configure an HTTP request action:

1. Click HTTP request from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Select an HTTP method. The options are DELETE, GET, PATCH, POST, or PUT.
4. Configure the fields:
   • URL: Enter a static URL or use a template to reference other actions, e.g., {{actions.slug.outputs.result}}.
     • If you use {{actions.url.outputs.result}}, for example, you can set the URL to the output of a jq action. In this example, .actions indicates a reference to a workflow action, .url is the slug for the action we’re referencing, .outputs is the location of the actual output of the jq expression, and .result is the result field where the output is stored.
     • Because Mustache performs HTML escaping by default, special characters referenced in a value with two curly braces ({{}}) will be converted to their associated HTML encoding. For example, {{=}} would become &#61. To reference a non-escaped value, use three curly braces ({{{=}}}).
   • Headers: Click one of the options provided, or enter your own.
     • When using a secret with a header, prefix the secret with context..
   • Payload: This field appears if you are using an HTTP request that sends a payload. The payload that you supply can also be templated and can reference an entity that the workflow is being run with. Some additional steps are required to properly template raw JSON in the payload field.
     • Single primitive values will work as expected, but to add JSON objects or arrays, follow these steps you first need to create a Data Transformation action that accesses the relevant JSON and pipes it into the tojson built-in.
     • For example, .context.initiatedBy | tojson would enable a user to add the full initiatedBy object ({ "email": "user@email.com" }) into an HTTP request payload. When templating this value, three curly braces are needed in order to reference a non-escaped value. Continuing our earlier example, if the data transformation action we just created has the slug transform-to-json, then the payload would include {{{actions.transform-to-json.outputs.result}}}.
       
5. Click Save action.

caution

If using special characters when templating, make sure to include three curly braces to reference a non-HTML-escaped value.

Manual approval

The Manual approval action type pauses the workflow to get approval from a member of a given Team. Like with user inputs, the workflow will proceed to the next action once the action has been approved.

Configure a manual approval action

To configure a manual approval action:

1. Click Manual approval from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Under Teams allowed to approve, select one or more teams who are allowed to approve the action. Any member of a given team can approve the action.
4. Click Save action.

You can have multiple manual approvals within a given workflow. If you have two actions with two different sets of teams set as approvers, each team will only be able to approve the action they are defined under.

Pending approval

When a manual approval action is triggered, users that belong to teams designated as approvers will see an additional tab in the Workflows page: Pending approval.

This page displays any actions that are pending your approval. If manual approval actions exist within a workflow, but do not require your approval, they will not appear here, even if you are designated to approve a different action in the same workflow.

You can open any workflow in the pending approval tab to Approve or Reject the action.

Once all of your approval requests have been approved or rejected, this tab will disappear from the Workflows page.

Scaffolder

The Scaffolder action uses a Cortex Scaffolder template to perform a given function. You must have the Execute Scaffolder permission to configure a Scaffolder action.

Configure a Scaffolder action

To configure a Scaffolder action:

1. Click Scaffolder from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Under Scaffolder template, select a template from the dropdown.
   • This dropdown pulls in all templates available from the Scaffolder page.
4. Configure the remaining fields. The fields differ depending on the template's specifications and available Git providers. The option to create a repo also may or may not be visible, depending on whether the template requires a pull request.
   
5. Click Save action.

Define Scaffolder template overrides

You can also define Scaffolder template overrides for an action — these will override template fields with output variables from a previous workflow step, or from the context of the workflow.

To add an override:

1. In the bottom of the action configuration, click Add variable.
2. In the override variable modal, click the Select a variable dropdown to select the Scaffolder template fields to override. Note that the options in this dropdown will be pulled from fields in the Scaffolder template you selected in the first step.
   
3. Under Path to variable, enter the path to the actual value we want in the workflow.
   • For example, if you wanted to override the Project name variable for a Scaffolder with the tag of the entity you’re running, the path would be context.entity.tag — that will obtain and supply the value.
4. If you want to override the options that are available to a user running the workflow, toggle on Is value override.
   • For example, if you wanted to restrict the project name to some set of values based on a particular HTTP fetch, you would toggle this setting on.
   • When toggled on, the value being grabbed in lieu of project_name is the value of the variable. When toggled off, the value grabbed would be the option provided for that variable, i.e. the project name.

When you run a workflow with a Scaffolder action, the action will perform the typical Scaffolder flow, prompting a user to provide certain inputs. Once those inputs are provided, the Scaffolder will run.

Slack

The Slack action sends a Slack message to a given channel.

Prerequisites

Before configuring a Slack action:

• Make sure the Cortex Slack Bot is added to the channel you want to send messages to via the action.
• Make sure the Slack Bot has the chat:write.public permission scope enabled.

Configure a Slack action

To configure a Slack action:

1. Click Slack from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Under Channel name, select a channel.
   • The channels listed in the dropdown are pulled from your organization's integration with Slack.
4. Under Message text, enter the message that will be sent in Slack via this action.
   • You can enter a simple string or use templating for a more dynamic message. For example, you can templatize to include the email address of the person who initiated the workflow, reference prior actions, or reference outputs.
5. Click Save action.

Note

When testing your new Slack action, if you receive the error Cannot send message to Slack channel without invitation, please try reinstalling the Slack integration to ensure that the correct permissions are configured.

User input

The User input action pauses the workflow and prompts the user for specific inputs. Once user inputs are entered, the workflow will proceed to the next action.

Note that users with permission to "Edit workflows" will be able to obtain secret values using complex data transformation on secrets or echoing services.

Configure a user input action

To configure a user input action:

1. Click User input from the list of actions.
2. Enter a name.
   • The slug field will automatically pre-populate based on the name you enter.
3. Click Add input.
   
4. Configure the "Create input field" form:
   • Type: Select from the following:
     • Paragraph: Multi-line, freeform text.
     • Secret: Capture a secret value.
     • Select: Manually configured or predefined data selection.
       • Toggle on Allow multiple to enable multiple selections for a given input field.
     • Text: Short, freeform text.
     • Toggle: Boolean value.
   • Name: Enter a name for the input field.
   • Key: Enter a value to be used when templating. This must be unique across fields in a given user input action.
   • Description: Enter a description of the input field.
   • Placeholder: Enter text to display when a field is empty.
   • Default value: Enter a value that will automatically populate the field.
   • Previous action output path: Optionally, enter the previous action output path to override the value of a given input.
     • For example, if the key is name, then entering actions.name-action.outputs.name in the previous action output path field will use the output from a previous step as the name.
   • Validation regex: Set validation options for the input field.
     • If you chose the Secret type, enter the secret value that a user will need to input to run this action.
5. Additional configuration is required for the Select type. See the additional steps for the Select type below.
6. Click Apply at the bottom of the "Edit input field" modal.
7. Click Add input field.

Additional steps for the Select type

If you chose the type Select while configuring the user input action, additional fields must be configured depending on which Data source you select:

• Manual data source: You can manually define each option for the input. You can select any of these defined options as the default value.
  
• Cortex entity data source: You can filter the entities that will be available for user selection. If you don't set filters, the input will apply to all entities in your catalog.
  
• Cortex user data source: You can filter by teams and users to determine the options available to users. If you don't set filters, the input will apply to all Cortex users and Teams.
  
• Slack channels data source: You can choose to include or exclude one or more Slack channels from the available options. The default values will include all Slack channels registered in Cortex.

---

Referencing previous actions and workflow state

Each workflow, when run, will build up a state object that can be referenced throughout the workflow, and allows actions to reference both the top-level state and a previous action's state.

In addition, you can use an action's unique identifier (a slug or a user input key) to reference it in another action within your workflow.

Read more in the Actions documentation.

Additional information on actions

To learn about using request signing with actions, duplicating an action, and templating an action, see the Actions documentation.

Running a Workflow

Run a Workflow from the Workflows page

1. On the Workflows page, locate the Workflow you want to run.
2. On the right side of the Workflow, click the Play icon.
   • The workflow will automatically launch. Workflows that require User input or Manual approval will pause until your configured input or approval is completed.

When an action completes, a green checkmark is displayed in the top right corner. Actions that require input or approval will display an orange Pause icon.

When a run has been started, it appears in the Runs tab on the Workflows page. A completed runs will display as Successful, while those awaiting input or approval will display as Paused.

Running a workflow with secret user input

If the Workflow has a secret user input action configured, the user running the Workflow will be prompted to enter information into the field, which will be redacted in the Workflow's Outputs tab. If the Workflow has regex validation configured, the user must enter a secret matching the value of the Validation regex that was configured for this action.

The secret fields can be seen in the Output of the workflow after it has been run, but the secret values will be redacted.

Note that users with permission Edit Workflows will be able to obtain secret values using complex data transformation on secrets or echoing services.

Run a workflow from an entity

You can also run a workflow while viewing an entity:

1. On the left navigation menu of Cortex, click Catalogs > All entities.
2. Click an entity to view its details page.
3. On the left side of the entity details, click Workflows to view and run any entity-scoped Workflows.

Cancel a workflow

If you cancel a run that is partially complete, it will not undo any successfully completed actions.

To cancel a running workflow:

1. On the Workflows page, click the Runs tab then locate the Workflow you want to cancel.
2. Click on the Workflow to view its run details page.
3. Click Cancel run.