Class PersonMethods

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.

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

Methods summary

`public`	# `__construct(ClientConnection $conn)` Create a new PersonMethods object. Create a new PersonMethods object. Parameters `$conn` The ClientConnection object to use to invoke methods on the server.
`public IbisAttributeScheme[]`	# `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. 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 `IbisAttributeScheme[]` All the available person attribute schemes (in precedence order).
`public IbisPerson[]`	# `allPeople(boolean $includeCancelled, string $identifier = null, integer $limit = null, string $fetch = null)` Return a list of all people (in batches). 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 `null` 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 `$includeCancelled` [optional] Flag to allow cancelled people to be included (people who are no longer members of the University). Defaults to `false`. `$identifier` [optional] The identifier (CRSid) of the person to start after, or `null` to start from the first person. `$limit` [optional] The maximum number of people to return. Defaults to 100. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisPerson[]` The requested people (in identifier order).
`public IbisPerson[]`	# `listPeople(string $crsids, string $fetch = null)` Get the people with the specified identifiers (typically CRSids). 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 `$crsids` [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. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisPerson[]` The requested people (in identifier order).
`public IbisPerson[]`	# `modifiedPeople(long $minTxId, long $maxTxId, string $crsids = null, boolean $includeCancelled = null, boolean $membershipChanges = null, boolean $instNameChanges = null, string $fetch = null)` Find all people modified between the specified pair of transactions. 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 `$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. `$crsids` [optional] Only include people with identifiers in this list. By default, all modified people will be included. `$includeCancelled` [optional] Include cancelled people (people who are no longer members of the University). By default, cancelled people are excluded. `$membershipChanges` [optional] Include people whose group or institutional memberships have changed. By default, only people whose attributes have been directly modified are included. `$instNameChanges` [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. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisPerson[]` The modified people (in identifier order).
`public IbisPerson[]`	# `search(string $query, boolean $approxMatches = null, boolean $includeCancelled = null, string $misStatus = null, string $attributes = null, integer $offset = null, integer $limit = null, string $orderBy = null, string $fetch = null)` Search for people using a free text query string. This is the same search function that is used in the Lookup web application. 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 `$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 people to be included (people who are no longer members of the University). Defaults to `false`. `$misStatus` [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. `$attributes` [optional] A comma-separated list of attributes to consider when searching. If this is `null` (the default) then all attribute schemes marked as searchable will be included. This is ignored for LQL queries. `$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 either `"identifier"` or `"surname"` (the default for non-LQL queries). This is ignored for LQL queries, which always return results in identifier order. `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisPerson[]` The matching people.
`public integer`	# `searchCount(string $query, boolean $approxMatches = null, boolean $includeCancelled = null, string $misStatus = null, string $attributes = null)` Count the number of people that would be returned by a search using a free text query string. 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 `$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 people to be included (people who are no longer members of the University). Defaults to `false`. `$misStatus` [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. `$attributes` [optional] A comma-separated list of attributes to consider when searching. If this is `null` (the default) then all attribute schemes marked as searchable will be included. This is ignored for LQL queries. Returns integer The number of matching people.
`public IbisPerson`	# `getPerson(string $scheme, string $identifier, string $fetch = null)` Get the person with the specified identifier. 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 `$scheme` [required] The person identifier scheme. Typically this should be `"crsid"`, but other identifier schemes such as `"usn"` or `"staffNumber"` may be available. `$identifier` [required] The identifier of the person to fetch (typically their CRSid). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisPerson` The requested person or `null` if they were not found.
`public IbisAttribute`	# `addAttribute(string $scheme, string $identifier, IbisAttribute $attr, integer $position = null, boolean $allowDuplicates = null, string $commitComment = null)` Add an attribute to a person. By default, this will not add the attribute again if it already exists. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person to udpate (typically their CRSid). `$attr` [required] The new attribute to add. `$position` [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. `$allowDuplicates` [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. `$commitComment` [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.
`public IbisAttribute[]`	# `getAttributes(string $scheme, string $identifier, string $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. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$attrs` [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 `IbisAttribute[]` The requested attributes.
`public IbisGroup[]`	# `getGroups(string $scheme, string $identifier, string $fetch = null)` 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. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The person's groups (in groupid order).
`public IbisInstitution[]`	# `getInsts(string $scheme, string $identifier, string $fetch = null)` Get all the institutions to which the specified person belongs. The returned list of institutions is sorted by name. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisInstitution[]` The person's institutions (in name order).
`public boolean`	# `isMemberOfGroup(string $scheme, string $identifier, string $groupid)` Test if the specified person is a member of the specified group. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$groupid` [required] The ID or name of the group. Returns boolean `true` if the specified person is in the specified group, `false` otherwise (or if the person or group does not exist).
`public boolean`	# `isMemberOfInst(string $scheme, string $identifier, string $instid)` Test if the specified person is a member of the specified institution. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$instid` [required] The ID of the institution. Returns boolean `true` if the specified person is in the specified institution, `false` otherwise (or if the person or institution does not exist).
`public IbisGroup[]`	# `getManagedGroups(string $scheme, string $identifier, string $fetch = null)` Get all the groups that the specified person has persmission to edit. The returned list of groups is sorted by groupid. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisGroup[]` The groups that the person manages (in groupid order).
`public IbisInstitution[]`	# `getManagedInsts(string $scheme, string $identifier, string $fetch = null)` Get all the institutions that the specified person has permission to edit. The returned list of institutions is sorted by name. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$fetch` [optional] A comma-separated list of any additional attributes or references to fetch. Returns `IbisInstitution[]` The institutions that the person manages (in name order).
`public boolean`	# `deleteAttribute(string $scheme, string $identifier, integer $attrid, string $commitComment = null)` Delete an attribute of a person. It is not an error if the attribute does not exist. 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 `$scheme` [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"`. `$identifier` [required] The identifier of the person to udpate (typically their CRSid). `$attrid` [required] The ID of the attribute to delete. `$commitComment` [recommended] A short textual description of the change made (will be visible on the history tab in the web application). Returns boolean `true` if the attribute was deleted by this method, or `false` if it did not exist.
`public IbisAttribute`	# `getAttribute(string $scheme, string $identifier, integer $attrid)` Get a specific attribute of a person. Get a specific attribute of a person. `[ HTTP: GET /api/v1/person/{scheme}/{identifier}/{attrid} ]` Parameters `$scheme` [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"`. `$identifier` [required] The identifier of the person (typically their CRSid). `$attrid` [required] The ID of the attribute to fetch. Returns `IbisAttribute` The requested attribute.
`public IbisAttribute`	# `updateAttribute(string $scheme, string $identifier, integer $attrid, IbisAttribute $attr, string $commitComment = null)` Update an attribute of a person. 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 `PersonMethods::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 `$scheme` [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"`. `$identifier` [required] The identifier of the person to udpate (typically their CRSid). `$attrid` [required] The ID of the attribute to update. `$attr` [required] The new attribute values to apply. `$commitComment` [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.

Classes

Interfaces

Exceptions

Class PersonMethods

Methods summary

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns