Configuring Mappings in REST Web Service Listener Policies

The Mappings page enables you to map key and value strings contained in Web service requests to custom variables.

To access

• In the Operations Connector user interface, click in the toolbar. Then click Event > REST Web Service Listener.

• In the Operations Connector user interface, click in the toolbar. Then click Metrics > REST Web Service Listener.

Alternatively, double-click an existing policy to edit it.

Click Mappings to open the policy Mappings page.

Mappings overview

A custom mapping definition consists of a map name (variable), an optional input data property (XML element or XML attribute), and one or more source and target value pairs. For example, you can assign the XML element Severity to the map name mapSeverity, and add a source value of serious. You can then assign the target value critical to the variable so that Operations Connector inserts the value critical into the event in all places where the variable is used.

XML properties use the following syntax: <$DATA:/<XMLProperty>>

<XMLProperty> is the path from the root XML element of XML data to a specific XML element or attribute within that data. XML path uses slashes (/) as the path delimiters.

For example, the custom definition with the mapSeverity map name has the input data property of <$DATA:/PerformanceAlert/Severity> where Severity is a child element of PerformanceAlert.

XML properties are optional. If you do not assign an input data property to a map name (variable), you must add the source value directly to the variable when you insert the variable in an event attribute.

The Sample Data tab is empty if no sample data has been loaded into the policy or if the sample data does not match any specified XML tags.

The Sample Data tab shows the following information if sample data is available:

• XML Properties

  If sample data is available, the XML Properties section of the Sample Data tab shows all XML elements and attributes that match an XML tag.

  The XML Properties section by default shows the short path to the XML property or value. To view the full path, click . The full path begins with the XML tag specified in the Source tab.

  The items in the XML Properties section are by default sorted alphabetically in ascending order.

  To search for an XML property or value, type the search string in the Search Properties box. The list changes as you type; only matching items appear.

• Values for <XMLProperty>

  This section displays the values of an XML property selected in the XML Properties section. If a value appears more than once, click to show or hide duplicate values. To find values that belong to more than one XML property, select the value and click . The XML Sample Data window opens and shows all XML properties that have the selected value.

Tasks

How to configure REST Web Service mappings (events and metrics)

This task describes how to map XML elements and attributes to custom variables.

1. Create one or more custom variables.

   If you are working with sample data, drag the XML elements or attributes from the XML Properties list to the Map Name column. Operations Connector automatically adds the default prefix map to the map name and inserts the correct path to the XML property.

   Alternatively, click above the Map Name column and type the variable name in the map name field. XML properties are optional. If you do not assign an XML property to a variable, you must add the source value directly to the variable when you insert the variable in an event or a metric attribute.

2. Add source and target value pairs to each custom variable.

   • If sample data is loaded in Operations Connector and shortcuts to XML elements are defined, drag a value from the Values for '...' list to the Source Value column, and then type the target value in the corresponding field.

     Alternatively, c Click above the Source Value column and type the source and target values in the corresponding fields.

   • Optional. In the Indicators tab, add indicators to the source or target value fields. After loading the indicators from the OMi server, the Indicators tab shows a hierarchy of configuration item types.

     To insert an indicator in a source or target value field, drag the indicator state (for example, HTTPServer:Normal) from the Indicators tab and drop it on the corresponding field.

   • Optional. In the Policy Variables tab, add policy variables to event or metric attributes. Operations Connector replaces the variables with the appropriate values in the generated event or metric.

     Use quotation marks to surround variables, for example "<$MSG_NODE>" or "<$MSG_GEN_NODE>", at least for those variables whose values can contain space characters.

Related tasks

• How to Collect Event Data Through the REST Web Service Listener

• How to Collect Metrics Data Through the REST Web Service Listener

UI Descriptions

Policy VariablesTab

Policy Variables Tab for Database and REST Web Service Listener Policies (Events only)

Variable	Description
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the Operations Agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT>	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. The following severity conversions are performed when this variable is set by the Windows Event Log: information=Normal, warning=Warning, error=critical, success audit=Normal, failure audit=Critical, default=unknown).Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. For open message interface policies, this value is the msg_text parameter submitted by the opcmsg command. For the Windows Event Log this value is the event ID and description. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585
<$MSG_TYPE>	Delivers the name set for message type.

Policy Variables Tab for XML File and Structured Log File Policies (Events only)

Variable	Description
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT>	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. The following severity conversions are performed when this variable is set by the Windows Event Log: information=Normal, warning=Warning, error=critical, success audit=Normal, failure audit=Critical, default=unknown).Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. For open message interface policies, this value is the msg_text parameter submitted by the opcmsg command. For the Windows Event Log this value is the event ID and description. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585
<$MSG_TYPE>	Delivers the name set for message type.

Policy Variables Tab for Open Message Interface, Scheduled Task, and SNMP Interceptor Policies (Events only)

Variable	Description
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the Operations Agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT> (Open Message Interface and Scheduled Task Only)	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. The following severity conversions are performed when this variable is set by the Windows Event Log: information=Normal, warning=Warning, error=critical, success audit=Normal, failure audit=Critical, default=unknown).Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. For open message interface policies, this value is the msg_text parameter submitted by the opcmsg command. For the Windows Event Log this value is the event ID and description. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585
<$MSG_TYPE>	Delivers the name set for message type.
<$NAME> (Scheduled Task Only)	Returns the name of the policy that sent the event. Sample output: cpu_util
<$OPTION(N)> (Open Message Interface Only)	Returns the value of an optional variable that is set by opcmsgor opcmon (for example, <$OPTION(A)>, < $OPTION(B)>, and so on.).
<$PROG> (Scheduled Task Only)	Returns the name of the program executed by the scheduled task policy Sample output: check_for_upgrade.bat
<$USER> (Scheduled Task Only)	Returns the name of the user under which the scheduled task was executed. Sample output: administrator

Policy Variables Tab for All Policy Types (Metrics only)

Variable	Description
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.