Integraatiot - KohaSuomi/Koha GitHub Wiki

Tässä dokumentissa kerrotaan, miten integraatiot Kohaan hoidetaan, miten integraatioihin käytettäviä rajapintoja avataan ja suljetaan sekä listataan erilaiset integraatiot kimpoittain.

Kohaan tehtävien integraatioiden kehitys ja käyttöönotot alkavat aina "kick-off" palaverilla, jossa paikalla ovat ainakin kirjaston edustajat, integroitavan järjestelmän toimittaja (tai toimittajat), kimpan pääkäyttäjä sekä Koha-Suomen edustaja. Integraatioihin voi liittyä mm. tietoturvaan, tietosuojaan ja palvelinkuorman hallintaan liittyviä näkökohtia, jotka täytyy käydä läpi. Kick-offissa voidaan päättää keitä mahdollisissa jatkopalavereissa on tarpeen olla mukana, hahmotella alustavasti tarkotuksenmukainen toteutustapa halutulle integraatiolle, sekä aikatauluttaa ja vastuuttaa integraatioon liittyvät tehtävät.

Automaattien ja ovikoneiden kytkemiseksi Kohaan kick-offia ei tarvita. Siihen on olemassa hyvin vakiintunut toimintamalli, joka on kuvattu erillisessä SIP2-tunnusten käsittelyohjeessa.

Rajapintojen avaaminen ja sulkeminen

Integraation tyypistä riippuen voidaan tarvita erilaisia toimenpiteitä. Rajapintaosoitteet saa tarvittaessa Koha-Suomelta. Muista aina päivittää Integraatiot-dokumentti ja informoida Koha-Suomea mahdollisista integraatioiden muutoksista.

Rajapintojen avaaminen

  • Jos integraatioon käytetään borrowers/status rajapintaa, pelkkä rajapintaosoitteiden toimittaminen integroitavan järjestelmän toimittajalle riittää.
  • Jos integraatioon käytetään oauthia + patrons/* (tai muita) endpointteja, tarvitaan riittävillä oikeuksilla oleva käyttäjätunnus ja sille API-avaimet eli client id (asiakkaan tunnus) ja client secret (avain), kumpikin tarvitaan. Pääkäyttäjä voi luoda nämä ja toimittaa salattuna ne integroitavan järjestelmän toimittajalle.
  • Jos integraatioon käytetään SIP2oHTTPS:ää, pääkäyttäjä luo tunnuksen automaatille/ovikoneelle/Smartboxille SIP2-tunnusten käsittelyohjeen mukaisesti.
  • Jos integraatioon käytetään Finna-APIa, täytyy asia hoitaa Finnan ja/tai palveluntarjoajan kanssa. Pääkäyttäjät tai Finna-pääkäyttäjät voivat hoitaa tämän. Kohan päässä palvelun tai laitteen käyttöönotto ei aiheuta toimenpiteitä.
  • Jos asiakkaan tunnistautuminen perustuu korttiavaruuteen tai korttisarjaan, täytyy asia hoitaa palveluntarjoajan päässä. Varsinaista integraatiota Kohaan ei tässä tapauksessa ole eikä palvelun tai laitteen käyttöönotto aiheuta toimenpiteitä Kohan päässä.

Integraatioiden tarvitsemat oikeudet

  • Finna (Discovery interface)
  • Kaupunkisovellus (Hion Digital)
    • remaining_circulation_permissions
    • catalogue
    • view_borrower_infos_from_any_libraries
    • reserveforothers
  • Kellutin
    • catalogue
    • report
  • Puppe
    • catalogue
    • editcatalogue
    • budget_manage_all
    • order_manage
    • order_manage_all
    • vendors_manage
  • Tunnistamo
    • borrowers
  • Webkake
    • remaining_circulation_permissions
    • borrowers

Rajapintojen sulkeminen

Joissain tapauksissa integroituja palveluja tai laitteita voi poistua käytöstä. Alapuolella tällaisten tapausten varalle toimintaohjeet.

  • Jos integraatioon käytetään borrowers/status rajapintaa, on sulkeminen aina palveluntarjoajan homma. Kohan päästä palvelun tai laitteen poistaminen käytöstä ei aiheuta toimenpiteitä.
  • Jos integraatioon käytetään oauthia + patrons/* (tai muita) endpointteja, niin sulkeminen voidaan tehdä perumalla palveluun tai laitteeseen liitetyn käyttäjätunnuksen API-avain tai poistamalla tunnus Kohasta. Pääkäyttäjät voivat hoitaa tämän.
  • Jos integraatioon käytetään SIP2oHTTPS:ää, voidaan palvelun tai laitteen käyttämä tunnus poistaa Kohasta. Pääkäyttäjät voivat poistaa tunnuksen. Tässä tapauksessa tarvitsee avata myös tiketti tunnuksen poistamisesta, jotta tunnus voidaan poistaa myös SIP-palvelimelta. Jos tunnus halutaan säilyttää lokitietoja varten, voi siltä ottaa pois käyttäjäoikeudet, vaihtaa salasanan ja merkitä huomautuksiin, että tunnus ei ole käytössä.
  • Jos integraatioon käytetään Finna-APIa, täytyy asia hoitaa Finnan ja/tai palveluntarjoajan kanssa. Pääkäyttäjät tai Finna-pääkäyttäjät voivat hoitaa tämän. Kohan päässä palvelun tai laitteen poistaminen käytöstä ei aiheuta toimenpiteitä.
  • Jos asiakkaan tunnistautuminen perustuu korttiavaruuteen tai korttisarjaan, täytyy asia hoitaa palveluntarjoajan päässä. Varsinaista integraatiota Kohaan ei tässä tapauksessa ole eikä palvelun tai laitteen poistaminen käytöstä aiheuta toimenpiteitä Kohan päässä.

Kimppojen integraatiot

Alapuolella on listattuna Koha-kimppojen järjestelmäintegraatiot kimpoittain.

Helle

Koha-API

  • eBooking - Koha-API sipmessages
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Hublet - Koha-API borrowers/status
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages / IPSEC SIP2
  • Kirjastokino - Koha-API borrowers/status
  • Viddla - Koha-API borrowers/status
  • WebKake - Koha-API

Finna-API

  • Biblio - Finna-API
  • Medici.tv - Finna-API
  • PressReader - Finna API

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX

Asiakasviestintä

  • Kirjeet - Print plugin, ei integraatiota
  • Sähköpostit - Postfix relay, palvelukanava.fi
  • Tekstiviestit - Telia

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota
  • Naxos Music Library Jazz - korttiavaruus, ei integraatiota
  • Naxos Music Library World - korttiavaruus, ei integraatiota

Kirkes

Koha-API

  • eMagz - Koha API borrowers/status
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Cineast - Koha-API borrowers/status
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages

Finna-API

  • Medici-TV - Finna-API
  • Rockway - Finna-API
  • Ebooking - Finna-API
  • Ellibs - Finna-API

Hankinta

  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX
  • Hankintaportaali - EDItX

Asiakasviestintä

  • Kirjeet (Suomi.fi) - KSMessaging, iPostPDF
  • Sähköpostit - Postfix relay, palvelukanava.fi
  • Tekstiviestit - Telia Kontakti SMS Sovellusten viestintäpalvelu

Raportteri

  • Järvenpään kaupungin tiedolla johtamisen palvelu

Laskutus

  • Lowell/Keravan kaupunki
  • Sarastia/Järvenpään kaupunki
  • Provincia/Mäntsälän kunta
  • Monetra/Tuusulan kunta

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota
  • Naxos Music Library Jazz - korttiavaruus, ei integraatiota
  • Naxos Music Library World - korttiavaruus, ei integraatiota
  • Naxos Video Library - korttiavaruus, ei integraatiota
  • Epress sanomalehdet - käytössä vain kirjaston koneilla

Kyyti

Finna-API

  • PressReader - Finna API

Koha-API

  • Finna Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Haminan kaupunkisovellus (Hion Digital [ent. Geniem oy]) - Koha-API ?
  • Cineast - Koha-API borrowers/status
  • Kouvolan kaupunkisovellus (Punosmobile) - Koha-API borrower/status
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages
  • Varaamo (Kouvola) - Koha-API borrower/status
  • Kirjastokorttitulostus (Kouvola, Kotka) - Koha-API borrowers/status, Canon
  • Hublet (Kotka) - Koha-API borrowers/status

Hankinta

  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa EDItX
  • Hankintaportaali EDItX

Asiakasviestintä

  • Kirjeet - KSMessaging iPost/EPL, Posti Messaging / Print-plugin, ei integraatiota
  • Tekstiviestit - ArenaInteractive oy
  • Sähköpostit - Postfix relay, palvelukanava.fi

Lappi (10/2024)

Koha-API

  • Ceepos - Koha-API
  • eMagz - Koha-API borrowers/status
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Hublet - Koha-API borrowers/status
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages
  • Varaamo - Koha-API borrowers/status
  • Cineast - Koha-API borrower/status
  • WebKake - Koha-API

Finna-API

  • Ellibs - Finna-API
  • Medici.tv - Finna-API
  • OverDrive - Finna API
  • PressReader - Finna API
  • Rockway - Finna-API
  • ePress - IP-tunnistautuminen

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX

Asiakasviestintä

  • Tekstiviestit - Link Mobility
  • Kirjeet - KSMessaging iPostEPL, Posti messaging
  • Sähköpostit - Postfix relay, palvelukanava.fi

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota

Lastu

Koha-API

  • Cineast - Koha-API borrowers/status
  • Hublet - Koha-API borrowers/status
  • Finna - Koha-API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Lainaus- ja palautusautomaatit sekä ovikoneet (Lyngsoe & Mikro-Väylä) - Koha-API sipmessages
  • Puppe - Koha-API
  • Timmi - Koha-API borrowers/status

Finna-API

  • eBooking
  • PressReader

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus
  • Naxos Music Library Jazz - korttiavaruus
  • Rockway - korttiavaruus

Asiakasviestintä

  • Tekstiviestit - DNA
  • Kirjeet - Suomi.fi - KSMessaging/iPostPDF
  • Sähköpostit - Postfix relay, palvelukanava.fi

Lumme

Koha-API

  • eBooking: Koha-API sipmessages
  • ePress - Koha-API borrowers/status
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Hublet - Koha-API borrowers/status
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages
  • Cineast - Koha-API borrowers/status
  • Puppe (hankinnan saapumiskäsittely) - Koha-API acquisitions/funds, acquisitions/orders

Finna-API

  • PressReader - Finna API

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX

Asiakasviestintä

  • Kirjeet - KSMessaging iPostPDF, Posti messaging
  • Tekstiviestit - Link Mobility
  • Sähköpostit - Postfix relay, palvelukanava.fi

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota
  • Naxos Music Library Jazz - korttiavaruus, ei integraatiota
  • RedFox-sanakirjapalvelu -korttiavaruus, ei integraatiota

OUTI (8/2024)

Koha-API

  • Ceepos - Koha-API
  • eMagz - Koha-API borrower/status
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha-API sipmessages
  • Cineast - Koha-API borrower/status
  • Varaamo - Koha-API borrower/status
  • WebKake - Koha-API

Finna-API

  • Ellibs - Finna API
  • Medici.tv - Finna API
  • OverDrive - Finna API
  • PressReader - Finna API
  • Rockway - Finna API
  • ePress - IP-tunnistautuminen

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX
  • Puppe-tilaustenvastaanottotyökalu - Koha-API

Asiakasviestintä

  • Kirjeet - KSMessaging iPostEPL, Posti messaging
  • Tekstiviestit - Link Mobility
  • Sähköpostit - Postfix relay, palvelukanava.fi

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota

Siili

Koha-API

  • Finna - Koha-API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Siilinjärvi kuntasovellus (ent. Geniem Oy, nyk. Hion Digital Oy) - Koha-API
  • Lainaus- ja palautusautomaatit - Koha-API sipmessages
  • Viddla - Koha-API borrowers/status

Hankinta

  • Hankintaportaali - EDItX

Asiakasviestintä

  • Sähköpostit - Postfix relay, palvelukanava.fi
  • Tekstiviestit - LINK Mobility
  • Kirjeet - Print-plugin, ei integraatioita

Vaara

Koha-API

  • Ceepos - Koha-API
  • Cineast - Koha-API borrowers/status
  • Finna - Koha API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Joensuun kaupunkisovellus (HionDigital) - Koha-API
  • Lainaus- ja palautusautomaatit sekä ovikoneet - Koha API sipmessages, IPSEC/SIP2
  • Hublet - Koha-API borrower/status
  • Toveri-ovikoneet - Koha-API sstatus, Toveri-plugin
  • WebKake - Koha-API

Finna-API

  • PressReader - Finna API
  • Rockway-musiikkikoulu - Finna API

Hankinta

  • Hankintaportaali - EDItX
  • Kirjastopalvelun verkkokauppa - EDItX
  • Kirjavälityksen verkkokauppa - EDItX

Asiakasviestintä

  • Tekstiviestit - LinkMobility
  • Sähköposti - Postfix relay, palvelukanava.fi
  • Suomi.fi - KSMessaging/iPostPDF
  • Kirjeet - KSMessaging/iPostEPL, Ropo Capital

Muut (ei integraatiota)

  • Naxos Music Library - korttiavaruus, ei integraatiota
  • Naxos Music Library Jazz - korttiavaruus, ei integraatiota
  • Naxos Video Library - korttiavaruus, ei integraatiota

Vaski

Koha-API

  • Cineast - Koha-API borrowers/status
  • E-booking - Koha-API borrowers/status
  • Finna - Koha-API, kirjautuneen käyttäjän toiminnot ja saatavuustiedot / OAI-PMH
  • Hublet - Koha-API borrowers/status
  • Kirjastokorttitulostus - Koha-API borrowers/status, Canon
  • Lainaus- ja palautusautomaatit ja ovikoneet - Koha-API sipmessages, IPSEC/SIP2
  • Optima Locker - Koha-API borrowers/status
  • Puppe (hankinnan saapumiskäsittely) - Koha-API acquisitions/funds, acquisitions/orders
  • Tunnistamo - Koha-API oauth, patrons/*

Finna-API

  • PressReader - Finna-API
  • Promentor - Finna-API
  • Rockway - Finna-API

Hankinta

  • Kirjastopalvelun verkkokauppa (Aarre) - EDItX
  • Kirjavälityksen verkkokauppa (Kirjaväylä) - EDItX
  • Hankintaportaali - EDItX

Asiakasviestintä

  • Tekstiviestit - DNA
  • Sähköposti - Postfix relay, palvelukanava.fi
  • Kirjeet - KSMessaging iPostEPL, Posti Messaging

Laskutus

  • Revire (ent. Suomen Kuntaperintä) ja Svea-perintä - Finvoice3

Raportteri

  • Turun kaupungin Tietovarasto
  • Kellutin (Weasel)
  • Harava-ohjelma