Sample scenario: Enumerate all persons

We saw in our previous post how to get a specific person.  If you don’t exactly know which person you want, you instead need to enumerate objects from ILM.  ILM exposes a WS-Enumeration endpoint which enables you specify a filter query and then page over results.  We described the WS-Enumeration protocol a bit more in Topic 6.

To enumerate over each person object in ILM we must pass a filter that only returns person objects.  To do this we specify the XPath expression “/Person”.  For those with .NET backgrounds, think of this expression as syntactically similar to the expression you would pass to XmlNode.SelectNodes(String).  ILM supports modest filters compared to XmlNode, but even with simple rules you can construct very useful results.  For example, to get the administrator person, one way is to use the expression “/Person[DisplayName=’Administrator’]”.  Unfortunately fully describing the filter language is beyond the scope of this particular post, and for now we suggest trial and error or reading the MSDN page above for information on XPath expressions.  If there is enough demand we may cover this topic later.

Let’s get to the code:

static void Topic13EnumeratePerson()

        {

            WSEnumerationClient enumerationClient = new WSEnumerationClient();

            enumerationClient.ClientCredentials = GetCredentials();

            enumerationClient.Enumerate("/Person");

            while (enumerationClient.IsContextValid)

            {

                foreach (ResourceManagementObject person in enumerationClient.Pull())

                {

                    Assert.IsNotNull(person);

                    Assert.IsFalse(String.IsNullOrEmpty(person.ObjectId));

                }

            }

            Console.WriteLine("Topic 13 Complete");

        }

1. First we use the enumeration client instead of transfer client.  Recall that the enumeration client has a state.  You must call enumerate before trying to call pull, for example.  With the transfer client you could call the methods in any order.
2. We specify the client’s credentials as before.
3. We begin the enumeration by calling Enumerate.  We provide the Enumerate method our XPath filter.
4. (The while loop) We keep pulling data so long as our enumeration context is valid.  Each pull response and the initial enumeration response includes a context.  If the context is missing then we know that no further results can be obtained.
5. (The foreach loop) We then iterate over each object returned from a pull.  Recall that pull retrieves at most a fixed number of objects from the server.  This operation enables paging, and by default we only return 15 objects.  To ensure we call pull ceil(n/15) for n persons we place the foreach loop inside the while loop.
6. (The body of the foreach) We provide sample code to validate we get data back.  This is where you would do interesting things with the objects.

That’s it!  The next steps are to construct business-relevant queries and do something with the objects you get back.

In our next post we’ll use the enumeration client to construct a useful view of ILM’s schema.