AncestorControl DataObject
AncestorControl is used to request the ancestors of an entity.
The AncestorControl data object extends from HierarchyControl. It is used in the input data object of the get API to request the ancestors of an entity. If AncestorControl is added to the data object in a get operation, the ancestors of the entities under Root DataObject are returned in the returning data object.
Because AncestorControl is extended from SearchControl, you can specify search properties in the AncestorControl to return only the ancestors that satisfy the search criteria. AncestorControl can also be used to specify the level and the properties to be returned for the ancestors.
The data graph structure of a AncestorControl data object consists of:
- properties
- is a list of the attributes you want to return from the entities which match the search criteria. For example, you want to get the sn and givenName attributes of the persons who is in marketing department.
- searchBases
- is a list of the search bases used to limit the search to those bases specified in the list.
- countLimit
- specifies the maximum number of search results returned by the search operation.
- timeLimit
- If the profile repository supports timeLimit, it specifies in milliseconds the maximum duration of the search.
- expression
- is the search expression in XPath format.
- level
- specifies the level of the ancestors to return. The default value for the level is 1. See the following table.
This table summaries the possible values of the ancestor level:
AncestorControl level | Description |
---|---|
1 (default) | Returns parent only. |
Any positive integer | Returns the specified level of ancestors. For example, specifying 2 returns two levels, the parent and grandparent. |
0 | Returns all the ancestors up to the virtual member manager node. |
XML schema definition
The following is the XML schema
definition for the AncestorControl DataObject.
<xsd:complexType name="AncestorControl">
<xsd:complexContent>
<xsd:extension base="HierarchyControl">
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
Sample data object
Following is a sample AncestorControl
DataObject that returns all ancestors and their uid, cn, o, and ou properties
if they exist:
<wim:controls xsi:type="wim:AncestorControl" level="0">
<wim:properties>uid</wim:properties>
<wim:properties>cn</wim:properties>
<wim:properties>o</wim:properties>
<wim:properties>ou</wim:properties>
</wim:controls>