This Universal Extension provides the capability to send an monitor AWS SQS message towards messages from an existing queue and run job(s) and/or workflows accordingly.

Software Requirements

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

...

Software Requirements Universal Agent

Both Windows and Linux agents are supported:

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

Software Requirements Universal Controller

Universal Controller Version 7.0.0.0 and later.

This Universal Task requires that Universal Controller property /wiki/spaces/UC71x/pages/5177877 (uc.web_service.response.content.default) is set to JSON.

Key Features

This Universal Extension provides the following main features:

Support to send an monitor AWS SQS message towards messages from a standard or a FIFO queue.
Support to launch a task in Universal Controller with variables holding the id, body, attributes, message attributes and receipt handle for each fetched message.
Support for authorization via IAM Role-Based Access Control (RBAC) strategy.
Support for Proxy communication via HTTP/HTTPS protocol.

...

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

Field	Input

Type

type	Default

ValueRaw

value	Type	Description
Action	Required	Send Message	Choice	The action performed upon the task execution.
Region	Required	-	Text	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

Use Proxy	Required	False	Boolean	Flag to configure whether Proxy should be used in communication.
Proxy Type	Optional	http	Choice	Type of

message

proxy connection to be

sent

used.

Available options are:

Raw
Script

Message Attributes

http
https
https with password

Required when Use Proxy is enabled.

Proxy

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"

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

http

Choice

Type of proxy connection to be used.

Available options are:

http
https
https with password

Required when Use Proxy is enabled.

Proxy

Optional

-

Text

Proxy server and port. Valid format: http://proxyip:port or https://proxyip:port.

Required when Use Proxy is enabled.

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 password".

Proxy Credentials

Optional

-

Credentials

Credentials to be used for the proxy communication.

They are comprised of:

username
password

Required when Proxy Type is configured for "https with password".

Task Examples

Send Message to Standard Queue

Example of Universal Task for sending a message towards a standard queue:

Image Removed

Send Message to FIFO Queue

Example of Universal Task for sending a message via script towards a FIFO queue:

Image Removed

...

Text	Proxy server and port. Valid format: http://proxyip:port or https://proxyip:port. Required when Use Proxy is enabled.
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 password".
Proxy Credentials	Optional	-	Credentials	Credentials to be used for the proxy communication. They are comprised of: username password Required when Proxy Type is configured for "https with password".
Attribute Names	Optional	All	Choice	A list of attributes to be returned along with each message. Available options are: All - Returns all values Approximate First Receive Timestamp – Returns the time the message was first received from the queue (epoch time in milliseconds). Approximate Receive Count – Returns the number of times a message has been received across all queues but not deleted. AWS Trace Header – Returns the X-Ray trace header string. SenderId: For an IAM user, returns the IAM user ID. For an IAM role, returns the IAM role ID. Sent Timestamp – Returns the time the message was sent to the queue (epoch time in milliseconds). Message Deduplication Id – Returns the value provided by the producer of the message for FIFO queue. Message Group Id – Returns the value provided by the producer of the message for FIFO queue. Sequence Number – Returns the value provided by Amazon SQS.
Message Attribute Names	Optional	-	Text	Attribute names of the message to be returned from the request, separated by a comma. For example: `FirstName,LastName,Title.` `ALL` returns all attributes of the message. Retrieve all message attributes starting with a prefix, using for example bar.*. Naming rules and restrictions: Name can contain alphanumeric characters and the underscore (_ ), hyphen (- ), and period (. ). Name is case-sensitive and must be unique among all attribute names for the message. Name must not start with AWS-reserved prefixes such as AWS. or Amazon. (or any casing variants). Name must not start or end with a period (. ), and it should not have periods in succession (.. ). Name can be up to 256 characters long.
Maximum Number of Messages	Required	10	Integer	The maximum number of messages to return within each request. Valid values from 1 to 10.
Visibility Timeout (seconds)	Required	1	Integer	The duration that the received messages are hidden from subsequent retrieve requests. Valid values range from 1 to 43200.
Wait Time (seconds)	Required	1	Integer	The duration for which the call waits for Maximum Number of Messages to arrive in the queue before returning. If the requested number of messages is available, the messages are returned sooner than Wait Time (seconds).
Polling Interval (seconds)	Required	60	Integer	The amount of time the task will wait before pooling for a new message batch when no messages are found during the last cycle. Valid values from 0.
Delete After Processing	Required	True	Boolean	Flag to delete the received message after processing. If an error occurs during the launching task process, the received message will not be deleted regardless of the Delete after processing flag.
Launch Task Name	Required	-	Text	The name of the Task to be launched in the Universal Controller. The task will always be launched with the Task variables: messageId - Returns the MessageId. messageBody - Returns the Body of message. attributes - Returns the list of specified attributes of the message in JSON format. messageAttributes - Returns the list of specified message attributes in JSON format. receiptHandle - Returns the received ReceiptHandle value of message.
Universal Controller URL	Required	-	Text	The Universal Controller URL to launch the Task after receiving a message. For example: http://192.168.88.10:8080/uc
Universal Controller Credentials	Required	-	Credentials	The credentials of Universal Controller URL to be used for launching the task The Credentials must have “Web Service Access” Permissions.

Task Examples

Monitor Messages from Queue

Example of Universal Task for monitoring messages from an existing queue.

Image Added

Monitor Messages with Role Based Access Enabled

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

Image RemovedImage Added

http http Proxy Type Task Configuration

Example of Universal Task for sending a message monitoring messages through http proxy connection.

Image Removed

...

Image Added

https Proxy Type Task Configuration

Example of Universal Task for monitoring messages through https proxy connection:

Image Added

https with password Proxy Type Task Configuration

Example of Universal Task for sending a message monitoring messages through https with password proxy connection.

Image RemovedImage Added

Task Output

Output Only Fields

The output parameters are set after every message processing. If they are 'preserved on re-run', they prevent a re-run of the task instance from restarting from scratch.

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

Field	Type	Preserved on re-run	Description
Last Monitor Datetime	Text	False	Timestamp of the last time the messages were pooled from the queue.
Last Monitor Message Count	Integer	False	Number of fetched messages since the start of the monitoring (task instance).
Launched Task IDs	Text	False	sysID (32 char) of the last launched task as returned by UAC REST API.
Read Message Count	Integer	False	Number of fetched messages since the start of the monitoring (task instance).
Launched Task Count	Integer	False	Number of launched tasks instances since the start of the monitoring (task instance).

Exit Codes

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

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.

...

.

...

{
    "exit_code": 0,
    "status_description": "SUCCESS: Task executed successfully.",
    "changed": true,
    "invocation": {
        "extension": "1.0.0",
        "version": "ue-aws-sqs-message",
        "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 test 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 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).

Document References

This document references the following documents:

Name	Location	Description
Universal Templates	https://docs.stonebranch.com/confluence/display/UC71x/Universal+Templates	User documentation for creating Universal Templates in the Universal Controller user interface.
Universal Tasks	https://docs.stonebranch.com/confluence/display/UC71x/Universal+Tasks	User 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.

Versions Compared

Old Version 1

New Version 2

Key

Software Requirements

Software Requirements Universal Agent

Software Requirements Universal Controller

Key Features

Task Examples

Send Message to Standard Queue

Send Message to FIFO Queue

Task Examples

Monitor Messages from Queue

Monitor Messages with Role Based Access Enabled

http http Proxy Type Task Configuration

https Proxy Type Task Configuration

https with password Proxy Type Task Configuration

Task Output

Output Only Fields

Exit Codes

Extension Output

Document References

Page Comparison

Versions Compared

Old Version 1

New Version 2

Key

Software Requirements

Software Requirements Universal Agent

Software Requirements Universal Controller

Key Features

Task Examples

Send Message to Standard Queue

Send Message to FIFO Queue

Task Examples

Monitor Messages from Queue

Monitor Messages with Role Based Access Enabled

http http Proxy Type Task Configuration

https Proxy Type Task Configuration

https with password Proxy Type Task Configuration

Task Output

Output Only Fields

Exit Codes

Extension Output

Document References