About Transient Error Handling for a IBM webMethods Messaging Trigger

When building a webMethods messaging trigger, you can specify whether or not Integration Server retries a trigger service when the trigger service fails because of a transient error caused by a run-time exception.

A run-time exception (specifically, an ISRuntimeException) occurs when the trigger service catches and wraps a transient error and then reissues it as an ISRuntimeException. A transient error is an error that arises from a temporary condition that might be resolved or corrected quickly, such as the unavailability of a resource due to network issues or failure to connect to a database. Because the condition that caused the trigger service to fail is temporary, the trigger service might execute successfully if the Integration Server waits and then re-executes the service.

You can configure transient error handling for a webMethods messaging trigger to instruct Integration Server to wait an specified time interval and then re-execute a trigger service automatically when an ISRuntimeException occurs. Integration Server re-executes the trigger service using the original input document.

When you configure transient error handling for a webMethods messaging trigger, you specify the following retry behavior:

  • Whether Integration Server should retry trigger services for the webMethods messaging trigger. Keep in mind that a trigger service can retry only if it is coded to throw ISRuntimeExceptions.
  • The maximum number of retry attempts Integration Server should make for each trigger service.
  • The time interval between retry attempts.
  • How to handle a retry failure. That is, you can specify what action Integration Server takes if all the retry attempts are made and the trigger service still fails because of an ISRuntimeException.

You can also configure Integration Server and/or a webMethods messaging trigger to handle transient errors that occur during trigger preprocessing. The trigger preprocessing phase encompasses the time from when a trigger first receives a message from it’s local queue on webMethods messaging trigger to the time the trigger service executes.

For more information about transient error handling for trigger preprocessing, see Transient Error Handling During Trigger Preprocessing.

Service Requirements for Retrying a Trigger Service for a IBM webMethods Messaging Trigger

To be eligible for retry, the trigger service must do one of the following to catch a transient error and reissue it as an ISRuntimeException:

  • If the trigger service is a flow service, the trigger service must invoke pub.flow:throwExceptionForRetry. For more information about the pub.flow:throwExceptionForRetry, see the webMethods Integration Server Built-In Services Reference .
  • If the trigger service is written in Java, the service can use com.wm.app.b2b.server.ISRuntimeException(). For more information about constructing ISRuntimeExceptions in Java services, see the webMethods Integration Server Java API Reference for the com.wm.app.b2b.server.ISRuntimeException class.

If a transient error occurs and the trigger service does not use pub.flow:throwExceptionForRetry or ISRuntimeException() to catch the error and throw an ISRuntimeException, the trigger service ends in error. Integration Server will not retry the trigger service.

Adapter services built on Integration Server 6.0 or later, and based on the ART framework, detect and propagate exceptions that signal a retry if a transient error is detected on their back-end resource. This behavior allows for the automatic retry when the service functions as a trigger service.

Note: Integration Server does not retry a trigger service that fails because a ServiceException occurred. A ServiceException indicates that there is something functionally wrong with the service. A service can throw a ServiceException using the EXIT step.

For more information about the EXIT step, see webMethods Service Development Help .

Handling Retry Failure

Retry failure occurs when Integration Server makes the maximum number of retry attempts and the trigger service still fails because of an ISRuntimeException. When you configure retry properties, you can specify one of the following actions to determine how Integration Server handles retry failure for a webMethods messaging trigger.

  • Throw exception. When Integration Server exhausts the maximum number of retry attempts, Integration Server treats the last trigger service failure as a service error. This is the default behavior.
  • Suspend and retry later. When Integration Server reaches the maximum number of retry attempts, Integration Server suspends the webMethods messaging trigger and then retries the trigger service at a later time.

Overview of Throw Exception for Retry Failure

Throwing an exception when retry failure occurs allows the webMethods messaging trigger to continue with document processing when retry failure occurs for a trigger service. You can configure audit logging in such a way that you can use webMethods Monitor to submit the document at a later time (ideally, after the condition that caused the transient error has been remedied).

The following table provides an overview of how Integration Server handles retry failure when the Throw exception option is selected.

Step Description
1 Integration Server makes the final retry attempt and the trigger service fails because of an ISRuntimeException.
2 Integration Server treats the last trigger service failure as a service exception.
3 Integration Server rejects the document.

If the document is guaranteed, Integration Server returns an acknowledgement to the webMethods Broker.

If a trigger service generates audit data on error and includes a copy of the input pipeline in the service log, you can use webMethods Monitor to re-invoke the trigger service manually at a later time. Note that when you use webMethods Monitor to process the document, it is processed out of order. That is, the document is not processed in the same order in which it was received (or published) because the document was acknowledged to its transport when the retry failure occurred.

4 Integration Server processes the next document in the webMethods messaging trigger queue.

Overview of Suspend and Retry Later for Retry Failure

Suspending a webMethods messaging trigger and retrying the trigger service later when retry failure occurs provides a way to resubmit the document programmatically. It also prevents the webMethods messaging trigger from retrieving and processing other documents until the cause of the transient error condition has been remedied. This preserves the publishing order, which can be especially important for serial webMethods messaging triggers.

The following table provides more information about how the Suspend and retry later option works.

Step Description
1 Integration Server makes the final retry attempt and the trigger service fails because of an ISRuntimeException.
2 Integration Server suspends document processing and document retrieval for the webMethods messaging trigger temporarily.

The webMethods messaging trigger is suspended on this Integration Server only. If the Integration Server is part of a cluster, other servers in the cluster can retrieve and process documents for the webMethods messaging trigger.

Note: The change to the webMethods messaging trigger state is temporary. Document retrieval and document processing will resume for the webMethods messaging trigger if Integration Server restarts, the webMethods messaging trigger is enabled or disabled, or the package containing the webMethods messaging trigger reloads. You can also resume document retrieval and document processing manually using Integration Server Administrator or by invoking the pub.trigger:resumeRetrieval and pub.trigger:resumeProcessing public services.
3 Integration Server rolls back the document to the webMethods messaging trigger document store. This indicates that the required resources are not ready to process the document and makes the document available for processing at a later time. For serial webMethods messaging triggers, it also ensures that the document maintains its position at the top of webMethods messaging trigger queue.
Note: When the watt.server.dispatcher.messageStore.redeliverOriginalMessage parameter is set to true,Integration Server stores and resubmits the original message after retry failure. If the parameter is set to false, Integration Server stores the message as it is at that point in trigger service execution. If the trigger service modified the message, Integration Server stores the modified message and uses that as input for subsequent trigger service execution. The default value of the watt.server.dispatcher.messageStore.redeliverOriginalMessage parameter is false.
4 Optionally, Integration Server schedules and executes a resource monitoring service. A resource monitoring service is a service that you create to determine whether the resources associated with a trigger service are available. A resource monitoring service returns a single output parameter named isAvailable.
5 If the resource monitoring service indicates that the resources are available (that is, the value of isAvailable is true), Integration Server resumes document retrieval and document processing for the webMethods messaging trigger.

If the resource monitoring service indicates that the resources are not available (that is, the value of isAvailable is false), Integration Server waits a short time interval (by default, 60 seconds) and then re-executes the resource monitoring service. Integration Server continues executing the resource monitoring service periodically until the service indicates the resources are available.

Tip: You can change the frequency at which the resource monitoring service executes by modifying the value of the watt.server.trigger.monitoringInterval property.
6 After Integration Server resumes the webMethods messaging trigger, Integration Server passes the document to the webMethods messaging trigger. The webMethods messaging trigger and trigger service process the document just as they would any document in the trigger queue.
Note: At this point, the retry count is set to 0 (zero).

Configuring Transient Error Handling for a IBM webMethods Messaging Trigger

About this task

The transient error handling behavior that you specify for a webMethods messaging trigger determines how Integration Server handles transient errors that occur during trigger service execution. The selected behavior also determines how Integration Server handles transient errors that occur during trigger preprocessing.

For more information about transient error handling for trigger preprocessing, see Transient Error Handling During Trigger Preprocessing.

To configure transient error handling for a webMethods messaging trigger

Procedure

  1. In the Package Navigator view of Designer, open the webMethods messaging trigger for which you want to configure retry behavior.
  2. In the Properties view, under Transient error handling, select one of the following for Retry until property:
    Select... To...
    Max attempts reached Specify that Integration Server retries the trigger service a limited number of times.

    In the Max retry attempts property, enter the maximum number of times Integration Server should attempt to re-execute the trigger service. The default is 0 retries.

    Successful Specify that the Integration Server retries the trigger service until the service executes to completion.
    Note: If a webMethods messaging trigger is configured to retry until successful and a transient error condition is never remedied, a trigger service enters into an infinite retry situation in which it continually re-executes the service at the specified retry interval. Because you cannot disable a webMethods messaging trigger during trigger service execution and you cannot shut down the server during trigger service execution, an infinite retry situation can cause the Integration Server to become unresponsive to a shutdown request. For information about escaping an infinite retry loop, see About Retrying Trigger Services and Shutdown Requests.
  3. In the Retry interval property, specify the time period the Integration Server waits between retry attempts. The default is 10 seconds.
  4. Set the On retry failure property to one of the following:
    Select... To...
    Throw exception Indicate that Integration Server throws a service exception when the last allowed retry attempt ends because of an ISRuntimeException.

    This is the default.

    For more information about the Throw exception option, see Overview of Throw Exception for Retry Failure.

    Suspend and retry later Indicate that Integration Server suspends the webMethods messaging trigger when the last allowed retry attempt ends because of an ISRuntimeException. Integration Server retries the trigger service at a later time. For more information about the Suspend and retry later option, see Overview of Suspend and Retry Later for Retry Failure.
    Note: If you want Integration Server to suspend the webMethods messaging trigger and retry it later, you must provide a resource monitoring service that Integration Server can execute to determine when to resume the webMethods messaging trigger. For more information about building a resource monitoring service, see Publish-Subscribe Developer’s Guide .
  5. If you selected Suspend and retry later, then in the Resource monitoring service property, specify the service that Integration Server should execute to determine the availability of resources associated with the trigger service. Multiple webMethods messaging triggers can use the same resource monitoring service.
  6. Click File > Save.

Results

Notes:
  • webMethods messaging triggers and services can both be configured to retry. When a webMethods messaging trigger invokes a service (that is, the service functions as a trigger service), the Integration Server uses the webMethods messaging trigger retry properties instead of the service retry properties.
  • When Integration Server retries a trigger service and the trigger service is configured to generate audit data on error, Integration Server adds an entry to the service log for each failed retry attempt. Each of these entries will have a status of “Retried” and an error message of “Null”. However, if Integration Server makes the maximum retry attempts and the trigger service still fails, the final service log entry for the service will have a status of “Failed” and will display the actual error message. This occurs regardless of which retry failure option the webMethods messaging trigger uses.
  • Integration Server generates the following journal log message between retry attempts:

    [ISS.0014.0031D] Service serviceName failed with ISRuntimeException. Retry x of y will begin in retryInterval milliseconds.

  • If you do not configure service retry for a webMethods messaging trigger, set the Max retry attempts property to 0. This can improve the performance of services invoked by the webMethods messaging trigger.
  • You can invoke the pub.flow:getRetryCount service within a trigger service to determine the current number of retry attempts made by the Integration Server and the maximum number of retry attempts allowed for the trigger service. For more information about the pub.flow:getRetryCount service, see the webMethods Integration Server Built-In Services Reference .

About Retrying Trigger Services and Shutdown Requests

While Integration Server retries a trigger service, Integration Server ignores requests to shut down the server until the trigger service executes successfully or all retry attempts are made. This allows Integration Server to process a document to completion before shutting down.

Sometimes, however, you might want Integration Server to shut down without completing all retries for trigger services. Integration Server provides a server parameter that you can use to indicate that a request to shut down the Integration Server should interrupt the retry process for trigger services. The watt.server.trigger.interruptRetryOnShutdown parameter can be set to one of the following:

Set to... To...
false Indicate that Integration Server should not interrupt the trigger service retry process to respond to a shutdown request. The Integration Server shuts down only after it makes all the retry attempts or the trigger service executes successfully. This is the default value.
Important: If watt.server.trigger.interruptRetryOnShutdown is set to “false” and a webMethods messaging trigger is set to retry until successful, a trigger service can enter into an infinite retry situation. If the transient error condition that causes the retry is not resolved, Integration Server continually re-executes the service at the specified retry interval. Because you cannot disable a webMethods messaging trigger during trigger service execution and you cannot shut down the server during trigger service execution, an infinite retry situation can cause Integration Server to become unresponsive to a shutdown request. To escape an infinite retry situation, set the watt.server.trigger.interruptRetryOnShutdown to “true”. The change takes effect immediately.
true Indicate that Integration Server should interrupt the trigger service retry process if a shutdown request occurs. Specifically, after the shutdown request occurs, Integration Server waits for the current service retry to complete. If the trigger service needs to be retried again (the service ends because of an ISRuntimeException), the Integration Server stops the retry process and shuts down. Upon restart, the transport (the webMethods Broker or, for a local publish, the transient store) redelivers the document to the webMethods messaging trigger for processing.
Note: If the trigger service retry process is interrupted and the transport redelivers the document to the webMethods messaging trigger, the transport increases the redelivery count for the document. If the webMethods messaging trigger is configured to detect duplicates but does not use a document history database or a document resolver service to perform duplicate detection, Integration Server considers the redelivered document to be “In Doubt” and will not process the document. For more information about duplicate detection and exactly-once processing, see Exactly-Once Processing for IBM webMethods Messaging Triggers.
Note: When you change the value of the watt.server.trigger.interruptRetryOnShutdown parameter, the change takes effect immediately.