External Search of Messages Processed by Advanced Adapter Engine of PI/PO

Advanced Adapter Engine of SAP PI/PO systems is shipped with APIs which can be used for collection of information on message processing statistics by external applications, these APIs are exposed via HTTP protocol in a form of servlets and SOAP services and are well described in various materials on SCN (for example, see Andreas Job’s blog http://scn.sap.com/community/pi-and-soa-middleware/blog/2015/01/22/reading-messages-from-pi-system, Michal Krawczyk’s blogs http://scn.sap.com/community/pi-and-soa-middleware/blog/2010/04/13/pixi-how-to-get-a-pi-message-from-java-stack-aae-in-pi-711-from-abap, http://scn.sap.com/community/pi-and-soa-middleware/blog/2012/06/27/michals-pi-tips-how-to-get-rwb-message-overview-data-to-an-external-system, http://scn.sap.com/community/pi-and-soa-middleware/blog/2013/03/09/michals-popi-tips-audit-logs-from-a-native-ws–new-feature, my blog http://scn.sap.com/community/pi-and-soa-middleware/blog/2014/02/25/external-collection-of-message-processing-statistics-from-advanced-adapter-engine-of-pi) and in SAP Notes.

Besides from use cases already highlighted in referenced resources, often the requirement is not only to collect statistics about processed messages (like processed messages overview and performance statistics), often requirement is capability of searching for specific already processed messages by data contained in their payload. Advanced Adapter Engine is bundled with respective functionality named User-Defined Message Search (UDMS) being embedded into Message Monitor of PIMON, which provides capabilities for searching for processed messages based on values of elements of dynamic header or payload. For details on configuration of this functionality, see http://help.sap.com/saphelp_nw74/helpdata/en/48/b2e0186b156ff4e10000000a42189b/content.htm, for its usage – http://help.sap.com/saphelp_nw74/helpdata/en/48/b2dfe56b156ff4e10000000a42189b/content.htm. After UDMS is configured locally in Advanced Adapter Engine, it can be consumed centrally from Technical Monitoring workcenter of Solution Manager.

But these are not the only tools which can be utilized for fulfilling requirement of message search by payload for messages processed by Advanced Adapter Engine. The standard SOAP service AdapterMessageMonitoringVi, which is shipped with PI/PO, can help to achieve this goal – being exposed via the SOAP service, this functionality can be consumed by any external application / SOAP client. For example, this may be helpful if some external application system needs to search for processed messages in PI/PO knowing application data that has been sent out from that system. Or, if central monitoring system other than Solution Manager is used in the company.

The service itself was described in blogs of Andreas and Michal mentioned above, but I will concentrate on few operations of it, which were not well described before and which are of particular interest in the light of the topic of this blog. They are following three operations:

First two operations (getUserDefinedSearchFilters and getUserDefinedSearchExtractors) are used to retrieve information on UDMS configuration – such as configured filters and extractors.

In sake of demonstration, the following UDMS filter has been maintained:

The operation getUserDefinedSearchFilters doesn’t require any input in the request – when executed, it will provide a list of configured UDMS filters:

Knowing the interface and namespace which are subject for UDMS (for example, based on preceding call of getUserDefinedSearchFilters), we can search for respective extractors (search criteria) configured for it using the operation getUserDefinedSearchExtractors:

The third operation – getUserDefinedSearchMessages – can be used to search for messages utilizing already available UDMS configuration.

The service request element node attributes should contain UDMS specific search criteria – namely:

• BusinessAttribute – a list of search criteria and their values: name – UDMS search criteria / extractor name, value – searched value. These fields’ values are case sensitive, and mask symbols are permitted when specifying the searched value;
• operator – search mode. Valid values are: AND and OR. Values are not case sensitive. It is mandatory to provide the value for operator even if only one search criterion is specified. If operator value is not provided or is different from AND / OR, the service operation call will return error saying the operator is unknown.

Content of these fields can be mapped to their corresponding representations in user interface of Message Monitor, in the section User-Defined Search Criteria of advanced message search of it:

(please note that operator corresponds to the selector of search mode in user interface: AND = Message contains all values, OR = Message contains one of the values).

Below is the screenshot of SOAP request and response being outcome of querying the service operation AdapterMessageMonitoringVi.getUserDefinedSearchMessages(), for search criteria depicted above:

The service request which is analogous to the selection above, will be:

The service response returns amount of found messages matching provided search criteria (element node number) as well as detailed information regarding each of found messages (element nodes AdapterFrameworkData):

Besides from UDMS specific search criteria, other filters can be specified in the request in order to make messages search more precise and specific. Those filtering criteria are located in the service request section filter and correspond to sections Message Header Data, Technical Attributes and Identifiers of advanced message search of Message Monitor.