/alma-slipsomat

Script for syncing Alma letters XSL files with a local folder

Primary LanguagePython

This repo contains our slipsomat script for pulling and pushing files to Alma using Selenium browser automation. The script computes and stores checksums of all the letters to protect you from overwriting the work of others.

Using something like Selenium for synchronizing files might seem like a rather silly approach. It is! It works… sort-of, but we'd much prefer that Ex Libris implemented a proper protocol we could use, so please go and vote for this idea on Ideas Exchange to put some pressure on Ex Libris to do just that.

Setup

You will need Python 2.7 or 3.3 or later. Install using python setup.py install, or pip install -e . if you plan to hack on the script and want an editable install.

Once installed, you can run slipsomat from any directory containing a slipsomat.cfg file. To get started with your own files, you can create an empty directory with a slipsomat.cfg with the following contents:

[login]
auth_type=
domain=
instance=
institution=
username=
password=

[selenium]
browser=firefox

[window]
width=1200
height=700

where you fill in the blank values.

  • Set auth_type=Feide if you authenticate using Feide SAML. Set auth_type=SAML for Shibboleth or other SAML providers (submit an issue if it doesn't work with your provider!). Set auth_type=basic to use the standard Alma login.
  • domain is your Feide domain, e.g. uio.no. If you don't use Feide as your SAML provider, you can leave this empty.
  • instance is the Alma instance name, which is the first part of your ALMA URL. If your Alma URL is bibsys-k.alma.exlibrisgroup.com, then bibsys-k is the instance name.
  • institution the Alma institution name, e.g. 47BIBSYS_UBO
  • username is your username.
  • password can be left blank if you want to be asked for it each time. This is the recommended solution, since the password is stored in plain text.
  • browser can be set to firefox, chrome or phantomjs. The corresponding driver must be installed (GeckoDriver for Firefox, ChromeDriver for Chrome). I've had success with all three browsers, but from time to time a browser can start crashing or freezing at some point. First thing to try then is to upgrade both Selenium and the browser driver. If there's still problems, switch to another browser for some time. If that doesn't help, there might be an issue with slipsomat. Please file an issue.

Debugging

If you have inquirer installed (does not work on Windows), slipsomat will give you some options for starting a debug session if the script crashes.

Getting started

The slipsomat command will give you an interactive shell where you can type various commands. Type help for an overview.

To get started in an empty directory, type pull to pull in all the XSLT files from your Alma instance and store them in a folder named xsl (will be created if not there already). Optionally, type defaults to pull in all default letters too. Note that a status.json file is also created. This holds the checksums for all the letters, allowing the script to easily keep track of which files have been modified (locally or in Alma).

Once you have a directory with all your files you're free to put them under version control if you like. Here's the repo we use for our files: https://github.com/scriptotek/alma-letters-ubo

Workflow

In a workspace directory (a directory having a slipsomat.cfg file):

  1. Start by doing git pull to pull in changes from other users.

  2. slipsomat to start the script

  3. Optional: the slipsomat command pull will check if any files have been updated directly in Alma (without using slipsomat), fetch those and update status.json. Comparison is done by comparing the update date in Alma with the update date in status.json. Alma does not provide time granularity for updates, only date, so for files that have been modified today, the script will open the letter in Alma to get the text and calculate a checksum to compare with the checksum in status.json. Note: If you skip this step, slipsomat will still warn you if you try to push a letter that have been modified remotely (checksums not matching), but then you will have to merge manually.

  4. After having made modifications to one or more letters, run the slipsomat command push to push the updates to Alma. Comparison is done by comparing checksums of the local files with the checksums in status.json. Before making any changes, the script will print a list of files and confirm that you want to upload these.

  5. After having tested the modifications, do a git commit (remember to include the updated status.json) and git push

The shell has a command history, and tab completion. For example test Ful<tab><tab>.

Updating default letters

  • Use the slipsomat command defaults to pull in all default letters. Note that the command takes quite some time to run, since all letters have to be checked as Alma provides no information whatsoever on when the default letters were last updated.

Testing the output of a letter

Alma lets you test the output on the Notification Template page, but doing this manually each time is boring, so slipsomat provides you with the test command to automate that.

Create a folder called "test-data" in the same folder as the slipsomat.cfg file. Add one or more XML files you want to test there.

Start slipsomat and run the command

test filename.xml

where filename.xml is a file in the "test-data" folder. This will upload the XML file to the Notification Template page and store the resulting HTML output and a screenshot in the "test-data" folder.

To test multiple files at the same time, you can use Unix style pathname pattern expansion ("globbing"). E.g. to test all XML files in the "test-data" folder, use the * wildcard character:

test *.xml

By default, the command will use English as the letter language. To test another language, just append @ and the language code to the filename. Example:

test filename.xml@nn

You can even test multple languages in one go by specifying multiple language codes separated by comma like so:

test filename.xml@en,no,nn

This can also be used in combination with globbing. To test all XML files in the "test-data" folder in three languages:

test *.xml@en,no,nn

See also

Development

Given that you have created a slipsomat.cfg file, here's how to start experimenting:

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.keys import Keys
from slipsomat.slipsomat import Browser, TemplateTable

# We set a quite short timeout (3 seconds) since we don't want to wait
# a long time every time we write a wrong selector.
browser = Browser('slipsomat.cfg', default_timeout=3)

# Open Browser and login using credentials from slipsomat.cfg
browser.connect()

table = TemplateTable(browser)
letter = table.rows[0]
letter.view_default()

wait = browser.waiter()
# Try looking for some element and click it
element = wait.until(EC.element_to_be_clickable((By.XPATH, '//button[@aria-label="Open Alma configuration"]')))
element.click()