PubMan Sword

This page briefly describes the SWORD Server implementation in the PubMan solution. General Information about SWORD can be found here.

Implementation[edit]

For start the SWORD functionality is directly implemented in PubMan. In future we should have a separate SWORD service for all eSciDoc solutions.

PubMan implements 3 classes for the SWORD service:

PubManSwordServer - Processing of requests
PubManServiceDocumentServlet - Accepting requests for the Service Document (dependent on user credentials)
PubManDepositServlet - Accepting requests for the deposits (dependent on user credentials)

Interface[edit]

The PubMan SWORD interface is deployed within the PubMan ear, therefore one can access the above described servlets by the PubMan baseURL + the servlet path.

(Example with PubMan base url http://pubman.mpdl.mpg.de/pubman)

Service Document[edit]

http://pubman.mpdl.mpg.de/pubman/faces/sword-app/servicedocument

Request:

GET with user credentials

Response:

Code 200

A servicedocument describing:

All open collections a user may deposit to.
Collection identifier (mandatory for deposit)
Accepted formats (mandatory for deposit)
The workflow of a collection

Deposit Service[edit]

http://pubman.mpdl.mpg.de/pubman/faces/sword-app/deposit?collection=collectionIdentifier

Request:
Parameters to send:

Authorization: User credentials in the form of HTTP basic access authorization (Mandatory)
- user credentials are to be sent base-64 encoded in the format "Basic username:password"

    Example:
     parameter-name: Authorization  
     parameter-value: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

X-Packaging: Metadata format as described in the servicedocument (Mandatory)

     Example: 
       parameter-name: X-Packaging
       parameter-value: http://purl.org/net/sword-types/tei/peer

x-Verbose: true/false, sets the verbose output (Optional)
x-No-Op: true/false, Test deposit with no actual item deposit (Optional)

Response:

Code 201: Created

- Item action: Save, Submit, Release

Code 202: Accepted

- Item action: Save
- Item action: Save, Submit

Code 203:

- No user credentials were provided

- User was not recognized

Code 403:

- No collection was provided
- No rights to deposit to the provided collection

Code 415:

- Media Type not supported in PubMan
- No metadata file was provided
- Metadata could not be transformed into publication format

Code 400:

- Authentication Failure

- Validation Failure

Code 500:

- Internal Server Error

Code 413:

- Mediation not allowed

Plus an Atom Entry Document which contains information about the deposit:

 <atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:sword="http://purl.org/net/sword/">
   <atom:author>
      <atom:name>Friederike, Kleinfercher</atom:name>
   </atom:author>
   <atom:content src="http://pubman.mpdl.mpg.de/pubman/item/escidoc:xy"/>
   <atom:summary>item.xml ,123.pdf</atom:summary>
   <atom:title>First Sword item</atom:title>
   <atom:source>
      <atom:generator>http://pubman.mpdl.mpg.de/pubman</atom:generator>
   </atom:source>
   <atom:updated>2009-04-02T14:23:02Z</atom:updated>
   <sword:treatment>Zip archives recognised as content
      packages are opened and the individual files contained
      in them are stored. All other files are stored as
      is.</sword:treatment>
   <sword:acceptPackaging>http://purl.org/escidoc/metadata/schemas/0.1/publication</sword:acceptPackaging>
   <sword:noOp>false</sword:noOp>
 </atom:entry>

The zip file may contain several files but must contain exactly one metadata file. All files not containing metadata are transformed to PubFiles and are added to the Publication item.
The metadatafile must have a specific file-ending: ".bib" for BibTex, ".xml" for publication (eSciDoc XML), ".enl" for EndNote and ".tei" for PEER TEI Publications
The item is deposited to the collection: collectionIdentifier
The validation of the item depends on the collection
The action of deposit depends on the collection

Action Mapping[edit]

SWORD Action	PubMan Action	Comment	Status
Deposit	Submit Submit & Release	depending on the collection workflow and collection policies.	Implemented
Edit	Submit Submit & Release	depending on the collection workflow and collection policies.	Not implemented
Delete	Withdraw Delete	If item is in state released If item is in state pending or In-Revision	Not implemented

Important Information[edit]

File visibility will be set to public
File content category will be set to Publisher Version for all pdf files. Other files will get content category Supplementary Material.

Test the sword interface[edit]

For testing the sword interface from the desktop you can use for example the poster firefox addon
Find out for which collections you have access rights by visiting http://test-pubman.mpdl.mpg.de:8080/pubman/faces/sword-app/servicedocument
Enter the following information in the poster
3.1. URL: http://test-pubman.mpdl.mpg.de:8080/pubman/faces/sword-app/deposit?collection=YOURCOLLECTIONID

3.2. Under 'Content to Send' upload the file you want to ingest (metadata file plus optional fulltext), in zip format.

Attention: accurate file extention may be necessary (e.g. .bib for BibTeX-files)

3.3. Under 'Headers' enter:
3.3.1. Name: Authorization Value: Basic username:pwd (Base64 encoded, e.g.: ZGVtbzpkZW1v for demo:demo ; complete entry would be: Basic ZGVtbzpkZW1v)

3.3.2. Name: x-packaging Value: metadata format (check the servicedocument which are allowed, e.g. BibTex or EndNote)

3.3.3. optional Name: x-verbose Value: true/false

3.3.4. optional Name: x-No-Op Value: true/false
Press the POST button