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='PersonAccount']” to return only the members
which are of PersonAccount entity type.
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"/>