MQ Get Message activity

Use the MQ Get Message activity retrieves messages from an MQ queue during run time.

Note: You must have created an endpoint for the MQ activity before configuring the activity.
The Configure task has three sections:
  • 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.

Note: The maximum message size is 100 MBytes.

Queue and Message details

Specify the Queue and Message details for the fields in the following table. Required fields are marked with an asterisk.
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.
  • At least once -  Specifies that the message is delivered at least once but can be delivered more than once. Connection or Integration Appliance failures can result in messages being retrieved and processed more than once. This delivery option is typically used when the receiving system can detect or tolerate duplicate messages
  • At most once - Specifies the message is delivered only once or not at all. Connection or Integration Appliance failures can result in messages being missed. This delivery option is typically used when the receiving system cannot tolerate duplicate messages but can tolerate lost messages.
  • Exactly once -  Specifies the message is delivered once and only once. Connection or Integration Appliance failures do not affect delivery with this option. The Integration Appliance uses MQ message IDs to ensure that every message is retrieved and processed exactly once.
    Note: If you select the Exactly Once option, you must enable persistence. For more information, see Enabling Persistence.
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

  1. 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.

  2. 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 Task
    Input 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.

For example, a MQ Get Message activity is configured with the following options:
  • 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.
During run time, if the MQ Get Message activity is continuously unable to retrieve a message from the queue, as shown in the following figure:




Feedback | Notices


Timestamp icon Last updated: Wednesday, February 17, 2016


http://pic.dhe.ibm.com/infocenter/wci/v7r0m0/topic/com.ibm.wci.doc/MQ_Get_Message_Activity.html