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.
