search

uio-library / alma-letters-ubo

University of Oslo Library XSLT files for Alma letters
8 stars 5 forks source link
alma xsl-files

readme

⚠️ Archived

This repository has been archived on Oct 14, 2022. Unfortunately we did not have the time and resources to update slipsomat, our hacky synchronizing tool, after a breaking change in Alma.

Synchronizing the letters would be much easier if there was an API for doing so, so feel free to vote for this idea (if it's not yet implemented when you read this ✨): https://ideas.exlibrisgroup.com/forums/308173-alma/suggestions/12471084-synchronizing-xsl-templates-with-external-systems

alma-letters-ubo

This is a collection of the XSL files used to generate letters and slips in Alma, as customized by the University of Oslo Library. In general, we try to make the files re-usable by others, but we fail in some cases.

We also have a Python script for synchronizing the files with Alma at https://github.com/scriptotek/alma-slipsomat

Overview of the .xsl files

Descriptions for the letters can be found in Ex Libris Knowledge Base.

Documentation for the fields is not available, and probably isn't something we can expect anytime soon. Tamar Fuches wrote the following about it on the Dev forum: "Regarding documentation, we do not have it currently. It will take time to get this ready."

A curiosity of the letters is that typos are not uncommon; from the name FulReasourceRequestSlipLetter to field names like autho_initials and what have we, odd translation placeholders like @@You_were_specify@@. Anyways, this doesn't affect the end result, it's just annoying to work with, and makes you wonder if the application code is written using the same amount of carelessness. Hopefully not.

Letters usage

Some letters are used much more than others, and should be prioritized. A sample of 3080 letters taken during a few days in June 2016 showed the following distribution:

FulReasourceRequestSlipLetter : 1002
FulTransitSlipLetter : 834
FulPlaceOnHoldShelfLetter : 501
ResourceSharingShippingSlipLetter : 215
OrderListLetter : 99
FulIncomingSlipLetter : 96
FulPersonalDeliveryLetter : 87
FulUserBorrowingActivityLetter : 75
AnalyticsLetter : 64
ConversationLetter : 32
FulOutgoingEmailLetter : 32
FulLostRefundFeeLoanLetter : 16
PurchaseRequestStatusLetter : 7
FineFeePaymentReceiptLetter : 6
FulLoanReceiptLetter : 5
FulReturnReceiptLetter : 3
FulCancelEmailLetter : 2
GeneralAssignToLetter : 1
ProcessBibExportFinishedLetter : 1
InterestedInLetter : 1
POLineCancellationLetter : 1

In total, only 21 letters were used, but this was in the summer when we're not sending overdue letters and such, so I should probably make a new sample later.

Example XML data

Some examples XML files are provided in the test-data folder. The files have been generated using test users or anonymized using the provided anonymize.sh script.

Templates

The files in xsl/letters/call_template contains templates used by the other files. This means that if you intend to use some of our letter files, such as xsl/letters/FulReasourceRequestSlipLetter.xsl, you also need to copy the template files (or at least some of them).

Ideally, we would have created new template files to hold any new templates we add, but since we aren't allowed to create new files, we have had to add new templates to the existing files. Wherever a template is used, however, we try to remember to add a comment indicating which template file the template is defined in, to ease lookup.

Our current guideline is to use

Quick overview of new templates we've added:

In the other template files we've only done smaller modifications to the existing templates.

Utskriftsløsning

USIT har opprettet egne epost-adresser for for alle kønavnene for printerne det skal skrives til. Postmaster har konfigurert det slik at epost sendt til disse adressene sendes direkte til et enkelt Bash-script, som skriver HTML-teksten fra e-postene til disk og kaller html2ps for å konvertere fra HTML til PostScript, som så sendes til riktig printerkø basert på hvilke adresse e-posten ble sendt til.

Fordeler med løsningen inkluderer at det går kjapt (utskriftene kommer "umiddelbart" når man trykker "Print slip") og at det er en enkel løsning å drifte. En ulempe med løsningen er at html2ps ikke støtter CSS, så vi kan bare gjøre enkel formatering.

Spesielle elementer

Hentehylle og hentenummer

FulReasourceRequestSlipLetter som hentehyllelapp

Lenge fantes det ikke en egen hentehyllelapp, og FulReasourceRequestSlipLetter måtte brukes både som hentelapp for bibliotekspersonalet og som hentehyllelapp:

% if work_flow_entity/step_type = 'ON_HOLD_SHELF' then
    Hentehyllelapp retta mot bruker
% else
    Hentelapp retta mot personale
% endif

I desember 2018 la Ex Libris til en egen hentehyllelapp (basert på et Ideas Exchange-forslag).

Hentenummer

Av personvernhensyn stiller vi opp dokumenter etter hentenummer, ikke navn. Alma har ikke noen mulighet for å genere hentenummer enda (selv om det forhåpentligvis er på vei, se Ideas Exchange-forslag). Enn så lenge generer vi derfor hentenummer selv på en litt hackete måte. Det er svært begrenset hva man kan gjøre i et lukket XSLT-miljø, så vi har ikke funnet noen måte å generere garantert unike numre på. I stedet generer vi numre som stort sett er unike. Vi har valgt å ha relativt korte numre (6 sifre), selv om det øker sjansen for en og annen kollisjon.

Hentenummer

Nummeret vårt begynner med to sifre fra hentefrist-datoen (for å gjøre sorteringen av hentehylla enkel). Deretter legger vi på to sifre fra en bruker-ID og to sifre fra en dokument-ID. Numrene genereres i XSLT-malenpickupNumber i mailReason.xsl. I tillegg har vi en mal pickupNumberWithLabel (i samme fil) som viser "Til henting i skranken" for dokumenter som ikke har hentefrist, samt for enkelte bibliotek som ikke har selvbetjent hentehylle.

De to malene (pickupNumber og pickupNumberWithLabel) brukes av FulReasourceRequestSlipLetter (selve hentehyllelappen), samt hentemeldingene (FulPlaceOnHoldShelfLetter.xsl og SmsFulPlaceOnHoldShelfLetter.xsl).

Libnummer (norsk ISIL-kode)

Fire av sedlene brukes som sendelapper mellom bibliotek og har derfor libnummer nederst. Nummeret må plasseres i en fast avstand fra bunnen av arket fordi det skal være synlig i vinduskonvolutter for sending av dokumenter. For sending av bøker stikkes sedlene i bøkene slik at arket stikker ut på bunnen av boka med libummeret synlig.

For å få plassert libnummeret i en fast avstand fra bunnen av arket har vi konfigurert html2ps (dokumentasjon) til å legge innhold fra meta-taggen libnummer i bunntekst (footer):

@html2ps{
    footer {
      left: "$[libnummer]";
      center: " ";  /* override default value */
      right: "$[address]";
      font-size: 48pt;
    }
}
@page {
   margin-left: 2cm;
   margin-right: 3cm;
   margin-top: 0;
   margin-bottom: 6cm;
}

html2ps-oppsettet driftes av USITs gruppe for drift av meldingstjenester. For å gjøre endringer i konfigurasjonen sender vi epost til postmaster at rt.uio.no der vi beskriver endringene – det har gått greit så langt, de svarer raskt.

Eksempel på en meta-tagg: <meta name="libnummer" content="103 0310"/>.

Tips