Invoking Other AWS Services from a
Systems Manager Automation Workflow

You can invoke other AWS services and other Systems Manager capabilities in your Automation
workflow by using the following Automation actions in your Automation documents.

aws:executeAwsApi: This Automation action
calls and executes AWS API actions. Most API actions are supported, although
not all API actions have been tested. For example, the following API actions
are supported: CreateImage, Delete bucket, RebootDBInstance,
and CreateGroups, to
name a few. Streaming API actions, such as the Get Object action, aren't
supported.

aws:waitForAwsResourceProperty: This
Automation action enables your workflow to wait for a specific resource
state or event state before continuing the workflow. For example, you can
use this action with the Amazon Relational Database Service (Amazon RDS) DescribeDBInstances API action to pause an Automation workflow
so that a database instance has time to start.

aws:assertAwsResourceProperty: This
Automation action enables you to assert a specific resource state or event
state for a specific Automation step. For example, you can specify that an
Automation step must wait for an Amazon EC2 instance to start. Then it will call
the Amazon EC2 DescribeInstanceStatus API action with the DesiredValue
property of running. This ensures that the Automation workflow
waits for a running instance and then continues when the instance is, in
fact, running.

Here is a sample Automation document in YAML that uses the aws:executeAwsApi
action to disable read and write permissions on an Amazon S3 bucket.

Here is a sample Automation document in YAML that uses all three actions. The
document does the following:

Uses the aws:executeAwsApi action to call the Amazon EC2 DescribeImages API
action to get the name of a specific Windows Server 2016 AMI. It outputs the
image ID as ImageId.

Uses the aws:executeAwsApi action to call the Amazon EC2 RunInstances API
action to launch one instance that uses the ImageId from the
previous step. It outputs the instance ID as InstanceId.

Uses the aws:waitForAwsResourceProperty action to poll the Amazon EC2
DescribeInstanceStatus API action to wait for the instance to reach the
running state. The action times out in 60 seconds. The step
times out if the instance state failed to reach running after
60 seconds of polling.

Uses the aws:assertAwsResourceProperty action to call the Amazon EC2
DescribeInstanceStatus API action to assert that the instance is in the
running state. The step fails if the instance state is not
running.

Working with Inputs
and Outputs

Each of the previously described Automation actions enables you to call a
specific API action by specifying the service namespace, the API action name,
the input parameters, and the output parameters. Inputs are defined by the API
action that you choose. You can view the API actions (also called methods) by
choosing a service in the left navigation on the following Services Reference page. Choose a method in the
Client section for the service that you want to invoke.
For example, all API actions (methods) for Amazon Relational Database Service (Amazon
RDS) are listed on the
following page: Amazon RDS methods.

You can view the schema for each Automation action in the following
locations:

The schemas include descriptions of the required fields for using each
action.

Using the Selector/PropertySelector Fields

Each Automation action requires that you specify either an output
Selector (for aws:executeAwsApi) or a
PropertySelector (for aws:assertAwsResourceProperty and
aws:waitForAwsResourceProperty). These fields are used to process the JSON
response from an AWS API action. These fields use the JSONPath
syntax.

Here is an example to help illustrate this concept for the
aws:executeAwsAPi action:

In the aws:executeAwsApi step getImageId, the
workflow invokes the DescribeImages API action and receives a
response from ec2. The workflow then applies Selector -
"$.Images[0].ImageId" to the API response and assigns the selected
value to the output ImageId variable. Other steps in the same
Automation workflow can use the value of ImageId by specifying
"{{ getImageId.ImageId }}".

Here is an example to help illustrate this concept for the
aws:waitForAwsResourceProperty action:

In the aws:waitForAwsResourceProperty step
waitUntilInstanceStateRunning, the workflow invokes the
DescribeInstanceStatus API action and receives a response from
ec2. The workflow then applies PropertySelector -
"$.InstanceStatuses[0].InstanceState.Name" to the response and checks
if the specified returned value matches a value in the
DesiredValues list (in this case running). The
step repeats the process until the response returns an instance state of
running.

Using JSONPath in an
Automation Worfklow

A JSONPath expression is a string beginning with "$." that is used to select
one of more components within a JSON element. The following list includes
information about JSONPath operators that are supported by Systems Manager
Automation:

Dot-notated child (.): Use with a
JSON object. This operator selects the value of a specific key.

Deep-scan (..): Use with a JSON
element. This operator scans the JSON element level by level and selects
a list of values with the specific key. Note that the return type of
this operator is always a JSON array. In the context of an Automation
step output type, the operator can be either StringList or
MapList.

Array-Index ([ ]): Use with a JSON
array. This operator gets the value of a specific index.

To better understand JSONPath operators, review the following JSON response
from the ec2 DescribeInstances API action. Below this response are
several examples that show different results by applying different JSONPath
expressions to the response from the DescribeInstances API
action.

This sample walkthrough shows you how to create and execute an Automation
document in YAML that uses all three API actions to see if an Amazon Relational Database
Service (Amazon RDS)
database instance is running. If the instance isn't running, the workflow starts
it.

To invoke an Amazon RDS API action from a Systems Manager Automation

Open a text editor and paste the following Automation document content
into the file. Specify an Automation role and the instance ID to check.
You will add the mainSteps actions later.

For the first step of the workflow, you need to determine if the
instance is already running. You can use the
aws:assertAwsResourceProperty action to determine and assert a specific
instance status. Before you can add the aws:assertAwsResourceProperty
action to the document, you must determine and specify the required
inputs. The following list describes how to determine and specify the
required inputs. You can view an example of how to enter this
information in the Automation document following the list.

Determine the namespace of the service to invoke. You can view
a list of AWS service namespaces in the AWS General
Reference. The namespace for Amazon RDS is
rds.

Determine which Amazon RDS API action enables you to view the
status of a database instance. You can view the API actions
(also called methods) on the Amazon RDS methods page.

Specify one or more request parameters for the
DescribeDBInstances API action. For example, this action uses
the DBInstanceIdentifier request parameter.

Determine one or more PropertySelectors. A PropertySelector is
a response object that is returned by the request of this API
action. For example, on the Amazon RDS methods. Choose the describe_db_instances method and scroll down to the
Response Structure section.
DBInstances is listed as a response
object. For the purposes of this walkthrough, specify
DBInstances and DBInstanceStatus
as the PropertySelectors. Remember that PropertySelectors are
entered by using JSONPath. This means that you format the
information in the Automation document like this:

PropertySelector:
"$.DBInstances[0].DBInstanceStatus".

Specify one or more DesiredValues. If you don't know the
values you want to specify, then execute the DescribeDBInstances API action to determine
possible values. For this walkthrough, specify
available and
starting.

Enter the information you collected into the Automation
document as shown in the following example.