PersonMethods

Class in module ibisclient.methods

class PersonMethods(conn)

Bases: object

Methods for querying and manipulating people.

Notes on the fetch parameter

All methods that return people, institutions or groups also accept an optional fetch parameter that may be used to request additional information about the entities returned. Without this parameter, only a few basic details about each person, institution or group are returned. The fetch parameter is quite flexible, and may be used in a number of different ways:

• Attribute fetching. Attributes may be fetched by specifying the schemeid of an attribute scheme. For example to fetch a person's email addresses, use the value "email". For people common attribute schemes include "jpegPhoto", "misAffiliation", "title", "universityPhone", "mobexPhone", "landlinePhone", "mobilePhone", "pager", "labeledURI" and "address". The full list of person attribute schemes may be obtained using PersonMethods.allAttributeSchemes().

• Pseudo-attributes. Certain special pseudo-attributes are defined for convenience. For people, the following pseudo-attributes are supported:

  • "phone_numbers" - fetches all phone numbers. This is equivalent to "universityPhone,instPhone,mobexPhone,landlinePhone,mobilePhone,pager".

  • "all_identifiers" - fetches all identifiers. Currently people only have CRSid identifiers, but in the future additional identifiers such as USN or staffNumber may be added.

  • "all_attrs" - fetches all attributes from all person attribute schemes. This does not include identifiers or references.

• Reference fetching. For people, the following references are supported (and will fetch only non-cancelled institutions and groups):

  • "all_insts" - fetches all the institutions to which the person belongs (sorted in name order).

  • "all_groups" - fetches all the groups that the person is a member of, including indirect group memberships, via groups that include other groups.

  • "direct_groups" - fetches all the groups that the person is directly a member of. This does not include indirect group memberships - i.e., groups that include these groups.

• Chained reference fetching. To fetch properties of referenced objects, the "dot" notation may be used. For example, to fetch the email addresses of all the institutions to which a person belongs, use "all_insts.email". Chains may include a number of reference following steps, for example "all_insts.managed_by_groups.all_members.email" will fetch all the institutions to which the person belongs, all the groups that manage those institutions, all the visible members of those groups and all the email addresses of those managing group members. For more information about what can be fetched from referenced institutions and groups, refer to the documentation for InstitutionMethods and GroupMethods.

Multiple values of the fetch parameter should be separated by commas.

Fetch parameter examples

fetch = "email" This fetches all the person's email addresses.

fetch = "title,address" This fetches all the person's titles (roles) and addresses.

fetch = "all_attrs" This fetches all the person's attributes.

fetch = "all_groups,all_insts" This fetches all the groups and institutions to which the person belongs.

fetch = "all_insts.parent_insts" This fetches all the person's institutions, and their parent institutions.

fetch = "all_insts.email,all_insts.all_members.email" This fetches all the person's institutions and their email addresses, and all the members of those institutions, and the email addresses of all those members.

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

addAttribute(scheme, identifier, attr, position=None, allowDuplicates=None, commitComment=None)

Add an attribute to a person. By default, this will not add the attribute again if it already exists.

When adding an attribute, the new attribute's scheme must be set. In addition, either its value or its binaryData field should be set. All the remaining fields of the attribute are optional.

[ HTTP: POST /api/v1/person/{scheme}/{identifier}/add-attribute ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person to udpate (typically their CRSid).

attrIbisAttribute

[required] The new attribute to add.

positionint

[optional] The position of the new attribute in the list of attributes of the same attribute scheme (1, 2, 3,...). A value of 0 (the default) will cause the new attribute to be added to the end of the list of existing attributes for the scheme.

allowDuplicatesbool

[optional] If True, the new attribute will always be added, even if another identical attribute already exists. If False (the default), the new attribute will only be added if it doesn't already exist.

commitCommentstr

[recommended] A short textual description of the change made (will be visible on the history tab in the web application).

Returns

IbisAttribute

The newly created or existing attribute.

allAttributeSchemes()

Return a list of all the person attribute schemes available. The schemeid values of these schemes may be used in the fetch parameter of other methods that return people.

Note

Some of these attribute schemes are not currently used (no people have attribute values in the scheme). These schemes are reserved for possible future use.

[ HTTP: GET /api/v1/person/all-attr-schemes ]

Returns

list of IbisAttributeScheme

All the available person attribute schemes (in precedence order).

allPeople(includeCancelled, identifier=None, limit=None, fetch=None)

Return a list of all people (in batches).

The results are sorted by identifier, starting with the first person after the person with the specified identifier. Thus, to iterate over all people, pass a None identifier to get the first batch of people, then pass the last identifier from the previous batch to get the next batch, and repeat until no more people are returned.

By default, only a few basic details about each person are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

[ HTTP: GET /api/v1/person/all-people ]

Parameters

includeCancelledbool

[optional] Flag to allow cancelled people to be included (people who are no longer members of the University). Defaults to False.

identifierstr

[optional] The identifier (CRSid) of the person to start after, or None to start from the first person.

limitint

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

fetchstr

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

Returns

list of IbisPerson

The requested people (in identifier order).

deleteAttribute(scheme, identifier, attrid, commitComment=None)

Delete an attribute of a person. It is not an error if the attribute does not exist.

Note that in this method, the commitComment is passed as a query parameter, rather than as a form parameter, for greater client compatibility.

[ HTTP: DELETE /api/v1/person/{scheme}/{identifier}/{attrid} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person to udpate (typically their CRSid).

attridlong

[required] The ID of the attribute to delete.

commitCommentstr

[recommended] A short textual description of the change made (will be visible on the history tab in the web application).

Returns

bool

True if the attribute was deleted by this method, or False if it did not exist.

getAttribute(scheme, identifier, attrid)

Get a specific attribute of a person.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/{attrid} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

attridlong

[required] The ID of the attribute to fetch.

Returns

IbisAttribute

The requested attribute.

getAttributes(scheme, identifier, attrs)

Get one or more (possibly multi-valued) attributes of a person. The returned attributes are sorted by attribute scheme precedence and then attribute precedence.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/get-attributes?attrs=... ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

attrsstr

[required] The attribute scheme(s) to fetch. This may include any number of the attributes or pseudo-attributes, but it may not include references or attribute chains (see the documentation for the fetch parameter in this class).

Returns

list of IbisAttribute

The requested attributes.

getGroups(scheme, identifier, fetch=None)

Get all the groups to which the specified person belongs, including indirect group memberships, via groups that include other groups. The returned list of groups is sorted by groupid.

Note that some group memberships may not be visible to you. This method will only return those group memberships that you have permission to see.

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 of each group.

Note

This method will not include cancelled groups.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/groups ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

fetchstr

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

Returns

list of IbisGroup

The person's groups (in groupid order).

getInsts(scheme, identifier, fetch=None)

Get all the institutions to which the specified person belongs. The returned list of institutions is sorted by name.

By default, only a few basic details about each institution are returned, but the optional fetch parameter may be used to fetch additional attributes or references of each institution.

Note

This method will not include cancelled institutions.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/insts ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

fetchstr

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

Returns

list of IbisInstitution

The person's institutions (in name order).

getManagedGroups(scheme, identifier, fetch=None)

Get all the groups that the specified person has persmission to edit. The returned list of groups is sorted by groupid.

Note that some group memberships may not be visible to you. This method will only include groups for which you have persmission to see the applicable manager group memberships.

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 of each group.

Note

This method will not include cancelled groups.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-groups ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

fetchstr

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

Returns

list of IbisGroup

The groups that the person manages (in groupid order).

getManagedInsts(scheme, identifier, fetch=None)

Get all the institutions that the specified person has permission to edit. The returned list of institutions is sorted by name.

Note that some group memberships may not be visible to you. This method will only include institutions for which you have permission to see the applicable editor group memberships.

By default, only a few basic details about each institution are returned, but the optional fetch parameter may be used to fetch additional attributes or references of each institution.

Note

This method will not include cancelled institutions.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-insts ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

fetchstr

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

Returns

list of IbisInstitution

The institutions that the person manages (in name order).

getPerson(scheme, identifier, fetch=None)

Get the person with the specified identifier.

By default, only a few basic details about the person are returned, but the optional fetch parameter may be used to fetch additional attributes or references of the person.

Note

The person returned may be a cancelled person. It is the caller's repsonsibility to check its cancelled flag.

[ HTTP: GET /api/v1/person/{scheme}/{identifier} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes such as "usn" or "staffNumber" may be available.

identifierstr

[required] The identifier of the person to fetch (typically their CRSid).

fetchstr

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

Returns

IbisPerson

The requested person or None if they were not found.

isMemberOfGroup(scheme, identifier, groupid)

Test if the specified person is a member of the specified group.

Note

This may be used with cancelled people and groups.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-group/{groupid} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

groupidstr

[required] The ID or name of the group.

Returns

bool

True if the specified person is in the specified group, False otherwise (or if the person or group does not exist).

isMemberOfInst(scheme, identifier, instid)

Test if the specified person is a member of the specified institution.

Note

This may be used with cancelled people and institutions, but it will not include cancelled membership groups.

[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-inst/{instid} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person (typically their CRSid).

instidstr

[required] The ID of the institution.

Returns

bool

True if the specified person is in the specified institution, False otherwise (or if the person or institution does not exist).

listPeople(crsids, fetch=None)

Get the people with the specified identifiers (typically CRSids).

Each identifier 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".

By default, only a few basic details about each person are returned, but the optional fetch parameter may be used to fetch additional attributes or references.

The results are sorted by identifier scheme and value.

Note

The number of people that may be fetched in a single call is limited by the URL path length limit (around 8000 characters). A CRSid is up to 7 characters long, and other identifiers are typically longer, since they must also include the identifier scheme. Thus the number of people that this method may fetch is typically limited to a few hundred.

Note

The people returned may include cancelled people. It is the caller's repsonsibility to check their cancelled flags.

[ HTTP: GET /api/v1/person/list?crsids=... ]

Parameters

crsidsstr

[required] A comma-separated list of identifiers. The name of the query parameter reflects a time when only crsids were used with lookup. Alternate schemes can be specified as noted above.

fetchstr

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

Returns

list of IbisPerson

The requested people (in identifier order).

modifiedPeople(minTxId, maxTxId, crsids=None, includeCancelled=None, membershipChanges=None, instNameChanges=None, fetch=None)

Find all people 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) people were affected.

By default, only a few basic details about each person 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 person. It is not possible to query for old data, or more detailed information about the specific changes made.

[ HTTP: GET /api/v1/person/modified-people?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.

crsidsstr

[optional] Only include people with identifiers in this list. By default, all modified people will be included.

includeCancelledbool

[optional] Include cancelled people (people who are no longer members of the University). By default, cancelled people are excluded.

membershipChangesbool

[optional] Include people whose group or institutional memberships have changed. By default, only people whose attributes have been directly modified are included.

instNameChangesbool

[optional] Include people who are members of instituions whose names have changed. This will also cause people whose group or institutional memberships have changed to be included. By default, changes to institution names do not propagate to people.

fetchstr

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

Returns

list of IbisPerson

The modified people (in identifier order).

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

Search for people 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 person 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 "person:", it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the approxMatches and attributes parameters, but it will respect the values of includeCancelled and misStatus. In addition, an LQL query will ignore the orderBy parameter, since LQL queries always return results in ID order.

[ HTTP: GET /api/v1/person/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 people to be included (people who are no longer members of the University). Defaults to False.

misStatusstr

[optional] The type of people to search for. This may be

• "staff" - only include people whose MIS status is "" (empty string), "staff", or "staff,student".

• "student" - only include people whose MIS status is set to "student" or "staff,student".

Otherwise all matching people will be included (the default). Note that the "staff" and "student" options are not mutually exclusive.

attributesstr

[optional] A comma-separated list of attributes to consider when searching. If this is None (the default) then all attribute schemes marked as searchable will be included. This is ignored for LQL queries.

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 either "identifier" or "surname" (the default for non-LQL queries). This is ignored for LQL queries, which always return results in identifier order.

fetchstr

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

Returns

list of IbisPerson

The matching people.

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

Count the number of people that would be returned by a search using a free text query string.

Note

If the query string starts with the prefix "person:", it is treated as an LQL query, allowing more advanced searches. An LQL query will ignore the approxMatches and attributes parameters, but it will respect the values of includeCancelled and misStatus.

[ HTTP: GET /api/v1/person/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 people to be included (people who are no longer members of the University). Defaults to False.

misStatusstr

[optional] The type of people to search for. This may be

• "staff" - only include people whose MIS status is "" (empty string), "staff", or "staff,student".

• "student" - only include people whose MIS status is set to "student" or "staff,student".

Otherwise all matching people will be included (the default). Note that the "staff" and "student" options are not mutually exclusive.

attributesstr

[optional] A comma-separated list of attributes to consider when searching. If this is None (the default) then all attribute schemes marked as searchable will be included. This is ignored for LQL queries.

Returns

int

The number of matching people.

updateAttribute(scheme, identifier, attrid, attr, commitComment=None)

Update an attribute of a person.

The attribute's value, binaryData, comment, instid and effective date fields will all be updated using the data supplied. All other fields will be left unchanged.

To avoid inadvertently changing fields of the attribute, it is recommended that getAttribute() be used to retrieve the current value of the attribute, before calling this method with the required changes.

[ HTTP: PUT /api/v1/person/{scheme}/{identifier}/{attrid} ]

Parameters

schemestr

[required] The person identifier scheme. Typically this should be "crsid", but other identifier schemes may be available in the future, such as "usn" or "staffNumber".

identifierstr

[required] The identifier of the person to udpate (typically their CRSid).

attridlong

[required] The ID of the attribute to update.

attrIbisAttribute

[required] The new attribute values to apply.

commitCommentstr

[recommended] A short textual description of the change made (will be visible on the history tab in the web application).

Returns

IbisAttribute

The updated attribute.