Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel

Table of Contents

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/

Overview

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

Version Information

...

Refer to Changelog for version history information.

Software Requirements

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

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.

Software Requirements for Universal Agent

Both Windows and Linux agents are supported:

  • Universal Agent for Windows x64 Version 7.0.0 and later with python options installed.
  • Universal Agent for Linux Version 7.0.0 and later with python options installed.

Software Requirements for Universal Controller

Universal Controller Version 7.0.0.0 and later.

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.

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:

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

  2. To import the Universal Template into your Controller, follow the instructions here.

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

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.

...

  • Start Asynchronous Execution

...

The Credentials definition should be as follows.

  • AWS Access Key ID as "Runtime User".
  • AWS Secret Access Key as "Runtime Password".

...


Panel

Table of Contents

Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/

 Version Information

Template NameExtension NameExtension Version
AWS Step Functionsue-aws-stepfunctions2.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.

AreaDetails
Python VersionRequires 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 ControllerUniversal 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:

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

  2. To import the Universal Template into your Controller, follow the instructions here.

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

FieldInput typeDefault valueTypeDescription
ActionRequiredStart Asynchronous ExecutionChoiceAction performed upon the task execution. Available actions are as follows.
  • Start Asynchronous Execution
AWS RegionOptional-TextRegion 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 AWS Credentials the region as configured on the task execution environment. Refer to configuration options for more information.
Role Based AccessAWS CredentialsOptionalFalse-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 ARNOptional-TextRole Amazon Resource Name (ARNCredentials

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 AccessOptionalFalseBoolean

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 ARNOptional-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 ArnRequired-TextThe Amazon Resource Name (ARN) of the state function to execute.
Execution NameOptional-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.Visible only when

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

InputOptional-ScriptThe string that contains the JSON input data for the execution.
Wait for Success or FailureOptionalFalseBoolean

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 IntervalOptional10Integer

The polling interval in seconds between checking for the Step Function status.

Required when Wait for Success or Failure ="True".

Use ProxyOptionalFalseBooleanFlag to indicate whether Proxy shall be used in the communication with AWS.
Proxy TypeOptionalHTTPChoice

Type of proxy connection to be used. The following options are available.

  • HTTP
  • HTTPS
  • HTTPS With Credentials

Required when Use Proxy is checked.

ProxyOptional-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 FileOptional-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 CredentialsOptional-Credentials

Credentials to be used for the proxy communication. Credential 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".

...

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

Output Only Fields

...

FieldTypePreserved on re-runDescription
Execution ArnTextFalseThe Amazon Resource Name (ARN) that which identifies the execution.
Execution StatusTextFalseThe current status of the execution.

Exit Codes

...

Generated Execution NameTextFalseThe 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.

...

Attribute changed is populated as follows"

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

...

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 StepStepfunctions Functions workflow executed successfully.",
"changed": true,
"invocation": {
"extension": "ue-aws-stepfunctions",
"version": "12.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:123456789012169598488829:stateMachine:UE_Test_StateMachine",
"execution_name": "ue-stepfunction-fd1aaa9a-8dde-4c8d-bed9-e56e1fb44243",
"input": {}null,
"use_proxy": false,
"wait_for_success_or_failure": true,
"polling_interval": 52,
"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:123456789012169598488829:execution:UE_Test_StateMachine:ue-stepfunction-2d091ad565cb4d81-9efd08ff-499c4fe2-a2c4-9f3a0aa6ca878661-4bf5c8c02eff1",
"stateMachineArn": "arn:aws:states:us-east-1:169598488829:stateMachine:UE_Test_StateMachine",
"name": "ue-stepfunction-2d091ad565cb4d81-08ff-9efd4fe2-499ca2c4-9f3a0aa6ca878661-4bf5c8c02eff1",
"status": "SUCCEEDED",
"startDate": "20222023-0708-2215 1316:1727:0558.548000977000+0003:00",
"stopDate": "20222023-0708-2215 1316:1728:1105.578000081000+0003:00",
"output": "{}null",
"outputDetails": {
"included": true
} } }

STDOUT and STDERR

STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

  • Python code modifications should not be done.
  • Template Modifications
    • General Section
      • "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
    • Universal Template Details Section
      • "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
    • Result Processing Defaults Section
      • Success and Failure Exit codes should not be changed.
      • Success and Failure Output processing should not be changed.
    • Fields Restriction Section
      • Default configured values should not be changed.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

...

Changelog

}
}
}

STDOUT and STDERR

STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.

Anchor
IntegrationModifications
IntegrationModifications

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

  • Python code modifications should not be done.
  • Template Modifications
    • General Section
      • "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
    • Universal Template Details Section
      • "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
    • Result Processing Defaults Section
      • Success and Failure Exit codes should not be changed.
      • Success and Failure Output processing should not be changed.
    • Fields Restriction Section
      • Default configured values should not be changed.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Document LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
AWS Step FunctionsUser guide for AWS Step Functions.
IAM RBAC authorization modelUser Documentation for Comparing ABAC to the traditional RBAC model.

Changelog

ue-aws-stepfunctions-2.0.0 (2023-09-01)

  • Breaking Change: This version supports Universal Agent and Universal Controler from version 7.2 onwards. Customers that used older versions of this integration on Universal Controller and Universal Agent of versions <= 7.2 are required to upgrade to use the new functionality introduced by 2.0.0.
  • Added:A suffix is added to the Execution Name before AWS Service is called. That suffix represents the execution count for a specific task instance, therefore providing uniqueness of the Execution Name.
  • Fix: The Extension Output attribute “fields.invocation.execution_name” is corrected to represent the user input after the resolution of UC Functions and variables

ue-aws-stepfunctions-1.0.1 (2022-09-29)

  • Fix: Correct the handling of the escaped characters within input field json payload which led to the impossibility of execution of the Step Function.(#30334)

...