Microsoft® Forefront Identity Manager 2010 (FIM) provides an FIM Service by which client applications can run queries and retrieve the results. The FIM Service can be used by developers who are building applications, components that interact programmatically with FIM, or customer user interfaces for FIM. This topic describes the FIM XPath Filter Dialect, which you can use to create these queries. The FIM XPath Filter Dialect is a subset of the XML Path Language (XPath) 2.0, with some additional functions.

You need to understand and use the FIM XPath Filter Dialect for the following scenarios:

The FIM Service provides access, in compliance with the Web Services Enumeration specification, to a collection of resources that are represented as XML elements. Client applications can send WS-Enumeration Enumerate messages to the FIM Service to identify a subset of those elements or to retrieve the results of an operation performed on a subset of elements. Subsets of elements and operations to be performed on them are identified by expressions in the FIM XPath Filter Dialect.

When the FIM Service receives a WS-Enumeration Enumerate message that identifies the XPath Filter Dialect as the filter dialect used in the message, if the filter expression complies with the specification of the XPath Filter Dialect, the FIM Service identifies the subset of identity objects identified by the filter expression, or the operation to be performed on a subset of identity objects, and replies with a WS-Enumeration enumeration context (see Enumerate). This enumeration context can be used in subsequent Pull messages to the FIM Service to retrieve the subset of identity objects in batches, or to retrieve the results of the operation.

The following is an example collection of identity objects, which are the xml representations of FIM resources:

  Copy Code 
<Person>
  <ObjectID>11111111-1111-1111-1111-111111111111</ObjectID>
  ...
</Person>
<Group>
  <ObjectID>22222222-2222-2222-2222-222222222222</ObjectID>
  ...
</Group>

Data Types

The XPath Filter Dialect supports querying on FIM data types defined in the following table.

Data type Definition

Boolean

A Boolean true or false value.

The following example returns all Person resources for which the IsRASEnabled property value is true.

  Copy Code 
/Person[IsRASEnabled = true]

number

A signed integer.

The following example returns all Person resources for which the FreezeCount property value is 1.

  Copy Code 
/Person[FreezeCount > 1]

Indexed string

Any sequence of characters from the Universal Character Set that does not exceed 448 characters.

The following example Returns all Person resources for which the EmployeeType property value is the string Full Time Employee.

  Copy Code 
/Person[EmployeeType = 'Full Time Employee']

dateTime

A valid value of the dateTime type defined in the W3C Date and Time Formats specification, with the time zone fragment completely omitted. The dateTime represents a date and time in Universal Coordinated Time.

The following example returns all Group resources that have an ExpirationTime property that is greater than or equal to 10:12:23 on January 2, 2010.

  Copy Code 
/Group[ExpirationTime >= '2010-01-02T10:12:23]'

reference

A reference to a resource or collection of resources.

The following example returns all Person resources that are direct employees of a particular manager.

  Copy Code 
/Person[Manager = '0ed98b5b-7e5b-4cc5-b470-bc94cfff7d8f']

The following example returns all Person resources that are managed by a full-time manager.

  Copy Code 
/Person[Manager = /Person[EmployeeType = 'Full Time Employee']

The FIM XPath Filter Dialect does not support expressions on unindexed string attributes and binary attributes. The values of these types of attributes can be returned when querying the FIM Service, but the queries cannot contain conditions based on the values of these attributes.

Types of Expressions

The XPath Filter Dialect supports the following types of XPath 2.0 expressions:

  • Location path expressions

  • Boolean expressions

  • Equality expressions

  • Relational expressions

  • Function calls

Note:
The XPath Filter Dialect is case sensitive. Keep this in mind when writing your xpath filters.  For example, /Person[displayname = 'value'] is NOT the same as /Person[DisplayName = 'value'].

Location Path Expressions

A location path expression identifies zero or more resources that match the specified filter. Location path expressions have the following structure:

  Copy Code 
/step/step/step/... | step/step/...

A location path expression consists of one or more location steps. Location step expressions are delimited by a forward slash (/).

A forward slash at the beginning of an expression indicates an absolute location path as distinct from a relative location path. A relative location path identifies resources referenced by an attribute relative to the context resource-set. The context resource-set is the collection of resources that have already been identified.

In the following location path expression:

  Copy Code 
/Group/ComputedMember

The location path expression consists of two location steps: Group and ComputedMember. This location path expression yields a resource-set that consists of all resources that are included in the ComputedMember attribute of any Group resource.

In the above example, /Group is an absolute location path and /ComputedMember is a relative location path that identifies resources referenced by the ComputedMember attribute of the resource-set identified by /Group.

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

Restrictions

In the XPath Filter Dialect, an absolute location path must refer to an object type, and a relative location path must refer to an attribute of type reference, which refers to a resource (see Schema Data Types).

The following location path expression:

  Copy Code 
/Group/ComputedMember

is valid because ComputedMember is a referece attribute type.

The following location path expression:

  Copy Code 
/Person[DisplayName="Kim"]/Manager

is also valid because Manager is a reference attribute type. This location path returns the Person object for Kim's manager.

However, the following location path expression:

  Copy Code 
/Group/ComputedMember/DisplayName

is not valid, because DisplayName is not a reference attribute type, and therefore the location path expression cannot return a resource-set corresponding to a collection of FIM resources.

Location Steps

There is one valid type of location step in the FIM XPath Filter Dialect. It is defined in the following table:

Structure Purpose

node-name[predicate][predicate]...[predicate]

Identifies, by name, the child elements of the context node-set.

node-name must be the SystemName of a FIM resource type (such as Person or Group) or a reference type attribute in the FIM schema.

  Copy Code 
/Person[EmployeeType = 'Full Time Employee']

Examples

Identifying Child Nodes by Name

In this location path expression:

  Copy Code 
/Person/Manager[ObjectID='11111111-1111-1111-1111-111111111111']

the location steps are Person and Manager[ObjectID='11111111-1111-1111-1111-111111111111']

The second location step consists of a node name:

  Copy Code 
Manager

and a predicate:

  Copy Code 
ObjectID='11111111-1111-1111-1111-111111111111'

If a Person contains a Manager with the specified ObjectID, the location path expression would return the following node set, assuming that Manager is a Person resource type:

  Copy Code 
<Person>
  <ObjectID>11111111-1111-1111-1111-111111111111</ObjectID>
</Person>

Location Step Node Names

A name by which a child node is identified in a location step must be in one of the forms defined in the following table:

Structure Description

QName

A namespace-qualified name as defined in the XML Namespaces specification that refers to the SystemName of a FIM resource type or a reference type attribute in the FIM schema.

*

A wildcard that matches the name of any child node.

Examples

Identifying Child Nodes by Using QNames

In the following location path expression:

  Copy Code 
/Group/ComputedMember

both Group and ComputedMember are QNames.

Identifying Child Nodes by Using the Wildcard

The location path expression /Person/* returns a node-set that consists of all resources reference by any reference type attribute on the Person resource.

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, or relational expressions.

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

In the following location path expression:

  Copy Code 
/Person[ObjectID='11111111-1111-1111-1111-111111111111']

the predicate:

  Copy Code 
ObjectID='11111111-1111-1111-1111-111111111111'

is evaluated for each resource in the resource-set referred to by the following location path expression:

  Copy Code 
/Person

and yields any Person resource that has an ObjectID of which the value is '11111111-1111-1111-1111-111111111111'.

Equality Expressions

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

  Copy Code 
left_hand_side operator right_hand_side

The following table lists the valid equality operators:

Operator Result

=

The expression evaluates to true if the term on the right and the term on the left are equal; otherwise yields false.

The following example evaluates to true for resources of type Person that have a value of "Full Time Employee" for the EmployeeType attribute:

  Copy Code 
/Person[EmployeeType = 'Full Time Employee']

!=

The expression evaluates to true if:

  • The term on the left is not NULL and its value is not equal to the term on the right.

  • The term on the left is NULL and the term on the right is a location path expression.

The expression evaluates to false if:

  • The term on the left is NULL and the term on the right is a literal value.

  • The term on the left is not NULL and its value is equal to the term on the right.

The != operator is not supported if the left hand term is a multivalued attribute.

The following example evaluates to true if any Person resources have an EmployeeType attribute that does not have the value Full Time Employee.

  Copy Code 
/Person[EmployeeType !='Full Time Employee']

If any Person resource has an EmployeeType that has the value Full Time Employee or does not have a value for EmployeeType, the expression will evaluate to false.

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

  • The name of an attribute.

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

  • An explicit value or the return value of a function. The value must be one of the following types:

    • A Boolean value.

    • A dateTime value.

    • A number.

    • A string.

    • A reference value (ObjectID of a FIM resource, enclosed in quotation marks).

    • A location path expression, if the left-hand term is the QName of a Reference type attribute. Note: this option is only available for use in query. Filters used in Sets cannot contain a location path expression as the right-hand term in an equality expression, except when referencing the membership of a Set resource.

Dereferencing

A predicate can dereference an attribute of type reference to reach the underlying object. This is performed to query for a specific object that has a predicate based on an attribute that is unique to the type of the underlying object. For example, in the following location path expression:

  Copy Code 
/Person[Manager=/Person[EmployeeType = 'Full Time Employee']]

The expression Manager/=Person dereferences the reference attribute Manager to reach the underlying Person object. This is so that another predicate, EmployeeType ='Full Time Employee', can be used to specify the desired Person object based on the EmployeeType attribute, which is unique to the Person object type.

When the = operator is used in an equality expression where the left-hand term is a reference attribute (multi-valued 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 that is contained in the node-set returned by the right-hand term.

The following expression returns all groups that have an Owner who is a Contractor:

  Copy Code 
/Group[Owner = /Person[EmployeeType = 'Contractor']

In other words, this filter returns all groups in which any of the values of their Owner attribute is among the set of people whose EmployeeType is Contractor.

Multi-Valued Attributes

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 that is contained in the left_hand_term.

The following expression:

  Copy Code 
/Group[ComputedMember = '11111111-1111-1111-1111-111111111111']

returns all groups whose ComputedMember attribute contains the resource with the ObjectID '11111111-1111-1111-1111-111111111111'.

Relational Expressions

Relational expressions compare the values of terms. They have the following form:

  Copy Code 
left_hand_side operator right_hand_side

The following table lists the valid relational operators:

Operator Result

<=

Evaluates to true if the term on the right is smaller than or equal to the term on the left; otherwise evaluates to false.

<

Evaluates to true if the term on the right is smaller than the term on the left; otherwise yields false.

>=

Evaluates to true if the term on the right is greater than or equal to the term on the left; otherwise evaluates to false.

>

Evaluates to true if the term on the right is greater than the term on the left; otherwise evaluates to false.

The left-hand term of a relational expression must be a QName that corresponds to the SystemName of an attribute in the FIM schema.

The right-hand term of a relational expression must be an explicit value that is one of the following types:

  • A dateTime value.

  • A number.

  • The result of a function.

Relation Expression Example

In the following location path expression:

  Copy Code 
/Person[CreatedTime >= 2001-02-13T00:00]

the predicate:

  Copy Code 
CreatedTime >= 2001-02-13T00:00

is a relational expression. The left-hand term of the expression is the name of an attribute, and the right-hand term is a dateTime value. The expression yields true for any Person resource whose CreatedTime value is later than or equal to midnight on the thirteenth of February, 2001.

Boolean Expressions

Boolean expressions evaluate the validity of two expressions. They have one of the following forms:

Form

Description

left_expression or right_expression

Yields true if either the expression on the right or the expression on the left is true; otherwise, yields false.

left_expression and right_expression

Yields true if both the expression on the right and the expression on the left are true; otherwise, yields false.

Boolean Expression Examples

Boolean expression using the Or Operator

In the following location path expression:

  Copy Code 
/Person[ObjectID='11111111-1111-1111-1111-111111111111' or ObjectID='22222222-2222-2222-2222-222222222222']

the predicate:

  Copy Code 
ObjectID='11111111-1111-1111-1111-111111111111' or ObjectID='22222222-2222-2222-2222-222222222222'

is a Boolean expression that consists of two equality expressions. It yields true if either equality expression is true for the current resource.

Boolean expression using the And Operator

In the following location path expression:

  Copy Code 
/Person[EmployeeType='Full Time Employee' and JobTitle='Engineer']

the predicate:

  Copy Code 
EmployeeType='Full Time Employee' and JobTitle='Engineer'

is a Boolean expression that consists of two equality expressions. It yields true if both equality expressions are true for a resource.

Function Calls

Calls to functions are expressed in the following form:

  Copy Code 
function_name(argument, argument, ...)

An argument to a function varies depending on the function.

When an attribute passed into a function as an argument is a multi-valued attribute, the function applies to all values that are contained in the attribute. For example, Contains(ActionType, 'Delete') returns true if any values in the ActionType attribute contain the value 'Delete'.

The XPath Dialect Filter supports the following XPath 2.0 core library functions:

Function Signature Description

boolean contains(attribute, string)

Returns true if the value of the attribute specified in the first argument contains the second as a substring; otherwise returns false. Note that this implementation differs from contains in XPath 2.0.

Note: The use of this function is limited to query. This function cannot be used in the Filter property of a Set or Group resource.

boolean starts-with(attribute, string)

Returns true if the value of the attribute specified in the first argument starts with the second; otherwise returns false. Note that this implementation differs from starts-with in XPath 2.0.

Boolean ends-with(attribute, string)

Returns true if the value of the attribute specified in the first argument ends with the second; otherwise returns false. Note that this implementation differs from ends-with in XPath 2.0.

Boolean not(equality expression)

The not function returns true if the argument evaluates to false and false if the argument evaluates to true.

Note: The argument to the not() function must be an equality expression that uses the = operator. The != operator, additional functions or Boolean expressions are not permitted as arguments to the not() function.

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.

Formal Definition

The XPath Filter Dialect may be specified, using the Backus Naur Form, as follows:

  Copy Code 
<Expression >::= <LocationPathExpression> | 
					<FunctionCallExpression> |
		 <Expression> '|' <Expression>

< LocationPathExpression> ::= <LocationStep> <LocationStep> |
							<FunctionCallExpression> |
							<ElementNodeLocationStep>  


<LocationStep >::= <ElementNodeLocationStep>

<ElementNodeLocationStep> ::= '/' QNAME  |  
							 '/' QNAME <PredicateList>  

<PredicateList> ::= <Predicate> 

<Predicate> ::= '[' <PredicateExpression >']'

<PredicateExpression> ::= <BooleanExpression> | 
			<EqualityExpression> |
			<RelationalExpression>

<EqualityExpression> ::= <LeftEqualityTerm> <EqualityOperator> <RightEqualityTerm>

<EqualityOperator > ::= '=' |
	'!='

<LeftEqualityTerm> ::= QNAME

<RightEqualityTerm> ::= <LocationPathExpression> |
		 <FunctionCallExpression> |
	<BooleanToken> |
		 DATETIME |
		NUMBER |
		STRING 

<BooleanToken> ::= 'true' |
		 'false'

<RelationalExpression> ::= <LeftRelationTerm> <RelationalOperator> <RightRelationalTerm>

<RelationalOperator> ::= '<=' |
					'<' |
					 '>=' |
				'>'

<LeftRelationalTerm> ::= QNAME 

<RightRelationalTerm >::= <FunctionCallExpression> |
			<LocationPathExpression> |
		 NUMBER |
			DATETIME

<BooleanExpression> ::= <BooleanTerm><BooleanOperator> < BooleanTerm> |
		 <BooleanExpression><BooleanOperator>< BooleanTerm>| 
					 '(' <BooleanExpression> ')' <BooleanOperator>< BooleanTerm>

<BooleanTerm> ::=  LocationPathExpression | 
									EqualityExpression | 
									RelationalExpression

<BooleanOperator >::= 'and' |
	'or'

<FunctionCallExpression> ::= <FunctionName> '(' <ParameterList> ')'

<ParameterList>::= <Parameter> | 
		 <ParameterList><Parameter>

<Parameter> ::=	<LocationPathExpression>| 
		<NumericalExpression> | 
	<FunctionCallExpression> | 
	NUMBER |
	 DATETIME |
	 STRING

<FunctionName >::= 'contains' | 
		'starts-with' | 
		'ends-with' |
				 'current-dateTime' |
				 'dateTime' |
				 'add-dayTimeDuration-to-dateTime' |
				 'add-yearMonthDuration-to-dateTime' |
				 'subtract-dayTimeDuration-from-dateTime' |
				'subtract-yearMonthDuration-from-dateTime' |
				'not'

Using the XPath Filter Dialect in WS-Enumeration Enumerate Messages

Identifying the XPath Filter Dialect

To identify the XPath Filter Dialect as the filter dialect of a WS-Enumeration Enumerate message, set the value of the WS-Enumeration Dialect attribute to http://schemas.microsoft.com/2006/11/XPathFilterDialect.

Exceptions

The Web Services Enumeration specification defines SOAP faults that may be returned when a filter expression cannot be processed. When an error occurs in the processing of an XPath Filter Dialect expression incorporated in a WS-Enumeration Enumerate message, those faults must be returned.

See Also