Use dynamic variables in your workflow document

You can use dynamic variables in your workflow documents to represent values that vary at runtime for your image creation process. String interpolation for dynamic variables allows you to embed JSONPath expressions within structured content such as JSON strings.This is particularly useful when you need to pass runtime values within complex payloads to step actions like ExecuteStateMachine or WaitForAction.

To use string interpolation for dynamic variables, wrap JSONPath expressions in double curly braces "{{...}}" within your string content. Only JSONPath expressions wrapped in double curly braces are processed as variables. Any JSONPath expressions not wrapped in double curly braces are treated as literal string content.

JSONPath dynamic workflow variable syntax

$.<document structure>.[<step name>.]<variable name>

Dynamic variable values are represented as JSONPath selectors with structural nodes that uniquely identify the target variable. The first node after the root ($) refers to the workflow document structure, such as stepOutputs, or in the case of Image Builder system variables, imageBuilder. The following list contains supported JSONPath workflow document structure nodes.

The parameters and stepOutputs document structure nodes include an optional node for the step name. This helps ensure unique variable names across all of the steps.

The final node in the JSONPath is the name of the target variable, such as instanceId.

Each step can refer to the output of any prior step actions with these JSONPath dynamic variables. This is also known as chaining, or referencing. To refer to output from a prior step action, you might use the following dynamic variable.

$.stepOutputs.step-name.output-name

Example 1: Input parameter chaining indicator

The following example shows an input parameter that uses string interpolation to resolve a dynamic variable in the parameter value at runtime.

  - name: ApplyTestComponents
    action: ExecuteComponents
    onFailure: Abort
    inputs:
      instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"

Example 2: String interpolation in dynamic variables

The following example demonstrates how dynamic variables use string interpolation to determine values at runtime.

- name: ValidateImageConfiguration
  action: ExecuteStateMachine
  inputs:
    stateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:ImageValidation
    input: |
      {
        "imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
        "region": "us-east-1",
        "buildDate": "{{ $.imagebuilder.dateTime }}",
        "instanceType": "{{ $.stepOutputs.LaunchStep.instanceType }}"
      }

In this example, the JSONPath expressions wrapped in double curly braces are resolved at runtime:

The literal strings like "region": "us-east-1" remain unchanged.

Use Image Builder system variables

Image Builder provides the following system variables that you can use in your workflow document: