Yleistä
Tulkintaohje
Sanomavastaukset

Yleistä

Ohjelmistorajapinta mahdollistaa sekä aineistojen noudon Netvisorista että aineistojen tuonnin Netvisoriin. Rajapinnan tarjoamat resurssit on jaettu ylätason kategorioihin.
Yhteistä kaikille tapahtumille on:

  • Päivämäärät ovat ANSI–muodossa
  • Maakoodit ovat aina ISO 3166 –muodossa
  • Liitteet ovat aina Base64 -enkoodattuna XML-sanomaan
  • Tyhjiä elementtejä ei tarvitse kirjoittaa XML-sanomaan, esimerkiksi päivityspyynnössä tyhjä elementti tulkitaan rajapinnassa käskyksi päivittää arvo tyhjäksi
  • Pakollisia kenttiä ei tule jättää tyhjäksi
  • Elementtien täytyy olla DTD:n mukaisessa järjestyksessä

Skandinaavisten kirjainten (Ä, ä, Ö, ö tai Å, å) saamiseksi käyttöliittymään on sanoman oltava ISO/IEC 8859-15-enkoodatussa muodossa, mutta xml-deklaraatiota ei kuitenkaan tarvita. Netvisorin palvelinpuoli tekee sisällölle tarvittavat esikäsittelyt, jolloin aineiston tulee aina alkaa <root>. Mikäli ääkköset eivät toimi ISO/IEC 8859-15 enkoodatussa muodossa, voidaan enkoodaus muuttaa UTF-8 muotoon. 

Tee isot haut ja tietojen siirrot virka-ajan ulkopuolella, jollei niiden siirtoon virka-aikana ole erityistä tarvetta. Tietojen siirron aiheellinen tiheys eroaa resurssi- ja käyttötapauskohtaisesti. Monissa tapauksissa siirto kerran vuorokaudessa tai kuukaudessa riittää. Voit nopeuttaa siirtoja myös sopivilla rajauksilla käyttäen resurssien parametreja.

Tulkintaohje

Ohessa on kuvattu integraatiorajapinnan eri merkintöjen tarkoitus ja tulkinnat.
Eri sanomien XML-rakenne on kuvattu taulukkomuotoisesti niistä kohdista sanomia kun se on mahdollista ja loogista. XML:n rakenteellisuudesta johtuen kuvauksissa on jouduttu käyttämään esimerkiksi viittauksia ohjeistuksen eri kohtiin, jotta kokonaisuus on pysynyt selkeänä.

Rakennekuvausten perusrakenne on seuraava:
Kutsu:

  • Perustiedot
    • Käytettävä resurssi
    • GET - yleensä datan noutoa Netvisorista
    • POST - yleensä datan tuontia Netvisoriin
  • Parametrit
    • Yleensä QueryString:ssä määritettäviä, erotetaan varsinaisesta resurssista ?-merkillä ja tämän jälkeen &-merkillä
    • Kaikilla resursseilla ei ole
  • XML-rakenne dataa tuotaessa (POST)
    • Kuvattu XML:n rakenne sekä esim. elementtien määrät ja pakollisuus

Mikäli POST-sanomalla käytetään itsesulkevia tageja, niin huomaa että näitä ei lueta ollenkan, mukaanlukien mahdolliset attribuutit. Esimerkiksi asiakaskortin elementtiä <email/> ei lueta ollenkaan, mutta <email></email> taas tyhjentää kyseisen arvon Netvisorin asiakaskortilta. 


Vastaus:
Jokaiseen kutsuun vastataan XML-vastauksella, jonka rakenne vastaa suurilta osin kutsua. Sanoman yleisrakenteen voi katsoa alemmasta kappaleesta. Vastaus GET-tyyppisiin noutosanomiin sisältää resurssikohtaisen datarakenteen, joka on kuvattu kussakin resurssikuvauksessa erikseen. POST-tyyppisiin tuontisanomiin tulee sanomasta riippuen vastauksessa Replies-elementti, jonka sisällä on esim. InsertedDataIdentifier-elementti sisältäen lisätyn asian ID-arvon.

Sanomavastaukset

Jokaiseen rajapintakutsuun vastataan vakioidulla sanomavastauksella. GET-tyyppisissä sanomissa vastaus sisältää pyydetyn datan (<resurssikohtainen elementti>) ja POST-tyyppisissä mahdollisesti tapauskohtaisen vastauksen (Replies).
Vastaussanoman yleinen rakenne:
Elementti: Root (1 ilmentymä)
Elementti: Root/ResponseStatus (1 ilmentymä)

ElementtiMuotoKuvausEsimerkkiLisätiedot
StatusMerkkijonoIndikoi tapahtuiko kutsun käsittelyssä virhettäOKFAILED
StatusMerkkijonoVirhevakio ja -kuvaus Tämä elementti vain jos FAILED tilassa. Ks. Virheden hallinta
TimeStampPäivämäärä Vastauksen aikaleima01.01.2018 12:00:00 

 
Vastauksen tyyppi on sidoksissa dataliikenteen suuntaan:

1. Noudettaessa dataa Netvisorista
Noudettu data on omana elementtinään sanomassa:
Elementti: Root/ResponseStatus/<resurssikohtainen elementti>
2. Tuotaessa dataa Netvisoriin
Vastaus sisältää Replies-elementin ja sen sisällä tapauskohtaisesti dataa:
Elementti: Root/ResponseStatus/Replies (0-1 ilmentymä)

ElementtiMuotoKuvausEsimerkkiLisätiedot
InsertedDataIdentifierMerkkijono   
TAI
ReplyMerkkijono   

Oheiset elementit esiintyvät 0-n kertaa.




Oliko tästä vastauksesta apua? Kyllä Ei

Send feedback
Pahoittelut, että emme voineet auttaa. Anna palautetta, jotta voimme parantaa tätä artikkelia.