Skip to main content

Workflows

The Workflows feature allows you to automate complex development workflows within Cortex based on all the contextual data that exists 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.

You can access Workflows from the main nav.

workflows 1

All existing workflows can be viewed together in the Workflows tab. You can see a given 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, you can find historic runs for each workflow, as well as its status: In Progress, Paused, Successful, Canceled, or Error.

workflows 2

Creating a workflow

Users with permissions to edit workflows can select Create workflow next to the search bar to begin constructing a workflow.

workflows 3

A workflow comprises high-level metadata and a collection of actions that run sequentially. The first step when creating any workflow is entering some key information: the name of your workflow and a description of what the workflow does. Both will appear on the main Workflows page.

workflows 4

You’ll also be asked to supply a slug for your workflow. Like a tag, this will be used to identify a specific workflow. Unlike tags, slugs can be updated and edited.

info

Unlike tags, slugs can be updated/edited.

Next, you’ll define the scope of your workflow, or the context in which the workflow will run. A Global scope won’t narrow the workflow’s scope to a specific entity, whereas an Entity scope will apply to a specific entity.

workflows 5

Then, you can choose to include or exclude certain groups to filter the applicable entities.

Finally, you’ll set a Permission for the workflow. This will dictate who will be able to view and run a given workflow.

workflows 6

When permission is set to All, all users in your workspace will be able to access the workflow. The Workflows write permission limits workflow accessibility to users with admin permissions and users with a custom role that includes workflow write permissions.

Workflows with the Workflows write permission enabled will not be visible to users without appropriate permissions.

Before you save a workflow, you can toggle Draft on or off. Note that when draft is enabled, the workflow will only be visible to users with admin or workflows write permissions, even if the permission is set to All.

Adding actions

To add an action to your workflow, select the Add action button in the UI builder. You can create one of six different action types: HTTP request, Scaffolder, user input, data transformation, Slack, and manual approval.

workflows 7

All actions require a name and a slug. The slug for an action must be unique across the workflow. The rest of the fields will depend on the action type you select.

caution

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

HTTP request

The HTTP request action makes and records a request to a given URL. For this action, you’ll enter an HTTP method — DELETE, GET, PATCH, POST, or PUT — as well as a URL and a collection of headers.

workflows 8

The URL you enter can be a static URL, or you can use a template to reference other actions: {{actions.slug.outputs.result}}.

If we use {{actions.url.outputs.result}}, for example, we 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 ({{{=}}}).

Next, you’ll enter Headers for the HTTP request. You can use the options provided, or enter your own.

You’ll also see a Payload field for HTTP requests that send a payload — DELETE, PATCH, POST, or PUT.

workflows 9

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 }}}.

caution

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

Scaffolder

The Scaffolder action uses a Cortex Scaffolder template to perform a given function. Select a Scaffolder template from the dropdown — this will pull all templates available to you from the Scaffolder page.

workflows 10

Depending on the template's specifications and available Git providers, you'll see the option to Create a new repo or Open a pull request.

  • When using GitLab, you'll see Merge request/project.
  • Bitbucket and Azure DevOps only support the option to Create a new repo.

The option to create a repo also may or may not be visible, depending on whether the template requires a pull request.

workflows 11

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. Select Add variable to create an override.

workflows 12

Use 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.

Then, enter a Path to variable, the path to the actual value we want in the workflow. For example, if we wanted to override the Project name variable for a Scaffolder with the tag of the entity we’re running, our path would be context.entity.tag — that will grab and supply the value.

It’s also possible to override the options that are available to a user running the workflow by toggling Is value override. For example, if we wanted to restrict the project name to some set of values based on a particular HTTP fetch, we would toggle Is value override on.

workflows 13

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.

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.

workflows 14

Use the Add input button to define a user input field.

workflows 15

First, select the Type for the input:

  • Text
  • Multi-select
  • Select
  • Long text
  • Toggle

The majority of form fields will be the same across these input types.

In addition to a name for the input, you’ll be required to supply a Key, which must be unique across fields in a given user input action. The key value will be used when templating.

Next, you can enter an optional Placeholder for the input. This will display when a field is empty, and can give the user an idea of what value to enter.

In the optional Previous step input path field, you can override the value of this input, just like with the Scaffolder override path. For example, if our key is name, then entering actions.name-action.outputs.name in the previous step input path field will use the output from a previous step as the name.

workflows 16

Next, you can enter a Validation regex and a Default value for the input. You can also set whether the input is required or optional.

Finally, you have the option to add a description to a specific input. If it’s not immediately obvious what information the action is seeking, a description can help clarify how to proceed.

Type-specific inputs

When you create a multi-select input field, you’ll see an additional Options field where you can supply as many options as makes sense for the input. The default value option will also display as a dropdown with the options you supplied.

workflows 17

When you create a Select input field, you’ll also have the ability to supply options.

Note

Multi-select inputs allow a user to choose more than one value, while Select inputs limit users to a single value.

workflows 18

The Select input type also includes a toggle for Is value override. Like with the Scaffolder action type, this allows you to use the value in the Previous step input path field to override the options. When Is value override is toggled on, users cannot interact with this input field when the workflow is running.

workflows 19

You can define as many user inputs as you want for a given User input action. Next to the name for each input field, you can see its type.

Note that the order in which the inputs are added will be the same order users will be prompted to answer in.

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.

workflows 20

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.

This field can pass any sort of jq expression, as long as the variables and context are referenced differently.

Slack

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

workflows 21

For this action, select a Channel name from the dropdown menu. The channels available in the dropdown are pulled directly from your organization’s integration with Slack.

Note

The hash character for a Slack channel is already provided before the dropdown field.

In the Message text field, you can dictate the actual message text that will be sent in the Slack message. 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.

Note

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

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 or rejected.

workflows 22

From the dropdown, you can select one or more Teams allowed to approve the action. Any member of a given team can approve the 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.

workflows 23

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.

Running a workflow

Once you’ve created a workflow, you can run it from the Workflows page by selecting the play icon or while editing a given workflow.

workflows 25

The workflow will automatically launch when you select run, but will pause for User inputs and Manual approvals.

When you run a workflow, you can select any action to see its Inputs, Outputs, and Run context in the side panel.

workflows 26

As each action completes, you’ll see a green checkmark in the top right corner. Actions that require input or approval will have an orange pause icon in the corner.

workflows 27

You can also cancel a workflow while it's running by clicking the Cancel run link within a run's details page. If you cancel a run that's partially complete, it will not undo any previously successful steps.

workflows 28

tip

You can cancel a run that's partly complete without undoing any successful steps.

Once a run has been started, it will appear in the runs tab. Completed runs will display as Successful, while those awaiting input or approval will display as Paused.