XPath Filter Dialect: Fundamentals

Article
02/06/2009

ILM “2” provides a Web Service Enumeration (WS-Enumeration) end point by which client applications can run queries and retrieve the results. Please refer to Joe Schulman’s excellent extensibility blog for more details on using the WS-Enumeration end point in ILM “2”.

This blog focuses on the XPath Filter Dialect, which you can use to create the queries to submit through the ILM Web Services. XPath Filter Dialect is a subset of the XML Path Language (XPath) 2.0, with some additional functions.

Client applications can send WS-Enumeration Enumerate messages to the ILM Service to identify a of resources and attributes. The subsets resources to return are identified by expressions in the XPath Filter Dialect (from here on usually referred to simply as an ‘xpath filter’ in this blog).

If you are developing your own custom client for ILM, or submitting queries to ILM through a custom activity, you will need to use the xpath filter as your query language. In the ILM portal, xpath is the language in which you express the queries for Search Scopes that can be created. Xpath is also used to express the membership conditions of calculated groups and sets.

The following is an example of an xpath filter that identifies all people whose Job Title is ‘Engineer’: /Person[JobTitle = ‘Engineer’]

Rather than continue listing examples of xpath filters you may find useful, I’m going to use this blog post to describe the fundamentals of the ILM Xpath Filter Dialect so that you can understand the expression language and construct any filter you need. I will follow up this blog with another post of some sample filters for commonly requested queries and reports.

Much of the content I include here is probably covered by the ILM “2” SDK in much more detail, but hopefully you’ll also find some of the guidance here conveniently available and useful J. I will build on this topic with examples as people request them, so feel free to make suggestions!

Let’s start by looking at the data types the ILM xpath filters support.

Data Types

The ILM XPath Filter Dialect supports the four data types defined for XPath 1.0, plus the dateTime type that is defined in the XML Schema specification. These types are defined in the following table.

Data type	Definition
node-set	A collection of XML nodes without duplicates. Refer to Joe Schulman’s blog for examples of node sets in ILM WS-Enumeration. Think of a node-set as a collection of resources.
Boolean	true or false
number	A signed integer.
string	Any sequence of characters from the Universal Character Set.
dateTime	The dateTime represents a date and time in Universal Coordinated Time.
reference	A GUID that identifies a reference to a resource.

Now that we know what types of data we can filter on in our expressions, let’s take a look at what types of expressions we can actually define.

Types of Expressions

ILM “2” supports the following types of xpath expressions:

Location path expressions
Boolean expressions
Equality expressions
Relational expressions
Function calls

1. Location Path Expressions

A location path expression identifies a node-set (collection of resources). A location path expression consists of one or more location steps. Location step expressions are delimited by a forward slash (/). A location path expression must refer to an object type in ILM, or an attribute of type reference which refers to a resource. Location path expressions have the following form: /step/step/… | step/step/…

A forward slash at the beginning of an expression indicates an absolute location path expression as distinct from a relative location path expression. A relative location path expression identifies a node-set relative to the context node-set. The context node-set is the set of nodes that have already been identified.

Example: /Group/ComputedMember is a location path expression that consists of two location steps: Group and ComputedMember. The result of this filter is all resources that are the ComputedMember of any Group.

Example: /Person[AccountName = ‘nima’]/Manager returns the resource referenced by the Manager attribute of the Person with an Account Name of ‘nima’.

Example: /Person[AccountName = ‘nima’]/DisplayName is not a valid xpath filter because DisplayName is not a reference type attribute.

Union of location path expressions

The union of one or more location path expressions can be obtained by linking the location path expressions with the union operator, which is denoted by the vertical bar character, |.

Example: /Person | /Group returns all people and groups.

Predicates

Predicates are expressions that appear enclosed in brackets at the end of location steps. In the XPath Filter Dialect, predicate expressions must be Boolean expressions, equality expressions, function expressions or relational expressions.

Predicates filter the current node-set to produce a subset. A predicate is evaluated for each node in the current node-set. If the result of the predicate is true for a node, that node is included in the subset yielded by the predicate; otherwise, it is excluded.

Example: /Person/Manager[JobTitle = ‘VP’] returns all people whose Manager’s Job Tile is ‘VP’. The location step here are Person and Manager[JobTitle = ‘VP’] . The second location step consists of a node name, Manager, and a predicate, JobTitle = ‘VP’.

You can even have location path expressions nested inside predicates.

For example, the filter /Person[Manager = /Person[JobTitle = ‘VP’]] returns all people whose Manager is a person with a Job Title of ‘VP’. Note that this returns us the same result as a previous example: /Person/Manager[JobTitle = ‘VP’].

2. Equality Expressions

Equality expressions test the equality of terms. They have the following form: left_hand_term operator right_hand_term

The valid equality operators are as follows:

Operator	Result
=	Yields true if the term on the right and the term on the left are equal; otherwise yields false.
!=	Yields true if the term on the right and the term on the left are not equal; otherwise yields false.

The left-hand term of an equality expression must be the name of an attribute in the ILM schema.

The right-hand term of an equality expression can be one of the following:

· A function call.

· A Boolean value.

· A dateTime value.

· A number.

· A string.

· A reference value.

If the left-hand term is a reference type attribute, the right-hand term can be a location path expression (ie. a filter representing a sub-condition).

Multi-Valued Equality Expressions

When the = operator is used in an equality expression where the left-hand term is a multi-valued attribute and the right-hand term is a literal value, the expression evaluates to true if the value of the right-hand term is any of the values contained in the left_hand_term.

Example: /Group[ComputedMember = ’11111111-1111-1111-1111-111111111111’] returns all groups whose ComputedMember attribute contains the resource with the ObjectID ’11111111-1111-1111-1111-111111111111’.

When the = operator is used in an equality expression where the left-hand term is a reference attribute (multivalued or single valued) and the right-hand term is a location path expression, the expression evaluates to true if the value of the attribute on the left-hand term is any of the values contained in the node-set returned by the right_hand_term.

Example: /Group[Owner = /Person[EmployeeType = ‘Contractor’] returns all groups whose Owner is a Contractor. In other words, this filter returns all groups where any of the values of their Owner attribute is among the set of people whose Employee Type is ‘Contractor’.

3. Relational Expressions

Relational expressions compare the values of two terms. They have the following form: left_hand_term operator right_hand_term

Valid relational operators are: <=, <, >=, >, which are pretty self explanitory.

4. Boolean Expressions

Boolean expressions evaluate the validity of two expressions in a predicate using ‘or’, and ‘and’.

When ‘or’ is used, the predicate evaluates to true if either expression is true.

Example: /Person[JobTitle = ‘VP’ or ‘Senior VP’] returns people whose Job Title is ‘VP’ or ‘Senior VP’.

When ‘and’ is used, the predicate evaluates to true only if both expression are true.

Example: /Person[JobTitle = ‘VP’ and Department = ‘Sales’] returns people who are VPs and are in the Sales department.

5. Function Calls

The ILM XPath Filter Dialect provides the following functions that can be used in location path expressions:

Function Signature	Description
boolean contains(Attribute, string)	Returns true if the value of the first argument, which must be a valid attribute in the ILM schema, contains the second as a substring; otherwise returns false.
boolean starts-with(Attribute, string)	Returns true if the value of the first argument, which must be an attribute in the ILM schema, starts with the second; otherwise returns false.
Boolean ends-with(Attribute, string)	Returns true if the value of the first argument, which must be an attribute in the ILM schema, ends with the second; otherwise returns false.
Boolean not(boolean)	The not function returns true if the argument evaluates to false and false if the argument evaluates to true. The argument must be one of the following expressions which returns a Boolean: 1. Relational expression 2. Equality expression 3. Function call
dateTime current-dateTime()	Returns the current date and time with time zone. For more information see current-dateTime in XPath 2.0.
dateTime dateTime(date, time)	Returns the arithmetic sum of the arguments. For more information see dateTime in XPath 2.0.
dateTime add-dayTimeDuration-to-dateTime(dayTimeDuration, dateTime)	Returns the result of adding the values of the two arguments. For more information see add-dayTimeDuration-to-dateTime in XPath 2.0.
dateTime add-yearMonthDuration-to-dateTime(yearMonthDuration, dateTime)	Returns the result of adding the values of the two arguments. For more information see add-yearMonthDuration-to-dateTime in XPath 2.0.
dateTime subtract-dayTimeDuration-from-dateTime(dayTimeDuration, dateTime)	Returns the results of subtracting the value of the second argument from the value of the first argument. For more information see subtract-dayTimeDuration-from-dateTime in XPath 2.0.
dateTime subtract-yearMonthDuration-from-dateTime(yearMonthDuration, dateTime)	Returns the results of subtracting the value of the second argument from the value of the first argument. For more information see subtract-yearMonthDuration-from-dateTime in XPath 2.0.
node-set descendants(locationPathExpression, attributeName)	Returns a node-set (set of resources) that consists of the dereferenced resources obtained by dereferencing the reference attribute specified by attributeName, starting with the resource specified by the location path expression. Example: descendants(/Person[DisplayName = Nima’], ‘Manager’) returns the manager of the person with the DisplayName of ‘Nima’, and the manager of all those people recursively (ie. everyone ‘Nima’ reports to indirectly)
Bool descendant-in(attributeName, Filter)	This function obtains a set of resources by recursively dereferencing the reference attribute specified by attributeName, starting with the context node. If the set of resources obtained contains the resource identified by Filter (or is among the resources identified by Filter), the function returns true; otherwise, it returns false. Example: /Person[ descendant-in(‘Manager’ , /Person[DisplayName = ‘Nima’])] returns all people who report to ‘Nima’ (ie. people who have ‘Nima’ in their management chain).
node-set membersof(ObjectID)	The membersof function accepts the unique identifier of a Set as input, and returns the members of that Set.
node-set allTime(locationPathExpression)	The allTime function accepts a valid filter expression in the XPath Filter Dialect as input, and returns the resources matching that expression at any time over the history of the data in the ILM Service database.
node-set atTime(locationPathExpression, dateTime)	The atTime function accepts a valid filter expression in the XPath Filter Dialect and a DateTime as input. It returns the resources matching that matched the expression at the specific DateTime specified.
node-set betweenTime(locationPathExpression, dateTime, dateTime)	The betweenTime function accepts a valid filter expression in the XPath Filter Dialect, two DateTime values as input, and returns the resources matching that expression at any time between the two DateTimes specified.

Hopefully this blog helps you understand the structure of the XPath Filter Dialect expression language. Trust me when I say this knowledge will come in extremely handy if you will be performing any of the following:

· Creating search scopes for the portal. Search scopes are pre-canned searches you can use in the portal.

· Creating advanced calculated sets and groups that cannot be created using the Filter Builder control in the ILM portal. One example of such a set is the set of all resources that contain an Expected Rule Entry for a particular Synchronization Rule in their Expected Rules List.

· Creating custom activities that will query the ILM Service database.

· Creating a WS client that will submit queries to the ILM Web Service. Such clients can be used for purposes such as reporting.

Stay tuned as I will be following up with some xpath ‘tips and tricks’ and sample filters for commonly requested queries.

Cheers,

Nima Ganjeh

XPath Filter Dialect: Fundamentals

Additional resources