Lookup/Ibis web service client API
  • Class

Classes

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

Interfaces

  • ClientConnection

Exceptions

  • IbisException
  1 <?php
  2 /* === AUTO-GENERATED - DO NOT EDIT === */
  3 
  4 /*
  5 Copyright (c) 2012, University of Cambridge Computing Service
  6 
  7 This file is part of the Lookup/Ibis client library.
  8 
  9 This library is free software: you can redistribute it and/or modify
 10 it under the terms of the GNU Lesser General Public License as published
 11 by the Free Software Foundation, either version 3 of the License, or
 12 (at your option) any later version.
 13 
 14 This library is distributed in the hope that it will be useful, but
 15 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 16 or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
 17 License for more details.
 18 
 19 You should have received a copy of the GNU Lesser General Public License
 20 along with this library.  If not, see <http://www.gnu.org/licenses/>.
 21 */
 22 
 23 require_once dirname(__FILE__) . "/../client/IbisException.php";
 24 
 25 /**
 26  * Methods for querying and manipulating 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 
Lookup/Ibis web service client API documentation generated by ApiGen