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. The name
232 * of the query parameter reflects a time when only crsids were used with
233 * lookup. Alternate schemes can be specified as noted above.
234 * @param string $fetch [optional] A comma-separated list of any additional
235 * attributes or references to fetch.
236 *
237 * @return IbisPerson[] The requested people (in identifier order).
238 */
239 public function listPeople($crsids,
240 $fetch=null)
241 {
242 $pathParams = array();
243 $queryParams = array("crsids" => $crsids,
244 "fetch" => $fetch);
245 $formParams = array();
246 $result = $this->conn->invokeMethod("GET",
247 'api/v1/person/list',
248 $pathParams,
249 $queryParams,
250 $formParams);
251 if (isset($result->error))
252 throw new IbisException($result->error);
253 return $result->people;
254 }
255
256 /**
257 * Find all people modified between the specified pair of transactions.
258 *
259 * The transaction IDs specified should be the IDs from two different
260 * requests for the last (most recent) transaction ID, made at different
261 * times, that returned different values, indicating that some Lookup
262 * data was modified in the period between the two requests. This method
263 * then determines which (if any) people were affected.
264 *
265 * By default, only a few basic details about each person are returned,
266 * but the optional ``fetch`` parameter may be used to fetch
267 * additional attributes or references.
268 *
269 * NOTE: All data returned reflects the latest available data about each
270 * person. It is not possible to query for old data, or more detailed
271 * information about the specific changes made.
272 *
273 * ``[ HTTP: GET /api/v1/person/modified-people?minTxId=...&maxTxId=... ]``
274 *
275 * @param long $minTxId [required] Include modifications made in transactions
276 * after (but not including) this one.
277 * @param long $maxTxId [required] Include modifications made in transactions
278 * up to and including this one.
279 * @param string $crsids [optional] Only include people with identifiers in this
280 * list. By default, all modified people will be included.
281 * @param boolean $includeCancelled [optional] Include cancelled people (people
282 * who are no longer members of the University). By default, cancelled
283 * people are excluded.
284 * @param boolean $membershipChanges [optional] Include people whose group or
285 * institutional memberships have changed. By default, only people whose
286 * attributes have been directly modified are included.
287 * @param boolean $instNameChanges [optional] Include people who are members of
288 * instituions whose names have changed. This will also cause people
289 * whose group or institutional memberships have changed to be included.
290 * By default, changes to institution names do not propagate to people.
291 * @param string $fetch [optional] A comma-separated list of any additional
292 * attributes or references to fetch.
293 *
294 * @return IbisPerson[] The modified people (in identifier order).
295 */
296 public function modifiedPeople($minTxId,
297 $maxTxId,
298 $crsids=null,
299 $includeCancelled=null,
300 $membershipChanges=null,
301 $instNameChanges=null,
302 $fetch=null)
303 {
304 $pathParams = array();
305 $queryParams = array("minTxId" => $minTxId,
306 "maxTxId" => $maxTxId,
307 "crsids" => $crsids,
308 "includeCancelled" => $includeCancelled,
309 "membershipChanges" => $membershipChanges,
310 "instNameChanges" => $instNameChanges,
311 "fetch" => $fetch);
312 $formParams = array();
313 $result = $this->conn->invokeMethod("GET",
314 'api/v1/person/modified-people',
315 $pathParams,
316 $queryParams,
317 $formParams);
318 if (isset($result->error))
319 throw new IbisException($result->error);
320 return $result->people;
321 }
322
323 /**
324 * Search for people using a free text query string. This is the same
325 * search function that is used in the Lookup web application.
326 *
327 * By default, only a few basic details about each person are returned,
328 * but the optional ``fetch`` parameter may be used to fetch
329 * additional attributes or references.
330 *
331 * NOTE: If the query string starts with the prefix ``"person:"``, it
332 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
333 * more advanced searches. An LQL query will ignore the
334 * ``approxMatches`` and ``attributes`` parameters, but
335 * it will respect the values of ``includeCancelled`` and
336 * ``misStatus``. In addition, an LQL query will ignore the
337 * ``orderBy`` parameter, since LQL queries always return
338 * results in ID order.
339 *
340 * ``[ HTTP: GET /api/v1/person/search?query=... ]``
341 *
342 * @param string $query [required] The search string.
343 * @param boolean $approxMatches [optional] Flag to enable more approximate
344 * matching in the search, causing more results to be returned. Defaults
345 * to ``false``. This is ignored for LQL queries.
346 * @param boolean $includeCancelled [optional] Flag to allow cancelled people to
347 * be included (people who are no longer members of the University).
348 * Defaults to ``false``.
349 * @param string $misStatus [optional] The type of people to search for. This may
350 * be
351 *
352 * * ``"staff"`` - only include people whose MIS status is
353 * ``""`` (empty string), ``"staff"``, or
354 * ``"staff,student"``.
355 *
356 * * ``"student"`` - only include people whose MIS status is set to
357 * ``"student"`` or ``"staff,student"``.
358 *
359 * Otherwise all matching people will be included (the default). Note
360 * that the ``"staff"`` and ``"student"`` options are not
361 * mutually exclusive.
362 * @param string $attributes [optional] A comma-separated list of attributes to
363 * consider when searching. If this is ``null`` (the default) then
364 * all attribute schemes marked as searchable will be included. This is
365 * ignored for LQL queries.
366 * @param int $offset [optional] The number of results to skip at the start
367 * of the search. Defaults to 0.
368 * @param int $limit [optional] The maximum number of results to return.
369 * Defaults to 100.
370 * @param string $orderBy [optional] The order in which to list the results.
371 * This may be either ``"identifier"`` or ``"surname"`` (the
372 * default for non-LQL queries). This is ignored for LQL queries, which
373 * always return results in identifier order.
374 * @param string $fetch [optional] A comma-separated list of any additional
375 * attributes or references to fetch.
376 *
377 * @return IbisPerson[] The matching people.
378 */
379 public function search($query,
380 $approxMatches=null,
381 $includeCancelled=null,
382 $misStatus=null,
383 $attributes=null,
384 $offset=null,
385 $limit=null,
386 $orderBy=null,
387 $fetch=null)
388 {
389 $pathParams = array();
390 $queryParams = array("query" => $query,
391 "approxMatches" => $approxMatches,
392 "includeCancelled" => $includeCancelled,
393 "misStatus" => $misStatus,
394 "attributes" => $attributes,
395 "offset" => $offset,
396 "limit" => $limit,
397 "orderBy" => $orderBy,
398 "fetch" => $fetch);
399 $formParams = array();
400 $result = $this->conn->invokeMethod("GET",
401 'api/v1/person/search',
402 $pathParams,
403 $queryParams,
404 $formParams);
405 if (isset($result->error))
406 throw new IbisException($result->error);
407 return $result->people;
408 }
409
410 /**
411 * Count the number of people that would be returned by a search using
412 * a free text query string.
413 *
414 * NOTE: If the query string starts with the prefix ``"person:"``, it
415 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
416 * more advanced searches. An LQL query will ignore the
417 * ``approxMatches`` and ``attributes`` parameters, but
418 * it will respect the values of ``includeCancelled`` and
419 * ``misStatus``.
420 *
421 * ``[ HTTP: GET /api/v1/person/search-count?query=... ]``
422 *
423 * @param string $query [required] The search string.
424 * @param boolean $approxMatches [optional] Flag to enable more approximate
425 * matching in the search, causing more results to be returned. Defaults
426 * to ``false``. This is ignored for LQL queries.
427 * @param boolean $includeCancelled [optional] Flag to allow cancelled people to
428 * be included (people who are no longer members of the University).
429 * Defaults to ``false``.
430 * @param string $misStatus [optional] The type of people to search for. This may
431 * be
432 *
433 * * ``"staff"`` - only include people whose MIS status is
434 * ``""`` (empty string), ``"staff"``, or
435 * ``"staff,student"``.
436 *
437 * * ``"student"`` - only include people whose MIS status is set to
438 * ``"student"`` or ``"staff,student"``.
439 *
440 * Otherwise all matching people will be included (the default). Note
441 * that the ``"staff"`` and ``"student"`` options are not
442 * mutually exclusive.
443 * @param string $attributes [optional] A comma-separated list of attributes to
444 * consider when searching. If this is ``null`` (the default) then
445 * all attribute schemes marked as searchable will be included. This is
446 * ignored for LQL queries.
447 *
448 * @return int The number of matching people.
449 */
450 public function searchCount($query,
451 $approxMatches=null,
452 $includeCancelled=null,
453 $misStatus=null,
454 $attributes=null)
455 {
456 $pathParams = array();
457 $queryParams = array("query" => $query,
458 "approxMatches" => $approxMatches,
459 "includeCancelled" => $includeCancelled,
460 "misStatus" => $misStatus,
461 "attributes" => $attributes);
462 $formParams = array();
463 $result = $this->conn->invokeMethod("GET",
464 'api/v1/person/search-count',
465 $pathParams,
466 $queryParams,
467 $formParams);
468 if (isset($result->error))
469 throw new IbisException($result->error);
470 return intval($result->value);
471 }
472
473 /**
474 * Get the person with the specified identifier.
475 *
476 * By default, only a few basic details about the person are returned,
477 * but the optional ``fetch`` parameter may be used to fetch
478 * additional attributes or references of the person.
479 *
480 * NOTE: The person returned may be a cancelled person. It is the
481 * caller's repsonsibility to check its cancelled flag.
482 *
483 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier} ]``
484 *
485 * @param string $scheme [required] The person identifier scheme. Typically this
486 * should be ``"crsid"``, but other identifier schemes
487 * such as ``"usn"`` or ``"staffNumber"`` may be available.
488 * @param string $identifier [required] The identifier of the person to fetch
489 * (typically their CRSid).
490 * @param string $fetch [optional] A comma-separated list of any additional
491 * attributes or references to fetch.
492 *
493 * @return IbisPerson The requested person or ``null`` if they were not found.
494 */
495 public function getPerson($scheme,
496 $identifier,
497 $fetch=null)
498 {
499 $pathParams = array("scheme" => $scheme,
500 "identifier" => $identifier);
501 $queryParams = array("fetch" => $fetch);
502 $formParams = array();
503 $result = $this->conn->invokeMethod("GET",
504 'api/v1/person/%1$s/%2$s',
505 $pathParams,
506 $queryParams,
507 $formParams);
508 if (isset($result->error))
509 throw new IbisException($result->error);
510 return $result->person;
511 }
512
513 /**
514 * Add an attribute to a person. By default, this will not add the
515 * attribute again if it already exists.
516 *
517 * When adding an attribute, the new attribute's scheme must be set.
518 * In addition, either its value or its binaryData field should be set.
519 * All the remaining fields of the attribute are optional.
520 *
521 * ``[ HTTP: POST /api/v1/person/{scheme}/{identifier}/add-attribute ]``
522 *
523 * @param string $scheme [required] The person identifier scheme. Typically this
524 * should be ``"crsid"``, but other identifier schemes may be
525 * available in the future, such as ``"usn"`` or
526 * ``"staffNumber"``.
527 * @param string $identifier [required] The identifier of the person to udpate
528 * (typically their CRSid).
529 * @param IbisAttribute $attr [required] The new attribute to add.
530 * @param int $position [optional] The position of the new attribute in the
531 * list of attributes of the same attribute scheme (1, 2, 3,...). A value
532 * of 0 (the default) will cause the new attribute to be added to the end
533 * of the list of existing attributes for the scheme.
534 * @param boolean $allowDuplicates [optional] If ``true``, the new attribute
535 * will always be added, even if another identical attribute already
536 * exists. If ``false`` (the default), the new attribute will only be
537 * added if it doesn't already exist.
538 * @param string $commitComment [recommended] A short textual description of
539 * the change made (will be visible on the history tab in the web
540 * application).
541 *
542 * @return IbisAttribute The newly created or existing attribute.
543 */
544 public function addAttribute($scheme,
545 $identifier,
546 $attr,
547 $position=null,
548 $allowDuplicates=null,
549 $commitComment=null)
550 {
551 $pathParams = array("scheme" => $scheme,
552 "identifier" => $identifier);
553 $queryParams = array();
554 $formParams = array("attr" => $attr,
555 "position" => $position,
556 "allowDuplicates" => $allowDuplicates,
557 "commitComment" => $commitComment);
558 $result = $this->conn->invokeMethod("POST",
559 'api/v1/person/%1$s/%2$s/add-attribute',
560 $pathParams,
561 $queryParams,
562 $formParams);
563 if (isset($result->error))
564 throw new IbisException($result->error);
565 return $result->attribute;
566 }
567
568 /**
569 * Get one or more (possibly multi-valued) attributes of a person. The
570 * returned attributes are sorted by attribute scheme precedence and
571 * then attribute precedence.
572 *
573 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/get-attributes?attrs=... ]``
574 *
575 * @param string $scheme [required] The person identifier scheme. Typically this
576 * should be ``"crsid"``, but other identifier schemes may be
577 * available in the future, such as ``"usn"`` or
578 * ``"staffNumber"``.
579 * @param string $identifier [required] The identifier of the person (typically
580 * their CRSid).
581 * @param string $attrs [required] The attribute scheme(s) to fetch. This may
582 * include any number of the attributes or pseudo-attributes, but it
583 * may not include references or attribute chains (see the documentation
584 * for the ``fetch`` parameter in this class).
585 *
586 * @return IbisAttribute[] The requested attributes.
587 */
588 public function getAttributes($scheme,
589 $identifier,
590 $attrs)
591 {
592 $pathParams = array("scheme" => $scheme,
593 "identifier" => $identifier);
594 $queryParams = array("attrs" => $attrs);
595 $formParams = array();
596 $result = $this->conn->invokeMethod("GET",
597 'api/v1/person/%1$s/%2$s/get-attributes',
598 $pathParams,
599 $queryParams,
600 $formParams);
601 if (isset($result->error))
602 throw new IbisException($result->error);
603 return $result->attributes;
604 }
605
606 /**
607 * Get all the groups to which the specified person belongs, including
608 * indirect group memberships, via groups that include other groups.
609 * The returned list of groups is sorted by groupid.
610 *
611 * Note that some group memberships may not be visible to you. This
612 * method will only return those group memberships that you have
613 * permission to see.
614 *
615 * By default, only a few basic details about each group are returned,
616 * but the optional ``fetch`` parameter may be used to fetch
617 * additional attributes or references of each group.
618 *
619 * NOTE: This method will not include cancelled groups.
620 *
621 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/groups ]``
622 *
623 * @param string $scheme [required] The person identifier scheme. Typically this
624 * should be ``"crsid"``, but other identifier schemes may be
625 * available in the future, such as ``"usn"`` or
626 * ``"staffNumber"``.
627 * @param string $identifier [required] The identifier of the person (typically
628 * their CRSid).
629 * @param string $fetch [optional] A comma-separated list of any additional
630 * attributes or references to fetch.
631 *
632 * @return IbisGroup[] The person's groups (in groupid order).
633 */
634 public function getGroups($scheme,
635 $identifier,
636 $fetch=null)
637 {
638 $pathParams = array("scheme" => $scheme,
639 "identifier" => $identifier);
640 $queryParams = array("fetch" => $fetch);
641 $formParams = array();
642 $result = $this->conn->invokeMethod("GET",
643 'api/v1/person/%1$s/%2$s/groups',
644 $pathParams,
645 $queryParams,
646 $formParams);
647 if (isset($result->error))
648 throw new IbisException($result->error);
649 return $result->groups;
650 }
651
652 /**
653 * Get all the institutions to which the specified person belongs. The
654 * returned list of institutions is sorted by name.
655 *
656 * By default, only a few basic details about each institution are
657 * returned, but the optional ``fetch`` parameter may be used
658 * to fetch additional attributes or references of each institution.
659 *
660 * NOTE: This method will not include cancelled institutions.
661 *
662 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/insts ]``
663 *
664 * @param string $scheme [required] The person identifier scheme. Typically this
665 * should be ``"crsid"``, but other identifier schemes may be
666 * available in the future, such as ``"usn"`` or
667 * ``"staffNumber"``.
668 * @param string $identifier [required] The identifier of the person (typically
669 * their CRSid).
670 * @param string $fetch [optional] A comma-separated list of any additional
671 * attributes or references to fetch.
672 *
673 * @return IbisInstitution[] The person's institutions (in name order).
674 */
675 public function getInsts($scheme,
676 $identifier,
677 $fetch=null)
678 {
679 $pathParams = array("scheme" => $scheme,
680 "identifier" => $identifier);
681 $queryParams = array("fetch" => $fetch);
682 $formParams = array();
683 $result = $this->conn->invokeMethod("GET",
684 'api/v1/person/%1$s/%2$s/insts',
685 $pathParams,
686 $queryParams,
687 $formParams);
688 if (isset($result->error))
689 throw new IbisException($result->error);
690 return $result->institutions;
691 }
692
693 /**
694 * Test if the specified person is a member of the specified group.
695 *
696 * NOTE: This may be used with cancelled people and groups.
697 *
698 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-group/{groupid} ]``
699 *
700 * @param string $scheme [required] The person identifier scheme. Typically this
701 * should be ``"crsid"``, but other identifier schemes may be
702 * available in the future, such as ``"usn"`` or
703 * ``"staffNumber"``.
704 * @param string $identifier [required] The identifier of the person (typically
705 * their CRSid).
706 * @param string $groupid [required] The ID or name of the group.
707 *
708 * @return boolean ``true`` if the specified person is in the specified
709 * group, ``false`` otherwise (or if the person or group does not
710 * exist).
711 */
712 public function isMemberOfGroup($scheme,
713 $identifier,
714 $groupid)
715 {
716 $pathParams = array("scheme" => $scheme,
717 "identifier" => $identifier,
718 "groupid" => $groupid);
719 $queryParams = array();
720 $formParams = array();
721 $result = $this->conn->invokeMethod("GET",
722 'api/v1/person/%1$s/%2$s/is-member-of-group/%3$s',
723 $pathParams,
724 $queryParams,
725 $formParams);
726 if (isset($result->error))
727 throw new IbisException($result->error);
728 return strcasecmp($result->value, "true") == 0;
729 }
730
731 /**
732 * Test if the specified person is a member of the specified institution.
733 *
734 * NOTE: This may be used with cancelled people and institutions, but
735 * it will not include cancelled membership groups.
736 *
737 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/is-member-of-inst/{instid} ]``
738 *
739 * @param string $scheme [required] The person identifier scheme. Typically this
740 * should be ``"crsid"``, but other identifier schemes may be
741 * available in the future, such as ``"usn"`` or
742 * ``"staffNumber"``.
743 * @param string $identifier [required] The identifier of the person (typically
744 * their CRSid).
745 * @param string $instid [required] The ID of the institution.
746 *
747 * @return boolean ``true`` if the specified person is in the specified
748 * institution, ``false`` otherwise (or if the person or institution
749 * does not exist).
750 */
751 public function isMemberOfInst($scheme,
752 $identifier,
753 $instid)
754 {
755 $pathParams = array("scheme" => $scheme,
756 "identifier" => $identifier,
757 "instid" => $instid);
758 $queryParams = array();
759 $formParams = array();
760 $result = $this->conn->invokeMethod("GET",
761 'api/v1/person/%1$s/%2$s/is-member-of-inst/%3$s',
762 $pathParams,
763 $queryParams,
764 $formParams);
765 if (isset($result->error))
766 throw new IbisException($result->error);
767 return strcasecmp($result->value, "true") == 0;
768 }
769
770 /**
771 * Get all the groups that the specified person has persmission to edit.
772 * The returned list of groups is sorted by groupid.
773 *
774 * Note that some group memberships may not be visible to you. This
775 * method will only include groups for which you have persmission to
776 * see the applicable manager group memberships.
777 *
778 * By default, only a few basic details about each group are returned,
779 * but the optional ``fetch`` parameter may be used to fetch
780 * additional attributes or references of each group.
781 *
782 * NOTE: This method will not include cancelled groups.
783 *
784 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-groups ]``
785 *
786 * @param string $scheme [required] The person identifier scheme. Typically this
787 * should be ``"crsid"``, but other identifier schemes may be
788 * available in the future, such as ``"usn"`` or
789 * ``"staffNumber"``.
790 * @param string $identifier [required] The identifier of the person (typically
791 * their CRSid).
792 * @param string $fetch [optional] A comma-separated list of any additional
793 * attributes or references to fetch.
794 *
795 * @return IbisGroup[] The groups that the person manages (in groupid order).
796 */
797 public function getManagedGroups($scheme,
798 $identifier,
799 $fetch=null)
800 {
801 $pathParams = array("scheme" => $scheme,
802 "identifier" => $identifier);
803 $queryParams = array("fetch" => $fetch);
804 $formParams = array();
805 $result = $this->conn->invokeMethod("GET",
806 'api/v1/person/%1$s/%2$s/manages-groups',
807 $pathParams,
808 $queryParams,
809 $formParams);
810 if (isset($result->error))
811 throw new IbisException($result->error);
812 return $result->groups;
813 }
814
815 /**
816 * Get all the institutions that the specified person has permission to
817 * edit. The returned list of institutions is sorted by name.
818 *
819 * Note that some group memberships may not be visible to you. This
820 * method will only include institutions for which you have permission
821 * to see the applicable editor group memberships.
822 *
823 * By default, only a few basic details about each institution are
824 * returned, but the optional ``fetch`` parameter may be used
825 * to fetch additional attributes or references of each institution.
826 *
827 * NOTE: This method will not include cancelled institutions.
828 *
829 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/manages-insts ]``
830 *
831 * @param string $scheme [required] The person identifier scheme. Typically this
832 * should be ``"crsid"``, but other identifier schemes may be
833 * available in the future, such as ``"usn"`` or
834 * ``"staffNumber"``.
835 * @param string $identifier [required] The identifier of the person (typically
836 * their CRSid).
837 * @param string $fetch [optional] A comma-separated list of any additional
838 * attributes or references to fetch.
839 *
840 * @return IbisInstitution[] The institutions that the person manages (in name order).
841 */
842 public function getManagedInsts($scheme,
843 $identifier,
844 $fetch=null)
845 {
846 $pathParams = array("scheme" => $scheme,
847 "identifier" => $identifier);
848 $queryParams = array("fetch" => $fetch);
849 $formParams = array();
850 $result = $this->conn->invokeMethod("GET",
851 'api/v1/person/%1$s/%2$s/manages-insts',
852 $pathParams,
853 $queryParams,
854 $formParams);
855 if (isset($result->error))
856 throw new IbisException($result->error);
857 return $result->institutions;
858 }
859
860 /**
861 * Delete an attribute of a person. It is not an error if the attribute
862 * does not exist.
863 *
864 * Note that in this method, the ``commitComment`` is passed
865 * as a query parameter, rather than as a form parameter, for greater
866 * client compatibility.
867 *
868 * ``[ HTTP: DELETE /api/v1/person/{scheme}/{identifier}/{attrid} ]``
869 *
870 * @param string $scheme [required] The person identifier scheme. Typically this
871 * should be ``"crsid"``, but other identifier schemes may be
872 * available in the future, such as ``"usn"`` or
873 * ``"staffNumber"``.
874 * @param string $identifier [required] The identifier of the person to udpate
875 * (typically their CRSid).
876 * @param int $attrid [required] The ID of the attribute to delete.
877 * @param string $commitComment [recommended] A short textual description of
878 * the change made (will be visible on the history tab in the web
879 * application).
880 *
881 * @return boolean ``true`` if the attribute was deleted by this method, or
882 * ``false`` if it did not exist.
883 */
884 public function deleteAttribute($scheme,
885 $identifier,
886 $attrid,
887 $commitComment=null)
888 {
889 $pathParams = array("scheme" => $scheme,
890 "identifier" => $identifier,
891 "attrid" => $attrid);
892 $queryParams = array("commitComment" => $commitComment);
893 $formParams = array();
894 $result = $this->conn->invokeMethod("DELETE",
895 'api/v1/person/%1$s/%2$s/%3$s',
896 $pathParams,
897 $queryParams,
898 $formParams);
899 if (isset($result->error))
900 throw new IbisException($result->error);
901 return strcasecmp($result->value, "true") == 0;
902 }
903
904 /**
905 * Get a specific attribute of a person.
906 *
907 * ``[ HTTP: GET /api/v1/person/{scheme}/{identifier}/{attrid} ]``
908 *
909 * @param string $scheme [required] The person identifier scheme. Typically this
910 * should be ``"crsid"``, but other identifier schemes may be
911 * available in the future, such as ``"usn"`` or
912 * ``"staffNumber"``.
913 * @param string $identifier [required] The identifier of the person (typically
914 * their CRSid).
915 * @param int $attrid [required] The ID of the attribute to fetch.
916 *
917 * @return IbisAttribute The requested attribute.
918 */
919 public function getAttribute($scheme,
920 $identifier,
921 $attrid)
922 {
923 $pathParams = array("scheme" => $scheme,
924 "identifier" => $identifier,
925 "attrid" => $attrid);
926 $queryParams = array();
927 $formParams = array();
928 $result = $this->conn->invokeMethod("GET",
929 'api/v1/person/%1$s/%2$s/%3$s',
930 $pathParams,
931 $queryParams,
932 $formParams);
933 if (isset($result->error))
934 throw new IbisException($result->error);
935 return $result->attribute;
936 }
937
938 /**
939 * Update an attribute of a person.
940 *
941 * The attribute's value, binaryData, comment, instid and effective date
942 * fields will all be updated using the data supplied. All other fields
943 * will be left unchanged.
944 *
945 * To avoid inadvertently changing fields of the attribute, it is
946 * recommended that {@link getAttribute} be used to
947 * retrieve the current value of the attribute, before calling this
948 * method with the required changes.
949 *
950 * ``[ HTTP: PUT /api/v1/person/{scheme}/{identifier}/{attrid} ]``
951 *
952 * @param string $scheme [required] The person identifier scheme. Typically this
953 * should be ``"crsid"``, but other identifier schemes may be
954 * available in the future, such as ``"usn"`` or
955 * ``"staffNumber"``.
956 * @param string $identifier [required] The identifier of the person to udpate
957 * (typically their CRSid).
958 * @param int $attrid [required] The ID of the attribute to update.
959 * @param IbisAttribute $attr [required] The new attribute values to apply.
960 * @param string $commitComment [recommended] A short textual description of
961 * the change made (will be visible on the history tab in the web
962 * application).
963 *
964 * @return IbisAttribute The updated attribute.
965 */
966 public function updateAttribute($scheme,
967 $identifier,
968 $attrid,
969 $attr,
970 $commitComment=null)
971 {
972 $pathParams = array("scheme" => $scheme,
973 "identifier" => $identifier,
974 "attrid" => $attrid);
975 $queryParams = array();
976 $formParams = array("attr" => $attr,
977 "commitComment" => $commitComment);
978 $result = $this->conn->invokeMethod("PUT",
979 'api/v1/person/%1$s/%2$s/%3$s',
980 $pathParams,
981 $queryParams,
982 $formParams);
983 if (isset($result->error))
984 throw new IbisException($result->error);
985 return $result->attribute;
986 }
987 }
988