Enumeration Endpoint

Article
06/14/2010

The Enumeration endpoint of Forefront Identity Manager (FIM) provides operations by which client applications can retrieve, in batches, a collection of objects that matches specified criteria. The operations are the industry-standard ones defined by the WS-Enumeration specification.

The Enumeration endpoint also provides some extensions to the operations defined by the WS-Enumeration specification. For example, clients can use the endpoint in the following ways.

Determine the total number of objects matching the client's specified criteria.
Traverse the objects in a collection both forwards and backward.
Go to a particular subset of the collection.
Retrieve the first batch of responses in the Enumeration Response message.
Request a set of objects as they existed at a specific time.
Request a set of objects that have been localized to a particular locale.
Enumerate the properties of an object.
Request a subset of object properties.
Specify that the requested objects are returned in sorted order.

The FIM Query specification defines additional extensions by which clients can indicate the particular elements of the objects matching their specified criteria that they want to retrieve, and specify a sort order.

Initiating a Query

Clients can retrieve a collection of objects matching specified criteria by invoking the Enumerate operation of the Enumeration endpoint. Pass in a query expression that is in a language defined by the FIM Query specification. If the operation succeeds, the client will receive the following data items in response:

An XML representation of an enumeration context. Enumeration contexts are defined in the WS-Enumeration specification. An enumeration context is a reference the client can use in subsequent requests to the Enumeration endpoint to identify the query that was expressed in the original invocation of the Enumerate operation. The client must refer to the query in subsequent requests to retrieve its results.
The expiration time for the enumeration context. The expiration time is always calculated by adding a user-configurable duration to the time of the Enumerate request. The FIM deployment specification defines how you configure this duration.
A count of the total number of objects matching the query. This is an extension to the WS-Enumeration specification.

Retrieving the Results

To retrieve the results of a query, the client invokes the Pull operation of the Enumeration endpoint, providing the enumeration context as input, and receives the next batch of objects that matches the query. The client can also specify the maximum number of objects included in the batch. As an extension to the WS-Enumeration specification, the client can also specify the index number of a particular object in the collection of objects that matches the query. Objects are added to the batch starting from the index number. As another extension to the WS-Enumeration specification, the client can specify the direction in which objects are to be added to the batch: proceeding forward through the collection of objects that matches the query toward the end, or proceeding backward through the collection toward the start.

Renewing the Enumeration Context

As indicated earlier in this topic, the response to a successful invocation of the Enumerate operation returns an expiration time for the enumeration context. A client can invoke the Renew operation to request that the expiration time for an enumeration context be extended. The client must provide the enumeration context as input.

If the request succeeds, the client will return the new expiration time for the enumeration context. The new expiration time is calculated by adding the same configurable duration used to create the original request to the time of the Renew request.

Querying the Expiration Time of an Enumeration Context

To retrieve the expiration time for a particular enumeration context, a client can invoke the GetStatus operation of the Enumeration endpoint, passing in the enumeration context.

Discarding an Enumeration Context

A client can invoke the Release operation of the Enumeration endpoint, providing the enumeration context as input, to discard an enumeration context before it expires.

Behavior

The following illustration shows the behavior of the Enumeration endpoint.

Operations of the Enumeration endpoint

Exceptions

The endpoints of the FIM Service respond to exceptions by returning SOAP faults to their clients. The WS-Enumeration specification defines several such faults that may be returned by the Resource endpoint.

See Request Processing for more information about how the FIM Service responds to requests for objects that the user is not permitted to access.

EnumerationEnd Messages

The FIM Service does not send the optional EnumerationEnd message to clients.

Information Disclosure

No personally identifying information is disclosed by the ordinary response to the invocation of the Enumeration endpoint's Enumerate, Renew, GetStatus, or Release operations. The potential disclosure of information in fault responses is discussed in Message-Specific Authentication.

Operations

The Enumeration endpoint implements the following operations:

The default endpoint address is https://Localhost: 5725/ResourceManagementService/Enumeration.

Remarks

The FIM web service only accepts UTF-8 encoding of strings and SOAP messages. Other encodings will be converted to UTF-8 if possible. If an encoding cannot be converted to UTF-8 then the web service will return wxf:InvalidRepresentationFault (see WS-Transfer: Identity Management Operations for Directory Access Extensions specification).