Thursday, September 10, 2015

Take the guess work out of XPath with the Lithnet FIM Service PowerShell Module

Summary

The FIM Service allows you to query for resources using a subset of the XPath 2.0 dialect. It provides a quite powerful mechanism for searching for resources, but has more than a few curiosities when it comes to constructing queries for different attribute types.
The Lithnet FIM Service PowerShell module includes three cmdlets to help take the guess work out of constructing your XPath queries.
New-XPathQuery
The New-XPathQuery cmdlet creates a predicate that forms part of an XPath expression. The query is the Attribute = ‘value’ component of the expression
New-XPathQueryGroup
An XPath query group contains multiple XPath query objects, or other query groups, that are combined together with an ‘and’ or ‘or’ operator.
New-XPathExpression
The XPath expression wraps the query or query group with the appropriate syntax defining the object type (eg /Person[query])

Working with different attribute types

The cmdlets generate the correct syntax for each attribute type, without you have having to remember all the different ways the query needs to be expressed.
For example, lets have a look at the way we have to test for presence for each different attribute type
String /Person[(starts-with(AccountName, '%'))]
Integer /Person[(unixGid <= 999999999999999)]
DateTime /Person[(ExpiryDate <= '9999-12-31T23:59:59.997')]
Boolean /Person[((AccountDisabled = true) or (AccountDisabled = false))]
Reference /Person[(Manager = /*)]
The New-XPathQuery cmdlet has a simple syntax, that is independent of the type of attribute.

The cmdlet will automatically generate the syntax that is appropriate for the attribute specified. It’s not just the IsPresent operator that is made simpler. The cmdlets support all the attribute types and operators that are supported by FIM. The underlying Lithnet RMC library used by the cmdlets has over 100 associated unit tests to ensure all combinations of operators and attributes generate the correct XPath syntax.

How do i use it?


Simple query

The following example shows a simple query that checks for an AccountName of ‘ryan’

Combining queries into a group

You can combine multiple queries together in a group using the New-XPathQueryGroup cmdlet. This allows you to join queries created by New-XPathQuery together with an And or Or operator. Searching for an AccountName of ‘bob’ or ‘ryan’ is shown in the example below.

Nested query groups

Query groups can contain child query groups as well. You can build complex nested expressions using  multiple groups. The following example looks for all users who have a display name starting with ‘ryan’ or ‘bob’ that also have an email address

Nested expressions

When querying a reference attribute, you can use another expression as a query parameter. This allows you to build dereferencing expressions with ease. The following example searches for all people who have a manager with the AccountName ‘ryan’

Dereferencing expressions

Creating a dereferencing expression is easy with the DereferenceAttribute parameter on the New-XPathExpression cmdlet. The following example gets the manager of the person with the AccountName ‘ryan’

Using the expression object


Passing the expression to Search-Resources

Expression objects can be passed to other cmdlets such as Search-Resources. Rather than providing an XPath string to Search-Resources, you can simply pass the expression object.

Filter syntax

You can also use the builder to create the Filter attribute used is sets and groups. The –WrapFilterXml parameter ensures that the <Filter> XML element is wrapped around your expression

Setting Filter attributes directly


The library supports setting the value of a Filter attribute to an expression object directly. Ensure you set the –WrapFilterXml parameter on your expression.


Further Reading



Feedback


If you have an idea for a new feature, contact me using one of the methods below

Email: ryan@lithiumblue.com

2 comments :

Anonymous said...

Ryan,

Looks nice. Is your module just a front-end for the FIM Automation Snapin, or is it a replacement? If it is a replacement, is it any faster?

My big complaint with the "official" module is its glacier-like speed. I have not been able to find an answer to why it's so incredibly slow other than "just build X code from Y library", but I'm not a developer. :-(

Thanks,
Erich

Ryan Newington said...

Hi Erich,

It is a full replacement for the FIM Automation snapin. Performance was one of the main reasons I wrote it, with the other being that you needed too much code to do simple things with that module.

It is significantly faster, as it supports compound update and delete operations, has support for multi-threaded create operations, and overcomes a built-in problem with the FIM automation module that makes queries significantly more expensive than they need to be. (The reason you are looking for is that if you dont specify what attributes you want to retrieve on an object, the FIM Service queries every attribute in the database (even those not bound to the object). This is really expensive for the SQL server to process. The Lithnet PowerShell module automatically restricts the list of attributes based on the object type, and provides you the ability to request only the atttributes you need (-AttributesToGet parameter). FIM Automation provides no such support.)

You can read about Ike's experience here https://tlktechidentitythoughts.wordpress.com/2015/09/02/fim-2010-portal-another-powershell-for-fim/.

Our own FIM scripts have gone from hours to execute to minutes without doing anything special.

Hope that helps

Ryan