Menu
Sign In to the Console
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Automation System Variables

This section describes variable and parameter uses in Systems Manager Automation documents.

System Variables

Automation documents currently support the following system variables.

VariableDetails

global:DATE

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

global:DATE_TIME

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

global:REGION

The region which the document is executed in. For example, us-east-1.

Automation Variables

Automation documents currently support the following automation variables.

VariableDetails

automation:EXECUTION_ID

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

Terminology

This section uses the following terms to describe how variables and parameters are resolved.

TermDefinitionExample

Constant ARN

A valid ARN without variables

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

Document Parameter

A parameter defined at the document level for an Automation document (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 document when any part of the document 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 execution substituted into the document when any part of the document is evaluated.

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

SSM parameter

A variable defined within the Parameter Service. It is not declared as a Document Parameter. It may require permissions to access.

 
{ 
   "description": "Run Command Demo",
   "schemaVersion": "0.3",
   "assumeRole": "arn:aws:iam::123456789012:role/roleName",
   "parameters": { 
      "commands": { 
         "type": "STRING_LIST",
         "description": "list of commands to execute as part of first step"
      },
      "instanceIds": { 
         "type": "STRING_LIST",
         "description": "list of instances to execute commands on"
      }
   },
   "mainSteps": [ 
      { 
         "name": "runFixedCmds",
         "action": "aws:runCommand",
         "maxAttempts": 1,
         "onFailure": "Continue",
         "inputs": { 
            "DocumentName": "AWS-RunPowerShellScript",
            "InstanceIds": [ 
               "{{LaunchInstance.InstanceIds}}"
            ],
            "Parameters": { 
               "commands": [ 
                  "dir",
                  "date",
                  "echo {Hello {{ssm:administratorName}}}",
                  ""{{outputFormat}}" -f "left","right","{{global:DATE}}","{{automation:EXECUTION_ID}}","{{global:TIME}}""
               ]
            }
         }
}

Supported Scenarios

ScenarioCommentsExample

Constant ARN assumeRole at create

An authorization check will be performed to check the calling user is permitted to pass the given assume role.

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

Document Parameter supplied for assumeRole at create

Must be defined in the Parameter list of the document.

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

Value supplied for Document Parameter at start.

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

 
...
"parameters": {
    "amiId": {
      "type": "STRING",
      "default": "ami-7f2e6015",
      "description": "list of commands to execute as part of first step"
    },
...

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

SSM parameter referenced within step definition

The variable exists within the customers account and the assumeRole for the document has access to the variable. A check will be performed at create time to confirm the assumeRole has access. SSM parameters do not need to be set in the parameter list of the document.

 
...
"mainSteps": [
    {
      "name": "RunSomeCommands",
      "action": "aws:runCommand",
      "maxAttempts": 1,
      "onFailure": "Continue",
      "inputs": {
        "DocumentName": "AWS:RunPowerShell",
        "InstanceIds": [{{LaunchInstance.InstanceIds}}],
        "Parameters": {

"commands" : [

"echo {Hello {{ssm:administratorName}}}"

]

       }
      }
    },

...

System variable referenced within step definition

A system variable is substituted into the document at execution time. The value injected into the document is relative to when the substitution occurs. e.g. The value of a time variable injected at step 1 will be different to the value injected at step 3 due to the time taken to execute the steps between. System variables do not need to be set in the parameter list of the document.

 
...
  "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:TIME}}}"

]

       }
      }
    }, ...

Automation variable referenced within step definition.

Automation variables do not need to be set in the parameter list of the document. 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 cannot be used by the customer for Document Parameters. This is resolved at the time of execution for the referring step. The parameter is not listed in the parameters of the document.

 
...
"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

ScenarioCommentExample

SSM Parameter supplied for assumeRole at create

Not supported.

 
...

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

...

SSM Parameter supplied for Document Parameter at start

The user supplies an input parameter at start time which is an SSM parameter

 
...

"parameters": {
    "amiId": {
      "type": "STRING",
      "default": "ami-7f2e6015",
      "description": "list of commands to execute as part of first step"
    },

...

User supplies input : { "amiId" : "{{ssm:goldenAMIId}}" }

Variable step definition

The definition of a step in the document 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 Document Parameters

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

 
...
"parameters": {
    "amiId": {
      "type": "STRING",
      "default": "ami-7f2e6015",
      "description": "list of commands to execute as part of first step"
    },
    "otherAmiId": {
      "type": "STRING",
      "description": "The other amiId to try if this one fails".

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

...

Multi-level expansion

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

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

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

}

...

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