Primus Integraatio
Movitin Primus integraation käyttöönotto ja ohjeistus
Alustus
Tässä dokumentissa kuvataan asiakasorganisaation, yleisesti kunnan käytössä olevan Primus‑järjestelmän, sekä meidän eli Intoit Oy:n Movit‑järjestelmän välisen integraation käyttöönottoa ja käyttöä.
Primus on Visman ylläpitämä järjestelmä, jota käytetään laajasti kouluissa ja kunnissa. Järjestelmässä ylläpidetään muun muassa oppilaskortteja. Kouluissa käytössä oleva Wilma-järjestelmä toimii Primuksen päällä.
Movitissa käytössä oleva Primus-integraatio mahdollistaa tiedon siirtämisen Primuksen ja Movitin välillä. Integraation avulla tietoa voidaan siirtää joko Primuksesta Movittiin tai molempiin suuntiin kunnan tarpeiden mukaan.
Integraation tarkoituksena on helpottaa tiedon ylläpitämistä sekä varmistaa tiedon oikeellisuus ja ajantasaisuus sekä Primuksessa että Movitissa.
Disclaimer: Integraatiota ja siihen liittyvää käyttöliittymää kehitetään jatkuvasti. Tämän vuoksi on mahdollista, että tässä dokumentissa kuvatut toiminnot tai näkymät poikkeavat osittain järjestelmän nykyisestä versiosta.
Käyttöönotto ja Määritykset
Jokainen Primus integraatio on yksilöllinen, riippunen miten ja missä laajuudessa kunta sitä käyttää. Seuraavassa käydään läpi mitä kaikkea tarvitaan toimivan ja pitä ottaa huomioon integraation käyttöönottoon.
Mahdolliset ongelmatilanteet on myös käyty jäljempänä läpi.
Integraation käyttöönotto
Integraatio ei ole oletusarvoisesti käytössä Movit-instanssissa, vaan se on erillinen feature flag, joka aktivoidaan järjestelmänvalvojan käyttäjätunnuksilla Movit hallinnan kautta. Aktivoinnin jälkeen integraatiota varten tehdään vielä erilliset määritykset (osoite ja portti) kehittäjän toimesta.
Kunnalta tarvitsemme seuraavat tiedot yhteyden muodostamista varten.
- Primus-palvelimen verkko-osoite (esim. leppavirta.inschool.fi)
- Käytettävä portti (esim. 1222, jos poikkeaa oletusarvosta)
Vain kunnalla on pääsy Primukseen, joten kaikki muutokset ja tarkistukset Primukseen täytyy tehdä kunnan työntekijän toimesta.
Primukseen tulee luoda erillinen testi-käyttäjätunnus Movit-integraatiota varten. Yleensä vain kunnan Primus pääkäyttäjällä on tähän tarvittavat oikeudet. Tämä tunnus on vain testaus- ja koulutuskäyttöä varten, jota käytetään tiedonsiirron testaukseen Primuksen ja Movitin välillä sekä asiakkaan koulusta varten. Tunnus voidaan kunnan näin halutessa poistaa, kun integraatio on otettu onnistuneesti käyttöön, mutta poistaminen voi hidastaa mahdollisia häiriöiden selvittämistä tulevaisuudessa. Normaalissa arkikäytössä käytetään aina kunnan käyttäjien omia Primus tunnuksia.
- testikäyttäjälle tulee aina antaa vähintään seuraavat käyttöoikeudet:
o koulut – koulutiedot (vähintään testikoulut)
o lk – luokkarekisteri (vähintään testikoulujen luokat)
o opphenk – oppilastiedot (vähintään testioppilaat)
o kuljetus – kuljetusmuotojen haku (koulukuljetusoppilaiden tunnistaminen)
o liikenne – liikennöitsijät ja autot (reittitiedot, mikäli käytössä)
Kaikilla kunnilla ei ole Primuksessa määriteltynä kuljetusmuotoja. Jos näin on, sovimme erikseen, miten koulukuljetusoppilaat rajataan Movitiin siirrettäväksi.
Mikäli liikennerekisterin tiedot (liikennöitsijät, autot) ovat Primuksessa ajan tasalla, voimme hyödyntää myös näitä tietoja Primusintegraation käytössä.
Määritykset
Kunnat käyttävät Primus-järjestelmää eri tavoilla, eikä sen käyttöön ole olemassa yhtä yhtenäistä toimintamallia. Tästä syystä käyttöön liittyviä variaatioita on yhtä paljon kuin käyttäviä kuntiakin.
Saatavilla on alustava listaus tiedoista, joita Movit hakee integraation kautta sekä tieto siitä, mistä järjestelmän osista tiedot lähtökohtaisesti noudetaan. Tästä huolimatta jokainen integraatio määritellään ja toteutetaan tapauskohtaisesti tällä hetkellä.
Kartoitusvaiheessa käydään kunnan kanssa läpi, mitä tietoja integraation kautta siirretään ja mihin ne kohdistuvat. Tämän jälkeen määritellään, mistä Primuksen kentistä tiedot haetaan ja missä muodossa ne tuodaan Movit-järjestelmään.
Primuksessa oleva kenttäkoodi muodostetaan muodossa K + kentän numero (esim. K1234).
Yllä näkymä Primuksen käyttöliittymästä. Hakasuluissa oleva numero on primuksen kentän numero (K-numero). Tässä esimerkissä on Kivelän koulu Leppävirran kunnassa. Koulun nimi tulee kentästä K2.
Jos kunta ei käytä Lukukaudessa jaksoja, Primukseen on määritettävä vähintään yksi jakso, jotta integraatio voidaan ottaa käyttöön ja se toimii oikein.
Määrityksessä on hyvä tarkistaa, että oppilastyypeissä löytyy kaikki mitä kyseisessä kunnassa on käytössä sekä löytyykö kaikki olemassa olevat koulut ja luokat.
Mikäli kunnalla on Primukseen määritetty apuvälineet, voidaan ne siirtää integraation avulla Movittiin, mutta tämä tulee aina tehdä erikseen kehittäjän kanssa, joka määrittää mistä kentästä tieto tuodaan Movittiin.
Esim. Primuksessa kentässä (K12236, opphenk) Oppilas tarvitsee vastaanottajan kotona Tuodaan meillä täppä kohtaan Vastaanottaja Movitin matkustaprofiiin kohtaan Apuvälineet.
Kaksisuuntainen Integraatio
Mikäli halutaan, että Movit voi myös siirtää tietoja takaisin Primukseen (esimerkiksi
koulumatkojen etäisyydet tai hakuajat), tulee Primukseen määrittää PrimusQuery-siirto alla olevin määrityksin.
- Lisätään uusi määritys PrimusQuery-siirrot-rekisteriin
- Nimi: movit-import
- Kanta: opphenk
- Määritys: Intoit:n toimittama määritystiedosto (erillinen liite).
Määritystiedosto määrittää ne kentät, joihin Movit saa kirjoittaa tietoja Primuksessa.
Kenttälistaus löytyy Primuksesta osoitteesta: https://update.service.inschool.fi/cgibin/kantacgi?opphenk&english
Mahdolliset Ongelmatilanteet
Jos yhteyttä ei saa luotua vaan tulee login failed on yleensä syy seuraavissa.
- Osoite tai portti väärin
o Primuksesta pitää tarkistaa tietojen oikeellisuus
- PrimusQuery ei ole päällä.
o Tämä ei ole oletuksena päällä Primuksessa vaan pitää erikseen käydä aktivoimassa laittamalla täppä oikeaan kohtaan Primuksen asetuksista, jos kunta ei ole sitä aikaisemmin käyttänyt muuhun tarkoitukseen.
- Kaksivaiheinen tunnistus primukseen
o Integraatio ei tällä hetkellä tue kaksivaiheista tunnistautumista ja tähän ainoa ratkaisu on kunnan tehdä erilliset tunnukset Movitin käyttöön ilman kaksivaiheista tunnistautumista. Kaksivaiheinen tunnistautuminen ei yleisesti ole vielä käytössä, mutta yleistyy todennäköisesti lisääntyvien tietoturvavaatimusten myötä.
- Palomuuri estää yhteyden
o Tarvitaan palomuuriin avauksia Visman suuntaan, jolloin kunta on yhteydessä toimittajaan ja pyytää avaamaan kehittäjän ilmoittamat IP-osoitteet.
o Joissakin harvinaisissa tapauksissa syy voi olla internet-protokollassa. Yleisesti käytössä on IPv6 (Internet Protocol version 6) mitä myös Movit käyttää. Jos kunnalla on käytössä IPv4 tarvitaan väliin erillinen yhteyspalvelin, joka käyttää IPv4 standardia.
Jos kirjautuminen onnistuu, mutta järjestelmä antaa virheilmoituksen, syy on yleensä mappauksessa. Tällöin kysely menee teknisesti läpi, mutta paluuviesti on puutteellinen tai virheellinen.
- Jokin kenttä, josta Movit hakee tietoa ei ole käytössä kunnalla tai on tyhjä
o Jos Movitin tekemä kysely tuo tyhjän (null) antaa se herjan
Esim. Error: Primus-listaus ei sisällä yhtään liikennöitsijää
§ Ratkaisu on ohjata kysely käyttämään toista kenttää, jos mahdollista tai kunta ottaa kyseisen kentän käyttöön.
- Tunnuksella, jota käytetään ei ole tarpeeksi oikeuksia
o Primuksessa annetaan tunnukselle tarpeeksi oikeuksia.
- Tunnus on luotu puutteellisesti, jonka vuoksi ei toimi.
o Tunnuksen voi kopioida jo olemassa olevasta toimivasta tunnuksesta, jos tunnuksen kanssa on haasteita.
Jos kirjautuminen onnistuu eikä järjestelmä anna virheilmoitusta, mutta haku ei tuota yhtään tulosta, syynä voi olla edellä mainittu virheellinen mappaus tai käyttäjätunnukseen liittyvä ongelma.
Tilanteessa, jossa haku ei tuota tuloksia tai on vajanainen, mahdollisena syynä voi olla myös koodiin kovakoodattu suodatus, joka tulee tarkistaa kehittäjän toimesta.
Ohjeistus integraation käyttöön
Kirjautuminen
Primus integraatio löytyy yläpalkin lisätoimintojen alta
Järjestelmään kirjaudutaan käyttäjän omilla käyttäjätunnuksilla. Meillä on käytössä yleensä instanssikohtaiset tunnukset, joilla voidaan testata yhteyden toimivuus.
Kirjautumisen yhteydessä valitaan kunta, jonka Primus-järjestelmään yhteys muodostetaan. Tämä valinta on käytettävissä vain, jos samassa instanssissa on useampi integraatio, muussa tapauksessa kenttä on harmaana eikä valittavissa.
Tämän jälkeen syötetään Primus-käyttäjätunnus ja kyseiseen tunnukseen liittyvä salasana, minkä jälkeen siirrytään seuraavaan vaiheeseen. Yhteyden muodostaminen voi kestää hetken. On huomioitava, että Primus-käyttäjätunnus on eri kuin Movit-käyttäjätunnus.
HUOM, kun liikutaan käyttöliittymässä, käytetään alareunassa olevia edellinen vaihe ja seuraava vaihe painikkeilla. Tai vaihtoehtoisesti yläreunassa olevia välilehtiä, mutta ei käytetä selaimen eteen ja taakse -painikkeita.
Tietojen lataus
Seuraavaksi tietojen lataus -välilehti, jossa määritetään mitä tietoa halutaan käsitellä ja hakea Primuksen päästä. Käyttöliittymässä voidaan käsitellä tietoa isommissa ryhmissä tai vain yksittäistä oppilasta.
Oppilastyyppejä on kunnilla yleensä useita, joista osaa ei tarvita kuljetussuunnittelussa, joten oppilaslajin perässä olevasta suppilosta painamalla saa auki seuraavan ikkunan, josta voi määrittää näkymässä näkyvät oppilaslajit. Tämä valinta pysyy muistissa tunnuksella eikä tarvitse erikseen joka kerta tehdä.
Valitaan ensin oppilastyyppi esim. peruskoulu oppilas.
Tämä märittää mistä taulusta haetaan tietoa primuksesta ja valittuna voi olla vain yksi kerrallaan (kunnasta riippuen tämä tieto haetaan kentästä oppilastyyppi tai oppilaslaji).
HUOM, jos tässä valittuna esikoulu ja kouluista koulu, jossa ei esikoulua niin haku ei tuo yhtään tulosta.
Tämän jälkeen, jos valittuna on koulut/luokat tehdään seuraavat suodatukset.
- Suodata matkaoikeudella (hakee ne, joihin kyseisellä tunnuksella oikeudet)
o ei suodatusta
o Hae vain oppilaat, joilla ei ole kuljetusoikeutta Primuksessa
o Hae vain oppilaat, joilla on kuljetusoikeus primuksessa
- Suodata kuljetustyypillä (tarvittaessa, jos käytössä)
o Juna (K3644)
o Bussi (K3645)
o Taksi (K3646)
o Erillinen (K3647)
o Tilausbussi (K3648)
o Muu (K3649)
- Koulut
o Listaa kaikki kunnan koulut
§ Valitaan koulu tai koulut, joista tietoa halutaan hakea.
- Luokat
o Listaa kaikki luokat, joita valituissa kouluissa löytyy
§ pitää valita vähintään yksi, jos ei haluta rajata valitaan kaikki.
§ Jos jollakin luokalla ei ole määritetty yhtään oppilasta näkyy se harmaana
Kun haetaan vain yhden oppilaan tietoja, tarvitaan mistä sitä haetaan eli oppilastyyppi esim. peruskoulu oppilas.
Sukunimi ja etunimi kentät ovat molemmat pakollisia, mutta siihen voi kirjoittaa joko kokonimen tai nimen alkuosat Erkki Esimerkki -> es er.
Jos haku löytää oppilaan tai oppilaita tuo se tuloksen alapuolelle. Jos useampi tulos, valitse oikea tällä kertaa käsiteltävä oppilas.
Koulukuljetusoikeudet
Koulukuljetusoikeudet välilehdellä näkyy oppilaskortilta tulevat tiedot, jotka Primukseen on merkitty sekä tarvittavat Movit tiedot.
- Primus ID
o Primuksessa oleva oppilaan tunniste
- Movit ID
o Jos oppilas löytyy jo Movitista tuo käyttöliittymä Movit ID:n. Jos sarake on tyhjä ei oppilasta ole vielä Movittiin luotu ja tallennuksen jälkeen oppilas luodaan.
- Matkustaja
o Primuksessa oleva matkustajan nimi (Oppilas). Yleensä etunimi tulee Primuksen kentästä (Kxxx) jossa hänen kaikki nimet. Jos Movitissa vain kutsumanimi käytössä ei käyttöliittymä osaa yhdistää tunnuksia vaan tulee dublikaatit oppilaista. Näissä tapauksissa pitää määrittää integraatioon kutsumanimi (K4).
- Koulu
o Oppilaalle Primuksessa määritetty koulu.
Jos oppilaalta puuttuu koulu ei suodatukset löydä oppilasta.
§ HUOM. jos oppilas löytyy Movitista yliajaa Movitissa oleva koulu Primuksen koulun.
- Luokka/Ryhmä
o Oppilaan Primuksessa ylläpidetty luokka. Jos oppilaalle jo määritetty seuraavan lukukauden luokka, näkyy se suluissa alempana.
- Kävelymatkan yläraja
o Alasvetovalikko, jossa vaihtoehtoina ovat 3 km ja 5 km. Kävelymatkan yläraja määräytyy luokka-asteen mukaan siten, että 1.–2. luokkalaisille käytetään 3 km:n rajaa ja tätä ylemmille luokka-asteille 5 km:n rajaa. Tiedon syöttävä henkilö voi kuitenkin tarvittaessa muuttaa valintaa, mikäli katsoo sen tarpeelliseksi.
HUOM, Movit ei tällä hetkellä osaa erottaa peruskoulun ja lukion 1–2 luokan oppilaita, joten järjestelmä antaa oletuksena myös lukio oppilaille 3 km ylärajan.
- Kotiosoite
o Oppilaan Primuksessa määritetty kotiosoite.
- Kävelymatka (km)
o Movit laskee kotiosoitteen ja koulun välisen matkan. Oletuksena on lyhin reitti, mutta sen voi välilehden ylävalikosta vaihtaa suositelluksi reitiksi.
Jos Primuksessa oleva matka poikkeaa Movitin laskemasta näkyy se alempana harmaana tekstinä, joka ylivedetty.
- Reitti
o Sarakkeessa lukee ”näytä kartta” josta aukeaa seuraava ponnahdusikkuna
o Karttanäkymään piirretään reitti valinnan mukaisesti joko suositeltuna reittinä tai lyhimpänä reittinä, jota on mahdollista muuttaa tarvittaessa kohdasta, hae lyhin reitti tai vaihtoehtoisesti hae suositeltu reitti, riippuen kumpi on tällä hetkellä valittuna.
o Karttanäkymässä esitetään lisäksi reittiin liittyvät tiedot, kuten:
§ oppilaan nimi
§ kotiosoite
§ koulun osoite
§ mahdolliset Primukseen kirjatut lisätiedot kuljetussuunnittelijalle
o Karttanäkymässä voidaan myös tehdä koulukuljetuspäätös (Koulukuljetuksessa). Koulukuljetuspäätös on mahdollista tehdä vaihtoehtoisesti jo edellisessä vaiheessa ilman karttanäkymän avaamista.
o Näkymään voi saada myös seuraavat optiot, jotka aktivoidaan kartan yläreunan painikkeilla.
§ Julkisen liikenteen pysäkit.
Riippuen missä kunnan aikataulut on ylläpidetty, voidaan tehdä integraatio joko Digitransitiin tai Digiroadiin tai molemmat kunnan näin halutessaan
§ Vaaralliset tiet (koululiitu.fi)
Tätä varten tarvitaan kunnan xxx tiedosto.
HUOM. Movit ei osaa käyttää tätä tietoa, kun laskee koulumatkaa vaan kyseessä on graaffinen lisäys, joka auttaa hahmottamaan mahdollisia vaarallisia tieosuuksia.
- Koulukuljetuksessa
o Onko oppilas oikeutettu koulukuljetukseen (kyllä/ei) ja mikä mahdollinen kuljetuksen muoto Primukseen on määritetty.
Lukujärjestys
Lukujärjestyksessä tuodaan oppilaiden primuksessa ylläpidetyt kouluajat.
Ylhäältä valitaan vetovalikosta oikea jakso.
Jos tämä on Primuksessa väärin ylläpidetty tuo integraatio väärät lukujärjestykset tai ei tuo ollenkaan. Jakso tuodaan kentästä Kxxxx.
Huom. Kunnat ylläpitää lukujärjestyksiä Kurre-järjestelmässä.
- Lukujärjestykset pitää siirtää Kurresta manuaalisesti Primukseen jaksoittain, jotta lukujärjestykset näkyvän Movitissa oikein.
Näkymässä on oppilaan nimi, Koulu, luokka sekä viikon koulupäivän alku- ja loppuajat.
Kyseisessä näkymässä voi myös muokata aikoja manuaalisesti tarpeen vaatiessa.
Primuksesta importoitu lukujärjestys tulee näkyviin matkustajan profiiliin matkojen alapuolelle.
Yllä esimerkki Movitin matkustajaprofiilissa olevasta lukujärjestyksestä.
Koulumatkat
Koulumatkat ja matkatyyppi -välilehdellä määritetään millä mahdollisella matkatyypillä (julkinen/kuljetus) oppilas kulkee koulumatkat.
Määritykset voi tehdä päiväkohtaisesti sekä matkakohtaisesti. Valitsemalla yksittäisten päivien kohdalla tai oikeasta sivusta voi valita kaikki päivät.
Esim. oppilas kulkee julkisilla, mutta keskiviikkona loppuu myöhemmin, jolloin julkiset ei enää kulje, joten hänelle myönnetty keskiviikko iltapäivälle taksikuljetus. Tällöin hänellä on keskiviikon paluumatkaa lukuun ottamatta julkinen liikenne.
Jos käyttöliittymään on tehty integraatio julkisen liikenteen aikatauluihin (digiroad tai digitransit) saadaan arvioitu matka-aika julkisilla näkyviin koulumatkat -välilehdelle painamalla ”hae julkisen liikenteen aikataulut” painiketta.
Tällöin Movit laskee aikataulujen perusteella mahdollisen matka-ajan.
HUOM. Vaikka matkoja voi käyttöliittymässä katsoa viikkokohtaisesti ei Tällä hetkellä voi käyttöliittymässä tehdä muutoksia viikkokohtaisesto vaan muutokset tapahtuvat aina kaikkiin päiviin tulevaisuuteen tästä hetkestä alkaen.
Tarvittaessa päivä ja viikkokohtaiset muutokset tehdään suoraan Movitin matkustajaprofiiliin.
Tietojen tallennus
Jotta tieto tallennetaan pitää lopuksi määrittää mitä tietoa ja minne tallennetaan.
Näkymässä valitaan tiedon siirtosuunta, jos kunnassa käytetään, kaksisuuntaista tiedonsiirtoa. Muussa tapauksessa integraatio on vain Primuksesta Movittiin.
Yhteenvedossa näkyy mitä tietoa ollaan tallentamassa sekä tässä näkymässä voi vielä valita mitä tietoja tallennetaan.
Yllä olevassa esimerkissä ylimmän oppilaan matkustajaprofiili on jo olemassa Movit-järjestelmässä, minkä vuoksi sillä on valmiiksi Movit ID. Tässä tapauksessa uutta tunnusta ei luoda, vaan ainoana muutoksena päivitetään lukujärjestys.
Kahta alimmaista matkustajaprofiilia ei puolestaan ole vielä luotu Movitiin, joten tallennuksen yhteydessä järjestelmä luo niille uudet matkustajaprofiilit Movitiin.
Keskimmäistä profiilia ei ole valittu tallennettavaksi, minkä vuoksi sen tietoja ei siirretä eikä tallenneta. Tämä näkyy käyttöliittymässä harmaana ja yliviivattuna.
Kun olet varmistanut, että näkymä on oikea, voit tallentaa tiedon painamalla oikeassa alakulmassa olevaa tallenna-näppäintä.
Järjestelmä antaa vielä kuittauksen ponnahdusikkunalla, kun tiedonsiirto on tehty.
HUOM. On hyvä tarkistaa latauksen jälkeen Movitin matkustajalistauksesta, että kaikki tieto on siirtynyt eikä esim. osoitteita puutu (voi olla ongelma kaksikielisillä alueilla).
Oppilaasta siirtyy integraation kautta seuraavat tiedot
- Nimi
- Puhelinnumero
o Vain ensisijainen numero.
§ Jos oppilaan profiiliin tarvitaan enemmän numeroita voi ne lisätä manuaalisesti suoraan Movitin käyttöliittymästä tai excel importin kautta
- Sähköposti
o Jos Primukseen lisätty
- Profiilitieto kuljettajalle
o Jos Primukseen lisätty
- Muistiinpanot (ajojärjestelijälle)
o Jos Primukseen lisätty
- Luokka
- Pääkohde
- Kotiosoite
- Apuvälineet
o Jos mappaus tehty ja Primukseen lisätty
Näiden lisäksi integraation kautta siirtyy aiemmin mainittu lukujärjestys sekä mahdolliset kunnan kanssa erikseen määritetyt tiedot.