Amazon SQS service

1. Overview

This service connects a flow to an Amazon Simple Queue Service (SQS) queue. It is one component with three actions. You choose the action in the Action attribute:

  • SEND puts the content of the MessagePart In on the queue.

  • RECEIVE reads one message from the queue and puts its body in the MessagePart Out. It does not remove the message.

  • DELETE removes a message you have already received.

You place it in the Services section of a flow, like any other service. One component performs one action, so a flow that receives a message and then removes it from the queue uses two Amazon SQS services: the first set to RECEIVE and the last set to DELETE.

A flow with two Amazon SQS services — one set to RECEIVE and one set to DELETE

With SEND and DELETE the service calls Amazon and then passes the ConnectMessage to the next component. The content it read from the MessagePart In is written to the MessagePart Out, which changes nothing while both names are the same, as they are by default.

Use this service when the flow itself decides at which point to use the queue. If you want the queue to start the flow, use the Amazon SQS listener, which checks the queue on a schedule.

2. Attributes

In the table below, you will find an explanation of these properties. All attributes with a * are mandatory.

The Amazon SQS service properties
Attribute Description

Name*

By default, we fill this out with the technical tag, followed by a serial number. Changing the name is optional.

Enabled

Set this value to true, if you want this service to be enabled.

Consumer Autostart

Has no effect here. The field is shared with the listener components, where it decides whether the listener starts together with the interface. A service runs whenever the flow reaches it.

Queue URL*

The full URL of the queue, as shown in the AWS console, for example https://sqs.eu-west-1.amazonaws.com/123456789012/orders. This URL is also used as the endpoint of the connection, so it has to match the region you select below.

AWS Region

The AWS region of the queue. The default is eu-west-1.

AWS Access Key*

The AWS access key the agent uses to sign its calls to Amazon.

AWS Secret Access Key*

The secret that belongs to the access key. The Constructor shows it masked.

MessagePart In

Name of the MessagePart this component reads. Every action uses it, and SEND sends its content as the message body. The default is msgprt0.

MessagePart Out

Name of the MessagePart this component writes its result to. RECEIVE puts the message body there. SEND and DELETE copy the MessagePart In content into it. The default is msgprt0.

Use Proxy

Set this to true to reach Amazon through an HTTP proxy. The Constructor then shows the two attributes below and makes them mandatory. The default is false.

Proxy Host

Only shown when Use Proxy is true. Host name or IP address of the proxy.

Proxy Port

Only shown when Use Proxy is true. Port number of the proxy. The default is 80.

AWS Receipt Header*

Name of the header that holds the receipt handle of the message to remove. Only the DELETE action uses it, and only then is it shown and required. The default is sqs_receipt_handle, which is the header written by the RECEIVE action and by the Amazon SQS listener.

Action*

The action this component performs on the queue: SEND, RECEIVE or DELETE. The default is DELETE.

Description

Description of the specific service. This is for documentation purposes.

3. Sending a message

With Action set to SEND, the service reads the MessagePart In and sends its content as the body of a new message on the queue. The service accepts text, an XML document and raw bytes. Any other content is logged as an error and the call to Amazon is still made, without a body, so the flow ends in error.

The queue sends nothing back, so the ConnectMessage that arrived is passed on unchanged. The identifier that Amazon gives the new message is written to the agent log, not to a header.

4. Receiving a message

With Action set to RECEIVE, the service reads one message and puts its body in the MessagePart Out. It waits up to 10 seconds for a message to appear. That wait is fixed and is not on the form, and your flow always receives one message.

The service adds these headers to the ConnectMessage:

Header Description

sqs_message_id

The identifier Amazon gave the message.

sqs_receipt_handle

The receipt handle. You need it to delete the message afterwards.

The service expects a message to be there. If the queue is still empty after those 10 seconds, the service has nothing to return and the flow ends in error. Use this action only when you already know a message is waiting. If you want the queue to drive the flow, use the Amazon SQS listener.

5. Deleting a message

Receiving a message does not remove it from the queue. Amazon only hides it for the length of the queue’s visibility timeout, and then offers it again to any consumer. To take the message off the queue for good, end the flow with an Amazon SQS service whose Action is DELETE.

The delete call identifies the message by its receipt handle. The service reads that handle from the header you name in AWS Receipt Header. The header has to be on the message: when it is missing, the service cannot delete anything and the flow ends in error. If the message was fetched by the RECEIVE action or by the Amazon SQS listener, the default sqs_receipt_handle is already the right header.

Amazon gives you a new receipt handle every time it hands out the same message. Delete the message while the visibility timeout of that delivery is still running. If the flow takes longer, the message becomes visible again, the old handle may no longer delete it, and the message starts the flow a second time.