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).

 

 

  • No labels