Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Getting Started with SWORD Digital Deposits

Josh Weisman on February 6th, 2017

As part of the institutional repository workflows, Alma now supports depositing digital material using the SWORD 2.0 protocol. SWORD is an ATOM-based protocol meant to facilitate the deposit process between a client and digital repository server. In Alma terms, this means that a client can perform the following actions:

  • Deposit one or more files along with accompanying metadata
  • Specify that a deposit is in draft form and not yet ready for approval
  • Update metadata, add or remove files for deposits in draft or returned status

For more information on Alma support for digital deposits and the deposit workflow, see the online help. For more information on Alma's SWORD support, see the SWORD section in the Developer Network.

SWORD is intended to allow an institution to build a custom deposit application. We expect institutions to have varying requirements for a deposit interface, and using SWORD allows the flexibility to build a tool which fits your needs. This article will demonstrate the use of SWORD to deposit a number of files and metadata into Alma. We will use the sample clients provided by the SWORD project.

Getting Started

To enable the SWORD server in Alma you need to create an integration profile. Add an integration profile of type SWORD Deposit and choose a username and password. Then save the profile. The SWORD deposit root URL is: https://YOUR_ALMA_URL/sword/INSTITUTION. The service document is available at /sd.

PHP Client

To perform a SWORD deposit using the PHP client, first clone the Github repository. In the test directory, open the test-swordappclient.php file. Change the following parameters at the top of the file:

// The URL of the service document
$testurl = "https://na01.alma.exlibrisgroup.com/sword/MY_INST/sd";

// The user (if required)
$testuser = "USER_NAME";

// The password of the user (if required)
$testpw = "PASSWORD";    

// The on-behalf-of user (if required)
$testobo = "user";

// The URL of the example deposit collection
$testdepositurl = "https://na01.alma.exlibrisgroup.com/sword/MY_INST/col/238593350000561";

A full version of the test script is available in this Github repository. Then run the test application from the command line:

$ php test-swordappclient.php

About to deposit multipart file (test-files/atom_multipart_package) to https://na01.alma.exlibrisgroup.com/sword/MY_INST/col/1620699450000561
As: apikey
: Received HTTP status code: 201 (Created)
 - ID: 1620717240000561
 - Title: If SWORD is the answer, what is the question? Use of the Simple Web service Offering Repository Deposit protocol

Your deposited material is now available in Alma. You can search for the deposit ID returned in the Deposit Receipt in Alma to view the deposit and the corresponding bibliographic record.

SWORD Search Deposit

SWORD Deposit

 

Ruby Client

The Sword2Ruby client is available as a gem. To use it, install the gem on your machine by running gem install sword2ruby. Once the gem is installed, you can create a small Ruby script which performs the deposit. 

$ bundle exec ruby sword.rb 

Running Sword2Ruby version 1.0.1
service.sword_version: 
service.sword_max_upload_size: 0
service.workspaces.count: 1
service.collections.count: 2

deposit_receipt.has_entry: true
deposit_receipt.entry.to_s: <entry xmlns='http://www.w3.org/2005/Atom'><id>1620717490000561</id><title type='text'>Test from Ruby</title><updated>2016-08-02T00:00:00Z</updated>...

Node.js

Node.js doesn't have a dedicated client listed on the SWORD client implementations page. But that doesn't mean we're out of luck. The SWORD deposit request is a relatively simple multipart HTTP POST. That means we can use the Request NPM package to construct our own SWORD deposit by hand.

var request = require('request');

headers = {
   "In-Progress": false,
   "On-behalf-of": USER_NAME
}

var options = {
   url: SWORD_URL,
   method: 'POST',
   auth: {
      user: USER_NAME,
      pass: PASSWORD
   },
   headers: headers,
   multipart: [{
      'content-type': 'application/atom+xml; charset="utf-8"',
      'content-disposition': 'attachment; name=atom',
      body: '<entry><dc:title>My Title</dc:title></entry>'
   }, {
      'content-type': 'application/zip',
      'content-disposition': 'attachment; name=payload; filename=' + FILENAME)),
      'Content-Transfer-Encoding': 'base64',
      'Packaging': 'http://purl.org/net/sword/package/SimpleZip',
      'Content-MD5': utils.checksum(FILE),
      body: utils.base64_encode(FILE)
   }]
};

request(options, next);

With SWORD support in Alma you can design many kinds of solutions, from simple deposit scripts to full-fledged deposit applications. All of the code snippets from this article are available in this repository. If you're looking for a really bare-bones example, you can look at the curl sample in the same Gist.

Github