Introduction to WS-Enumeration

In the previous post I introduced WS-Transfer and provided two simple examples how ILM uses it.  In this post I introduce the second protocol, WS-Enumeration.

In contrast to WS-Transfer, WS-Enumerations is a stateful protocol designed to enumerate object instances based on a given filter. After providing the filter, or “query” as we sometimes call it, the client then pulls object instances page-by-page.  The protocol works as follows (Figure below):

1. A client sends an enumerate request which requests the ILM Service to prepare an ordered list of ILM object instances based on some filter.
2. The ILM Service returns an “enumeration context” in the response. The enumeration context is an opaque string the client uses to refer to this enumeration session.
3. The client sends a pull request with the numeration context.  Because the enumeration context is required, a pull request is only valid after a successful enumerate request and before the enumeration context expires.  This ordering is why we call WS-Enumeration stateful.
4. The server returns data to the client in the pull response.  Like WS-Transfer, we use XML representations of ILM object instances.
5. The client keeps pulling data until it receives an end of sequence notice.

Let’s describe the operations in details:

Enumerate

The enumerate operation requests the ILM Service to provide a list of object instances based on a provided filter. In ILM this filter is a subset of XPath.  You may use simple, limited features from XPath to specify predicates and selection.  To filter all Person objects, you would use filter “/Person” and to filter on all types of objects in ILM, you would use filter “/ObjectTypeDescription”.  The ILM Service returns an enumeration context in the response that the client may use to pull instances included in the filter.

Pull

The pull operation requests the next N object instances for a given enumeration context where N is provided in the request. The ILM Service returns at most N XML representations of these object instances in the response. Each of the returned objects satisfies the filter in the enumerate request.

GetStatus

Because enumeration contexts can expire, the GetStatus operation requests the ILM Service to provide the expiration of a given enumeration context.

Renew

The renew operation requests the ILM Service to set the expiration of a given enumeration context to a new time. This operation is useful for extending long-running pulls. In practical terms, however, few ILM clients will need to invoke this operation.

Release

The release operation requests the ILM Service to discard the enumeration context. It is not necessary for clients to invoke this operation, but it is helpful in freeing up resources prior to their expiration.

WS-Enumeration usage in ILM “2”

ILM uses WS-Enumeration for querying objects.  For instance, when you click on “My Groups”, the portal is simply making a WS-Enumeration call with filter “/Group[Owner=’{0000}’]” where {0000} is your user id.  WS-Enumeration is also the supported interface for gathering data for reporting.  I have seen pretty sweet demos of SQL Reporting Services using nothing but a WS-Enumeration adapter as a data source.

Please note that WS-Enumeration operations only return “naked” XML representations of object instances. In some cases WS-Enumeration operations will dereference object instances like group members into Person objects.

In our next post we’ll introduce the WS-Transfer Extensions for Identity Management Operations.