Visma Fivaldi Rajapinnat Web Services -rajapinta

Visma Fivaldi Rajapinnat Web Services -rajapinta

2 Sisällys 1 Yleistä... 3 1.1 Muut aiheeseen liittyvät käsikirjat... 3 1.2 Yhteydet muihin Visma Fivaldi -sovelluksiin... 3 2 Toiminnallisuudet... 4 2.1 Autentikointi ja auktorisointi... 4 2.2 Aineistojen validointi... 5 2.3 Tiedostojen tuonti tietokantaan... 5 2.4 Tiedostojen noutaminen tietokannasta... 5 2.5 Kumppanikäyttäjätunnukset... 6 2.6 Siirtomäärien seuranta... 6 3 Käyttöönotto... 7 3.1 Kumppanikäyttäjän lisäyksessä tarvittavat tiedot... 7 3.2 Oikeuksien hallinta palvelunhallinta apuohjelmassa... 8 3.3 XML-siirtojen perustietojen määritys... 10 4 Tietojen siirto... 13 4.1 Tuetut operaatiot... 13

1 Yleistä Web Services -rajapinnan kautta autentikoidut ja auktorisoidut käyttäjät voisivat turvallisesti vastaanottaa ja lähettää XML-muotoisia aineistoja Visma Fivaldin ja ulkoisten sovellusten välillä. Aineistojen sisältö siirretään toteutetun Web Servicen ja sitä kutsuvan sovelluksen välillä Web Service -kanavalla HTTP-protokollalla SOAPsanoman liitteenä. Liitteessä olevan aineiston validointi tapahtuu jo olemassa olevilla tietokantaproseduureilla. Tietoja voidaan lukea yritysrekisteriin, tuoterekisteriin, palkanlaskentaan, tilaustenkäsittelyyn ja osin perustietoihin. Tietoja voidaan hakea yritysrekisteristä, tuoterekisteristä, projektit-rekisteristä, tilaustenkäsittelystä ja kiinteistönhallinnan rekistereistä (henkilötiedot-, huoneistot-, maksulajit-, taloyhtiön perustiedot- ja sidokset-rekistereistä). Rajapintojen tarkoituksena on tehostaa informaatiokulkua kahden tai useamman eri järjestelmän välillä. Jotta voidaan varmistaa, että aineistot siirtyvät ja tallentuvat järjestelmään halutulla tavalla, suosittelemme että rajapinnat otetaan käyttöön aina yhdessä konsulttimme kanssa. Huomioi kuitenkin, että Visma Fivaldin konsultit eivät voi auttaa varsinaisen aineiston muodostamisessa, aineistot pitää aina tehdä itse tai saada kolmannelta osapuolelta. Konsultoinnin tilauslomakkeen löydät täältä, mutta halutessasi konsultointia voi tilata myös suoraan Visma Fivaldin myynnistä. 1.1 Muut aiheeseen liittyvät käsikirjat Visma Fivaldi rajapinnat Visma Payroll -aineistojen tuonti Visma Fivaldiin 1.2 Yhteydet muihin Visma Fivaldi -sovelluksiin XML-aineiston muodostus XML-aineiston sisäänluku XML-siirtojen perustiedot Yritysrekisteri Tuoterekisteri Projektit-rekisteri Tilaustenkäsittely Palkanlaskenta Kiinteistönhallinta 6.6.2019 Visma Software 3

2 Toiminnallisuudet 2.1 Autentikointi ja auktorisointi Web Servicen autentikointi ja auktorisointi on toteutettu OASIS WS-Security UsernameToken -standardilla, jossa salasana on salattu algoritmilla. Vaatimuksena lähettävältä osapuolelta on muodostaa Web Serviceen SOAP-sanoman header-osaan WS-Security-standardin mukainen UsernameToken autentikointi ja auktorisointi. UsernameToken-elementin alielementteinä vaadittavat elementit ovat username, nonce, created sekä password, joka täytyy olla PasswordDigest-tyyppinen. Salasanoja ei pidetä tallessa tai ylläpidetä palvelimella jossa Web Service sijaitsee. Käyttäjätunnuksen autentikointi ja auktorisointi on kaksivaiheinen. Käyttäjätunnuksella ja salasanalla voi olla määritelty oikeudet Web Servicen käyttöön. Lisäksi oikeuksia rajataan yrityksittäin ja aineistotyypeittäin. Aineistotyypeittäin voidaan erikseen antaa oikeudet noutaa ja tuoda sovellukseen. Kirjautuessa tarkistetaan, että itse UsernameToken on muodostettu oikein ja sisältää vaadittavat elementit. Jos näin ei ole, niin autentikointi ja auktorisointi epäonnistuu ja lähettäjälle palautetaan Responce-sanomassa SOAP-sanoma, joka sisältää WS-Security-standardin mukaisen virheen autentikoinnin ja auktorisoinnin epäonnistumisesta. Jos UsernameToken on muodostettu oikein, läpäisee sanoma tässä vaiheessa autentikoinnin ja auktorisoinnin. Varsinainen autentikointi ja auktorisointi toteutetaan tietokantaproseduurissa Web Servicen, operaatioiden sekä haluttujen aineistojen tarkkuudella. Autentikoinnin ensimmäisessä vaiheessa tarkistetaan, onko Web Service -kutsun tehnyt käyttäjä olemassa tietokannassa. Autentikointi suoritetaan kaksiosaisesti. Ensin tarkistetaan, onko tietokannassa olemassa käyttäjä annetulla käyttäjätunnuksella, hakemalla kyseisen käyttäjätunnuksen salasana. Autentikoinnin toisessa vaiheessa tarkistetaan salasanan täsmääminen PasswordDigestin sisältämään salasanaan. Jos annetun käyttäjätunnuksen salasana ei täsmää tietokannassa olevaan salasanaan, auktorisointi epäonnistuu. Epäonnistumisesta muodostetaan Web Serviceä kutsuneen käyttäjän lähettämään Request-sanomaan vastauksena Responce-sanoma, jossa sisältönä on SOAP-sanoma sisältäen WS-Security-standardin mukaisen virhe-elementin autentikoinnin ja auktorisoinnin epäonnistumisesta. Jos auktorisointi onnistuu, niin proseduurissa suoritetaan seuraavaksi auktorisointi jokaisen eri aineiston kohdalla operaation, käyttäjätunnuksen, kantaryhmän, yrityksen ja aineiston tarkkuudella. Jos autentikoidulla käyttäjällä on oikeudet operaatioon kaikkien haluttujen annetussa kantaryhmässä olevan yrityksen aineistojen osalta, onnistuu auktorisointi. Tässä tapauksessa palautetaan lähetettyyn Request-sanomaan Responce-sanoma, jonka sisältö on autentikoinnin ja authorisoinnin onnistumisesta kertova koodi 00 ok. Jos yhdenkin pyydettävän tai tuotavan aineiston kohdalla auktorisointi epäonnistuu, palautetaan Request-sanomaan Responcesanoma, jonka sisältönä on virhekoodi 40 sekä selkokielinen erittely aineistoista joihin käyttäjätunnuksella ei ole oikeuksia. Esimerkkinä paluusanoma: 40 Ei oikeuksia aineistoon (yritysrekisteri). Tämän virhekoodin perusteella muodostetaan Web Serviceä kutsuneen käyttäjän lähettämään Request-sanomaan vastauksena Res- 6.6.2019 Visma Software 4

ponce-sanoma. Sanoman sisältönä on SOAP-sanoma sisältäen WS-Security-standardin mukaisen virhe-elementin autentikoinnin ja authorisoinnin epäonnistumisesta, sekä tarkemman kuvauksen eri aineistoista, joihin käyttäjätunnuksella ei ole oikeuksia. 2.2 Aineistojen validointi Aineistojen validointi Web Servicessä rajoittuu SOAP-sanoman validointiin. Validoinnissa tarkistetaan, että sanoma on oikein muodostettu Web Servicen WSDL-tiedoston mukaisesti. WSDL-tiedostossa on määritelty operaatiot, joilla toteutettua Web Serviceä voi kutsua. Näiden operaatioiden kutsumiseen määritellyt parametrit esitellään myös WSDL-tiedostossa. Web Servicessä näiden parametrien sisältämä tieto validoidaan, eli tietosisällön täytyy olla sellaista, jolla aineistoja voidaan noutaa sovelluksen tietokannasta ja tuoda sovelluksen tietokantaan. Itse aineiston validointi tapahtuu olemassa olevilla tietokantaproseduureilla. 2.3 Tiedostojen tuonti tietokantaan XML-muotoisen tiedon sisään tuominen sovelluksen tietokantaan tapahtuu operaatiolla addfile. addfile-funktion parametreina ovat schema, businessid ja lista parametriobjekteista, ParameterObject. Schema-parametrin sisältämä tieto tarkoittaa tietokantaryhmää, josta aineistoa noudetaan, tai johon aineistoa tuodaan. Tämä tieto tarvitaan, koska aineistojen siirrossa täytyy olla tiedossa missä kantaryhmässä kyseinen yritys sijaitsee. Tämä tieto välitetään Visma Fivaldin toimesta Web Servicen käyttäjille, koska heillä ei ole olemassa tietoa, missä kantaryhmässä eri yritykset ja niihin liittyvät tiedot sijaitsevat tietokannassa. BusinessId-parametri määrittää yrityksen jonka aineistoa noudetaan tai johon aineistoa tuodaan. Aineistojen siirto sallitaan yrityskohtaisesti. ParameterObject-parametri on erikseen räätälöity parametri Web Serviceä varten, joka pitää sisällään listan parametriobjekteja. 2.4 Tiedostojen noutaminen tietokannasta XML-muotoisen tiedon noutamiseen sovelluksen tietokannasta tapahtuu operaatiolla getfile. getfile-funktion parametreina ovat schema, businessid ja lista parametriobjekteista, ParameterObject. Schema-parametrin sisältämä tieto tarkoittaa tietokantaryhmää, josta aineistoa noudetaan, tai johon aineistoa tuodaan. Tämä tieto tarvitaan, koska aineistojen siirrossa täytyy olla tiedossa missä kantaryhmässä yritys, jonka aineistoja noudetaan tai johon aineistoja tuodaan, sijaitsee. Tämä tieto (FV001, FV002 ) välitetään Visman kautta Web Servicen käyttäjille erikseen, koska heillä ei ole olemassa tietoa, missä kantaryhmässä eri yritykset ja niihin liittyvät tiedot sijaitsevat tietokannassa. BusinessId-parametri määrittää yrityksen (yritystunnus), jonka aineistoa noudetaan tai johon aineistoa tuodaan. Aineistojen siirto sallitaan yrityskohtaisesti. ParameterObject-parametri on erikseen räätälöity parametri Web Serviceä varten, joka pitää sisällään listan parametriobjekteja. 6.6.2019 Visma Software 5

2.5 Kumppanikäyttäjätunnukset Visma Fivaldin toimesta avataan kumppanikäyttäjätunnukset. Luotu käyttäjätunnus ja salasana lähetetään käyttäjätunnukselle määritettyyn matkapuhelinnumeroon. Käyttäjätunnukselle määritetään Visma Fivaldin toimesta ylemmän tason käyttöoikeuksia tilauksen mukaisesti. Ympäristön pääkäyttäjän toimesta annetaan tuonti ja vienti oikeudet yrityksiin. 2.6 Siirtomäärien seuranta Kaikkien siirtojen tiedot tallennetaan tietokantaan, josta Visma Fivaldin toimesta voidaan tarkistaa mitä siirtoja on tehty, milloin ja kenen toimesta sekä onko siirto onnistunut. Siirtotiedot voidaan tulostaa näytölle tai viedä Exceliin. 6.6.2019 Visma Software 6

3 Käyttöönotto Visma Fivaldin toimesta luodaan Fivaldi-palvelunhallintaan kumppanikäyttäjät ja määritetään kumppanikäyttäjien tietovirtakohtaiset ylemmän tason tuonti/nouto-oikeudet tilauksen mukaisesti. Mahdolliset muutokset näihin tietoihin tehdään myös Visma Fivaldin toimesta. 3.1 Kumppanikäyttäjän lisäyksessä tarvittavat tiedot Seuraavat tiedot tarvitaan asiakkaalta kumppanikäyttäjän luonnissa. Käyttäjätunnus: Tunnus, jota käytetään tietoja siirrettäessä. Tunnuksen pituus max 20 merkkiä. Yritys: Kumppanikäyttäjäyritys. Nimen pituus max 60 merkkiä. Y-tunnus: Kumppanikäyttäjäyrityksen Y-tunnus, 9 merkkiä. Sähköposti: Kumppanikäyttäjän sähköpostiosoite, jonka pituus max 100 merkkiä Matkapuhelin: Kumppanikäyttäjän matkapuhelinnumero, johon lähetään käyttäjätunnus ja salasana. Puhelinnumeron pituus max 20 merkkiä. Kielikoodi: Vaihtoehdot FIN/SWE/ENG. Vaikuttaa mm SMS- viestin tekstiin. Asyritys: Valitaan onko kumppanikäyttäjätunnus kaikille ympäristölle näkyvä tunnus vai asiakasyrityskohtainen. Sisäinen lisätieto: Lisätietokenttä. Ulkoinen lisätieto: Lisätietokenttä, joka näkyy Fivaldin palvelunhallinnassa kumppanikäyttäjän tiedoissa. Käyttörajoitukset Rajoitettu ma-pe alkaen klo (tt:mi): Määrittää kellonajan, jonka jälkeen käyttäjätunnus ei ole käytössä mape. Arvoväli 0:00 24:00. Rajoitettu ma-pe loppuen klo (tt:mi): Määrittää kellonajan, jonka jälkeen käyttäjätunnus on jälleen käytössä ma-pe. Arvoväli 0:00 24:00. Viikonloppurajoitus (la 0:00 Su 24:00): käyttäjätunnus ei ole käytössä viikonloppuisin la 0:00 ja su 24:00 välisenä aikana Tietovirrat Kiha: vientioikeus kiinteistöhallinnan tietojen nouto ulkoiseen järjestelmään Palkat: tuontioikeus palkkatapahtumien tuonti ulkoisesta järjestelmästä Perustiedot: tuontioikeus yrityksen joidenkin perustietojen tuonti ulkoisesta järjestelmästä muiden siirtojen yhteydessä Projektit: vientioikeus projekti-rekisterin tietojen nouto ulkoiseen järjestelmään seurantakohdetaso kerrallaan Tilaukset: tuontioikeus ja vientioikeus tilausten tuonti ja vienti Tilaushistoria: vientioikeus myyntihistorian vienti Tuoterekisteri: tuontioikeus ja vientioikeus tuoterekisterin tietojen tuonti ja vienti Yritysrekisteri: tuontioikeus ja vientioikeus yritysreksiterin tietojen tuonti ja vienti 6.6.2019 Visma Software 7

3.2 Oikeuksien hallinta palvelunhallinta apuohjelmassa Ympäristön pääkäyttäjä antaa Visma Fivaldin luomalle kumppanikäyttäjälle Palvelunhallinta-apuohjelmassa (Visma Fivaldin Java-puolella Muut > Palvelunhallinta) oikeudet tietovirta- ja yrityskohtaisesti. Palvelunhallinnan vasemman reunan puunäkymässä näkyy Kumppanikäyttäjät-haara, jos asiakasyrityksellä on Web Service -ruutuja käytössä. Kumppanikäyttäjästä näytetään näkymän oikean puolen yläosassa kentät Yritys ja Lisätieto. Näkymän alaosassa eri tietovirroista näkyvät ne tietovirrat, joihin annettu palvelunhallinnassa oikeudet. Punaisena näkyvät ne, joille käyttäjä ei voi antaa oikeuksia. Tietovirta ei ole tuettu kyseiseen suuntaan tai kumppanikäyttäjälle ei ole annettu oikeuksia. Halutuille Web Services -rajapinnoille annetaan tietojen tuontia varten lisäys -oikeus ja tietojen vientiä varten käyttö -oikeus. 6.6.2019 Visma Software 8

Palvelunhallinnassa voidaan lisäksi asettaa käyttäjälle Kirjautumisen rajoitusryhmä niiden rajoitusten lisäksi, mitä Visman toimesta on kumppanikäyttäjälle tilauksen perusteella asetettu. Kirjautumisen rajoitusryhmällä voi rajata kumppanikäyttäjän siirtoaikoja ja sallittuja IP-osoitteita asiakasyrityskohtaisesti. Tämä on selitetty tarkemmin Visma Fivaldin Palvelunhallinta-käsikirjan luvussa 18 Käyttäjän kirjautumisen estäminen tai rajoittaminen tiettyinä aikoina ja/tai tietystä paikasta. 6.6.2019 Visma Software 9

3.3 XML-siirtojen perustietojen määritys Avaa määritysnäkymä valitsemalla Fivaldi Webin puolella Muut > XML-siirtojen perustiedot. Avautuvassa näkymässä tulee tehdä valinnat jokaiseen neljään kohtaan (Yritysrekisteri, Tuoterekisteri, Myyntitilaukset, Palkkatapahtumat) ja tallentaa muutokset, vaikka aikoisit siirtää tietoja vain tuoterekisteriin. Tällöin asetukset tallentuvat oikein. 6.6.2019 Visma Software 10

Yritysrekisteri-kohdan määritykset: Lisää uudet tietueet (ei päivitystä) o Käyttötapa: Uudet asiakkaat tuodaan aina aineiston kautta Fivaldiin. o Kaikki aineiston sisältämät arvot tuodaan uuden asiakkaan luonnissa yritysrekisteriin. o Ylläpito voi tapahtua ensimmäisen aineistotuonnin jälkeen suoraan Fivaldissa tai uusien tietojen osalta aineistosta. HUOM. Tämä vaihtoehto aiheuttaa ongelman, jos asiakkaita luodaan Fivaldiin manuaalisesti ja jos aineistot eivät kata kaikkia tarpeellisia tietoja (esim. asiakkaan verkkolaskuosoitteita). Silloin käy niin, että manuaalisesti perustetun asiakkaan osalta, ensimmäisellä tuontikerralla tyhjentyvät kaikki ne tiedot joita ei ollut aineistossa. Seuraavan tuonnin yhteydessä tätä ongelmaa ei enää ole. Mikäli asiakkaita perustetaan myös manuaalisesti, valitse silloin vaihtoehto Päivitä kaikki tietueet, säilytä kentät joita ei aineistossa. Päivitä kaikki tietueet o Käyttötapa: Uudet asiakkaat tuodaan aina aineiston kautta Fivaldiin. o Ylläpito tapahtuu vain aineiston tietojen perusteella. o Valitaan silloin kun asiakkaiden tiedot ylläpidetään toisessa järjestelmässä. o Viimeisin tilanne tuodaan aina aineiston perusteella Fivaldiin. Huom! Tämä valinta tyhjentää olemassa olevat tiedot, jos tietoa ei tuoda aineistossa. Päivitä kaikki tietueet, säilytä kentät joita ei aineistossa o Käyttötapa: Uudet asiakkaat tuodaan aineiston kautta tai perustetaan manuaalisesti Fivaldiin. o Ylläpito voi tapahtua suoraan Fivaldiin tai aineiston tietojen perusteella. o Valitse tämä vaihtoehto, jos uusia asiakkaita perustetaan suoraan Fivaldiin sekä aineiston kautta ja jos aineistot eivät sisällä aina kaikkia tarvittavia tietoja. o Tämä vaihtoehto säilyttää aina asiakkaan sellaisetkin tiedot joita aineisto ei sisältänyt. Tuoterekisteri-kohdan määritykset: Lisää uudet tietueet (ei päivitystä) Tuo vain uudet yritystunnukset, ei koske olemassa oleviin yritystunnuksiin. Päivitä kaikki tietueet Tuo uudet tuotteet ja päivittää olemassa olevien tuotteiden kentät siirtotiedoston tiedoilla. Päivittää myös kentät, joita ei ole siirtotiedostossa. Huom! Tämä valinta tyhjentää olemassa olevat tiedot, jos tietoa ei tuoda aineistossa. Poista kaikki tuotteet ensin, lisää aineiston tuotteet Tuo uudet tuotteet ja päivittää olemassa olevien tuotteiden kentät siirtotiedoston tiedoilla. Ei koske kenttiin, joita ei ole siirtotiedostossa. Myyntitilaukset-kohdan määritykset: Lisää uudet tietueet (ei päivitystä) Tuo vain myyntitilaukset joiden SalesOrderNumber on uusi. Päivitä kaikki tietueet Päivittää myyntitilausten tiedot siirtoaineiston tiedoilla. Huom! Tämä valinta tyhjentää olemassa olevat tiedot, jos tietoa ei tuoda aineistossa. Myyntitilauksia tuotaessa ohjelma poistaa myös manuaalisesti lisätyt tuoterivit, eli jäljelle jää vain siirtoaineiston tiedot. 6.6.2019 Visma Software 11

Käytä tuonnissa alennusrekisteriä Mahdolliset alennusprosentit haetaan Alennukset/hinnoittelu-rekisteristä. Perusta puuttuvat tuotteet ja päivitä toimittajan tiedot Perustaa tuoterekisteriin puuttuvan tuotteen koodin ja nimen. Ei lisää muita tietoja. Hae puuttuva seurantakohteen 1 arvo Fivaldin perustiedoista yleisten asetusten mukaisesti. Hae puuttuva seurantakohteen 2 arvo Fivaldin perustiedoista yleisten asetusten mukaisesti. Hae puuttuva seurantakohteen 3 arvo Fivaldin perustiedoista yleisten asetusten mukaisesti. Hae puuttuva seurantakohteen 4 arvo Fivaldin perustiedoista yleisten asetusten mukaisesti. HYVÄ TIETÄÄ: Seurantakohteiden tuomisen marssijärjestys on listattu Pääkäyttäjän käyttöönoton työjärjestys -helpissä, kohdassa Tilikartta > Seurantakohteet. Palkkatapahtumat-kohdan määritykset: Seurantakohteet luetaan aineistosta Palkkarivin seurantakohteen arvot luetaan siirtoaineistosta. Seurantakohteet luetaan henkilön oletustiedostosta Palkkarivin seurantakohteen arvot haetaan palkansaajan tiedoista. Ensisijaisesti aineiston kohteet, toiseksi henkilön oletuskohteet Palkkarivin seurantakohteen arvot luetaan siirtoaineistosta. Jos aineistossa ei ole arvoa seurantakohteelle, luetaan mahdollinen arvo palkansaajan tiedoista. Aineiston muodostuksen perustiedot Tiedoston oletusnimi Fivaldista ulosluettavan tiedon tallennustiedoston nimi. Ulosluettavalle tiedostolle voi antaa oletusnimen, mutta oletusnimen tallentaminen ei ole pakollista. Nimen puuttuessa järjestelmä käyttää oletusnimeä ulosluettu.xml. Seurantakohteen tapahtumat, seurantakohdetaso Ulosluettaessa seurantakohdetasoja, määritetään luettava seurantakohdetaso tähän. Tällä valinnalla vaikutetaan siihen, minkä seurantakohdetason tietoja haetaan IP-rajapinnan yli. 6.6.2019 Visma Software 12

4 Tietojen siirto Kumppanikäyttäjä integroi ympäristöönsä tietojen lähettämistä ja noutamista varten tarvittavan toiminallisuuden parhaaksi katsomallaan tavalla. Kumppanikäyttäjä saa Visma Fivaldilta WSDL-tiedoston rajapinnan toteuttamista varten. WSDL-tiedostossa on määritelty operaatiot, joilla Web Service -rajapintaa voi kutsua. Operaatioiden kutsumiseen määritellyt parametrit esitellään myös WSDL-tiedostossa. 4.1 Tuetut operaatiot Web Services rajapinnassa tuetut operaatiot ovat Addfile ja Getfile. Sallitut arvot Addfile-operaatiossa ovat: companies (yritysrekisteri) products (tuoterekisteri) orders (tilaukset) salaries (palkat) Sallitut arvot Getfile-operaatiossa ovat: companies (yritysrekisteri) products (tuoterekisteri) orders (tilaukset) orderhistory (tilaushistoria) estate (kiha-aineisto) projects (projektit) journal (kirjanpidon tositteet) 6.6.2019 Visma Software 13