Service EJB form - Completing the Exceptions tab

Use the Exceptions tab to specify exception information to be returned to the client application that sent the request when the EJB service encounters a fatal processing error. You can also use the Exceptions tab to specify other conditions that cause exception information to be returned to the client.

An exception is a fatal processing error in the service, preventing valid data from being returned using the normal return value process. You can also configure the system to return other, non-fatal activity status information to the client as part of the return value.

Field Description
Condition Select the condition that causes the system to return the specified data:
  • 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 the condition evaluates to 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 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 an exception of type PRQueuedRequestException that includes the queue item ID of the service request. To include additional information in the exception, 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 exception, so you do not need to explicitly include it in the mapping.)

    If you configure a Queue When condition, specify a request processor in the Request Processor field on the Service tab. For more information, see the 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 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.

If the condition value is Mapping Error, Security Error or Service Error, leave this field blank.

Map From Select the source or type of source of the exception message data.
  • Clipboard — The system maps the data value from the scalar property specified by the Map From Key value.
  • Constant — The system returns a fixed value that you specify in the Map From Key field.
  • XML Stream — The system composes a stream of XML text formatted by an XML Stream rule.
  • HTML Stream — The system composes a stream of HTML text formatted according to an HTML rule.
  • HTML Frame — The system returns a stream of HTML text generated by the service activity.
Map From Key The value that you specify in this field depends on the option you selected in the Map From field:
  • If the Map From value is Clipboard, enter the property name to which the data is to be mapped.
  • If the Map From value is Constant, enter a literal string. To include blank spaces in your text string, surround the string with double quotes.
  • For XML Stream, enter the Stream Name key part 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 key part.
  • For HTML Stream, enter the Stream Name key part of the HTML rule that is to generate the data stream. The system uses the Primary Page Class of the service as the Applies To key part.
  • For HTML Frame, enter the name of the frame specified as a parameter 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.