Workflow block configuration reference

This page lists the configuration fields for each Workflow block as they appear in a Workflow definition. Use it when you create or update Workflows with the Workflows API or manage them as YAML with Workflows as code. The API and YAML use the same structure, so every example on this page works in both. In JSON, use the same keys. For instructions on configuring blocks in the Workflow editor, see Adding blocks to a Workflow.

The fastest way to get a correct definition is to build the Workflow in the UI first, then click Export Workflow YAML (see Workflows as code). The export shows the exact values Cortex expects, including IDs that are specific to your workspace.

How a block appears in a Workflow definition

In a definition, blocks are listed under actions. Each entry has the same outer fields, and the block-specific configuration sits under schema. The schema.type value sets which other fields the block takes.

Field	Type	Required	Description
`name`	string	Yes	The display name of the block.
`slug`	string	Yes	A unique identifier for the block within the Workflow. Use lowercase letters, digits, and hyphens, 2 to 255 characters, not starting or ending with a hyphen.
`isRootAction`	boolean	Yes	Whether this is the first block in the Workflow. A Workflow has exactly one root block.
`outgoingActions`	array of strings	Yes	The slugs of the blocks that run after this one. Use `[]` for the last block. For a Branch block, list the `outgoingAction` of every path, including the fallback path.
`schema`	object	Yes	The block’s configuration. Always includes `type`. See the sections below.

actions:
- name: Get user email
  slug: get-user-email
  isRootAction: true
  outgoingActions:
  - notify-team
  schema:
    type: JQ
    expression: .context.initiatedBy.email
- name: Notify team
  slug: notify-team
  isRootAction: false
  outgoingActions: []
  schema:
    type: SLACK
    channel: platform-team
    message: "Workflow started by {{actions.get-user-email.outputs.result}}"

Referencing run data in block fields

Blocks can read the Workflow run state through three top-level keys: context, actions, and variables. Each block writes its result to actions.<slug>.outputs. How you reference a value depends on the field:

Text fields (URLs, headers, payloads, messages, descriptions) - Use Mustache templates, such as {{variables.app-name}} or {{actions.get-user-email.outputs.result}}. Use three curly braces to avoid HTML escaping.
JQ expressions - Start with a dot, such as .variables.app-name.
CEL expressions, JavaScript, and path fields - Use dot paths without a leading dot, such as variables.app-name.
Slugs that contain a hyphen - In CEL, JavaScript, and JQ, quote them: actions["get-user-email"] (or .actions["get-user-email"] in JQ).

For the full state object, see Referencing a Workflow state in a block.

Core blocks

Branch (`CONDITIONAL_BRANCH`)

Cortex evaluates the paths in order and takes the first one whose expression returns true. If none do, it takes the fallback path. See Branch for how paths work.

Field	Type	Required	Description
`branches`	array of objects	Yes	The conditional paths, evaluated in order. See the path fields below.
`fallbackBranch`	object	No	The path to take if no other path returns `true`.
`joiningAction`	string	No	The slug of the block where the paths join again. Leave it out if the paths don’t join. When set, the slug must also be in this block’s `outgoingActions`.

Each path in branches takes the following fields. fallbackBranch takes the same fields except expression, and its type is FALLBACK.

Field	Type	Required	Description
`type`	string	Yes	`CONDITIONAL` for paths in `branches`, `FALLBACK` for `fallbackBranch`.
`name`	string	Yes	The display name of the path.
`slug`	string	Yes	The path’s identifier. It must be unique within the block.
`expression`	string	Yes (`CONDITIONAL` only)	A CEL expression that can read `context`, `actions`, and `variables`, such as `variables.count > 0`.
`outgoingAction`	string	No	The slug of the first block in this path.

Outputs: actions.<slug>.outputs.conditions.<path-slug>.result

- name: Check environment
  slug: check-environment
  isRootAction: false
  outgoingActions:
  - deploy-production
  - deploy-staging
  schema:
    type: CONDITIONAL_BRANCH
    branches:
    - type: CONDITIONAL
      name: Production
      slug: production
      expression: actions["user-input"].outputs.environment == "prod"
      outgoingAction: deploy-production
    fallbackBranch:
      type: FALLBACK
      name: Everything else
      slug: everything-else
      outgoingAction: deploy-staging

Data transformation (`JQ`)

Field	Type	Required	Description
`expression`	string	Yes	A jq expression. Its input has the keys `context`, `actions`, and `variables`, such as `.context.initiatedBy.email`.

Outputs: actions.<slug>.outputs.result

schema:
  type: JQ
  expression: .context.initiatedBy | tojson

HTTP request (`HTTP_REQUEST`)

Field	Type	Required	Description
`httpMethod`	string	Yes	One of `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
`url`	string	Yes	The request URL. Supports templates. When `integration` is set, enter a path relative to the integration’s base URL.
`headers`	object	Yes	A map of header names to values. Use `{}` for no headers. Supports templates.
`payload`	string	No	The request body. Supports templates.
`integration`	string	No	A configured integration to authenticate the request with, such as `GitHub`, `Jira`, or `Cortex`. See Authenticating HTTP requests with an integration.
`integrationAlias`	string	No	The integration configuration to use when the integration has more than one.
`targetHost`	string	No	Only for the `Google` integration: the `*.googleapis.com` host to call. Defaults to `cloudresourcemanager.googleapis.com`. Cortex rejects this field with any other integration.

Outputs: actions.<slug>.outputs.status, actions.<slug>.outputs.headers, actions.<slug>.outputs.body

schema:
  type: HTTP_REQUEST
  httpMethod: POST
  url: https://api.example.com/v1/environments
  headers:
    Content-Type: application/json
    Authorization: "Bearer {{context.secrets.example-token}}"
  payload: '{"name": "{{actions.user-input.outputs.env-name}}"}'

Asynchronous HTTP request (`HTTP_REQUEST_ASYNC`)

This block takes all of the HTTP request fields, plus a timeout. The Workflow pauses until the external system calls the callback URL (available as {{callbackUrl}}) or the timeout expires. See Asynchronous HTTP request for the callback format.

Field	Type	Required	Description
`timeoutInSeconds`	integer	No	How long to wait for the callback, in seconds.

schema:
  type: HTTP_REQUEST_ASYNC
  httpMethod: POST
  url: https://ci.example.com/pipelines/provision
  headers:
    Content-Type: application/json
  payload: '{"callback": "{{callbackUrl}}"}'
  timeoutInSeconds: 3600

JavaScript (`JAVASCRIPT`)

Field	Type	Required	Description
`script`	string	Yes	The script to run. It runs as the body of `run(actions, context, variables)` and must end with a `return` statement.

Outputs: actions.<slug>.outputs.result, plus any top-level keys of the returned object.

schema:
  type: JAVASCRIPT
  script: |
    const email = context.initiatedBy.email;
    return { username: email.split("@")[0] };

Manual approval (`MANUAL_APPROVAL`)

Field	Type	Required	Description
`approvingTeamIds`	array of strings	Yes	The Cortex IDs (CIDs) of the teams whose members can approve, not team tags. Can be `[]` when `approvingTeamIdsOverride` is set.
`approvingTeamIdsOverride`	string	No	A dot path that resolves the approving teams at run time, such as `variables.approvers` or `actions.user-input.outputs.team`. The value at the path must be an array of team Cortex IDs or team tags. Don’t wrap it in template braces.
`approverDescription`	string	No	A message shown to approvers. Supports templates.

schema:
  type: MANUAL_APPROVAL
  approvingTeamIds: []
  approvingTeamIdsOverride: variables.approvers
  approverDescription: "Approve the new environment for {{actions.user-input.outputs.env-name}}"

Run Workflow (`RUN_WORKFLOW`)

Field	Type	Required	Description
`workflowId`	string	Yes	The child Workflow to run.
`entityId`	string	No	The entity to run the child Workflow against.
`inputs`	object	Yes	Values for the child Workflow’s variables, keyed by variable slug. The child reads each value as `{{variables.<slug>}}`. Values keep the variable’s type and can use templates. Use `{}` if there are no inputs.
`waitForCompletion`	boolean	Yes	Whether to wait for the child run to finish before continuing. Cortex uses `false` if you leave it out.
`timeoutInSeconds`	integer	No	How long to wait for the child run, in seconds. When it expires, Cortex cancels the child run. Only used with `waitForCompletion`.

Outputs: actions.<slug>.outputs.runId. With waitForCompletion: true, also status, runResponse, and variables. See Run Workflow.

schema:
  type: RUN_WORKFLOW
  workflowId: approval-workflow
  waitForCompletion: true
  timeoutInSeconds: 86400
  inputs:
    app-id: "{{actions.form.outputs.appId}}"
    count: 5

Scaffolder (`SCAFFOLDER`)

Field	Type	Required	Description
`scaffolderTemplateTag`	string	One of these two	The tag of the Scaffolder template. If both fields are set, Cortex uses this one, which keeps definitions portable across workspaces.
`scaffolderTemplateId`	string	One of these two	The template’s tag or Cortex ID. In responses, this is always the Cortex ID, or `null` if the template was deleted.
`createNewRepository`	boolean	No	Whether to create a new repository. Defaults to `true`. Set it to `false` to open a pull request against an existing repository.
`createService`	boolean	No	Whether to create the entity in Cortex.
`inputOverrides`	array of objects	Yes	Values that override template fields. See Input overrides. Use `[]` for none.

schema:
  type: SCAFFOLDER
  scaffolderTemplateTag: java-service
  createNewRepository: true
  createService: true
  inputOverrides:
  - type: VALUE
    inputKey: project_name
    outputVariable: context.entity.tag
    editable: false

Set variable(s) (`SET_VARIABLES`)

The variables must be declared in the Workflow’s variables list (see Configuring Workflow settings).

Field	Type	Required	Description
`variables`	array of objects	Yes	The variables to set. Each item has a `slug` (the variable’s slug) and a `source`.
`variables[].source.type`	string	Yes	`REFERENCE` to read a value from a path, or `JAVASCRIPT` to compute it with a script.
`variables[].source.path`	string	For `REFERENCE`	A dot path into the run data, such as `actions.fetch.outputs.body`.
`variables[].source.script`	string	For `JAVASCRIPT`	A script that returns the value. It runs as the body of `run(actions, context, variables)`.

schema:
  type: SET_VARIABLES
  variables:
  - slug: approved
    source:
      type: REFERENCE
      path: actions.run-approval.outputs.variables.approved
  - slug: retry-count
    source:
      type: JAVASCRIPT
      script: return (variables["retry-count"] ?? 0) + 1;

User input (`USER_INPUT`)

Field	Type	Required	Description
`inputs`	array of objects	Yes	The fields to show the user. See User input field types.
`inputOverrides`	array of objects	Yes	Values that override or prefill fields. See Input overrides. Use `[]` for none.
`jsValidatorScript`	string	No	JavaScript that validates the response. See Adding validation logic.

Outputs: actions.<slug>.outputs.<key> for each field.

schema:
  type: USER_INPUT
  inputs:
  - type: INPUT_FIELD
    name: Service name
    key: service-name
    required: true
    validationRegex: ^[a-z][a-z0-9-]+$
  - type: SELECT_FIELD
    name: Environment
    key: environment
    required: true
    options: [dev, staging, prod]
    optionsLabels: [Development, Staging, Production]
    allowAdditionalOptions: false
  inputOverrides: []
  jsValidatorScript: ""

User input field types

Every field takes these common keys:

Field	Type	Required	Description
`type`	string	Yes	The field type. See the table below.
`name`	string	Yes	The label shown to the user.
`key`	string	Yes	The output key. It must be unique within the block.
`required`	boolean	Yes	Whether the user must provide a value.
`description`	string	No	Help text shown with the field. Supports templates.

Each type also takes the keys below. Keys in bold are required.

UI type	`type`	Additional keys
Text	`INPUT_FIELD`	`defaultValue` (string), `placeholder`, `validationRegex`
Paragraph	`TEXTAREA_FIELD`	`defaultValue` (string), `placeholder`, `validationRegex`
Secret	`SECRET_FIELD`	`disabled`, `placeholder`, `validationRegex`
Toggle	`TOGGLE_FIELD`	`defaultValue` (boolean)
Number	`NUMBER_FIELD`	`format` (`INTEGER` or `DECIMAL`), `disabled`, `min`, `max`, `defaultValue` (number), `placeholder`
Date	`DATE_FIELD`	`format` (`DATE` or `DATETIME`), `disabled`, `defaultValue` (string), `placeholder`
Select, manual options	`SELECT_FIELD`	`options` (array of strings), `allowAdditionalOptions`, `optionsLabels`, `defaultValue` (string), `placeholder`
Select, manual options with Allow multiple	`MULTISELECT_FIELD`	`options` (array of strings), `allowAdditionalOptions`, `optionsLabels`, `defaultValue` (array of strings), `placeholder`
Select, Cortex entity	`CORTEX_ENTITY_FIELD`	`entityFilter`, `allowMultiple`, `limitEntitiesToRunnerUserScope`, `shouldDisplayOptionsAsHierarchy`, `defaultValue` (array of strings), `placeholder`
Select, Cortex user	`CORTEX_USER_FIELD`	`filter`, `allowMultiple`, `defaultValue` (array of `{name, email}` objects), `placeholder`
Select, Slack channels	`SLACK_FIELD`	`filter` (object with `channels`), `allowMultiple`, `defaultValue` (array of strings), `placeholder`
Nested form	`NESTED_FORM_FIELD`	See Nested form fields.

Notes on these keys:

If you leave out a required boolean (disabled, allowMultiple, allowAdditionalOptions, limitEntitiesToRunnerUserScope, or shouldDisplayOptionsAsHierarchy), Cortex uses false. If you leave out format, Cortex uses DECIMAL for numbers and DATE for dates.
optionsLabels sets display labels in the same order as options. If you leave it out, Cortex shows the option values.
entityFilter accepts typeFilter ({types: [service, team]}), groupTags, excludedGroupTags, teamIds, domainIds, and emailOwners. Use {} to allow all entities.
For CORTEX_USER_FIELD, filter accepts teamCids and userEmails. Use {} to allow all users.

- type: CORTEX_ENTITY_FIELD
  name: Service
  key: service
  required: true
  allowMultiple: false
  limitEntitiesToRunnerUserScope: true
  shouldDisplayOptionsAsHierarchy: false
  entityFilter:
    typeFilter:
      types: [service]

Nested form fields

A NESTED_FORM_FIELD lets the user enter a list of items. It takes the common keys, plus:

Field	Type	Required	Description
`itemType`	string	No	`OBJECT` (the default) for items with several sub-fields, or `STRING`, `INTEGER`, `DECIMAL`, or `BOOLEAN` for single values. For single values, Cortex derives this from `element`.
`inputs`	array of objects	For `OBJECT`	The sub-fields for each item. Uses the same field types as `inputs` on the block, up to five levels of nesting.
`inputOverrides`	array of objects	For `OBJECT`	Overrides for the sub-fields. Use `[]` for none.
`element`	object	For single values	One field definition that describes every item. Its `type` must be `INPUT_FIELD`, `TEXTAREA_FIELD`, `DATE_FIELD`, `NUMBER_FIELD`, or `TOGGLE_FIELD`.
`min`	number	No	The minimum number of items. It also sets how many items appear by default. Defaults to 1.
`max`	number	No	The maximum number of items.
`disabled`	boolean	No	Whether the field is disabled.

Outputs: an array of objects for OBJECT (for example, [{"name": "db-1", "size": 100}]), or a flat array for single values (for example, [8080, 8443]).

- type: NESTED_FORM_FIELD
  name: Databases
  key: databases
  required: true
  itemType: OBJECT
  min: 1
  max: 5
  inputs:
  - type: INPUT_FIELD
    name: Name
    key: name
    required: true
  - type: NUMBER_FIELD
    name: Size (GB)
    key: size
    required: true
    format: INTEGER
    disabled: false
  inputOverrides: []

For a single-value example, see Workflows as code.

Input overrides

inputOverrides on User input and Scaffolder blocks fill a field from a value earlier in the run.

Field	Type	Required	Description
`type`	string	Yes	`VALUE` sets the field’s value. `OPTION` sets the options the user can choose from.
`inputKey`	string	Yes	The key of the field to override.
`outputVariable`	string	Yes	A dot path to the value, such as `actions.lookup.outputs.result` or `variables.team-tags`.
`editable`	boolean	Yes (`VALUE` only)	Whether the user can edit the value before continuing. When `true`, the Workflow pauses for the user. Cortex uses `false` if you leave it out.

Integration blocks

Most prebuilt integration blocks use the ADVANCED_HTTP_REQUEST type and identify the action with actionIdentifier. Each action has its own set of inputs, so the easiest way to get the identifier and input keys is to add the block in the UI and export the Workflow YAML.

`type`	Fields
`ADVANCED_HTTP_REQUEST`	`actionIdentifier` (string, required, such as `googleCloud.getProject`), `inputs` (object, required, keyed by input), `integrationAlias` (required when the integration has more than one configuration)
`AWS`	`actionIdentifier` (string, required, such as `aws.ec2.describeInstances`), `inputs` (object, required), `accountId` (string, required, supports templates), `region` (string, required, such as `us-east-1`, supports templates)
`SLACK`	`channel` (required, the channel name without `#`), `message` (required)
`MS_TEAMS_SEND_MESSAGE`	`teamId`, `channelId`, `message` (all required)
`PAGERDUTY_CREATE_INCIDENT`	`serviceId`, `title`, `body`, `fromEmail`, `urgency` (`HIGH` or `LOW`), all required; `incidentTypeName`
`GITHUB_CREATE_OR_UPDATE_FILE`	`alias`, `repositoryName`, `path`, `content` (not base64-encoded), `commitMessage`, all required; `branch` (defaults to the default branch), `committer` and `author` (each `{name, email}`)
`JIRA_CREATE_ISSUE`	`alias`, `projectKey`, `issueSummary`, `issueType`, `description`, `labels`, `components`, and `fields`, all required (use `[]` or `{}` for none); `assignee`, `reporter`, `priority`

schema:
  type: ADVANCED_HTTP_REQUEST
  actionIdentifier: googleCloud.getProject
  integrationAlias: production
  inputs:
    projectId: "{{actions.user-input.outputs.project-id}}"

Validating a definition

Before you save, you can check a definition with the Validates YAML descriptor endpoint. It reports missing required fields, slugs that aren’t unique, and broken references between blocks.

Cortex

Get Started

Connect data

Standardize

Improve

Streamline

Configure

Resources

Workflow block configuration reference

How a block appears in a Workflow definition

Referencing run data in block fields

Core blocks

Branch (`CONDITIONAL_BRANCH`)

Data transformation (`JQ`)

HTTP request (`HTTP_REQUEST`)

Asynchronous HTTP request (`HTTP_REQUEST_ASYNC`)

JavaScript (`JAVASCRIPT`)

Manual approval (`MANUAL_APPROVAL`)

Run Workflow (`RUN_WORKFLOW`)

Scaffolder (`SCAFFOLDER`)

Set variable(s) (`SET_VARIABLES`)

User input (`USER_INPUT`)

User input field types

Nested form fields

Input overrides

Integration blocks

Validating a definition

​How a block appears in a Workflow definition

​Referencing run data in block fields

​Core blocks

​Branch (CONDITIONAL_BRANCH)

​Data transformation (JQ)

​HTTP request (HTTP_REQUEST)

​Asynchronous HTTP request (HTTP_REQUEST_ASYNC)

​JavaScript (JAVASCRIPT)

​Manual approval (MANUAL_APPROVAL)

​Run Workflow (RUN_WORKFLOW)

​Scaffolder (SCAFFOLDER)

​Set variable(s) (SET_VARIABLES)

​User input (USER_INPUT)

​User input field types

​Nested form fields

​Input overrides

​Integration blocks

​Validating a definition

How a block appears in a Workflow definition

Referencing run data in block fields

Core blocks

Branch (`CONDITIONAL_BRANCH`)

Data transformation (`JQ`)

HTTP request (`HTTP_REQUEST`)

Asynchronous HTTP request (`HTTP_REQUEST_ASYNC`)

JavaScript (`JAVASCRIPT`)

Manual approval (`MANUAL_APPROVAL`)

Run Workflow (`RUN_WORKFLOW`)

Scaffolder (`SCAFFOLDER`)

Set variable(s) (`SET_VARIABLES`)

User input (`USER_INPUT`)

User input field types

Nested form fields

Input overrides

Integration blocks

Validating a definition