Creating a Workflow

Workflows allow you to automate running sequential actions and development workflows based on contextual data that exist inside your workspace. On this page, learn how to create a Workflow in the Cortex UI.

For information on creating Workflows via GitOps, see Workflows as code.

How to create a Workflow

Prerequisites

Before getting started:

• You must have the Edit Workflows permission.

• If you plan to manage Workflows in the UI, make sure UI editing is enabled under Settings > GitOps > Workflows.

Understanding RBAC for Workflows

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 add a "Manual approval" block to your Workflow, requiring approval from specific team members. Read more about configuring this under Step 3: Add blocks to your Workflow.

Step 1: Choose a template or a blank Workflow

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

1. In the lefthand navigation menu of Cortex, click Workflows.

2. In the upper right corner of the page, click Create Workflow.

3. Choose whether to start with a template or a blank workflow.

   • Workflow Template: Click the tile for the template you wish to use.

     • There are templates available for the following common Workflows: Create a AWS S3 bucket, create an AWS EC2 instance, create a ServiceNow incident, create an Azure function, and create a Jira issue.

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

   • Blank Scorecard: Click the "Blank Workflow" tile at the top 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.

   • Display icon: Select an icon that will be used when displaying this Workflow across Cortex.

   • Run response template: Optionally enter a response template.

     • See more information about templating in the Blocks documentation.
   • 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:

       • Entity Type: Select the entity type that this Workflow applies to.

         • Optionally, you can also choose groups to include or exclude.

       • 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.
2. Optionally, if you want to first save this Workflow as a draft, toggle on Save as draft at the top of the page.

   • When a Workflow is saved as a draft, it is only visible to users with the Workflow edit permission.

3. By default, a Workflow will be visible to all users in your organization who have permission to view Workflows. If you want to adjust view permissions for your Workflow:

   1. Click Access at the top of the page.

   2. Turn off the toggle for Organization access.

   3. Configure the users, teams, or roles who should have access to your 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.

   4. Click Apply.

      
4. At the top of the page, click Save Workflow.

Step 3: Add blocks to your Workflow

Workflows are made of individual blocks, which are each responsible for a specific task when a Workflow is run. To add a block to your Workflow, click + in the Workflow visual in the center of the page, choose the type, then configure the block.

Click + to add a block

Cortex provides a library of blocks to choose from, including core blocks, Cortex-based blocks, and integration-related blocks. Learn more about configuring blocks below.

Note: The slug for each block must be unique across a Workflow.

Adding core blocks

The core blocks are described below.

Branch

A Branch allows you to set up to five conditional paths for a Workflow.

Configure a branch

To configure a branch:

1. Click Branch from the list of blocks.

2. On the right side of the page, enter a Block name.

   • The slug field will automatically pre-populate based on the name you enter.

3. Click +Add Path.
4. On the right side of the page, the "Conditional paths" section will expand. 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 a block's slug that contains a dash, wrap the slug in quotes and square brackets.

     • For example, if you want to reference a block with the slug slug-example, the expression would begin with actions["slug-example"].

     • Note: Autocomplete will provide correctly formatted options based on the blocks defined in your Workflow.

5. Under the Path expression text box, click Save.

   • You will be redirected to the block 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 block. You can add any type, including another branch.

7. When you are finished adding paths, click Save at the bottom of the block editor.

8. If you want to add additional blocks that occur after the paths within your branch, click + below the branch 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 blocks 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

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.

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

Data transformation

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

Configure a data transformation

To configure a data transformation:

1. Click Data transformation from the list of blocks.

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.

HTTP request

The HTTP request makes and records a request to a given URL. For use cases requiring asynchronous operations (e.g., provisioning cloud resources, CI/CD pipelines), use the HTTP async action.

Configure an HTTP request

To configure an HTTP request:

1. Click HTTP request from the list of blocks.

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

     • 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 block

       • .url is the slug for the Workflow block we’re referencing

       • .outputs is the location of the actual output of the jq expression

       • .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. To add JSON objects or arrays, create a Data Transformation block 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 () 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 block we just created has the slug transform-to-json, then the payload would include {{{actions.transform-to-json.outputs.result}}}.

5. Click Save.

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

HTTP action (async)

The HTTP async request makes and records a request to a given URL. This block will pause execution until a callback API is invoked or a timeout occurs, enabling long-running Workflows.

You can pass the callback URL to the external service by using the template variable {{callbackUrl}}. This can be passed as part of the URL, in a header, or in the payload.

For example, when passing the variable in a URL, it would look like the following format: https://example.com/?url={{callbackUrl}}.

Configure an HTTP async request

1. Click HTTP action (async) from the list of blocks.

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

     • 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 block

       • .url is the slug for the Workflow block we’re referencing

       • .outputs is the location of the actual output of the jq expression

       • .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:

     • Include an Authorization header and use a personal access token.
     • Optionally include additional headers: Click one of the provided headers, 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 () 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}}}.

   • Timeout: Configure a timeout for this action. The maximum is 30 days and the minimum is 1 minute.

     • After a timeout, the block will fail with the status timed_out. If you have notifications enabled, you will receive a notification if you initiate a Workflow and it times out.

5. Click Save.

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

JavaScript

Configure a JavaScript block

Use a JavaScript block to insert custom code or add looping and other logic to your Workflows.

The JavaScript runtime supports the ES2020 specification and has an implementation of Fetch API, allowing you to make HTTP requests directly in the script rather than needing to add an additional HTTP request block to your Workflow.

To test your block's code locally, you can use Cortex's JavaScript harness.

1. Click JavaScript from the list of blocks.

2. On the right side of the page, configure the fields:

   • Block name: Enter a descriptive name for your block.

   • Slug: The slug field will automatically pre-populate based on the name you enter.

   • JavaScript: Enter the script you want to run. The script must end with a return statement. The value from the return statement is exposed via outputs.result.

     • For example, in the script return {"a": 1, "b": 2}, the result can be referenced from subsequent blocks as actions.<SLUG>.outputs.a.

     • You can reference previous blocks and run context by accessing actions and context. For example, actions["jq"].outputs.result

     • If you want the block to fail, you can use the throw statement. For example:

       let previous = actions.previous.outputs.result;
       if (previous == null) {
         throw "Some error";
       }

3. Click Save.

Manual approval

A Manual approval pauses the Workflow to get approval from a member of a given Team. Like with user inputs, the Workflow will proceed to the next block once it has been approved.

Configure a manual approval

To configure a manual approval:

1. Click Manual approval from the list of blocks.

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 request from this block. Any member of a given team can approve the block.

4. Click Save.

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

Pending approval

When a manual approval block is triggered, users that belong to teams designated as approvers will see Pending approvals at the top of their Workflows page.

This section displays any blocks 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 block in the same Workflow.

You can open any Workflow in the pending approval list to Approve or Reject the block.

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

Scaffolder

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

To configure a Scaffolder:

1. Click Scaffolder from the list of blocks.

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.

If using the Scaffolder to create a new repo and the desired repo already exists, Cortex will surface an error and prevent the flow from continuing.

Define Scaffolder template overrides

You can also define Scaffolder template overrides for a block — 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 block configuration, click Add variable.

2. In the override variable modal, click the 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, 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.

Running a workflow with a Scaffolder step

When you run a workflow with a Scaffolder block, the Scaffolder will prompt you for user input. Some fields, such as Commit message and Pull request title, only appear if your Scaffolder step creates a Pull Request rather than a repository.

After the inputs are provided, the Scaffolder will run.

User input

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

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

To configure a user input block:

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 user input.
4. Configure the "Create input field" form:

   • 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 block.

   • Description: Enter a description of the input field.

   • Type: Select from the following:

     • Number: A numerical value.

       • If you select this type, you can then choose Integer or Decimal for the number format, and select a minimum and maximum value.

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

     • Date: Date in YYYY-MM-DD format.

   • Placeholder: Enter text to display when a field is empty.

   • Default value: Enter a value that will automatically populate the field.

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

   • Path to override value: Optionally, enter the previous block 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 block output path field will use the output from a previous step as the name.

     • Is override value editable: Enable this option if you want to allow users to edit the override value before continuing to execute the Workflow.
5. Additional configuration is required for the Select type. See the additional steps for the Select type below.
6. Click Add input at the bottom of the "Edit input field" modal.

7. Click Save.

Additional steps for the Select type

If you chose the type Select while configuring the user input block, 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.

Adding Cortex blocks or integration blocks

Before adding an integration-based block, make sure you have configured the integration with the correct permissions described in Cortex's documentation for that integration.

1. While viewing the blocks library, click the integration block you want to add.

   • The necessary permissions needed for the block are included in the block library. For example:

   
2. At the bottom of the modal, click Insert.

   • The block is inserted into your Workflow, and a configuration form appears in the side panel.

3. In the side panel, configure the block metadata:

   • Block name: Add a name for your block.

   • Slug: Add a unique identifier for your block

4. When the integration supports multiple configurations, you'll be prompted to select the configuration alias to use with the block. The block will authenticate using the selected configuration, so ensure that you select the configuration with the required permissions.

5. Additional input fields differ depending on which block you choose.

   • These inputs are all template-able using Mustache-syntax ({{ ... }}). For fields that are not textual, click the "Path" icon on the right of the input to switch to Mustache-based templating.

   

   Number input

   

   Number input in templating mode
6. At the bottom of the side panel, click Save.

For additional information on configuring a Slack block, see below.

Slack

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

Prerequisites

Before configuring a Slack block:

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

Configure a Slack block

To configure a Slack block:

1. Click Slack from the list of blocks.

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

   • 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 blocks, or reference outputs.

5. Click Save.

When testing your new Slack block, 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.

Referencing previous blocks and Workflow state

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

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

Read more in the Blocks documentation.

Additional information on blocks

To learn about using request signing with blocks, duplicating a block, and templating a block, see the Blocks documentation.

Next step: Running a Workflow

To learn more, see Running a Workflow.