Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Building a Digital Deposit Tool for Alma

Institutions who implement their institutional repository with Alma require a deposit workflow for users. The requirements for a deposit tool can often vary widely among institutions and even among workflows. For example, a tool to deposit theses would require different metadata and file types than a tool to accept faculty-produced PowerPoint presentations. Now that Alma supports the SWORD protocol for depositing digital material, we can create custom deposit experiences that meet our institution's specific requirements.

In this article, we'll create a tool which accepts general deposits to our digital repository. We'll leverage a generic SWORD library to make calls against the Alma SWORD server. Our tool will have the following features:

Introduction

We'll build our deposit tool on top of the My Alma Library application, a Ruby on Rails-based showcase for integration use cases with the Alma APIs. In a previous article, we've seen how to access digital collections in an external application. We'll add to that the ability to view and manage end-user deposits.

We've been introduced to Alma SWORD support in a previous article as well. There we saw how to use the Sword2Ruby client provided by the SWORD project. We'll use that gem in our project and leverage it to make our SWORD calls.

gem 'sword2ruby', '>=1.0.2', :git => 'https://github.com/swordapp/sword2ruby.git'

Authentication

There are two levels of authentication required for SWORD. The first is basic authentication with the username and password defined in the SWORD integration profile. This proves that the deposit tool is authorized to use the SWORD APIs. Since deposits are always made in the context of an end user, we also need to indicate on whose behalf the deposit is being made. SWORD accommodates this by providing an 'On-behalf-of' header, which we will populate with the authenticated user from our deposit tool.

Add a New Deposit

To add a new deposit, we first need to check what collections have been made available in Alma. We'll request a SWORD Service Document, which returns a list of the 'collections' configured in Alma as deposit profiles. Since we provide the SWORD server with the 'On-behalf-of' header, it returns only the deposit profiles for which the specified user is authorized.

We build a list of those collections and provide them as a drop down box along with the accompanying instructions. Then we show the metadata fields we're interested in having the user fill out. Here we can use any validation and business logic according to our requirements.

We also provide an HTML file dialog. We allow multiple files to be added to the form, which will be zipped into a single file when submitted. We're using the Bootstrap File Input library to provide some nice styling to our file input field.

SWORD allows deposits to be made in submitted or draft mode, so we provide two buttons on our interface as well. 

SWORD Deposit Tool Add Deposit

When the user clicks submit, we add the files to a zip archive and send it along with the specified collection and Dublin Core metadata to the post_multipart! method of the Sword2Ruby client. Once we receive the response from Alma, we redirect back to the user's list of deposits.

collection.post_multipart!(
   :connection=>sword_connection,
   :entry=>entry,
   :filepath=>zip_file.to_s,
   :content_type=>"application/zip",
   :in_progress=>draft,
   :packaging=>"http://purl.org/net/sword/package/SimpleZip"
)

List of Deposits

To allow users to check on the status of their deposits, we want to display a list of the deposits and some basic information. The SWORD protocol doesn't have an appropriate method for this use case, so we'll supplement our application with a call to the native Retrieve User Deposits API. This API returns the deposit status, based on which we can provide a link to view the deposit or to edit it.

SWORD Deposit Tool List Deposits

View Deposit

To view a deposit's files, we use the Alma digital viewer. The view link is available in the Retrieve User Deposits API and in the SWORD deposit receipt in the alternate URI. Using the Sword2Ruby library, this can be retrieved with the 'alternate_uri' method.

SWORD Deposit Tool View Deposit

Retrieve and Edit a Deposit

According to the SWORD standard, you can retrieve a deposit, replace a deposit's metadata, and add or remove a deposit's files. Alma supports all of these actions, allowing us to enable users to edit their deposits. According to the Alma deposit lifecycle, deposits which are in the DRAFT or RETURNED status can be edited. For those deposits, we provide an edit link from the deposit list.

Retrieve a Deposit

Retrieving a deposit can be done by issuing a GET on the edit URI. This request returns a deposit receipt. Using the Sword2Ruby library, we create a new deposit receipt and populate it with a call to the edit URI:

Sword2Ruby::DepositReceipt.new(
   sword_connection.get(
      "#{ENV["sword_service"]}/edit/#{id}"),
   sword_connection)

We then build a screen which has 3 sections- deposit details, metadata, and files.

SWORD Deposit Tool Edit Deposit

Edit Metadata

We can replace a deposit’s metadata by issuing an HTTP PUT to the edit URI. Our edit page shows the existing metadata. Clicking the Update Metadata button will retrieve the deposit, add each of the fields to the deposit’s entry, and then call the put! method on the entry.

deposit = sword_get_deposit(id)
entry = deposit.entry

dc.each do |param|
   entry.delete_dublin_core_extension! param[0]
   param[1].each do |val|
      entry.add_dublin_core_extension! param[0], val
   end
end
     
entry.put!( { in_progress: in_progress } )

Add Files

We can add files to our deposit by issuing an HTTP POST to the edit media URI. Our edit page provides the same file input we used for the create deposit form. When submitted, the form will call the post_media! method to add the files:

entry.post_media!(
   :filepath=>zip_file.to_s,
   :content_type=>"application/zip",
   :packaging=>"http://purl.org/net/sword/package/SimpleZip"
)

Delete Files

We can remove a file from a deposit by issuing an HTTP DELETE to the edit media URI. Our edit page provides a trash icon next to each file. When clicked, we do some validation and then call the delete method on the file’s URI.

Submit or Withdraw a Deposit

An editable deposit (DRAFT or RETURNED status) can have one of two outcomes- it can be submitted to the library staff for approval, or it can be withdrawn if the depositor no longer wants to deposit the material. Our application allows for both of these actions from the edit deposit page.

To submit a deposit, we make a call to the update metadata method and pass the “in_progress” parameter as false. The SWORD server then submits the deposit for approval.

To withdraw a deposit, we call the delete! method on the deposit’s entry. The SWORD server marks the deposit as WITHDRAWN.

Summary

Alma’s SWORD support allows us to leverage standard libraries to build a custom interface for our deposit workflows. The libraries wrap the underlying SWORD calls, reduce the amount of code that we need to write and maintain, and allow us to focus on our business requirements.

All of the code for this application is available in this Github repository.

Github