Service HTTP form - Completing the Response tab

Use the Response tab to specify how the service rule constructs the response that the Pega Platform sends in reply to the request. You can set up more than one response, based on conditions. You can also specify additional HTTP response codes to send with the response.

Important: Service HTTP rules are no longer being actively developed. To avoid upgrade issues when these rules are deprecated, use Service REST rules instead. For more information about Service REST rules, see Service REST rules.

When no response is configured on this tab, at run time the Pega Platform returns one of the following HTTP response codes by default:

200 — The request was processed without any errors.
500 — An error occurred during processing.
400 — An authentication problem occurred.

Conditions

To override any of those codes, specify a response on this tab. Define each condition with the following three fields:

Field	Description
Condition	Select one of the following conditions: Default Send this response when there are no errors to report. If you plan to set up more than one condition, configure the `Default` condition as the last one in the list. To send an HTTP response code other than 200, specify a different code for the Default condition in the HTTP Response Code field. When The system evaluates the when condition specified by the When Key field. If the condition is true, the system returns the response message data. If the condition is false, the system evaluates the next when condition rule in the list. If all listed 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 Pega Community article Configure a service to queue a failed service request for another attempt. Mapping Error If an error occurs while mapping incoming data from a request message to the clipboard, the service returns the specified response message data. If the list of response conditions does not include an entry for mapping errors, the Pega Platform returns the HTTP status code 500. Security Error If an error occurs while authenticating the 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 the HTTP status code 401. 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 message. Note: It is a best practice to configure the error conditions to ensure that the system notifies an administrator about the error.
When Name	Optional, but required if the Condition value is set to `When` or `Queue When`. Specify the name — second key part — of a when condition rule to evaluate for this condition. The system uses the first key part — the Applies To class — of the service activity as the first key part of the when condition rule.
Content Type	Select `text/plain`, `text/html`, or `text/xml` for the header in the outgoing message.
Status Code	Optional. Enter an HTTP status code to return to the external application with the response.

Header fields

By default, the Pega Platform sets values for the HTTP headers Server, Cache-Control, Content-Type, Content-Length, and Date in the response. Additionally, if the Processing Mode in the service package is set to Stateful, the system sends the Requestor ID value automatically to the client application as a token, in a cookie with the prefix PegaRULES.

If the response is include a header other than the ones that are set by default, complete the fields in this section. The data type of a header field is String.

Field	Description
Name	Enter the external name of the header field.
Description	Enter a short description of the header field.
Map From	Specify the source or the type of source of the value in the Pega Platform. `Clipboard` — Map from the page name or property on the clipboard specified by the Map From Key field. `Constant` — The data is a fixed value. If additional choices appear, they identify a custom function rule in a `MapFrom` library ( Rule-Utility-Function ). 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 property name to which the data is mapped at run time. If the Map From value is a Rule-Utility-Function from a `MapFrom` library, enter or select property that holds the value pass to the custom function at run time. If the Map To value is `Constant`, enter the value of the constant, surrounded by quotation marks.

Message Data

Use the fields in this section to define the data for the response. The data type of the message data is String.

Field Description

Description Enter a short description of the string in the response.

Field	Description
Description	Enter a short description of the string in the response.
Map From	Specify the source or the type of source of the value in the Pega Platform : `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 additional choices appear, they 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: Clipboard Enter the reference to the property. If this is a `Queue When` mapping or the mapping for a service that processes service requests asynchronously, enter `Param.pxQueueItemID`. For information see Pega Community articles Configure a service to queue a failed service request for another attempt or Configure a service to process requests asynchronously. Constant Enter a literal text string. To include blank spaces in your text string, surround the string with double quotes. XML Stream Enter either the Stream Name (second key part) 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 (found on the Service tab) as the first key part of the HTML rule. To maintain backward compatibility for service rules created in PRPC releases before PRPC Version 5.2, you can specify a data mapping with only a Namespace value. In that case, the system at run time determines the Element Name key part from the root element of the incoming XML document. However, this mapping works only if the Parser Type of the XML parse rule is set to `DOM` and validation is not enabled. As a best practice, specify both the Namespace Name and the Element Name of the rule. HTML Stream Enter either the Stream Name (second key part) 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. HTML Frame Enter the name of the frame specified in the Show-HTML step of the service activity. Use this option to return data from activities that were originally written for interactive browser clients and use the Show-HTML method. Rule-Utility-Function from a MapFrom library Either select the property that holds the value to be processed by the function at run time or leave this field blank, as appropriate for the function.

Map From

Specify the source or the type of source of the value in the Pega Platform :

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 additional choices appear, they 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:

Clipboard: Enter the reference to the property. If this is a Queue When mapping or the mapping for a service that processes service requests asynchronously, enter Param.pxQueueItemID. For information see Pega Community articles Configure a service to queue a failed service request for another attempt or Configure a service to process requests asynchronously.

Constant: Enter a literal text string. To include blank spaces in your text string, surround the string with double quotes.

XML Stream

Enter either the Stream Name (second key part) 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 (found on the Service tab) as the first key part of the HTML rule.

To maintain backward compatibility for service rules created in PRPC releases before PRPC Version 5.2, you can specify a data mapping with only a Namespace value. In that case, the system at run time determines the Element Name key part from the root element of the incoming XML document. However, this mapping works only if the Parser Type of the XML parse rule is set to DOM and validation is not enabled. As a best practice, specify both the Namespace Name and the Element Name of the rule.

HTML Stream: Enter either the Stream Name (second key part) 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.

HTML Frame: Enter the name of the frame specified in the Show-HTML step of the service activity. Use this option to return data from activities that were originally written for interactive browser clients and use the Show-HTML method.

Rule-Utility-Function from a MapFrom library: Either select the property that holds the value to be processed by the function at run time or leave this field blank, as appropriate for the function.