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