FIM XPath Filter Dialect
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:
Creating SearchScopeConfiguration resources that can be used in the FIM Portal.
Creating advanced membership criteria for dynamic sets and groups.
Developing custom applications that issue queries to the FIM Service via WS-enumeration Enumerate messages.
Developing custom FIM Workflow Activities that issue queries to the FIM Service using the FIM EnumerateResourcesActivity. For more information about custom activities, see Custom Activities and Workflows.
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:
<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. |
number |
A signed integer. The following example returns all Person resources for which the FreezeCount property value is |
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 |
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. |
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. The following example returns all Person resources that are managed by a full-time manager. |
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:
/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:
/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:
/Group/ComputedMember
is valid because ComputedMember is a referece attribute type.
The following location path expression:
/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:
/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.
/Person[EmployeeType = 'Full Time Employee']
Examples
Identifying Child Nodes by Name
In this location path expression:
/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:
Manager
and a predicate:
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:
<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:
/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:
/Person[ObjectID='11111111-1111-1111-1111-111111111111']
the predicate:
ObjectID='11111111-1111-1111-1111-111111111111'
is evaluated for each resource in the resource-set referred to by the following location path expression:
/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:
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: |
!= |
The expression evaluates to true if:
The expression evaluates to false if:
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 If any Person resource has an EmployeeType that has the value |
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:
/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:
/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:
/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:
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:
/Person[CreatedTime >= 2001-02-13T00:00]
the predicate:
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 |
|
Yields true if either the expression on the right or the expression on the left is true; otherwise, yields false. |
|
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:
/Person[ObjectID='11111111-1111-1111-1111-111111111111' or ObjectID='22222222-2222-2222-2222-222222222222']
the predicate:
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:
/Person[EmployeeType='Full Time Employee' and JobTitle='Engineer']
the predicate:
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:
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 |
|---|---|
|
Returns true if the value of the attribute specified in the first argument contains the second as a substring following a wordbreaking character, otherwise returns false. Note that this implementation differs from contains in XPath 2.0. Given the following string: "The quick brown fox," and the contains() query on the string "u", the expected result is that nothing is returned, since the letter "u" only appears in the middle of a string, and not immediately after a wordbreaker. If we ran the contains() query on the string "qu", however, we would get a match, since the substring "qu" appears immediately after a wordbreaking character. 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. |
|
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. |
|
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. |
|
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. |
|
Returns the current date and time with time zone. For more information see current-dateTime in XPath 2.0. |
|
Returns the arithmetic sum of the arguments. For more information see dateTime in XPath 2.0. |
|
Returns the result of adding the values of the two arguments. For more information see add-dayTimeDuration-to-dateTime in XPath 2.0. |
|
Returns the result of adding the values of the two arguments. For more information see add-yearMonthDuration-to-dateTime in XPath 2.0. |
|
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. |
|
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:
<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 https://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
Concepts
FIM XPath Filter Dialect Examples