Collecting Business Context for Integration & Exception Monitoring

With Integration & Exception Monitoring you can not only collect technical message and error information, but also use product specific mechanisms to collect business context from the payload of the messages. 

You can now use the integrated search mechanism in Integration & Exception Monitoring to search for it and find related messages with a certain value across platforms, e.g. find all messages related to a certain sales order number from the ABAP backend to the middleware like SAP Process Integration or SAP Cloud Platform Integration. 

Prerequisites

To successfully display and search for business context information in Integration & Exception Monitoring, please make sure that your user has the following authorizations:

  • Authorization object FRN_AIM with ACTVT=27

 

SAP Process Integration

For messages sent via SAP Process Integration you use so called User-Defined Search Attributes (UDS) to collect the payload information from messages.

Configuration in SAP PI

The setup of the User-Defined Message Search is performed in the SAP PI system. You can define user-defines search attributes in the Advanced Adapter Engine, as well as in the integration Engine.

For more information please refer to the SAP Help Portal:

* for Process Integration in SAP NetWeaver 7.5 this section is under "Message Packaging"

Configuration in SAP Focused Run

The configuration for the data collection is done in the Integration & Exception Monitoring setup.

  1. Open the Integration & Exception Monitoring setup for the PI Java system
  2. Make sure you select the category 'PI Messages'
  3. Create a new Filter and add the name for the UDS attribute in the filter 'UDS Attribute Name'
  4. If you want to collect more than one UDS attribute, you can add an additional entry for the filter field 'UDS Attribute Name' by clicking on the "+" icon in the upper right corner of the filter field table
  5. Enter the interface name and the interface namespace if you plan to collect UDS attributes
  6. Save your entries.

The collected UDS attributes will be visible in Integration & Exception on the tab 'UDS Attributes' in the PI message details.

IDoc

For IDoc messages the collection of the payload content is configured in SAP Focused Run.

Collect Content Information

The first step is to collect the information on the message types, segments and fields that you want to collect from the IDoc.

  1. Log on to the managed ABAP backend system
  2. Go to transaction WE05
  3. Enter the message type to find an IDoc you want to collect business context from
  4. Double-click on the IDoc to open it
  5. Open the sub-tree Data records and click on the segment that contains the fields you want to collect
  6. The field list will be displayed to the right

Note down: Message Type, Segment name, and Field name (Fld name)

Configuration in SAP Focused Run

The data collector for the IDoc business context is customized via table /IMA/EDID4COLL. 

  1. Find LMDB ID: The LMDB ID for the ABAP backend system is the field LMDBID of table /IMA/TSCONFIG.
  2. Add an entry to table /IMA/EDID4COLL:
    • LMDBID: The LMDB ID of the ABAP backend system from step 1
    • MESTYP: The message type of the IDoc
    • DIRECTION: IDoc Direction
      • 1 Outbound
      • 2 Inbound
    • COUNTER: Enter a number that you didn't use before for the same LMDBID/MESTYP/DIRECTION combination. This allows you to collect more than one field from the same IDoc
    • SEGNAM: The segment name of the content in the IDoc
    • FNAME: The field name (Fld name) of the content in the IDoc
    • NOTIF_RULE: This field specifies whether the business attributes should be sent in the email notification. A value of 'X' indicates that the business attributes are not sent for that combination.
  3. Save your changes.

The collected payload information will be visible in Integration & Exception Monitoring on the tab 'Additional Attributes' of the IDoc details.

SAP Integration Suite - Cloud Integration

The collection of business context from messages sent via SAP Cloud Integration is done using Groovy scripts in SAP Cloud Integration. 

Collect Content Information

To collect payload information via a Groovy script, you need to create a so called Exchange Property for the step after which you want to collect the payload. To do this, you first need to find out the XPath of the information you want to extract.

  1. Change log level of the Integration Flow to Trace
    1. Log on to your SAP Cloud Integration tenant
    2. Go to Operations View → Manage Integration Content → Select your Integration Flow → Log Configuration → Set log level to Trace
  2. Run the Integration Flow
  3. Extract the payload from the Integration Flow instance
    1. Go to Operations View → Monitor Message Processing → Select the instance that ran with the trace → Logs
    2. Click on the blue highlighted word Trace
    3. Select the step to which you plan to add the Exchange Property and after which you plan to add the Groovy script
    4. Go to Message Content → Payload
    5. Click on Download Payload
  4. Rename the .body file to .xml
  5. Open the file in an XML editor
  6. Build the XPath by separating the tags to the content of interest by '/' (see example below)

Example: Creating XPath from Message Body

To create the XPath you have to describe the path from the start of the XML message to the information you are interested in.

In this example you want to extract the Campaign ID. The XML file is pictured below.

The XPath for the Campaign ID would be:

/n0:LeadBulkReplicationRequest/LeadRequestMessage/Lead/Campaign/ID


Adjust IFlow

The next step is to adjust the IFlow and add an exchange property as well as adding a Groovy script.

Add Exchange Property

  1. Navigate to Design → <Package> → Artefacts → <IFlow>
  2. Switch to edit mode
  3. Select the step in the iFlow from which you want to extract the payload
  4. Go to Content Modifier → 'Exchange Property'
  5. Add a new property
    1. Enter a name
    2. Select type 'XPath'
    3. Enter the XPath you created in the step before as value
Create Groovy Script
  1. In the left-side navigation bar click Message Transformers → Script → Groovy Script
  2. Select the arrow that leaves the step from which you want to extract the payload
  3. Click on the Groovy Script step → '+' (Create) button
  4. Replace the code of the processData method in then script with the lines in the panel below
  5. Save the changes
  6. The script file will be created and assigned to the Groovy Script step (Groovy Script → Processing → Script File)

Groovy Script Code

def Message processData(Message message) {

       //Properties 

       map = message.getProperties();

       value = map.get("<Exchange Property name>");

       def messageLog = messageLogFactory.getMessageLog(message);

       messageLog?.addCustomHeaderProperty("<Exchange Property name>", value)

       return message;

}

Configuration in SAP Focused Run

In SAP Focused Run you have to set up the monitoring for the SAP CPI system as described here. No additional setup is necessary. 

The collected payload information are visible in Integration & Exception Monitoring on the tab 'Custom Headers' in the message details.

Web Services

For Web Services the payload is collected by maintaining the filter field "Payload Field Name" during the Integration & Exception Monitoring setup.


Collect Content Information

The first step is to collect the payload field name from the web service message.

  1. Log on to the managed ABAP backend system
  2. Go to transaction SRT_MONI
  3. Enter the search parameters to find one web service message for the web service you are interested in
  4. Double-click on the web service message to open it
  5. Select 'Message Body'
  6. Click the button 'Original XML' to open the formatted XML message
  7. Find the attribute you are interested in
  8. Note down the XML tag name


Configuration in SAP Focused Run

The configuration for the data collection is done in the Integration & Exception Monitoring setup.

  1. Open the Integration & Exception Monitoring setup for the ABAP system
  2. Make sure you select the category 'Web Service Messages (ABAP)'
  3. Create a Filter and add the XML tag name in the filter 'Payload Field Name'
  4. If you want to collect more than one payload attribute, you can add an additional entry for the filter field 'Payload Field Name' by clicking on the "+" icon in the upper right corner of the filter field table
  5. Save your entries.

The collected payload information are visible in Integration & Exception Monitoring on the tab 'Additional Attributes' in the web service message details.