Intro
One of features that were available in ABAP stack of PI 7.1x systems and that its Java stack was lacking is customizable behavior of message persistence for various processing steps. Transition towards Java-only processing in PI brought special attention to this topic due to major requirements focusing on more precise monitoring of messages processed in Advanced Adapter Engine. One of very common use cases is the requirement to check payload of the processed message before and after mapping execution (for example, in order to identify correctness of the mapping execution for the particular message executed at runtime). As a result, several significant and very useful enhancements in this area - namely, customizable message staging and logging in Advanced Adapter Engine - were provided in PI 7.3x and extended in PI 7.31.
In this blog, I would like to summarize various message staging and logging options that are available in Advanced Adapter Engine of PI 7.3x.
Overview
Following message staging and logging options are available in Advanced Adapter Engine of PI 7.3x:
- Global staging/logging;
- Scenario-specific staging/logging using advanced settings of Integrated Configuration;
- Scenario-specific logging using adapter module in communication channel.
In PI 7.30, message staging customization is only possible globally for the entire Advanced Adapter Engine – meaning that all scenarios running in the corresponding Advanced Adapter Engine are affected by respective staging configuration. Customizable global message logging and scenario-specific staging/logging options are not available in PI 7.30 yet.
In PI 7.31, customizable global logging (originally for synchronous messages) mechanism as well as scenario-specific staging and logging options were introduced making it possible to customize staging and logging of messages in Advanced Adapter Engine differently for specific scenarios using advanced settings of Integrated Configuration or a dedicated adapter module configured in the respective communication channel.
In SP04 for PI 7.31, functionality of message logging is extended making it possible to use logging of asynchronous messages.
Before proceeding with discussion of various staging and logging options, let’s firstly highlight major differences between these two mechanisms of the message persistence in Advanced Adapter Engine.
Purpose of message staging is persistence of an asynchronous message at a particular runtime processing step (stage) for later editing/restart of the message from the persisted version as well as for displaying persisted (staged) message.
Purpose of message logging is persistence of any kind of an asynchronous/synchronous message at a particular runtime processing step for later displaying of the persisted (logged) message. Please note that editing or restart of the logged message is not possible.
Message logging is a more lightweight mechanism in comparison to message staging since there is less information persisted during logging (only information required for message displaying) than during staging (all information necessary for message displaying and restarting) as well as because during staging the persisted message is put to the queue and retrieved from it for processing steps where staging applies. Thus, in case of pure monitoring purposes, staging will bring more overhead to message processing, so logging is recommended in this case.
Redundant staging and logging configured for several (many) processing steps should be avoided since it brings negative impact to message processing time in Advanced Adapter Engine as well as additional load on database resulting in increased execution time of the scenario in PI and increased database growth rate.
Global staging/logging
Message staging and logging behavior is configured adjusting corresponding properties of the J2EE service XPI Adapter: XI:
- Property xiadapter.stage.conf – for staging configuration;
- Property xiadapter.logger.conf – for logging configuration.
For both mentioned properties, value syntax is composed by specifying processing step(s) and staging/logging mode (condition) for each of specified processing step. If messages should be staged/logged at several processing steps, respective step/mode pairs are delimited with comma ( , ).
Possible processing steps and modes that are relevant for staging are provided in tables below:
| Processing Step | Description |
|---|---|
| BI | After sender adapter processing, but before inbound schema validation |
| VI | Before scenario look-up step (check if scenario is local Advanced Adapter Engine based or dual-stack based involving Integration Engine) |
| MS | Before mapping step |
| AM | After mapping step, but before outbound schema validation |
| VO | After outbound schema validation |
| Mode | Description |
|---|---|
| 0 | MODE_NO_STORE: No message persistence (staging) |
| 1 | MODE_STORE_ON_ERROR: Message is persisted only if its next processing step (stage) throws an exception |
| 2 | MODE_STORE_AND_CONTINUE: Message is persisted and processing is continued with the next step. If its next processing step throws an exception, the processor reschedules the message from this storage and returns Note: the mode is deprecated in PI 7.31 due to performance inefficiency during message persistence |
| 3 | MODE_STORE_AND_RETURN: Message is persisted and rescheduled, processing is continued with the next step |
For logging, only processing steps BI, MS and AM are relevant.
Mode values that are relevant for logging are derived from 'basic' 4-bit binary values by summarization of respective 'basic' binary values and its further conversion to a decimal value. Relevant 'basic' values are enumerated in the table below:
| Binary Value | Description |
|---|---|
| 0000 | No logging |
| 0001 | Asynchronous messages are logged |
| 0010 | Synchronous messages are logged |
| 0100 | Onlу еrrοr mеѕѕаgеѕ аrе lοggеd |
| 1000 | Logging with cοntеnt hіdіng (payload is hidden) |
Sample custom configuration of global message staging is provided below:
In this example, asynchronous messages are persisted (staged) in two versions - before mapping and after mapping.
In Message Monitor, the persisted versions of the message can be observed (highligted on the screenshot below):
Please also note that during staging, the message was put into the queue and retrieved it multiple times (corresponding to amount of processing steps for which staging was configured and should be conducted for the processed message). This can be noticed when examining audit log of the message:
Similarly, sample custom configuration of global message logging is provided below:
In this example, asynchronous messages are persisted (logged) in two versions, at the same processing steps as in the global staging example - before mapping and after mapping.
In Message Monitor, the persisted versions of the message can be observed (highligted on the screenshot below):
In logging, there is no multiple operations of queue write (put) / read (retrieve) due to difference in nature of the logging mechanism in comparison to the staging mechanism:
Absence of additional queue write/read operations results in less overhead caused by logging than by staging - the effect that was already mentioned earlier in this blog.
Scenario-specific staging/logging using advanced settings of Integrated Configuration
Sometimes it is necessary to apply specific (more or less precise) staging or logging for the particular scenario - meaning that staging/logging configuration for the corresponding scenario should differ from the globally defined one (described in the previous section of the blog). In order to fulfill such a requirement, configuration of scenario-specific staging and logging can be performed using the tab 'Advanced Settings' of the Integrated Configuration object in PI 7.31. On this tab, the one can choose at which processing steps staging or logging should be activated for which modes.
Valid processing steps that can be chosen for staging and logging using advanced settings of Integrated Configuration are the same as those applicable for global staging and logging configuration and described earlier.
For staging, following modes are valid:
- None (no staging);
- Store (stage always);
- Store on error (stage only in case of error at subsequent processing step).
For logging, following modes are valid:
- None (no logging);
- Log (log always);
- Log on error (log only in case of error at subsequent processing step);
- Log without payload (log always, payload is hidden);
- Log on error without payload (log only in case of error at subsequent processing step, payload is hidden).
Sample configuration of combined options of staging and logging of Integrated Configuration is provided below:
In this example, messages (including their payloads) are persisted (staged) right after sender adapter processing and are further persisted (logged) before mapping and after mapping.
In Message Monitor, the persisted (both staged and logged) versions of the message can be observed (highligted on the screenshot below):
Scenario-specific logging using adapter module in communication channel
In PI 7.31, a SAP standard adapter module MessageLoggerBean is provided - this module can be inserted in the adapter module sequence of the corresponding communication channel.
Fully qualified adapter module name is localejbs/AF_Modules/MessageLoggerBean .
Adapter module parameters and their valid values are enumerated in the table below:
| Parameter Name | Description | Parameter Values |
|---|---|---|
| log.condition | Condition (mode) at which logging should be activated | Integer value derived from following 'basic' values:
|
| log.location | Optional parameter that specifies processing step within the adapter module processing sequence where the message should be logged | Name of the processing step within the adapter module processing sequence. If not specified, location default is used. |
Sample configuration of the adapter module processing sequence of the communication channel that utilizes the described adapter module is provided below:
In this example, asynchronous messages (including their payloads) that are processed by the receiver communication channel's SOAP adapter bean are persisted (logged).
Below is an extract of the audit log of the processed message were log entries reflecting execution of MessageLoggerBean are highlighted - as seen, logging mode (controlled by log condition adapter module parameter) is indicated:
In Message Monitor, the persisted version of the message can be observed, version of the message is controlled by log location adapter module parameter (highligted on the screenshot below):
Outro
Described staging and logging options can be employed in combination making staging and logging in Advanced Adapter Engine even more flexible.
For example, the below persisted versions of the processed message are outcome of joint usage of:
- Global staging before mapping;
- Scenario-specific logging after mapping for an utilized Integrated Configuration object;
- Adapter module MessageLoggerBean in a receiver communication channel for SOAP adapter bean log location.
References
There are also other very nice materials on SCN that cover message staging and logging functionality available in Advanced Adapter Engine of PI 7.3x - namely, it is highly recommended to go through following blogs to get additional information on the topic:
- PI/XI: PI 7.3 message version persistence for ICO integration flows - teaser, the blog written by Michal Krawczyk: http://scn.sap.com/community/pi-and-soa-middleware/blog/2010/10/18/pixi-pi-73-message-version-persis...
- Scenario specific message staging and logging in PI 7.31 AAE, the blog written by Nageshwar Reddy: http://scn.sap.com/community/pi-and-soa-middleware/blog/2012/07/26/scenario-specific-message-staging...
- Message Versioning in the Advance Adapter Engine of PI 7.30, the blog written by William Li: http://scn.sap.com/community/pi-and-soa-middleware/blog/2012/01/03/message-versioning-in-the-advance...
- SAP Managed Tags:
25 Comments
