> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/actions/template/steps.md).

# steps

Field reference for the steps section of an action's YAML definition.

{% hint style="info" %}
This page is the field-by-field reference for the `steps` section of an action's YAML definition. It is for customizing an action beyond its form. Start with [Actions → The 'steps' section](https://docs.ilert.com/integrations/actions.md#the-steps-section) for what the section does and how to edit it.
{% endhint %}

The `steps` section of an action definition. Every step whose `when` is true runs, in declaration order unless `needs` reorders it. Requests inside a step run in sequence. Strings marked ITL are rendered with the ilert template language against the outbound context, strings marked ICL are conditions in the ilert condition language.

Strings marked ITL are rendered with the ilert template language, strings marked ICL are conditions in the ilert condition language. The variables they can read are described under [Context schema](https://docs.ilert.com/integrations/actions/context.md).

```yaml
openapi: 3.1.0
info:
  title: ilert action template - steps
  version: 1.0.0
  description: >-
    The `steps` section of an action definition. Every step whose `when` is
    true runs, in declaration order unless `needs` reorders it. Requests inside
    a step run in sequence. Strings marked ITL are rendered with the ilert
    template language against the outbound context (see ../context/), strings
    marked ICL are conditions in the ilert condition language.
components:
  schemas:
    Steps:
      type: array
      description: >-
        Ordered list of steps. Step ids must be unique and `needs` must not form
        a cycle.
      items:
        $ref: '#/components/schemas/Step'

    Step:
      type: object
      required: [id]
      properties:
        id:
          type: string
          minLength: 1
          description: Unique step id. Later steps read this step as `steps.<id>`.
        needs:
          type: array
          default: []
          items:
            type: string
          description: >-
            Ids of steps that must have ended `OK` before this one runs. If a
            needed step ended `SKIPPED` or `ERROR`, this step is `SKIPPED`
            without evaluating `when`. Must not name the step itself or an
            undeclared step.
        when:
          type: string
          description: >-
            ICL condition. Absent or blank means true. A false condition
            records the step as `SKIPPED`.
          examples:
            - "twin == nil"
            - "twin.ref.issueId != nil and signal.type == 'alert.comment_added'"
        operation:
          $ref: '#/components/schemas/Operation'
        requests:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/Request'
          description: HTTP requests, sent in order.
        referenceWrite:
          $ref: '#/components/schemas/ReferenceWrite'
        authoredId:
          type: string
          description: >-
            ITL. Id of a sub-object this step created in the target system, for
            example a comment. It is recorded on the twin so the matching
            callback is recognized by `inbound.echoBy` and dropped. Rendered
            with `last` set to the step's final response.
          examples:
            - "{{ last.body.id }}"

    Operation:
      type: string
      enum: [CREATE, UPDATE, NOOP]
      default: NOOP
      description: >-
        Label for the twin lifecycle, not a dispatch branch. A `CREATE` step
        must set `referenceWrite.externalId`; no other operation may set it.

    Request:
      type: object
      required: [id, method, url]
      properties:
        id:
          type: string
          minLength: 1
          description: >-
            Unique within the step. Later requests of the same step read the
            response as `responses.<id>`.
        method:
          $ref: '#/components/schemas/HttpMethod'
        url:
          type: string
          description: >-
            ITL. May start with `{{ credential.hostUrl }}`, which is the only
            place (besides `referenceWrite.externalUrl` and inbound reads) where
            the connector's base URL may be used.
          examples:
            - "{{ credential.hostUrl }}/rest/api/2/issue/{{ twin.ref.issueId }}"
        headers:
          type: object
          default: {}
          additionalProperties:
            type: string
          description: >-
            Header name to ITL value. Never add authentication headers: the
            connector's secret is added when the request is sent. A
            `User-Agent` is added unless set here.
        body:
          type: string
          description: ITL. Usually JSON; set a matching `Content-Type` header.
        expect:
          $ref: '#/components/schemas/Expect'
        retry:
          $ref: '#/components/schemas/Retry'
        applyFieldMapping:
          type: boolean
          default: false
          description: Apply the action's field mapping to this request's JSON body.
        resolveFrom:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/BodyResolver'
          description: >-
            Template-only. Requires `applyFieldMapping: true`. Replaces a mapped
            value with one looked up in an earlier response.

    HttpMethod:
      type: string
      enum: [GET, POST, PUT, PATCH, DELETE, HEAD]

    Retry:
      type: string
      enum: [AUTO, SAFE, NEVER]
      description: >-
        Absent means `AUTO`: retried when the method is safe to repeat (GET,
        PUT, DELETE, HEAD). `SAFE` declares the request safe to repeat whatever
        its method. `NEVER` sends it at most once.

    Expect:
      type: object
      properties:
        successStatus:
          type: array
          default: []
          items:
            type: integer
            minimum: 100
            maximum: 599
          description: Status codes that count as success. Empty means any 2xx.
        condition:
          type: string
          description: >-
            ICL over the response that just arrived (`last`). Must hold in
            addition to the status check. A failing condition is not retried.
          examples:
            - "last.body.ok == true"

    ReferenceWrite:
      type: object
      description: >-
        Writes the twin when the step completes, rendered with `last` set to
        the step's final response. Requires the action to have an external
        system (a branded template).
      properties:
        externalId:
          type: string
          description: >-
            ITL. Id of the created object in the target system. Required on a
            `CREATE` step, forbidden on any other. Inbound callbacks are matched
            against it.
          examples:
            - "{{ last.body.id }}"
        externalUrl:
          type: string
          description: ITL. Link to the object. May start with `{{ credential.hostUrl }}`.
          examples:
            - "{{ credential.hostUrl }}/browse/{{ last.body.key }}"
        ref:
          type: object
          default: {}
          additionalProperties:
            type: string
          description: Name to ITL value. Stored on the twin and read later as `twin.ref.<name>`.

    BodyResolver:
      type: object
      required: [externalField, itemsPath, matchField, valueField]
      description: >-
        Looks up the mapped value of `externalField` in a list from an earlier
        response and replaces it with the matching element's `valueField`. If
        nothing matches, the request is not sent and the step still ends `OK`.
      properties:
        externalField:
          type: string
          description: Dotted path in the request body.
          examples: [transition.id]
        itemsPath:
          type: string
          description: JSONPath rooted at `responses` (or `steps`) of an earlier request in this step.
          examples: [$.responses.getTransitions.body.transitions]
        matchField:
          type: string
          description: Dotted path inside each element compared with the mapped value.
          examples: [to.name]
        valueField:
          type: string
          description: Dotted path inside the matched element whose value is written.
          examples: [id]
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ilert.com/integrations/actions/template/steps.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
