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 repsonsibility 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 repsonsibility 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 * Get one or more (possibly multi-valued) attributes of an institution.
550 * The returned attributes are sorted by attribute scheme precedence and
551 * then attribute precedence.
552 *
553 * ``[ HTTP: GET /api/v1/inst/{instid}/get-attributes?attrs=... ]``
554 *
555 * @param string $instid [required] The ID of the institution.
556 * @param string $attrs [required] The attribute scheme(s) to fetch. This may
557 * include any number of the attributes or pseudo-attributes, but it
558 * may not include references or attribute chains (see the documentation
559 * for the ``fetch`` parameter in this class).
560 *
561 * @return IbisAttribute[] The requested attributes.
562 */
563 public function getAttributes($instid,
564 $attrs)
565 {
566 $pathParams = array("instid" => $instid);
567 $queryParams = array("attrs" => $attrs);
568 $formParams = array();
569 $result = $this->conn->invokeMethod("GET",
570 'api/v1/inst/%1$s/get-attributes',
571 $pathParams,
572 $queryParams,
573 $formParams);
574 if (isset($result->error))
575 throw new IbisException($result->error);
576 return $result->attributes;
577 }
578
579 /**
580 * Get all the members of the specified institution.
581 *
582 * By default, only a few basic details about each member are returned,
583 * but the optional ``fetch`` parameter may be used to fetch
584 * additional attributes or references of each person.
585 *
586 * NOTE: This method will not include cancelled people.
587 *
588 * ``[ HTTP: GET /api/v1/inst/{instid}/members ]``
589 *
590 * @param string $instid [required] The ID of the institution.
591 * @param string $fetch [optional] A comma-separated list of any additional
592 * attributes or references to fetch for each person.
593 *
594 * @return IbisPerson[] The institution's members (in identifier order).
595 */
596 public function getMembers($instid,
597 $fetch=null)
598 {
599 $pathParams = array("instid" => $instid);
600 $queryParams = array("fetch" => $fetch);
601 $formParams = array();
602 $result = $this->conn->invokeMethod("GET",
603 'api/v1/inst/%1$s/members',
604 $pathParams,
605 $queryParams,
606 $formParams);
607 if (isset($result->error))
608 throw new IbisException($result->error);
609 return $result->people;
610 }
611
612 /**
613 * Delete an attribute of an institution. It is not an error if the
614 * attribute does not exist.
615 *
616 * Note that in this method, the ``commitComment`` is passed
617 * as a query parameter, rather than as a form parameter, for greater
618 * client compatibility.
619 *
620 * ``[ HTTP: DELETE /api/v1/inst/{instid}/{attrid} ]``
621 *
622 * @param string $instid [required] The ID of the institution.
623 * @param int $attrid [required] The ID of the attribute to delete.
624 * @param string $commitComment [recommended] A short textual description of
625 * the change made (will be visible on the history tab in the web
626 * application).
627 *
628 * @return boolean ``true`` if the attribute was deleted by this method, or
629 * ``false`` if it did not exist.
630 */
631 public function deleteAttribute($instid,
632 $attrid,
633 $commitComment=null)
634 {
635 $pathParams = array("instid" => $instid,
636 "attrid" => $attrid);
637 $queryParams = array("commitComment" => $commitComment);
638 $formParams = array();
639 $result = $this->conn->invokeMethod("DELETE",
640 'api/v1/inst/%1$s/%2$s',
641 $pathParams,
642 $queryParams,
643 $formParams);
644 if (isset($result->error))
645 throw new IbisException($result->error);
646 return strcasecmp($result->value, "true") == 0;
647 }
648
649 /**
650 * Get a specific attribute of an institution.
651 *
652 * ``[ HTTP: GET /api/v1/inst/{instid}/{attrid} ]``
653 *
654 * @param string $instid [required] The ID of the institution.
655 * @param int $attrid [required] The ID of the attribute to fetch.
656 *
657 * @return IbisAttribute The requested attribute.
658 */
659 public function getAttribute($instid,
660 $attrid)
661 {
662 $pathParams = array("instid" => $instid,
663 "attrid" => $attrid);
664 $queryParams = array();
665 $formParams = array();
666 $result = $this->conn->invokeMethod("GET",
667 'api/v1/inst/%1$s/%2$s',
668 $pathParams,
669 $queryParams,
670 $formParams);
671 if (isset($result->error))
672 throw new IbisException($result->error);
673 return $result->attribute;
674 }
675
676 /**
677 * Update an attribute of an institution.
678 *
679 * The attribute's value, binaryData, comment and effective date fields
680 * will all be updated using the data supplied. All other fields will be
681 * left unchanged.
682 *
683 * To avoid inadvertently changing fields of the attribute, it is
684 * recommended that {@link getAttribute} be used to
685 * retrieve the current value of the attribute, before calling this
686 * method with the required changes.
687 *
688 * ``[ HTTP: PUT /api/v1/inst/{instid}/{attrid} ]``
689 *
690 * @param string $instid [required] The ID of the institution.
691 * @param int $attrid [required] The ID of the attribute to update.
692 * @param IbisAttribute $attr [required] The new attribute values to apply.
693 * @param string $commitComment [recommended] A short textual description of
694 * the change made (will be visible on the history tab in the web
695 * application).
696 *
697 * @return IbisAttribute The updated attribute.
698 */
699 public function updateAttribute($instid,
700 $attrid,
701 $attr,
702 $commitComment=null)
703 {
704 $pathParams = array("instid" => $instid,
705 "attrid" => $attrid);
706 $queryParams = array();
707 $formParams = array("attr" => $attr,
708 "commitComment" => $commitComment);
709 $result = $this->conn->invokeMethod("PUT",
710 'api/v1/inst/%1$s/%2$s',
711 $pathParams,
712 $queryParams,
713 $formParams);
714 if (isset($result->error))
715 throw new IbisException($result->error);
716 return $result->attribute;
717 }
718 }
719