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 navigation bar.

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.

Creating a workflow

Select Create workflow next to the search bar to begin constructing a workflow.

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 will both appear on the main Workflows page.

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.

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.

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.

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.

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.

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.

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. 

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

The payload that you supply can also be templated and can reference an entity that the workflow is being run with. 

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.

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, while 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.

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.

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.

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

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

First, select the Type for the input: text, multi-select, select, long text, or 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. 

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 field for Options. Here, 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.

When you create a Select input field, you’ll also have the ability to supply Options. Note that multi-select inputs allow a user to choose more than one value, while select inputs limit users to a single value.

The Select input type also includes a toggle for Is value override. Like with the Scaffolder action type, the Is value override option 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.

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.

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.

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 that the hash character is already provided for you 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, to reference prior actions, or to 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.

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.

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.

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. 

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.

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.

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