# Workflows

A Workflow is an automated, multi-step process that runs entirely within your Cortex workspace. It lets teams define tasks, trigger actions, collect input, and route approvals in one place, turning complex operations into a single, repeatable experience.

Workflows address the friction that comes from relying on manual checklists, Slack threads, and siloed knowledge to run critical processes. Specifically, they solve for inconsistency across teams, slow or invisible approvals, repeated manual effort on common tasks, and the risk of errors when steps are done ad hoc.

{% hint style="success" %}
Looking for a quick introduction to building and managing Workflows? Check out the Cortex Academy course on [Workflows](https://academy.cortex.io/courses/understanding-workflows).
{% endhint %}

## How workflows work <a href="#how-workflows-work" id="how-workflows-work"></a>

Engineering teams use workflows when they need to standardize and automate high-stakes operations like service creation, access provisioning, or incident response, especially when those processes involve multiple tools, people, or approval steps. They're also useful for onboarding, where repeatability and speed matter.

### How is a Workflow structured? <a href="#structured" id="structured"></a>

Workflows are made up of steps called blocks. Each block defines part of your workflow's logic and can collect input, trigger external systems, apply conditional logic, or interact with Cortex.

**Note:** If the initiating user doesn't have permission to perform the block's action, the block fails. To manage who can run the workflow, use access controls.

Blocks are organized into three categories:

1. **Core blocks** - Core blocks control the fundamental behavior, logic, and flow of a workflow. They include:
   * Asynchronous HTTP request - Make an asynchronous HTTP request and wait for callback
   * Branch - Create a branch based on conditional logic
   * Data transformation - Run a JQ expression
   * HTTP request -Make an HTTP request
   * JavaScript - Run a JavaScript script
   * Manual approval - Await asynchronous human approval
   * Scaffolder - Run a scaffolder template
   * Set variable(s) - Set or update variable(s)
   * User input - Collect asynchronous input from users
2. **Cortex blocks** - Cortex blocks perform actions against your Cortex catalog or use internal platform data. They run using the permissions of the user who initiated the workflow and include:
   * Create or update an entity
   * Add custom data to an entity
   * List deployments tied to an entity
   * Get Scorecard scores or details
3. **Integration blocks** - Integration blocks connect workflows to external tools such as GitHub, PagerDuty, ServiceNow, and Slack, enabling automation across incidents, repositories, approvals, and more. Common use cases include:
   * Creating a new GitHub repository
   * Opening an incident in ServiceNow
   * Sending a message to a Slack channel
   * Updating a Jira issue
   * Triggering a Jenkins job or pipeline

{% hint style="info" %}
Cortex supports a growing number of integrations across engineering and operations tools, including AWS, GitHub, Jenkins, PagerDuty, and Slack. For a full list of supported platforms, see [Integrations](/ingesting-data-into-cortex/integrations.md).
{% endhint %}

### How does a workflow manage data during a run? <a href="#data" id="data"></a>

When a workflow runs, Cortex generates a state object with two top-level keys: context and actions.

**Context** contains metadata about the workflow run. It's created at the start and remains unchanged throughout execution, even if the entity or its secrets change. Useful context fields include:

* `context.entity` - The workflow's entity, including tag, name, and full descriptor from `cortex.yaml`.
* `context.initiatedBy` - The user who triggered the workflow.
* `context.secrets` - Secure secrets referenced by tag. Secrets are automatically redacted in workflow runs and outputs.

You can reference context values using mustache templating, for example:

```
{{context.entity.tag}}
{{context.initiatedBy.email}}
{{context.secrets.slack-api-token}}
```

**Actions** build dynamically as the workflow runs. Each block adds a key named after its slug, storing both inputs and outputs. This allows later steps to reference outputs from earlier ones, e.g. `{{actions.get-users.outputs.result}}`. This value can be used in a JQ expression, a user input block, or an HTTP request payload.

## Identifying processes to turn into Workflows

Standardizing repeatable tasks across your teams ensures consistency and improves quality. Cortex features like [Scorecards](/standardize/scorecards.md) and [Eng Intelligence](/improve/eng-intelligence.md) can help you identify good candidates for Workflow automation.

* **Scorecards** - Use Scorecards to see how teams perform against your standards over time, allowing you to identify overburdened teams and other areas for improvement. If a team has a lower score, investigate which processes are causing friction. Can any of their processes become Workflows to automate best practices and improve their efficiency?
* **Eng Intelligence** - Use Eng Intelligence to understand how teams are performing across different industry KPIs. Use this data to drive improvement via Workflows. For example, review metrics for cycle time and deployment frequency to identify where work gets stuck. Can any of these processes become Workflows to free up time and ship faster?

For a list of Workflow use case ideas, see the [Workflow guides](/guides/product-areas/workflows.md).

## Managing Workflows

Workflows can be managed in the [Cortex UI](/streamline/workflows/create.md) or via [GitOps](/streamline/workflows/workflows-as-code.md). You can also use the [API](/api/readme/workflows.md) to create, read, update, and delete Workflows. The API can also trigger Workflow runs and retrieve their status and history.

{% hint style="info" %}
When using GitOps to manage Workflows, it's recommended to build out the Workflow in the UI first for an easier start and faster testing. Learn more in [Workflows as code](/streamline/workflows/workflows-as-code.md).
{% endhint %}

It's possible to configure specific users, teams, or roles to run a Workflow. See [Configuring Workflow settings](/streamline/workflows/create.md#step-2-configuring-workflow-settings).

It's also possible to add a "Manual approval" block to a Workflow, requiring approval from specific team members. Read more in the [Blocks documentation](/streamline/workflows/blocks.md).

## Workflows overview video

{% embed url="<https://www.youtube.com/watch?v=AiJYYnOFAqk>" %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/streamline/workflows.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.