Projekti

Yleinen

Profile

EditX-hankinta

Tutustu myös vanhempaan dokumenttiin: EditX-käyttöönotto

EditX on avoimiin standardeihin perustuva ja helposti laajennettava tapa siirtää tietoja aineistontoimittajien ja Kohan välillä. Sen avulla pystytään toimimaan Kohan hankinnan suhteen samalla tavalla riippumatta aineistontoimittajasta.


1. Käyttöönotto Kohassa

Kohassa pitää tehdä seuraavia määrityksiä, jotta tietueiden yhdistely ja tilaussanomien käsittely toimii oikein.

1.1 Tilit ja korit

Kohaan on määriteltävä tietynmuotoiset tilit. Tilien tilikoodi pitää olla muodossa kirjastolyhenne - hyllypaikkalyhenne - budjettivuosi, esim.

OUPKAIK2019
OUPK = kirjaston lyhenne Kohassa
AIK = hyllypaikan lyhenne
2019 = budjettivuosi

OUPKLN2019
OUPK = Oulun kaupungin pääkirjasto
LN = Lasten ja nuorten hyllypaikka
2019 = budjettivuosi

MUPKAIK2019
MUPK = Muhoksen kirjasto
AIK = Aikuisten hyllypaikka
2019 = budjettivuosi

Huomioitavaa: EditX-tilauksissa käytettävien tilien täytyy olla hyllypaikan mukaisia. Ei voida käyttää esim. AV-tiliä, jos sen nimistä hyllypaikkaa ei ole olemassa Kohassa.

Tilien luonnissa on mahdollista tehdä
  • Joka vuosi uudet tilit samassa muodossa, vain vuosiluku vaihtuu.
  • Ikitilit, jotka ovat nimensä mukaisesti "ikuisesti" voimassa, esim. OUPKAIK2999. Vuosiluku on tässäkin tapauksessa oltava mukana.

Toimittaja luo verkkokauppaansa tilejä vastaavat korit. Katso tarkempi ohje kohdasta Käyttöönotto aineistontoimittajan verkkokaupassa. Korin nimi on vapaa, mutta tilin Koha-tilikoodi täytyy tulla tilaussanomassa FundNumber-elementissä. Esim.

Kori: AIK2019
FundNumber: OUPKAIK2019

Yhdellä korilla tilataan yhdelle kirjastolle ja yhdelle hyllypaikalle. Verkkokaupassa on siis oltava kori jokaiselle hyllypaikalle, jolle tilataan.

1.2 Kohan toimittajatieto

Kohassa pitää olla (kuntakohtainen) toimittajatieto olemassa jokaiselle toimittajalle, jolta aineistoa tilataan, esim. Oulu Kirjastopalvelu. Toimittajan lisääminen

Lisäksi sanomassa oleva aineiston toimittaja pitää liittää Kohan toimittajatietoon. Liitosta varten tarvitaan sanoman VendorAssignedID ja sitä vastaava Koha-aineistotoimittajan id-tunnus. Sen näkee toimittajatiedoissa selaimen osoiteriviltä.

1.2.1 Kohan toimittajatiedon mäppääminen toimittajan asiakastunnukseen

Tulossa: Kohan aineistotoimittajan liittäminen tilaussanoman toimittajatietoon tehdään käyttöliittymässä Hankinnan EDI-tilit sivulla. Sivulle pääsee myös Ylläpito-sivun kautta (Ylläpito → Hankinnan asetukset → EDI-tilit).

Valitse Uusi tili

Täytä seuraavat kohdat

  • Toimittaja: Valitse toimittajatieto alasvetovalikosta.
  • Kuvaus: Kuvaus on vapaaehtoinen.
  • Siirto: Valitse "FILE".
  • Määre: Kenttään valitaan
    • Assigned by supplier (91) käytettäessä sanoman VendorAssignedID:tä
    • Assiegned by buyer (92) käytettäessä sanoman BuyerAssignedID:tä
  • SAN: Kenttään tulee joko VendorAssignedID tai BuyerAssignedID, riippuen siitä, kumpaa halutaan käyttää.
  • Käytössä olevat tilaukset: Laita tähän ruksi. (Suomennos muutetaan myöhemmin.)

Valitse OK.

Lisätty EDI-tili tulee näkyviin EDI-tilien listalle. Olemassaolevia tilejä voi muokata valitsemalla Muokkaa. Tilin voi poistaa Poista-painikkeella.

1.3 Authoriser eli tilauksen luoja

Kohaan täytyy luoda EditX-tilauksille Authoriser. Tämä on Kohan käyttäjätunnus, joka näkyy EditX tilauksissa tilauksen luojana. Tunnus ei tarvitse mitään oikeuksia. Katso Asiakkaan lisäys.

Authoriser:in borrowernumber määritetään EditX-rajapinnan konfiguraatiossa (*anteeksi, jäi kaksi suomenkielistä sanaa). Tämän tekee pyynnöstä järjestelmänkehittäjä.

1.4 Kohan MARC-määritykset

Huomaa: Nämä määritykset on tärkeä tehdä, jotta kuvailutietueiden tuplakontrolli toimii oikein.

Tietueiden täsmäytys tehdään tilaussanoman MARCXML:n ja Kohan tietokannan biblioitems-taulun perusteella. Täsmäytykseen käytetään seuraavia biblioitems-taulun kenttiä:

  • isbn
  • ean
  • publishercode + editionresponsibility

Kohan MARC-määrityksissä pitää olla seuraavat määritykset:

  • ISBN-numero MARC-kentästä 020$a liitetään biblioitems-taulun kenttään isbn.
  • EAN-koodi MARC-kentästä 024$a liitetään biblioitems-taulun kenttään ean. Indikaattoria ei huomioida.
  • Julkaisijan tunnus MARC-kentästä 028$a liitetään biblioitems-taulun kenttään publishercode.
  • Julkaisija MARC-kentästä 028$b liitetään biblioitems-taulun kenttään editionresponsibility.
    • publishercodea ja editionresponsibilityä käytetään täsmäytyksessä aina yhdessä. Vain jos kumpikin täsmää, syntyy vastaavuus.

Aina kun kenttäliitoksia muutetaan, pitää vanhojen tietueiden tiedot päivittää ajan tasalle (misc/batchRebuildBiblioTables.pm --downstream --confirm). Järjestelmänkehittäjä tekee tämän pyynnöstä.

Huomaa: On mahdollista, että liitos näyttäisi olevan paikoillaan, vaikka ei oikeasti olekaan. Tarkista siis aina liitos Muokkaa-painikkeen takaa.

1.5 ONIX-aineistolajien määritys

Kohan tietokannassa on map_productform-taulu, jossa liitetään tilaussanoman ONIX-aineistotyypit Kohan aineistolajeihin. Liitokset tekee järjestelmänkehittäjä heille toimitetun vastaavuuslistan perusteella.

Vastaavuslistan esimerkkitiedosto: Onix-koodit.xlsx


1.6 Tietueiden täsmäytys eli tuplakontrolli

EDItX-sanomista luodaan tilauksen luonnin yhteydessä minitietue kaikista niistä teoksista, joita ei löydy ennestään tietokannasta. EDItX-sanomassa on jokaiselle teokselle kuvailutieto MARCXML-muodossa. Ennen kuin uusi tietue luodaan, tarkistetaan, löytyykö tietokannasta jo kyseinen teos. Vertailuun/täsmäytykseen käytetään biblioitems-taulun ISBN (020$a), EAN (024$a), ja publishercodea (julkaisijan tunnus 028$a) yhdessä editionresponsibilityn (julkaisijan nimen 028$b) kanssa (kumpikin pitää täsmätä). Jos millään standarditunnisteella ei löydy Kohan biblioitems-taulusta, niin luodaan uusi tietue. Jos löytyy vastaavuus, käytetään tilauksen luonnissa kyseistä tietuetta ja niteet luodaan olemassa olevaan tietueeseen.

Tietueiden täsmäytyksessä on tällä hetkellä puute, joka aiheuttaa tuplatietueita tietokantaan. Jos tietueella on biblioitems-taulun ISBN- tai EAN-sarakkeessa kaksi tai useampi tunniste, ei täsmäytys toimi. Jos tunnisteita on useampi, erotetaan ne |-merkillä toisistaan. Täsmäytys pyrkii täsmäyttämään koko sarakkeen sisältöön, jolloin esim. yhdellä ISBN-numerolla haettaessa tieto ei täsmää sarakkeen tietoon. Tästä on tehty kehitysehdotus, että täsmäyttäjä osaisi purkaa sarakkeen sisällön palasiksi ja täsmäyttää tunnisteen kumpaankin/kaikkiin tietoihin erikseen.


2. Käyttöönotto aineistontoimittajan verkkokaupassa

Aineistontoimittajan verkkokaupan täytyy tukea EditX-tilaussanomien lähettämistä. Selvitä asia ennakkoon toimittajasi kanssa. Tällä hetkellä EditX-tilaussanomia käyttää Booky/Kirjastopalvelu, Kirjavälitys sekä Woiman hankintaportaali.

Verkkokaupoissa on tehtävä seuraavat määritykset:

  • tilauskori pitää määrittää EditX-tilaussanomia ”muodostavaksi”
  • tilauskoriin pitää määrittää FundNumber, DeliverToLocation ja DestinationLocation -elementteihin Kohan tilikoodi

Toimittajalta pitää tilata tilauskorit ja niihin pitää tehdä seuraavat määritykset. Esim.

Aikuisten hyllypaikalle: FundNumber, DeliverToLocation ja DestinationLocation OUPKAIK2019
Lasten ja nuorten hyllypaikalle: FundNumber, DeliverToLocation ja DestinationLocation OUPKLN2019
Musiikki-hyllypaikalle: FundNumber, DeliverToLocation ja DestinationLocation OUPKMUS2019

Huomioitavaa: Tili- ja sijoitustiedot ovat sidoksissa toisiinsa. Korien sijoitustietojen on vastattava Kohan kirjastoyksiköitä ja hyllypaikkoja. Sijoitustietona ei voi käyttää esim. OUPKAV2019, jos Kohassa ei ole olemassa AV-hyllypaikkaa.

Järjestelmänkehittäjä toimittaa Koha-palvelimen osoitteen, käyttäjätunnuksen ja salasanan aineistontoimittajille pyynnöstä.

Lisäksi tarvitaan tilaussanomissa oleva VendorAssignedID (toimittajan antama tunniste) tai BuyerAssignedID (kirjaston antama tunniste), jotta tilaukset pystytään muodostamaan Kohassa oikean toimittajatiedon alle. VendorAssignedID:n saa aineistontoimittajilta. BuyerAssignedID:n voi määritellä itse ja pyytää aineistontoimittajaa käyttämään sitä sanomassa.


3. Käyttöönoton määritykset Koha-palvelimella

Järjestelmänkehittäjä tekee nämä määritykset.

3.1 Käyttäjätunnus aineistontoimittajalle

Luo editx käyttäjä Koha-palvelimelle: adduser --shell /usr/sbin/nologin editx

Tätä tunnusta aineistontoimittajat käyttävät toimittaessaan tilaussanomat Koha-palvelimelle. Yhtä ja samaa tunnusta voidaan käyttää yhteisesti kaikille aineistontoimittajille.

Tipauta liiat oikeudet: chmod 360 /home/editx

Käyttäjän tarvitsee ainoastaan pystyä vaihtamaan kotihakemistoonsa ja kirjoittamaan sinne tiedostoja. Tiedostojen lukeminen ei ole tarpeen (toimittajien ei ole tarpeen lukea toistensa tilaussanomia).

Tulevan chrootin takia on hyvä vähän karsia myös /home -haaran oikeuksia. Käyttäjille riittää että he pääsevät /home:n kautta siirtymään kotihakemistoonsa. Ei ole tarpeen nähdä muiden käyttäjätilien kotihakemistojen nimiä saatikka kirjoittaa /home -haaraan mitään: chmod 711 /home

Muuta käyttäjän kotihakemiston sijainti osoittamaan tulevan chrootin juureen (huom! älä siirrä varsinaista kotihakemistoa!): usermod -d /editx editx

3.2 SFTP

Näihin tarvitaan root-oikeudet Koha-palvelimella. Lisää tämä /etc/ssh/sshd_config loppuun:

Match user editx
ChrootDirectory /home
X11Forwarding no
AllowTcpForwarding no
AllowAgentForwarding no
PermitTunnel no
ForceCommand internal-sftp -u 0707

Käyttäjä lukitaan /home -hakemistohaaraan ja ainoastaan ryhmälle jätetään oikeudet luotuihin tiedostoihin. Käynnistä tämän jälkeen sshd-uudelleen, jotta muutokset astuvat voimaan: service ssh restart

3.3 LXC

Valmistele mount bind containeria varten. Lisää containerin config -tiedostoon (root-oikeuksin hostilla) rivi:

lxc.mount.entry = /home/editx /var/lib/lxc/[container]/[rootfs]/home/koha/koha-dev/var/spool/editx/tmp none defaults,bind 0 0

Siirry containerin sisälle ssh [container] tai sudo lxc-attach -n [container], ja luo tarvittavat hakemistot: cd ~/koha-dev/var/spool && mkdir -p editx/tmp editx/load editx/fail editx/archive. Luo hakemistot Koha-käyttäjänä (eli jos siirryit containeriin lxc-attachilla, niin su koha ensin), jotta hakemistojen omistajat asettuvat oikein.

Lisää editx-ryhmä + liitä siihen koha-käyttäjä: sudo sh -c "addgroup --gid [GID] editx && usermod -a -G editx koha"

editx ryhmän GID täytyy olla sama containerin sisällä kuin hostilla. Tarvittaessa GID:tä voi muuttaa sudo groupmod -g [GID] editx -komennolla. Ryhmäoikeuden perusteella koha-käyttäjä saa kaikki oikeudet tilaussanomien käsittelyyn.

Poistu containerista takaisin hostille ja tee vielä containerin uudelleenkäynnistys hostilla: sudo sh -c "lxc-stop -n [container] && lxc-start -d -n [container]" TAI vaihtoehtoisesti editx-hakemiston mount-bind hostilta containerin sisälle: sudo mount --bind /home/editx /var/lib/lxc/[container]/[rootfs]/home/koha/koha-dev/var/spool/editx/tmp.

3.4 Rajapinnan konfigurointi

Konfiguraatio on tiedostossa ~/koha-dev/etc/procurement_config.xml:

<?xml version="1.0"?>
<data>
    <settings>
        <import_tmp_path>/home/koha/koha-dev/var/spool/editx/tmp</import_tmp_path> <!-- The folder where files should be first put. The Integrations external entrypoint -->
        <import_load_path>/home/koha/koha-dev/var/spool/editx/load</import_load_path> <!-- The path from where the script reads files to import -->
        <import_archive_path>/home/koha/koha-dev/var/spool/editx/archive</import_archive_path> <!-- The path where files are archived after succesfull import-->
        <import_failed_path>/home/koha/koha-dev/var/spool/editx/fail</import_failed_path> <!-- The path where files are archived if something fails during import-->
        <authoriser>nnnnnn</authoriser> <!-- A borrowers id (borrowernumber) used in import, change this! -->
        <allowed_locations>LN,AIK,MUS,OU</allowed_locations>
        <automatch_biblios>yes</automatch_biblios> <!-- Set to 'no' if you want to create a new biblio and biblioitem on every order. -->
    </settings>
    <notifications>
        <mailto>osoite1@ouka.fi,osoite2@ouka.fi,osoite3@ouka.fi</mailto> <!-- comma separated list of email-addresses to send error reports to -->
    </notifications>
</data>

Polkuihin ei yleensä tarvitse koskea, oletuspolut toimivat jos käyttöönotto tehdään tässä dokumentissa kuvatulla tavalla. Authoriser on Kohassa määritelty EditX-tilausten luoja (Kohaan tarkoitusta varten lisätyn editx-käyttäjän borrowernumber) ja allowed_locations kertoo mille hyllypaikoille aineistoa voi hankkia. Kuvailutietueiden tuplakontrollin voi halutessaan kytkeä pois muuttamalla automatch_biblios asetukseksi no. Silloin tilatuista nimekkeistä muodostuu aina uudet kuvailutietueet omine niteineen.

Notifications-osan mailto-elementissä määritellään sähköpostitse lähetettävien virhesanomien vastaanottajat.

3.5 Sanomien käsittelyn ja virhehuomautusten ajastus

Lisää seuraavat rivit containerin koha-käyttäjän crontabiin:

*/1 7-22 * * * $KOHA_CRONJOB_TRIGGER cronjobs/runEditXImport.pl
01 06 * * *    $KOHA_CRONJOB_TRIGGER cronjobs/notify-failed-editx.sh

Sanomat käsitellään klo 7.00-22.00 välisenä aikana minuutin välein tai niin nopeassa tahdissa kuin mahdollista. KOHA_CRONJOB_TRIGGER pitää huolen sanomankäsittelyskriptin lukituksesta. Sähköpostihuomautukset virheellisistä sanomista lähetetään kello 6.01 aamuisin.


4. Tilausten seuranta ja virheraportointi

4.1 EDIFACT-sanomat

Huomattavaa: Jotta sanomat voi nähdä, pitää käyttäjätunnuksella olla edi_manage-käyttäjäoikeus.

Tilaussanomien käsittelyn etenemistä voi seurata hankinnan EDIFACT-sanomat -sivulla.


(Kuva vaihdetaan suomenkieliseen)

Kenttien selitteet:

  • Tyyppi kertoo sanoman sisällön muodon (käytännössä aina EDItX).
  • Siirretty kertoo päivän, jolloin sanoma on tullut palvelimelle.
  • Tila kertoo sanoman käsittelyn tilan. Tilakoodit ovat:
    • PROCESSING: käsittely on käynnissä
    • POSTPONED: sanoma on joko virheellinen tai ei ole tullut palvelimelle vielä kokonaan
    • FAILED: käsittely on epäonnistunut
    • OK: käsitelty onnistuneesti
  • Toimittaja-kenttään tulee aineistontoimittajan toimittajatieto, jos sellainen sanomasta löytyy ja se on liitetty Koha-toimittajaan.
  • Tiedot-kentässä on linkki Koha-laskuun (ei käytössä).
  • Tiedostonimi on sanoman tiedostonimi.
  • Toiminnot
    • Katso viesti näyttää sanoman sisällön. Viesti-popparin sisältö on sekava, mutta siitä voi etsiä tarvitsemansa tiedon selaimen hakutoiminnolla (CTRL+F).
    • Poista poistaa rivin EDIFACT-sanomista, mutta ei poista tilausta eikä siihen liittyviä kuvailutietueita, niteitä ja varauksia.

4.2 Virheraportointi sähköpostitse

Virheisiin päättyneiden sanomien käsittelystä on mahdollista saada valittuihin sähköpostiosoitteisiin ilmoitus. Järjestelmänkehittäjä lisää osoitteet osoitelistalle pyydettäessä.

Esimerkkiviesti:

4.3 Erilaisia virhetilanteita

Aina virheviestiin ei saada poimittua järkeviä syitä käsittelyn epäonnistumiselle, mutta alla on muutamia esimerkkejä erilaisista virheviesteistä ja kuinka toimia.

Sanoma odottaa käsittelyä

Toisinaan sanomien käsittelijä ei saa käsiteltyä sanomia ja sanoma jää odottamaan. Tällöin lähetetään seuraavanlainen viesti:

Seuraavat EDItX sanomat odottavat edelleen käsittelyä:

/home/koha/koha-dev/var/spool/editx/tmp/EditxShipNotice_id_2353578_20200722062915.xml

Sanomien siirrossa aineistontoimittajalta Koha-palvelimelle on tapahtunut virhe
ja sanomat ovat puutteellisia.

Puutteelliset sanomat on jätetty hakemistoon /home/koha/koha-dev/var/spool/editx/tmp.

Käsittely voi epäonnistua koska
  • tilaussanoma on tullut palvelimelle sellaiseen aikaan, jolloin sanomia ei käsitellä. Esim. myöhään illalla tai aikaisin aamulla.
    • käy tarkistamassa EDIFACT-sanomat-sivulla hakemalla sanoman tiedostonimellä, onko sanoman käsittely edelleen kesken. Jos sanoman tila on ok, ei tarvitse tehdä korjausliikkeitä.
  • tilaussanoma yritetään ottaa käsittelyyn kesken palvelimelle siirron
    • käy tarkistamassa EDIFACT-sanomat-sivulla hakemalla sanoman tiedostonimellä, onko sanoman käsittely edelleen kesken. Jos sanoman tila on ok, ei tarvitse tehdä korjausliikkeitä.
    • jos sanoman käsittely on epäonnistunut uudelleen, siitä tulee toinen viesti eri syyllä.

Virheellinen tai puuttuva FundNumber

Sanomassa voi olla virheellinen FundNumber eli tilikoodi tai sitten tilikoodi puuttuu Kohasta.

=== Sanoma: LibraryShipNotice_15373634_20200406115217.xml ===

2020-04-06 12.00.04 -- Error was: Cannot insert order: Mandatory parameter budget_id is missing at /home/koha/Koha/Koha/Procurement/OrderProcessor/Order.pm line 37.

Koskee: HEI_PKM2020
  • Jos tilikoodi on väärin sanomassa, pyydä (pääkäyttäjä tai kimpassa asiasta vastaava) aineistontoimittajaa korjaamaan tieto oikeaksi heidän järjestelmässään.
  • Jos tilikoodi on oikein, mutta se puuttuu Kohasta tai on virheellinen, pääkäyttäjä tai kimpassa tileistä vastaava käy lisäämässä tilin tai korjaamassa olemassa olevan oikeaan muotoon.

VendorAssignedID:n mäppäys toimittajaan puuttuu

Jos sanomassa tulee mukana VendorAssignedID, jota ei ole lisätty EDI-tilit sivulle Kohassa, niin tulee seuraava sanoma:

Seuraavien EDItX sanomien käsittelyssä oli ongelmia:

=== Sanoma: portaali_order_20200423103001.xml ===

2020-04-23 10.30.05 -- No vendor for SAN 267139 (qualifier 91) in vendor_edi_accounts.
2020-04-23 10.30.05 -- Error was: Died at /home/koha/Koha/Koha/Procurement/OrderProcessor.pm line 544.

Koskee: RAPKAIK2020
  • Tarkista, onko tunnus (viestissä SAN xxxx) oikein ja lisää (pääkäyttäjä) tarvittava mäppäys EDI-tilit -sivulle
  • jos tunnus on väärin, pyydä (pääkäyttäjä tai muu kimpan vastaava) aineistontoimittajaa korjaamaan VendorAssignedID-tieto

Sanoma ei ole formaatin mukainen tai muuten puutteellinen

Joskus saapuva sanoma on viallinen, eikä ole XML-formaatin mukainen. Sieltä voi myös puuttua jotain pakollisia tietoja. Silloin sähköpostiviesti voi olla epämääräisempi.

=== Sanoma: portaali_order_20200423143002.xml ===

2020-04-23 14.30.05 -- Error was: :2: parser error : Start tag expected, '<' not found

Koskee: <DeliverToLocation/>

Seuraavien EDItX sanomien käsittelyssä oli ongelmia:

=== Sanoma: portaali_order_20200217145002.xml ===

2020-01-02 15.50.04 -- File: /home/koha/koha-dev/var/spool/editx/tmp/portaali_order_20200102155003.xml is not valid XML, processing postponed.
2020-02-17 14.50.07 -- Error was: :2: parser error : Start tag expected, '<' not found

Koskee: KEPKLN2020
  • kehittäjät tarkistaa, onko sanoma XML-formaatin mukainen
  • pääkäyttäjä voi tarkistaa EDIFACT-sivulla avaamalla viestin, puuttuuko sieltä jotain oleellista, kuten FundNumber, DestinationLocation, DeliverToLocation. Sanomaa voi verrata sellaiseen, jonka käsittely on onnistunut.
  • pääkäyttäjä tai kimpan vastaava ilmoittaa aineistontoimittajalle, että sanoma on virheellinen ja pyytää korjaamaan tiedot.