Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Version Information

Template Name	Extension Name	Extension Version

Template Name	Extension Name	Extension Version
AWS Step Functions	ue-aws-stepfunctions	2.0.0

Refer to Changelog for version history information.

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area	Details

Area

Details

Python Version

Requires Python of version 3.7. Tested with the Universal Agent bundled Python distribution (python version 3.7.6).

Python Version

Both Windows and Linux agents are supported:

Universal Agent for Windows x64 Version >= 7.2.0.0
Universal Agent for Linux Version >= 7.2.0.0

Universal Controller

Universal Controller Version >= 7.2.0.0

Network and Connectivity Requirements

Extensions' Universal Agent host should be able to reach AWS Step Functions REST endpoints. The AWS Credentials provided in the Universal Task, should have sufficient permissions on AWS to execute the Step Function.

Overview

This integration allows customers to execute AWS Step Functions from Universal Controller.

Key Features

This Universal Extension provides the following key features.

Actions
- Execute a AWS Step Function and wait until is reaches status "Success" or "Failed".
- Execute a AWS Step Function asynchronously without waiting for the execution to finish.
Authentication
- Authentication using AWS Credentials
- Authorization via IAM Role-Based Access Control (RBAC) strategy.
Other
- Communication through Proxy with use of HTTP or HTTPS.

Import Universal Template

To use the Universal Template, you first must perform the following steps:

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true. For more information about Resolvable Credentials click here.
To import the Universal Template into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Configure Universal Task

For a new Universal Task, create a new task, and enter the required input fields.

Input Fields

The input fields for this Universal Extension are described below.

Field	Input type	Default value	Type	Description

Field	Input type	Default value	Type	Description
Action	Required	Start Asynchronous Execution	Choice	Action performed upon the task execution. Available actions are as follows. Start Asynchronous Execution
AWS Region	Optional	-	Text	Region for the Amazon Web Service. When AWS Region is not populated as part of the task definition, during task execution the integration will look for the region as configured on the task execution environment. Refer to configuration options for more information.
AWS Credentials	Optional	-	Credentials	The Credentials definition should be as follows. AWS Access Key ID as "Runtime User". AWS Secret Access Key as "Runtime Password". When AWS Credentials are not populated as part of the task definition, during task execution the integration will look for AWS Credentials on the task execution environment. Refer to configuration options for more information.
Role Based Access	Optional	False	Boolean	Special type of authorization is provided by Role Assumption where the client sends his own credentials and the role he wants to assume from another user. If allowed, the client receives temporary credentials with limited time access to some resources.
Role ARN	Optional	-	Text	Role Amazon Resource Name (ARN) that will be used to access and execute the Step Function.Role ARN format: `arn:aws:iam::<AWS Account ID>:instance-profile/<Role name>`. Required when Role-Based Access has been checked.
State Machine Arn	Required	-	Text	The Amazon Resource Name (ARN) of the state function to execute.
Execution Name	Optional	-	Text	The name of the execution. For more information and restrictions refer to Limits Related to State Machine Executions in the AWS Step Functions Developer Guide. If empty when execution, the Universal Task will generate a unique value for each instance. On the first and subsequent runs of a task instance a suffix is appended to the name representing the execution count of the task. This makes the execution name unique across runs. Visible only when Action = “Start Asynchronous Execution”.
Input	Optional	-	Script	The string that contains the JSON input data for the execution.
Wait for Success or Failure	Optional	False	Boolean	If selected, the task will continue running until the task reaches the "SUCCEEDED", "FAILED", "ABORTED" or "TIMEOUT" state. Required when Action is "Start Asynchronous Execution".
Polling Interval	Optional	10	Integer	The polling interval in seconds between checking for the Step Function status. Required when Wait for Success or Failure ="True".
Use Proxy	Optional	False	Boolean	Flag to indicate whether Proxy shall be used in the communication with AWS.
Proxy Type	Optional	HTTP	Choice	Type of proxy connection to be used. The following options are available. HTTP HTTPS HTTPS With Credentials Required when Use Proxy is checked.
Proxy	Optional	-	Text	Comma-separated list of Proxy servers. Valid formats: http://proxyip:port or http://proxyip:port,https://proxyip:port`.` Required when Use Proxy is checked.
Proxy CA Bundle File	Optional	-	Text	The path to a custom certificate bundle to use when establishing SSL/TLS connections with proxy. Used when Proxy Type is configured for "HTTPS" or "HTTPS With Credentials".
Proxy Credentials	Optional	-	Credentials	Credentials to be used for proxy communication. The credential definition should be as follows. Proxy Username as "Runtime User". Proxy Password as "Runtime Password". Required when Proxy Type is configured for "HTTPS With Credentials".

Task Examples

Start Asynchronous Execution

Example of AWS Step Functions Universal Task for triggering a Step Function with AWS Credentials and State Machine ARN only.

Start Asynchronous Execution With Proxy

Example of AWS Step Functions Universal Task for submitting a new AWS Step Function with the following arguments.

Environment Variables for AWS Region
Input script
Execution Name
Proxy Type "HTTPS With Credentials"

Start Asynchronous Execution With IAM Role

Example of AWS Step Functions Universal Task for submitting a new AWS Step Function using an IAM Role and without providing AWS Credentials.
AWS Credentials are expected in this case to be configured on the task execution environment.
Wait fot Success or Failure is selected so the Universal Task instance will continue execution until the AWS Step Function reaches one of the following final states.

SUCCESS
FAIL
ABORTED
TIMEOUT

Task Output

Cancellation logic

There is no specific cancel logic. In the case of Retry, the action will be re-executed.

Output Only Fields

The output fields for this Universal Extension are described below.

Field	Type	Preserved on re-run	Description

Field	Type	Preserved on re-run	Description
Execution Arn	Text	False	The Amazon Resource Name (ARN) which identifies the execution.
Execution Status	Text	False	The current status of the execution.
Generated Execution Name	Text	False	The unique execution name that is generated by the task and used when the AWS service is called.

Exit Codes

The exit codes for AWS Step Functions Extension are described below.

Exit Code	Status Classification Code	Status Classification Description	Status Description

Exit Code	Status Classification Code	Status Classification Description	Status Description
0	SUCCESS	Successful Execution	SUCCESS: AWS Step Functions workflow executed successfully. If the Wait for Success or Failure = "True" the SUCCESS exit code means the AWS Step Functions was successfully executed.
0	SUCCESS	Successful Execution	SUCCESS: AWS Step Functions workflow started successfully If the Wait for Success or Failure = "False" the RUNNING exit code means the AWS Step Functions was successfully started.
1	FAIL	Failed Execution	FAIL: Unexpected error. Execute in Debug for more information.
2	AUTHENTICATION_ERROR	Bad credentials	AUTHENTICATION_ERROR: Account cannot be authenticated.
3	AUTHORIZATION_ERROR	Insufficient Permissions	AUTHORIZATION_ERROR: Account is not authorized to perform the requested action.
10	CONNECTION_ERROR	Bad connection data or connection timed out	CONNECTION_ERROR: < Error Description >
11	CONNECTION_ERROR	Extension specific connection error	CONNECTION_ERROR: ProxyConnectionError: Failed to connect to proxy URL `<url>`
20	DATA_VALIDATION_ERROR	Failed Execution	DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDOUT for more details
23	FAIL	Successful Execution	FAILED: Step Function is in FAILED state.
24	FAIL	Successful Execution	FAILED: Step Function is in ABORTED state.
25	FAIL	Successful Execution	FAILED: Step Function is in TIMEOUT state.

Extension Output

In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.

Attribute changed is populated as follows

true, in case the AWS Step Function is successfully triggered.

The Extension output contains attribute result. Attribute result contains the following sub-attributes.

Attribute	Type	Description

Attribute	Type	Description
executionArn	string	The Amazon Resource Name (ARN) that identifies the execution.
stateMachineArn	string	The Amazon Resource Name (ARN) that identifies the state machine.
name	string	The name of the execution.
startDate	string	The date the execution is started.
stopDate	string	If the execution has already ended, the date the execution stopped. Visible only when Wait for Success or Failure is selected
status	string	The current status of the execution.
output	string	The JSON output data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding. Visible only when Wait for Success or Failure is selected
outputDetails	object	Provides details about execution input or output. Include indicates whether output was included in the response. Always true for API calls. Visible only when Wait for Success or Failure is selected

An example of the Extension Output for a successful execution an AWS Step Function with the Wait For Success or Failure option selected is presented below.

{
"exit_code": 0,
"status_description": "SUCCESS: AWS Stepfunctions workflow executed successfully.",
"changed": true,
"invocation": {
"extension": "ue-aws-stepfunctions",
"version": "2.0.0",
"fields": {
"action": "Start Asynchronous Execution",
"credentials_user": "****",
"credentials_password": "****",
"region": "us-east-1",
"role_based_access": false,
"role_arn": null,
"state_machine_arn": "arn:aws:states:us-east-1:169598488829:stateMachine:UE_Test_StateMachine",
"execution_name": "",
"input": null,
"use_proxy": false,
"wait_for_success_or_failure": true,
"polling_interval": 2,
"proxy_type": null,
"proxy": null,
"proxy_credentials_user": null,
"proxy_credentials_password": null,
"proxy_ca_bundle_file": null
}
},
"result": {
"executionArn": "arn:aws:states:us-east-1:169598488829:execution:UE_Test_StateMachine:ue-stepfunction-65cb4d81-08ff-4fe2-a2c4-0aa6ca878661-1",
"stateMachineArn": "arn:aws:states:us-east-1:169598488829:stateMachine:UE_Test_StateMachine",
"name": "ue-stepfunction-65cb4d81-08ff-4fe2-a2c4-0aa6ca878661-1",
"status": "SUCCEEDED",
"startDate": "2023-08-15 16:27:58.977000+03:00",
"stopDate": "2023-08-15 16:28:05.081000+03:00",
"output": "null",
"outputDetails": {
"included": true
}
}
}

AWS Step Functions