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 institutions.
27 *
28 * **The fetch parameter for institutions**
29 *
30 * All methods that return institutions also accept an optional
31 * ``fetch`` parameter that may be used to request additional
32 * information about the institutions returned. For more details about
33 * the general rules that apply to the ``fetch`` parameter,
34 * refer to the {@link PersonMethods} documentation.
35 *
36 * For institutions the ``fetch`` parameter may be used to fetch
37 * any institution attribute by specifying the ``schemeid`` of an
38 * institution attribute scheme. Examples include ``"address"``,
39 * ``"jpegPhoto"``, ``"universityPhone"``, ``"instPhone"``,
40 * ``"landlinePhone"``, ``"mobilePhone"``, ``"faxNumber"``,
41 * ``"email"`` and ``"labeledURI"``. The full list (which may be
42 * extended over time) may be obtained using {@link allAttributeSchemes}.
43 *
44 * In addition the following pseudo-attributes are supported:
45 *
46 * * ``"phone_numbers"`` - fetches all phone numbers. This is
47 * equivalent to
48 * ``"universityPhone,instPhone,landlinePhone,mobilePhone"``.
49 *
50 * * ``"all_attrs"`` - fetches all attributes from all institution
51 * attribute schemes. This does not include references.
52 *
53 * * ``"contact_rows"`` - fetches all institution contact rows. Any
54 * chained fetches from contact rows are used to fetch attributes from any
55 * people referred to by the contact rows.
56 *
57 * The ``fetch`` parameter may also be used to fetch referenced
58 * people, institutions or groups. This will only include references to
59 * non-cancelled entities. The following references are supported:
60 *
61 * * ``"all_members"`` - fetches all the people who are members of the
62 * institution.
63 *
64 * * ``"parent_insts"`` - fetches all the parent institutions. Note
65 * that currently all institutions have only one parent, but this may change
66 * in the future, and client applications should be prepared to handle
67 * multiple parents.
68 *
69 * * ``"child_insts"`` - fetches all the child institutions.
70 *
71 * * ``"inst_groups"`` - fetches all the groups that belong to the
72 * institution.
73 *
74 * * ``"members_groups"`` - fetches all the groups that form the
75 * institution's membership list.
76 *
77 * * ``"managed_by_groups"`` - fetches all the groups that manage the
78 * institution's data (commonly called "Editor" groups).
79 *
80 * As with person ``fetch`` parameters, the references may be used
81 * in a chain by using the "dot" notation to fetch additional information
82 * about referenced people, institutions or groups. For example
83 * ``"all_members.email"`` will fetch the email addresses of all members
84 * of the institution. For more information about what can be fetched from
85 * referenced people and groups, refer to the documentation for
86 * {@link PersonMethods} and {@link GroupMethods}.
87 *
88 * @author Dean Rasheed (dev-group@ucs.cam.ac.uk)
89 */
90 class InstitutionMethods
91 {
92 // The connection to the server
93 private $conn;
94
95 /**
96 * Create a new InstitutionMethods object.
97 *
98 * @param ClientConnection $conn The ClientConnection object to use to
99 * invoke methods on the server.
100 */
101 public function __construct($conn)
102 {
103 $this->conn = $conn;
104 }
105
106 /**
107 * Return a list of all the institution attribute schemes available.
108 * The ``schemeid`` values of these schemes may be used in the
109 * ``fetch`` parameter of other methods that return institutions.
110 *
111 * ``[ HTTP: GET /api/v1/inst/all-attr-schemes ]``
112 *
113 * @return IbisAttributeScheme[] All the available institution attribute schemes (in precedence
114 * order).
115 */
116 public function allAttributeSchemes()
117 {
118 $pathParams = array();
119 $queryParams = array();
120 $formParams = array();
121 $result = $this->conn->invokeMethod("GET",
122 'api/v1/inst/all-attr-schemes',
123 $pathParams,
124 $queryParams,
125 $formParams);
126 if (isset($result->error))
127 throw new IbisException($result->error);
128 return $result->attributeSchemes;
129 }
130
131 /**
132 * Return a list of all institutions.
133 *
134 * By default, only a few basic details about each institution are
135 * returned, but the optional ``fetch`` parameter may be used
136 * to fetch additional attributes or references.
137 *
138 * ``[ HTTP: GET /api/v1/inst/all-insts ]``
139 *
140 * @param boolean $includeCancelled [optional] Whether or not to include cancelled
141 * institutions. By default, only live institutions are returned.
142 * @param string $fetch [optional] A comma-separated list of any additional
143 * attributes or references to fetch.
144 *
145 * @return IbisInstitution[] The requested institutions (in instid order).
146 */
147 public function allInsts($includeCancelled,
148 $fetch=null)
149 {
150 $pathParams = array();
151 $queryParams = array("includeCancelled" => $includeCancelled,
152 "fetch" => $fetch);
153 $formParams = array();
154 $result = $this->conn->invokeMethod("GET",
155 'api/v1/inst/all-insts',
156 $pathParams,
157 $queryParams,
158 $formParams);
159 if (isset($result->error))
160 throw new IbisException($result->error);
161 return $result->institutions;
162 }
163
164 /**
165 * Get the institutions with the specified IDs.
166 *
167 * By default, only a few basic details about each institution are
168 * returned, but the optional ``fetch`` parameter may be used
169 * to fetch additional attributes or references.
170 *
171 * The results are sorted by ID.
172 *
173 * NOTE: The URL path length is limited to around 8000 characters, and
174 * an instid is up to 8 characters long. Allowing for comma separators
175 * and URL encoding, this limits the number of institutions that this
176 * method may fetch to around 700.
177 *
178 * NOTE: The institutions returned may include cancelled institutions.
179 * It is the caller's responsibility to check their cancelled flags.
180 *
181 * ``[ HTTP: GET /api/v1/inst/list?instids=... ]``
182 *
183 * @param string $instids [required] A comma-separated list of instids.
184 * @param string $fetch [optional] A comma-separated list of any additional
185 * attributes or references to fetch.
186 *
187 * @return IbisInstitution[] The requested institutions (in instid order).
188 */
189 public function listInsts($instids,
190 $fetch=null)
191 {
192 $pathParams = array();
193 $queryParams = array("instids" => $instids,
194 "fetch" => $fetch);
195 $formParams = array();
196 $result = $this->conn->invokeMethod("GET",
197 'api/v1/inst/list',
198 $pathParams,
199 $queryParams,
200 $formParams);
201 if (isset($result->error))
202 throw new IbisException($result->error);
203 return $result->institutions;
204 }
205
206 /**
207 * Find all institutions modified between the specified pair of
208 * transactions.
209 *
210 * The transaction IDs specified should be the IDs from two different
211 * requests for the last (most recent) transaction ID, made at different
212 * times, that returned different values, indicating that some Lookup
213 * data was modified in the period between the two requests. This method
214 * then determines which (if any) institutions were affected.
215 *
216 * By default, only a few basic details about each institution are
217 * returned, but the optional ``fetch`` parameter may be used
218 * to fetch additional attributes or references.
219 *
220 * NOTE: All data returned reflects the latest available data about each
221 * institution. It is not possible to query for old data, or more
222 * detailed information about the specific changes made.
223 *
224 * ``[ HTTP: GET /api/v1/inst/modified-insts?minTxId=...&maxTxId=... ]``
225 *
226 * @param long $minTxId [required] Include modifications made in transactions
227 * after (but not including) this one.
228 * @param long $maxTxId [required] Include modifications made in transactions
229 * up to and including this one.
230 * @param string $instids [optional] Only include institutions with instids in
231 * this list. By default, all modified institutions will be included.
232 * @param boolean $includeCancelled [optional] Include cancelled institutions. By
233 * default, cancelled institutions are excluded.
234 * @param boolean $contactRowChanges [optional] Include institutions whose contact
235 * rows have changed. By default, changes to institution contact rows are
236 * not taken into consideration.
237 * @param boolean $membershipChanges [optional] Include institutions whose members
238 * have changed. By default, changes to institutional memberships are not
239 * taken into consideration.
240 * @param string $fetch [optional] A comma-separated list of any additional
241 * attributes or references to fetch.
242 *
243 * @return IbisInstitution[] The modified institutions (in instid order).
244 */
245 public function modifiedInsts($minTxId,
246 $maxTxId,
247 $instids=null,
248 $includeCancelled=null,
249 $contactRowChanges=null,
250 $membershipChanges=null,
251 $fetch=null)
252 {
253 $pathParams = array();
254 $queryParams = array("minTxId" => $minTxId,
255 "maxTxId" => $maxTxId,
256 "instids" => $instids,
257 "includeCancelled" => $includeCancelled,
258 "contactRowChanges" => $contactRowChanges,
259 "membershipChanges" => $membershipChanges,
260 "fetch" => $fetch);
261 $formParams = array();
262 $result = $this->conn->invokeMethod("GET",
263 'api/v1/inst/modified-insts',
264 $pathParams,
265 $queryParams,
266 $formParams);
267 if (isset($result->error))
268 throw new IbisException($result->error);
269 return $result->institutions;
270 }
271
272 /**
273 * Search for institutions using a free text query string. This is the
274 * same search function that is used in the Lookup web application.
275 *
276 * By default, only a few basic details about each institution are
277 * returned, but the optional ``fetch`` parameter may be used
278 * to fetch additional attributes or references.
279 *
280 * NOTE: If the query string starts with the prefix ``"inst:"``, it
281 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
282 * more advanced searches. An LQL query will ignore the
283 * ``approxMatches`` and ``attributes`` parameters, but
284 * it will respect the value of ``includeCancelled``. In
285 * addition, an LQL query will ignore the ``orderBy`` parameter,
286 * since LQL queries always return results in ID order.
287 *
288 * ``[ HTTP: GET /api/v1/inst/search?query=... ]``
289 *
290 * @param string $query [required] The search string.
291 * @param boolean $approxMatches [optional] Flag to enable more approximate
292 * matching in the search, causing more results to be returned. Defaults
293 * to ``false``. This is ignored for LQL queries.
294 * @param boolean $includeCancelled [optional] Flag to allow cancelled institutions
295 * to be included. Defaults to ``false``.
296 * @param string $attributes [optional] A comma-separated list of attributes to
297 * consider when searching. If this is ``null`` (the default) then
298 * all attribute schemes marked as searchable will be included. This is
299 * ignored for LQL queries.
300 * @param int $offset [optional] The number of results to skip at the start
301 * of the search. Defaults to 0.
302 * @param int $limit [optional] The maximum number of results to return.
303 * Defaults to 100.
304 * @param string $orderBy [optional] The order in which to list the results.
305 * This may be either ``"instid"`` or ``"name"`` (the default for
306 * non-LQL queries). This is ignored for LQL queries, which always return
307 * results in instid order.
308 * @param string $fetch [optional] A comma-separated list of any additional
309 * attributes or references to fetch.
310 *
311 * @return IbisInstitution[] The matching institutions.
312 */
313 public function search($query,
314 $approxMatches=null,
315 $includeCancelled=null,
316 $attributes=null,
317 $offset=null,
318 $limit=null,
319 $orderBy=null,
320 $fetch=null)
321 {
322 $pathParams = array();
323 $queryParams = array("query" => $query,
324 "approxMatches" => $approxMatches,
325 "includeCancelled" => $includeCancelled,
326 "attributes" => $attributes,
327 "offset" => $offset,
328 "limit" => $limit,
329 "orderBy" => $orderBy,
330 "fetch" => $fetch);
331 $formParams = array();
332 $result = $this->conn->invokeMethod("GET",
333 'api/v1/inst/search',
334 $pathParams,
335 $queryParams,
336 $formParams);
337 if (isset($result->error))
338 throw new IbisException($result->error);
339 return $result->institutions;
340 }
341
342 /**
343 * Count the number of institutions that would be returned by a search
344 * using a free text query string.
345 *
346 * NOTE: If the query string starts with the prefix ``"inst:"``, it
347 * is treated as an <a href="/lql" target="_top">LQL query</a>, allowing
348 * more advanced searches. An LQL query will ignore the
349 * ``approxMatches`` and ``attributes`` parameters, but
350 * it will respect the value of ``includeCancelled``.
351 *
352 * ``[ HTTP: GET /api/v1/inst/search-count?query=... ]``
353 *
354 * @param string $query [required] The search string.
355 * @param boolean $approxMatches [optional] Flag to enable more approximate
356 * matching in the search, causing more results to be returned. Defaults
357 * to ``false``. This is ignored for LQL queries.
358 * @param boolean $includeCancelled [optional] Flag to allow cancelled institutions
359 * to be included. Defaults to ``false``.
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 *
365 * @return int The number of matching institutions.
366 */
367 public function searchCount($query,
368 $approxMatches=null,
369 $includeCancelled=null,
370 $attributes=null)
371 {
372 $pathParams = array();
373 $queryParams = array("query" => $query,
374 "approxMatches" => $approxMatches,
375 "includeCancelled" => $includeCancelled,
376 "attributes" => $attributes);
377 $formParams = array();
378 $result = $this->conn->invokeMethod("GET",
379 'api/v1/inst/search-count',
380 $pathParams,
381 $queryParams,
382 $formParams);
383 if (isset($result->error))
384 throw new IbisException($result->error);
385 return intval($result->value);
386 }
387
388 /**
389 * Get the institution with the specified ID.
390 *
391 * By default, only a few basic details about the institution are
392 * returned, but the optional ``fetch`` parameter may be used
393 * to fetch additional attributes or references of the institution.
394 *
395 * NOTE: The institution returned may be a cancelled institution. It is
396 * the caller's responsibility to check its cancelled flag.
397 *
398 * ``[ HTTP: GET /api/v1/inst/{instid} ]``
399 *
400 * @param string $instid [required] The ID of the institution to fetch.
401 * @param string $fetch [optional] A comma-separated list of any additional
402 * attributes or references to fetch.
403 *
404 * @return IbisInstitution The requested institution or ``null`` if it was not found.
405 */
406 public function getInst($instid,
407 $fetch=null)
408 {
409 $pathParams = array("instid" => $instid);
410 $queryParams = array("fetch" => $fetch);
411 $formParams = array();
412 $result = $this->conn->invokeMethod("GET",
413 'api/v1/inst/%1$s',
414 $pathParams,
415 $queryParams,
416 $formParams);
417 if (isset($result->error))
418 throw new IbisException($result->error);
419 return $result->institution;
420 }
421
422 /**
423 * Add an attribute to an institution. By default, this will not add the
424 * attribute again if it already exists.
425 *
426 * When adding an attribute, the new attribute's scheme must be set.
427 * In addition, either its value or its binaryData field should be set.
428 * All the remaining fields of the attribute are optional.
429 *
430 * ``[ HTTP: POST /api/v1/inst/{instid}/add-attribute ]``
431 *
432 * @param string $instid [required] The ID of the institution.
433 * @param IbisAttribute $attr [required] The new attribute to add.
434 * @param int $position [optional] The position of the new attribute in the
435 * list of attributes of the same attribute scheme (1, 2, 3,...). A value
436 * of 0 (the default) will cause the new attribute to be added to the end
437 * of the list of existing attributes for the scheme.
438 * @param boolean $allowDuplicates [optional] If ``true``, the new attribute
439 * will always be added, even if another identical attribute already
440 * exists. If ``false`` (the default), the new attribute will only be
441 * added if it doesn't already exist.
442 * @param string $commitComment [recommended] A short textual description of
443 * the change made (will be visible on the history tab in the web
444 * application).
445 *
446 * @return IbisAttribute The newly created or existing attribute.
447 */
448 public function addAttribute($instid,
449 $attr,
450 $position=null,
451 $allowDuplicates=null,
452 $commitComment=null)
453 {
454 $pathParams = array("instid" => $instid);
455 $queryParams = array();
456 $formParams = array("attr" => $attr,
457 "position" => $position,
458 "allowDuplicates" => $allowDuplicates,
459 "commitComment" => $commitComment);
460 $result = $this->conn->invokeMethod("POST",
461 'api/v1/inst/%1$s/add-attribute',
462 $pathParams,
463 $queryParams,
464 $formParams);
465 if (isset($result->error))
466 throw new IbisException($result->error);
467 return $result->attribute;
468 }
469
470 /**
471 * Get all the cancelled members of the specified institution.
472 *
473 * By default, only a few basic details about each member are returned,
474 * but the optional ``fetch`` parameter may be used to fetch
475 * additional attributes or references of each person.
476 *
477 * NOTE: This method returns only cancelled people. It does not include
478 * people who were removed from the institution. Cancelled people are no
479 * longer considered to be current staff, students or accredited visitors,
480 * and are no longer regarded as belonging to any groups or institutions.
481 * The list returned here reflects their institutional memberships just
482 * before they were cancelled, and so is out-of-date data that should be
483 * used with caution.
484 *
485 * ``[ HTTP: GET /api/v1/inst/{instid}/cancelled-members ]``
486 *
487 * @param string $instid [required] The ID of the institution.
488 * @param string $fetch [optional] A comma-separated list of any additional
489 * attributes or references to fetch for each person.
490 *
491 * @return IbisPerson[] The institution's cancelled members (in identifier order).
492 */
493 public function getCancelledMembers($instid,
494 $fetch=null)
495 {
496 $pathParams = array("instid" => $instid);
497 $queryParams = array("fetch" => $fetch);
498 $formParams = array();
499 $result = $this->conn->invokeMethod("GET",
500 'api/v1/inst/%1$s/cancelled-members',
501 $pathParams,
502 $queryParams,
503 $formParams);
504 if (isset($result->error))
505 throw new IbisException($result->error);
506 return $result->people;
507 }
508
509 /**
510 * Get all the contact rows of the specified institution.
511 *
512 * Any addresses, email addresses, phone numbers and web pages
513 * associated with the contact rows are automatically returned, as
514 * well as any people referred to by the contact rows.
515 *
516 * If any of the contact rows refer to people, then only a few basic
517 * details about each person are returned, but the optional
518 * ``fetch`` parameter may be used to fetch additional
519 * attributes or references of each person.
520 *
521 * NOTE: This method will not include cancelled people.
522 *
523 * ``[ HTTP: GET /api/v1/inst/{instid}/contact-rows ]``
524 *
525 * @param string $instid [required] The ID of the institution.
526 * @param string $fetch [optional] A comma-separated list of any additional
527 * attributes or references to fetch for any people referred to by any
528 * of the contact rows.
529 *
530 * @return IbisContactRow[] The institution's contact rows.
531 */
532 public function getContactRows($instid,
533 $fetch=null)
534 {
535 $pathParams = array("instid" => $instid);
536 $queryParams = array("fetch" => $fetch);
537 $formParams = array();
538 $result = $this->conn->invokeMethod("GET",
539 'api/v1/inst/%1$s/contact-rows',
540 $pathParams,
541 $queryParams,
542 $formParams);
543 if (isset($result->error))
544 throw new IbisException($result->error);
545 return $result->institution->contactRows;
546 }
547
548 /**
549 * Create a group owned by an institution.
550 *
551 * A new group will be created with the institution being its only owner.
552 *
553 * Only limited attributes (short hyphenated name, title and description) of
554 * the new group can be specified when creating a group. The GroupMethod's
555 * update methods be used to modify other attributes.
556 * The new group will have membership visibility of 'university' and be managed
557 * by the same groups as its owning institution.
558 *
559 * ``[ HTTP: POST /api/v1/inst/{instid}/create-group ]``
560 *
561 * @param string $instid [required] The ID of the institution.
562 * @param string $name [required] A short hyphenated name for the new group. Must be in lower case and
563 * begin with the instid followed by a hyphen.
564 * @param string $title [required] A title for the new group.
565 * @param string $description [required] A more detailed description of the new group.
566 * @param string $managedBy [optional] The sole group that will manage group data for the new group.
567 * If not provided, the new group will be managed by the same groups as its owning institution.
568 * @param string $commitComment [recommended] A short textual description of
569 * the change made (will be visible on the history tab in the web
570 * application).
571 *
572 * @return IbisGroup The newly created group.
573 */
574 public function createGroup($instid,
575 $name,
576 $title,
577 $description,
578 $managedBy=null,
579 $commitComment=null)
580 {
581 $pathParams = array("instid" => $instid);
582 $queryParams = array();
583 $formParams = array("name" => $name,
584 "title" => $title,
585 "description" => $description,
586 "managedBy" => $managedBy,
587 "commitComment" => $commitComment);
588 $result = $this->conn->invokeMethod("POST",
589 'api/v1/inst/%1$s/create-group',
590 $pathParams,
591 $queryParams,
592 $formParams);
593 if (isset($result->error))
594 throw new IbisException($result->error);
595 return $result->group;
596 }
597
598 /**
599 * Get one or more (possibly multi-valued) attributes of an institution.
600 * The returned attributes are sorted by attribute scheme precedence and
601 * then attribute precedence.
602 *
603 * ``[ HTTP: GET /api/v1/inst/{instid}/get-attributes?attrs=... ]``
604 *
605 * @param string $instid [required] The ID of the institution.
606 * @param string $attrs [required] The attribute scheme(s) to fetch. This may
607 * include any number of the attributes or pseudo-attributes, but it
608 * may not include references or attribute chains (see the documentation
609 * for the ``fetch`` parameter in this class).
610 *
611 * @return IbisAttribute[] The requested attributes.
612 */
613 public function getAttributes($instid,
614 $attrs)
615 {
616 $pathParams = array("instid" => $instid);
617 $queryParams = array("attrs" => $attrs);
618 $formParams = array();
619 $result = $this->conn->invokeMethod("GET",
620 'api/v1/inst/%1$s/get-attributes',
621 $pathParams,
622 $queryParams,
623 $formParams);
624 if (isset($result->error))
625 throw new IbisException($result->error);
626 return $result->attributes;
627 }
628
629 /**
630 * Get all the members of the specified institution.
631 *
632 * By default, only a few basic details about each member are returned,
633 * but the optional ``fetch`` parameter may be used to fetch
634 * additional attributes or references of each person.
635 *
636 * NOTE: This method will not include cancelled people.
637 *
638 * ``[ HTTP: GET /api/v1/inst/{instid}/members ]``
639 *
640 * @param string $instid [required] The ID of the institution.
641 * @param string $fetch [optional] A comma-separated list of any additional
642 * attributes or references to fetch for each person.
643 *
644 * @return IbisPerson[] The institution's members (in identifier order).
645 */
646 public function getMembers($instid,
647 $fetch=null)
648 {
649 $pathParams = array("instid" => $instid);
650 $queryParams = array("fetch" => $fetch);
651 $formParams = array();
652 $result = $this->conn->invokeMethod("GET",
653 'api/v1/inst/%1$s/members',
654 $pathParams,
655 $queryParams,
656 $formParams);
657 if (isset($result->error))
658 throw new IbisException($result->error);
659 return $result->people;
660 }
661
662 /**
663 * Delete an attribute of an institution. It is not an error if the
664 * attribute does not exist.
665 *
666 * Note that in this method, the ``commitComment`` is passed
667 * as a query parameter, rather than as a form parameter, for greater
668 * client compatibility.
669 *
670 * ``[ HTTP: DELETE /api/v1/inst/{instid}/{attrid} ]``
671 *
672 * @param string $instid [required] The ID of the institution.
673 * @param int $attrid [required] The ID of the attribute to delete.
674 * @param string $commitComment [recommended] A short textual description of
675 * the change made (will be visible on the history tab in the web
676 * application).
677 *
678 * @return boolean ``true`` if the attribute was deleted by this method, or
679 * ``false`` if it did not exist.
680 */
681 public function deleteAttribute($instid,
682 $attrid,
683 $commitComment=null)
684 {
685 $pathParams = array("instid" => $instid,
686 "attrid" => $attrid);
687 $queryParams = array("commitComment" => $commitComment);
688 $formParams = array();
689 $result = $this->conn->invokeMethod("DELETE",
690 'api/v1/inst/%1$s/%2$s',
691 $pathParams,
692 $queryParams,
693 $formParams);
694 if (isset($result->error))
695 throw new IbisException($result->error);
696 return strcasecmp($result->value, "true") == 0;
697 }
698
699 /**
700 * Get a specific attribute of an institution.
701 *
702 * ``[ HTTP: GET /api/v1/inst/{instid}/{attrid} ]``
703 *
704 * @param string $instid [required] The ID of the institution.
705 * @param int $attrid [required] The ID of the attribute to fetch.
706 *
707 * @return IbisAttribute The requested attribute.
708 */
709 public function getAttribute($instid,
710 $attrid)
711 {
712 $pathParams = array("instid" => $instid,
713 "attrid" => $attrid);
714 $queryParams = array();
715 $formParams = array();
716 $result = $this->conn->invokeMethod("GET",
717 'api/v1/inst/%1$s/%2$s',
718 $pathParams,
719 $queryParams,
720 $formParams);
721 if (isset($result->error))
722 throw new IbisException($result->error);
723 return $result->attribute;
724 }
725
726 /**
727 * Update an attribute of an institution.
728 *
729 * The attribute's value, binaryData, comment and effective date fields
730 * will all be updated using the data supplied. All other fields will be
731 * left unchanged.
732 *
733 * To avoid inadvertently changing fields of the attribute, it is
734 * recommended that {@link getAttribute} be used to
735 * retrieve the current value of the attribute, before calling this
736 * method with the required changes.
737 *
738 * ``[ HTTP: PUT /api/v1/inst/{instid}/{attrid} ]``
739 *
740 * @param string $instid [required] The ID of the institution.
741 * @param int $attrid [required] The ID of the attribute to update.
742 * @param IbisAttribute $attr [required] The new attribute values to apply.
743 * @param string $commitComment [recommended] A short textual description of
744 * the change made (will be visible on the history tab in the web
745 * application).
746 *
747 * @return IbisAttribute The updated attribute.
748 */
749 public function updateAttribute($instid,
750 $attrid,
751 $attr,
752 $commitComment=null)
753 {
754 $pathParams = array("instid" => $instid,
755 "attrid" => $attrid);
756 $queryParams = array();
757 $formParams = array("attr" => $attr,
758 "commitComment" => $commitComment);
759 $result = $this->conn->invokeMethod("PUT",
760 'api/v1/inst/%1$s/%2$s',
761 $pathParams,
762 $queryParams,
763 $formParams);
764 if (isset($result->error))
765 throw new IbisException($result->error);
766 return $result->attribute;
767 }
768 }
769