RabbitMQ Emit Service (com.ibi.agents.XDRabbitMQEmitAgent)

Syntax:

com.ibi.agents.XDRabbitMQEmitAgent

Description:

This service emits a document to a RabbitMQ server using version 0-9-1 of the Advanced Message Queuing Protocol (AMQP). The Broker URI is the server address. The destination is a combination of the Outgoing Exchange Name and the Routing Key.

The Broker URI has the following format:

scheme://host:port/virtualhost

The scheme is AMQP for communication in clear with the port defaulting to 5672. For secure communication over TLS, the scheme is AMQPS with the port defaulting to 5671. The virtual host is a RabbitMQ concept that allows multiple configurations for the same RabbitMQ server. When /virtualhost is not specified, the virtual host defaults to /. The syntax scheme://host:port is the only way to specify / as the virtual host, since ending the URI with / is not allowed.

When using AMQPS, the TLS configuration is specified with an SSL Context provider. This provider is created in the iSM Administration Console within the Security Provider page under the Server tab.

The user name and password are the credentials to access the RabbitMQ server. The user is created in the RabbitMQ console within the Users page under the Admin tab. Make sure the user is given permission to access the chosen virtual host. The RabbitMQ console can usually be accessed at:

http://host:15672

In version 0-9-1 of AMQP, the message is not sent directly to a queue. Instead, the sender sends the message to an exchange and associates a Routing Key. It is the responsibility of the exchange to route the message to all the queues with a binding that matches the message and the routing key. The queue bindings are part of the exchange configuration on the server. The matching rule depends on the exchange type as follows.

Exchange Type	Matching Rule
direct	The routing key must equal the binding key.
fanout	The routing key is ignored and the binding always matches.
headers	The routing key is ignored. The binding specifies a header name and the value it must have to match. It is possible to specify multiple headers at the same time, in which case the x match attribute determines if 'any' or 'all' headers must match.
topic	The routing key is matched with wildcards.

The Mandatory property determines what happens when the message does not match any queue bindings and therefore was routed to zero queues. When this happens, an error is returned if mandatory is set, otherwise the message is silently discarded.

The RabbitMQ Emit Service expects the exchange, the queue bindings, and the destination queues to be pre-configured on the server. The service does not declare those objects automatically.

AMQP defines a set of properties that are always part of the message. Most properties are open to interpretation by the receiving application. These are: App ID, Content Encoding, Content Type, Correlation ID, Message ID, Response Reply To, Timestamp, Type and User ID. For example, the RabbitMQ server considers the payload to be a byte string. The receiving application may use the Content Encoding and Content Type to reconstruct the message, but that is just by convention.

The properties that affect the broker are: Delivery Mode, Expiration and Priority. The delivery mode is Persistent or Non-Persistent. Persistent messages held in a durable queue will survive a broker restart.

The Expiration is the time the message can remain in the queue before it expires. Expired messages are either discarded or dead-lettered, but only when they reach the head of the queue. Until then, they occupy storage and are counted in the queue statistics. The Priority affects the order messages are delivered by a priority queue. The AMQP specification says the priority is from 0 to 9 but RabbitMQ supports priorities from 0 to 255.

Unlike message properties, message headers are not standardized. They are under the sending application control. When the Request Header Namespace is specified, every special register of type HDR it contains will create a message header of the same name. For example, if the Request Header Namespace is ns and there is special register of type HDR called ns.hdr1 with value v1, then a message header called hdr1 will be created with value v1.

The Avoid Preemitter parameter determines whether preemitters will be executed. The default is to skip the preemitters.

The Return Document parameter determines the contents of the output document. Choose status to return a status document, or input to return the input document of the service.

Parameters:

The following table describes the parameters of the RabbitMQ Emit service (com.ibi.agents.XDRabbitMQEmitAgent).

Parameter	Description
Outgoing Exchange Name	The exchange where the outgoing message will be published.
Broker URI *	The Broker URI, in the following format: scheme://host:port/virtualhost where: scheme Is AMQP or AMQPS. port Is optional defaulting to 5672 for AMQP and 5671 for AMQPS. virtualhost Is also optional.
SSL Context Provider	The iWay Security Provider for SSL Context. If you are using AMQPS and SSL Context Provider is left blank, then the default provider will be used.
User *	User ID for the Broker.
Password *	Password that is associated with the user ID for the Broker.
Routing Key	The routing key of the outgoing message.
Mandatory	Determines what happens when a message is routed to zero queues. When set to true, an error is returned. When set to false, the message is discarded. By default, this parameter is set to false.
App ID	Creating application ID.
Content Encoding	MIME Content Encoding of the payload.
Content Type	MIME Content Type of the payload.
Correlation ID	Application correlation identifier.
Delivery Mode	Determines whether the message is persistent (2) or non-persistent (1). By default, this parameter is set to 1 (persistent).
Expiration	The message time to live in the queue, non-negative integral number of milliseconds.
Message ID	Application message identifier.
Priority	Message priority (0 to 255).
Response Reply To	Destination to reply to this response.
Timestamp	The value of the timestamp property in the outgoing message, in milliseconds since the epoch.
Type	Message type name.
User ID	Creating user ID.
Request Header Namespace	The special register namespace from which protocol headers for the outbound request will be taken. By default, this parameter is set to none.
Avoid Preemitter	Determines whether any preemitter should be avoided. By default, this parameter is set to true.
Return Document	Determines whether the output document will be a status document or the input document. By default, this parameter is set to status.

Edges:

The following table lists and describes the line edges that are returned by the RabbitMQ Emit service (com.ibi.agents.XDRabbitMQEmitAgent).

Line Edge	Description
success	The message was successfully sent.
fail_parse	An iFL expression could not be evaluated.
fail_connect	The service could not connect to the broker.
fail_operation	The operation could not be completed successfully.