Automation system variables - AWS Systems Manager
TerminologySupported scenariosUnsupported scenarios

AWS Systems Manager Change Manager is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see AWS Systems Manager Change Manager availability change.

Automation system variables

AWS Systems Manager Automation runbooks use the following variables. For an example of how these variables are used, view the JSON source of the AWS-UpdateWindowsAmi runbook.

To view the JSON source of the AWS-UpdateWindowsAmi runbook

  1. Open the AWS Systems Manager console at https://console.aws.amazon.com/systems-manager/.

  2. In the navigation pane, choose Documents.

  3. In the document list, use either the Search bar or the numbers to the right of the Search bar to choose the runbook AWS-UpdateWindowsAmi.

  4. Choose the Content tab.

System variables

Automation runbooks support the following system variables.

Variable Details

global:ACCOUNT_ID

The AWS account ID of the user or role in which Automation runs.

global:DATE

The date (at run time) in the format yyyy-MM-dd.

global:DATE_TIME

The date and time (at run time) in the format yyyy-MM-dd_HH.mm.ss.

global:AWS_PARTITION

The partition that the resource is in. For standard AWS Regions, the partition is aws. For resources in other partitions, the partition is aws-partitionname. For example, the partition for resources in the AWS GovCloud (US-West) Region is aws-us-gov.

global:REGION

The Region that the runbook is run in. For example, us-east-2.
Automation variables

Automation runbooks support the following automation variables.

Variable Details

automation:EXECUTION_ID

The unique identifier assigned to the current automation. For example, 1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c.

Terminology

The following terms describe how variables and parameters are resolved.

Term Definition Example

Constant ARN

A valid Amazon Resource Name (ARN) without variables.

arn:aws:iam::123456789012:role/roleName

Runbook parameter

A parameter defined at the runbook level (for example, instanceId). The parameter is used in a basic string replace. Its value is supplied at Start Execution time.

 
{ 
   "description": "Create Image Demo",
   "version": "0.3",
   "assumeRole": "Your_Automation_Assume_Role_ARN",
   "parameters":{ 
      "instanceId": { 
         "type": "String",
         "description": "Instance to create image from"
   }
}

System variable

A general variable substituted into the runbook when any part of the runbook is evaluated.

 
"activities": [ 
   { 
      "id": "copyImage",
      "activityType": "AWS-CopyImage",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": { 
         "ImageName": "{{imageName}}",
         "SourceImageId": "{{sourceImageId}}",
         "SourceRegion": "{{sourceRegion}}",
         "Encrypted": true,
         "ImageDescription": "Test CopyImage Description created on {{global:DATE}}"
      }
   }
]

Automation variable

A variable relating to the automation substituted into the runbook when any part of the runbook is evaluated.

 
{ 
   "name": "runFixedCmds",
   "action": "aws:runCommand",
   "maxAttempts": 1,
   "onFailure": "Continue",
   "inputs": { 
      "DocumentName": "AWS-RunPowerShellScript",
      "InstanceIds": [ 
         "{{LaunchInstance.InstanceIds}}"
      ],
      "Parameters": { 
         "commands": [ 
            "dir",
            "date",
            "“{{outputFormat}}” -f “left”,”right”,”{{global:DATE}}”,”{{automation:EXECUTION_ID}}”
         ]
      }
   }
}

Systems Manager Parameter

A variable defined within AWS Systems Manager Parameter Store. It can't be directly referenced in step input. Permissions might be required to access the parameter.

 

description: Launch new Windows test instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
  AutomationAssumeRole:
    type: String
    default: ''
    description: >-
      (Required) The ARN of the role that allows Automation to perform the
      actions on your behalf. If no role is specified, Systems Manager
      Automation uses your IAM permissions to run this runbook.
  LatestAmi:
    type: String
    default: >-
      {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
    description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{LatestAmi}}'
...

Supported scenarios

Scenario Comments Example

Constant ARN assumeRole at creation.

An authorization check is performed to verify that the calling user is permitted to pass the given assumeRole.

 
{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "arn:aws:iam::123456789012:role/roleName",
  "parameters": { 
  ...

Runbook parameter supplied for AssumeRole when the automation is started.

Must be defined in the parameter list of the runbook.

 
{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "{{dynamicARN}}",
  "parameters": {
 ...

Value supplied for runbook parameter at start.

Customer supplies the value to use for a parameter. Any inputs supplied at start time need to be defined in the parameter list of the runbook.

 
...
"parameters": {
    "amiId": {
      "type": "String",
      "default": "ami-12345678",
      "description": "list of commands to run as part of first step"
    },
...

Inputs to Start Automation Execution include : {"amiId" : ["ami-12345678"] }

Systems Manager Parameter referenced within runbook content.

The variable exists within the customer's account, or is a publicly accessibly parameter, and the AssumeRole for the runbook has access to the variable. A check is performed at create time to confirm the AssumeRole has access. The parameter can't be directly referenced in step input.

 

...
parameters:
    LatestAmi:
    type: String
    default: >-
      {{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
    description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{LatestAmi}}'
...

System variable referenced within step definition

A system variable is substituted into the runbook when the automation is started. The value injected into the runbook is relative to when the substitution occurs. That is, the value of a time variable injected at step 1 is different from the value injected at step 3 because of the time it takes to run the steps between. System variables don't need to be set in the parameter list of the runbook.

 
...
  "mainSteps": [
    {
      "name": "RunSomeCommands",
      "action": "aws:runCommand",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "DocumentName": "AWS:RunPowerShell",
        "InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
        "Parameters": {
            "commands" : [
                "echo {The time is now {{global:DATE_TIME}}}"
            ]
        }
    }
}, ...

Automation variable referenced within step definition.

Automation variables don't need to be set in the parameter list of the runbook. The only supported Automation variable is automation:EXECUTION_ID.

 
...
"mainSteps": [
    {
      "name": "invokeLambdaFunction",
      "action": "aws:invokeLambdaFunction",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "FunctionName": "Hello-World-LambdaFunction",

"Payload" : "{ "executionId" : "{{automation:EXECUTION_ID}}" }"
      }
    }
...

Refer to output from previous step within next step definition.

This is parameter redirection. The output of a previous step is referenced using the syntax {{stepName.OutputName}}. This syntax can't be used by the customer for runbook parameters. This is resolved when the referring step runs. The parameter isn't listed in the parameters of the runbook.

 
...
"mainSteps": [
    {
      "name": "LaunchInstance",
      "action": "aws:runInstances",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "ImageId": "{{amiId}}",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 2
      }
    },
    {
      "name":"changeState",
      "action": "aws:changeInstanceState",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
        "DesiredState": "terminated"
      }
    }

...

Unsupported scenarios

Scenario Comment Example

Systems Manager Parameter supplied for assumeRole at create

Not supported.

 
...

{
  "description": "Test all Automation resolvable parameters",
  "schemaVersion": "0.3",
  "assumeRole": "{{ssm:administratorRoleARN}}",
  "parameters": {

...

Systems Manager Parameter directly referenced in step input.

Returns InvalidDocumentContent exception at create time.

 

...
mainSteps:
  - name: launchInstance
    action: 'aws:runInstances'
    maxAttempts: 3
    timeoutSeconds: 1200
    onFailure: Abort
    inputs:
      ImageId: '{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}'
...

Variable step definition

The definition of a step in the runbook is constructed by variables.

 
...

"mainSteps": [
    {
      "name": "LaunchInstance",
      "action": "aws:runInstances",
      "{{attemptModel}}": 1,
      "onFailure": "Continue",
      "inputs": {
        "ImageId": "ami-12345678",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 2
      }

...

User supplies input : { "attemptModel" : "minAttempts" }

Cross referencing runbook parameters

The user supplies an input parameter at start time, which is a reference to another parameter in the runbook.

 
...
"parameters": {
    "amiId": {
      "type": "String",
      "default": "ami-7f2e6015",
      "description": "list of commands to run as part of first step"
    },
    "alternateAmiId": {
      "type": "String",
      "description": "The alternate AMI to try if this first fails".

"default" : "{{amiId}}"
    },

...

Multi-level expansion

The runbook defines a variable that evaluates to the name of a variable. This sits within the variable delimiters (that is {{ }}) and is expanded to the value of that variable/parameter.

 
...
  "parameters": {
    "firstParameter": {
      "type": "String",
      "default": "param2",
      "description": "The parameter to reference"
    },
    "secondParameter": {
      "type": "String",
      "default" : "echo {Hello world}",
      "description": "What to run"
    }
  },
  "mainSteps": [{
      "name": "runFixedCmds",
      "action": "aws:runCommand",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "DocumentName": "AWS-RunPowerShellScript",

"InstanceIds" : "{{LaunchInstance.InstanceIds}}",
        "Parameters": {
          "commands": [ "{{ {{firstParameter}} }}"]

}

...

Note: The customer intention here would be to run a command of "echo {Hello world}"

Referencing output from a runbook step that is a different variable type

The user references the output from a preceding runbook step within a subsequent step. The output is a variable type that doesn't meet the requirements of the action in the subsequent step.

 
...
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
    - Name: "name"
      Values: 
      - "{{ImageName}}"
  outputs:
  - Name: ImageIdList
    Selector: "$.Images"
    Type: "StringList"
- name: copyMyImages
  action: aws:copyImage
  maxAttempts: 3
  onFailure: Abort
  inputs:
    SourceImageId: {{getImageId.ImageIdList}}
    SourceRegion: ap-northeast-2
    ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2
    Encrypted: true 
... 
Note: You must provide the type required by the Automation action. 
In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.