Service MQ form - Completing the Response tab

Use the Response tab to define data sent as part of the outgoing response message. The system maps data from the clipboard to fields of the message header or data values in the message buffer. By specifying various response conditions on this tab, the MQ service can return response messages of different types and formats.

At runtime, the system evaluates the array of response conditions in order, and returns response data to the client from the first condition that evaluates to True.

Two arrays of fields are associated with each condition. Click the Expand icon to access these fields, which are initially hidden. Click the Collapse icon to hide them.

Field Description
Response Condition  
Condition Specify a condition that determines the format and content of the response message:
  • Default — The system does not evaluate the data. It returns the response value specified in this row. Enter Default as the bottom choice in the array.
  • When — The system evaluates the when condition rule specified by the When Key field. If true, it returns the response message data specified in this row. If false, continue evaluating the next when condition rule in the list. If all specified when condition rules are false, return the default response data. Use this feature to extend the normal set of fatal error conditions that result in exceptions being returned to the client.
  • Queue When — The system evaluates the when condition rule specified by the When Key field. If the condition evaluates to true, the system queues the service request and returns the queue item ID of the service request.
  • If you configure a Queue When condition, you must specify a request processor in the Request Processor field on the Service tab. For more information, see PDN article Configure a service to queue a failed service request for another attempt.
  • Mapping Error — If an error occurs while mapping incoming data from the request message to the clipboard, the system returns the response message specified in this row.
  • Security Error — If an error occurs while authenticating the application client credentials, the system returns the specified response message data specified in this row.
  • Service Error — If a service error occurs, the system sends the response message data specified in this row.
If a runtime mapping error, security error or service error exception occurs but this array does not include an entry for that exception condition, the system returns a standard error report message to the client application.
Note: It is a best practice to configure the error conditions to ensure that the system notifies an administrator about the error.
When Name If the Condition value is When, specify the name of the when condition rule to be evaluated. Otherwise, leave this field blank.
Requestor Options Indicate whether the system is to keep this requestor session open or close it after the response message is sent for this condition.
Header fields Click the Expand icon to access these fields.
Field Name Select a message header field from the selection list.
Description Enter a text description.
Map From Select how the system creates response header values:
  • Clipboard — The system maps the data value to the scalar property specified by the Map From key.
  • Constant — The system sends a fixed value.

If more choices appear, they identify a custom function rule in a MapFrom library. Review the function rule to determine what it does.

Map From Key If the Map From value is Clipboard, enter a property reference that is the source of the data.

If the Map From value is Constant, enter a literal text string. To include blank spaces in your text string, surround the string with double quotes.

Message Data  
Data Type Enter the external data type of the response parameter: String, Integer, Bytes, All Chars, All Bytes, Double, or Boolean.

To write the entire message buffer as one variable-length text or binary data, specify All Chars or All Bytes in the first row of this array, and leave the Length field blank. Leave other rows blank. In this case, the system does not write the length into the message buffer.

Offset Optional. Enter a number of bytes. At runtime, the system positions the internal cursor within the buffer to this position before it writes the data.
Length Optional. Complete this field only for String and Bytes data values. Enter a fixed length for the data being written.
  • If the Data Type is String, this is the character-length of the text value being written.
  • If the Data Type is Bytes, this is the length of the byte-array being written.

At runtime, the system examines the length of the data value. If the data value is longer than the specified length, the data value is truncated. If it is shorter, the value is padded with white space (for String values), or zeros (for Bytes values).

If you don't specify a data length, the system writes an integer representing the actual string length into the data buffer immediately before it writes the data value.
Description Enter a text description.
Map From Select how the system creates request parameter values. The choice you make for this field depends on what you select for Data Type:
  • Clipboard — The system maps the data value to the property specified by the Map From Key field.
  • Constant — The system sends a fixed value.

If more choices appear, they identify a custom function rule in a MapFrom library. Review the function rule to determine what it does.

Map From Key Enter additional details that complete the Map From mapping:
  • If the Map From value is Clipboard, enter a property reference that is the source of the data. If this is a Queue When mapping or the mapping for a service that processes service requests asynchronously, enter Param.pxQueueItemID. For information see PDN articles Configure a service to queue a failed service request for another attempt or Configure a service to process requests asynchronously.
  • If the value is Constant, enter a literal text string. To include blank spaces in your text string, surround the string with double quotes.
  • If the value is XML Stream, enter a Stream Name key part of the XML Stream rule that is to generate the data. The system uses the Applies To class of this Connect MQ rule as the Applies To class of the XML Stream rule.
  • If the Map From value is HTML Stream, enter the Stream Name of the HTML rule that is to generate the data stream. The system uses the Applies To class of this Connect MQ rule as the Applies To class of the HTML rule.
  • If the Map From value is a Rule-Utility-Function from a MapFrom library, either select the property that holds the value to be processed by the function or leave this field blank, as appropriate for the function.

When replies are sent

The Pega Platform examines information in the arriving message, as well as the results of evaluating this Response tab, to determine whether to send a reply MQ message. The table below shows this computation.

Request type allows reply? Reply to Q and Reply to Q Mgr included in request header? Evaluation of this tab provides message content? Result
N N N No reply.
N N Y No reply, warning message added to the Pega Platform log.
N Y N No reply.
N Y Y Normal reply, information message added to log.
Y N N No reply, warning message added to log.
Y N Y No reply, warning message added to log.
Y Y N Reply with empty message, information message added to the Pega Platform log.
Y Y Y Reply.