DescendantControl DataObject
DescendantControl is used to request the descendants of an entity.
The DescendantControl data object extends from HierarchyControl. It is used in the input data object of the get API to request descendants of the entity. If DescendantControl is added to the data object in a get operation, the descendants of the entities under Root DataObject are returned in the returning data graph.
Because DescendantControl is extended from SearchControl, you can specify search properties in the DescendantControl to return only the descendants that satisfy the search criteria. For example, you can add property expression with value: entities[@xsi:type='PersonAccount'] to return only the descendants that are of PersonAccount entity type. DescendantControl can also be used to specify the level and the properties to be returned for the descendants.
- 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
- is used to specify 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 descendants to be returned. The default value for the level is 1. See the following table.
DescendantControl level | Description |
---|---|
1 (default) | Returns children only. |
Any positive integer | Returns the specified level of descendants. For example, specifying 2 returns two levels, the children and grandchildren. |
0 | Returns all the descendants. |
XML schema definition
<xsd:complexType name="DescendantControl">
<xsd:complexContent>
<xsd:extension base="HierarchyControl">
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
Sample data object
<wim:controls xsi:type="wim:DescendantControl" level="0">
<wim:properties>uid</wim:properties>
<wim:properties>cn</wim:properties>
<wim:properties>o</wim:properties>
<wim:properties>ou</wim:properties>
</wim:controls>