Lookup/Ibis web service client API
  • Class

Classes

  • GroupMethods
  • IbisAttribute
  • IbisAttributeScheme
  • IbisClientConnection
  • IbisContactPhoneNumber
  • IbisContactRow
  • IbisContactWebPage
  • IbisDto
  • IbisError
  • IbisGroup
  • IbisIdentifier
  • IbisInstitution
  • IbisMethods
  • IbisPerson
  • IbisResult
  • IbisResultParser
  • InstitutionMethods
  • PersonMethods

Interfaces

  • ClientConnection

Exceptions

  • IbisException
  1 <?php
  2 /* === AUTO-GENERATED - DO NOT EDIT === */
  3 
  4 /*
  5 Copyright (c) 2012, University of Cambridge Computing Service
  6 
  7 This file is part of the Lookup/Ibis client library.
  8 
  9 This library is free software: you can redistribute it and/or modify
 10 it under the terms of the GNU Lesser General Public License as published
 11 by the Free Software Foundation, either version 3 of the License, or
 12 (at your option) any later version.
 13 
 14 This library is distributed in the hope that it will be useful, but
 15 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 16 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
 17 License for more details.
 18 
 19 You should have received a copy of the GNU Lesser General Public License
 20 along with this library.  If not, see <http://www.gnu.org/licenses/>.
 21 */
 22 
 23 require_once dirname(__FILE__) . "/../client/IbisException.php";
 24 
 25 /**
 26  * Methods for querying and manipulating people.
 27  *
 28  * **Notes on the fetch parameter**
 29  *
 30  * All methods that return people, institutions or groups also accept an
 31  * optional ``fetch`` parameter that may be used to request
 32  * additional information about the entities returned. Without this
 33  * parameter, only a few basic details about each person, institution or
 34  * group are returned. The ``fetch`` parameter is quite flexible,
 35  * and may be used in a number of different ways:
 36  *
 37  * * **Attribute fetching**. Attributes may be fetched by specifying the
 38  *   ``schemeid`` of an attribute scheme. For example to fetch a
 39  *   person's email addresses, use the value ``"email"``. For people common
 40  *   attribute schemes include ``"jpegPhoto"``, ``"misAffiliation"``,
 41  *   ``"title"``, ``"universityPhone"``, ``"mobexPhone"``,
 42  *   ``"landlinePhone"``, ``"mobilePhone"``, ``"pager"``,
 43  *   ``"labeledURI"`` and ``"address"``. The full list of person
 44  *   attribute schemes may be obtained using {@link allAttributeSchemes}.
 45  *
 46  * * **Pseudo-attributes**. Certain special pseudo-attributes are defined
 47  *   for convenience. For people, the following pseudo-attributes are supported:
 48  *
 49  *   * ``"phone_numbers"`` - fetches all phone numbers. This is
 50  *     equivalent to
 51  *     ``"universityPhone,instPhone,mobexPhone,landlinePhone,mobilePhone,pager"``.
 52  *
 53  *   * ``"all_identifiers"`` - fetches all identifiers. Currently people
 54  *     only have CRSid identifiers, but in the future additional identifiers such
 55  *     as USN or staffNumber may be added.
 56  *
 57  *   * ``"all_attrs"`` - fetches all attributes from all person attribute
 58  *     schemes. This does not include identifiers or references.
 59  *
 60  * * **Reference fetching**. For people, the following references are
 61  *   supported (and will fetch only non-cancelled institutions and groups):
 62  *
 63  *   * ``"all_insts"`` - fetches all the institutions to which the person
 64  *     belongs (sorted in name order).
 65  *
 66  *   * ``"all_groups"`` - fetches all the groups that the person is a
 67  *     member of, including indirect group memberships, via groups that include
 68  *     other groups.
 69  *
 70  *   * ``"direct_groups"`` - fetches all the groups that the person is
 71  *     directly a member of. This does not include indirect group memberships -
 72  *     i.e., groups that include these groups.
 73  *
 74  * * **Chained reference fetching**. To fetch properties of referenced
 75  *   objects, the "dot" notation may be used. For example, to fetch the email
 76  *   addresses of all the institutions to which a person belongs, use
 77  *   ``"all_insts.email"``. Chains may include a number of reference
 78  *   following steps, for example
 79  *   ``"all_insts.managed_by_groups.all_members.email"`` will fetch all the
 80  *   institutions to which the person belongs, all the groups that manage those
 81  *   institutions, all the visible members of those groups and all the email
 82  *   addresses of those managing group members. For more information about what
 83  *   can be fetched from referenced institutions and groups, refer to the
 84  *   documentation for {@link InstitutionMethods} and {@link GroupMethods}.
 85  *
 86  * Multiple values of the ``fetch`` parameter should be separated
 87  * by commas.
 88  *
 89  * **Fetch parameter examples**
 90  *
 91  * ``fetch = "email"``
 92  * This fetches all the person's email addresses.
 93  *
 94  * ``fetch = "title,address"``
 95  * This fetches all the person's titles (roles) and addresses.
 96  *
 97  * ``fetch = "all_attrs"``
 98  * This fetches all the person's attributes.
 99  *
100  * ``fetch = "all_groups,all_insts"``
101  * This fetches all the groups and institutions to which the person belongs.
102  *
103  * ``fetch = "all_insts.parent_insts"``
104  * This fetches all the person's institutions, and their parent institutions.
105  *
106  * ``fetch = "all_insts.email,all_insts.all_members.email"``
107  * This fetches all the person's institutions and their email addresses, and
108  * all the members of those institutions, and the email addresses of all
109  * those members.
110  *
111  * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
112  */
113 class PersonMethods
114 {
115     // The connection to the server
116     private $conn;
117 
118     /**
119      * Create a new PersonMethods object.
120      *
121      * @param ClientConnection $conn The ClientConnection object to use to
122      * invoke methods on the server.
123      */
124     public function __construct($conn)
125     {
126         $this->conn = $conn;
127     }
128 
129     /**
130      * Return a list of all the person attribute schemes available. The
131      * ``schemeid`` values of these schemes may be used in the
132      * ``fetch`` parameter of other methods that return people.
133      *
134      * NOTE: Some of these attribute schemes are not currently used (no
135      * people have attribute values in the scheme). These schemes are
136      * reserved for possible future use.
137      *
138      * ``[ HTTP: GET /api/v1/person/all-attr-schemes ]``
139      *
140      * @return IbisAttributeScheme[] All the available person attribute schemes (in precedence
141      * order).
142      */
143     public function allAttributeSchemes()
144     {
145         $pathParams = array();
146         $queryParams = array();
147         $formParams = array();
148         $result = $this->conn->invokeMethod("GET",
149                                             'api/v1/person/all-attr-schemes',
150                                             $pathParams,
151                                             $queryParams,
152                                             $formParams);
153         if (isset($result->error))
154             throw new IbisException($result->error);
155         return $result->attributeSchemes;
156     }
157 
158     /**
159      * Return a list of all people (in batches).
160      *
161      * The results are sorted by identifier, starting with the first person
162      * after the person with the specified identifier. Thus, to iterate over
163      * all people, pass a ``null`` identifier to get the first batch of
164      * people, then pass the last identifier from the previous batch to get
165      * the next batch, and repeat until no more people are returned.
166      *
167      * By default, only a few basic details about each person are returned,
168      * but the optional ``fetch`` parameter may be used to fetch
169      * additional attributes or references.
170      *
171      * ``[ HTTP: GET /api/v1/person/all-people ]``
172      *
173      * @param boolean $includeCancelled [optional] Flag to allow cancelled people to
174      * be included (people who are no longer members of the University).
175      * Defaults to ``false``.
176      * @param string $identifier [optional] The identifier (CRSid) of the person to
177      * start after, or ``null`` to start from the first person.
178      * @param int $limit [optional] The maximum number of people to return.
179      * Defaults to 100.
180      * @param string $fetch [optional] A comma-separated list of any additional
181      * attributes or references to fetch.
182      *
183      * @return IbisPerson[] The requested people (in identifier order).
184      */
185     public function allPeople($includeCancelled,
186                               $identifier=null,
187                               $limit=null,
188                               $fetch=null)
189     {
190         $pathParams = array();
191         $queryParams = array("includeCancelled" => $includeCancelled,
192                              "identifier"       => $identifier,
193                              "limit"            => $limit,
194                              "fetch"            => $fetch);
195         $formParams = array();
196         $result = $this->conn->invokeMethod("GET",
197                                             'api/v1/person/all-people',
198                                             $pathParams,
199                                             $queryParams,
200                                             $formParams);
201         if (isset($result->error))
202             throw new IbisException($result->error);
203         return $result->people;
204     }
205 
206     /**
207      * Get the people with the specified identifiers (typically CRSids).
208      *
209      * Each identifier may be either a CRSid, or an identifier from another
210      * identifier scheme, prefixed with that scheme's name and a slash. For
211      * example ``"mug99"`` or ``"usn/123456789"``.
212      *
213      * By default, only a few basic details about each person are returned,
214      * but the optional ``fetch`` parameter may be used to fetch
215      * additional attributes or references.
216      *
217      * The results are sorted by identifier scheme and value.
218      *
219      * NOTE: The number of people that may be fetched in a single call is
220      * limited by the URL path length limit (around 8000 characters). A
221      * CRSid is up to 7 characters long, and other identifiers are typically
222      * longer, since they must also include the identifier scheme. Thus the
223      * number of people that this method may fetch is typically limited to a
224      * few hundred.
225      *
226      * NOTE: The people returned may include cancelled people. It is the
227      * caller's repsonsibility to check their cancelled flags.
228      *
229      * ``[ HTTP: GET /api/v1/person/list?crsids=... ]``
230      *
231      * @param string $crsids [required] A comma-separated list of identifiers.
232      * @param string $fetch [optional] A comma-separated list of any additional
233      * attributes or references to fetch.
234      *
235      * @return IbisPerson[] The requested people (in identifier order).
236      */
237     public function listPeople($crsids,
238                                $fetch=null)
239     {
240         $pathParams = array();
241         $queryParams = array("crsids" => $crsids,
242                              "fetch"  => $fetch);
243         $formParams = array();
244         $result = $this->conn->invokeMethod("GET",
245                                             'api/v1/person/list',
246                                             $pathParams,
247                                             $queryParams,
248                                             $formParams);
249         if (isset($result->error))
250             throw new IbisException($result->error);
251         return $result->people;
252     }
253 
254     /**
255      * Find all people modified between the specified pair of transactions.
256      *
257      * The transaction IDs specified should be the IDs from two different
258      * requests for the last (most recent) transaction ID, made at different
259      * times, that returned different values, indicating that some Lookup
260      * data was modified in the period between the two requests. This method
261      * then determines which (if any) people were affected.
262      *
263      * By default, only a few basic details about each person are returned,
264      * but the optional ``fetch`` parameter may be used to fetch
265      * additional attributes or references.
266      *
267      * NOTE: All data returned reflects the latest available data about each
268      * person. It is not possible to query for old data, or more detailed
269      * information about the specific changes made.
270      *
271      * ``[ HTTP: GET /api/v1/person/modified-people?minTxId=...&maxTxId=... ]``
272      *
273      * @param long $minTxId [required] Include modifications made in transactions
274      * after (but not including) this one.
275      * @param long $maxTxId [required] Include modifications made in transactions
276      * up to and including this one.
277      * @param string $crsids [optional] Only include people with identifiers in this
278      * list. By default, all modified people will be included.
279      * @param boolean $includeCancelled  [optional] Include cancelled people (people
280      * who are no longer members of the University). By default, cancelled
281      * people are excluded.
282      * @param boolean $membershipChanges [optional] Include people whose group or
283      * institutional memberships have changed. By default, only people whose
284      * attributes have been directly modified are included.
285      * @param boolean $instNameChanges [optional] Include people who are members of
286      * instituions whose names have changed. This will also cause people
287      * whose group or institutional memberships have changed to be included.
288      * By default, changes to institution names do not propagate to people.
289      * @param string $fetch [optional] A comma-separated list of any additional
290      * attributes or references to fetch.
291      *
292      * @return IbisPerson[] The modified people (in identifier order).
293      */
294     public function modifiedPeople($minTxId,
295                                    $maxTxId,
296                                    $crsids=null,
297                                    $includeCancelled=null,
298                                    $membershipChanges=null,
299                                    $instNameChanges=null,
300                                    $fetch=null)
301     {
302         $pathParams = array();
303         $queryParams = array("minTxId"           => $minTxId,
304                              "maxTxId"           => $maxTxId,
305                              "crsids"            => $crsids,
306                              "includeCancelled"  => $includeCancelled,
307                              "membershipChanges" => $membershipChanges,
308                              "instNameChanges"   => $instNameChanges,
309                              "fetch"             => $fetch);
310         $formParams = array();
311         $result = $this->conn->invokeMethod("GET",
312                                             'api/v1/person/modified-people',
313                                             $pathParams,
314                                             $queryParams,
315                                             $formParams);
316         if (isset($result->error))
317             throw new IbisException($result->error);
318         return $result->people;
319     }
320 
321     /**
322      * Search for people using a free text query string. This is the same
323      * search function that is used in the Lookup web application.
324      *
325      * By default, only a few basic details about each person are returned,
326      * but the optional ``fetch`` parameter may be used to fetch
327      * additional attributes or references.
328      *
329      * NOTE: If the query string starts with the prefix ``"person:"``, it
330      * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
331      * more advanced searches. An LQL query will ignore the
332      * ``approxMatches`` and ``attributes`` parameters, but
333      * it will respect the values of ``includeCancelled`` and
334      * ``misStatus``. In addition, an LQL query will ignore the
335      * ``orderBy`` parameter, since LQL queries always return
336      * results in ID order.
337      *
338      * ``[ HTTP: GET /api/v1/person/search?query=... ]``
339      *
340      * @param string $query [required] The search string.
341      * @param boolean $approxMatches [optional] Flag to enable more approximate
342      * matching in the search, causing more results to be returned. Defaults
343      * to ``false``. This is ignored for LQL queries.
344      * @param boolean $includeCancelled [optional] Flag to allow cancelled people to
345      * be included (people who are no longer members of the University).
346      * Defaults to ``false``.
347      * @param string $misStatus [optional] The type of people to search for. This may
348      * be
349      *
350      * * ``"staff"`` - only include people whose MIS status is
351      *   ``""`` (empty string), ``"staff"``, or
352      *   ``"staff,student"``.
353      *
354      * * ``"student"`` - only include people whose MIS status is set to
355      *   ``"student"`` or ``"staff,student"``.
356      *
357      * Otherwise all matching people will be included (the default). Note
358      * that the ``"staff"`` and ``"student"`` options are not
359      * mutually exclusive.
360      * @param string $attributes [optional] A comma-separated list of attributes to
361      * consider when searching. If this is ``null`` (the default) then
362      * all attribute schemes marked as searchable will be included. This is
363      * ignored for LQL queries.
364      * @param int $offset [optional] The number of results to skip at the start
365      * of the search. Defaults to 0.
366      * @param int $limit [optional] The maximum number of results to return.
367      * Defaults to 100.
368      * @param string $orderBy [optional] The order in which to list the results.
369      * This may be either ``"identifier"`` or ``"surname"`` (the
370      * default for non-LQL queries). This is ignored for LQL queries, which
371      * always return results in identifier order.
372      * @param string $fetch [optional] A comma-separated list of any additional
373      * attributes or references to fetch.
374      *
375      * @return IbisPerson[] The matching people.
376      */
377     public function search($query,
378                            $approxMatches=null,
379                            $includeCancelled=null,
380                            $misStatus=null,
381                            $attributes=null,
382                            $offset=null,
383                            $limit=null,
384                            $orderBy=null,
385                            $fetch=null)
386     {
387         $pathParams = array();
388         $queryParams = array("query"            => $query,
389                              "approxMatches"    => $approxMatches,
390                              "includeCancelled" => $includeCancelled,
391                              "misStatus"        => $misStatus,
392                              "attributes"       => $attributes,
393                              "offset"           => $offset,
394                              "limit"            => $limit,
395                              "orderBy"          => $orderBy,
396                              "fetch"            => $fetch);
397         $formParams = array();
398         $result = $this->conn->invokeMethod("GET",
399                                             'api/v1/person/search',
400                                             $pathParams,
401                                             $queryParams,
402                                             $formParams);
403         if (isset($result->error))
404             throw new IbisException($result->error);
405         return $result->people;
406     }
407 
408     /**
409      * Count the number of people that would be returned by a search using
410      * a free text query string.
411      *
412      * NOTE: If the query string starts with the prefix ``"person:"``, it
413      * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
414      * more advanced searches. An LQL query will ignore the
415      * ``approxMatches`` and ``attributes`` parameters, but
416      * it will respect the values of ``includeCancelled`` and
417      * ``misStatus``.
418      *
419      * ``[ HTTP: GET /api/v1/person/search-count?query=... ]``
420      *
421      * @param string $query [required] The search string.
422      * @param boolean $approxMatches [optional] Flag to enable more approximate
423      * matching in the search, causing more results to be returned. Defaults
424      * to ``false``. This is ignored for LQL queries.
425      * @param boolean $includeCancelled [optional] Flag to allow cancelled people to
426      * be included (people who are no longer members of the University).
427      * Defaults to ``false``.
428      * @param string $misStatus [optional] The type of people to search for. This may
429      * be
430      *
431      * * ``"staff"`` - only include people whose MIS status is
432      *   ``""`` (empty string), ``"staff"``, or
433      *   ``"staff,student"``.
434      *
435      * * ``"student"`` - only include people whose MIS status is set to
436      *   ``"student"`` or ``"staff,student"``.
437      *
438      * Otherwise all matching people will be included (the default). Note
439      * that the ``"staff"`` and ``"student"`` options are not
440      * mutually exclusive.
441      * @param string $attributes [optional] A comma-separated list of attributes to
442      * consider when searching. If this is ``null`` (the default) then
443      * all attribute schemes marked as searchable will be included. This is
444      * ignored for LQL queries.
445      *
446      * @return int The number of matching people.
447      */
448     public function searchCount($query,
449                                 $approxMatches=null,
450                                 $includeCancelled=null,
451                                 $misStatus=null,
452                                 $attributes=null)
453     {
454         $pathParams = array();
455         $queryParams = array("query"            => $query,
456                              "approxMatches"    => $approxMatches,
457                              "includeCancelled" => $includeCancelled,
458                              "misStatus"        => $misStatus,
459                              "attributes"       => $attributes);
460         $formParams = array();
461         $result = $this->conn->invokeMethod("GET",
462                                             'api/v1/person/search-count',
463                                             $pathParams,
464                                             $queryParams,
465                                             $formParams);
466         if (isset($result->error))
467             throw new IbisException($result->error);
468         return intval($result->value);
469     }
470 
471     /**
472      * Get the person with the specified identifier.
473      *
474      * By default, only a few basic details about the person are returned,
475      * but the optional ``fetch`` parameter may be used to fetch
476      * additional attributes or references of the person.
477      *
478      * NOTE: The person returned may be a cancelled person. It is the
479      * caller's repsonsibility to check its cancelled flag.
480      *
481      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier} ]``
482      *
483      * @param string $scheme [required] The person identifier scheme. Typically this
484      * should be ``"crsid"``, but other identifier schemes may be
485      * available in the future, such as ``"usn"`` or
486      * ``"staffNumber"``.
487      * @param string $identifier [required] The identifier of the person to fetch
488      * (typically their CRSid).
489      * @param string $fetch [optional] A comma-separated list of any additional
490      * attributes or references to fetch.
491      *
492      * @return IbisPerson The requested person or ``null`` if they were not found.
493      */
494     public function getPerson($scheme,
495                               $identifier,
496                               $fetch=null)
497     {
498         $pathParams = array("scheme"     => $scheme,
499                             "identifier" => $identifier);
500         $queryParams = array("fetch" => $fetch);
501         $formParams = array();
502         $result = $this->conn->invokeMethod("GET",
503                                             'api/v1/person/%1$s/%2$s',
504                                             $pathParams,
505                                             $queryParams,
506                                             $formParams);
507         if (isset($result->error))
508             throw new IbisException($result->error);
509         return $result->person;
510     }
511 
512     /**
513      * Add an attribute to a person. By default, this will not add the
514      * attribute again if it already exists.
515      *
516      * When adding an attribute, the new attribute's scheme must be set.
517      * In addition, either its value or its binaryData field should be set.
518      * All the remaining fields of the attribute are optional.
519      *
520      * ``[ HTTP: POST /api/v1/person/{scheme}/{identifier}/add-attribute ]``
521      *
522      * @param string $scheme [required] The person identifier scheme. Typically this
523      * should be ``"crsid"``, but other identifier schemes may be
524      * available in the future, such as ``"usn"`` or
525      * ``"staffNumber"``.
526      * @param string $identifier [required] The identifier of the person to udpate
527      * (typically their CRSid).
528      * @param IbisAttribute $attr [required] The new attribute to add.
529      * @param int $position [optional] The position of the new attribute in the
530      * list of attributes of the same attribute scheme (1, 2, 3,...). A value
531      * of 0 (the default) will cause the new attribute to be added to the end
532      * of the list of existing attributes for the scheme.
533      * @param boolean $allowDuplicates [optional] If ``true``, the new attribute
534      * will always be added, even if another identical attribute already
535      * exists. If ``false`` (the default), the new attribute will only be
536      * added if it doesn't already exist.
537      * @param string $commitComment [recommended] A short textual description of
538      * the change made (will be visible on the history tab in the web
539      * application).
540      *
541      * @return IbisAttribute The newly created or existing attribute.
542      */
543     public function addAttribute($scheme,
544                                  $identifier,
545                                  $attr,
546                                  $position=null,
547                                  $allowDuplicates=null,
548                                  $commitComment=null)
549     {
550         $pathParams = array("scheme"     => $scheme,
551                             "identifier" => $identifier);
552         $queryParams = array();
553         $formParams = array("attr"            => $attr,
554                             "position"        => $position,
555                             "allowDuplicates" => $allowDuplicates,
556                             "commitComment"   => $commitComment);
557         $result = $this->conn->invokeMethod("POST",
558                                             'api/v1/person/%1$s/%2$s/add-attribute',
559                                             $pathParams,
560                                             $queryParams,
561                                             $formParams);
562         if (isset($result->error))
563             throw new IbisException($result->error);
564         return $result->attribute;
565     }
566 
567     /**
568      * Get one or more (possibly multi-valued) attributes of a person. The
569      * returned attributes are sorted by attribute scheme precedence and
570      * then attribute precedence.
571      *
572      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/get-attributes?attrs=... ]``
573      *
574      * @param string $scheme [required] The person identifier scheme. Typically this
575      * should be ``"crsid"``, but other identifier schemes may be
576      * available in the future, such as ``"usn"`` or
577      * ``"staffNumber"``.
578      * @param string $identifier [required] The identifier of the person (typically
579      * their CRSid).
580      * @param string $attrs [required] The attribute scheme(s) to fetch. This may
581      * include any number of the attributes or pseudo-attributes, but it
582      * may not include references or attribute chains (see the documentation
583      * for the ``fetch`` parameter in this class).
584      *
585      * @return IbisAttribute[] The requested attributes.
586      */
587     public function getAttributes($scheme,
588                                   $identifier,
589                                   $attrs)
590     {
591         $pathParams = array("scheme"     => $scheme,
592                             "identifier" => $identifier);
593         $queryParams = array("attrs" => $attrs);
594         $formParams = array();
595         $result = $this->conn->invokeMethod("GET",
596                                             'api/v1/person/%1$s/%2$s/get-attributes',
597                                             $pathParams,
598                                             $queryParams,
599                                             $formParams);
600         if (isset($result->error))
601             throw new IbisException($result->error);
602         return $result->attributes;
603     }
604 
605     /**
606      * Get all the groups to which the specified person belongs, including
607      * indirect group memberships, via groups that include other groups.
608      * The returned list of groups is sorted by groupid.
609      *
610      * Note that some group memberships may not be visible to you. This
611      * method will only return those group memberships that you have
612      * permission to see.
613      *
614      * By default, only a few basic details about each group are returned,
615      * but the optional ``fetch`` parameter may be used to fetch
616      * additional attributes or references of each group.
617      *
618      * NOTE: This method will not include cancelled groups.
619      *
620      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/groups ]``
621      *
622      * @param string $scheme [required] The person identifier scheme. Typically this
623      * should be ``"crsid"``, but other identifier schemes may be
624      * available in the future, such as ``"usn"`` or
625      * ``"staffNumber"``.
626      * @param string $identifier [required] The identifier of the person (typically
627      * their CRSid).
628      * @param string $fetch [optional] A comma-separated list of any additional
629      * attributes or references to fetch.
630      *
631      * @return IbisGroup[] The person's groups (in groupid order).
632      */
633     public function getGroups($scheme,
634                               $identifier,
635                               $fetch=null)
636     {
637         $pathParams = array("scheme"     => $scheme,
638                             "identifier" => $identifier);
639         $queryParams = array("fetch" => $fetch);
640         $formParams = array();
641         $result = $this->conn->invokeMethod("GET",
642                                             'api/v1/person/%1$s/%2$s/groups',
643                                             $pathParams,
644                                             $queryParams,
645                                             $formParams);
646         if (isset($result->error))
647             throw new IbisException($result->error);
648         return $result->groups;
649     }
650 
651     /**
652      * Get all the institutions to which the specified person belongs. The
653      * returned list of institutions is sorted by name.
654      *
655      * By default, only a few basic details about each institution are
656      * returned, but the optional ``fetch`` parameter may be used
657      * to fetch additional attributes or references of each institution.
658      *
659      * NOTE: This method will not include cancelled institutions.
660      *
661      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/insts ]``
662      *
663      * @param string $scheme [required] The person identifier scheme. Typically this
664      * should be ``"crsid"``, but other identifier schemes may be
665      * available in the future, such as ``"usn"`` or
666      * ``"staffNumber"``.
667      * @param string $identifier [required] The identifier of the person (typically
668      * their CRSid).
669      * @param string $fetch [optional] A comma-separated list of any additional
670      * attributes or references to fetch.
671      *
672      * @return IbisInstitution[] The person's institutions (in name order).
673      */
674     public function getInsts($scheme,
675                              $identifier,
676                              $fetch=null)
677     {
678         $pathParams = array("scheme"     => $scheme,
679                             "identifier" => $identifier);
680         $queryParams = array("fetch" => $fetch);
681         $formParams = array();
682         $result = $this->conn->invokeMethod("GET",
683                                             'api/v1/person/%1$s/%2$s/insts',
684                                             $pathParams,
685                                             $queryParams,
686                                             $formParams);
687         if (isset($result->error))
688             throw new IbisException($result->error);
689         return $result->institutions;
690     }
691 
692     /**
693      * Test if the specified person is a member of the specified group.
694      *
695      * NOTE: This may be used with cancelled people and groups.
696      *
697      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-group/{groupid} ]``
698      *
699      * @param string $scheme [required] The person identifier scheme. Typically this
700      * should be ``"crsid"``, but other identifier schemes may be
701      * available in the future, such as ``"usn"`` or
702      * ``"staffNumber"``.
703      * @param string $identifier [required] The identifier of the person (typically
704      * their CRSid).
705      * @param string $groupid [required] The ID or name of the group.
706      *
707      * @return boolean ``true`` if the specified person is in the specified
708      * group, ``false`` otherwise (or if the person or group does not
709      * exist).
710      */
711     public function isMemberOfGroup($scheme,
712                                     $identifier,
713                                     $groupid)
714     {
715         $pathParams = array("scheme"     => $scheme,
716                             "identifier" => $identifier,
717                             "groupid"    => $groupid);
718         $queryParams = array();
719         $formParams = array();
720         $result = $this->conn->invokeMethod("GET",
721                                             'api/v1/person/%1$s/%2$s/is-member-of-group/%3$s',
722                                             $pathParams,
723                                             $queryParams,
724                                             $formParams);
725         if (isset($result->error))
726             throw new IbisException($result->error);
727         return strcasecmp($result->value, "true") == 0;
728     }
729 
730     /**
731      * Test if the specified person is a member of the specified institution.
732      *
733      * NOTE: This may be used with cancelled people and institutions, but
734      * it will not include cancelled membership groups.
735      *
736      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-inst/{instid} ]``
737      *
738      * @param string $scheme [required] The person identifier scheme. Typically this
739      * should be ``"crsid"``, but other identifier schemes may be
740      * available in the future, such as ``"usn"`` or
741      * ``"staffNumber"``.
742      * @param string $identifier [required] The identifier of the person (typically
743      * their CRSid).
744      * @param string $instid [required] The ID of the institution.
745      *
746      * @return boolean ``true`` if the specified person is in the specified
747      * institution, ``false`` otherwise (or if the person or institution
748      * does not exist).
749      */
750     public function isMemberOfInst($scheme,
751                                    $identifier,
752                                    $instid)
753     {
754         $pathParams = array("scheme"     => $scheme,
755                             "identifier" => $identifier,
756                             "instid"     => $instid);
757         $queryParams = array();
758         $formParams = array();
759         $result = $this->conn->invokeMethod("GET",
760                                             'api/v1/person/%1$s/%2$s/is-member-of-inst/%3$s',
761                                             $pathParams,
762                                             $queryParams,
763                                             $formParams);
764         if (isset($result->error))
765             throw new IbisException($result->error);
766         return strcasecmp($result->value, "true") == 0;
767     }
768 
769     /**
770      * Get all the groups that the specified person has persmission to edit.
771      * The returned list of groups is sorted by groupid.
772      *
773      * Note that some group memberships may not be visible to you. This
774      * method will only include groups for which you have persmission to
775      * see the applicable manager group memberships.
776      *
777      * By default, only a few basic details about each group are returned,
778      * but the optional ``fetch`` parameter may be used to fetch
779      * additional attributes or references of each group.
780      *
781      * NOTE: This method will not include cancelled groups.
782      *
783      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-groups ]``
784      *
785      * @param string $scheme [required] The person identifier scheme. Typically this
786      * should be ``"crsid"``, but other identifier schemes may be
787      * available in the future, such as ``"usn"`` or
788      * ``"staffNumber"``.
789      * @param string $identifier [required] The identifier of the person (typically
790      * their CRSid).
791      * @param string $fetch [optional] A comma-separated list of any additional
792      * attributes or references to fetch.
793      *
794      * @return IbisGroup[] The groups that the person manages (in groupid order).
795      */
796     public function getManagedGroups($scheme,
797                                      $identifier,
798                                      $fetch=null)
799     {
800         $pathParams = array("scheme"     => $scheme,
801                             "identifier" => $identifier);
802         $queryParams = array("fetch" => $fetch);
803         $formParams = array();
804         $result = $this->conn->invokeMethod("GET",
805                                             'api/v1/person/%1$s/%2$s/manages-groups',
806                                             $pathParams,
807                                             $queryParams,
808                                             $formParams);
809         if (isset($result->error))
810             throw new IbisException($result->error);
811         return $result->groups;
812     }
813 
814     /**
815      * Get all the institutions that the specified person has permission to
816      * edit. The returned list of institutions is sorted by name.
817      *
818      * Note that some group memberships may not be visible to you. This
819      * method will only include institutions for which you have permission
820      * to see the applicable editor group memberships.
821      *
822      * By default, only a few basic details about each institution are
823      * returned, but the optional ``fetch`` parameter may be used
824      * to fetch additional attributes or references of each institution.
825      *
826      * NOTE: This method will not include cancelled institutions.
827      *
828      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-insts ]``
829      *
830      * @param string $scheme [required] The person identifier scheme. Typically this
831      * should be ``"crsid"``, but other identifier schemes may be
832      * available in the future, such as ``"usn"`` or
833      * ``"staffNumber"``.
834      * @param string $identifier [required] The identifier of the person (typically
835      * their CRSid).
836      * @param string $fetch [optional] A comma-separated list of any additional
837      * attributes or references to fetch.
838      *
839      * @return IbisInstitution[] The institutions that the person manages (in name order).
840      */
841     public function getManagedInsts($scheme,
842                                     $identifier,
843                                     $fetch=null)
844     {
845         $pathParams = array("scheme"     => $scheme,
846                             "identifier" => $identifier);
847         $queryParams = array("fetch" => $fetch);
848         $formParams = array();
849         $result = $this->conn->invokeMethod("GET",
850                                             'api/v1/person/%1$s/%2$s/manages-insts',
851                                             $pathParams,
852                                             $queryParams,
853                                             $formParams);
854         if (isset($result->error))
855             throw new IbisException($result->error);
856         return $result->institutions;
857     }
858 
859     /**
860      * Delete an attribute of a person. It is not an error if the attribute
861      * does not exist.
862      *
863      * Note that in this method, the ``commitComment`` is passed
864      * as a query parameter, rather than as a form parameter, for greater
865      * client compatibility.
866      *
867      * ``[ HTTP: DELETE /api/v1/person/{scheme}/{identifier}/{attrid} ]``
868      *
869      * @param string $scheme [required] The person identifier scheme. Typically this
870      * should be ``"crsid"``, but other identifier schemes may be
871      * available in the future, such as ``"usn"`` or
872      * ``"staffNumber"``.
873      * @param string $identifier [required] The identifier of the person to udpate
874      * (typically their CRSid).
875      * @param int $attrid [required] The ID of the attribute to delete.
876      * @param string $commitComment [recommended] A short textual description of
877      * the change made (will be visible on the history tab in the web
878      * application).
879      *
880      * @return boolean ``true`` if the attribute was deleted by this method, or
881      * ``false`` if it did not exist.
882      */
883     public function deleteAttribute($scheme,
884                                     $identifier,
885                                     $attrid,
886                                     $commitComment=null)
887     {
888         $pathParams = array("scheme"     => $scheme,
889                             "identifier" => $identifier,
890                             "attrid"     => $attrid);
891         $queryParams = array("commitComment" => $commitComment);
892         $formParams = array();
893         $result = $this->conn->invokeMethod("DELETE",
894                                             'api/v1/person/%1$s/%2$s/%3$s',
895                                             $pathParams,
896                                             $queryParams,
897                                             $formParams);
898         if (isset($result->error))
899             throw new IbisException($result->error);
900         return strcasecmp($result->value, "true") == 0;
901     }
902 
903     /**
904      * Get a specific attribute of a person.
905      *
906      * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/{attrid} ]``
907      *
908      * @param string $scheme [required] The person identifier scheme. Typically this
909      * should be ``"crsid"``, but other identifier schemes may be
910      * available in the future, such as ``"usn"`` or
911      * ``"staffNumber"``.
912      * @param string $identifier [required] The identifier of the person (typically
913      * their CRSid).
914      * @param int $attrid [required] The ID of the attribute to fetch.
915      *
916      * @return IbisAttribute The requested attribute.
917      */
918     public function getAttribute($scheme,
919                                  $identifier,
920                                  $attrid)
921     {
922         $pathParams = array("scheme"     => $scheme,
923                             "identifier" => $identifier,
924                             "attrid"     => $attrid);
925         $queryParams = array();
926         $formParams = array();
927         $result = $this->conn->invokeMethod("GET",
928                                             'api/v1/person/%1$s/%2$s/%3$s',
929                                             $pathParams,
930                                             $queryParams,
931                                             $formParams);
932         if (isset($result->error))
933             throw new IbisException($result->error);
934         return $result->attribute;
935     }
936 
937     /**
938      * Update an attribute of a person.
939      *
940      * The attribute's value, binaryData, comment, instid and effective date
941      * fields will all be updated using the data supplied. All other fields
942      * will be left unchanged.
943      *
944      * To avoid inadvertently changing fields of the attribute, it is
945      * recommended that {@link getAttribute} be used to
946      * retrieve the current value of the attribute, before calling this
947      * method with the required changes.
948      *
949      * ``[ HTTP: PUT /api/v1/person/{scheme}/{identifier}/{attrid} ]``
950      *
951      * @param string $scheme [required] The person identifier scheme. Typically this
952      * should be ``"crsid"``, but other identifier schemes may be
953      * available in the future, such as ``"usn"`` or
954      * ``"staffNumber"``.
955      * @param string $identifier [required] The identifier of the person to udpate
956      * (typically their CRSid).
957      * @param int $attrid [required] The ID of the attribute to update.
958      * @param IbisAttribute $attr [required] The new attribute values to apply.
959      * @param string $commitComment [recommended] A short textual description of
960      * the change made (will be visible on the history tab in the web
961      * application).
962      *
963      * @return IbisAttribute The updated attribute.
964      */
965     public function updateAttribute($scheme,
966                                     $identifier,
967                                     $attrid,
968                                     $attr,
969                                     $commitComment=null)
970     {
971         $pathParams = array("scheme"     => $scheme,
972                             "identifier" => $identifier,
973                             "attrid"     => $attrid);
974         $queryParams = array();
975         $formParams = array("attr"          => $attr,
976                             "commitComment" => $commitComment);
977         $result = $this->conn->invokeMethod("PUT",
978                                             'api/v1/person/%1$s/%2$s/%3$s',
979                                             $pathParams,
980                                             $queryParams,
981                                             $formParams);
982         if (isset($result->error))
983             throw new IbisException($result->error);
984         return $result->attribute;
985     }
986 }
987 
Lookup/Ibis web service client API documentation generated by ApiGen