Yleistä
Palvelurajapintoja tarvitaan, kun halutaan tarjota käyttäjille itsepalvelutoimintoja, kuten lainojen uusiminen, varausten tekeminen tai omien tietojen päivitys.
Tyypillinen rajapinta on XML-pohjainen HTTP-protokollan yli käytettävä toimintokokonaisuus, joka toteuttaa ainakin suurimmaksi osaksi vähintään Level 3:n ILS DI:n rajapintasuosituksesta. Uudemmat rajapinnat ovat tyypillisesti REST-pohjaisia ja sisältävät esim. OpenAPI-kuvauksen. Olennaista on, että rajapinta on hyvin dokumentoitu.
Rajapinnan tulee olla turvallisesti käytettävä, eli verkossa kulkevat tiedot pitää salata esim. käyttämällä HTTPS-protokollaa.
Rajapinnassa tulisi käyttää mahdollisuuksien mukaan esim. erilaisille viesteille tai statuksille koodeja, jotka voidaan helposti kääntää Finnassa käytettävälle kielelle.
Finna pystyy yleensä sopeutumaan siihen, miten kattavat tiedot kirjastojärjestelmästä saadaan, mutta mitä kattavammat tiedot ja toiminnot ovat saatavissa, sitä paremmin palvelu toimii.
Esimerkkitiedot, joita kirjastojärjestelmän rajapinnan ja Finnan välillä voi liikkua
Finnan toiminnallisuus perustuu VuFind-järjestelmään, jonka kirjastojärjestelmäajureiden käyttämien tietojen peruskuvaus löytyy osoitteesta https://vufind.org/wiki/development:plugins:ils_drivers. Finnassa on käytössä myös lisätoimintoja, joita perus-VuFindissa ei ole.
Tässä on esimerkkinä toimintokohtainen listaus tiedoista, joita kirjastojärjestelmältä pyydetään tai sille lähetetään Finnassa.
Saatavuustiedot
Nidekohtaisesti haettavat tiedot:
- bibliografisen tietueen id
- varastotietueen id
- niteen id
- tila
- sijainti
- kuuluuko nide kurssikirjavarastoon (course reserve)
- hyllypaikka (call number)
- viivakoodi
- onko nide saatavissa
- mahdollinen eräpäivä
- varausten lukumäärä
- palautuspäivä
- ei tietoa saatavuudesta (bool)
- mahdollinen järjestystieto, mikäli rajapinta ei palauta tietueita valmiiksi järkevässä järjestyksessä
- asiakkaille näkyvät huomautukset
Varastotietueista haettavat tiedot:
- sijainti
- ostohistoria (saapumisvalvonta)
- huomautukset
- numerot saatavissa
- lisänumerot
- hakemistot
Lisätiedot, jos asiakas on kirjautunut:
- onko teos tai nide varattavissa (bool)
- varaustyyppi
- varaustaso (nide- ja/tai teostaso)
- varastotilaus tehtävissä (bool)
- kaukolainatilaus tehtävissä (bool)
Saatavuustietojen näyttämisen jälkeen voidaan tarkistaa asynkronisesti, voiko käyttäjä todella tehdä varauksen, varastotilauksen tai kaukolainatilauksen, jos tarkistus on hidas.
Sijainti koostuu tyypillisesti ainakin kahdesta osasta: kirjasto, jossa aineisto sijaitsee, ja sijainti ko. kirjastossa.
Käyttäjätiedot
Haettavat tiedot:
- etunimi
- sukunimi
- puhelinnumero
- tekstiviestinumero
- sähköposti
- osoite
- käyttäjäryhmä (käyttäjälle näkyvä tieto)
- käyttäjän kategoria (ei näytetä käyttäjälle)
- tiedot lainauskielloista ("blocks")
- huollettavat
- huoltaja
- käyttäjälle näytettävät huomautukset
- varaustunnus (varauksen noudossa käytettävä nimimerkki)
- tilin vanhenemispäivämäärä
- viestintäasetukset (erilaisten viestien lähetysasetukset)
- lainaushistorian tallennuksen tila
Yhteystietojen muokkauspyyntö
- muokattavat tiedot määriteltävissä järjestelmäkohtaisesti
Vastauksessa:
- tieto siitä, onnistuiko
- tieto siitä, vaatiiko henkilökunnan hyväksynnän muutosten voimaantulemiseksi
Viestintäasetusten muokkauspyyntö
- muokattavat tiedot määriteltävissä järjestelmäkohtaisesti
Lainaushistorian tallennuksen tilan muokkauspyyntö
- päällä/pois päältä/oletus (vaihtoehdot määriteltävissä)
PIN-koodin vaihtamispyyntö
- uusi PIN-koodi
- vanha PIN-koodi (tarvittaessa, myös Finna voi tarkistaa)
Vastauksessa:
- tieto onnistumisesta
Lainat
Lainojen haussa on tuettava sivutusta ja erilaisia järjestämisvaihtoehtoja, mikäli pitkän lainalistauksen hakeminen kirjastojärjestelmästä on hidasta.
Haettavat tiedot:
- lainan id
- bibliografisen tietueen id
- niteen id
- eräpäivä
- tila (lainassa/myöhässä tms.)
- volyymi
- julkaisuvuosi
- nimeke
- uusimiskertojen lukumäärä
- uusimiskertojen maksimimäärä
- onko laina uusittavissa
- mahdollinen viesti asiakkaalle
- kaukolainat:
- instituution tunniste
- instituution nimi
- instituution avain
Lainojen uusimispyyntö
Lainakohtaisesti:
- lainan id
- onnistuminen (bool)
- viesti onnistumisesta
- uusi eräpäivä
Vastauksessa:
- tieto onnistumisesta
Varaukset
Haettavat tiedot:
- varauksen id
- bibliografisen tietueen id
- niteen id (jos nidekohtainen varaus)
- tyyppi
- noutopaikka
- vanhentunut (bool)
- vanhentumisaika
- luontiaika
- sijainti varausjonossa
- noudettavissa (bool)
- matkalla noutopisteeseen (bool)
- onko varaus jäädytetty (inaktiivinen)
- onko varaus muokattavissa (yleensä muokattavissa kunnes matkalla noutopisteeseen tai noudettavissa)
- volyymi
- julkaisuvuosi
- nimeke
- kaukolainapyynnöt:
- instituution tunniste
- instituution nimi
- instituution avain
Varauksen tekopyyntö
- mahdollisten noutopisteiden haku
- noutopaikka
- Joko yksittäinen piste tai varausryhmän ja noutopaikan yhdistelmä
- varauksen tyyppi
- bibliografisen tietueen id
- niteen id (jos nidekohtainen varaus)
- viimeinen voimassaolopäivä
- mahdollinen kommentti
Vastauksessa:
- tieto onnistumisesta
Varauksen perumispyyntö
- varauksen id tms.
Vastauksessa:
- tieto onnistumisesta
Varauksen noutopaikan vaihtamispyyntö
- varauksen id tms.
- uusi noutopaikka
Vastauksessa:
- tieto onnistumisesta
Varauksen jäädytys- tai vapautuspyyntö
- varauksen id tms.
- uusi tila
Vastauksessa:
- tieto onnistumisesta
Varausryhmien haku
Varausta tehtäessä voidaan välittää kirjastojärjestelmälle asiakkaan ja varauksen tiedot.
Haettavat tiedot:
- varausryhmän id
- varausryhmän nimi
Noutopaikkojen haku
Varausta tehtäessä voidaan välittää kirjastojärjestelmälle asiakkaan, varauksen ja mahdollisen varausryhmän tiedot, jos ne vaikuttavat noutopaikkalistaukseen.
Haettavat tiedot:
- noutopaikan id
- noutopaikan nimi
Varastotilaukset
Haettavat tiedot:
- varastotilauksen id
- bibliografisen tietueen id
- niteen id (jos nidekohtainen)
- tila
- viimeksi päivitetty
- noutopaikka
- luontiaika
- käsittelyaika
- vanhentunut (bool)
- vastausviesti
- sijainti jonossa
- noudettavissa (bool)
- peruttu (bool)
- volyymi
- issue
- vuosi
- nimeke
- käsitelty (bool)
- kaukolainapyynnöt:
- instituution tunniste
- instituution nimi
- instituution avain
Varastotilauksen tekopyyntö
- kuten varauksen teko
Varastotilauksen perumispyyntö
- varastotilauksen id tms.
Vastauksessa:
- tieto onnistumisesta
Lainaushistoria
Lainaushistorian haussa on tuettava sivutusta ja erilaisia järjestämisvaihtoehtoja. Lainaushistorian tallentamiseen tarvitaan normaalisti käyttäjän lupa.
Lainaushistoriassa olevista lainoista toivottavat tiedot:
- lainan id
- bibliografisen tietueen id
- niteen id
- nimeke
- numerointitieto (esim. lehden vuosikerta ja numero)
- lainauspäivä
- eräpäivä
- palautuspäivä
- uusimiskertojen määrä
- mahdollinen tilatieto
Lainaushistorian tallennuksen tilan vaihtamispyyntö
- uusi tila
Lainaushistorian tyhjentämispyyntö
Maksut
Haettavat tiedot:
- maksun id
- maksun tyyppi
- bibliografisen tietueen id (tarvittaessa)
- niteen id (tarvittaessa)
- maksun päivämäärä
- maksun määrä
- maksettavaa jäljellä
- kuvaus
- kirjasto (tiliöintiä varten)
- maksettavissa verkossa (bool)
Verkkomaksamispyyntö
- maksettava summa
- transaktion tunniste
Vastauksessa:
- tieto onnistumisesta
Kaukolainapyynnöt
Kaukolainatilaukset ovat käytettävissä vain Voyagerissa (UB-toiminnallisuus). Kaukolainatilaukset sisältyvät varauksiin tai varastotilauksiin vähän tilan mukaan (Voyagerin erikoisuus).
