Writing Log Entries to Audit Log of the Message from Custom Java Mapping Program

When utilizing custom Java mapping programs, it is a common requirement to enrich them with the tracing/logging features that would be useful for further runtime analysis and troubleshooting by bringing more transparency to executed logic at least in part of major transformation steps.

The most commonly used approach that is well documented in SAP Help and often utilized and described on SCN is usage of trace entries. Trace entries can be inserted from the custom developed mapping program to runtime trace and further accessed via NetWeaver Log Viewer from PI application traces or collected by XPI Inspector.

Technically, this is achieved by employing corresponding methods of the object AbstractTrace (like methods com.sap.aii.mapping.api.AbstractTrace.addInfo(),com.sap.aii.mapping.api.AbstractTrace.addWarning()). The AbstractTrace object is, in its turn, obtained from AbstractTransformation (by invoking method com.sap.aii.mapping.api.AbstractTransformation.getTrace()) – that is the standard class extended by the custom class implementing transformation logic of the developed mapping program.

Utilization of trace functionality has some significant drawbacks that prevent its usage for normal monitoring activities – namely:

• Increased trace severity level can negatively impact performance of traced applications. This is especially critical in case the system is used under high volume. As an outcome of this, precise traces are normally enabled for a short period of time (for example, when reproducing or facing the error) and are switched off / reduced to a lower severity level afterwards;
• Trace output contains lots of detailed information collected and recorded at runtime for the traced application. As a result, further manual analysis of trace output may become a time consuming and complex activity.

For more information on insertion of trace entries in application to custom developed mapping programs, please refer to following materials:

• SAP Help documentation on AbstractTrace object: http://help.sap.com/saphelp_nw73ehp1/helpdata/en/4b/f416e4eaca4c86e10000000a42189e/content.htm ;
• “Attachments zipping during Mapping“, the blog written by Praveen Gujjeti: http://scn.sap.com/docs/DOC-26528 ;
• “Mapping Trace in SAP PI 7.31 Single Stack“, the blog written by Kapila Epasinghe: http://scn.sap.com/community/pi-and-soa-middleware/blog/2013/09/18/tracing-in-sap-pi-731-single-stack .

If the intention is to extend processing log of PI messages with important information on custom mapping program execution that can be used by PI monitoring team, it is more natural to interact with audit log of the processed message. The motivation of this web blog is to provide a sample code snippet that can be used in custom mapping programs in order to add necessary information to the audit log of the message.

In this approach, the backbone is usage of Audit Log Manager functionality in part of interacting with the audit log of the specific message. The whole logic that needs to be implemented can be described as a sequence of following steps:

1. Retrieve message ID and convert it to the format that is compliant to RFC 4122;
2. Retrieve message direction;
3. Based on obtained message ID and direction, construct message key;
4. For the constructed message key, add audit log entry using methods of the interface AuditAccess.

The code fragment below illustrates how this can be achieved programmatically:

// Retrieve message ID from input header (com.sap.aii.mapping.api.InputHeader)
// of transformation input (com.sap.aii.mapping.api.TransformationInput).
String msgID = arg0.getInputHeader().getMessageId();
// Convert message ID to UUID format (in compliance to RFC 4122).
// UUID format is used by Advanced Adapter Engine for identifiers of processed messages.
// For the sake of simplicity, conversion is done manually - alternatively, specific libraries can be used for this.
final String DASH = "-";
String uuidTimeLow = msgID.substring(0, 8);
String uuidTimeMid = msgID.substring(8, 12);
String uuidTimeHighAndVersion = msgID.substring(12, 16);
String uuidClockSeqAndReserved = msgID.substring(16, 18);
String uuidClockSeqLow = msgID.substring(18, 20);
String uuidNode = msgID.substring(20, 32);
String msgUUID =
     uuidTimeLow + DASH + uuidTimeMid + DASH + uuidTimeHighAndVersion + DASH
     + uuidClockSeqAndReserved + uuidClockSeqLow + DASH + uuidNode;
// Construct message key (com.sap.engine.interfaces.messaging.api.MessageKey)
// for retrieved message ID and outbound message direction (com.sap.engine.interfaces.messaging.api.MessageDirection).
MessageKey msgKey = new MessageKey(msgUUID, MessageDirection.OUTBOUND);
// Add new audit log entry with status ‘Success’ (com.sap.engine.interfaces.messaging.api.auditlog.AuditLogStatus)
// to the audit log (com.sap.aii.af.service.auditlog.Audit) for the constructed message key.
Audit.addAuditLogEntry(msgKey, AuditLogStatus.SUCCESS,
     "Demo: This is an audit log entry that have been generated by custom mapping program");

As an outcome, the respective log entry is available in the audit log of the processed message and can be displayed for example using Message Monitor in PIMON:

Please note that instead of directly accessing the object com.sap.aii.af.service.auditlog.Audit, it is also possible to have an “extended” style of retrieving message audit log accessor using public API provided in the bounds of PI. This is normally superfluous for custom mapping programs, but may be useful when accessing Messaging System of PI externally:

try {
     // Retrieve instance of audit log accessor (com.sap.engine.interfaces.messaging.api.auditlog.AuditAccess)
     // using public API access factory (com.sap.engine.interfaces.messaging.api.PublicAPIAccessFactory).
     AuditAccess msgAuditAccessor = PublicAPIAccessFactory.getPublicAPIAccess().getAuditAccess();
     // Add new audit log entry with status ‘Success’ to the audit log of the message using the constructed message key.
     msgAuditAccessor.addAuditLogEntry(msgKey, AuditLogStatus.SUCCESS,
          "Demo: This is an audit log entry that have been generated by custom mapping program");
     } catch (MessagingException e) {
          // Exception handling logic.
          e.printStackTrace();
     }

For more information on corresponding used Java objects, please refer to PI Javadocs that are available on SAP Help: http://help.sap.com/javadocs/NW73EHP1/SPS09/PI/index.html .