LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • Configuring blocks in a workflow
  • Available types of blocks
  • Duplicating a block
  • Using request signing with Workflow blocks
  • Workflow states
  • The Workflow state context key
  • Referencing a block or workflow state in a workflow
  • Additional information on Workflows

Was this helpful?

Export as PDF
  1. Workflows

Blocks

Last updated 3 days ago

Was this helpful?

Blocks (formerly known as actions) are the building blocks of Workflows. Workflows are made up of individual blocks, which are each responsible for a specific task. A Workflow allows you to run a sequence of tasks that can reference contextual data from your workspace.

Configuring blocks in a workflow

To learn how to create a Workflow and configure blocks, see .

You must have the Edit Workflows permission to create, update, and delete Workflows.

Available types of blocks

Cortex offers a searchable library of blocks that can be added to your Workflows:

  • Core blocks

    • Perform actions such as requiring a manual approval on a step within a Workflow.

  • Cortex blocks

    • Perform Cortex-based actions, such as getting scores for an entity.

      • Note that Cortex blocks use the of the Workflow's initiating user. If the user does not have permissions to execute the action associated with a given block, the block will fail.

  • Third-party integration blocks

    • For example, you can add a block that creates a new repository in , or you can add a block that creates a new incident in .

Integration blocks

Cortex provides prebuilt blocks to perform a variety of actions for the following integrations:

Core blocks

Cortex provides the following core blocks:

  • Branch

  • Data transformation

  • HTTP request

  • HTTP request (async)

  • JavaScript

  • Manual approval

  • Scaffolder

  • User input

Duplicating a block

There may be an instance where you want to repeat a task within your Workflow. It is possible to duplicate an existing block.

To duplicate a block:

  1. In Cortex, navigate to the Workflow that contains the block you want to copy.

  2. Click the 3 dots icon on the right side of the block.

  3. In the dropdown menu, click Duplicate block.

  4. If needed, drag and drop the block to reorder it in the Workflow.

Using request signing with Workflow blocks

If you're using a Workflow as a way to trigger hooks into internal tooling, we recommend validating that the request is actually originating from Cortex using request signing. Signing secrets are added to requests coming from Workflow blocks.

We add the following headers to each request made by Cortex. Use these headers to verify that the request is valid and originated from Cortex:

  • x-cortex-timestamp

    • This header uses the current timestamp in millis, and is used to prevent replay attacks. Cortex will sign the requests using the format <timestamp>.<body>.

  • x-cortex-timestamp-only-signature-256

    • This header calculates the SHA256 signature using only the timestamp. Use this header in environments where the HTTP request body is unavailable due to platform limitations.

  • x-cortex-signature-256

    • This header uses the SHA256 algorithm. For security best practices, we recommend using this header rather than x-cortex-signature.

  • x-cortex-signature

    • This header uses the SHA1 algorithm and exists for backward compatibility. SHA1 is considered unsafe and this signature should be considered deprecated.

To configure a signing secret:

  1. Enter a secret into the text field, then click Save secret.

    1. Create a string with the value $timestamp.$requestBody if the request body is non-null OR $timestamp if the request body is null.

    2. Calculate an HMAC using the SHA256 algorithm. Use the Secret you provided to Cortex as the key and the string from Step 1 as the payload.

    3. Verify that the x-cortex-signature-256 matches the HMAC calculated in Step 2.

Workflow states

The Workflow state object includes top-level context and actions keys:

  • context is immutable, set at the beginning, and available to all blocks.

    • If an entity changes during Workflow execution, those changes will not be represented in context.entity.

    • If secrets change during a Workflow, those changes will not be represented in context.secrets.

    • You can examine the context object via the Run context tab when viewing a Workflow run.

  • actions is built up as actions execute via blocks.

    • Each block will have an inputs and outputs key, but their format differs based on the block type.

The state object looks similar to the following:

Workflow state object example

{
  "context": {
    "initiatedBy": {
      "name": "Henry Hippocampus",
      "email": "henry.hippocampus@cortex.io",
      "identityMappings": {
        "github": "hhippocampus"
      },
      "identityMappingsByAlias": {
        "github": {
          "cortex": "hhippocampus",
          "other-config": "hippo"
        }
      }
    },
    "workflowRunId":"a607c73f-b8e2-44b7-aa20-e23de7cf7af7",
    "initiatedAtIso8601Timestamp": "2025-05-16T21:42:37.642+00:00", // ISO8601 timestamp
    "secrets": {
      "secret-tag": "********"
    },
    "entity": { // only present for entity-scoped workflows
      "id": "en0123456789abcdef",
      "tag": "test-entity",
      "name": "Test Entity",
      "descriptor": { 
        "info": { ... }
      }
    }
  },
  "actions": {
    "action-slug-1": {
      "inputs": {},
      "outputs": {}
    }, 
    "action-slug-2": {
      "inputs": {},
      "outputs": {}
    }
    ...
  }
}

The Workflow state context key

The context object always has the following keys:

  • {{context.workflowRunId}}: The Workflow run ID

  • {{context.initiatedAtIso8601Timestamp}}: The timestamp at which this block was initiated

  • {{context.initiatedBy}}: The user object of the initiator

    • email: The user's email

    • name: The initiator's name

    • identityMappings: A mapping of the identity providers listed below to the initiating user's corresponding external ID. The external ID will be pulled from identity provider's default configuration when there is more than one configuration.

      • azure_devops

      • bitbucket

      • clickup

      • github

      • gitlab

      • jira

      • microsoft_teams

      • opsgenie

      • pagerduty

      • service_now

      • slack

    • identityMappingsByAlias: Similar to identityMappings, but each provider maps to an object of configuration alias to external ID. This field is useful when users have different external IDs across an integration's configurations.

  • {{context.secrets}} An object of Cortex secret tags to their values.

Access configured secrets

You can access your configured secrets by tag: {{context.secrets.SECRET_TAG}}.

Note that Mustache performs HTML escaping by default, so if your configured secret contains a reserved HTML character, use triple braces to use raw content: {{{context.secrets.SECRET_TAG}}}.

Secret values are redacted in inputs and outputs of the workflow state.

Accessing a secret in the context object is not supported for Slack blocks.

Access entity data

If the block is being run in the context of a catalog entity, the template context will contain data about the entity in the {{context.entity}} key:

  • id

  • tag

  • name

  • descriptor (this is the cortex.yaml, as an object)

These can be accessed under the {{context.entity}} key, for example {{context.entity.tag}} or {{context.entity.descriptor.info.x-cortex-git.github.repository}}

Referencing a block or workflow state in a workflow

You can reference a previous block or a workflow state in several ways:

  • Accessed directly from JQ actions

  • Referenced to define "User input" block overrides

  • Referenced in "Branch" block path expressions using CEL syntax

Block and workflow state reference example

Assume a Workflow was created where you gather names from an "HTTP request" block, a "data transformation" block parses the array of names, the names are surfaced to users in a "user input" block where they can select a name, then a "branch" block runs a different path based on which name was selected during the previous "user input" block. In one of the branch paths, there is a "Slack" block that sends a templated message based on the output of previous blocks.

The workflow contains the following blocks:

  • HTTP request block called users

    • In this example, the block sends a GET request to gather user names from a URL containing sample data.

  • Data transformation block called names

    • It contains a JQ query referencing the output of the users block: [.actions.users.outputs.body[] | .name]

  • User input block called pick-name

    • It contains an override that references the output of the names block: actions.names.outputs.result

  • Branch block called create-services

    • There are multiple paths in this branch, depending on which name you chose in the previous block. One of the name options is Ervin, and there is a conditional path called Ervin within this block that contains the following path expression. It references Ervin as the output of the pick-names block: actions['pick-name'].outputs.name == 'Ervin' && context.entity.descriptor.info['x-cortex-type'] == 'team'.

    • The Ervin path contains a Slack block to send a templated message via Slack, referencing the output of the pick-name block and referencing the workflow state by including the email address of the user who initiated the workflow: We created a service for {{actions.pick-name.outputs.name}}. [message from workflow triggered by {{context.initiatedBy.email}}]

When you run the workflow, the following chain of events occurs:

  1. The HTTP request block gathers user names.

    • In the "Inputs" tab of this block, you can see where the data was pulled from.

    • In the "Outputs" tab of this block, you can see the list of names under the body.

  2. The data transformation block parses an array of names from the HTTP request block.

    • In the "Outputs" tab of this block, you can see the list of names.

  3. The Workflow is paused while awaiting user input. The user input block surfaces a name field where the user can select a name from the list. The names are from the array parsed in the previous block.

  4. The user selects the name Ervin, and the Workflow continues to the next block.

  5. The branch block runs a path depending on which name you chose in the previous block. In this example, the Ervin path runs because the CEL expression for that conditional path was configured to run when the pick-name block's output is Ervin.

    • In the "Outputs" tab of this block, you can see the conditions that were checked to verify which path to run.

  6. The Ervin path contains a Slack block that sends a templated message referencing the output the previous block and the user who initiated the Workflow. The message is sent to the user with the templated references translated: We created a service for Ervin. [message from workflow triggered by jdoe@example.com]

Additional information on Workflows

See instructions for configuring integration-related blocks in the Workflows documentation under .

See instructions for configuring each type of core block in the Workflows documentation under .

A copy of the block will be duplicated in place within the Workflow.

In Cortex, navigate to , then scroll down to the "Request signing secret" section.

Calculate the signature (an HMAC):

Each Workflow, when run, will build up a state object. This state can be and allows blocks to reference both the top-level state (e.g., who initiated a Workflow) and the state of a previous block.

Read more about .

Templated into block schemas via ({{}})

To learn more about using blocks in a Workflow, see the .

AWS
Azure DevOps
Bitbucket
GitHub
GitLab
Jenkins
LaunchDarkly
Microsoft Teams
PagerDuty
ServiceNow
Slack
Settings > Secrets
RFC2104
Mustache
Workflows documentation
referenced throughout the Workflow
the context key below
the Workflows documentation
Scorecard
permissions
GitHub
ServiceNow
Step 3: Add blocks to your Workflow
Step 3: Add blocks to your Workflow
The searchable blocks library lists available core blocks, Cortex blocks, and integration blocks.