Path Editor

Overview

This guide provides information on how you can modify paths in Active Console and helps you use them for configuring links and rules in your workspace. Also, this covers the discussion about the different type of paths that determine which dataviews can be displayed in the metric table or list views, and elements in path editor.

Each component or data item in the Active Console has its own path with the following elements that are critical to match the specified item for setting targets, rules, modifiers, and links. These are the default paths for some data items that you can configure in path editor:

The path provides a fully qualified path to the component, starting from the Gateway. For more information about paths, see XPaths.

Types of path editor

There are different types of path editor that you can use to edit a path.

Data item path editor

The Data item path editor performs basic path functionality, such as defining targets for rules.

You can access the data item path editor by:

• Go to Gateway Setup Editor > Rules > Targets.
• Searching data items using the Advanced mode in the Search and Reporting dockable.
• Editing the paths in the workspace list view settings.

Geneos URL editor

The Geneos URL defines the path that can be integrated in the dashboard objects, dropped item, invoke selection, user selection, and web pages. This is mostly used in modifying the URL links, object's paths, and data sets in the Active Dashboard.

You can access the Geneos URL path editor by:

• Editing the paths and properties in Notifier Manager.
• Editing the modifier in the workspace list view settings.
• Refactoring a path using the Advanced Mode in the Refactor Tool.

Expert mode path editor

The Expert mode path editor only appears when a previously entered path contains a syntax that the editor cannot convert correctly. A dialog appears that allows you to manually edit the path, instead of dragging and dropping elements from the editor.

For more information, see Use expert mode path editor.

Path editor basic interface

The Path Editor includes the following main areas:

An example interface of a blank data item path editor:

Right-clicking the selected elements in the work area of the path editor gives you these options:

Double-clicking the selected element gives you additional element properties to edit:

Note: The list of elements properties vary depending on the tool or element you have selected.

Path editor tools and elements

New elements can be added to the path using the tools available in the toolbar. The following tools are available for the Data item path editor and the Geneos URL editor.

Data item elements

All these data item elements are available for Data Item and Geneos URL path editor:

Relative path elements

The table shows the relative path elements available for the data item editor and Geneos URL path editor:

Element/Tool	Data item path editor	Geneos URL path editor	Description
This			Matches the previous element. It can be used to create relative paths in the rule editor.
Parent			Matches the parent of the previous element. If the previous element is a managed entity, then it matches the probe the entity is in.
Child			The default separator. Normally, this is added (and removed) automatically as required when the path configurable is in auto-complete mode.
Descendants			Matches to all children of the previous element. If the previous element is a managed entity, then adding this to the end of the path matches to all samplers, dataviews, headlines, and managed variables that are contained within the managed entity.
Ancestor or self			Matches to the previous element and all ancestors of that element. If the previous element is a managed entity, then adding this to the end of the path matches the probe and Gateway that the managed entity is in.
Ancestors			Matches all ancestors of the previous element. If the previous element is a managed entity, it matches the probe and Gateway the managed entity is in.
Client			Matches a specific client (as specified in the host and port). The client is the system running the Active Console. This can be used when passing parameters to a command to be run on the client.
Descendants or self			Matches to the previous element and all children of that element. For example, if the previous element is a managed entity, then adding this to the end of the path matches to all samplers, dataviews, headlines and managed variables that are contained within the managed entity. This also matches the managed entity itself.
View Path			These are usually the managed entity attributes. This creates a managed entity element, and then bring up the properties for that element so you can change the view path settings. It is present for convenience, since these properties can also be accessed through managed entity element.
All Elements			Can be used when creating Append, Merge, and Replace to tell the system which elements to modify. All Elements causes the Append, Merge, or Replace to be applied to all element in the preceding path.
Last Element			Can be used when creating Append, Merge, and Replace to tell the system which elements to modify. Last Element causes the Append, Merge, or Replace to be applied to the last element in the preceding path.

Geneos URLs elements

These tools are only available for Geneos URL editor, and can perform these functions:

Configure user-defined paths

The Path Editor dialog opens whenever you edit the field or a Gateway Setup Editor setting which takes a path as its value. You can also launch either the Data Item path editor or the Geneos URL editor from the Active Console > Tools > Path Editor menu.

Note: Opening the Path Editor from the Tools menu creates no paths in any context. It only displays the selected path editor.

Add elements in the path editor

To add elements to a path:

1. Drag and drop the element you want to use in the work area.
2. Drag the data item to the relevant modification point. This adds an instance of the tool to the path.
3. Click OK.

For example, when the Dataview element is selected from the Data Item Elements toolbar, it displays the full path that you can modify:

The UserReadable Path also displays the path and it changes real-time when you add an instance to the current path. When you drag the relative path element to the relevant modification point, the editor displays these modification points:

The modification points appear when a data item or element is selected and there is a valid place to apply the tool in the current path. If no modification points appear when the tool is selected, there are no suitable points to insert an element of the specified type into the current path.

Use auto complete

By default, the path configurable provides you with as much help as possible to create paths that can match data items in the system. When Auto Complete is enabled, the path after each element is added and removed. To modify this, right-click anywhere in the path editor dialog, and select Auto Complete.

The Auto Complete function performs these actions:

• Removes a second child element if it follows a another child element or relative element. .
• Inserts child elements between non-relative elements. If there are two non-relative path elements together, the editor automatically inserts a child element between them.
• Removes the last element from the path if it is a child element. The path cannot end in a child element.
• Fully qualifies a path if a non-relative element is dragged into an empty path.

For example, if you add a sampler to an empty path, then it fully qualifies the path from the Gateway.

Edit element properties

To edit an element's properties, follow these steps:

1. Select the specific data item in your current path.
2. Click Edit or double-click the data item. The Element Properties dialog displays.
3. Edit the relevant fields that you want to modify.
4. Click Close. The specified properties displays in the current path.

The properties dialog lists all the attributes of the selected element that you can define in a path, and therefore match to. To change a property, either:

• Select a value from the drop down list in the relevant value cell.
• Enter a value directly in the field and use the special characters or wildcards, as required.

The list of possible values in the drop down list in a given property is derived from any sources available to the path configurable. This depends on the Gateways you are connected to, and any setups you are editing. By default, the possible values are limited by the other selections you have made in the path. For example, if you are editing a managed entity properties, and you have already selected the name of a probe in the previous probe element, the choice of managed entity name is limited to those available on the specified probe.

To remove this restriction, deselect the Restrict property values on path menu item. All possible values for any given property become available.

To clear all the properties set on an element without going through the properties dialog, right-click the selected element and click Clear Path.

Create a new property

Some elements, such as managed entity, allow you to add additional user-defined properties.

To create a new property:

1. Open the Element Properties.
2. Click Add Property.
3. Enter the property name in the Name field.
4. Click OK. The new property field appears in the Element Properties dialog.

The new properties only persist if you provide them with values. If you leave them blank, the editor no longer displays the new property the next time you open it.

Use special characters in the element properties

There are some special characters that you can use when entering or selected values in the properties fields:

• Wildcard (*) — asterisks * and question marks ? are wildcards. An asterisk * matches to any string, while the question mark ? matches to any single character.

• Contains (* … *) — if a value is wrapped in asterisks *, it is treated as Contains. The value must contain the string between the asterisks.

• Not (! … ) — if the field starts with an exclamation mark !, then the test is negated. This works with values, wildcards, and contains (for example, !*ABA* means that the value must not contain "ABA").

• Operator (<, >, >=, <=, !=) — by default, the property must be equal to the value to match. However, you can alter this by preceding the value with a suitable mathematical operator.

  Note: This only works with numeric values in cases where the value is a number, such as >4, or !=3400.

Severities map to numeric values in the underlying system:

This means that if you want to enter a value into a severity property, such as warning or critical, you can enter ">1".

Evaluate paths

Evaluating the paths allow you to view the actual matches in the system based on the elements and properties that you have set. To evaluate a path, you can either:

• Click Evaluate Path.
• Right-click the work area of the path editor, and click Evaluate Full Path.

In this example, the Dataview is selected from the Data Item Elements toolbar:

Note: The most important figure is the number of items that match the last element which is the Dataview data item.

The complete list of items that match the configured path displays at the bottom of the path editor dialog. It list down the following:

• Name.
• Type.
• Severity.
• Element properties, such as Active and Snoozed.

Each element also shows the number of data items it match in the system. If an item matches no object, then there is no related data item in the system. If the last element matches no data item or object, then your path matches no items in the Gateway that you are currently connected to:

Evaluate a specific element

To evaluate a specific data item in the path:

1. Right-click the data item.
2. Click Evaluate to this element.

Use Geneos URL elements

The Geneos URL path editor uses a superset of the elements provided in the path editor. This section provides examples that use the elements or tools available for Geneos URLs.

Use component, dockable, and tab

In this example, the object in the Active Dashboard should open the tab that you are going to set in the element properties. To do this, follow these steps:

1. Go to Active Console > View > Active Dashboards > Active Dashboard Palette.
2. Drag and drop any object into the dashboard canvas.
3. Right-click the object and click Properties. .
4. Go to the Links tab.
5. Click Add in the Links section.
6. Click the ellipsis button in the URL field. This opens the Geneos URL path editor dialog.
7. Drag and drop the Tab data item into the work area of your editor.
8. Modify the element properties of the following:
   • Component — select Active Console.
   • Dockable — select metricsview.
   • Tab — select Metrics.

   

9. Click OK in the Path Editor dialog.

When you double-click the object, this opens the Metrics view. You can also right-click the object and select Links to open the Metrics view.

To know more about objects in Active Dashboard, see .

Use WWW page

This allows you to create a link from a dashboard object to any websites. To do this, follow these steps:

1. Go to Active Console > View > Active Dashboards > Active Dashboard Palette.
2. Drag and drop any object into the dashboard canvas.
3. Right-click the object or open the Object Inspector dockable to edit the property of the object.
4. Click Add in the Links section.
5. Click the ellipsis button in the URL field. This opens the Geneos URL path editor dialog.
6. Drag and drop the WWW Page element into the work area canvas.
7. Double-click the element or click Edit. The opens the Element Properties dialog.
8. Enter the address of the website in the URL field.
9. Click Close.
10. Double-click the object to open the specified website.

The Links section in the Object Inspector dockable shows the URL and alias for the WWW page element you have set:

Use dropped item and append (Netprobes View)

Many of the views are provided by List View with preconfigured paths. For example, in the Netprobes View, it always displays Netprobes:

• If you drop a Gateway into the Netprobes view, it displays the Netprobes being used by that Gateway.
• If you drop a managed entity on it, it displays the Netprobes where that managed entity belongs to.

To set up this behaviour, follow these steps:

1. Go to List View > Configure the view. This opens the List View settings dialog.
2. Click Drag and Drop in the List View settings dialog.
3. Select Define Locally on the Inheritance menu. This makes the Local settings section configurable.
4. Click Add.
5. Click Edit in the Modifier field. By default, it contains the "droppeditem" value.

For more information on list view settings, see List View.

The path of the modifier starts with a dropped item element:

droppeditem

This gets replaced by the path of the data item dropped on it. The Append causes the two elements that it contains to be added to this path, firstly a descendant element followed by a probe. When a Gateway gets dropped into the Netprobes view, the path to the Gateway gets a descendant element attached to the end of its path, followed by a probe, and this path is then passed to the list view.

The effect is that the list view gets a path which matches any probe which is a descendant of the Gateway, and the list view therefore displays all probes. The path of the modifier becomes like this:

droppeditem()/append(/probe)

In the next path of the modifier, it starts with a dropped item element, followed by the Append that contains an Ancestor, and followed by a probe:

droppeditem()/append(/ancestor::probe)

The result is that the path to the managed entity dropped into the list view gets modified by adding an ancestor element followed by a probe. Then, this gets passed to the list view. The effect is that the list view receives a path that matches the probe which is an ancestor of the managed entity. Therefore, it displays the probe where the managed entity belongs to.

Use merge and replace

When a Merge element is applied to an existing element in a path, it merges together the properties from the existing element and the merged element. Any properties defined in the original element and not redefined in the Merge element still set their original value.

When a Replace element is applied to an existing element in a path, it replaces all the properties in the existing element. Any property which is not defined in the Replace element set it to undefined in the resulting element, regardless if it has a value or not in the original element.

You can use the replace element when refactoring a path. To do this, follow these steps:

1. Go to Active Console > Tools > Re-factor paths.
2. Select Advanced Mode.
3. Click Add. This creates a new undefined URL.
4. Double click the undefined URL row. This opens the Geneos URL path editor.
5. Drag and drop the Sampler element into the work area.
6. Double-click the sampler data item or click Edit. This opens the Element Properties of the sampler.
7. Select the name of the sampler you want to replace in the Name field.
8. Close the Element Properties dialog. This brings you back to the path editor dialog.
9. Drag and drop the Replace element in the modification point after the sampler data item.
10. Drag and drop another Sampler element into the modification point of the Replace element.
11. Enter the new name of the sampler in the Name field of the Element Properties dialog.
12. Click Close.
13. Click OK. The Refactor Tool displays the affected paths.
14. Click Refactor.

In this example, all CPU samplers in the system should be replaced with a new CPU name. The path editor looks like this:

The Refactor Tool displays the list of affected paths, old paths, and the new paths where it contain the new name for all the affected samplers:

Use user selection (Items of interest view)

The User Selection is the last item selected that passes the filter specified on its properties. A good example of the application of the User Selection element is the Items of interest. It is a preconfigured list view that uses a user selection.

To view the content path which is preconfigured for the view, follow these steps:

1. Go to Active Console > View > Items of interest > Configure the view.
2. Click Content Paths.
3. Click the ellipsis button of the path. This opens the Geneos URL path editor:

The path with user selection, append, and followed by an accessor element means that:

• When the user selects an item in one of the other views, the user selection item in this path is substituted by the path of the object that the user has selected.
• If the user selects a probe, then the probe's path is substituted in.
• The append element is then applied to it, creating a path which matches any cell which is a descendant of the probe and has the properties severity>1, active=true, and snoozed=false.
• This matches and displays any active unsnoozed cell with a warning or critical severity which is also a descendant of the item that is selected.
• For a Gateway with no warning or critical cells, selecting the Gateway or any item in the State Tree displays nothing in the Items of interest, since the selected item has no descendant cells with the required severity. Similarly, if you select this Gateway in the Gateways view, or select any of its descendant probes or entities in the probe view, or entities view, then nothing is displayed in the Items of interest.
• For a Gateway which has warning or critical cells, selecting the Gateway or any item in the State Tree (or selecting the Global State in the State Tree) displays all the warning or critical cells in the Items of interest. Similarly, if you select this Gateway in the Gateways view, or select any of its descendant probes or entities in the probe view, or entities view, then all of the warning or critical cells are displayed in the Items of interest.

An example of Items of interest list view with user selection elements in the path:

Use expert mode path editor

The standard forms of the path editor (featuring the drag-and-drop and its work area) does not support all valid XPaths. For example, you might want to specify two or more filters on a cell value to match a literal asterisk (*) character in a row name, or to use a wildcard expression in a situation that the standard editor interprets as "contains".

By experimenting with the standard forms of the path editor and evaluating the full XPath generated, you can usually determine the syntax required, and edit this directly into the path by typing into the field that displays an XPath, or by using the XML view in the Gateway Setup Editor.

If you have manually entered a path which is not supported by the standard editors, the expert mode path editor opens automatically:

The configured path in the Content Path settings has invalid characters that prompts the expert mode path editor. To resolve it, you can manually edit the paths by removing the invalid or excess characters. In this example, remove the extra slash (/) and bracket ([) before the Append element:

geneos://component(ac)/userselection(//managedEntity//sampler[(state("severity")="3")])//[append(/ancestor::managedEntity[(state("severity")="2")])

Further reading

To know more about list view settings, see List View.