HierarchySearch

NAME
    HierarchySearch - LUMP CGI XML API for following the heirarchy up from
    one structural unit to the first structural unit above (or below) it of
    a give structural unit type.

DESCRIPTION
    The HierarchySearch CGI script permits

    These IDs can then be used with (for example) GetStructuralUnit to
    actually retrieve the Structural Units for further processing, display,
    etc.

PARAMETERS
  Standard
    *username* - Name of user running this CGI script. Required unless web
    server authentication is in use (when it is, the web server
    authenticated user is used instead).
    *password* - Password for the user. This is only required if the web
    server is not handling the user authentication and if no security hash
    parameter is being given.
    *security_hash* - An opaque value used to authenticate the user without
    requiring the password to be sent. This value is generated by a previous
    execution of a LUMP API script and may well be time limited. It is only
    required if no password or webserver authentication is done.
    *act_as* - Users in the SysAdmins group can elect to act on the behalf
    of other users once they are themselves authenticated. If this parameter
    is present it should contain the username of the user that should be
    switched to if this option is available and the real user has been
    authenticated successfully. Optional.
    *session_id* - An opaque string as far as the server is concerned that
    is intended solely to allow async clients to differentiate different
    results more easily. Optional.

  Specific for this script
    *su_id* - The ID of the structural unit from which the hierarchy search
    should commence. Required.
    *sut_id* - ID of the Structural Unit Type that we should be searching
    for an instance of.
    *sut_name* - Name of the Structural Unit Type that we should be
    searching for an instance of. One of either *sut_id* or *sut_name* are
    required. If both are given, *sut_name* is ignored.
    *direction* - Whether to search for parents or children. Valid values
    are 'parents' or 'children', and if this parameter is not specified it
    defaults to 'parents'.

RESULTS
    The script returns an XML document in the standard LUMP response format
    (as documented in LUMP-XML-Response). The <returns> section contains a
    list of the matching Structural Unit (<su> elements) each contain an ID
    (<id> element) if successful.

    For example, a call such as
    "HierarchySearch?suid=897&sut_name=Module&direction=parents" might
    return the following XML:

     <response>
      <returns>
       <su>
        <id>867</id>
        <su>
         <id>866</id>
         <su>
          <id>865</id>
         </su>
        </su>
       </su>
      </returns>
      <session>
       <security_hash>1247479361:3a2d93c40a11d1a1d7a4c39d80dea6cf</security_hash>
       <lump_version>1</lump_version>
       <acting_as>guest</acting_as>
      </session>
      <error>
      <error_message>Success</error_message>
       <error_code>SUCCESS</error_code>
      </error>
     </response>

SEE ALSO
    GetStructuralUnit

    LUMP-XML-Response

COPYRIGHT
    Copyright 2009 Loughborough University Library <library@lboro.ac.uk>.

    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.2 or
    any later version published by the Free Software Foundation; with no
    Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
    Texts.