Continued routing on failure is an Advanced Routing mode that provides custom error handling by, for example, enabling an output communication point to re-route messages for further processing upon transmission failure instead of sending them directly to the Error Queue.
This functionality is available at all times for communication points operating in Output, Out->In, and Bidirectional modes. Continued routing on failure is enabled on an output communication point when it is placed on the input side of the route, and its error output connector ('red lollipop') is connected to another component (in other words, a filter) in the route. Failed messages received by the communication point are sent to the Failed Queue for processing. Failed messages are populated with error-related message properties, which can be used to configure downstream route logic to handle failed messages automatically, instead of requiring manual user intervention when they are sent to the Error Queue. A failed message in this context is a message that fails to transmit due to message errors, connection errors (after retries have been exceeded), or as per the action configured in a message tracking scheme.
The Management Console enables you to search for failed messages via the Output Search page, and also provides message counts for the Failed Queue and Failed Archive (in addition to error messages in the Error Queue) for a communication point.
Continued routing on failure can be used in conjunction with continued routing on success, so that further actions can be performed for both successfully transmitted messages and failed messages by the same output communication point.
Refer to the following sections for details:
Configuring
To configure continued routing on failure:
Drag and drop an output communication point that requires failed message handling to the input side of the route.
An error output connector (as in the 'red lollipop' normally displayed for filters) is automatically displayed on the output communication point when it is placed on the route's input side. The error output connector is shown by default for all communication points placed on a route's input side that are configured in Output, Out→In or Bidirectional mode.
Rhapsody IDE does not display the error output connector for Sink, Dynamic Router and Error Message Redirector communication points because they transfer messages to another route within the engine and hence technically cannot fail to send.
- Use a connector to connect the error output connector to the components configured for processing failed messages in the route; if the error output connector is not connected, failed messages are sent to the Error Queue. For details on, messages that fail due to:
- Message errors, refer to Message Errors.
- Connection errors, refer to Connection Errors.
- A particular response code or error option configured in a message tracking scheme, refer to Message Tracking.
You can, if required, combine continued routing on success with continued routing on failure. In this case, a connector can be placed on the communication point to components in the route to handle successful messages, and the communication point's the error output connector can be connected to components to handle failed messages.
In the following example, the route receives processed messages from an upstream route and uploads them to an SFTP Server via an (S)FTP Client communication point running in Output mode. Using Advanced Routing, when a message is successfully transmitted, the (S)FTP Client communication point sends a notification to users via an Email Client communication point. When the upload fails with a 5xx server return code (indicating a message error), the (S)FTP Client communication point uses a message property to send the message to a database that stores failed messages. If the upload fails for any other reason, the message is sent to a backup SFTP Server.
Connection Errors
Connection errors are transmission failures that typically occur because a communication point could not connect to an external system after exceeding the maximum number of connection retries configured per message.
To enable continued routing on failure for connection errors, set the communication point's Retries Exceeded Action to Treat as error in the Connection Retries panel under the Connection tab in the communication point's properties dialog. Refer to Connection Retries for details.
Additionally, for communication points in Out→In mode, connection errors are also defined as occurring when no response is received after response timeouts and the maximum number of resends. To enable continued routing on failure in this case, set the communication point's Fail Action to Treat as error or Treat as error and close connection in the Out->In Mode Connection Properties panel under the Connection tab in the communication point's properties dialog. Refer to Out->In Mode Connection Properties for details.
When a connection error occurs, the failed message is sent to the error output connector (if the error output connector of the communication point is connected). The following standard message properties are added to the failed message to provide the reason for the failure, so that connected downstream components can determine what course of action to take:
| Message Property | Description |
|---|---|
rhapsody:ErrorCause |
Is set to:
|
rhapsody:ErrorCommunicationPointId |
Provides the identifier of the communication point where the message failed. |
rhapsody:ErrorCommunicationPointName |
Provides the name of the communication point where the message failed. |
In previous versions of Rhapsody before Rhapsody 6.5, the connection retries exceeded action for communication points has an option to send messages that fail only to the Error Queue. With the introduction of continued routing on failure, the Send to Error Queue option has been replaced by Treat as error. The new option enables routes to handle failed messages if required, or send them to the Error Queue.
Consequently, options to redirect messages to input or output communication points have been marked as deprecated for connection errors. While these deprecated options still function as before, it is recommended you use Advanced Routing functionality instead.
Message Errors
Message errors are transmission failures that typically occur when a communication point sends a message that is rejected by a receiving system.
When a message error occurs, the failed message is sent to error output connector (if the error output connector of the communication point is connected). The following standard message properties are added to the failed message to provide the reason for the failure, so that connected downstream components can determine what course of action to take:
| Message Property | Description |
|---|---|
rhapsody:ErrorCause |
Is set to |
rhapsody:ErrorCommunicationPointId |
Provides the identifier of the communication point where the message failed. |
rhapsody:ErrorCommunicationPointName |
Provides the name of the communication point where the message failed. |
The following communication points provide additional information for the reason a message error occurred via published message properties. These message properties are supplied when the communication point is unsuccessful in transmitting a message over a connection and receives an error response from the server indicating the failure reason.
Communication Point |
Supported Mode |
Message Properties |
Description |
|---|---|---|---|
| (S)FTP Client | Output, Out→In | sftp:ReplyCode |
An FTP server return code. |
| Database | Output, Out→In |
|
A success or failure code that conforms to SQL standards. |
database:ErrorCode |
A vendor specific error code. |
||
database:ErrorReason |
A detailed description of the error. |
||
| Database Insertion | Output |
|
A success or failure code that conforms to SQL standards. |
|
A vendor specific error code. |
||
|
A detailed description of the error. |
||
| HTTP Client |
Output, Out→In* |
ResponseCode |
An HTTP response code. |
ResponseMessage |
An HTTP response status. |
*The message properties already exist for the HTTP Client communication point in Out→In mode. They are made available for the adjacent downstream component when using Advanced Routing.
User-determined Message Failures
Rhapsody automatically determines whether a failed message has occurred as a result of a message error or connection error. However, for the following communication points, users can specify whether to treat failed messages as message errors or connection errors, for certain failure causes, by setting a specific configuration property:
| Communication Point | Configuration Property | Value |
|---|---|---|
| Database | Message Errors |
|
| HTTP Client | Dynamic Connection Failed Action |
|
On 4xx Error Response |
|
|
On 5xx Error Response |
|
|
| TCP Client | Dynamic Connection Failed Action |
|
Message Tracking
Failed messages can also be generated by a message tracking scheme as part of response handling and error handling.
In previous versions of Rhapsody before Rhapsody 6.5, message tracking has options to send failed messages only to the Error Queue. With the introduction of continued routing on failure, the Send to Error Queue option has been replaced by Treat as error. The new option enables routes to handle failed messages if required, or send them to the Error Queue.
Consequently, options to redirect messages to input or output communication points have been marked as deprecated for message tracking response and error handling options. While these deprecated options still function as before, it is recommended you use Advanced Routing functionality instead.
Response Handling
In a message tracking scheme, users can specify a message to be treated as failed for a particular response code. This is configured in the message tracking scheme's Response Handling tab by setting Action when received to Treat as error. Refer to Maintaining Message Tracking Schemes for details.
Error Handling
In a message tracking scheme, users can specify a message to be treated as failed for no response and other errors. These are configured in the message tracking scheme's Error Handling tab by setting Action after maximum resends to Treat as error. Refer to Maintaining Message Tracking Schemes for details.
Message Properties
A failed message is sent to the error output connector of the communication point (if the error output connector of the communication point is connected). The following standard message properties are added to the failed message to provide the reason for the failure, so that connected downstream components can determine what course of action to take:
| Message Property | Description |
|---|---|
rhapsody:ErrorCause |
Provides the reason why the message was sent to the Failed Queue:
|
rhapsody:ErrorCommunicationPointId |
Provides the identifier of the communication point where the message failed. |
rhapsody:ErrorCommunicationPointName |
Provides the name of the communication point where the message failed. |
Monitoring
Message Events
On the Management Console's Message View page, message events are displayed in a single path for a communication point using continued routing on failure. A message failing to send is indicated as a message event in Message View:
Failed Queue
Communication points, with continued routing on failure configured, send failed messages to a queue called the Failed Queue for processing.
The Monitoring Communication Points page displays:
- The number of unprocessed failed messages on the Failed Queue for a communication point.
- The total number of failed messages processed by a communication point in the Failed Archive.
The Communication Point Details page displays:
- A graph depicting failed message throughput statistics for the communication point.
- The number of messages failed by the communication point since the communication point was created and started for the first time.
- The number of messages failed by the communication point since the count was reset.
- The number of messages queued for processing by the communication point via Advanced Routing (continued routing on failure), but which cannot be sent on because the receiving system is unavailable.
- Whether the communication point is configured to continue routing on success.
Output Search
Output search results include messages that have failed as a result of connection errors or message errors. Refer to Output Search for details.
Notifications
A notification alert is raised if the Failed Queue of a communication point is not empty for a user-defined period of time. Refer to Default Settings for the default settings for notification thresholds for communication points.
Infinite Loop Detection
As in the case of the Dynamic Router communication point, communication points using Advanced Routing provide some built-in protection against accidental infinite loops through a configurable limit on the number of times that a single input message can be sent by a communication point. Refer to Infinite Loop Detection for details.