Workflow definition schema

Overview

A workflow definition describes the automated process to execute. Workflow definitions use YAML with a camelCase naming convention. Each workflow consists of:

• Schema properties: Basic information (name, description, and inputs)
• Steps: The sequence of actions to perform
• Expressions: Dynamic values using jq syntax
• Secrets: Secure credential references

Schema structure

Schema properties

The following table describes the top-level properties of a workflow definition.

workflowInputs (Optional)

The following example shows a workflowInputs definition:

workflowInputs:
  myInput1:
    type: String
  myInput2:
    type: Number
    defaultValue: 42

Each input entry supports the following fields:

• workflowInputs.<inputName> (Required)

  • Type: String (conforming to expression-safe pattern)
  • Min. length: 1
  • Max length: 50
  • Description: The name of the workflow input.

• workflowInputs.<inputName>.type (Required)

  • Type: Enum (Boolean, List, Map, String, Int, Float, Enum)
  • Description: The data type of the workflow input.

• workflowInputs.<inputName>.defaultValue (Optional)

  • Type: Any value conforming to type.
  • Description: The default value for the workflow input.

• workflowInputs.<inputName>.required (Optional)

  • Type: Boolean (True, False).
  • Description: The default value for this field is true.

• workflowInputs.<inputName>.enumValues (Optional)

  • Type: List (String).
  • Description: This field defaults to an empty list {}. It is required when the workflowInputs type is Enum.

• workflowInputs.<inputName>.validations (Optional)

  • Type: Array of maps.
  • Description: The validations to run on the workflow inputs the user provides. The properties listed here apply to all validation types. Specific validation types support additional properties. Refer to Validation types for details.

• validations[*].type (Required)

  • Type: String
  • Description: The type of the validation indicating what validation occurs on this field. See Validation types for more information on each validation type.

• validations[*].errorMessage (Required)

  • Type: String
  • Description: The error message to display when a particular validation fails.

Sample YAML for validations

name: calendar_demo

workflowInputs:
  timezone:
    type: String
    defaultValue: 'America/Los_Angeles'
    validations:
      - type: regex
        errorMessage: "The provided timezone is not correct"
        pattern: "^[A-Za-z]+\/[A-Za-z_]+(?:\/[A-Za-z_]+)?$"

      - type: maxLength
        errorMessage: "Timezone length should be less than 100"
        length: 100
      
  accountId:
    type: Int
    validations:
      - type: minIntValue
        errorMessage: "Account id should be greater than 100000"
        minValue: 100000
      - type: maxIntValue
        errorMessage: "Account id should be less than 9999999"
        maxValue: 9999999

steps:
  - name: getCurrentTime
    type: action
    action: http.get
    version: 1
    inputs:
      url: 'https://worldtimeapi.org/api/timezone/${{ .workflowInputs.timezone }}'
      selectors:
        - name: timezone
          expression: '.responseBody | fromjson.abbreviation'
        - name: datetime
          expression: '.responseBody | fromjson.datetime'

workflowConstants (Optional)

Workflow constants provide access to runtime metadata about the currently executing workflow. These constants are automatically available in all workflow definitions and you can reference them using the expression syntax ${{ .workflowConstants.<constantName> }}.

Available constants

The following constants are available in all workflow definitions.

Usage examples

name: testWorkflowConstantsWithJQ
 description: Test workflow to demonstrate workflowConstants usage
  steps:
    - name: logWithConstants
      type: action
      action: newrelic.ingest.sendLogs
      version: '1'
      inputs:
        logs:
          - message: Workflow Execution Started
            attributes:
              accountId: ${{ .workflowConstants.accountId }}
              orgId: ${{ .workflowConstants.organizationId }}
              version: ${{ .workflowConstants.definitionVersion }}
              scopeType: ${{ .workflowConstants.definitionScopeType }}
              startedAt: ${{ .workflowConstants.startedAt }}
              runId: ${{ .workflowConstants.runId }}
              workflowDefinitionName: ${{ .workflowConstants.definitionName }}

Use workflow constants with jq expressions to transform values:

steps:
    - name: transformConstants
      type: action
      action: newrelic.ingest.sendLogs
      version: '1'
      inputs:
        logs:
          - message: Testing JQ transformations on workflowConstants
            attributes:
              # Convert epoch milliseconds to ISO8601 format
              startedAtISO8601: ${{ (.workflowConstants.startedAt / 1000) | todateiso8601 }}
              # Convert to uppercase
              runIdUppercase: ${{ .workflowConstants.runId | ascii_upcase }}
              # Get string length
              definitionNameLength: ${{ .workflowConstants.definitionName | length }}
              # Convert to string
              accountIdString: ${{ .workflowConstants.accountId | tostring }}
              # Combine multiple constants
              combinedMetadata: ${{ .workflowConstants.definitionName + "-" + .workflowConstants.runId }}

The following example converts a timestamp using the DateTime action:

steps:
    - name: convertStartedAtFromEpoch
      type: action
      action: utils.datetime.fromEpoch
      version: 1
      inputs:
        timestamp: ${{ .workflowConstants.startedAt }}
        timezoneId: UTC
        pattern: "yyyy-MM-dd HH:mm:ss"
        timestampUnit: MILLISECONDS
        selectors:
          - name: datetime
            expression: ".datetime"
          - name: timezone
            expression: ".timezone"

Constraints and behavior

Steps

The following table describes the steps property of a workflow definition.

Common step properties

The following properties apply to all step types.

Step types

Action

A step that runs a specific action. Refer to the Action catalog for the available options.

• steps[*].action (Required)

  • Type: String
  • Description: The fully qualified name of the action function to run. It should follow this convention: <company domain>.<category of work>.<action name in camelCase>

  The following are examples of valid action names:

  • Action using New Relic services (for example, through NerdGraph): newrelic.dashboards.getDashboard
  • Action using Slack: slack.chat.postMessage

• steps[*].version (Required)

  • Type: String
  • Description: The version of the action function to run.

• steps[*].inputs (Optional)

  • Type: Map of values (includes expressions)
  • Description:
    • The inputs to pass to the action function. Each action defines the specific inputs it accepts.
    • You can use expressions. See the expression strings section for details.

  重要

  Do not pass sensitive data (API keys, secrets, PII, PHI, or any personally identifiable data) as arguments.

• steps[*].inputs.selectors (Optional)

  • Type: list of maps in the form of name with expression.

  • Description:

    • The selectors input allows you to redefine the output to only return the specified elements.
    • You can use expressions. See the Expression strings section for details.

  • The following example retrieves timezone and datetime from the http.get action output.

  name: calendar_demo
  
    workflowInputs:
      timezone:
        type: String
        defaultValue: 'America/Los_Angeles'
      accountId:
        type: Int
  
    steps:
      - name: getCurrentTime
        type: action
        action: http.get
        version: 1
        inputs:
          url: 'https://worldtimeapi.org/api/timezone/${{ .workflowInputs.timezone }}'
          selectors:
            - name: timezone
              expression: '.responseBody | fromjson.abbreviation'
            - name: datetime
              expression: '.responseBody | fromjson.datetime'

  コピー

Loop

A loop iterates over collections (lists, maps, arrays) and automatically creates index and element variables for each iteration. You can access these loop variables only within the loop using ${{ .steps.<loopStepName>.loop.element }} or ${{ .steps.<loopStepName>.loop.index }}.

The loop step supports the following properties:

• steps[*].for (Required)

  • Type: Constant
  • Description: Signals the start of a loop.

• steps[*].in (Required)

  • Type: String (expression)
  • Description: Expression that evaluates to a collection of elements.

• steps[*].steps (Required)

  • Description: Steps to execute on each iteration. Each step can be any step type, including nested loops.

Example: Basic loop

name: myRangeIterator
steps:
  - name: looper
    type: loop
    for:
      # iterate over [1..5]
      in: ${{ [range(1; 6)] }}
      steps:
        - name: logProgress
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "Element: ${{ .steps.looper.loop.element | tostring }}" # not exist outside of this loop
                attributes:
                  # ranges over [0..4]
                  index: ${{ .steps.looper.loop.index }}

Example: Use for loop with jq expression

name: process-orders
description: Process and validate orders

workflowInputs:
  validStatuses:
    type: List
    defaultValue: ["pending", "confirmed", "shipped"]

steps:
  - name: getOrders
    type: assign
    inputs:
      orders:
        - { id: "001", status: "pending", amount: 100 }
        - { id: "002", status: "invalid", amount: 50 }
        - { id: "003", status: "shipped", amount: 200 }

  - name: processOrders
    type: loop
    for:
      in: ${{ .steps.getOrders.outputs.orders }}
      steps:
        - name: validateStatus
          type: switch
          switch:
            - condition: ${{ .steps.processOrders.loop.element.status as $status | .workflowInputs.validStatuses | index($status) != null }}
              next: validOrder
          next: invalidOrder

        - name: invalidOrder
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "Invalid order status"
                attributes:
                  orderId: ${{ .steps.processOrders.loop.element.id }}
                  status: ${{ .steps.processOrders.loop.element.status }}

        - name: validOrder
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "Processing valid order"
                attributes:
                  orderId: ${{ .steps.processOrders.loop.element.id }}
                  status: ${{ .steps.processOrders.loop.element.status }}
                  amount: ${{ .steps.processOrders.loop.element.amount }}

Example: Loop on map

name: myMapIterator
steps:
  - name: looper
    type: loop
    for:
      in: '${{ [ {"key1": "val1"}, {"key2": "val2"} ] }}'
      steps:
        - name: logProgress
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "Element: ${{ .steps.looper.loop.element | tostring }}"

Example: Jump within a loop

You can jump between steps within the same loop. You cannot jump into or out of loops, between different loops, or to parent/child loops.

name: myLoopJump
steps:
  - name: fistStep
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "the first step"
  - name: loopStep
    type: loop
    for:
      in: ${{ [range(1; 6)] }}
      steps:
        - name: loopStep1
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop first step"
          next: loopStep3                         # Okay within the loop
        - name: loopStep2
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop second step, never executed"
        - name: loopStep3
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop third step"
          next: fistStep                        # Not okay, first step is not in the loop context

Example: Break and continue

Use next: break or next: continue to control loop flow. These are reserved keywords within loops. Outside loops, they jump to the workflow end. Inside a loop, end behaves like break.

name: myLoopContinueBreak
steps:
  - name: fistStep
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "the first step"
  - name: loopStep
    type: loop
    for:
      in: ${{ [range(1; 6)] }}
      steps:
        - name: loopStep1
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop first step"
          # continue with next iteration without executing loopStep2
          next: continue
        - name: loopStep2
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop second step, never executed"

  - name: loopAgain
    type: loop
    for:
      in: ${{ [range(1; 6)] }}
      steps:
        - name: loopAgainStep1
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop again first step"
          # stop iterating and continue with next step after the loop
          next: break
        - name: loopAgainStep2
          type: action
          action: newrelic.ingest.sendLogs
          version: 1
          inputs:
            logs:
              - message: "the loop again second step, never executed"

  - name: lastStep
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "the last step"

Switch

A switch step checks various conditionals and takes the first branch that evaluates to true. It can contain any number of condition elements in a list, checking them in order and processing the first one that evaluates to true. If none evaluate to true, it runs its next step as defined in steps[*].next.

• steps[*].switch (Required)

  • Type: Array
  • Description: An array of switch cases, specifying the ordered list of conditions to evaluate.

• steps[*].switch[*].condition (Required)

  • Type: String (expression)
  • Description: The condition of the switch case. If the condition evaluates to true, the workflow executes the case's next step.
  • See the Expression strings section for details.

• steps[*].switch[*].next (Required)

  • Type: String (conforming to expression-safe pattern)
  • Description: The name of the step to run if the case's condition evaluates to true. The special keyword end indicates this is the last step to run.

  - name: hasCompleted
      type: switch
      switch:
        - condition: ${{ .steps.waitForCompletion.outputs.automationExecutionStatus == "Failed" }}
          next: displayError
        - condition: ${{ .steps.waitForCompletion.outputs.automationExecutionStatus == "Success" }}
          next: displaySuccess
      next: displayUnexpected

  コピー

Wait

A step that pauses workflow execution for a specified number of seconds before continuing.

The wait step can also listen for one or more signals. Each signal must define a corresponding next step. If the wait step receives a signal, it processes the first one received and executes its defined next step. If no signal is received, the workflow continues to the next step after the wait period ends.

The wait step stores the received signal value in its output, making it available for use in subsequent steps.

The following example shows a wait step with a signal handler:

name: waitSignalExample
steps:
  - name: waitStep
    type: wait
    seconds: 300
    signals: [{name: 'mySignal', next: 'mySignalHandler'}]
  - name: endStep
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "didn't get signal"
    next: end
  - name: mySignalHandler
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        # log entry "got signal with data bar" when using signalInputs [{"foo": "bar"}]
        - message: "got signal with data ${{ .steps.waitStep.outputs.signalInputs.foo }}"

The wait step accepts the following properties:

• steps[*].seconds (Required)

  • Type: Number
  • Description: The number of seconds to wait before continuing the workflow run.

• steps[*].signals

  • Type: Array
  • Description: The signals that divert program flow when the wait step receives them.

• steps[*].signals[*].name

  • Type: String
  • Description: The name of the signal to listen for.

• steps[*].signals[*].next

  • Type: String
  • Description: The step to execute if the specified signal is received.

Assign

A step that defines variables for use throughout the workflow. This step assigns values to variables that subsequent steps can reference. This step type lets you define all variables in one place for use throughout the workflow.

The following sample workflow shows how to use the assign step:

name: sampleWorkflowWithAssign

workflowInputs:
  initialValue:
    type: String
    defaultValue: "abcd"
  anotherValue:
    type: Int
    defaultValue: 1234

steps:
  - name: variableInitialization
    type: assign
    inputs:
      stringVar: "${{ .workflowInputs.initialValue }}"
      intVar: "${{ .workflowInputs.anotherValue }}"
      concatenationVar: "${{ .workflowInputs.initialValue }} - concatenated"
      booleanVar: true
      mapVar:
        key1: "value1"
        key2: "${{ .workflowInputs.initialValue }}"
      listVar:
        - "listItem1"
        - "${{ .workflowInputs.initialValue }}"
        - "${{ .workflowInputs.anotherValue }}"

  - name: logVariables
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "stringVar: ${{ .steps.variableInitialization.outputs.stringVar }}"
        - message: "intVar: ${{ .steps.variableInitialization.outputs.intVar }}"
        - message: "concatenationVar: ${{ .steps.variableInitialization.outputs.concatenationVar }}"
        - message: "booleanVar: ${{ .steps.variableInitialization.outputs.booleanVar }}"
        - message: "mapVar: ${{ .steps.variableInitialization.outputs.mapVar | tojson }}"
        - message: "listVar: ${{ .steps.variableInitialization.outputs.listVar | tojson }}"

The assign step accepts the following input:

• steps[*].inputs (Required)
  • Type: Map of values (includes expressions)
  • Description:
    • The inputs are a map of variable names and their assigned values. When you assign secret references to variables, they remain as references and the system doesn't convert them to their actual values. However, the workflow evaluates and converts other expressions (such as workflow inputs) to their actual values.
  • Allowed input types: Integer, Double, Boolean, String, Array, Map

State

A step that stores key/value pairs in the workflow's shared state. Values persist for the duration of the workflow run. Subsequent steps can access these values using the .workflowState accessor. If multiple state steps set the same key, each later value overwrites the earlier one.

The state step accepts the following input:

• steps[*].inputs (Required)
  • Type: Map of key/value pairs
  • Description: The key/value pairs to store in the workflow state.
    • Keys must be valid identifiers.
    • Values can be any type — String, Integer, Boolean, List, or Map (including nested structures). Values include expressions. The runtime doesn't resolve secret references — it stores them as-is.

To access state values in expressions, use .workflowState.<keyName> in any step that follows the state step:

${{ .workflowState.myKey }}

The following example shows a state step storing and retrieving values:

name: workflow-state-example
description: Store and retrieve state across steps
steps:
  - name: storeInitialData
    type: state
    inputs:
      count: 1
      foo: "bar"
  - name: updateCount
    type: state
    inputs:
      color: "green"
      count: 2
  - name: logState
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "foo=${{ .workflowState.foo }}, color=${{ .workflowState.color }}, count=${{ .workflowState.count }}"

The state step has the following constraints:

• Key name pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
• Key name max length: 255 characters
• Max keys per state step: 10
• Max total state keys per workflow run: 100
• State value max length: 1,000 characters

Error

A step that ends the workflow and reports a failure with a custom message. If a condition is present, the workflow evaluates it first and stops only when the condition is true. If you don't provide a message, the step uses the default message failed as requested from step: failureStep.

The following example shows an error step with a condition:

name: sendLogWorkflow
description: 'This workflow send Logs to newrelic'
steps:
  - name: sendLog
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: Sending Logs to NewRelic
  - name: error_4
    type: error
    condition: ${{.steps.sendLog.outputs.success == false}}
    message: Terminating Workflow as sendLog failed.
    next: end

The following table describes the inputs accepted by the error step.

Validation types

The following validation types are available for workflowInputs.

Expressions and secrets

Expression strings

Several properties accept string values with embedded expressions that the workflow evaluates during execution, enabling dynamic values in workflow definitions.

Expression strings can contain one or more expressions, each enclosed within double curly braces. jq evaluates the content within the braces, letting you access, filter, and transform values.

The following example gets the length of a workflow input string:

${{ .workflowInputs.myString | length }}

To validate and test your expressions, use the JQ Playground.

Expression properties

You can access these properties with expressions. They live in a scope object, so expressions must start with a period (.) to access those properties of the scope object.

The available properties are:

• workflowInputs — Object containing the inputs passed to the workflow on start.

  Example: ${{ .workflowInputs.myInput }}

• workflowState — Object containing key/value pairs stored by state steps during the current workflow run.

  Examples (flat key, nested property, array index): ${{ .workflowState.myKey }} · ${{ .workflowState.myMap.nestedProperty }} · ${{ .workflowState.myList[0] }}

• steps — Object containing a property for each step in the workflow.

  • steps.<stepName> — Object containing properties for a specific step.
  • steps.<stepName>.outputs — Object containing result properties, specific to the step or action.

  Example: ${{ .steps.myStep.outputs.myResult }}

Expression evaluation results

A single jq expression can evaluate to any JSON type. However, the final result of an expression string depends on whether the string contains only the expression or additional content.

Single expression (preserves JSON type)

If an expression string consists of only one expression with no surrounding content, it evaluates to the jq expression's result while maintaining its original JSON type. For example, ${{ .workflowInputs.myArray }} evaluates to an array. This preserves the type of complex data structures when passing them between steps.

Multiple expressions or mixed content (converts to string)

If an expression string contains content other than a single expression, it evaluates to a string result. This occurs when an expression has content before or after it, or when the string has multiple expressions within it. jq evaluates each expression and converts it to a string representation.

The following examples use myArray with the value [1, 2, 3].

Expression safe pattern

Properties you use in expressions must conform to: ^[A-Za-z_][A-Za-z0-9_]*$

Secret references

Use secret values in actions by providing reference strings that specify the name of a secret to look up in the Secrets Service. To reference a secret in a workflow definition, use the syntax:

• ${{ :secrets:<SECRET_NAME> }} for a secret not in a namespace

• ${{ :secrets:<NAMESPACE>:<SECRET_NAME> }} for a secret in a namespace

• ${{ :secrets:<SCOPE>:<NAMESPACE>:<SECRET_NAME> }} for a secret in a scope and namespace

  SCOPE accepts ACCOUNT or ORGANIZATION.

An expression string can contain jq expressions, secret references, or both.

The following are examples of secret references used in actions:

steps:
  - name: mySecretStep
    type: action
    action: newrelic.instrumentation.log
    inputs:
      message: My message
      licenseKey: ${{ :secrets:<SECRET_NAME> }}

steps:
    - name: bearer_auth
      type: action
      action: utils.http.post
      inputs:
        headers:
          Authorization: Bearer ${{ :secrets:<SECRET_NAME> }}

Complete example

Calendar demo

This complete workflow example demonstrates multiple workflow features, including workflow constants, selectors, wait steps, NRDB queries, and switch statements.

name: calendar_demo

steps:
  - name: getUserCreated
    type: action
    action: newrelic.nerdgraph.execute
    version: 1
    inputs:
      graphql: |
        {
          actor {
            user {
              id
              createdAt
              timeZoneName
            }
          }
        }
      selectors:
        - name: id
          expression: ".data.actor.user.id"
        - name: createdAt
          expression: ".data.actor.user.createdAt"
        - name: timeZoneName
          expression: ".data.actor.user.timeZoneName"

  - name: getCreatedTime
    type: action
    action: utils.datetime.fromEpoch
    version: 1
    inputs:
      timestamp: ${{ .steps.getUserCreated.outputs.createdAt }}
      pattern: "yyyy-MM-dd HH:mm:ss"
      timezoneId: ${{ .steps.getUserCreated.outputs.timeZoneName }}
      selectors:
        - name: datetime
          expression: ".datetime"
        - name: abbreviation
          expression: ".timezone.abbreviation"

  - name: logTime
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "Demo ${{ .workflowConstants.runId }} userId ${{ .steps.getUserCreated.outputs.id }} created at ${{ .steps.getCreatedTime.outputs.datetime }} ${{ .steps.getCreatedTime.outputs.abbreviation }}"

  - name: wait
    type: wait
    seconds: 1

  - name: queryForLog
    type: action
    action: newrelic.nrdb.query
    version: 1
    inputs:
      query: "FROM Log SELECT message, timestamp SINCE 5 minute ago WHERE message LIKE 'Demo ${{ .workflowConstants.runId }} userId ${{ .steps.getUserCreated.outputs.id }} created at%'"

  - name: checkQuery
    type: switch
    switch:
      - condition: ${{ .steps.queryForLog.outputs.results | length > 0 }}
        next: postResultsMessage

  - name: postWaitingMessage
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "Waiting for log message..."
    next: wait

  - name: postResultsMessage
    type: action
    action: newrelic.ingest.sendLogs
    version: 1
    inputs:
      logs:
        - message: "Found log message! ${{ .steps.queryForLog.outputs.results[0].message }}"

Related topics