Intrallect development

From DigiRepWiki

Contents

Terms and Conditions

Note that the following information is released by Intrallect Ltd under the following licence: Attribution-Noncommercial-Share Alike 2.5 UK: Scotland. This differs from the default licence applied to the rest of this Wiki, in that it licenses this material for use only in non-commercial contexts, and the licence comes under the jurisdiction of Scottish law. All the following material remains the copyright of Intrallect Ltd 2007. Derivative works should retain this statement of terms and conditions, and include a prominent link to the Intrallect website, http:///www.intrallect.com.

Introduction

This page provides details about the Intrallect implementation of the SWORD interface in its Learning Object Repository system, intraLibrary. Each development story is referenced by ID and Title. There is a full list of acceptance tests for each story. Narrative descriptions of each story may be added later.

SM-225: Remote deposit by authenticated user

A remote user makes a deposit into a collection using the Atom Publishing Protocol (APP), after having been authenticated (SM-244). The group and collection are identified using the "href" attribute of the target collection, exposed in the APP service document (SM-243). The object is deposited in the context of the first-available process including the "upload" action, that the user has access in the target group's workflow.

Acceptance tests:

  1. the object is deposited into the target collection
  2. deposited object is owned by the target user group
  3. deposited object enters a stage in the target group's current workflow
  4. the workflow stage is the first one that includes a process that gives the authenticated user access to the "upload" action
  5. if the authenticated user does not have access to such a workflow process, the deposit fails, and a suitable HTTP error code is returned, e.g. 401 Unauthorized
  6. a successful deposit request results in the same behaviour as a successful upload request (i.e. file/package is imported)

SM-243: collection discovery using the Atom Publishing Protocol (APP)

A remote user, using a depositing client-application, explores the deposit entry-points available to them by requesting the service document defined by the Atom Publishing Protocol (APP), http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-16.html#appdocs,

To access this document, they must pass through an authentication challenge (SM-244). For each group in which the user has deposit (i.e. upload) access, a "workspace" is included in the document. The collections that the group has permission to contribute to are listed inside each workspace, for example:

 <workspace>
   <atom:title>HE Depositors Group</atom:title>
   <collection href="http://repository.jorum.ac.uk/atom/group5/collection1" >
     <atom:title>HE Academy Collection</atom:title>
     <accept>*/*</accept>
   </collection>
   <collection href="http://repository.jorum.ac.uk/atom/group5/collection2" >
     <atom:title>Photo Collection</atom:title>
     <accept>*/*</accept>
   </collection> 
 </workspace>

Acceptance tests:

  1. only groups in which the authenticated user has upload access are listed as workspaces
  2. only collections to which the authenticated user has upload access within the context of a group are listed inside the workspace for that group
  3. each workspace has a title which is the name of the group
  4. each collection has a "href" that can be used to identify it as a deposit target.
  5. collection hrefs do not have to resolve to a web page
  6. collection hrefs differ between the workspaces to identify user-group context
  7. the "categories" element and its descendants are not included in the service document
  8. if the user has upload access in no groups, no workspaces are listed
  9. if a group has contribute permission for no collections, a workspace is not included for that group


SM-281: mediated deposit using SWORD extension to APP

When an authenticated administrator-class or librarian-class user accesses the APP service document, each "collection" element listed in the APP service document contains the following extension element <sword:mediation>true</sword:mediation>. The client initiates a deposit request which includes the HTTP header "X-On-Behalf-Of=<a-user-name>". If the supplied username matches a known user, the attached file/package is added to the workflow as if the named user had deposited it themselves.

Acceptance tests:

  1. a depositing client authenticated as a administrator or librarian-class user is shown the extension <sword:mediation>true</sword:mediation> in every collection listed in the APP service document
  2. a depositing client authenticated as a contributor user is not shown the extension <sword:mediation>true</sword:mediation> in any collection listed in the APP service document
  3. if a an authorised depositing client supplies a valid username in the "X-On-Behalf-Of" HTTP header, the owner of the object is the specified user
  4. any automatically-generated metadata is created using the ID of the specified user
  5. if an authorised depositing client supplies a invalid username in the "X-On-Behalf-Of" HTTP header the status code "401 Unauthorized" is returned
  6. if an unauthorised (contributor) depositing client uses "X-On-Behalf-Of" HTTP header, the status code "401 Unauthorized" is returned
  7. the namespace for the "sword" prefix is "http://purl.org/net/sword/"
  8. if an authorised depositing client supplies a invalid username in the "X-On-Behalf-Of" HTTP header, the header of response contains the value "TargetOwnerUnknown" in the field "X-Error-Code"
  9. if an unauthorised (contributor) depositing client uses "X-On-Behalf-Of" HTTP header, the header of response contains the value "MediationNotAllowed" in the field "X-Error-Code"

SM-296: reporting on deposited content-packages

When a package is deposited using the APP interface, the text of the package import report is returned in the "<sword:treatment>" element, which sits inside the atom "<entry>" element of the APP response. Example given in SWORD profile of APP at SWORD_APP_Profile_1.0#Deposit. For all upload/import/deposit, the first line of the report will say what format the content package was in, using the following text:

  • "Recognised as a content package in the following format: (IMS Content Package/SCORM 1.2/SCORM 2004)"

Acceptance tests:

  1. if an IMS package is uploaded, the upload report starts with the line "Recognised as a content package in the following format: IMS Content Package"
  2. if a SCORM 1.2 package is uploaded, the upload report starts with the line "Recognised as a content package in the following format: SCORM 1.2"
  3. if a SCORM 2004 is uploaded, the upload report starts with the line "Recognised as a content package in the following format: SCORM 2004"
  4. when a content package is deposited using the APP interface, the text of the package import report is returned in the "<sword:treatment>" extension element
  5. the "sword" namespace prefix is mapped to the "http://purl.org/net/sword/" namespace

SM-297: package namespaces for remote deposit

In each <app:collection> element in the APP service document, the root namespace(s) the system recognises for the package manifest file are returned in one or more "<sword:formatNamespace>" elements. If a deposit is made which includes a value for the "X-Format-Namespace" property of the request header, the deposit is only accepted if the manifest of the package is in the appropriate location for that type of manifest, and uses the namespace specified in the request.

Acceptance tests:

  1. The <sword:formatNamespace> is populated with the URI of root namespace of IMS manifest for IMS Content Packaging 1.1, "http://www.imsglobal.org/xsd/imscp_v1p1"
  2. If the namespace of the package manifest does not match the supplied value of X-Format-Namespace, a HTTP 500 (Internal Server Error) is returned, including the value "ErrorContent" in the HTTP extension parameter "X-Error-Code"
  3. if the namespace specified in the X-Format-Namespace is not a namespace of a package manifest supported by the system, i.e. "http://www.imsglobal.org/xsd/imscp_v1p1", the system will respond with a HTTP 500 (Internal Server Error) and the value of "ErrorContent" in the "X-Error-Code"
  4. the service document will include the following inside the "service" element: <sword:level>1</sword:level>
  5. elements with the "sword" namespace prefix are in the namespace "http://purl.org/net/sword/"

SM-298: verbose response to deposit request

The APP service document includes the extension element <sword:verbose>true<sword:verbose> in the "<app:service>" element. When a deposit is made using the APP interface which includes a value of "true" for the field "X-Verbose" in the HTTP header of the deposit request, any error/debugging information (stack trace...?) is returned in the "<sword:verboseDescription>" extension to the the atom "entry" element. See the examples at http://www.ukoln.ac.uk/repositories/digirep/index/SWORD_APP_Profile_0.5#Deposit.

Acceptance tests:

  1. <sword:verbose>true<sword:verbose> appears inside the "<app: ervice>" element of the APP service document
  2. If X-Verbose is set to "true" in the request, any error/debugging information available is returned in <sword:verboseDescription> element
  3. If X-Verbose is not set, or is set to "false" in the request, the <sword:verboseDescription> element does not appear in the response
  4. the "sword" namespace prefix is mapped to the "http://purl.org/sword/" namespace.

SM-299: test deposit with "no operation"

The entry <sword:noOp>true</<sword:noOp> is included in the root element of the APP service document to indicate the system supports test deposits. If the HTTP parameter "X-No-Op" is set to "true" in a deposit request, the system responds as if the deposit had been made, but doesn't actually import the file/package into the repository. When this happens, the entry "<sword:noOp>true</<sword:noOp>" is additionally included "<app:entry>" element of response. See the "level 1" example at SWORD_APP_Profile_1.0#Response

Acceptance tests:

  1. <sword:noOp>true</<sword:noOp> is included in the root element of the APP service document
  2. "X-No-Op" is set to "true" in a deposit request, the file/package is not deposited into the repository
  3. "X-No-Op" is set to "true" in a deposit request, the response returned is as if the deposit had been made, except that "<sword:noOp>true</<sword:noOp>" is additionally included "<app:entry>" element
  4. elements using the "sword" namespace prefix are in the "http://purl.org/net/sword/" namespace

SM-301: checkum test for deposit integrity

When a file/package is deposited using the APP (SWORD) interface, the client supplies an MD5 checksum in the "Content-MD5" parameter of the request header. When the request is received, an MD5 checksum is calculated on the attached file/package. If the checksums match, the file/package is deposited as normal. If the checksums don't match, the deposit is rejected.

Acceptance tests:

  1. if no checksum is supplied, the file/package is deposited using the existing procedure
  2. if a checksum is supplied, which matches the calculated checksum, the file/package is deposited using the existing procedure
  3. if a checksum is supplied, which does not match the calculated checksum, the system responds with a HTTP 412 (Precondition failed) and the value "ErrorChecksumMismatch" in the "X-Error-Code" parameter of the response header. Nothing is deposited into the system.
  4. this behaviour is independent of other optional HTTP parameters used in SWORD, such as X-On-Behalf-Of, X-Verbose and X-NoOp

SM-302: extensions to collection description in the APP

When a file/package is deposited using the APP (SWORD) interface, the client supplies an MD5 checksum in the "Content-MD5" parameter of the request header. When the request is received, an MD5 checksum is calculated on the attached file/package. If the checksums match, the file/package is deposited as normal. If the checksums don't match, the deposit is rejected.

Acceptance tests:

  1. The <sword:collectionPolicy> element is populated with the text of the usage agreement selected as the "repository agreement", if any
  2. The <dcterms:abstract> element is populated with the text of the relevant collection's description
  3. The <sword:treatment> element is populated with the following static text (in English) "Zip archives recognised as content packages are opened and the individual files contained in them are stored. All other files are stored as is."
  4. The namespace for the "dcterms" prefix is "http://purl.org/dc/terms/"
  5. The namespace for the "sword" prefix is "http://purl.org/net/sword/"

SM-306: identifiers in atom entry resulting from deposit

When a deposit request under the APP includes a value in the "Slug" HTTP header, this value is returned in the "atom:id" element of the atom "entry". The name of the repository is returned inside the "atom:generator" element, and the base URL of the repository in "uri" attribute of the atom:generator element, for example:

 <atom:source>
   <atom:generator uri="repository.myuni.ac.uk">
     The MyUni Repository
   </atom:generator>
 </atom:source>

Acceptance tests:

  1. If a value for Slug is specified in the deposit request, the value of "atom:id" element includes the supplied Slug
  2. If a value for Slug is not specified in the deposit request, the value of "atom:id" element is an auto-generated ID
  3. the "atom:generator" element contains the value of the RepositoryName property
  4. the "uri" attribute of the atom:generator element contains the base URL of the repository