GroupMethods

Class in module ibisclient.methods

class GroupMethods(conn)

Bases: object

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.

Code author: Dean Rasheed (dev-group@ucs.cam.ac.uk)

allGroups(includeCancelled, fetch=None)

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

includeCancelledbool

[optional] Whether or not to include cancelled groups. By default, only live groups are returned.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch.

Returns

list of IbisGroup

The requested groups (in groupid order).

getCancelledMembers(groupid, fetch=None)

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

groupidstr

[required] The ID or name of the group.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns

list of IbisPerson

The group's cancelled members (in identifier order).

getDirectMembers(groupid, fetch=None)

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

groupidstr

[required] The ID or name of the group.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns

list of IbisPerson

The group's direct members (in identifier order).

getGroup(groupid, fetch=None)

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

groupidstr

[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").

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch.

Returns

IbisGroup

The requested group or None if it was not found.

getMembers(groupid, fetch=None)

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

groupidstr

[required] The ID or name of the group.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch for each person.

Returns

list of IbisPerson

The group's members (in identifier order).

getToken(groupid, 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.

[ HTTP: GET /api/v1/group/{groupid}/token?aud=... ]

Parameters

groupidstr

[required] The ID of the group.

audstr

[required] Audience for the signed JWT.

Returns

str

The serialized JWT

listGroups(groupids, fetch=None)

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

groupidsstr

[required] A comma-separated list of group IDs or group names (may be a mix of both).

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch.

Returns

list of IbisGroup

The requested groups (in groupid order).

modifiedGroups(minTxId, maxTxId, groupids=None, includeCancelled=None, membershipChanges=None, fetch=None)

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

minTxIdlong

[required] Include modifications made in transactions after (but not including) this one.

maxTxIdlong

[required] Include modifications made in transactions up to and including this one.

groupidsstr

[optional] Only include groups with IDs or names in this list. By default, all modified groups will be included.

includeCancelledbool

[optional] Include cancelled groups. By default, cancelled groups are excluded.

membershipChangesbool

[optional] Include groups whose members have changed. By default, changes to group memberships are not taken into consideration.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch.

Returns

list of IbisGroup

The modified groups (in groupid order).

search(query, approxMatches=None, includeCancelled=None, offset=None, limit=None, orderBy=None, fetch=None)

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

querystr

[required] The search string.

approxMatchesbool

[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.

includeCancelledbool

[optional] Flag to allow cancelled groups to be included. Defaults to False.

offsetint

[optional] The number of results to skip at the start of the search. Defaults to 0.

limitint

[optional] The maximum number of results to return. Defaults to 100.

orderBystr

[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.

fetchstr

[optional] A comma-separated list of any additional attributes or references to fetch.

Returns

list of IbisGroup

The matching groups.

searchCount(query, approxMatches=None, includeCancelled=None)

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

querystr

[required] The search string.

approxMatchesbool

[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.

includeCancelledbool

[optional] Flag to allow cancelled groups to be included. Defaults to False.

Returns

int

The number of matching groups.

updateDirectMembers(groupid, addIds=None, removeIds=None, commitComment=None)

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

groupidstr

[required] The ID or name of the group.

addIdsstr

[optional] The identifiers of people to add to the group.

removeIdsstr

[optional] The identifiers of people to remove from the group.

commitCommentstr

[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

list of IbisPerson

The updated list of direct members of the group (in identifier order).