Express (Distributed operating systems), v8.0 > Secure applications and their environment > Authenticate users > Select a registry or repository > Manage realms in a federated repository > Virtual member manager > Reference > Program model > Control DataObject
GroupMembershipControl DataObject
GroupMembershipControl is used in the input data object of both the get API and the update API.
In the get API, GroupMembershipControl is used to request the groups that an entity belongs to. If theGroupMembershipControl is added to the input data object, the groups the entity belongs to are returned. GroupMembershipControl can also be used to specify the properties to be returned for groups as well as the level of nested groups to be returned.
Because GroupMembershipControl 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='Group' and cn='Admin*']” to return only the groups whose “cn” property starts with “Admin”.
The structure of a GroupMembershipControl data object in the get API consists of:
properties
is a list of the attributes to return from the entities which match the search criteria. For example, 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
is used for indicating the level of the nested groups to return. The default value for level is 1. See the following table. This table summaries the possible values of level:
GroupMembershipControl level values
GroupMembershipControl level Description 1 (default) Returns immediate groups only. 0 Returns all nested groups The structure of a GroupMembershipControl 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:
GroupMembershipControl modifyMode values
GroupMembershipControl modifyMode Description 1 (default) Assign Mode. The groups contained in the entity data object add the entity as a member. 2 Replace Mode. The groups contained in the entity data object add the entity as a member and all the existing members are removed. 3 Unassign Mode. The groups contained in the entity data object remove the entity from their members.
XML schema definition
The following is the XML schema definition for the GroupMembershipControl:
data object <xsd:complexType name="GroupMembershipControl"> <xsd:complexContent> <xsd:extension base="GroupControl"> </xsd:extension> </xsd:complexContent> </xsd:complexType>
Sample data objects
Following is a sample GroupMembershipControl DataObject used in the get API. It requests the immediate groups (level=1) that the entity belongs to. It also indicates to return the “cn” attribute for the groups, if the attribute exists.
<wim:controls xsi:type="wim:GroupMembershipControl" level="1"> <wim:properties>cn </wim:properties> <wim:properties>displayName </wim:properties> </wim:controls>Following is a sample GroupMembershipControl DataObject used in the update API. It indicates that the entity is to be unassigned from the groups.
<wim:controls xsi:type="wim:GroupMembershipControl" modifyMode="3"/>
Parent topic: Control DataObject