With the CLA’s recent work developing its API offering, we found ourselves in a position to review our existing digitisation request process.
Our workflow at York St John University was that an academic or librarian requesting digitised content would manually create a reading list record for (a book chapter perhaps?) then go to the CLA’s scan request form and input all the same details of the chapter, incl. ISBN, publication year, page range etc..
Our primary issues with this workflow are:
- Duplication of effort
- Manually entering data twice increases the risk of human error in typing etc…
When the CLA announced the Submit Request API we saw this as an opportunity to reduce library effort and increase accuracy of data being submitted.
Our Reading List provider offer (via reporting) most of the data required to populate a scan request. Using this reading list report in conjunction with the CLA’s API, we were successfully able to extract data from our reading list system and push it into the CLA Digital Content Store in a swift, automated fashion.
Workflow
Our integration is built on the following daily workflow:
- An item level report is exported (.csv) from the reading list (filtered by records added in the last 24 hrs)
- This report is loaded into Microsoft Excel
- Records with “SCAN” in the notes field are retained, all other rows are removed
- Buttons are generated to submit either each row, or all rows, to the CLA
- A response cell is generated next to each row to indicate success or error (and reason)
This was my first foray into such a task and while I am no expert when it comes to either Excel, VBA, or working with web services (APIs), I found this to be relatively straightforward to build and setup.
The CLA provide some great documentation and support on using their suite of APIs which can be found below:
The rest of the work in Excel turned out to be quite simple once a few things were figured out.
In hindsight, there were two bits of code I needed to use to get this working as intended:
Row Looping (preparing the data)
A macro associated with a button runs a bit of code (in a visual basic sub-routine: Alt-F11). This code gathers the values of each cell and concatenates them into the URL used in this submit request API call.
Excel cells:
Title | Chapter/Article Title |
The production of space | Chapter One: Plan of the Present Work |
API URL: (built from the cell values above)
https://api.cla.co.uk/dcs-course-content-urls/v2/SubmitRequest?hei=191&AcademicName=Joseph Munzer&EmailAddress=j.munzer@yorksj.ac.uk&IsBook=FALSE&ISN=631181776&Title=The production of space&ExtractTitle=Chapter One: Plan of the Present Work&PageRange=1-67&ChapterNumber=1&Publisher=1991 |
URL: (split up for easier reading)
https://api.cla.co.uk/dcs-course-content-urls/v2/SubmitRequest? hei={hei} &AcademicName=Joseph Munzer &ISN=631181776 &Title=The production of space &ExtractTitle=Chapter One: Plan of the Present Work &PageRange=1-67 &ChapterNumber=1 &Publisher=1991 |
Once the URL is fully populated by the cell values, the API SubmitRequest call is made, and a success/fail response is returned (either in a cell or pop-up message box)
API call (sending the request to the DCS)
At the end of each loop of a row (one digitisation request per row), I added a few lines of code to POST the generated URL. This requires authentication to ensure that only authorized people/programs can send a DCS submit request. The CLA provided this information, it consists of an encoded username, password and a 32-character subscription key.
Summary
The above two functions will allow a DCS customer to submit as many scan requests as they like to the DCS. Much of my work on this project has actually been around improving the workflow rather than getting basic functionality working. This has included developing little quality-of-life functions such as adding:
- ‘BrowseFor-File’ button
- ‘Close Sheet’ button to start again
- Adding response information to see in Excel if a submit didn’t work (and the reason why)
- Removing lines which don’t have scan request text in the notes field
- Adding individual submit buttons for each row.
Speaking to Kevin O’Donovan at LSE, we see great potential for further development by the community, especially with adding check permission functionality (via its respective API) which can be run prior to submitting requests. Additionally, I believe we could track the outcome of submit requests using the /GetCourseContent API and pull the digitisation URL back out of the DCS to load back into reading lists or catalogue records.
I’m eager to work with other institutions who are interested in developing tools to streamline these workflows. Please don’t hesitate to get in touch either for further information/chat/excel files. My email is: j.munzer@yorksj.ac.uk.
About the Author
Joseph Munzer is the Linux Systems & Applications Officer at York St John University.