Service JMS form
Completing the Response tab

Field

Description

Specify conditions that determine the format and content of the response message.

• Default — The Pega 7 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 7 Platform returns the specified response message data. If the list of response conditions does not include an entry for mapping errors, the Pega 7 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 7 Platform returns the specified response message data. If the list of response conditions does not include an entry for security errors, the Pega 7 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 7 Platform returns a standard error report message to the client application.

Tip: It is a best practice to configure the error conditions to ensure that the system notifies an administrator about the error.

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.

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.

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.

Field

Description

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.

Enter a short description of the header.

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.

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.

Field

Description

Select the data type of the message property, one of the Java primitive data types String, Boolean, Byte, Integer, Short, Long, Float, or Double.

Enter a short description of the message property.

Specify the source or the type of source of the value in the Pega 7 Platform. See the options described above for the Message Header section.

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.

Field

Description

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.

Enter a short description of the item you are mapping.

Specify the source or the type of source of the value in the Pega 7 Platform. See the options above for the Message Header section.

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.