GroupMemberControl is used in the input data object of both the
get API and the update API.
In the get API, GroupMemberControl is used to request the members of a
group. If the GroupMemberControl is added to the input data object,
the members of the group are returned. GroupMemberControl can also be used
to specify the properties to be returned for the members as well as the level
of nested members to be returned.
Because GroupMemberControl is extended from SearchControl, you can specify
properties to return only the groups that satisfy the search criteria. For
example, you can add property expression with value: “entities[@xsi:type='Person']”
to return only the members which are person.
The data graph structure of a GroupMemberControl data object in the get
API 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
- 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
- is used for indicating the level of the hierarchy to be returned. In GroupMemberControl,
it indicates the level of nested members. See the following table.
This table summaries the possible values of level:
Table 1. GroupMemberControl
level valuesGroupMemberControl level |
Description |
1 (default) |
Returns immediate members only. |
0 |
Returns all nested members. |
The data graph structure of a GroupMemberControl data object in the update
API consists of:
- modifyMode
- specifies to use the assign, modify or unassign mode. See the following
table.
This table summaries the possible values of modifyMode:
Table 2. GroupMemberControl
modifyMode valuesGroupMemberControl modifyMode |
Description |
1 (default) |
Assign Mode. The members contained in the group data
object are added to this the group as a members. |
2 |
Replace Mode. The members contained in the group data
object are added to the group as its members and all the existing members
of the group are removed. |
3 |
Unassign Mode. The members contained in the group data
object are removed from the group. |
XML schema definition
The following is the XML schema
definition for the GroupMemberControl DataObject:
<xsd:complexType name="GroupMemberControl">
<xsd:complexContent>
<xsd:extension base="GroupControl">
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
Sample data objects
Following is a sample GroupMemberControl
data object used in the get API. It requests the immediate members (level=1)
of the group. It also indicates to return the uid, cn, o, and ou attributes
for the members, if these attributes exist.
<wim:controls xsi:type="wim:GroupMemberControl" level="1">
<wim:properties>cn</wim:properties>
<wim:properties>uid</wim:properties>
<wim:properties>o</wim:properties>
<wim:properties>ou</wim:properties>
</wim:controls>
Following is a sample GroupMemberControl data object used
in the update API. It indicates that the members are to be unassigned from
the groups.
<wim:controls xsi:type="wim:GroupMemberControl" modifyMode="3"/>