Yleiset ohjeet resursseista

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>. 

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ä)

Elementti	Muoto	Kuvaus	Esimerkki	Lisätiedot
Status	Merkkijono	Indikoi tapahtuiko kutsun käsittelyssä virhettä	OK	FAILED
Status	Merkkijono	Virhevakio ja -kuvaus		Tämä elementti vain jos FAILED tilassa. Ks. Virheden hallinta
TimeStamp	Päivämäärä	Vastauksen aikaleima	01.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ä)

Elementti	Muoto	Kuvaus	Esimerkki	Lisätiedot
InsertedDataIdentifier	Merkkijono
TAI
Reply	Merkkijono

Oheiset elementit esiintyvät 0-n kertaa.

Oliko tästä vastauksesta apua? Kyllä Ei

Send feedback