Adapter properties and commands

This section lists the properties and commands supported by the adapter.

Host

Specifies the host name where the RabbitMQ broker is installed and running. This is a valid DNS name of the host or its IP address. This is a mandatory property. The corresponding adapter command is -H host (or -HOST host).

Port

Specifies the port on which the RabbitMQ broker is listening for connections from clients such as the RabbitMQ adapter and communicating with them using the AMQP protocol. Messages are consumed and produced on the connection established on this port. The default value is 5672. If TLS Connections property is set to value AMQP or AMQP/HTTP, the adapter establishes secure AMQP connection to the broker. The port number must match the port on which RabbitMQ accepts secure AMQP connections. Default port is 5671. The corresponding adapter command is -P port (or -PORT port).

Management Port

Specifies the port on which the RabbitMQ broker is accepting API calls over HTTP for performing management operations. The adapter connects to this port on the broker to obtain the lists of available exchanges and queues to display in the web UI. The default value is 15672. If TLS Connections property is set to value HTTP or AMQP/HTTP, the adapter establishes secure HTTP (HTTPS) connection to the broker. The port number must match the port on which RabbitMQ accepts secure HTTP connections. Default port is 15671. The corresponding adapter command is -MP port (or -MANAGEMENTPORT port).

User

Specifies the username to use for authentication when connecting to the message broker. This is a mandatory property. The corresponding adapter command is -USR username (or -USERNAME username).

Password

Specifies the password value to use for authentication when connecting to the message broker. The corresponding adapter command is -PWD password (or -PASSWORD password).

Virtual Host

Specifies the virtual host for the connection defined in the broker. The user must be authorized to access that virtual host. The default value is / , which is the default virtual host defined in the broker. The corresponding adapter command is -VH vhost (or -VIRTUALHOST vhost).

Connection Name

Specifies the optional name to use for identifying the connection. The broker includes this value in the broker log messages which makes it easier to locate log messages that apply to the connection established by the adapter. The corresponding adapter command is -CN name (or -CONNECTIONNAME name).

TLS Connection
Specifies the types of connections to utilize TLS for security. The corresponding adapter command is -TLSC connections (or -TLSCONNECTIONS connections). The following values are supported:
  • None: TLS is never used. This is the default value. The corresponding adapter command value is none.
  • AMQP: TLS for AMQP connections only. AMPQ connections are used for producing and consuming messages. The corresponding adapter command value is amqp.
  • HTTP: TLS for HTTP connections only. HTTP connections are used for listing available queues and exchanges in the web UI. The corresponding adapter command value is http.
  • AMQP/HTTP: TLS for both AMQP and HTTP connections. The corresponding adapter command value is amqp_http.
Truststore Location

Specifies the path to the truststore in PKCS#12 or JKS format that the adapter uses to validate the broker certificate when TLS is enabled. The truststore must contain the chain of certificates up to the CA certificate that is used to sign the broker certificate. The corresponding adapter command is -TSL path (or -TRUSTSTORELOCATION path).

Truststore Password

Specifies the password for the adapter to use to access the specified truststore when TLS is enabled. The corresponding adapter command is -TSP password (or -TRUSTSTOREPASSWORD password).

Verify Hostname

Verifies the hostname specified for the connection is listed in the certificate presented by the broker when TLS is enabled. If it is not listed in the certificate, the connection fails. The corresponding adapter command is -VH (or -VERIFYHOSTNAME).

Keystore Location

Specifies the path to the keystore in PKCS#12 or JKS format that the adapter uses to retrieve the private key and certificate with the public key. Which is required, if the broker is configured to request clients to provide a certificate for TLS connections (mutual TLS). The corresponding adapter command is -KSL path (or -KEYSTORELOCATION path).

Keystore Password

Specifies the password for the adapter to access the specified keystore when TLS is enabled and mutual TLS is configured. The corresponding adapter command is -KSP password (or –KEYSTOREPASSWORD password).

Key Password

Specifies the password for the adapter to access the private key in the specified keystore when TLS is enabled and mutual TLS is configured. The password is required, if the private key is secured with a password different from the keystore password. The corresponding adapter command is -KP password (or -KEYPASSWORD password).

Queue Name

Specifies the name of the queue from which to consume messages. Click the Fetch button when configuring this property in the web UI to show the available queue and select a queue from the list. You can enter in the name of the queue manually. The corresponding adapter command is -Q name (or -QUEUE name).

Exchange Name

Specifies the name of the exchange to produce the messages. Click the Fetch button when configuring this property in the web UI to show the available exchanges and select an exchange from the list. You can type in the name of the exchange manually. The corresponding adapter command is -E name (or -EXCHANGE name).

Routing Key

Specifies the routing key for the broker to use along with the exchange name to determine the queue or queues to which the produced messages should be routed and stored. The corresponding adapter command is -RK key (or -ROUTINGKEY key).

Receiving Guarantee Mode
Specifies the guarantee mode to request when consuming messages from the queue. The corresponding adapter command is -RGM mode (or -RECEIVINGGUARANTEEMODE mode). The following values are supported:
  • Transactions (AMQP TX): The adapter consumes messages under an AMQP (TX) transaction. If the adapter is requested to commit the transaction in the map or flow, it positively acknowledges the messages consumed under the transaction and commits the AMQP transaction after which the broker removes the messages from the queue. If the adapter is requested to roll back the transaction in the map or flow, it rolls back the AMQP transaction which results in the messages remaining on the queue. This is the default option. The corresponding adapter command value is tx.
  • Acknowledgments Only: The adapter consumes messages outside of an AMQP (TX) transaction. If the adapter is requested to commit the transaction defined in the map or flow context, it positively acknowledges the messages consumed under the transaction and the broker removes them from the queue. If the adapter is requested to roll back the transaction in the map or flow, it negatively acknowledges (nacks) the messages consumed under the transaction with redelivery enabled which results in the messages remaining on the queue. The corresponding adapter command value is acknowledgments_only.
  • Read Only: When a message is consumed by an adapter with redelivery enabled, the adapter negatively acknowledges the message regardless of whether it is requested to commit or rollback the transaction, so the message always remains on the queue. The corresponding adapter command value is read_only.
  • None: The adapter consumes messages in auto-acknowledge mode. This means that the messages are permanently removed from the queue after consumed by the adapter regardless of whether the adapter is subsequently requested to commit or rollback the transaction in the map or flow context. The corresponding adapter command value is none.
Delivery Guarantee Mode
Specifies the guarantee mode to request when producing messages to the exchange. The corresponding adapter command is -DGM mode (or -DELIVERYGUARANTEEMODE mode). The following values are supported:
  • Transactions (AMQP TX): The adapter produces messages to the exchange under an AMQP (TX) transaction. If the adapter is requested to commit the transaction in the map or flow context, it commits the AMQP transaction after which the broker stores the messages. If the adapter is requested to roll back the transaction in the map or flow context, it rolls back the AMQP transaction which results in the messages not being stored on the queue(s). Note that for the true transactional behavior to be enforced all the messages need to be routed to the same queue, it means the exchange and the routing key used for producing the messages must result in all messages in the transaction being routed and stored on the same queue. This is the default option. The corresponding adapter command value is tx.
  • Publisher Confirms: The adapter requests the broker to send confirmations about successful acceptance of each message. If the adapter is subsequently requested to commit the transaction in the map or flow context, it checks if all the messages in the transaction were positively acknowledged (acked) by the broker (and waits for any pending confirmations if necessary) and performs no further action. If any messages were negatively acknowledged (nacked) by the broker, the adapter logs them, if the logging is enabled and throws an exception to indicate the problem. The messages that were already positively acknowledged by the broker are stored on the broker and those that were negatively acknowledged are not. The corresponding adapter command value is publisher_confirms.
  • None: This is a 'fire and forget' mode. The adapter publishes messages and does not perform any further checking to verify if the messages where successfully accepted and stored by the broker. The corresponding adapter command value is none.
Mandatory Routing

Specifies the mandatory routing for the messages for the specified exchange name and routing key. When this property is enabled and a message not routed to its destination, the broker returns the messages to the adapter asynchronously and the adapter is notified about this throws an exception and causes the map or flow to fail.

When this property is enabled and Delivery Guarantee Mode is set to Transactions (AMQP TX), the adapter is notified about non-routable messages during the execution of the AMQP commit call. If that happens, the commit will complete successfully and the messages that were successfully routed will be committed but the adapter will still throw exception to indicate that some messages could not be routed and were returned by the broker.

When this property is enabled and Delivery Guarantee Mode is set to Publisher Confirms, the adapter is be notified about non-routable messages prior to being notified with positive or negative confirmation for each message. Since the adapter always waits for the confirmations from the broker in this mode, it will be timely notified of any non-routable and returned messages and will throw an exception. By default, this property is enabled.

If an alternate exchange is defined for the exchange to which the messages are published and the message could not be routed to the original exchange, it will be re-routed by the broker to the alternate exchange and will not be considered as non-routable. If this property is enabled, the broker will not return the message to the adapter as the message will be considered successfully routed. Returned messages are always logged by the adapter in the adapter log when logging is enabled. The corresponding adapter command is -MR (or -MANDATORYROUTING).

Consumer Tag

Specifies the consumer tag for the consumer. Tag to assign to the consumer created by the adapter for consuming messages from the broker to serve as events for triggering flow instances. Therefore, this property only applies to the consumer the adapter creates when used in a source node in a flow for that a watch is enabled. When the value is not specified for this property, the broker automatically generates a consumer tag value for the consumer. The corresponding adapter command is -CTAG tag (or -CONSUMERTAG tag).

Message Header

Specifies the JSON schema version that represents messages. The default value None means that message metadata will not be processed, only the message payload. The adapter does not do any JSON processing in this case and the entire data passed to and from the adapter represents the message payload binary data. The corresponding adapter command value is 0. The value Version 1 indicates the message JSON structure version 1, which is covered in detail in the Generating Schema section. The corresponding adapter command value is 1. The corresponding adapter command is -HDR version (or -HEADER version).

Charset

Specifies the character set to use for conversion between the raw bytes exchanged with the adapter framework and the Java strings required for the message header JSON fields. By default, the charset encoding from the current system locale is used. The corresponding adapter command is -CS charset (or -CHARSET charset).

Message Header Element

Specifies the message header fields. Comma-separated list of message header fields to include in the generated JSON schema and in the generated JSON representation of messages when consuming messages. Any extra whitespaces around the values are not ignored and are considered parts of those values. The property applies only when the Message Header property is set to a value other than None. The corresponding adapter command is -MHE list (or -MESSAGEHEADERELEMENTS list).

For example, if this property is set to the value app_id,priority,message_id,user_id, the JSON representation of the message will be:
{
    "app_id": "",
    "priority": 0,
    "message_id": "",
    "user_id": ""
}

It is important to note that the order of fields in the property value matches the order of elements in the generated JSON. Also, the payload element must be set among the property's fields to be included in JSON.

Native Headers

Specifies the native message headers. Comma-separated list of native message headers to include in the headers element in the generated JSON schema and in the generated JSON representation of messages when consuming messages. The native headers are required to be captured. They are required to be captured when the Message Header Elements property is not set, in that case all message header elements are automatically included and when it is set to a comma-separated list of values which includes the headers values. It is important to note that any extra whitespaces around the values in the list are not ignored and are considered parts of those values. The corresponding adapter command is -NH list (or -NATIVEHEADERS list).

For example, if generating a schema and the property Message Header Elements is set to value message_id,headers,payload, and the Native Header Fields is set to value title,size, as part of the schema generation process the adapter retrieves message from the queue that contains title header of string type and size header of numeric integer type then the generated JSON schema will be:
{
    "message_id": "",
    "headers": {
        "title": "",
        "size": 0
    },
    "payload": ""
}
Native Headers Element Type
Specifies the type to use when generating schema and consuming messages. You can define the type of the headers element in the JSON messages representation. When producing messages, the adapter automatically detects the type used in the JSON data provided to it. The corresponding adapter command is -NHET type (or -NATIVEHEADERSELEMENTTYPE type). The supported values are:
  • Object: The headers element is a JSON object. This is the default value. The corresponding adapter command value is object.
  • Array: The headers element is a JSON array. The corresponding adapter command value is array.
When the headers element is of array type, it is a JSON array with an arbitrary number of JSON objects that contains the key and value elements. In most cases, string types are appropriate when all headers for the message can be represented by the same atomic type:
"headers": [
    {
        "key": "header1_name",
        "value": "header1_value"
    }    
]
When the headers element is of object type, it is a JSON object with the number of elements that matches the number of headers in the message and where each of those elements has name and value that match the corresponding header's key and value. It is appropriate to use when the headers for the message have different types, such as a string, integer, floating-point decimal number, Boolean, and list of string values:
"headers": {
    "header1_name": "header1_value",
    "header2_name": 10,
    "header3_name": 10.05,
    "header4_name": true,
    "header5_name": [ 
        "header5_element1_value"
    ]
}
Message Payload Encoding
Specifies the encoding of the value of the payload element in the JSON message representation. The corresponding adapter command is -MPE encoding (or -MESSAGEPAYLOADENCODING encoding). The supported values are:
  • Text: The value is a string representation of the message payload. It assumes that the message payload is text encoded using the current system locale encoding or the encoding specified in the Charset property. The corresponding adapter command value is text.
  • JSON: The value is in JSON format. This can be an atomic JSON value, a JSON object, or a JSON array. It assumes that the message payload is JSON text encoded using the current system locale encoding or the encoding specified in the Charset property. The corresponding adapter command value is json.
  • Hex Pairs: The value is a string consisting of consecutive hex-digit pairs, where each pair corresponds to a single byte in the message payload's binary content. The corresponding adapter command value is hex_pairs.
  • Base64: The value is a string that represents base64 encoded message payload's binary content. The corresponding adapter command value is base64.
Application Id

Specifies the application identifier message property value to set for the produced messages. The value can also be set on a per-message basis using the app_id element in the JSON message structure. When both values are specified, the app_id JSON element value takes preference. The corresponding adapter command is -AID id (or -APPLICATIONID id).

Content Type

Specifies the content type message property value to set for the produced messages, for example gzip. The value can also be set on a per-message basis using the content_type element in the JSON message structure. When both values are specified, the content_type JSON element value takes preference. The corresponding adapter command is -CTYPE type (or –CONTENTTYPE type).

Content Encoding

Specifies the content encoding message property value to set for the produced messages, for example text/plain or application/json. The value can also be set on a per-message basis using the content_encoding element in the JSON message structure. When both values are specified, the content_encoding JSON element value takes preference. The corresponding adapter command is -CENC encoding (or –CONTENTENCODING encoding).

Correlation Id

Specifies the correlation identifier message property value to set for the produced messages. The value can also be set on a per-message basis using the correlation_id element in the JSON message structure. When both values are specified, the correlation_id JSON element value takes preference. The corresponding adapter command is -CID id (or –CORRELATIONID id).

Delivery Mode
Specifies the mode of delivery to set for the produced messages. The value can also be set on a per-message basis using the delivery_mode element in the JSON message structure. When both values are specified, the delivery_mode JSON element value takes preference. The corresponding adapter command is -DM mode (or –DELIVERYMODE mode). The following values are supported for this property:
  • Transient: For instructing the broker to store messages in memory. This is the default value. The corresponding adapter command value is transient.
  • Persistent: For instructing the broker to persist messages on disk. The corresponding adapter command value is permanent.
Reply To

Specifies the name of the response queue to set for the produced messages. The value can also be set on a per-message basis using the reply_to element in the JSON message structure. When both values are specified, the reply_to JSON element value takes preference. The corresponding adapter command is -RTO name (or –REPLYTO name).

Expiration

Specifies the message expiration duration in milliseconds to set for the produced messages. The value can also be set on a per-message basis using the expiration element in the JSON message structure. When both values are specified, the expiration JSON element value takes preference. The corresponding adapter command is -EXP duration (or –EXPIRATION duration).

Message Id

Specifies the message identifier message property value to set for the produced messages. The value can also be set on a per-message basis using the message_id element in the JSON message structure. When both values are specified, the message_id JSON element value takes preference. The corresponding adapter command is -MID id (or –MESSAGEID id).

Priority

Specifies the priority to set for the produced messages. The value can also be set on a per-message basis using the priority element in the JSON message structure. When both values are specified, the priority JSON element value takes preference. The corresponding adapter command is -PRI priority (or –PRIORITY priority).

Timestamp

Specifies the timestamp message property value to set for the produced messages. It is a string value in the yyyy-MM-dd HH:mm:ss format representing a timestamp with a second precision and using the timezone from the current system locale. The value can also be set on a per-message basis using the timestamp element in the JSON message structure. When both values are specified, the timestamp JSON element value takes preference. The corresponding adapter command is -TS timestamp (or –TIMESTAMP timestamp).

Type

Specifies the user defined message type to set for the produced messages. The value can also be set on a per-message basis using the type element in the JSON message structure. When both values are specified, the type JSON element value takes preference. The corresponding adapter command is -TYP type (or –TYPE type).

User Id

Specifies the user identifier message property value to set for the produced messages. When set, RabbitMQ verifies that it matches the user id associated with the current connection. The value can also be set on a per-message basis using the user_id element in the JSON message structure. When both values are specified, the user_id JSON element value takes preference. The corresponding adapter command is -UID id (or –USERID id).

Limit

Specifies the total number of messages to consume. The default value is 1. The special value S indicates all available messages. When the adapter is utilized as a listener for a flow node with a watch this property does not affects. In that case, the adapter waits indefinitely for a new message to arrive for as long as it is in the running state. The corresponding adapter command is -QTY limit.

Timeout

Specifies the time duration (in seconds) to wait for before retrieving the message. The default value is S. This is a special value that indicates unlimited (infinite) wait. The value 0 means no wait. When the adapter is utilized as a listener for a flow node with a watch this property does not affects. In that case, the adapter waits indefinitely for a new message to arrive for as long as it is in the running state. The corresponding adapter command is -LSN timeout.

Logging

Specifies the level of logging to use for the log (trace) file produced by the adapter.

The value Information means log informational messages, the value Errors Only means log error messages only, and the value Verbose means log debug and trace level messages along with the informational and error messages.

The corresponding adapter command is:

-T[V|E][+] [log_file]

-T -> Log adapter informational messages.

-TE -> Log only adapter errors.

-TV -> Use verbose (debug) logging. The log file records all activity that occurs while the adapter is producing or consuming messages.

+ -> Appends the trace information to the existing log file. Omit this argument to create a new log file.

log_file -> Specifies the location of the log file to which to write log messages. If not specified, the default log file name m4rabbitmq.mtr is used and the file is stored to the directory in which the executed compiled map resides.

Append Log

Flag indicating what to do if the specified log file already exists. When set to true, the log messages are appended to the file. When set to false, the file is truncated, and the messages are written to the empty file. The default value is true.

Log File Path

Specifies the location of the log file to which to write log messages. If not specified, the default log file name m4rabbitmq.mtr is used and the file is stored to the directory in which the executed compiled map resides.