Loughborough Online Reading List System
NAME SUOwner - LUMP CGI XML API to return a list of structural units that an individual owns. DESCRIPTION The SUOwner CGI script is designed to list Structural Units in a LUMP database that a particular user "owns" in some way. 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 *owner_username* - The username of a particular user. This is optional - if not specified *owner_userid* or the *username* parameter will be used. Can also be a comma separated list of usernames, which is useful if the *operation* is set to coeditors. *owner_userid* - The ID of a particular user. This is optional - if not specified *owner_username* or the *username* parameter will be used. *sutype* - The name of the structural unit type that we are interested in finding SUs from. This is a required parameter. *operation* - What we want to do. By default this is "maximal" which tries to find the most records that match all of the given owner usernames/ids. It can also be set to "coeditors" in which case it will find the structural units that the listed owner usernames/ids each have common editorship with the user running this script. *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. *last_update* - 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's contains the XML structure following this DTD fragment: <!ELEMENT returns (su+)> <!ELEMENT su (id|data)> <!ELEMENT id (#PCDATA)> <!ELEMENT data (name|value)> <!ELEMENT name (#PCDATA)> <!ELEMENT value (#PCDATA)> For example: <response> <returns> <su> <id>11</id> <data> <name>Module Code</name> <value>09LBC123</value> </data> <data> <name>Module Title</name> <value>Physco-dynamic Perambulation Through Libraries</value> </data> <data> <name>Module Tutor</name> <value>Dr I. Knowlittle</value> </data> </su> <su> <id>4332</id> <data> <name>Module Code</name> <value>09LBA346</value> </data> <data> <name>Module Title</name> <value>Gizmos and Grommets</value> </data> <data> <name>Module Tutor</name> <value>Dr I. Knowlittle</value> </data> </su> </returns> <session> <security_hash>1248086710:a615619fd3d278c8a15154afade9ccec</security_hash> <lump_version>1</lump_version> <acting_as></acting_as> </session> <error> <error_message>Success</error_message> <error_code>SUCCESS</error_code> </error> </response> The <error> section contains SUCCESS in the <error_code> if the operation finishes successfully, or a failure error code if it doesn't. The <error_message> element contains a human readable message that can be used to inform the user of problems if desired. SEE ALSO FindSuid GetStructuralUnit ListSUs LUMP-XML-Response COPYRIGHT Copyright 2009 Loughborough University Library <email@example.com>. 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.