- SAP Managed Tags:
This blog describes how to configure explicit retries when using the new XI adapter, which will be available for customers with the 02-September-2018 release. It describes the configuration options in a sample scenario.
Using the XI sender and receiver adapter in EO scenarios connecting backends using XI protocol is described in the following two blogs:
XI Receiver Adapter: Configuring Scenario Using the XI Receiver Adapter
XI Sender Adapter: Configuring Scenario Using the XI Sender Adapter
With the basic configuration described in the two blogs, messages in error are retried forever according to the configured retry interval defined in the XI adapter. But there may be scenarios where you want to stop the retries after a defined number of retries and process the message in an alternative way, for example send the message via mail to another receiver. Or you want to notify the tenant administrator after some retries and after some more retries, if the message was still not successful process it in an alternative way.
This is possible after the 02-September-2018 release using explicit retry configuration in an exception subprocess. We will re-use the sample scenario setup in the blog for the XI receiver adapter and extend it using explicit retry configuration. Note, that you have to use the newest version of XI sender and receiver adapter. This means, if you want to extend an existing scenario you have to remove and re-create the XI channel to get the most recent version.
To configure such a scenario we need to add a Local Integration Process with the retry configuration and an Exception Sub-Process that catches the exception and calls the Local Integration Process for the retry handling. The scenario cannot be configured directly in the Exception Sub-Process because there only one end event is allowed, but we need an error and an end event to distinguish between continuing the retry or ending the retry.
First add a Local Integration Process to the integration flow. In this process, you configure the specific retry handling. In this sample, we check the number of retries executed, and after 6 unsuccessful retries, we end the processing and trigger a mail to alert someone about the problem.
These are the steps: In the local integration process, configure a Router after the start event, add an Error End Event and configure the Router. We need to check the header that counts the numbers of retries. This header is different for the two temporary storage options: JMS and Data Store.
Configure the router as shown in the pictures. The header is used to decide if the message processing continues or if it ends and a mail is triggered. If message processing is to continue, an error is raised by the process so that the message stays in the JMS Queue or Data Store and goes into retry status.
Configuration for Data Store Option:
Configuration for JMS Queue Option:
Furthermore, you need to add an Exception Subprocess in the main process, and add a Local Process Call, where you select the configured Local Integration Process, within the exception subprocess. Add a Receiver for the mail to be sent. Connect the Message End Event of the exception subprocess to the receiver using a Mail receiver channel. In this channel, you configure the mail address the mail is to be sent to and the details to be sent.
The following picture shows the configuration when an XI receiver adapter is used, but the same configuration can be used with XI sender adapter.
With this configuration, the message will be removed from the JMS queue/data store after 5 unsuccessful retries, so that no further retries are executed. A mail is triggered to notify the appropriate person to take manual action.
If you use the explicit retry configuration, you are free to configure retries as required for your scenario. For example, you can notify someone after 3 retries but not stop the processing until 10 retries have been made, to allow enough time for manual actions. Or, you can send the message after 3 retries via an alternative receiver channel.
As already mentioned you need the most recent version of the XI adapter to support explicit retry configuration. So, if you are extending an existing scenario, remove and re-create the XI channel. Use the same configuration settings you have used before.
Save and deploy the integration flow.
Execute your scenario as described in the blog Configuring Scenario Using the XI Receiver Adapter. To test the error case you may just enter some invalid address in the XI receiver channel. Check that you receive the notification mail and that the message is removed from JMS queue/Data Store.
Configuring Explicit Retry in Exception Subprocess for a Scenario Using the XI Adapter with Exactly Once Option
Using the XI sender and receiver adapter in EO scenarios connecting backends using XI protocol is described in the following two blogs:
XI Receiver Adapter: Configuring Scenario Using the XI Receiver Adapter
XI Sender Adapter: Configuring Scenario Using the XI Sender Adapter
With the basic configuration described in the two blogs, messages in error are retried forever according to the configured retry interval defined in the XI adapter. But there may be scenarios where you want to stop the retries after a defined number of retries and process the message in an alternative way, for example send the message via mail to another receiver. Or you want to notify the tenant administrator after some retries and after some more retries, if the message was still not successful process it in an alternative way.
This is possible after the 02-September-2018 release using explicit retry configuration in an exception subprocess. We will re-use the sample scenario setup in the blog for the XI receiver adapter and extend it using explicit retry configuration. Note, that you have to use the newest version of XI sender and receiver adapter. This means, if you want to extend an existing scenario you have to remove and re-create the XI channel to get the most recent version.
To configure such a scenario we need to add a Local Integration Process with the retry configuration and an Exception Sub-Process that catches the exception and calls the Local Integration Process for the retry handling. The scenario cannot be configured directly in the Exception Sub-Process because there only one end event is allowed, but we need an error and an end event to distinguish between continuing the retry or ending the retry.
Configure Retry Handling in Local Integration Process
First add a Local Integration Process to the integration flow. In this process, you configure the specific retry handling. In this sample, we check the number of retries executed, and after 6 unsuccessful retries, we end the processing and trigger a mail to alert someone about the problem.
These are the steps: In the local integration process, configure a Router after the start event, add an Error End Event and configure the Router. We need to check the header that counts the numbers of retries. This header is different for the two temporary storage options: JMS and Data Store.
- The header SAPJMSRetries is set by the JMS handler and can be used in case you configure the XI adapter with JMS Queue as temporary storage.
- The header SAP_DataStoreRetries is set by the data store handler and can be used in case you configure the XI adapter with Data Store as temporary storage.
Configure the router as shown in the pictures. The header is used to decide if the message processing continues or if it ends and a mail is triggered. If message processing is to continue, an error is raised by the process so that the message stays in the JMS Queue or Data Store and goes into retry status.
Configuration for Data Store Option:
Configuration for JMS Queue Option:
Configure Exception Sub-Process to Call the Local Integration Process
Furthermore, you need to add an Exception Subprocess in the main process, and add a Local Process Call, where you select the configured Local Integration Process, within the exception subprocess. Add a Receiver for the mail to be sent. Connect the Message End Event of the exception subprocess to the receiver using a Mail receiver channel. In this channel, you configure the mail address the mail is to be sent to and the details to be sent.
The following picture shows the configuration when an XI receiver adapter is used, but the same configuration can be used with XI sender adapter.
With this configuration, the message will be removed from the JMS queue/data store after 5 unsuccessful retries, so that no further retries are executed. A mail is triggered to notify the appropriate person to take manual action.
If you use the explicit retry configuration, you are free to configure retries as required for your scenario. For example, you can notify someone after 3 retries but not stop the processing until 10 retries have been made, to allow enough time for manual actions. Or, you can send the message after 3 retries via an alternative receiver channel.
Re-Create the XI Receiver Channel
As already mentioned you need the most recent version of the XI adapter to support explicit retry configuration. So, if you are extending an existing scenario, remove and re-create the XI channel. Use the same configuration settings you have used before.
Save and deploy the integration flow.
Run the Scenario
Execute your scenario as described in the blog Configuring Scenario Using the XI Receiver Adapter. To test the error case you may just enter some invalid address in the XI receiver channel. Check that you receive the notification mail and that the message is removed from JMS queue/Data Store.
15 Comments
