What is an XPath?
XPaths are simply a way of describing an item on a gateway
Gateway/Netprobe/Managed Entity/Sampler/Data View/Row/CellEach element of an XPath is defined as
element_name[@property1=value][@property2=value]…so for example a snoozed, inactive cell in the status column on the same row as the target cell is
parent::node()/cell[(state("active")="0")][(state("snoozed")="1")][(@column="status")]Creating an XPath
Do not open up the Path Editor and try to create the path from scratch.
If a specific element is needed, the easiest and simplest approach is to left click on the element to select it, and then left click again and drag it directly into the Target. If it is one of a set of cells, select one and drag it.
Then select Edit and open the Path Editor and adjust the properties on each element to make it as general or specific as required.
- Removing all the properties means that an element will match all elements of that type.
- Any property can contain an * which is a wildcard.
- If any properties are missing from the item being tested then a blank string will be passed to the match. So a blank attribute and a non-existent attribute are the same thing on the gateway.
- It is best to always use Any for gateways as that allows the gateway to be renamed in future.
Using Evaluate path
Rules only apply to the gateway on which they are configured. If Active Console is connected to multiple gateways and the Gateway is defined as Any gateway, then Evaluate Path will list cells on other gateways which match the path, even though the rule will not actually apply to them.
XPath predicates
An XPath is composed of nodes and predicates. The
predicates are the expressions in the square brackets
that follow a node. The predicate performs a filter on
the node. So /geneos/gateway/directory/probe
will match all of the probes on a gateway. /geneos/gateway/directory/probe[(@name="pr123")]
will match the single probe with name "pr123".
/geneos/gateway/directory/probe[(rparam("Version")="GA3.0.20-140610")]
will match any probe which has a version number of
"GA3.0.20-140610".
Predicate Functions
Geneos provides a set of functions that can be applied to the nodes to be filtered. They return values that can then be tested in the predicate. The following functions are provided:
wild(searchString, matchString)
This function performs a wildcard comparison on strings.
The function takes 2 arguments
- searchString : string : the value to match
- matchString : string : a wildcard pattern to match against
The match string is compared against the whole of the search string, character by character, except that
- '*' in the matchString matches zero or more characters.
- '?' in the matchString matches exactly one character.
wild-no-case(searchString, matchString)
This function performs a wildcard comparison on strings ignoring the case of letters. The function takes 2 arguments
- searchString : string : the value to match
- matchString : string : a wildcard pattern to match against
contains(haystack, needle)
Checks whether a "haystack" string contains a "needle" string. The function takes 2 arguments
- haystack : string : the string to search
- needle : string : the string to search for
not(value)
Negates a Boolean argument. The function takes 1 argument
- value : boolean : value to negate
attr(name)
Extracts the value of a managed entity attribute. The function takes 1 argument
- name : string : name of the managed entity attribute to get the value of
param(name)
Extracts the value of a parameter for a directory component node. The function takes 1 argument.
- name : string : name of the parameter to get the value of
For a list of parameter names see section Extracting information > Parameters / Params
rparam(name)
Extracts the value of a runtime parameter for a directory component node. The function takes 1 argument
- name : string : name of the runtime parameter to get the value of
For a list of parameter names see section Extracting information > runtimeParameters / Rparams
state(name)
Extracts the value of a state attribute for a directory component node, or a dataview cell node. The function takes 1 argument
- name : string : name of the state attribute to get the value of
For a list of attributes see section Extracting information > state attributes
me(stripDomain)
Extracts the name of the user logged on to the gateway.
The function takes 1 argument
- stripDomain : boolean : if stripDomain is true then the username returned will have the Windows domain stripped, otherwise the full username will be returned
This function can only be used on a client that is logged in to the gateway, so it is not available for use with Rules or Database logging. It is available for command targets and argument targets in commands which are evaluated on the client when the command is executed. A command which uses this function in an argument target should not be used a scheduled command, because the value returned will be "NO USER ASSIGNED", since a scheduled command is not associated with a logged in user.
Identifying predicates
Identifying predicates are expressions that can be evaluated using the gateway setup. Examples of the most common of these predicates are listed below.
| Predicate | Example |
|---|---|
| name | @name="pr123" |
| row | @row="r1" |
| column | @column="c1" |
| type | @type="" |
| param | param("HostName")="a.bcd.com" |
| attr | attr("DEPT")="DEV" |
Non-identifying predicates
Non-identifying predicates are expressions that cannot be evaluated using the gateway setup. They need runtime information in order to be evaluated. Examples of the most common of these predicates are listed below.
| Predicate | Example |
|---|---|
| value | @value="OK" |
| state | state("snoozed")="1" |
| rparam | rparam("HostName")="pr123" |
| contains | contains(@value,".") |
| wild | wild(rparam("AssignedUser"),"user*") |
| me | me(true())="user7" |
There are certain places where the gateway will only accept identifying predicates e.g. Rule target, Rule context, Rule Group context, Database Logging Item Target etc. If a non-identifying predicate is used then the Gateway Setup Editor will return an error showing the non-identifying predicate(s) that breach the XPath requirements of the field in error.
Relative Paths
Only use a relative path where one is actually needed - it is advisable to avoid the temptation to overcomplicate things.
Relative paths are useful for
- cells from the same dataview
- comparing two values on the same row
Evaluate path on relative paths
It is possible to use the Path Editor in the GSE to test relative paths by using the evaluate path button. When used with a relative path, user needs to provide an XPath that the relative path will be tested against. For example, if constructing a relative XPath to use in a command, the XPath to one of the cells the command will be run from should be used. This XPath is dragged/typed into the "Evaluate path relative to:" text box in the path editor.
The user can then construct a relative path in the work area by using the Relative Path and Data-items Elements from the toolbar area. The evaluation of the relative path in relation to the target path can be executed by pressing the Evaluate path button or the right-click menu options 'Evaluate Full Path' and 'Evaluate to this element'.
The 'edit' dialog for every element in the relative path will have dropdown lists for the Name (and Column for table cells) which are relevant to the position of the element in the path. Other properties which cannot be evaluated in a relative path will be empty, but can be filled in by the user.
Useful relative paths
Same Row
Three ways to a cell on the same row as the single target cell
../cell[(@column="status")]
parent::node()/cell[(@column="status")]
ancestor::row/cell[(@column="status")]Same Column
A cell in the same column as the single target cell but a different row
parent::node()/parent::node()/row[(@name="activeMounts")]/cell[(@column="Value")]A column on the same dataview as the single target cell
ancestor::rows/row/cell[(@column="filename")]Sampling Status
Sampling Status is a headline, so two alternative relative paths from a single target cell on the dataview are
parent::node()/parent::node()/parent::node()/headlines/cell[(@name="samplingStatus")]
ancestor::dataview/headlines/cell[(@name="samplingStatus")]Elements Above
Any element in the path above this element
ancestorse.g. to find the gateway, probe or managedEntity, on which this element is a child, create a relative path which is the appropriate one of
ancestor::gateway
ancestor::probe
ancestor::managedEntityThere should be no need to add a property as there can only be one ancestor or each type in the path.
Note: It generally is more efficient to use a series of parent::node() statements in place of ancestor. This is because the system has to look at all ancestors and filter them, rather than directly selecting the appropriate element. A notable exception to this is going from a cell to a dataview.
Elements Below
Any element in the path below, use Descendants and Self (this is Ancestors in reverse) or
//To find all the SamplingStatus cells below this point
//headlines/cell[(@name="samplingStatus")]All managed entities
//managedEntityor to select a specific one, set the value of the property
//managedEntity[(@name="cjt_gwy2_ops")]Target names and relative paths
It is possible to reference parts of the unique path of the "target data-item" of a rule, and use this in relative paths in order to access similar data from another monitored system.
The target data-item is the item (typically a dataview cell) that the rule is run upon; this is where the severity is applied, the value is set (for compute engine rules) and/or what an action is run for.
The unique name of this item is the name that appears when selecting the "copy from name -> path" menu option in Active Console when you right-click on the item.
The ability to access the target name is most commonly used to get the row name of a dataview cell. This row name can then be used to extract and compare associated values published in a different dataview, or perhaps on a different managedEntity. Instructions on how to do these tasks can be found below.
Comparing similar data from another dataview
In this example the corresponding values in the
sendDataRate column of two dataviews are
compared.
First a rule is created. The aim is for the cells in toolkitA to have severity (colours) applied to them, so these are made the target of the rule by dragging a cell from this column (see highlighted cell 1 above) to the rule target.
This will apply the rule to the specific cell which was dragged into the field. To apply the rule to all cells in the column, open the path editor dialog by clicking the "edit" button and clear the row properties by selecting the option in the right-click context menu.
To reference data from another dataview, it is necessary to configure a path alias. This is done in the advanced rule configuration, accessed by clicking the advanced tab at the top of the rule configuration pane.
Create a new path alias and give it a helpful name. In the example image, the name is associatedRow, as it will be used to reference an associated row in a different dataview.
The path alias is populated by dragging a cell from the associated dataview (the view containing the data we want to compare against) into the field. In this example, cell 2 from toolkitB has been dragged (please see the earlier screenshots to see the precise cell that this refers to).
Once again, because the cell was dragged in, the path alias will currently only refer to that exact cell. In order for the rule to work correctly, it is necessary to reference the cell in toolkitB that has the same row name as the target cell in toolkitA. This is done by using a path variable. Path variables are substituted when a rule is executed. In this case, a path variable is used to substitute the row name.
Note: Path variables can only be utilised in path aliases for rules. Path variables are invalid everywhere else.
To do this, open the path editor by clicking the edit button, then hover over the row component of the path and click edit. In the dialog that opens, the name will be populated with the name of the cell that was dragged in. Replace this name with any variable name, as identified with a $ symbol. In the example image, the name used is row.
The path alias now references a variable named row, so this variable needs to be defined. Create a new path variable (just above the path alias definitions) and call it "row". When the variable is created, a mini rule editor pane is displayed.
The pane allows for complex expressions to be created, which are explained in the Path variable expressions section. This allows you to translate from the target data-item (cell the rule is applied on) to the secondary data-item (cell where extra data is extracted).
In the current example, however, all that is required is to copy the row name from the target data-item into the path alias, which is done using the target syntax. You can either type target "rowName" as per the example, or insert this text via the right-click menu option.
Now the path alias has been configured, it can be used to write the rule. This example compares the difference between the cell values in the two dataviews. If the values are too far apart, the severity is set to warning, and then critical if further apart.
The variable val is used in this rule to store the result of the path alias lookup. This is an optimisation to the rule, so that the value from the other cell only gets looked up once, even though the value is used twice.
Copying values using Compute Engine
Using path variables, rules can be created to copy values into a dataview, from another dataview. Following on from the previous example, it is possible to copy cell values from toolkitB to toolkitA as follows.
First start by creating an additional column in toolkitA to hold the copied values. This is done in the advanced section of the sampler configuration, in the dataviews setting near the bottom.
Save the setup and find the new column created in the dataview.
Create a new rule with one of the new cells as the target, and then erase the row name so that the rule applies to the whole column.
Then configure a path alias and path variable as for Target names and relative paths above.
The rule body is then the single line below:
value path "associatedRow" valuePath variable expressions
When a path variable is configured, the value of the variable is given by an expression. Up until now, the examples have been using basic target <name> expressions which just extract the selected name (the row name).
More complex expressions can be constructed by the use of rule functions (such as concat or stringBefore) which allow the row name (or other expression) to be processed. The resulting value is then cast to a string value before being used in the path alias.
Some examples:
| Row name (from target item) | Expression | Resulting value (to match aliased item) |
|---|---|---|
| CQSE1-A | target "rowName" | CQSE1-A |
| CQSE1-A | stringBefore(target "rowName", "-A") | CQSE1 |
| CQSE1-A | concat(stringBefore(target "rowName", "-A"), "-B") | CQSE1-B |
| prefix-VALUE-suffix | stringAfter(target "rowName", "prefix-") | VALUE_suffix |
| prefix-VALUE-suffix | stringBefore(stringAfter(target "rowName", "prefix-"), "-suffix") | VALUE |
Note: Path variables can only be utilised in path aliases for rules. Path variables are invalid everywhere else.
Wildcarded paths and path variables
Currently creating a pathAlias which contains a wildcard pattern is not supported by the drag-and-drop Path Editor dialog. Therefore this must be done manually by editing the path in the expert mode (See The 'expert mode' Path Editor in the Path Editor). Start by inserting a variable into the path (see Target names and relative paths for more details on doing this).
Then click in the path field (or switch to XML mode) to see a path similar to the following. The highlighted text shows the variable part of the path.
/geneos/gateway[(@name="TR_8600_test")]/directory/
probe[(@name="testhost_18248")]/
managedEntity[(@name="testhost")]/
sampler[(@name="p2ps User Mounts")][(@type="")]/
dataview[(@name="p2ps User Mounts")]/rows/
row[(@name=var("userName"))]/
cell[(@column="compBytesSentRate")]To modify this to be a wildcard, it is necessary to change
[(@name=var("userName"))]to
[wild(@name,var("userName"))]So the path now becomes
/geneos/gateway[(@name="TR_8600_test")]/directory/
probe[(@name="testhost_18248")]/
managedEntity[(@name="testhost")]/
sampler[(@name="p2ps User Mounts")][(@type="")]/
dataview[(@name="p2ps User Mounts")]/rows/
row[wild(@name,var("userName"))]/
cell[(@column="compBytesSentRate")]Note: To use a path variable as a wildcard pattern, it will probably be necessary to add wildcard characters (? and *) to the path variable expression in order to match using wildcards.
For example, to match rows which start with the target item rowname, the pathVariable expression should be concat(target "rowName", "*").
Commands - Useful Targets
Any and everything - e.g. give access to the command anywhere
// *Provide the command on all managed entities, use either of
/geneos/gateway/directory/probe/managedEntity//managedEntityExtracting information
Some commands take XPaths as arguments. For example, if the command is to run on the managedEntity or below and you need to pass in the Hostname related to this element (e.g. with a logon command), use
ancestor::probe/parameters/@HostNamei.e. find the probe above this element and then return the HostName parameter.
XPaths to return values to pass as parameters to commands
ancestor::gateway/parameters/@Port
ancestor::probe/runtimeParameters/@ConStateXPaths to return the value of a named Managed Entity attribute
ancestor::managedEntity/attributes/attribute[@name="<attribute name>"]/@value
ancestor::managedEntity/attributes/attribute[@name="OS"]/@valueObtaining parameter values in a rule
value path "myprobe" rparam "ConState" where myprobe is the alias ancestor::probe
value path "mygway" param "Name" where mygway is ancestor::gatewayThe contents of a cell
../cell[(@name="colname")]but the first column is special and a row name
@rownameThe tables below show which properties can be extracted from each element
| Element | gateway | directory | probe | managedEntity | sampler | dataview |
|---|---|---|---|---|---|---|
| Name | X | X | X | X | ||
| HostName | X | X | ||||
| Port | X | X | ||||
| Secure | X | X | ||||
| HotStandbyRole | X | X | ||||
| Group | X | X | X | X | ||
| Description | X | X | ||||
| BannerVar | X | |||||
| Type | X | |||||
| PluginName | X | |||||
| Virtual | X | |||||
| Imported | X | |||||
| ExportingGateway | X | |||||
| Floating | X | |||||
| SelfAnnounced | X | |||||
| SampleInterval | X | |||||
| UsingSampleInterval | X | |||||
| UsingSampleTime | X | |||||
| UsingSampleInterval | X | |||||
| UsingFileTrigger | X |
| Element | gateway | directory | probe | managedEntity | sampler | dataview | cells |
|---|---|---|---|---|---|---|---|
| UserName | X | X | |||||
| ConState | X | ||||||
| ImportedConState | X | ||||||
| RejectionReason | X | ||||||
| RejectionMessage | X | ||||||
| OS | X | ||||||
| Version | X | X | X | ||||
| AssignedUser | X | X | X | X | X | X | |
| SampleIntervalActive | X | ||||||
| SampleTime | X | ||||||
| SampleInfo | X |
state attributes
| Element name | Data type | Description |
|---|---|---|
| Severity | integer | Current severity - 0 = none, 1 = OK, 2 = warning, 3 = critical, 4+ = user. |
| Active | boolean | Whether the component is currently active. |
| Snoozed | boolean | Whether the component is currently snoozed. |
| Snoozed Parents (excluding cells) |
integer | Number of snoozed parents. |
| Snoozed Children (excluding cells) | integer | Number of snoozed children. |
| Logged (cells only) | boolean | Whether Value is configured to be logged to a database. |
| Logging success (logged cells only) | boolean | Whether Value is being logged successfully to the database. |
| User Assigned | boolean | Whether a user is currently assigned to the DataItem. |
Other Examples
Displaying a SampleTime
- On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it SampleTime
- Create a new rule setting
- Target to be the headline cell SampleTime
- pathalias SrcSampleTime to ancestor::dataview
- rule to value path "SrcSampleTime" rparam "SampleTime"
Totalling a column to a headline cell
- On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it TotalX
- Create a new rule setting
- Target to be the headline cell TotalX
- pathalias ColX to
parent::node()/parent::node()/rows/row/cell[(@column="X")]- rule to value total(wpath "ColX" value)
Totalling cells only when another column contains a certain value
- On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it SelectedXTotal
- Create a new rule setting
- Target to be the headline cell SelectedXTotal
- pathalias SelectX (to select only from columnX where column Y contains an "a") to
parent::node()/parent::node()/rows/row/cell[(@value="a")][(@column="Y")]/parent::node()/cell[(@column="X")]- rule to value total(wpath "SelectX" value)