ANGEL Messaging Specification

Version:

0.16, revision of RM requests to fit in with new schemas; created XHTML compliant version of document; addition of documentation and requests for bibliographic database (4.10); update resource element to match RM database changes; update references to DTDs to refer to schemas; fixing errors in anchor tags left by transformation to XHTML, added copyright notice

Date:

01 August 2003

Document History:

0.15, 7 March 2003, update remote search request/response to fit with development (5.1, 5.2); update list requests to RM to allow filtering to items with matching resources only; add new list requests to get media types, suppliers and ip_ranges (4.3-4.5), merged listAvailableRequest and getAvailableRequest; added links to DTDs

0.14, 19 July 2002, update resource requests, replacing several with a simple search by resource ID, adding requester IP address where missing, add getResourceList request (4.2); specify XQuery support level (7.2.2); update introduction to discussion of RM (4); update resource element (7.3) (make availability description more sophisticated, make resource_type element consistent with subject element)

0.13, 15 June 2002, updates from second round of demonstrator software; updates to bibliography; links to more DTDs; fixing errors; detail added for administrative resource manager requests (4.11-4.13); creating separate section for resource element (7.3), and updating resource element description

0.12, 16 November 2001, updates from first round of demonstrator software, mainly section 4.14; updates to bibliography; links to initial DTDs

0.11, first HTML version (small typo fixes)

0.1, 25 July 2001, first public version

0.06, 20 July 2001, final draft version

0.05 14 July 2001

0.04 7 July 2001, updated to include draft example messages

0.03 30 June 2001

0.02 16 June 2001

Related documents:

John Paschoud, ANGEL Conceptual Model Design, Deliverable 4.1

Copyright: © London School of Economics, 2001-2003

Table of Contents

1 Angel Architecture and Implementation

1.1 Architecture

1.2 Implementation

1.3 Logging

1.3.1 Log entry specification

1.3.2 Example log entry

1.4 Referrals

2 Messages between server broker and UM - Authentication

2.1 Definition of Groups

2.2 Logon Request

2.2.1 Example Logon Request - with password

2.2.2 Example Logon Request - with certificate

2.3 Logon Response

2.3.1 User Data (eduPerson element)

2.3.2 Course Information (imslip element)

2.3.3 Example Logon Response

2.4 User login time request

3 Messages between the server broker and RM - Authorisation

3.1 Authorisation Scenario

3.2 Authorisation Request

3.2.1 Example Authorisation Request

3.3 Response to Authorisation Request

3.3.1 Example Authorisation Response

4 Messages between the server broker and RM - resource information

4.1 Subject List Request

4.1.1 Example getSubjectList Request

4.2 Resource Type List Request

4.2.1 Example getResourceTypeList Request

4.3 Check Resource Availability Request

4.3.1 Example getAvailability Request

4.4 Search Resource Database Request

4.4.1 Example localSearch Request

4.5 Search Remote Resource Request

4.5.1 Example Search Request

4.6 Search for Resources Like This One Request

4.6.1 Example Search For Like Request

4.7 Create Resource Request

4.7.1 Example Create Resource Request

4.8 Edit Resource Request

4.8.1 Example Edit Resource Request

4.9 Delete Resource Request

4.9.1 Delete Resource Request

4.10 Create New Bibliographic Record Request

4.10.1 Example Create New Bibliographic Record Request

4.11 Resource Response

5 Messages between RM and client broker

5.1 Search request

5.1.1 Example Search request

5.2 Search response

5.2.1 Example Search Response

6 Other request/response pairs

6.1 Version Request

6.1.1 Example Version Request

6.2 Version Response

6.2.1 Example Version Response

7 Shared Message Elements

7.1 Diagnostic

7.1.1 Example Diagnostics

7.2 Search Query

7.2.1 Example Search Query

7.2.2 XQuery Support Level

7.2.3 Sample XQuery Strings

7.3 Resource

7.3.1 Example Resource Element

Appendices

A.1 Schema and Namespace References for XML Messages

Footnotes

References

1 Angel Architecture and Implementation

1.1 Architecture

These will communicate with brokers which redirect - and encrypt if necessary - the communication to and from the major components. This communication will use the protocol "XRR", which is a (yet to be defined, and properly named) XML-based request & response protocol [XML], used for internal communication between the service modules and the interface brokers, and also available to external ITE ("Interface To Everything") applications, or to enable inter-operation between two or more ANGEL systems. XRR will be based on the (well-defined) Xrep [DECOMATE] protocol that was designed for implementation of the Decomate2 system. XRR may be used internally between the components of a single ANGEL service in an 'unwrapped' form, and also made available for external applications in a 'wrapped' form, compliant with the SOAP [SOAP] Webservices architecture.

Knowledge about users and resources should be kept as separate as possible, to allow for institutions which want to use just the resource or user portions of ANGEL. This will also result in logically more consistent systems, and make it easier for third party systems to interoperate with ANGEL components. There will be three major internal components. The Resource Manager (RM) will manage communication with the resource database and organise authorisation for users to connect to external services. The Scheduled Services Manager (SSM) will manage pro-active services such as current awareness and resource database link checking. The User Manager (UM) will authenticate the user with institutional services.

Each component has at least one associated database. The Resource Manager has two databases, one containing collection level descriptions of resources, and the other used to store individual bibliographic records (intended to be used to store records from searches which are then accessible by other applications such as reading list management software).

The purpose of this document is to describe the messages between the brokers and these internal components, and will be maintained and updated throughout the lifetime of the project.

1.2 Implementation

Each major ANGEL component will be a socket which can be queried in a standardised XML syntax with a published schema [XMLSchema] for each major message type. These schemas will be independent to aid third party developers in interaction with the components involved, and are in Appendix A.1. Queries and responses will be encrypted using SSL, and certificates will be verified to ensure that only permitted services will talk to each other. (Early prototypes will use clear text messages entirely and will merely check the IP address from which the message has come against a list of authorised clients. Running without using SSL will probably always have to be a configuration option for institutions unwilling to take on the administrative overhead involved in the use of certificates.) This may slow things down, but it will mean that the interface is easier to set up and allow development to take place in different locations. The ANGEL components will not communicate directly with each other; all messages must be designed to pass via a broker (this is to make re-use of the components in other contexts easier). However, the components will respond to messages which are not from a broker to facilitate reuse, provided they receive a certificate which authorises the communication (or the communication comes from a registered IP address in early prototypes). In this case, SOAP should be used to encapsulate the messages.

This document will not specify the requests made by the SSM, since these will be identical to external messages made to the broker. However, it does detail requests made to the SSM to administer its database.

Like HTTP, each response from any of these components will include a status, which is "OK" for successful processing of the request and which will otherwise be one (or more) of a series of defined error messages. See Section 7.1 for a detailed description of diagnostic message format. Also like HTTP (1.0), the communications will consist of a single request/response pair, after which the connection will need to be remade [HTTP]. (HTTP 1.1 does make provision for session maintenance, but this is little used in practice, with cookies being the preferred mechanism for this task.)

Because ANGEL is acting as middleware, and different front ends may make use of only some components, enforcing any kind of session on the requests/responses is not appropriate; session control should be left up to the software which is using ANGEL. Thus no provision is made for sessions in the messages described in this document.

Capitalisation in XML tags

Since XML tags are case sensitive, a decision needs to be made about what convention to be used for the tags. The convention used in this document is that each word in the node is capitalised with the exception of the first. This convention is enforced by the message schemas (see Appendix A.1).

1.3 Logging

1.3.1 Log entry specification

1.3.2 Example log entry

<logEntry>

 <requestTime>120329</requestTime>

 <requestDate>20020407</requestDate>

 <requesterIP>192.145.243.39</requesterIP>

 <logLevel>error</logLevel>

 <request>

  <logonRequest>

   <ipAddress>192.145.243.191</ipAddress>

  </logonRequest>

 </request>

 <response>

  <logonResponse>

   <diagnostic>

    <diagCode>1001</diagCode>

    <diagType>fatal</diagType>

    <diagString>Required field missing</diagString>

    <diagAddInfo>userId or certificate required in logonRequest</diagAddInfo>

   </diagnostic>

  </logonResponse>

 </response>

</logEntry>

1.4 Referrals

2 Messages between server broker and UM - Authentication

To authenticate a user, a logonRequest message is sent by the ANGEL client broker to the UM. The UM responds with a success/failure message and, if successful, directory information about the user and a list of groups describing the entitlements of the user. This information is obtained from one of a list of institutional authentication and directory services listed in the UM configuration file. The list of groups is a necessary part of the response, as it describes the user's entitlements and will be used for authorisation (see Section 2.1). No other request/response is needed. The SSM will need to obtain user data without authentication for authorisation purposes, something which needs to be carefully controlled.

For some of the ANGEL applications, we want to know as much as we can about which courses a student is taking, or which courses a lecturer is teaching. We might want to ask the user to self select this sort of information, as is currently done in the PIE, if it cannot be obtained from institutional sources accessible to the UM. This would require a mechanism to ask whatever interface is communicating with the user to obtain the further information which is needed for carrying out particular actions; the interface may already have this information (if, for example, it is an MLE that the user wants to carry out an action which needs course details) or it can ask the user to supply it for it to be transferred to the ANGEL broker. The obvious mechanism to do this is to use a diagnostic message to say to the interface that a required field from the request message is missing, and then have the interface to re-submit the request with more information. This could then all be carried out without adding further messages to the specification.

There are also privacy issues to be considered when dealing with directory information. At the moment, for example, Athens does not return personal details about authenticated users to services; a decision presumably prompted by concerns about passing on details such as email addresses to commercial organisations in particular. It becomes of great importance to ensure that directory information is not passed on to third party services without proper safeguards. This concern has also been recognised by PAPI [PAPI] and Shibboleth [SHIBBOLETH]; the specification of the latter allows institutions to filter which pieces of user information are passed on to individual third parties. At the very least, there would need to be configuration options to filter which services could obtain directory information from the ANGEL.

The UM will record the last login time and date, and will be able to tell a client this data. Its database will also include information about the user from the logon response message.

2.1 Definition of Groups

2.2 Logon Request

2.2.1 Example Logon Request - with password

<logonRequest>

 <userID>jsmith</userid>

 <password>easytoguess</password>

 <requesterIP>149.245.231.242</requesterIP>

 <requestSource>user</requestSource>

</logonRequest>

2.2.2 Example Logon Request - with certificate

<logonRequest>

 <certificate>o98s745go$GTuelde984jde845oe948*O&(P&(GBLK

rlvupH$"(*N£()*

...</certificate>

 <requesterIP>149.245.231.242</requesterIP>

 <requestSource>user</requestSource>

</logonRequest>

2.3 Logon Response

Course information may be part of later versions of the eduPerson schema used in this message. For the meantime, this data should be expressed within ANGEL using the a subset of the Learner Information Package Information Model [IMSLIP], to be defined later. Since a large part of this model overlaps with aims of eduPerson, it will be necessary to provide an XSLT transformation in the broker to move from one format to the other (though it should be borne in mind that the IMS information is far more comprehensive). A XSLT transformation will also be written to transform this message into one compatible with that produced by earlier versions of this software produced for the Decomate and HeadLine projects.

2.3.1 User Data (eduPerson element)

This will be the eduPerson [EDUPERSON] schema version 1.0, expressed using XML rather than the directory format specified in the standard. The majority of eduPerson fields are optional, and many of them contain data which will probably not be passed to external systems for privacy reasons. The personal data contained in eduPerson is separated from the non-eduPerson fields so that compatibility can be maintained with any official DTD produced by the eduPerson consortium. Some fields are made required when the schema doesn't require them to be, as footnoted.

2.3.2 Course Information (imslip element)

2.3.3 Example Logon Response

<logonResponse>

 <group>all</group>

 <group>lse</group>

 <group>ac.uk</group>

 <group>staff</group>

 <group>economics</group>

 <eduPerson>

  <cn>Joanna Smith</cn>

  <initials>J</initials>

  <sn>Smith</sn>

  <eduPersonPrincipalName>jsmith24@ed.ac.uk</eduPersonPrincipalName>

  <eduPersonOrgDn>cn=University of Edinburgh, c=UK</eduPersonOrgDn>

  <ou>Department of Cultural Studies</ou>

  <eduPersonOrgUnitDn>cn=Department of Cultural Studies,

 cn=University of Edinburgh, c=UK</eduPesronOrgUnitDn>

  <eduPersonAffiliation>staff</eduPersonAffiliation>

  <eduPersonAffiliation>employee</eduPersonAffiliation>

  <mail>jsmith24@ed.ac.uk</mail>

 </eduPerson>

 <imslip>TBD

 </imslip>

 <diagnostic>

  <diagnosticCode>2000</diagnosticCode>

  <diagnosticString>OK</diagnosticString>

 </diagnostic>

 <dirsource>lseexchange</dirsource>

 <authsource>lsesmb</authsource>

</logonResponse>

2.4 User login time request

3 Messages between the server broker and RM - Authorisation

3.1 Authorisation Scenario

Authorisation is performed on a "just in time" basis, when the user requests access to a resource. (The RM will also be able to return information about which resources a user can access for purposes such as displaying lists of resources; this is requested using the kind of functional call detailed in Section 4.) When a user wants to access a resource, the broker passes a request to the RM which works out, from the list of groups, whether and how the user can be authorised to access the resource, and returns the necessary data (e.g. the contents of a cookie to be passed to the resource).

This architecture is related that used by PAPI [PAPI], which returns to the Web browser a set of temporary authentication credentials as cookies for each resource that the use can access when that user first authenticates. This avoids the problem which occurs because the HTTP protocol is not designed to use authentication data which originates with a third party (neither the user nor the resource). For the purposes of ANGEL, this architecture will be modified slightly. Instead of returning a large number of cookies on authentication, authorisation will be provided as needed, with a single cookie returned for access to a particular resource. This will not necessarily be the only authorisation method supported, so the authorisation response will have the flexibility to return other credentials for resource access.

The UM will also need to be able to function as the institutional parts of the Shibboleth architecture [SHIBBOLETH] - the Handle Service and an Attribute Authority. It is expected that the description of these and the authentication messages is likely to be unstable as the PAPI and Shibboleth models develop during the lifetime of the ANGEL project.

3.2 Authorisation Request

3.2.1 Example Authorisation Request

<authRequest>

 <resource_id>3290357</resource_id>

 <requesterIP>192.192.234.34</requesterIP>

 <group>all</group>

 <group>lse</group>

 <group>ac.uk</group>

 <group>staff</group>

 <group>economics</group>

</authRequest>

3.3 Response to Authorisation Request

3.3.1 Example Authorisation Response

<authResponse>

 <diagnostic>

  <diagnosticCode>2000</diagnosticCode>

  <diagnosticString>OK</diagnosticString>

 </diagnostic>

 <authorisedURL>http://megaresource.com:8080/papi-users/

 </authorisedURL>

 <tokenContents>

  <name>PAPI=sel*L)£%^(*"!``ou 092w^3 

   ...</name>

  <expires>Fri, 13-Jul-2001 12:01:00 GMT</expires>

  <path>papi-users</path>

  <domain>megaresource.com:8080</domain>

  <secure>secure</secure>

 </tokenContents>

</authResponse>

4 Messages between the server broker and RM - resource information

The RM acts as the buffer between the outside world and the resource database. This database is based on that constructed to describe hybrid library resources included in the HeadLine PIE [HEADLINE]. The purpose of this buffer is to make it possible to write a client to access the database without needing to understand its structure (particularly when changes are made to it) or configuring a database manager to permit access to the database itself, and to prevent erroneous accesses to the data which may compromise other client applications. The most important aspect of the structure of the database which is likely to affect client applications is that each resource has a number of locations connected to it; these are best characterised as different ways to get at essentially the same data.

The entitlements for a user to access a resource in the database are determined as follows. On authentication with the UM, a user is given a collection of groups to which they belong. Each location in the RM has an entry which lists the rights which specific groups have over it. These may be varied depending on the purpose of the database, but are likely to have values like "access", "borrow" and so on. The user is assumed to have all the rights which any group that they belong to is listed as having (so if none of the groups have entries for that location, the user has no rights at all over it). In addition, there is the ability to match the user's IP address against an IP network permitted to access the location; this is a simple boolean and if the user is not in the network, they lose their rights over the location. (Here, not having an entry is equivalent to a user being able to access the resource from anywhere.) It is also possible for an administrator to mark a location as unavailable, at which point no user can access it; this is useful if (for example) a location has a planned downtime but after that the previous arrangements for access will be re-instated.

For many of the requests which might be made of an RM, it is possible to frame them as searches using XML Query Language [[XMLQL]]. For certain types of request, ones which are basically searches of the information in the database, this is the format which is used. There are other queries which it is not possible to use this language for (editing requests, for example), and some where it is much simpler to define a specific request to obtain the information (to get a list of subject terms used in the database, for example). This is especially the case as it is not envisaged that the whole of the query language will be supported by the RM (see section7.2.2).

The RM database will not generally permit the deletion of resource descriptions, instead marking a resource or location as "deleted". Some requests will permit the retrieval of deleted records, so that editing may be made simpler and so that functions such as log analysis can be carried out after resources to which they need to refer cease to be accessible.

The RM will support at least the resource database functions used by the HeadLine PIE:

• Get subject list (section 4.1). This will return a list of the subject terms and IDs in the database.
• Get list of resource types (section 4.2). This will return a list of the resource types (used to describe the content of the resource, e.g. "newspaper", "statistical dataset", etc.) and IDs in the database. Note that the RDM distinguishes between this and "media type" such as "CDROM", "WWW", etc.
• Get resource description (implemented as a search for a specific resource ID - see section 4.4). This will return several descriptive fields.
• Get help about resource (URL with help information) (implemented as a search for a specific resource ID - see section 4.4)
• Get information about resource locations (implemented as a search for a specific resource ID - see section 4.4)
• Get URL for logo graphic for resource (implemented as a search for a specific resource ID - see section 4.4)
• Get list of searchable resources (implemented as a search)
• Get resource name (implemented as a search for a specific resource ID - see section 4.4)
• Get training information for resource (implemented as a search for a specific resource ID - see section 4.4)
• Check resource availability (section 4.3)
• Search resource database (section 4.4)
• Search resource (section 4.5). The query here would use, for example, the standard set of fields from the type of resource involved, and would be translated by the RM to a query to pass on to the client broker as described in Section 5.1.

Additional functions which are supported include:

• List resources available to specific set of groups (implemented as a search)
• Search for resources like a specified one (section 4.6)
• Get list of available resources (section 4.3)
• Create resource (section 4.7)
• Edit resource details to those specified (section 4.8)
• Delete resource (section 4.9)
• Create bibliographic record (section 4.10)

These administrative functions will require more detailed definitions so that the complexities of the resource database can be as smoothed out as will be needed for external applications to use them. These functions will also need to be restricted to requests from specific addresses (note: this means where the request came from, not the user IP where it originated, and is most likely to be a machine on which a CGI/servelet application resides which can be accessed by administrators). Access from localhost (127.0.0.1) will always be permitted.

4.1 Subject List Request

The database structure described in [HEADLINE] adopted as the basis for the Angel resource database has the option to include a controlled list of subject headings to be used to classify the resources. Thus applications which offer a front end to the resource manager are going to need to get a list of these subjects (which have principal fields subject_id and term - where they come from a controlled list information about their source should also be available if necessary). The returned list will be sorted alphabetically by term.

4.1.1 Example getSubjectList Request

<?xml version="1.0"?>
<getSubjectList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
 <requesterIP>123.123.123.123</requesterIP>
</getSubjectList>

4.2 Resource Type List Request

4.2.1 Example getResourceTypeList Request

<?xml version="1.0"?>
<getResourceTypeList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
 <requesterIP>123.123.123.123</requesterIP>
</getResourceTypeList>

4.3 Check Resource Availability Request

4.3.1 Example getAvailability Request

<?xml version="1.0"?>
<getAvailabilityRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

	xmlns="http://www.angel.ac.uk/rm_request"

	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">

 <requesterIP>123.123.123.123</requesterIP>

 <group>test</group>

 <group>fake</group>

 <right>elephant</right>

 <right>second</right>

</getAvailabilityRequest>

4.4 Search Resource Database Request

4.4.1 Example localSearch Request

<?xml version="1.0"?>
<localSearchRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
	search_type="collection"
	response_type="full"
  <requesterIP filter="N">123.23.53.35</requesterIP>
  <aq:query>
   <aq:queryString//resource[admin@ad_create_time > "20020614"] sortby(name)>/ar:queryString>
   <aq:maxResults>50</ar:maxResults>
   <aq:firstResultNo>251</ar:firstResultNo>
  </aq:query>
  <group>staff</group>
  <group>economics</group>
 </localSearchRequest>
</resourceRequest>

4.5 Search Remote Resource Request

The query here would be translated by the RM to a query to pass on to the client broker as described in Section 5.1. Since at this point there may not be information about the resource available to the requester, it will be necessary to use a standardised set of field names (based initially on BIB1) for complex searches, translating them from those used by the client service where necessary. This will be done by a separate RM service.

Where the resource ID is not specified in the request, the RM will use the database and the type of request to work out which resource(s) to search. This will be done by categorising the search queries understood by the RM, and then having a database structure which explains how to translate each possible query into one which the remote resource can understand, omitting those which are not appropriate. Thus, queries dealing with people will be listed in database entries for resources like student record systems, while bibliographic queries will be listed for library catalogues. Additional configuration may be needed to resolve unwanted overlap (e.g. between different student record systems which happen to use the same ID for different students), though it would be expected that most conflicts should be sorted out by including a resource ID in the request. Only resources which are available to the requester IP address in the list of specified groups will be searched.

When the RM database is included in a search, the bibliographic item will be used, unless the search type is "collection", in which case the main database is searched.

4.5.1 Example Search Request

<?xml version="1.0"?>
<localSearchRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <requesterIP filter="N">123.123.123.123</requesterIP>
  <aq:query xmlns:aq="http://www.angel.ac.uk/rm_query"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_query http://www.angel.ac.uk/schemas/rm_query.xsd">
    <aq:queryString>//resource[xf::starts-with(xf::lower-case(//name),xf::lower-case("A"))] sortby(@resource_id)</aq:queryString>
    <aq:maxResults>50</aq:maxResults>
  </aq:query>
</localSearchRequest>

4.6 Search for Resources Like This One Request

4.6.1 Example Search For Like Request

<?xml version="1.0"?>
<searchForLikeRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <requesterIP filter="N">123.123.123.123</requesterIP>
  <resourceID>13277</resourceID>
 
  <group>staff</group>
  <group>economics</group>
</searchForLikeRequest>

4.7 Create Resource Request

4.7.1 Example Create Resource Request

<?xml version="1.0"?>
<createRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <ar:resource xmlns:ar="http://www.angel.ac.uk/rm_respource"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_resource http://www.angel.ac.uk/schemas/rm_resource.xsd">
    <ar:admin manager_persid="s.mcleish@lse.ac.uk" creator_persid="m.mouse@disney.com" />
    <ar:summary>A test resource with no real existence.</ar:summary>
    <ar:resource_type>
      <ar:name>CD</ar:name>
    </ar:resource_type>
    <ar:name>Test Resource</ar:name>
    <ar:location url="http://www.test.com"  search_protocol="none" available="Y">
      <ar:group_right access_right="read" group="lse.ac.uk" />
      <ar:comment>On decomate</ar:comment>
      <ar:availability_message>Requires Athens user name and password</ar:availability_message>
      <ar:name>Decomate</ar:name>
      <ar:licensee_inst domain="lse.ac.uk">
        <ar:name>London School of Economics</ar:name>
      </ar:licensee_inst>
    </ar:location>
    <ar:keyword>
      <ar:keyword_phrase>elephant</ar:keyword_phrase>
    </ar:keyword>
    <ar:keyword>
      <ar:keyword_phrase>test</ar:keyword_phrase>
    </ar:keyword>
  </ar:resource>
  <requesterIP>123.123.123.123</requesterIP>
</createRequest>

4.8 Edit Resource Request

The RM will edit a resource in the following way. It will delete the existing resource information, and then create a new resource with the resource_id set by the request rather than generated automatically as it is in a create request (Section 4.7). While the process is being carried out, the RM will create a lock file to indicate that the specific resource ID is not available for re-use. This may fail if multiple RMs are used to manage a single database, but it is not envisaged that the Angel system would be used in this way.

The resource element is repeatable to allow batch editing - for example, a client program could retrieve all the resources with a URL matching an expression such as http://www.publisher.com/*, and then change all of these URLs to another, if publisher.com has now moved to another address.

4.8.1 Example Edit Resource Request

<?xml version="1.0"?>
<editRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <requesterIP>123.123.123.123</requesterIP>
  <ar:resource xmlns:ar="http://www.angel.ac.uk/rm_resource"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_resource http://www.angel.ac.uk/schemas/rm_resource.xsd"
	resource_id="3">
    <ar:name>Test Resource - after editing</ar:name>
    <ar:summary>A test resource with no real existence, that has now been edited.</ar:summary>
    <ar:location url="http://www.test2.com"  search_protocol="none" available="Y">
      <ar:group_right access_right="read" group="lse.ac.uk" />
      <ar:comment>On decomate</ar:comment>
      <ar:availability_message>Requires Athens user name and password</ar:availability_message>
      <ar:name>Decomate</ar:name>
      <ar:licensee_inst domain="lse.ac.uk">
        <ar:name>London School of Economics</ar:name>
      </ar:licensee_inst>
    </ar:location>
    <ar:resource_type>
      <ar:name>Almond</ar:name>
    </ar:resource_type>
    <ar:keyword>
      <ar:keyword_phrase>turnip</ar:keyword_phrase>
    </ar:keyword>
    <ar:keyword>
      <ar:keyword_phrase>test</ar:keyword_phrase>
    </ar:keyword>
    <ar:icon alt_text="Test Inc." url="http://www.test.com/test.jpg" />
    <ar:admin manager_persid="s.mcleish@lse.ac.uk" creator_persid="m.mouse@disney.com" />
  </ar:resource>
</editRequest>

4.9 Delete Resource Request

4.9.1 Example Delete Request

<?xml version="1.0"?>
<deleteRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <requesterIP>123.123.123.123</requesterIP>
  <resourceID>3</resourceID>
</deleteRequest>

4.10 Create New Bibliographic Record Request

4.10.1 Example Create New Bibliographic Record Request

<createBibItemRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_request"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_request http://www.angel.ac.uk/schemas/rm_request.xsd">
  <bib1 field="4">ANGEL IMS Query Demonstrator</bib1>
  <bib1 field="60">no comment</bib1>
  <bib1 field="1032">http://soar.dmu.ac.uk:5555/angel-demo/index.html</bib1>
</createBibItemRequest>

4.11 Resource Response

The responses need to be flexible, but only to a certain point, since the underlying data model is likely to change quite slowly. The possible responses are likely to include data about resources, locations,... (list to be finalised when RM data structure finalised) and the resourceResponse will inherit the structure of an RDF description of the resource database, using a resource element described in Section 7.3.

Information about the resource database itself, such as the listing of subject headings, will be given as though information about resource ID 0, which is reserved in the database for this purpose.

In several of the requests, it is possible to request that the results be filtered by availability to the end user. This is done by returning only those resources which have available locations. Where the filter attribute of the requesterIP node is not set to "Y", all appropriate resources are returned with the available attribute set to "Y" or "N" as necessary. (This is so that applications can be set to display resources "greyed out" where not available rather than denying the user information about their existence entirely.)

Resources returned will be ordered alphabetically by name unless the queryString specifies otherwise.

5 Messages between RM and client broker

These requests are used to obtain information from third party resources which can then be passed back to the server broker. The requests will be triggered by the appropriate client request to the server broker as detailed in Section4.

Like the RM requests, a container tag resourceClientRequest is put around the individual client broker requests; this has a required attribute for the namespace for the query.

5.1 Search request

This request/response pair is used to order the client broker to carry out a search of some third party resource. ANGEL will need a mechanism to specify searches of a variety of different kinds of resource metadata. This will use a search string which is compatible with the XML-Query Language [XMLQL]. This is a search language designed to pull out information from XML documents of known structure, and could easily be used to describe searches of any data which is organised into fields. It also allows the return format to be specified and so can be used to translate fields from a standard list to that used by the resource in question and back again (this will be used to mould the results into the correct format for the search response). It can be used to specify searches for MLEs where objects are described with the IMS Learning Content Packaging Specification [IMSCP] as well as bibliographic searches using Z39.50 and access to Web search engines. The request must also include info about where and how to search e.g. Z39.50, server name and port no, authentication details.

Of the alternatives, even in the most recent development revision of the Z39.50 bibliographic searching protocol, there is no public plan to creating an XML version [Z3950REV], and we probably don't want to implement the full complexity of Z39.50 anyway. (There are proposals to create such a version of Z39.50 [Z3950NG].) There is also a search metadata XML specification which we could adapt [POWELL]; it is designed to make simultaneous searching of multiple Web search engines in different languages and formats possible, and we will probably require something more sophisticated. (Web search engines could be described in the resource database using this specification.) We might well adopt those parts of this scheme which are about language translation.

Note that some functionality specifiable in search requests may not be available from some resources (e.g. maxResults and firstResult).

5.1.1 Example Search request

<?xml version="1.0" encoding="UTF-8"?>
<searchRequest xmlns="http://www.angel.ac.uk/rm_client_request" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.angel.ac.uk/rm_client_request http://www.angel.ac.uk/schemas/rm_client_request.xsd">
  <remoteSearch>
    <remoteURL>http://resolver.ukoln.ac.uk/openresolver/</remoteURL>
    <protocol>openurl</protocol>
  </remoteSearch>
  <requesterIP filter="N">123.123.123.123</requesterIP>
  <aq:query xmlns:aq="http://www.angel.ac.uk/rm_query" xsi:schemaLocation="http://www.angel.ac.uk/rm_query http://www.angel.ac.uk/schemas/rm_query.xsd">
    <aq:queryString>(((((((((((((((((((((((((//request/result/1004 = "Lorcan Dempsey")) AND (//request/result/openurl-resolver = "openurl"))) AND (//request/result/openurl-sid = "angel:1100"))) AND (//request/result/1034 = "article"))) AND (//request/result/openurl-id = "doi:10.1045/december99-dempsey"))) AND (//request/result/4 = "International Information Gateway Collaboration: report of the first IMesh Framework Workshop"))) AND (//request/result/5 = "D-Lib Magazine"))) AND (//request/result/8 = "1082-9873"))) AND (//request/result/31 = "1999-12"))) AND (//request/result/openurl-volume = "5"))) AND (//request/result/openurl-artnum = "12"))) AND (//request/result/openurl-aulast = "Dempsey"))) AND (//request/result/openurl-aufirst = "Lorcan"))</aq:queryString>
  </aq:query>
  <parameter name="location_id">1101</parameter>
  <parameter name="stylesheet">openurl2extsearchres.xsl</parameter>
  <parameter name="version">1.0</parameter>
  <parameter name="sid">ukoln:</parameter>
</searchRequest>

5.2 Search response

To formulate the search response, we need a standardised set of fields to describe the sort of resources indexed by the kind of resources we plan to search. This will be different from the resource information stored in the database, since it is describing information on a different level - the search response will describe things like journal articles rather than collections. We also need to cater for the possibility that some resources will describe unexpected types of information to allow flexibility in the sort of resources that can be described in the resource database. On the assumption that most of the information that will be returned is going to be bibliographical, a good way to do this is to use as default the BIB-1 fields which can be returned by most Z39.50 targets [BIB1], including those which are Bath Profile compliant [BATH], or possibly the more complex US-MARC fields - see for example [MEDLANE]. Note that XML tagnames cannot be digital only ([XML]), so that the field names from BIB-1 cannot be carried forward to form XML tags without some modification. Other than bibliographical data, the majority of search targets are likely to be MLEs, so that it will be necessary to retrieve information more suited to the IMS Content Packaging Specification [IMSCP]. Where searches return information not catered for by this sort of structure (such as a relevance ranking), this will be included by using a more generic "other field" structure. Relevance ranking will be assumed to be a series of values which decrease as the result becomes less relevant; a transformation will be used to change this if needed.

In the search response message, the diagnostic can be used to pass on information about the communication with the resource, if necessary.

5.2.1 Example Search Response

<searchResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_client_response"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_client_response http://www.angel.ac.uk/schemas/rm_client_response.xsd">
 <ad:diagnostic xmlns:ad="http://www.angel.ac.uk/diagnostic"
 	xsi:schemaLocation="http://www.angel.ac.uk/diagnostic http://www.angel.ac.uk/schemas/diagnostic.xsd">
  <ad:diagnosticCode>1000</ad:diagnosticCode>
  <ad:diagnosticString>OK</ad:diagnosticString>
 </ad:diagnostic>
 <result>
  <bib1 field="4">Safe as Milk</bib1>
  <bib1 field="1003">Don van Vliet</bib1>
  <otherField name="relevance"<98<</otherField>
 </result>
 ...
</searchResponse>

6 Other request/response pairs

These are likely to be useful for testing connections, making sure that services elsewhere are available and to ensure compatibility.

6.1 Version Request

6.1.1 Example Version Request

<versionRequest/>

6.2 Version Response

6.2.1 Example Version Response

<versionResponse>

 <socketName>UM</socketName>

 <socketVersion>1.01</socketVersion>

 <diagnostic>

  <diagnosticCode>2000</diagnosticCode>

  <diagnosticString>OK</diagnosticString>

 </diagnostic>

</versionResponse>

7 Shared Message Elements

7.1 Diagnostic

Diagnostic codes will consist of four digit numbers. The first number is a prefix identifying the ANGEL component producing the diagnostic - 1 for the UM, 2 for the RM, 3 for the SSM. The remaining three digits identify the diagnostic within each range - 1079 need not mean the same as 2079 - and will come from a list to be maintained and published by the project, to allow scope for developers to add new ones as needed. 000 in each case will be "OK", 001-499 will be fatal errors, 501-999 warnings. Warnings can be repeated and can appear with any other diagnostic, but must appear with an OK or fatal error. Only one OK or fatal error can appear in any response message. The ranges 401-499 and 901-999 will be reserved for "user defined errors" which can be defined by later developers working with the ANGEL components. For a list of current diagnostics, see the XML listing [DIAG] (also included in RM software release).

Both diagnosticType and diagnosticString can be derived from diagnosticCode, but are optionally included to improve interoperability and human readibility for debugging purposes.

Errors from external resources will be passed on, in an appropriate format, by the server broker to the originating client software.For example, the resource manager might well have an error code defined as "Z39.50 diagnostic" with the additional information containing the entire Z39.50 diagnostic message.

7.1.1 Example diagnostics

<ad:diagnostic xmlns:ad="http://www.angel.ac.uk/diagnostic"
 	xsi:schemaLocation="http://www.angel.ac.uk/diagnostic http://www.angel.ac.uk/schemas/diagnostic.xsd">
 <diagnosticCode>1000</diagnosticCode>
 <diagnosticString>OK</diagnosticString>
</diagnostic>

<ad:diagnostic xmlns:ad="http://www.angel.ac.uk/diagnostic"
 	xsi:schemaLocation="http://www.angel.ac.uk/diagnostic http://www.angel.ac.uk/schemas/diagnostic.xsd">
 <diagnosticCode>2079</diagnosticCode>
 <diagnosticString>Malformed message</diagnosticString>
 <diagnosticType>fatal</diagnosticType>
 <diagnosticAddInfo>Required element resourceId missing</diagnosticAddInfo>
</diagnostic>

<ad:diagnostic xmlns:ad="http://www.angel.ac.uk/diagnostic"
 	xsi:schemaLocation="http://www.angel.ac.uk/diagnostic http://www.angel.ac.uk/schemas/diagnostic.xsd">
 <diagnosticCode>2001</diagnosticCode>
 <diagnosticString>Z39.50 diagnostic</diagnosticString>
 <diagnosticType>fatal</diagnosticType>
 <diagnosticAddInfo>Cannot sort by abstract (ref. 207)
 </diagnosticAddInfo>
</diagnostic>

7.2 Search Query

This element is shared by the searchRequest and resourceRequest. The query itself is formatted in the XML query language XQuery [XMLQL].

7.2.1 Example search query

<query xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://www.angel.ac.uk/rm_query"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_query http://www.angel.ac.uk/schemas/rm_query.xsd">
 <queryString>//resource[subject/@term="Geography"]
 sortby(name)</queryString>
 <maxResults>50</maxResults>
 <firstResultNo>251</firstResultNo>
</query>

This particular query should return the resources which have subject term set to "Geography" (see below for more examples).

7.2.2 XQuery Support Level

7.2.3 Sample XQuery Strings

//resource[subject/@subject_id="21"] sortby(@resource_id)

//resource[subject/@term="Geography"] sortby(name)

//resource[xf::lower-case(keyword/keyword_phrase)=xf::lower-case("Philosophy")]
sortby(admin/@create_time)

//resource[xf::starts-with(xf::lower-case(//name),xf::lower-case("A"))]
sortby(@resource_id)

//resource[xf::contains(xf::lower-case(//summary),xf::lower-case("econom"))]
sortby(name)

//resource[@resource_id = "749"]

//resource[admin/@create_time > "20020614"] sortby(name)

//resource[(xf::starts-with(xf::lower-case(//name),xf::lower-case("A")))
and (subject/@term="Geography")] sortby(@resource_id)

7.3 Resource Element

The initial resource data structure was based on [HEADLINE]. The relationship of the XML to the structure of the database will be based on the rules suggested for this type of transformation in [WILLIAMS] (5). Not every available field will be returned for every request; some filtering will be done determined by the nature of the function requested (for example, a request for a list of searchable resources need only return the resource_ids of those which are searchable). Thus, it is envisaged that a standard response to all of the requests in Section 4 can be developed, with a filter being the only part needing customisation.

The one request for which the response will require information not contained in the resource database is the external resource search (see Section 4.6). This will be catered for by putting the result node as a child of the resource node. The diagnostic node will also be a child of the resource node, to cater for requests such as the search remote resource request which may return diagnostic information about several resources.

Example Resource Element

<ar:resource xmlns:ar="http://www.angel.ac.uk/rm_resource"
	xsi:schemaLocation="http://www.angel.ac.uk/rm_resource http://www.angel.ac.uk/schemas/rm_resource.xsd"
	resource_id="3">
    <ar:name>Test Resource - after editing</ar:name>
    <ar:summary>A test resource with no real existence, that has now been edited.</ar:summary>
    <ar:location url="http://www.test2.com"  search_protocol="none" available="Y">
      <ar:group_right access_right="read" group="lse.ac.uk" />
      <ar:comment>On decomate</ar:comment>
      <ar:availability_message>Requires Athens user name and password</ar:availability_message>
      <ar:name>Decomate</ar:name>
      <ar:licensee_inst domain="lse.ac.uk">
        <ar:name>London School of Economics</ar:name>
      </ar:licensee_inst>
    </ar:location>
    <ar:resource_type>
      <ar:name>Almond</ar:name>
    </ar:resource_type>
    <ar:keyword>
      <ar:keyword_phrase>turnip</ar:keyword_phrase>
    </ar:keyword>
    <ar:keyword>
      <ar:keyword_phrase>test</ar:keyword_phrase>
    </ar:keyword>
    <ar:icon alt_text="Test Inc." url="http://www.test.com/test.jpg" />
    <ar:admin manager_persid="s.mcleish@lse.ac.uk" creator_persid="m.mouse@disney.com" />
  </ar:resource>

(1) Special characters such as "~" must be encoded. (A labeled URI is one which contains a description separated from the URI itself by a space.)

(2) Not required in eduPerson specification, but will be needed for authorisation purposes.

(3) This list will need to be extended, by agreement with the eduPerson consortium. For full authorisation purposes, student will need to be divided into undergraduate, taught postgraduate, research postgraduate.

(4) While eduPerson allows this to be repeatable, it is likely that we will want to restrict it to a single value so that an email address can be used as a unique identifier.

(5) As well as the more important deviations from this method mentioned in the text, an admin element is also added to a the list; this is because the attributes it contains are applicable to several of the other elements and it is separated to avoid confusing repitition.

(6) This is not repeatable, even where the search protocol is one (like Z39.50) which allows parallel searching. To avoid problems with protocols where this is not possible, the RM will fork and make multiple requests where parallel searching is required. (This also means that where diagnostics about failed searches are passed back to the broker, it is not going to be necessary to indicate in the message which resource produced the error - see Section 7.1.) No mechanism is suggested for sorting the results of a search (though it can be specified in the query), and, in particular, no mechanism is currently suggested by which the RM can deduplicate results from multiple targets.

References

[BATH] The Bath Profile Editorial Team, An International Z39.50 Specification for Library Applications and Resource Discovery (http://www.nlc-bnc.ca/bath/bp-current.htm). Release 1.1, June 2000, updated Feb 2001
[BIB1] Z39.50 Maintenance Agency, Bib-1 Attribute Set, June 1998, last updated November 2001 (http://lcweb.loc.gov/z3950/agency/defns/bib1.html)
[COOKIE] Netscape Corporation, Persistent Client State HTTP Cookies Preliminary Specification, 1999 (http://www.netscape.com/newsref/std/cookie_spec.html)
[DECOMATE] John Paschoud and Simon McLeish, Technical Design: Access, Document Delivery & Accounting, Decomate II Project Deliverable 6.1 (http://www.bib.uab.es/project/eng/d61.html), Oct 1998
[DIAG] Angel diagnostic list in XML format, ( http://www.angel.ac.uk/public-filesdiaglist.xml), 2001-2003
[EDUPERSON] EDUCAUSE/Internet2 eduPerson Task Force, eduPerson Specification, Version 1.0 ( http://www.educause.edu/netatedu/groups/pki/eduperson/spec.pdf) released 12 Feb 2001. FAQ available at http://www.educause.edu/netatedu/groups/pki/eduperson/faq.pdf.
[HEADLINE] HeadLine Project resource data model structure diagram (http://www.headline.ac.uk/public/software/rdm-1.2.doc)
[HTTP] R. Fielding et al, Hyper Text Transfer Protocol Version 1.1 RFC 2616 ( http://www.cis.ohio-state.edu/Services/rfc/rfc-text/rfc2616.txt), T. Berners-Lee et al, Hyper Text Transfer Protocol Version 1.0 RFC 1945 ( http://www.cis.ohio-state.edu/Services/rfc/rfc-text/rfc1945.txt)
[IMSCP] IMS Global Learning Consortium Inc., Content Packaging Specification version 1.1.1, May 2001 (http://www.imsproject.org/content/packaging/index.html)
[IMSLIP] IMS Global Learning Consortium Inc., IMS Learner Information Packaging Information Model Specification Version 1.0, Mar 2001 (http://www.imsproject.org/profiles/lipinfo01.html)
[MEDLANE] Medlane Experiment - MARC to XML (http://xmlmarc.stanford.edu).
[PAPI] RedIris, The PAPI System (Point of Access to Information Providers) (http://www.rediris.es/app/papi/index.en.html - English version).
[POWELL] James Powell and Edward A. Fox, Multilingual Federated Searching Across Heterogeneous Collections, Dlib Magazine, Sept 1998 (http://www.dlib.org/dlib/september98/powell/09powell.html). For an implementation of this idea, see http://jin.dis.vt.edu/fedsearch/ and the DTD at http://www.xml.org/xml/schema/a9075010/searchdb-lite2.dtd.
[SHIBBOLETH] Marlena Erdos and Scott Cantor, Shibboleth Draft Architecture version 3, November 2001 ( http://middleware.internet2.edu/shibboleth/docs/draft-internet2-shibboleth-arch-v03.pdf). See also the main site (http://middleware.internet2.edu/shibboleth/).
[SOAP] Don Box et al, SOAP: Simple Object Access Protocol ( http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsoapsp/html/soapspec.asp), April 2000
[WILLIAMS] Kevin Williams et al, XML Structures for Existing Databases, from Professional XML Databases, Wrox Press, 2001 ( http://www-106.ibm.com/developerworks/library/x-struct/?dwzone=xml).
[XML] Tim Bray et al (eds), Extensible Markup Language (XML) Version 1.0, 2nd edition Oct 2000 (http://www.w3.org/TR/2000/REC-xml).
[XMLQL] Don Chamberlin et al (eds), XQuery 1.0: An XML Query Language (http://www.w3.org/TR/xquery). Version 1.0 released 7 June 2001, and is clearly work in progress.
[XMLSchema] XML Schema
Part 0: Primer (http://www.w3c.org/TR/xmlschema-0/), May 2001
Part 1: Structures (http://www.w3c.org/TR/xmlschema-1/), May 2001
Part 1: Datatypes (http://www.w3c.org/TR/xmlschema-2/), May 2001
[Z3950NG] Z39.50 Next Generation (http://www.loc.gov/z3950/agency/zng.html), early draft July 2001.
[Z3950REV] Z39.50 Maintenance Agency, Z39.50 Revision (Z39.50-2001) (http://lcweb.loc.gov/z3950/agency/revision/revision.html).