Service SOAP 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.

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, 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 like "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 How to a service that queues failed service requests 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.
    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 key of the when condition rule to be evaluated. Otherwise, leave this blank.
Map From Select how the system finds the output data for the fault message:
  • Clipboard — The system maps the data value from the scalar property specified by the Map From key. This option may only be selected when a 'When' condition is being used.
  • Constant — The system returns a fixed value.
  • XML Stream — The system composes a stream of XML data formatted using an XML Stream rule. This option may only be selected when a 'When' condition is being used.
  • HTML Stream — The system composes a stream of HTML data formatted by an HTML rule. This option may only be selected when a 'When' condition is being used.
  • HTML Frame — The system returns a stream of HTML data generated by the service activity.
  • RequestorID — Send a text value identifying the current requestor session.
Map From Key Identify a source for the Map From selection:
  • If the Map From value is Clipboard, identify the property that is the source of the value.
  • If you selected Constant, enter a literal text string. To include blank spaces in your text string, surround it with double quotes.
  • For XML Stream, enter the Stream Name of the XML Stream rule that is to generate the data. The system uses the Primary Page Class of the service as the Applies To class of the XML Stream rule. Enter only the Stream Name key part.
  • For HTML Stream, enter the Stream Name of the HTML rule that generates the data stream. The system uses the Primary Page Class of the service as the Applies To class of the HTML rule. Enter only the Stream Name key part.
  • If the Map From value is HTML Frame, enter the name of the frame specified in a Show-HTML step of the service activity. Use this to return data from activities that were originally written for interactive browser clients and so contain the Show-HTML method.
  • For RequestorID, leave this blank.
Fault Detail Key Enter the Stream Name (second key part) of the XML Stream rule that is used to generate the data. The system uses the Primary Page Class of the service as the Applies To class of the XML Stream rule. Enter only the Stream Name key part. This option may only be selected when XML Stream is selected as the MapFrom value.

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