Enumerate
The Enumeration Endpoint implements the Enumerate operation defined in the WS-Enumeration specification. The Enumerate operation enumerates a set of objects retrieved by a query.
Parameters
Action Header
For more information, see WS-Enumeration specification.
Filter Element
When a client initiates a query, the client invokes the Enumerate method and passes in a WS-Enumeration filter that identifies the objects to retrieve. For the implementation of the WS-Enumeration provided by the FIM Service, filters are formed using a subset of the XPath language. For more information, see FIM XPath Filter Dialect.
LocalePreferences Element
As an extension to WS-Enumeration, a client can request a collection of localized objects. The <LocalePreferences> element contains one or more <LocalePreference> elements. Each <LocalePreference> element specifies a <Locale> element and precedence for that locale in case multiple localized versions of the object property have been stored in the FIM Service database. For each property corresponding to one of the requested objects, only the property value corresponding to the locale with highest precedence is returned. The <PreferenceValue> element is a positive integer that specifies the precedence of the preferred locale, with 0 indicating the highest precedence. Specifying a locale preference is optional; if it is not defined, the default locale for each object property is returned.
<xs:schema
elementFormDefault='qualified'
targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'
xmlns:xs='http://www.w3.org/2001/XMLSchema'
xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
<xs:complexType
name='LocalePreferenceType'>
<xs:sequence>
<xs:element
name='Locale'
minOccurs='1'
maxOccurs='1'
nillable='false'
type='xs:string'/>
<xs:element
name='PreferenceValue'
minOccurs='1'
maxOccurs='1'
nillable='false'
type='xs:integer'/>
</xs:sequence>
</xs:complexType>
<xs:complexType
name='LocalePreferencesType'>
<xs:sequence>
<xs:element
name='LocalePreference'
minOccurs='1'
maxOccurs='unbounded'
nillable='false'
type='rm:LocalePreferenceType'/>
</xs:sequence>
</xs:complexType>
<xs:element
name='LocalePreferences'
nillable='false'
type='rm:LocalePreferencesType ' />
</xs:schema>
MaxElements Element
As an extension to WS-Enumeration, a client can request the maximum number of elements to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxElements parameter. This parameter is optional.
MaxCharacters Element
As an extension to WS-Enumeration, a client can request the maximum number of characters to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxCharacters parameter. This parameter is optional.
MaxTime Element
As an extension to WS-Enumeration, a client can request the maximum time allowed to generate the first batch of records to be returned in the Enumeration Response. This element complies with the WS-Enumeration specification for the Pull method MaxTime parameter. This parameter is optional.
Selection Element
As an extension to WS-Enumeration, a client can request that enumeration results include only specific attributes. Multiple selection elements can appear as children of the Enumerate element to select multiple attributes. If omitted, the server sorts results in an undefined way. If an attribute does not have a value for a requested attribute, the attribute is omitted for that particular result.
The following XML defines the schema for the Selection element:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement">
<xs:element name="Selection" type="xs:string"/>
</xs:schema>
Sorting Element
As an extension to WS-Enumeration, a client can request that enumeration results be sorted by one attribute. If omitted, the server sorts results in an undefined way.
The following XML defines the schema for the Sorting element:
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement">
<xs:element name="Sorting">
<xs:complexType>
<xs:sequence>
<xs:element name="SortingAttribute" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="Ascending" type="xs:string"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="Dialect" type="xs:string"/>
</xs:complexType>
</xs:element>
</xs:schema>
Return Value
Action Header
For more information, see WS-Enumeration specification.
Enumeration Context Element
As specified in the WS-Enumeration specification, responses to successful invocations of the Enumerate operation will incorporate an <EnumerationContext> element. The structure of the <EnumerationContext> element is left to implementers of the WS-Enumeration specification to determine. The following XML Schema describes the structure of the enumeration context elements provided in response to successful invocations of the FIM Service endpoint's Enumerate operation.
Note
Clients should not modify the contents of the enumeration context.
The following XML defines the schema for the Enumerate element:
<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration"
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement"
targetNamespace="https://schemas.microsoft.com/2006/11/ResourceManagement">
<xs:complexType name="EnumerationContextType">
<xs:sequence>
<xs:element name="CurrentIndex" type="xs:string"/>
<xs:element name="EnumerationDirection" type="xs:string"/>
<xs:element name="Expires" type="xs:string"/>
<xs:element name="Filter" type="xs:string"/>
<xs:element name="LocalePreferences" type="xs:string"/>
<xs:element name="Selection" type="xs:string"/>
<xs:element name="Sorting" type="xs:string"/>
<xs:element name="Count" type="xs:string"/>
</xs:sequence>
</xs:complexType>
</xs:schema>
The following table describes the elements of this structure.
| Element | Description |
|---|---|
EnumerationContext |
An opaque complex type used to maintain context for pulls. |
Expires Element
Responses to successful invocations of the Enumerate operation will incorporate the <Expires> element defined in the WS-Enumeration specification. This element gives the expiration time of the enumeration context. The expiration time is always calculated by the server so enumeration contexts do not expire.
EnumerationDetail Element
Also included in the response to any successful invocation of the Enumerate operation will be an <EnumerationDetail> element that provides a count of the number of objects matching the WS-Enumeration filter included in the original Enumerate request. The following code sample shows the structure of the <EnumerationDetail> element.
<?xml version='1.0' encoding='utf-8'?>
<xs:schema
elementFormDefault='qualified'
targetNamespace='https://schemas.microsoft.com/2006/11/ResourceManagement'
xmlns:xs='http://www.w3.org/2001/XMLSchema'
xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement'>
<xs:complexType
name='EnumerationDetailType'>
<xs:sequence>
<xs:element
name='Count'
minOccurs='0'
maxOccurs='1'
nillable='false'
type='xs:integer'/>
</xs:sequence>
</xs:complexType>
<xs:element
name='EnumerationDetail'
nillable='true'
type='rm:EnumerationDetailType' />
</xs:schema>
The following table describes the elements of this schema.
| Element | Description |
|---|---|
Count |
A count of the number of objects that match the WS-Enumeration filter included in the Enumeration request. |
EnumerationDetailType |
A wrapper. |
The following code example shows an EnumerationResponse message incorporating an <EnumerationDetail> element.
<s:Envelope
xmlns:s='http://www.w3.org/2003/05/soap-envelope'
xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/08/addressing'
xmlns:wsen=' https://schemas.xmlsoap.org/ws/2004/09/enumeration'
xmlns:rm='https://schemas.microsoft.com/2006/11/ResourceManagement' >
<s:Header>
...
<wsa:Action>
https://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse
</wsa:Action>
...
<rm:ResourceManagement s:mustUnderstand=“true"/>
</s:Header>
<s:Body>
<wsen:EnumerateResponse>
<wsen:EnumerationContext>
<rm:Count>1</rm:Count>
<rm:CurrentIndex>0</rm:CurrentIndex>
<rm:EnumerationDirection>Forwards</rm:EnumerationDirection>
<rm:Expires>12/31/9999 11:59:59 PM</rm:Expires>
<rm:Filter>/ma-data</rm:Filter>
<rm:LocalePreferences xsi:nil="true" />
<rm:Selection xsi:nil="true" />
<rm:Sorting xsi:nil="true" />
</wsen:EnumerationContext> ...
<rm:EnumerationDetail>
<rm:Count>100</rm:Count>
</rm:EnumerationDetail>
</wsen:EnumerateResponse>
</s:Body>
</s:Envelope>
Examples
Example Enumerate Message
The following code example shows an Enumerate message.
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration"
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement">
<s:Header>
<wsa:ReplyTo>
<wsa:Address>
http://www.fabrikam.com/sender
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>
http://www.fabrikam.com:5725/IdentityManagementService/Enumeration
</wsa:To>
<wsa:Action>
https://schemas.xmlsoap.org/ws/2004/09/enumeration/Enumerate
</wsa:Action>
<wsa:MessageID>
uuid:00000000-0000-0000-C000-000000000046
</wsa:MessageID>
</s:Header>
<s:Body>
<Enumerate xmlns="https://schemas.xmlsoap.org/ws/2004/09/enumeration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Filter Dialect="https://schemas.microsoft.com/2006/11/XPathFilterDialect">/ma-
data</Filter>
<LocalePreferences xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">
<LocalePreference>
<Locale>en-US</Locale>
<PreferenceValue>0</PreferenceValue>
</LocalePreference>
</LocalePreferences>
<MaxElements>20</MaxElements>
<MaxCharacters>3668672</MaxCharacters>
<Sorting Dialect="https://schemas.microsoft.com/2006/11/XPathFilterDialect"
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">
<SortingAttribute Ascending="true">DisplayName</SortingAttribute>
</Sorting>
<Selection
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">DisplayName</Selection>
<Selection
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">CreatedTime</Selection>
<Selection
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">Creator</Selection>
<Selection
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">ObjectType</Selection>
<Selection
xmlns="https://schemas.microsoft.com/2006/11/ResourceManagement">ObjectID</Selection>
<Time xsi:nil="true"></Time>
</Enumerate>
</s:Body>
</s:Envelope>
Example Enumerate Response
The following code example shows a response to a successful invocation of the Enumerate operation.
<s:Envelope xmlns:s=http://www.w3.org/2003/05/soap-envelope
xmlns:wsa="http://www.w3.org/2005/08/addressing"
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:wsen="https://schemas.xmlsoap.org/ws/2004/09/enumeration
xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:wsc="https://schemas.microsoft.com/ws/2006/05/context"
xmlns:rm="https://schemas.microsoft.com/2006/11/ResourceManagement">
<s:Header>
<wsa:Action s:mustUnderstand="1">
https://schemas.xmlsoap.org/ws/2004/09/enumeration/EnumerateResponse
</wsa:Action>
<wsa:RelatesTo>urn:uuid:e3a74cd4-d623-47d6-b33b-0dd733808b66</wsa:RelatesTo>
</s:Header>
<s:Body u:Id="_2">
<wsen:EnumerateResponse>
<wsen:Expires>12/31/9999 11:59:59 PM</wsen:Expires>
<wsen:EnumerationContext>
<rm:Count>1</rm:Count>
<rm:CurrentIndex>0</rm:CurrentIndex>
<rm:EnumerationDirection>Forwards</rm:EnumerationDirection>
<rm:Expires>12/31/9999 11:59:59 PM</rm:Expires>
<rm:Filter>/ma-data</rm:Filter>
<rm:LocalePreferences xsi:nil="true" />
<rm:Selection>
<rm:string>DisplayName</string>
<rm:string>ObjectType</string>
<rm:string>ObjectId</string>
<rm:string>CreatedTime</string>
<rm:string>Creator</string>
</rm:Selection>
<rm:Sorting
Dialect="https://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeTyp
e-20080602">
<rm:SortingAttribute Ascending="true">DisplayName</rm:SortingAttribute>
</rm:Sorting>
</wsen:EnumerationContext>
<rm:EnumerationDetail>
<rm:Count>1</rm:Count>
</rm:EnumerationDetail>
</wsen:EnumerateResponse>
<wsen:Items>
<rm:ma-data>
<rm:ObjectType>ma-data</rm:ObjectType>
<rm:ObjectID>
urn:uuid:fa14aafd-d74b-4833-bd94-94c96ee1b278
</rm:ObjectID>
<rm:DisplayName>AD Management Agent</rm:DisplayName>
<rm:CreatedTime>2009-01-20T23:28:40.207</rm:CreatedTime>
<rm:Creator>
urn:uuid:23dbfb6c-557f-48d1-ac38-6d570ddbe189
</rm:Creator>
</rm:ma-data>
</wsen:Items>
</s:Body>
</s:Envelope>