Projekti

Yleinen

Profile

KohaSuomiServices-mikropalvelut

Tällä hetkellä käytössä Tätin kyljessä Melinda siirtoja ja paikallis-Kohia varten. Voidaan asentaa mihin tahansa ja määritellä vaadittavat rajapintayhteydet

https://github.com/KohaSuomi/KohaSuomiServices

Kehittäjän ohjeet
Melindan testausohje
Prosessikaaviot
Virheviestit
Ohjeet kuvailijoille

Sisältö:

  • Biblio exporter - Mikropalvelu, jolla voidaan siirtää luettelointitietoja järjestelmästä toiseen käyttäen SRU- ja REST-rajapintoja.
  • Billing - Tehty vain alustavia suunnitelmia ja rakenteita, kuinka laskuja voisi käsitellä ja lähettää erilaisiin rajapintoihin keskitetysti.

Käyttöohje

Tätin KohaSuomiServices-palveluun pääsee kirjautumaan Tätin superlibrarian tunnuksilla osoitteessa: https://tati.koha-suomi.fi/service
Testiympäristö löytyy https://tati.koha-suomi.fi:8092/service osoitteesta.

Biblio exporter

Biblio exporterissa voidaan konfiguroida jokaiselle järjestelmälle siirtorajapinnat. Konfigurointi tehdään käyttöliittymässä, siinä ensin määritellään rajapinnat ja miten tietoa niihin lähetetään. SRU ja REST-tuntemus auttaa tässä. HUOM!! HOST-arvo vain yhdelle rajapinnalle, sille joka toimii tietueiden keskusvarastona eli meidän tapauksessa Tätille. (Rajoitan tuon lisäämisen monelle, kun palaan töihin) ;)

Parametreistä määritellään rajapinnan endpointiin lähetettävät arvot. SRU käyttää lähinnä "query string"-parametrejä, muita ei tarvita. RESTin parametrit ovat monimutkaisemmat ja esim. urliin voidaan määritellä path-parametri ja muut parametrit osiossa.

Kuvassa Melinda search-rajapinnan parametrit. Haussa käytetään tietueen kenttiä ja ne mäpätään johonkin hakukenttään aaltosulkeilla.

Kuvassa Melindan add-rajapinnan parametrit. Määrittelyt riippuvat vastaanottavasta rajapinnasta, esim. Melinda haluaa autentikaation headerissä basic-muodossa ja marc lähetetään bodyssa json-muodossa.

Koha-käyttäjätunnuksen ja Melinda-tunnuksen kytkeminen toisiinsa

Autentikaatiossa määritellään rajapintaan autentikointi. Jos autentikaatio pitää tehdä toiseen endpointiin, niin endpointin voi määritellä tässä. Muuten syötetään rajapinnan kirjautumistunnukset ja niille voi laittaa käyttäjätunnuslinkityksen. Kohan käyttäjätunnus on mahdollista kytkeä rajapinta tunnukseen, esim. Melinda vaatii jokaiselle kuvailijalle omat tunnukset ja näin Kohan käyttäjä linkitetään Melinda tunnukseen.

Tähän näkymään pääsee painamalla avain-kuvaketta

Vastauksen käsittely

Vastauksen käsittelylle on oma määritelmä. Se tällä hetkellä mahdollistaa jonkun arvon ottamisen REST-vastauksesta, hakemaan sillä vastaava get-endpointista ja päivittämään tietue takaisin Tätiin. Melinda ei vastaa add-endpointista käsiteltyä tietuetta vaan antaa tietueen id-arvon jolla pitää hakea käsitelty tietue ja päivittää takaisin Tätiin.

Kenttätäsmäytykset

Toiseksi määritellään kenttätäsmäytykset. Näillä voidaan määritellä tietueen identiteettikentät, siirrossa poistettavat kentät, tarkistuksessa pakolliset kentät tai tietueeseen lisättävä kenttä.
  • Haut toteutetaan kokonaisella tietueella, joten siitä otetaan tässä määritellyt identifier-arvot SRUn parametreihin. Identifierille voi määritellä arvon, jos haluaa tarkentaa mitä kentässä pitää lukea.

  • Remove-arvolla voidaan poistaa jokin kenttä siirrettävästä tietueesta.
  • Mandatory-arvoa käytettään siirrettävän tietueen tarkistuksessa, esim. jos päivitetään Melindaan tietue niin on hyvä tarkistaa onko omassa Melindan ID (035a).

  • Add-arvolla voidaan lisätä jokin kenttä ja arvo mukaan tietueeseen. Esim. Melindaan halutaan LOW-tägiin sana TATI, joka kertoo mistä järjestelmästä se on tullut. Jos osakenttiä halutaan lisätä enemmän, niin ne erotellaan putkella, kuten kuvassa alempana.

  • Copy-arvolla voidaan kopioida jokin tietueen kenttää toiseen, esim. siirtää BTJ:n 001 ja 003 kenttään 035a. Halutut kentät tulee olla ympyröity aaltosulkeilla ja putki välissä kertoo, että halutaan useampi arvo samaan.

Siirtoraportit

Palvelussa on mahdollista seurata siirtoja kaikkiin palveluihin ja yrittää uudelleen lähetystä. Jos rajapinnassa on force-ominaisuus, niin tämä asetetaan päälle nappia painamalla. Esim. Melindaan on mahdollista pakottaa siirto, jos huomaa konfliktissa olevan tietueen olevan eri.


Tietueiden automaattinen valutus Tätistä paikalliskantaan

Osa rajapinnan toimintaa on ns. tietueiden automaattinen valutus TäTistä paikalliskantaan. Toiminto tarkastelee määritetyllä aikavälillä tietueiden 005-kentän aikaleimoja ja jos tietueen aikaleima muuttuu, "aktivoidaan" se ja tarkistetaan, löytyykö TäTistä siihen samantasoiset tai laajemmat kuvailutiedot. Jos löytyy, niin tietue valutetaan paikalliskantaan.

Käsiteltyjä tietueita voi seurata Raportit-osiossa seuraavan polun takaa löytyvällä siirtoraportilla: Raportit -> Raporttiliitännäiset -> Siirtoraportti -> Aja raportti

Huomioitavia asioita
  • update_totalissues.pl -ajo pitää olla ajastettuna aktivoinnin ulkopuolelle, koska cron päivittää niteiden lainat tietueen 942$0-kenttään, jossa on tietueen kaikki lainat yhteensä ja samalla muuttaa tietueen 005-kentän aikaleiman.
  • UpdateTotalIssuesOnCirc -järjestelmäasetus ei kannata olla päällä, vaan kannattaa käyttää yllä olevaa ajoa lainamäärien päivittämiseen tietueeseen. Muuten tietueiden aikaleimat päivittyy pitkin päivää sitä mukaa, kun niteitä lainataan.

Määrittelyt Kohassa

Alla olevat määritykset pitää tehdä ennen käyttöönottoa.

1. KohaSuomiServices-mikropalvelu yhdistetään Kohaan RemoteAPIs-asetuksen avulla.

  • Self nimiseen rajapintaan määritellään oman järjestelmän tiedot, jos halutaan käyttää tietueiden tuontiin. Esim. jo Melindasta löytyvän tietueen voi tuoda omaan järjestelmään.
  • Määrittelyssä säädetään rajapintayhteys KohaSuomiService-mikropalveluun ja autentikointi, joka on tällä hetkellä toteutettu token-tyyliin. ApiToken tulee olla sama kuin KohaSuomiServicen konffissa. Interface arvo tulee täsmätä KohaSuomiServicessä olevaan rajapintanimeen, johon tietueita halutaan lähettää.
  • Toisiin rajapintoihin halutaan viedä, niin niille tulee määritellä type: export. Self-rajapinnan määrittely mahdollistaa tuonnin, vaikka ei olisi vienti mahdollisuutta.

Määritetyt rajapinnat tulevat näkyviin tietuenäytölle Tallenna-alasvetovalikon alle.

2. Säilytä alkuperäiset kentät Kohassa

Kohaan päivitettäessä on mahdollista säilyttää olemassa olevia arvoja käyttäen yhdistämissääntöä ja Biblio exporterin remove-matcheriä. Kohan update-endpointin voidaan määritellä arvo matcher_id ja haluttu id-arvo, tämä katsotaan Kohan yhdistämissäännöistä. Jos halutaan säilyttää konrollikentät, niin ne tulee määritellä poistettavaksi tuonnissa matcheriin, kuten kuvassa. Jostain syystä Koha ei osaa säilyttää osakentättömiä, vaikka ne matcherissä ovatkin.

HUOM! Tehkää paikallisjärjestelmään ainakin yhdistämissääntö, missä säilytettään 590-599, 856 ja 942. Yhdistämissäännön teko-ohje

3. Tee valutusta varten käyttäjätunnus

Tee valutusta varten käyttäjätunnus, jolla on käyttäjäoikeudet edit_catalogue ja delete_catalogue. Ilmoita tunnukset ja salasana salattuna Johannalle.

4. Anna käyttäjille oikeus katsoa siirtoraporttia

Valutuksen siirtoraportin (ks. alla) katselua varten pitää käyttäjäll olla report-oikeus, joka löytyy käyttäjäoikeuksista plugins-osion alta.

Siirtoraportti järjestelmään valutuksesta.

Valutuksia varten on tehty Koha-plugi, joka asennetaan Kohan plugityökalulla.
Plugin ja ohjeet asentamiseen saa osoitteesta: https://github.com/KohaSuomi/koha-plugin-exporter-report

Plugiin täytyy määritellä asetukset, rajapinnan osoite (https://tati.koha-suomi.fi/service/api/), API-avain (tämä löytyy KohaSuomiService:n konffista) ja Koha-kimpan nimi joka on KohaSuomiService:n asetuksista.

Siirtoraportilta voi nähdä odottavat, onnistuneet ja keskeytyneet tietuesiirrot Koha-kimppaan.

"Tarkista aktivointi"-välilehti lisätty 09.06.2021. Hae aktivointia tietuenumerolla.

Oikealla olevasta napista voi muokata aktivointikenttää ja -arvoa.

Jos tietuetta ei löydy aktivoituna, niin tulee "Not found"-virheilmoitus. Silloin kannattaa käydä tallentamassa tietue ilman muutoksia, jotta se aktivoitaisiin.


Ongelmatilanteita

Tietue täsmäytyy Melindassa väärään tietueeseen

Jos Tätissä oleva tietue täsmäytyy Melindassa väärään tietueeseen (esim. periaatteessa sama teos, mutta vähän eri versio, joka pitää säilyttää omana tietueenaan), eikä tietuetta saa vietyä sen vuoksi Melindaan, on Mikropalvelun ylläpidossa toiminto, jolla voidaan pakottaa tietueen vienti Melindaan. Tämän voi tehdä vain superlibrarian-oikeuksilla olevilla Täti-tunnuksilla.

Käyttäjä saa yleensä virheilmoituksen Conflict ["000503874"] eli konflikti toisen tietueen kanssa, sisältää samoja arvoja. Sulkujen sisällä on yleensä tietueiden id-arvot. (Katso kaikki virheilmoitukset)

  1. Kirjaudu Täti-tunnuksillasi osoitteeseen https://tati.koha-suomi.fi/service/ ja valitse sieltä Biblios -> Reports -> Failed
    Kuva Failed-välilehden näkymästä
  2. Etsi konfliktiin liittyvä rivi ja paina rivin oikeasta reunasta Force-nappia
    Kuva force-nappulasta