Adapter properties and commands
This section lists the properties and commands supported by the adapter.
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).
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).
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).
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).
Specifies the password value to use for authentication when connecting to the message broker. The corresponding adapter command is -PWD password (or -PASSWORD password).
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).
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).
- 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.
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).
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).
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).
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).
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).
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).
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).
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).
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).
- 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.
- 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.
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).
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).
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).
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).
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).
{
"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.
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).
{
"message_id": "",
"headers": {
"title": "",
"size": 0
},
"payload": ""
}
- 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.
"headers": [
{
"key": "header1_name",
"value": "header1_value"
}
]
"headers": {
"header1_name": "header1_value",
"header2_name": 10,
"header3_name": 10.05,
"header4_name": true,
"header5_name": [
"header5_element1_value"
]
}
- 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.
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).
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).
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).
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).
- 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.
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).
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).
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).
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).
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).
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).
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).
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.
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.
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.
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.
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.