Class GroupMethods

Methods for querying and manipulating groups.

The fetch parameter for groups

All methods that return groups also accept an optional fetch parameter that may be used to request additional information about the groups returned. For more details about the general rules that apply to the fetch parameter, refer to the PersonMethods documentation.

For groups the fetch parameter may be used to fetch references to people, institutions or other groups. In each case, only non-cancelled people, institutions and groups will be included when fetching references. The following references are supported:

"all_members" - fetches all the people who are members of the group, including members of groups included by the group, and groups included by those groups, and so on.
"direct_members" - fetches all the people who are direct members of the group, not taking into account any included groups.
"members_of_inst" - if the group is a membership group for an institution, this fetches that institution.
"owning_insts" - fetches all the institutions to which the group belongs.
"manages_insts" - fetches all the institutions that the group manages. Typically this only applies to "Editor" groups.
"manages_groups" - fetches all the groups that this group manages. Note that some groups are self-managed, so this may be a self-reference.
"managed_by_groups" - fetches all the groups that manage this group.
"reads_groups" - fetches all the groups that this group has privileged access to. This means that members of this group can see the members of the referenced groups regardless of the membership visibility settings.
"read_by_groups" - fetches all the groups that have privileged access to this group.
"includes_groups" - fetches all the groups included by this group.
"included_by_groups" - fetches all the groups that include this group.

As with person fetch parameters, the references may be used in a chain by using the "dot" notation to fetch additional information about referenced people, institutions or groups. For example "all_members.email" will fetch the email addresses of all members of the group. For more information about what can be fetched from referenced people and institutions, refer to the documentation for PersonMethods and InstitutionMethods.

Author: Dean Rasheed (dev-group@ucs.cam.ac.uk)
Located at methods/GroupMethods.php

Methods summary

`public`	# `__construct(ClientConnection $conn)` Create a new GroupMethods object. Create a new GroupMethods object. Parameters `$conn` The ClientConnection object to use to invoke methods on the server.
`public IbisGroup[]`	# `allGroups(boolean $includeCancelled, string $fetch = null)` Return a list of all groups. Return a list of all groups. By default, only a few basic details about each group are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references. `[ HTTP: GET /api/v1/group/all-groups ]` Parameters `$includeCancelled` [optional] Whether or not to include cancelled groups. By default, only live groups are returned. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The requested groups (in groupid order).
`public IbisGroup[]`	# `listGroups(string $groupids, string $fetch = null)` Get the groups with the specified IDs or names. Get the groups with the specified IDs or names. By default, only a few basic details about each group are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references. The results are sorted by groupid. NOTE: The URL path length is limited to around 8000 characters, which limits the number of groups that this method can fetch. Group IDs are currently 6 characters long, and must be comma separated and URL encoded, which limits this method to around 800 groups by ID, but probably fewer by name, depending on the group name lengths. NOTE: The groups returned may include cancelled groups. It is the caller's responsibility to check their cancelled flags. `[ HTTP: GET /api/v1/group/list?groupids=... ]` Parameters `$groupids` [required] A comma-separated list of group IDs or group names (may be a mix of both). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The requested groups (in groupid order).
`public IbisGroup[]`	# `modifiedGroups(long $minTxId, long $maxTxId, string $groupids = null, boolean $includeCancelled = null, boolean $membershipChanges = null, string $fetch = null)` Find all groups modified between the specified pair of transactions. Find all groups modified between the specified pair of transactions. The transaction IDs specified should be the IDs from two different requests for the last (most recent) transaction ID, made at different times, that returned different values, indicating that some Lookup data was modified in the period between the two requests. This method then determines which (if any) groups were affected. By default, only a few basic details about each group are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references. NOTE: All data returned reflects the latest available data about each group. It is not possible to query for old data, or more detailed information about the specific changes made. `[ HTTP: GET /api/v1/group/modified-groups?minTxId=...&maxTxId=... ]` Parameters `$minTxId` [required] Include modifications made in transactions after (but not including) this one. `$maxTxId` [required] Include modifications made in transactions up to and including this one. `$groupids` [optional] Only include groups with IDs or names in this list. By default, all modified groups will be included. `$includeCancelled` [optional] Include cancelled groups. By default, cancelled groups are excluded. `$membershipChanges` [optional] Include groups whose members have changed. By default, changes to group memberships are not taken into consideration. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The modified groups (in groupid order).
`public IbisGroup[]`	# `search(string $query, boolean $approxMatches = null, boolean $includeCancelled = null, integer $offset = null, integer $limit = null, string $orderBy = null, string $fetch = null)` Search for groups using a free text query string. This is the same search function that is used in the Lookup web application. Search for groups using a free text query string. This is the same search function that is used in the Lookup web application. By default, only a few basic details about each group are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references. NOTE: If the query string starts with the prefix `"group:"`, it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the `approxMatches` parameter, but it will respect the value of `includeCancelled`. In addition, an LQL query will ignore the `orderBy` parameter, since LQL queries always return results in ID order. `[ HTTP: GET /api/v1/group/search?query=... ]` Parameters `$query` [required] The search string. `$approxMatches` [optional] Flag to enable more approximate matching in the search, causing more results to be returned. Defaults to `false`. This is ignored for LQL queries. `$includeCancelled` [optional] Flag to allow cancelled groups to be included. Defaults to `false`. `$offset` [optional] The number of results to skip at the start of the search. Defaults to 0. `$limit` [optional] The maximum number of results to return. Defaults to 100. `$orderBy` [optional] The order in which to list the results. This may be `"groupid"`, `"name"` (the default for non-LQL queries) or `"title"`. This is ignored for LQL queries, which always return results in groupid order. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The matching groups.
`public integer`	# `searchCount(string $query, boolean $approxMatches = null, boolean $includeCancelled = null)` Count the number of groups that would be returned by a search using a free text query string. Count the number of groups that would be returned by a search using a free text query string. NOTE: If the query string starts with the prefix `"group:"`, it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the `approxMatches` parameter, but it will respect the value of `includeCancelled`. `[ HTTP: GET /api/v1/group/search-count?query=... ]` Parameters `$query` [required] The search string. `$approxMatches` [optional] Flag to enable more approximate matching in the search, causing more results to be returned. Defaults to `false`. This is ignored for LQL queries. `$includeCancelled` [optional] Flag to allow cancelled groups to be included. Defaults to `false`. Returns integer The number of matching groups.
`public IbisGroup`	# `getGroup(string $groupid, string $fetch = null)` Get the group with the specified ID or name. Get the group with the specified ID or name. By default, only a few basic details about the group are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references of the group. NOTE: The group returned may be a cancelled group. It is the caller's responsibility to check its cancelled flag. `[ HTTP: GET /api/v1/group/{groupid} ]` Parameters `$groupid` [required] The ID or name of the group to fetch. This may be either the numeric ID or the short hyphenated group name (for example `"100656"` or `"cs-editors"`). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup` The requested group or `null` if it was not found.
`public IbisPerson[]`	# `getCancelledMembers(string $groupid, string $fetch = null)` Get all the cancelled members of the specified group, including cancelled members of groups included by the group, and groups included by those groups, and so on. Get all the cancelled members of the specified group, including cancelled members of groups included by the group, and groups included by those groups, and so on. By default, only a few basic details about each member are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references of each person. NOTE: This method returns only cancelled people. It does not include people who were removed from the group. Cancelled people are no longer considered to be current staff, students or accredited visitors, and are no longer regarded as belonging to any groups or institutions. The list returned here reflects their group memberships just before they were cancelled, and so is out-of-date data that should be used with caution. `[ HTTP: GET /api/v1/group/{groupid}/cancelled-members ]` Parameters `$groupid` [required] The ID or name of the group. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch for each person. Returns `IbisPerson[]` The group's cancelled members (in identifier order).
`public IbisPerson[]`	# `getDirectMembers(string $groupid, string $fetch = null)` Get the direct members of the specified group, not including members included via groups included by the group. Get the direct members of the specified group, not including members included via groups included by the group. By default, only a few basic details about each member are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references of each person. NOTE: This method will not include cancelled people. `[ HTTP: GET /api/v1/group/{groupid}/direct-members ]` Parameters `$groupid` [required] The ID or name of the group. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch for each person. Returns `IbisPerson[]` The group's direct members (in identifier order).
`public IbisPerson[]`	# `updateDirectMembers(string $groupid, string $addIds = null, string $removeIds = null, string $commitComment = null)` Update the list of people who are direct members of the group. This will not affect people who are included in the group due to the inclusion of other groups. Update the list of people who are direct members of the group. This will not affect people who are included in the group due to the inclusion of other groups. Any non-cancelled people in the list of identifiers specified by `addIds` will be added to the group. This list should be a comma-separated list of identifiers, each of which may be either a CRSid or an identifier from another identifier scheme, prefixed with that scheme's name and a slash. For example `"mug99"` or `"usn/123456789"`. Any people in the list of identifiers specified by `removeIds` will be removed from the group, except if they are also in the list `addIds`. The special identifier `"all-members"` may be used to remove all existing group members, replacing them with the list specified by `newIds`. Examples: updateDirectMembers("test-group", "mug99,crsid/yyy99,usn/123456789", "xxx99", "Remove xxx99 and add mug99, yyy99 and usn/123456789 to test-group"); updateDirectMembers("test-group", "xxx99,yyy99", "all-members", "Set the membership of test-group to include only xxx99 and yyy99"); `[ HTTP: PUT /api/v1/group/{groupid}/direct-members ]` Parameters `$groupid` [required] The ID or name of the group. `$addIds` [optional] The identifiers of people to add to the group. `$removeIds` [optional] The identifiers of people to remove from the group. `$commitComment` [recommended] A short textual description of the change made (will be visible on the history tab of the group and all the affected people in the web application). Returns `IbisPerson[]` The updated list of direct members of the group (in identifier order).
`public IbisPerson[]`	# `getMembers(string $groupid, string $fetch = null)` Get all the members of the specified group, including members of groups included by the group, and groups included by those groups, and so on. Get all the members of the specified group, including members of groups included by the group, and groups included by those groups, and so on. By default, only a few basic details about each member are returned, but the optional `fetch` parameter may be used to fetch additional attributes or references of each person. NOTE: This method will not include cancelled people. `[ HTTP: GET /api/v1/group/{groupid}/members ]` Parameters `$groupid` [required] The ID or name of the group. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch for each person. Returns `IbisPerson[]` The group's members (in identifier order).
`public String`	# `getToken(string $groupid, string $aud)` Get a signed JSON Web Token (JWT) with the group as subject and specified audience, only if authorized user/group has permission to edit the group. Get a signed JSON Web Token (JWT) with the group as subject and specified audience, only if authorized user/group has permission to edit the group. `[ HTTP: GET /api/v1/group/{groupid}/token?aud=... ]` Parameters `$groupid` [required] The ID of the group. `$aud` [required] Audience for the signed JWT. Returns String The serialized JWT

Classes

Interfaces

Exceptions

Class GroupMethods

Methods summary

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns