Fail Service (com.ibi.agents.XDFailAgent)

Syntax:

com.ibi.agents.XDFailAgent

iIT Service Object:

misc: Fail or cause retry of the message of the flow

Description:

The failure business service always returns an XDException. If the retry option is selected for the Type of failure parameter, the exception calls for a retry of the input, if possible. This service is useful when debugging rollback logic in a customer business service.

Parameters:

Parameter	Description
Type of failure	The type of failure to be thrown. Select one of the following values from the drop-down list: fail retry The default value is fail.
Message	The message to be issued to the user.
Bypass Catch Processing	On failure, determines whether to bypass upper-level Catch nodes. Select one of the following values from the drop-down list: true. Immediately ends this process thread with an uncatchable termination, bypassing error processing. false. Allows the Fail service to participate in normal catch error handling. The default value is true. The setting of this parameter has no effect on process flows with no Catch nodes, or when issued within the execution of a single Catch node. When multiple Catch nodes are employed in a process flow, the use of this parameter can impact the execution flow after failure. In this case, the usual setting should be true to cause the fail node to have immediate effect. Setting false will cause the failure request to be processed by upper-level Catch nodes.
Bypass Error Message	Indicates not to trace at the error level when this service terminates the process. This is useful for cases where the trace log is being monitored by an external program for errors. The termination will be traced at the debug level. The default value is false.
Add Transaction Log Report Message	When set, a transaction log entry (XALOG) is written with the failure message. This causes a message to appear in the transaction log analysis. The default value is false.
Call at EOS?	In a streaming environment, EOS (End of Stream) is the short message that is sent after the last document, which signifies the EOS. This parameter determines whether this service should be called for the EOS message. The default value is false.

Edges:

The following table lists the available line edges for the Fail Service (com.ibi.agents.XDFailAgent).

Line Edge	Description
OnError	Error
OnSuccess	Success
OnFailure	Failure
OnCustom	OnError OnSuccess OnFailure fail_parse

Example:

This service can be used in situations where a failure must be reported or simulated (for example, if a certain fatal condition is reported). If you run this service in a process flow using <test/> as the incoming message and the retry option is selected for the Type of failure parameter, the following document is returned:

<?xml version="1.0" encoding="UTF-8" ?>
<eda>
  <error code="6" timestamp="2009-06-05T19:56:59Z"
  source="com.ibi.agents.XDFailAgent" stage="AGENT">XD[RETRY] cause: 0
  subcause: 0 message: Retry requested from XDFailAgent</error>
</eda>

Otherwise, a retry is silent and the incoming message is retried later.

If the fail option is selected for the Type of failure parameter, the process flow handles the termination as an error condition by searching upward on the execution edge to locate a Catch node. If no Catch node is found, then the process flow is terminated. If a Catch node is found, then standard catch logic is bypassed unless the Bypass Catch Processing parameter is set to false.

It is not recommended to design process flows in which failure indications are used to control execution logic (for example, simulating a long jump). Failure indications should only be used in the event of actual failures.