Amazon SQS listener

1. Overview

This listener watches an Amazon Simple Queue Service (SQS) queue and starts the flow for the messages it finds there. It checks the queue on a schedule you set with a cron expression, so the queue drives the flow.

The body of the message becomes the content of the MessagePart Name you configure, and the listener adds two headers that identify the message.

The listener reads messages. It does not remove them. Amazon hides a received message for the length of the queue’s visibility timeout and then offers it again, so the same message starts your flow a second time unless something deletes it. End the flow with an Amazon SQS service whose Action is DELETE.

2. Attributes

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

The Amazon SQS listener 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 listener to be enabled.

Consumer Autostart

Whether the listener starts together with the interface. Set it to false to deploy the interface with the listener stopped.

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 the queue lives in. The default is eu-west-1.

AWS Access Key*

The AWS access key used to authenticate.

AWS Secret Access Key*

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

MessagePart Name

Name of the MessagePart the message body is placed in. 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.

Max Messages Per Poll

How many messages one poll may read. Leave this at 1, and read the warning below before you change it.

Quartz Cron Expression

How often the listener checks the queue, in the format (sec) (min) (hour) (day-of-month) (month) (day-of-week). There is no year field. If the expression has seven fields, the agent does not accept it and the interface does not start. The default is */30 * * * * *, every 30 seconds.

Description

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

3. What one poll does

On every tick of the cron expression the listener asks the queue for messages and waits up to 10 seconds for one to appear. That wait is fixed and is not on the form.

If the queue is empty when the wait is over, nothing happens: no flow is started and nothing is logged as an error. This is the normal state of an idle queue.

For every message it receives, the listener builds a ConnectMessage with the message body in the MessagePart Name and these headers:

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.

Leave Max Messages Per Poll at 1. With a higher value the flow receives all the messages of one poll at once instead of one flow run per message, and the components after the listener cannot read that: the messages are taken from the queue, nothing processes them, and they come back after the visibility timeout. A value below 1 is worse, because the listener then reads nothing at all.

4. Deleting what you have read

A flow started by this listener has to end by removing the message it just handled. Add an Amazon SQS service, set its Action to DELETE, and leave its AWS Receipt Header at sqs_receipt_handle, which is the header this listener writes.

If the flow does not delete the message, it becomes visible again after the visibility timeout and the flow runs a second time with the same content. Amazon reports no error when this happens, so check the DELETE service first whenever a flow appears to run twice.