LinkedIn
Copied!

Table of Contents

Service SAP form - Completing the Faults tab

Use the Faults tab to specify data returned to the client application when the service encounters a fatal processing error and must return a SOAP fault message. You can also use the Faults tab for other conditions that you want to cause SOAP fault messages to be returned.

Service SAP rules are no longer being actively developed, and are being considered for deprecation in upcoming releases. Using Service SAP rules does not follow Pega development best practices. Use Service SOAP rules instead. For more information, see Service SOAP rules.

A fault is a fatal processing error in the service, such that valid data cannot be returned by the normal output parameter process. In addition to the fault message, the Pega Platform returns an HTTP Code 500 Internal Server Error.

You can also have the system return other, non-fatal activity status information to the client as the value of a response parameter set on the Response tab.

Field Description
Fault conditions
Condition Select the condition that causes the system to return the data you specify:
  • When — The system evaluates the when condition rule specified by the When key field. If the condition evaluates to true, the system returns an exception with the specified data. If false, the system continues evaluating the next when condition rule in the list. If all specified when condition rules return false, the system returns the normal response data specified on the Parameters tab to the client application. 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 a Pega Platform-specific SOAP fault that includes the queue item ID of the service request. To customize the fault reason string provided in the SOAP fault, select Constant from the Map from field and enter a string such as, "Object was locked - queued for retry." (The queue item ID is provided in the SOAP fault detail string, so you do not need to explicitly include it in the mapping.) Note that 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 the request message to the clipboard, the system returns an exception with the specified data. If the list of response conditions does not include an entry for mapping errors, the system returns a standard exception to the client application.
  • Security Error — If an error occurs while authenticating the application client credentials, the system returns an exception with the specified data. If the list of response conditions does not include an entry for security errors, the system returns a standard exception to the client application.
  • Service Error — If a service error occurs, the system returns an exception with the specified data. If the list of response conditions does not include an entry for service errors, the system returns a standard exception to the client application.
    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 key of the when condition rule to be evaluated. Otherwise, leave this blank.
Map from

Specify the source of the SOAP fault reason value:

The SOAP fault reason is also known as the SOAP faultstring in SOAP 1.1.
  • Clipboard — Map the SOAP header value from a property on the clipboard
  • Constant — Provide the literal value to send as the value of the SOAP header.
Map from key Specify the key of the property or rule from which to map the SOAP fault reason value:
  • If the Map From value is Clipboard, identify the property that is the source of the value.
If you selected XML Literal as the data type, the property value must contain text that is formatted as well-formed XML.
Fault detail key If you intend to return a value for the SOAP fault detail element, enter the Stream Name (second key part) of the XML Stream rule that is used to generate the data. The system assumes that the XML Type key (second key part) of the XML Stream rule is the constant value MapFrom. The system uses the page class of this service rule as the first key part of the stream rule.

For an example of this facility, see Pega Community article How to customize SOAP fault messages.

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.