AWS Systems Manager
User Guide

Automation System Variables

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

To view the JSON source of the AWS-UpdateWindowsAmi document

  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 document AWS-UpdateWindowsAmi.

  4. Choose the Content tab.

System Variables

Automation documents currently support the following system variables.

Variable Details

global:ACCOUNT_ID

The AWS account ID of the AWS Identity and Access Management (IAM) user or role in which Automation runs.

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 that the document is run in. For example, us-east-2.

Automation Variables

Automation documents currently support the following automation variables.

Variable Details

automation:EXECUTION_ID

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

Terminology

The following terms describe how variables and parameters are resolved.

Term Definition Example

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 Parameter Store. 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 run as part of first step" }, "instanceIds": { "type": "STRING_LIST", "description": "list of instances to run 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

Scenario Comments Example

Constant ARN assumeRole at create

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

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 run 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 customer's account and the assumeRole for the document has access to the variable. A check is 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. 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 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

Scenario Comment Example

SSM Parameter supplied for assumeRole at create

Not supported.

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

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 run 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 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": { "param1": { "type": "STRING", "default": "param2", "description": "The parameter to reference" }, "param2": { "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": [ "{{ {{param1}} }}"] } ... Note: The customer intention here would be to run a runCommand of "echo {Hello world}"

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

The user references the output from a preceding document step within a subsequent step. The output is a variable type that does not 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.