Show TOC

Configuring User-Defined Message SearchLocate this document in the navigation structure

Use

When you know what information is available in the payload of a message or its dynamic header, you can find such a message using the user-defined search feature. The process of finding messages with this feature is the following:

  1. Define what kind of information you want to search.

    You need to create filters and define search criteria. First you create a filter where you specify for which interface, sender, and receiver you want to search messages. Then for each filter you create search criteria. For each search criterion, you specify in which elements of the payload or the dynamic header you want to search.

  2. Create an index of the messages for a specified period of time.

    The system checks which messages match the available filters and search criteria.

  3. In message monitor, choose search criteria, and specify the values you want to find.

    The system checks the index and displays only the messages that correspond to your search criteria. For more information, see Advanced Message Search .

Note You can use a user-defined search only for asynchronous messages.
Prerequisites

The user account you use should be assigned to one of the Process Integration monitoring roles. For more information about which roles allow you to view and modify messages, see Monitoring Roles .

Procedure

1. Prepare Test Messages

Prepare at least one test message that contains the payload to be indexed. Make sure that this message is processed successfully and, that you see it in the NWA Message Monitor. Open it with the NWA Message Editor and make sure that it has a version that includes the payload you target for indexing. For optimal performance make sure that you configure it as few message staging and logging versions as possible. Mark down the exact header data for the specific message version that you target for indexing as you will need them in the next steps.

2. View Filters

  1. Do one of the following to access the user-defined configuration options:

    • Open a browser and go to http://[host]:[port]/pimon to access the Process Integration tools. Then choose Start of the navigation path Configuration and Administration Next navigation step Adapter Engine Next navigation step User-Defined Search Configuration End of the navigation path.

    • Open a browser and go to http://[host]:[port]/nwa to access SAP NetWeaver Administrator. Then choose Start of the navigation path SOA Next navigation step Monitoring Next navigation step PI Adapter User-Defined Message Search End of the navigation path.

  2. Use the following options in the List of Filters screen area to display the filters:

    • Use the Show dropdown menu to display the active, inactive, or all filters.

    • Use the controls on the right to refresh the filter list, show or hide the search or filtering options, and select the size of the table displaying the filters.

3. Create Filters

  1. Do one of the following:

    • To create a new filter, choose the New button.

    • To edit existing filters, select them in the table and choose the Edit button.

      You can select many filters by holding the Ctrl or Shift key.

  2. Enter or modify the filter details as follows:

    • It is mandatory to enter the interface and namespace. When needed, you can create more than one filter for the same interface.

    • Set the status of the filter.

    • For new filters, it is mandatory to enter the filter's name.

    • Optionally, enter details about the sender and the receiver.

    Note Message header fields are matched literally, for example empty sender component will match only message versions with empty sender component. Use wildcard * to match any value.
  3. Choose Add to finish modifying the filter.

    Optionally, you can create new filter, or modify or delete some of the filters displayed in the list of unsaved filters.

  4. Choose Save .

4. Define Search Criteria

  1. Select the filter for which you want to define search criteria and choose the Search Criteria tab.

  2. Choose New to create new search criteria.

    If you want to edit some of the existing search criteria for this filter, select them and choose Edit .

  3. For new search criteria, enter a name and optionally a description.

  4. Select one of the following options for the type of the search:

    • Choose Dynamic Header if you want to search for additional information written to the message header by sender adapters. You need to enter the header and its namespace.

    • Choose XPath Expression if you want to search for information in a particular element or attribute inside the message payload.

      Example To find the OrderID in this XML:
      <urn: OrderReqMT xmlns:urn="urn:test"> 
          <Order>
              <ID>1</ID>
              <Name>nuts</Name>
          </Order>
      </urn: OrderReqMT>
      

      You would use XPath: //ns0: OrderReqMT/Order/ID and prefix definition with value: ns0 and namespace: urn:test.

      You need to enter the XPath expression using the rules of version 1.0 of the XPath language. For more information, see http://www.w3.org/TR/xpath/Information published on non-SAP site.

      Note You should only use XPath expressions that return a single value. Do not use XPath expressions that return whole subtrees, such as child::* or //Person (where Person is an element in the message payload that contains child elements).
  5. Choose Add to finish modifying the search criteria.

    Optionally, you can create new criteria, or modify or delete some of those displayed in the list of unsaved search criteria.

  6. Choose Save .

5. Define Namespace Prefixes

You can use a namespace prefix instead of a namespace in XPath expressions. You always define a namespace prefix for a given filter. You can then use it for all search criteria of type XPath for this filter. To define a namespace prefix, proceed as follows:

  1. In the filter list, select the filter for which you want to define the namespace prefix.

  2. Choose the Prefixes tab and then choose New .

  3. Enter the namespace and the prefix and choose Add .

    You can optionally define new prefixes or delete some of the unsaved prefixes.

  4. Choose Save .

6. Index Messages and Test Search Criteria

  1. You can test if a search criterion can locate a particular message as intended. To do this, choose Test Search Criteria , enter the ID of the message, specify the direction of the message, and run the test.
  2. Choose Indexing Options to create an index of the messages that match the active filters and search criteria.

    This index is used when you want to find messages in the message monitor with a user-defined search. You need to specify the start and end date of the period for which messages should be indexed. After the indexing starts, you can check whether the indexing job has been completed using the Indexing Status button.

7. Troubleshooting

  • Make sure that your filters and extractors are configured correctly using the Test Search Criteria. It is pointless to start the Index job if your test message could not be indexed correctly.
  • For the best performance, define specific filters that target the explicit message version. Limit the wildcards to avoid applying too many extractors.
More Information
  • The user-defined search is one of the many ways to find messages in the Advanced Adapter Engine using the message monitor. For more information, see Monitoring Messages .

  • The user-defined search is also available for searching messages in the Integration Engine. You can configure it using transaction SXMS_LMS_CONF. For more information, see the documentation of the Integration Engine.