FindSuid

NAME
    FindSuid - LUMP CGI XML API for finding a Structural Unit ID

DESCRIPTION
    The FindSuid CGI script permits LUMP Structural Units to be searched
    for. The type of the structural unit(s) and the type and value of a data
    element within it/them are specified and the script will then return an
    XML document listing the IDs of the matching Structural Units. 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
    *sutype* - Name of the Structural Unit Type that the resulting
    Structural Unit should be an instance of. Optional and can be repeated
    to limit the search down to multiple structural unit types.
    *datatype* - Name of a Data Type for the associated datavalue parameter.
    Required.
    *datavalue* - The value of a Data Element of the required Data Type to
    search for. Required.
    *parent_su_id* - ID of another Structural Unit this is the parent of
    this one. Optional.
    *deleted* - If set to 'Y' it indicates that the search should include
    items marked as deleted. The default if this parameter is not given is
    not to include such Structural Units. Optional.
    *substring* - If set to 'Y' it indicates that the search should include
    substrings in the value matches. The default is to match the entire
    value. Optional.
    *owner_username* or *owner_userid* - These username or ID of a
    particular user. These are mutually exclusive (if both a specified,
    owner_username takes precidence) and are used to determine SU ownership.
    *user_role* - The role that the user should have in returned SUs. For
    example we might be only interested in SUs where the user is the
    academic, rather than being library staff or department admin. This is
    an optional parameter - the default is to return all matching SUs
    irrespective of the role the user has with them.
    *modified_time* - A timestamp that is used to compare against the last
    update time of the SUs. Only SUs that have been modified since this time
    stamp will be returned. This is an optional parameter - the default is
    to return all matching SUs irrespective of last modification time.
    *parent_suids* - A comma separated list of structural unit IDs that
    specify the parent SUs. Only matched structural units that a parent in
    the supplied list will be returned. This is an optional parameter - the
    default is to return all matching SUs irrespective of their parent.

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
    "FindSuid?sutype=Module&datatype=Module%20Code&datavalue=08LBA100" might
    return

     <response>
      <returns>
       <su>
        <id>14887</id>
       </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.