Administer > Policies > XML File Policies > XML File Policy User Interface > Configuring the Data Source in XML File Policies

Configuring the Data Source in XML File Policies

The source page of the XML file policy editor enables you to specify which XML file the policy reads. You can also set options that configure how the policy reads the file.

To access

  • In the Operations Connector user interface, click Create in the toolbar. Then click Event > XML XML File.

  • In the Operations Connector user interface, click Create in the toolbar. Then click Metric > XML XML File.

  • In the Operations Connector user interface, click Create in the toolbar. Then click Topology > XML XML File.

  • In the Operations Connector user interface, click Create in the toolbar. Then click Generic output > XML XML File.

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

Click Source to open the policy Source page.

Requirements for XML source files (events)

XML files must meet the following criteria so that they can be processed correctly by XML file policies:

  • XML file requirements:

    • Use file rolling to create two or more XML input files. Operations Connector first reads the oldest file before starting to process the oldest of the newer files. Each file should not be larger than 2 GB.

      You can use the asterisk (<*>) wildcard string in the Log File Path / Name text box on the Source page to match multiple file names. For example, to match the XML source file names events.1.xml and events.2.xml, use the pattern <path>/events<*>.xml in the Log File Path / Name text box. Note that the <*> wildcard string is the only supported OMi pattern in log file paths.

      When using file rolling, make sure the Close after reading option on the Source page is selected.

    • Make sure the polling interval is shorter than the frequency in which data is written to the file. The polling interval must not be shorter than 15 s, otherwise the policy cannot be saved.

  • XML format requirements:

    • The root element is optional.

    • If a root element exists, it must not be closed by its end tag.

    • All other XML elements must be complete.

    The following example XML document begins with the root tag <AllAlerts> and contains two types of events: performance alerts and availability alerts. If you define the XML elements <PerformanceAlert> and <AvailabilityAlert> as XML event tags in the Source page of XML file policies, only those events are processed by XML file policies.

    Example: 

    <AllAlerts>
      <AvailabilityAlert>
         <Title>Host Unreachable</Title>
         <Severity>Critical</Severity>
         <TimeOccured>02/11/10 03:52:18AM</TimeOccured>
         <Object>Host:fish.example.com</Object>
      </AvailabilityAlert>
      <PerformanceAlert>
         <Title>Disk IO rate high</Title>
         <Severity>Warning</Severity>
         <TimeOccured>02/11/10 04:08:31AM</TimeOccured>
         <Object>Disk:disk0:dog.example.com</Object>
      </PerformanceAlert>
      <AvailabilityAlert>
         <Title>Web Application unresponsive</Title>
         <Severity>Critical</Severity>
         <TimeOccured>02/11/10 05:01:26AM</TimeOccured>
         <Object>WebApp:http://employeeportal.intra.example.com</Object>
      </AvailabilityAlert>
      <PerformanceAlert>
         <Title>Phyiscal Read Rate high for Bufferpool BP1</Title>
         <Severity>Warning</Severity>
         <TimeOccured>02/11/10 08:37:09AM</TimeOccured>
         <Object>DB:USRDB:cat.example.com</Object>
      </PerformanceAlert>
      <PerformanceAlert>
         <Title>Phyiscal Read Rate high for Bufferpool BP1</Title>
         <Severity>Warning</Severity>
         <TimeOccured>02/11/10 08:37:09AM</TimeOccured>
         <Object>DB:USRDB:cat.example.com</Object>
      </PerformanceAlert>
    </AllAlerts>

Requirements for XML files (topology)

XML files must follow the topology discovery syntax.

Tasks

How to configure the XML source (events and metrics)

This task describes how configure the XML source file and how the policy reads it.

  1. Type the full path to the XML file on the Operations Connector system.

  2. Click to load a sample XML file. You can load a sample file from the Operations Connector system or from the system where the Web browser runs.

    When you load sample data, Operations Connector replaces already loaded data with the new data. This does not affect any mappings that are defined based on previously available sample data.

  3. Click Create a new XML event tag to create one or more XML tags. You can create a tag manually by typing the XML element. If you are working with sample data, you can create a tag by double-clicking the XML element in the list.

    The XML tag creates a shortcut to the XML element that you want the policy to process. An event tag typically identifies an event record in an XML log file, while a metric tag identifies a metric record in an XML log file. You can define more than one XML tag. For example, an XML file may contain two types of events: <PerformanceAlert> and <AvailabilityAlert>. To process both types, define both elements as event tags.

How to configure the XML source (topology)

This task describes how configure the XML source file and how the policy reads it.

  1. Type the full path to the XML file on the Operations Connector system.

  2. Enter the age to deletion - the number of times for the policy to be run for a host that is not part of the topology data. After this number of policy executions, this host is deleted from the server.

  3. Optionally, enable delta detection, so that only the difference between the received XML file and the repository is sent to the topology server.

Related tasks

UI Descriptions

Policy Source Page

UI Element Description

Log File Path / Name
Events and Metrics only)

Topology XML File
(Topology only)

Path and name of the XML file that the policy reads. Type the drive letter and the full path for the location of this file on the Operations Connector system.

You can use the following configurations to make your policy more flexible:

  • Windows environment variables (for example, winnt or clusterlog). The syntax for these variables is <$variablename>, for example <$winnt>.

  • Script or command that returns the path and name of the log file you want to access. For example, type <`command`> where command is the name of a script that returns the path and name of the log file you want the policy to read.

    The command can also return more than one log file path separated by spaces. Operations Agent processes each of the files using the same options and conditions as configured for this policy. This is very useful when you want to dynamically determine the log file path or process multiple instances of a log file.

  • Pattern matching. The pattern-matching language enables you to very accurately specify the file names that you want the policy to match. For example, you can use the pattern <path>/events<*>.xml to match XML source file names such as events.1.xml and events.2.xml.

Operations Connector cannot process XML files that are larger than 2 GB.
Polling Interval

Determines how often the policy reads the XML file (in days, hours, minutes, and seconds). This period of time is the polling interval. The larger polling interval is set, the less performance is needed. However, more memory is used (this depends on the amount of the data in the XML file). Setting the polling interval below 30 seconds is not recommended, the default setting is usually appropriate.

Note that a policy begins to evaluate data after the first polling interval passes, unless the Read from beginning (first time) or Read from beginning (always) radio button is selected, which results in evaluation of the first data at the policy activation. A shorter polling interval is better when you are testing a policy.

Default value: 5 minutes

Make sure that you set this value to a minimum of 15 seconds to be able to save the policy.

Logfile Character Set
(Event and Metrics only)

Name of the character set used by the XML file that the policy reads.

It is important to choose the correct character set. If the character set that the policy is expecting does not match the character set in the XML file, pattern matching may not work, and the event details can have incorrect characters or be truncated in OMi. If you are unsure of which character set is used by the XML file that the policy reads, consult the documentation of the program that writes the file.

Default value: UTF-8

Send event if log file does not exist (Events and Metrics only)

Send OMi event if topology file does not exist
(Topology only)

Operations Connector sends an event if the specified XML file does not exist.

Default value: not selected
Close after reading
(Events and Metric only)

If you select this option, the file handle of the XML file closes and reopens again after the polling interval. The XML file is read from the last position. If this file had a rollover in the meantime, it is read from the beginning. If the name of the XML file changes, and a new file was started in the meantime, the policy continues to read the new XML file and the original XML file data is lost.

If you do not select this option, the file handle remains and is read entirely each time, unless there is a newer file with the same name (or name pattern). In that case the original XML file is read to the end, and then the newer file is read. Therefore, no data is lost.

Consider the following example: a policy reads the XML file system.xml.While there is still some unread data in the system.xml file, it is renamed to systemMonday.xml, and a new version of the system.xml file is written.

In case this option is selected, the unread data from the systemMonday.xml file remains unread and the system.xml file is read entirely.

In case this option is not selected, the unread data from the new system.xml file is read after the reading of the systemMonday.xml file is completed.

Default value: not selected

Read Mode (Events and Metric only)

The read mode of an XML file policy indicates whether the policy processes the entire file or only new entries.

Read from last position. The policy reads only new—appended—entries written in the XML file while the policy is activated. If the file decreases in size between readings, then the entire file is read. Entries that are added to the file when the policy is disabled are not processed by the policy.

Choose this option if you are concerned only with entries that occur when the policy is enabled.

Advantage: No chance of reading the same entry twice. (Unless the file decreases in size because some entries were deleted.)

Disadvantage: Entries written to file while the policy is disabled or the agent is not running are not processed by the policy.

Read from beginning (first time). The policy reads the complete XML file each time the policy is activated or the agent restarts. This ensures that all entries in the file are compared with the rules in the policy. Each successive time that the policy reads the file, only new (appended) entries in the file are processed.

Choose this option if you want to ensure that every existing and future entry in the file is processed by the policy while it is activated.

Advantage: Every existing and future entry in the file will be processed by the policy.

Disadvantage: Duplicate entries can occur if an activated policy is deactivated and reactivated, or if the agent stops and restarts.

Read from beginning (always). The policy reads the complete XML file every time it detects that the file has changed. The policy scans the file at the specified polling interval. If no change is detected, the file is not processed. Any entries overwritten while the agent is not running or the policy is deactivated will not be evaluated by the policy.

Choose this option if the policy reads a file that is overwritten, rather than appended.

Advantage: Ensures that files that are overwritten are correctly processed.

Disadvantage: Only valid for files that are overwritten, rather than appended.

Every policy reads the same XML files independently from any other policies. This means, for example, that if "Policy 1" with read mode Read from beginning (first time) is activated and "Policy 2" with the same read mode already exists, "Policy 1" still reads the entire file after it has been activated.

Default value: Read from last position

Sample Data
(Events and Metrics only)

Enables you to upload an XML sample file. Operations Connector makes the XML elements and values of the sample file available to you in the Event and Rules pages so that you can insert them by dragging and dropping.

Load sample data from server. Loads an XML sample file from the OMi Connector system.

Load sample data from local file system. Loads an XML sample file from the system where the Web browser runs.

Operations Connector can only load a maximum of 50 MB of sample data.
Opens the XML Sample Data dialog box. This dialog box displays the contents of the uploaded XML sample file.
XML Event Tag
(Events only)

Enables you to specify one or more XML event tags. The XML event tag creates a shortcut to the XML element that you want to process. An event tag typically identifies an event record in an XML file. You can define more than one event tag.

Create new XML event tag manually. Enables you to type an XML element in the provided box.

Create new XML event tag from XML sample data. Opens the XML Sample Data Outline dialog box. This dialog box displays the XML elements and attributes contained in the uploaded XML sample data.

Deletes the selected XML event tag.

Deleting an event tag that is referenced in a policy corrupts the policy and renders it unusable.
XML Metric Tag
(Metrics only)

Enables you to specify one or more XML metric tags. The XML metric tag creates a shortcut to the XML element that you want to process. A metric tag typically identifies a metric record in an XML file. You can define more than one metric tag.

Create new XML metric tag manually. Enables you to type an XML element in the provided box.

Create new XML metric tag from XML sample data. Opens the XML Sample Data Outline dialog box. This dialog box displays the XML elements and attributes contained in the uploaded XML sample data.

Deletes the selected XML metric tag.

Deleting a metric tag that is referenced in a policy corrupts the policy and renders it unusable.
Detect deltas
(Topology only)

A delta is the difference between the received XML file and the repository. The delta is the bare minimum of information about the changes. It discovers all changes without regards to the RTSM model.

If an instance or relation is not discovered for a certain amount of time (Age to deletion), it is deleted. The counter goes up each time when the algorithm is running (this depends on the interval and the last time the file was written / sent via web service).

If not selected,no delta detection is done and the incoming topology file is directly sent to the topology server.

Default value: selected.

Age to deletion(Topology only)

A number of times for the policy to be run for a host that is not part of the topology data. After this number of policy executions, this host is deleted from the server.

Related topics

Pattern-Matching Details

Topology Discovery Syntax

Send Help Center feedback