Service JMS form - Completing the Response tab

If the JMS service uses the Point-to-Point messaging model and the request messages will have a queue or topic specified in their JMSReplyTo header fields, use the Response tab to specify how the service rule constructs the response to be sent. You can set up more than one response, based on conditions. (If the JMS service uses the Publish-Subscribe messaging model, responses are not expected; leave this tab blank.)

The list of response conditions is evaluated in order, and the first condition that evaluates to true determines the response data returned to the client. The system sends responses to the queue specified in the JMSReplyTo header value in the request message.

Response Condition

Field Description
Response Condition  
Condition Specify conditions that determine the format and content of the response message.
  • Default — The Pega Platform does not evaluate the data. It returns the specified response message data. Enter Default in the last row in the array.
  • When — The system evaluates the when condition specified by the When Key field. If true, it returns the response message data. If false, it continue evaluating the next when condition rule in the list. If all specified when condition rules are false, it returns the default response data. Use this feature to extend the normal set of fatal error conditions that result in exceptions returned to the client, such as inappropriate inputs to the service activity or other tests you define.
  • 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 Pega Platform returns the specified response message data. If the list of response conditions does not include an entry for mapping errors, the Pega Platform returns a standard error report message to the client application.
  • Security Error — If an error occurs while authenticating the application client credentials, the Pega Platform returns the specified response message data. If the list of response conditions does not include an entry for security errors, the Pega Platform returns a standard error report message to the client application.
  • Service Error — If a service error occurs, the system sends the specified response message data. If the list of response conditions does not include an entry for service errors, the Pega Platform 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 Key Optional. If the Condition value is When or Queue When, specify the name — second key part — of the when condition rule to be evaluated.

For example, your service activity can set a property value to 0 initially, and to a positive integer when it detects any application-related issues. The when condition rule can test whether the property has a non-zero value.
Message Type Select the type of the response:
  • None — No response is sent.
  • Empty Message — Contains a message with headers and/or message properties, but no message data.
  • Text Message — Contains one java.lang.String object.
  • Object Message — Contains one serializable Java object
  • Bytes Message — Contains a stream of bytes with no explicit structure.
  • Stream Message — Contains a stream of Java primitive values, Java objects, or byte arrays. Map their values in the order in which they are to appear in the response.
  • Map Message — Contains a list of name/value pairs with names as string objects and values as string or other Java objects, Java primitive types, or byte arrays.
Requestor Options Indicate whether the system is to keep this requestor session open, or close it after it sends the response message for this condition.

If the requestor session is left open, the client application can reuse this requestor session by referencing it in the PegaRULES_SessionID property of the next request message.

Message Headers

Click the triangle to access these fields. If the response is to include JMS headers, complete the fields in this section.

Field Description
Name Select the type of JMS message header:
  • JMSType — A value that has meaning to the application sending the message. For example, the values of the JMSType header can be used as message selector criteria by the JMS listener that routes messages to this service rule.
  • JMSCorrelationID — the JMS listener that routes messages to this service rule automatically copies the value from the JMSMessageID message header from the request message to this header in the response. To override the default value for JMSCorrelationID, map a value for it on this tab.
  • JMSDeliveryMode — One of the literal values NON_PERSISTENT or PERSISTENT.
  • JMSPriority — A priority value 0 to 9.
  • JMSTimeToLive — A value in milliseconds that specifies how long the message is to stay on the queue.
Description Enter a short description of the header.
Map From Specify the source or the type of source of the value in your application:
  • Clipboard — The source is a property or a page on the clipboard.
  • Constant — The source is a fixed value that does not change.
  • XML Stream — The source is a stream of XML data formatted by an XML Stream rule.
  • HTML Stream — The source is a stream of HTML data formatted by an HTML rule.
  • HTML Frame — The source is a stream of HTML data generated by the service activity.

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

Map From Key Specify the key to locating the property or rule in the source specified in the Map From field:
  • If the Map From value is Clipboard, enter the reference to the property.
  • 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.
  • If the Map From value is XML Stream, enter either the Stream Name (second key) of the appropriate XML Stream rule or a page name and stream name using the syntax PageName.StreamName. (The page must be on the clipboard when the service rule runs for rule resolution to find the rule.) If you specify the stream name only, the system uses the Page Class of this service rule (on the Service tab) as the first key part of the HTML rule.
  • If the Map From value is HTML Stream, enter either the Stream Name (second key) of the appropriate HTML rule or a page name and stream name using the syntax PageName.StreamName. (The page must be on the clipboard when the service rule runs for rule resolution to find the rule.) If you specify the stream name only, the system uses the Page Class of this service rule (on the Service tab) as the first key part of the HTML rule.
  • If the Map From value is HTML Frame, enter the name of the Frame specified in the Show-HTML step of the service activity. Use this to return data from activities that were originally written for interactive browser clients and use the Show-HTML method.
  • 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.

Message Properties

Use the fields in this section to map data for any JMS properties defined by the application sending the request.

The Pega Platform provides four application-specific JMS properties that contain information for response messages. (See More about JMS Listeners for details on these properties.) Do not map the values of those properties — they are managed by the listener and are included only when necessary.

Field Description
Data Type Select the data type of the message property, one of the Java primitive data types String, Boolean, Byte, Integer, Short, Long, Float, or Double.
Description Enter a short description of the message property.
Map From Specify the source or the type of source of the value in the Pega Platform. See the options described above for the Message Header section.
Map From Key Specify the key to locating the property or rule in the source specified in the Map From field. See the options listed above for the Message Header section.

Message Data

Use the fields in this section to define the body of the response message. Note the following:

  • If the Message Type is set to Empty Message, do not create any rows in this section.
  • If the Message Type is set to Text Message, include one row only in this section. The data type of the mapping must be set to String.
  • If the Message Type is set to Object Message, include one row only in this section. The data type of the mapping must be set to Object.
  • If the Message Type is set to Stream Message, create data mappings for each of the items in the stream in the order in which they will be received.
Field Description
Data Type Select the data type of the item you are mapping, one of the Java primitive data types String, Boolean, Byte, Integer, Short, Long, Float, or Double.
Description Enter a short description of the item you are mapping.
Map From Specify the source or the type of source of the value in the Pega Platform. See the options above for the Message Header section.
Map From Key Specify the key to locating the property or rule in the source specified in the Map From field. See the options listed above for the Message Header section.

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.