Versions Compared

Old Version 6

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Stonebranch

Saved on

Key

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

...

This Universal Extension provides the capability to send an AWS SQS message towards an existing queue.

Version Information

Template NameExtension NameExtension Version
Amazon SQS Messageue-aws-sqs-message1.1.1

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.

...

  • Universal Controller Version 7.0.0.0 and later.

Key Features

This Universal Extension provides the following main features:

...

Network and Connectivity Requirements

Extension's Universal Agent host should be able to reach AWS SQS Queue Message REST endpoints. The AWS Credentials provided in the Amazon SQS Queue Message Universal Task, should have sufficient permissions on AWS to send messages.

Key Features


  • Actions
    • Send an AWS SQS message towards a

...

    • Standard or a FIFO queue.

...

  • Authentication
    • AWS Credentials.
    • IAM Role-Based Access Control (RBAC) strategy.

...

  • Input/Output
    • Capability to Print the JSON Response .
  • 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

...

  1. Resolvable Credentials feature. Check that the

...

  1. Resolvable Credentials Permitted system property has been set to true.

...

Download the provided ZIP file.

...

In the Universal Controller UI, select Administration >Configuration > Universal Templates to display the current list of Universal Templates.

...

Click Import Template.

...

Select the template ZIP file and Import.

...

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

  2. When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list

...

  1. .

Configure Universal Task

For the a new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Templaterequired input fields.

Input Fields

The input fields for this Universal Extension are described in the following table.

Field

Input Type

Default Value

Type

Description

Action

Required

Send Message

Choice

The action performed upon the task execution.

AWS RegionRequired

Optional since version 1.1.0

Optional

-

Text

Message Body Script

Optional

-

Region for the Amazon Web Service.

Find more information about the AWS Service endpoints and quotas here.

Credentials

Required

-

Credentials

The AWS account credentials.

They are comprised of:

  • AWS access key ID

  • AWS secret access key

Queue Name

Required

-

Dynamic Choice

Dynamic fetched list of queue names.

The user can select the required queue name from a drop-down list.

Queue Name Prefix

Optional

-

Text

A prefix to use for filtering the Queue Names list results.

Only those queues whose name begins with the specified string are returned.

Queue Names are case-sensitive.

Role Based Access

Optional

False

Boolean

Flag to configure whether the type of authorization is based on IAM Role-Based Access Control(RBAC) strategy.

Find more information about the IAM RBAC authorization model here.

Role ARN

Optional

-

Text

The Role Amazon Resource Name (ARN) to have access to the SQS queue.

Role ARN format: arn:aws:iam::<AWS Account ID>:instance-profile/<Role name>

Required when Role Based Access has been clicked.

Message Body Source

Required

Raw

Choice

Type of message to be sent.

Available options are:

  • Raw

  • Script

Message Attributes

Optional

-

Script

The message attributes to send alongside the message body. Each message attribute consists of a Name, Type, and Value. It should be in JSON format and can have up to 10 attributes.

Example of Attribute Script with 2 Attributes:

{
 "CustomerFirstname": {
  "DataType": "String",
  "StringValue": "John"
 },
 "CustomerLastname": {
  "DataType": "String",
  "StringValue": "Doe"
 }
}

Message Body

Optional

-

Large Text

The message to send to queue.

A message can include only XML, JSON, and unformatted text.

The following Unicode characters are allowed:

#x9, #xA, #xD, #x20 to #xD7FF, #xE000 to #xFFFD, #x10000 to #x10FFFF

Any characters not included in this list will be rejected.

For more information, see the W3C specification for characters.

Required when Message Body Source is configured for "Raw"

ScriptWhen AWS Region is not populated as part of the task definition, during task execution the integration will look for AWS Region on the task execution environment. Refer to configuration options for more information.

AWS Credentials

Optional since version 1.1.0

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.

Queue Name

Required

-

Dynamic Choice

Dynamic fetched list of queue names.

The user can select the required queue name from a drop-down list.

Queue Name Prefix

Optional

-

Text

A prefix to use for filtering the Queue Names list results.

Only those queues whose name begins with the specified string are returned.

Queue Names are case-sensitive.

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 Arn: Amazon Role, which is applied for the connection.

Role ARN format: Example RoleArn: arn:aws:iam::119322085622:role.

Required when Role Based Access="True".

Message Body Source

Required

Raw

Choice

Type of message to be sent.

Available options are:

  • Raw

  • Script

Message Attributes

Optional

-

Script

The message attributes to send alongside the message body. Each message attribute consists of a Name, Type, and Value. It should be in JSON format and can have up to 10 attributes.

Example of Attribute Script with 2 Attributes:

{
 "CustomerFirstname": {
  "DataType": "String",
  "StringValue": "John"
 },
 "CustomerLastname": {
  "DataType": "String",
  "StringValue": "Doe"
 }
}

Message Body

Optional

-

Large Text

The message to send to queue. The minimum message size is 1 byte (1 character).The maximum is 262,144 bytes (256 KB)

A message can include only XML, JSON, and unformatted text.

The following Unicode characters are allowed:

#x9, #xA, #xD, #x20 to #xD7FF, #xE000 to #xFFFD, #x10000 to #x10FFFF

Any characters not included in this list will be rejected.

For more information, see the W3C specification for characters.

Required when Message Body Source is configured for "ScriptRaw".

Is Queue Fifo

Required

Message Body Script

Optional

-

Script

The message to send to queue. The minimum message size is 1 byte (1 character).

The maximum is 262,144 bytes (256 KB).

Required when Message Body Source is configured for "Script".

Is Queue Fifo

Required

False

Boolean

Flag to configure whether the message will be sent to a FIFO Queue.

It should be enabled, if the message will be sent to a FIFO Queue.

Delay Seconds

Optional

-

Integer

The length of time, in seconds, for which to delay a specific message. Messages with a positive value become available for processing after the delay period is finished.

Valid values from 0 to 900.

Used when Is Queue Fifo is disabled.

Message Deduplication ID

Optional

-

Text

Specifies ID for deduplication of sent messages. If a Message Deduplication ID is not provided and the queue doesn't have Content Based Deduplication set on Queue, an error will be raised.

Maximum Length is 128 characters.

Used when Is Queue Fifo is enabled.

Message Group ID

Optional

-

Text

Group ID that specifies that a message belongs to a specific message group.

Maximum Length is 128 characters.

Required when Is Queue Fifo is enabled.

Use Proxy

Required

False

Boolean

Flag to configure whether Proxy should be used in communication.

Proxy Type

Optional

httpHTTP

Choice

Type of proxy connection to be used.

Available options are :the following.

  • httpHTTP

  • https

  • https with password

Required

  • HTTPS

  • HTTPS With Credentials

Visible only when Use Proxy is enabled = "True".

Proxy

Optional

-

Text

Proxy server and port. Valid format: Comma separated list of Proxy servers. Valid formats are the following.
http://proxyip:port or http://proxyip:port or ,https://proxyip:port.

Required when Use Proxy is enabledchecked.

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 "httpsHTTPS" or "https with passwordHTTPS With Credentials".

Proxy Credentials

Optional

-

Credentials

Credentials to be used for the proxy communication.

They are comprised of:

  • username

    • password

    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 passwordHTTPS With Credentials".

    Task Examples

    Send Message to Standard Queue

    Example of Universal Task for sending a message towards a standard queue :Image Removedwith minimum parameters.

    Image Added

    Send Message to FIFO Queue with all optional input arguments

    Example of Universal Task for sending a message via script towards a FIFO queue:Image Removed, with all optional input argument.

    Image Added

    Send Message with

    ...

    Environment Variables as Region

    Example of Universal Task for sending a message with Role Based Access Enabled.

    Image Removed

    HTTP Proxy Type Task Configuration

    Example of Universal Task for sending a message through HTTP proxy connection.

    Image Removed

    HTTP with password Proxy Type Task Configuration

    Example of Universal Task for sending a message through

    HTTP

    with password proxy connection.

    Image Removedto StandardQueue providing no AWS Credentials in task definition and providing AWS Region as Environment Variable, leaving the respective input fields empty. AWS Credentials are expected in this case to be configured on the task execution environment. Please refer to AWS Credentials input field for more information.

    Image Added

    Task Output

    Exit Codes

    The exit codes for this Universal Extension are described in the following tablebelow.

    Exit Code

    Status Classification Code

    Status Classification Description

    Status Description

    0

    SUCCESS

    Successful Execution

    SUCCESS: Successful Task execution

    1

    FAIL

    Failed Execution

    FAIL: < Error Description >

    3

    AUTHORIZATION_ERROR

    Insufficient Permissions

    AUTHORIZATION_ERROR: The authorization credentials provided for the request are invalid.

    10

    CONNECTION_ERROR

    Bad connection data or connection timed out

    CONNECTION_ERROR: < Error Description >

    20

    DATA_VALIDATION_ERROR

    Bad input fields validation

    DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDERR for more details.

    Extension Output

    Upon Task's successful completion, the extension always produces an Extension Output.

    This Universal Extension sends a message towards a Standard or FIFO queue. When the message is sent successfully, related information is published as Extension Output.

    Attribute changed is populated as follows.

    • true in case the message was sent successfully.

    An example of the Extension Output for a successful triggering job is presented below.

    ...

    10

    ...

    CONNECTION_ERROR

    ...

    Bad connection data or connection timed out

    ...

    CONNECTION_ERROR: < Error Description >

    ...

    20

    ...

    DATA_VALIDATION_ERROR

    ...

    Bad input fields validation

    ...

    DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDERR for more details

    Extension Output

    Upon Task's successful completion, the extension always produces an Extension Output.

    This Universal Extension sends a message towards a standard or FIFO queue. When the message is sent successfully, related information is published as Extension Output

    AttributeTypeDescription
    MD5OfMessageBodystringMD5 digest of the non-URL-encoded message body string.
    MD5OfMessageAttributesstringMD5 digest of the non-URL-encoded message attribute string.
    MessageIdstringAttribute containing the MessageId of the message sent to the queue.
    SequenceNumberstringNon-consecutive number that Amazon SQS assigns to each message of FIFO queues.
    ResponseMetadatajsonResponse Metadata of the REST API.

    The following is an example of Extension Output for this Universal Extension.

    Code Block
    languagetext
    linenumberstrue
    {
    "exit_code": 0,
    "status_description": "SUCCESS: Task executed successfully.",
    "changed": true,
    "invocation": {
        "extension": "1.0.0ue-aws-sqs-message",
        "version": "ue-aws-sqs-message"1.1.0" ,
        "fields": {
            "action": "Send Message",
            "credentials_user": "AWSUSER123456789ABCDE",
            "credentials_password": "********",
            "region": "us-east-2",
            "queue_name": "StandardQueue",
            "queue_name_prefix": "",
            "role_based_access": true,
            "role_arn": "arn:aws:iam::123456789:role/arn_test",
            "message_body_source": "raw",
            "message_body": "Hi! This is a testSQS Message Body.",
            "message_body_script": null,
            "message_attributes": {
                "CustomerFirstname": {
                    "DataType": "String",
                    "StringValue": "John"
                },
                "CustomerLastname": {
                    "DataType": "String",
                    "StringValue": "Doe"
                }
            },
            "is_queue_fifo": false,
            "message_deduplication_id": null,
            "message_group_id": null,
            "delay_seconds": 0,
            "use_proxy": false,
            "proxy_type": null,
            "proxy_credentials_user": null,
            "proxy_credentials_password": null,
            "proxy": "",
            "proxy_ca_bundle_file": null
        }
    },
    "result": {
        "MD5OfMessageBody": "c6d58fdf00486074745c40334ab44780",
        "MD5OfMessageAttributes": null,
        "MessageId": "f65bc887-0376-42c3-b354-85749c6d1449",
        "SequenceNumber": null,
        "ResponseMetadata": {
            "RequestId": "3f579b52-6995-5c56-83dd-c14b19cbc99b",
            "HTTPStatusCode": 200,
            "HTTPHeaders": {
                "x-amzn-requestid": "3f579b52-6995-5c56-83dd-c14b19cbc99b",
                "date": "Fri, 26 Nov 2021 11:06:06 GMT",
                "content-type": "text/xml",
                "content-length": "378"
            },
            "RetryAttempts": 0
        }
    }
}

    result.event The result section, as displayed above, includes information of the dispatched SQS message, providing information about the message and response metadata.

    Universal Controller provides Output Functions that can be used to resolve the JSON Extension Output for further use (for example, by a sibling task)sibling task).

    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.

    Document References

    This document references the following documents:

    Name
    Document Link

    Location

    Description

    Universal Templates

    		https://docs.stonebranch.com/confluence/display/UC71x/Universal + TemplatesUser documentation for creating Universal Templates in the Universal Controller user interface.

    Universal Tasks

    		https://docs.stonebranch.com/confluence/display/UC71x/Universal+, working with and understanding Universal Templates and Integrations.
    Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.

    Scripts

    https://docs.stonebranch.com/confluence/display/UC71x/Scripts

    User documentation for creating Scripts in the Universal Controller user interface.

    Amazon SQS quotas

    https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html

    User documentation for Amazon SQS quotas.

    Amazon Simple Queue Service endpoints and quotas

    https://docs.aws.amazon.com/general/latest/gr/sqs-service.html

    User Guide for Amazon Simple Queue Service endpoints and quotas.

    IAM RBAC authorization model

    https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction_attribute-based-access-control.html#introduction_attribute-based-access-control_compare-rbac

    User Documentation for Comparing ABAC to the traditional RBAC model.

    W3C specification for characters

    https://www.w3.org/TR/REC-xml/#charsets

    		User Guide for legal character range.Amazon SQS MessageUser documentation for Amazon SQS.
    IAM RBAC authorization modelUser Documentation for Comparing ABAC to the traditional RBAC model.

    Anchor
    Changelog
    Changelog

    Changelog

    ue-aws-sqs-message-1.1.1 (2023-08-09)

    Fixes

    • Fixed: Field 'Proxy Type' raised a data validation error on Controller 7.3.0.0 and later. (#33871)

    ue-aws-sqs-message-1.1.0 (2022-06-30)

    Enhancements

    • Added: Allow AWS Credentials and AWS Region as optional fields enabling their configuration on the task execution environment. (#28251)

    ue-aws-sqs-message-1.0.0 (2022-02-11)

    Initial Version