public class PersonMethods extends Object
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:
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", "landlinePhone",
"mobilePhone", "pager", "labeledURI" and "address".
The full list of person attribute schemes may be obtained using allAttributeSchemes().
"phone_numbers" - fetches all phone numbers. This is
equivalent to
"universityPhone,instPhone,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."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."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 = "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.
| Constructor and Description |
|---|
PersonMethods(ClientConnection conn)
Create a new PersonMethods object.
|
| Modifier and Type | Method and Description |
|---|---|
IbisAttribute |
addAttribute(String scheme,
String identifier,
IbisAttribute attr,
int position,
boolean allowDuplicates,
String commitComment)
Add an attribute to a person.
|
List<IbisAttributeScheme> |
allAttributeSchemes()
Return a list of all the person attribute schemes available.
|
List<IbisPerson> |
allPeople(boolean includeCancelled,
String identifier,
int limit,
String fetch)
Return a list of all people (in batches).
|
boolean |
deleteAttribute(String scheme,
String identifier,
Long attrid,
String commitComment)
Delete an attribute of a person.
|
IbisAttribute |
getAttribute(String scheme,
String identifier,
Long attrid)
Get a specific attribute of a person.
|
List<IbisAttribute> |
getAttributes(String scheme,
String identifier,
String attrs)
Get one or more (possibly multi-valued) attributes of a person.
|
List<IbisGroup> |
getGroups(String scheme,
String identifier,
String fetch)
Get all the groups to which the specified person belongs, including
indirect group memberships, via groups that include other groups.
|
List<IbisInstitution> |
getInsts(String scheme,
String identifier,
String fetch)
Get all the institutions to which the specified person belongs.
|
List<IbisGroup> |
getManagedGroups(String scheme,
String identifier,
String fetch)
Get all the groups that the specified person has persmission to edit.
|
List<IbisInstitution> |
getManagedInsts(String scheme,
String identifier,
String fetch)
Get all the institutions that the specified person has permission to
edit.
|
IbisPerson |
getPerson(String scheme,
String identifier,
String fetch)
Get the person with the specified identifier.
|
boolean |
isMemberOfGroup(String scheme,
String identifier,
String groupid)
Test if the specified person is a member of the specified group.
|
boolean |
isMemberOfInst(String scheme,
String identifier,
String instid)
Test if the specified person is a member of the specified institution.
|
List<IbisPerson> |
listPeople(String crsids,
String fetch)
Get the people with the specified identifiers (typically CRSids).
|
List<IbisPerson> |
modifiedPeople(long minTxId,
long maxTxId,
String crsids,
boolean includeCancelled,
boolean membershipChanges,
boolean instNameChanges,
String fetch)
Find all people modified between the specified pair of transactions.
|
List<IbisPerson> |
search(String query,
boolean approxMatches,
boolean includeCancelled,
String misStatus,
String attributes,
int offset,
int limit,
String orderBy,
String fetch)
Search for people using a free text query string.
|
int |
searchCount(String query,
boolean approxMatches,
boolean includeCancelled,
String misStatus,
String attributes)
Count the number of people that would be returned by a search using
a free text query string.
|
IbisAttribute |
updateAttribute(String scheme,
String identifier,
Long attrid,
IbisAttribute attr,
String commitComment)
Update an attribute of a person.
|
public PersonMethods(ClientConnection conn)
conn - The ClientConnection object to use to invoke methods
on the server.public List<IbisAttributeScheme> allAttributeSchemes() throws IbisException, IOException, JAXBException
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 ]
IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> allPeople(boolean includeCancelled, String identifier, int limit, String fetch) throws IbisException, IOException, JAXBException
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 ]
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.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> listPeople(String crsids, String fetch) throws IbisException, IOException, JAXBException
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=... ]
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.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> modifiedPeople(long minTxId, long maxTxId, String crsids, boolean includeCancelled, boolean membershipChanges, boolean instNameChanges, String fetch) throws IbisException, IOException, JAXBException
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=... ]
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.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisPerson> search(String query, boolean approxMatches, boolean includeCancelled, String misStatus, String attributes, int offset, int limit, String orderBy, String fetch) throws IbisException, IOException, JAXBException
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=... ]
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"."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.IbisExceptionIOExceptionJAXBExceptionpublic int searchCount(String query, boolean approxMatches, boolean includeCancelled, String misStatus, String attributes) throws IbisException, IOException, JAXBException
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=... ]
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"."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.IbisExceptionIOExceptionJAXBExceptionpublic IbisPerson getPerson(String scheme, String identifier, String fetch) throws IbisException, IOException, JAXBException
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} ]
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.null if they were not found.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute addAttribute(String scheme, String identifier, IbisAttribute attr, int position, boolean allowDuplicates, String commitComment) throws IbisException, IOException, JAXBException
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 ]
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).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisAttribute> getAttributes(String scheme, String identifier, String attrs) throws IbisException, IOException, JAXBException
[ HTTP: GET /api/v1/person/{scheme}/{identifier}/get-attributes?attrs=... ]
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).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisGroup> getGroups(String scheme, String identifier, String fetch) throws IbisException, IOException, JAXBException
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 ]
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.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> getInsts(String scheme, String identifier, String fetch) throws IbisException, IOException, JAXBException
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 ]
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.IbisExceptionIOExceptionJAXBExceptionpublic boolean isMemberOfGroup(String scheme, String identifier, String groupid) throws IbisException, IOException, JAXBException
NOTE: This may be used with cancelled people and groups.
[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-group/{groupid} ]
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.true if the specified person is in the specified
group, false otherwise (or if the person or group does not
exist).IbisExceptionIOExceptionJAXBExceptionpublic boolean isMemberOfInst(String scheme, String identifier, String instid) throws IbisException, IOException, JAXBException
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} ]
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.true if the specified person is in the specified
institution, false otherwise (or if the person or institution
does not exist).IbisExceptionIOExceptionJAXBExceptionpublic List<IbisGroup> getManagedGroups(String scheme, String identifier, String fetch) throws IbisException, IOException, JAXBException
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 ]
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.IbisExceptionIOExceptionJAXBExceptionpublic List<IbisInstitution> getManagedInsts(String scheme, String identifier, String fetch) throws IbisException, IOException, JAXBException
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 ]
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.IbisExceptionIOExceptionJAXBExceptionpublic boolean deleteAttribute(String scheme, String identifier, Long attrid, String commitComment) throws IbisException, IOException, JAXBException
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} ]
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).true if the attribute was deleted by this method, or
false if it did not exist.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute getAttribute(String scheme, String identifier, Long attrid) throws IbisException, IOException, JAXBException
[ HTTP: GET /api/v1/person/{scheme}/{identifier}/{attrid} ]
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.IbisExceptionIOExceptionJAXBExceptionpublic IbisAttribute updateAttribute(String scheme, String identifier, Long attrid, IbisAttribute attr, String commitComment) throws IbisException, IOException, JAXBException
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} ]
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).IbisExceptionIOExceptionJAXBException