KohaSuomiServices-mikropalvelut¶

• Table of contents
• KohaSuomiServices-mikropalvelut
  • Käyttöohje
    • Biblio exporter
    • Koha-käyttäjätunnuksen ja Melinda-tunnuksen kytkeminen toisiinsa
    • Vastauksen käsittely
    • Kenttätäsmäytykset
    • Siirtoraportit
  • Tietueiden automaattinen valutus Tätistä paikalliskantaan
    • Määrittelyt Kohassa
      • 1. KohaSuomiServices-mikropalvelu yhdistetään Kohaan Broadcastbiblios-plugin avulla.
      • 2. Säilytä alkuperäiset kentät Kohassa
      • 3. Tee valutusta varten käyttäjätunnus
      • 4. Anna käyttäjille oikeus katsoa siirtoraporttia
    • Siirtoraportti järjestelmään valutuksesta.
    • "Tarkista aktivointi"-välilehti lisätty 09.06.2021. Hae aktivointia tietuenumerolla.
    • "Ilmoita kentistä"-asetus lisätty 23.6.2021
    • Ilmoittaminen osakentästä lisätty 29.9.2021
    • Aktivoinnin poistaminen lisätty 29.9.2021
    • Tietueen etsiminen raportilta lisätty 29.9.2021
  • Ongelmatilanteita
    • Tietue täsmäytyy Melindassa väärään tietueeseen

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.

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-test.koha-suomi.fi/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.

Voit testata linkityksen onnistumisen klikkaamalla kolmen neliön kuvaketta. Ilmoitus onnistumisesta tai epäonnistumisesta tulee ihan sivun yläreunaan.

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 Broadcastbiblios-plugin 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. Muokkaaminen pakottaa etsimään Tätistä vastaavaa tietuetta ja päivittää sen paikalliskantaan. Tätä voidaan käyttää myös niin, että päivittää aktivoinnin ilman muutoksia niin saadaan Tätistä tietue paikalliskantaan.

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

"Ilmoita kentistä"-asetus lisätty 23.6.2021¶

Siirtoraportin saa ilmoittamaan, jos jokin kenttä esiintyy muutoksissa. Kentät voi määrittää seuraavasti: Siirtoraportti -> Toiminnot -> Määrittely -> Ilmoita kentistä (erota pilkulla)

Raportilla riveillä näkyy ilmoitus.

Ilmoittaminen osakentästä lisätty 29.9.2021¶

Jos samasta kentästä katsotaan useampi osakenttä, niin laita jokainen erikseen esim. 245a,245c jne. Kenttien määritykseen pääsee seuraavasti: Siirtoraportti -> Toiminnot -> Määrittely -> Ilmoita kentistä (erota pilkulla).

Aktivoinnin poistaminen lisätty 29.9.2021¶

Tietueen aktivoinnin voi poistaa Tarkista aktivointi -välilehdellä, kun on ensin hakee tietueen esille tietuenumerolla.

Tietueen etsiminen raportilta lisätty 29.9.2021¶

Tietyn tietueen pystyy hakemaan esille Onnistuneet-välilehdellä listan yläpuolella olevalla haku-laatikolla.

---

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
   
2. Etsi konfliktiin liittyvä rivi ja paina rivin oikeasta reunasta Force-nappia