MQ Get Message activity
Use the MQ Get Message activity retrieves messages from an MQ queue during run time.
- Queue and Message details - where you specify properties for queue and message details.
- Delivery rules - where you specify how you want messages delivered.
- Retry options - where you specify how long to wait between retries and the number of time to retry before failing.
After completing the Configure tasks, Mapping inputs and Mapping outputs of the activity.
Queue and Message details
Field | Description |
---|---|
Queue Name * | Specifies the name of the MQ queue where Integration Appliance attempts to retrieve the message from. |
Timeout | The number of seconds before a timeout occurs between the MQ
Get Message activity requesting to retrieve a message
from the queue and the time it takes for the message to be returned.
If this timeout period expires and no message is returned from the
queue, the Integration Appliance waits the specified retry time before
attempting to retrieve a message again. For a detail explanation of
the timeouts and retry options, see Timeout and Retry options. To specify the number of seconds that the Integration Appliance should wait before issuing a timeout, select the After option and enter the number seconds in the Seconds field. By default the Never option is selected, this option specifies the Integration Appliance waits indefinitely to retrieve a message from the queue —there is no timeout period. |
Payload Data Type | Specifies the datatype of the message payload, either binary or string. |
Schema Fragment for MQRFH2 Header | Specifies if an MQRFH2 header is included in the message.
If the message includes a MQRFH2 header, select this check box and
click [...]. In the Browse For Schema Type Element dialog
box to find the XML Schema that defines the header, select the NameValueData
element in that XML Schema, and click OK. The
schema fragment is the NameValueData element and all its child elements. Note: The
XML Schema that defines the header must first be created and loaded
into the project before you can select it. For more information see Defining and loading an XML schema for a MQRFH2 header.
|
Delivery rules
Field | Description |
---|---|
Deliver Messages | The options available here depend on whether the Unique
ID's checkbox is selected. If selected, all three options
are available. If not, only At Least Once is
displayed.
|
Where messages have Unique ID's | Specifies if the messages on the queue have unique IDs. |
Retry options
Configure the retry options for getting a message from the MQ queue as described in the following table:
Retry Options | Description |
---|---|
1) Wait ___ seconds between each retry. | The number of seconds that the Integration Appliance waits before attempting to retrieve a message from the queue. To learn more about how this option relates to the Timeout field in the Configure pane or the timeout input parameter, see Timeout and Retry options. |
2) Try to connect ___ times before failing. | Specifies the maximum number of times the Integration Appliance
attempts to retrieve a message from the queue before issuing an error
and stops the processing of the current orchestration job. If you deploy an orchestration that contains an MQ Get Message activity and the Integration Appliance cannot connect to the specified MQ Server or cannot get a message from the queue, the Integration Appliance logs the errors as warnings in the system and orchestration logs until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system and orchestration logs and the stops processing the current orchestration job. For example, you set the retry count to 3. The first, second, and third errors appear in the system log as warnings. The Integration Appliance logs the fourth error as an error and stops processing the current orchestration job. To learn more about how this option relates to the Timeout field in the Configure pane or the timeout input parameter, see Timeout and Retry Options. |
Mapping inputs
- Select the Map Inputs task in the Checklist.
The Retry panel opens.
The input parameters of the activity are displayed in the To Activity panel.
- All the input parameters of the MQ Get Message activity
are optional. If the input parameter listed in the following table
are not displayed in the To Activity pane of
the Map Inputs panel, select Map
> Show Optional Parameters from the toolbar menu or right-click
in the To Activity panel and select the Show
Optional Parameters option. If the Map > Show
Optional Parameters option is not selectable in the toolbar
menu, click on a node in the Map Inputs panel
to activate this option.You can constrain the type of message returned by the MQ Get Message activity by mapping any combination of the following nodes of the mqmdheader optional input parameter:
- mqmdheader/MsgId
- mqmdheader/CorreId
- mqmdheader/GroupId
- mqmdheader/MsgSeqNumber
During run time, the activity iterates sequentially through the messages in the queue. If nothing is mapped to these nodes, nothing is constrained so the first message in the queue is returned by the MQ Get Message activity and next activity in the orchestration is processed.
If any of these nodes are mapped, during run time the MQ Get Message activity iterates through each message in the queue until it finds the first message that matches the run time values of all the mapped nodes. The first matching message is returned by the MQ Get Message activity and next activity in the orchestration is processed.
For example in the Map Inputs task, mqmdheader/MsgId is mapped to the string called msgId and a default value of largeOrders is specified for the mqmdheader/GroupId as shown in the following figure:During run time, the MQ Get Message activity returns the first message in the queue that satisfies both of the following conditions:- The run time value specified of the string variable called msgId is equal message ID of the message in the queue.
- The group IDof the message equals largeOrders.
You can optionally override the settings you specified for the Queue Name and the Timeout in the Configure task of the Checklist dynamically during run time, using the input parameters defined in the following table.
For example, the MQ queue name can be set in the Configure task to poqueue. During run time, the MQ queue name: newqueue could be passed into the activity using the queuename input parameter. The queue name specified dynamically during run time overrides the original setting specified in the Configure panel. In this example, the Integration Appliance looks at the MQ queue named newqueue for messages.
Optional Input Parameters that Override the Settings in the Configure TaskInput Parameter Name/Node Description Overrides the Setting in Task? timeout Specifies the amount of time that the Integration Appliance waits after requesting to retrieve a message from the queue before retrying. Specify a negative number to specify no timeout period — the Integration Appliance waits indefinitely to retrieve a message from the queue. Specifying a negative number is equal to specifying the Never option in the Configure task.
The timeout input parameter overrides the Timeout field of the Configure task. queuename Specifies the name of the MQ queue where the Integration Appliance looks for messages. The queuename input parameter overrides the encoding specified in the Queue Name field of the Configure task. See Creating a Map for general instructions on mapping.
Mapping outputs
You are not required to map the output parameters for this activity. See Creating a Map for general instructions on mapping.
Timeout and Retry options
The timeout specified in the Timeout field in the Configure task or the timeout input parameter specifies the number of seconds before a timeout occurs between the MQ Get Message activity requesting to retrieve a message from the queue and the time it takes for the message to be returned. If this timeout period expires and no message is returned from the queue, the Integration Appliance waits the amount of time specified in the 1) Wait ___ second(s) between each retry option before attempting to retrieve a message, again. The Integration Appliance keeps attempting to get the message up to the specified retry count. The retry count is specified with the 2) Try to connect ___ times before failing. The 1) Wait ___ second(s) between each retry and 2) Try to connect ___ times before failing options are specified in the Retry options task.
- The Timeout field in the Configure task is set to 10 seconds and the optional timeout input parameter is not mapped and no default value is defined.
- The 1) Wait ___ second(s) between each retry option is set to 15 seconds.
- The 2) Try to connect ___ times before failing option is set to 2.
