Versio: 0.3 Muokattu: 23.6.2008
2(10) SISÄLLYS 1 Tarkoitus...3 1.1 Rajaus...3 1.2 Dokumentaatio...3 2 Tietojen esitystavat...3 2.1 Numeerinen tieto...3 2.2 Päivämäärät ja kellonajat...3 2.3 Totuusarvot...4 3 Sanoman rakenne...4 3.1 Otsikkotiedot (headerstype)...4 3.1.1 Vastaanottavan organisaation tiedot (DestinationOrganisationType)... 5 3.1.2 Lähettävän organisaation tiedot (SenderOrganisationType)...6 3.1.3 Välityspalvelun metatiedoto (ProxyInfo)... 6 3.2 Vaaratilanneilmoituksen tiedot (MessageType)...6 3.2.1 Organisaatiotiedot (organisationtype)... 7 3.2.2 Vaaratilanneilmoituksen tiedot (IncidentType)...8 3.2.2.1 Luokittelutiedot (classificationstype)...9 3.2.2.2 Viranomaistiedot (authorityinformedtype)...9 3.2.3 Päämiehen yhteyshenkilön tiedot (foremancontactperson)...10 3.2.4 Asiakaskohtaiset tiedot (CustomDataType)...10 4 Vastaussanoma...10 4.1 Poikkeuskäsittely...10 Muutokset: 23.6.2008 Tarkennuksia 24.4.2008 Lisätty päämiehen yhteyshenkilön tiedot sanomakuvaukseen
3(10) 1 Tarkoitus Tässä dokumentissa kuvataan liittymärajapinta, joka välittää -välityspalveluun toimitetun vaaratilanneilmoituksen eteenpäin sanomassa määritellylle vastaanottajalle. Vastauksena lähettävälle osapuolelle palautetaan kuittaus onnistuneesta tai epäonnistuneesta siirrosta. Välitettäväksi lähetetty sanoma voidaan välittää ainoastaan yhdelle vastaanottajalle kerralla. Mikäli sanoman käsittelyssä tapahtui virhe tai sanoma on puutteellinen, lähettäjälle palautetaan standardi virhesanoma. Virhesanoman sisältö ja rakenne on kuvattu omaan dokumenttiin. 1.1 Rajaus Tässä dokumentissa kuvattua XML-skeemakuvausta käytetään sekä viestin vastaanotossa välityspalveluun että sen edelleen välityksessä varsinaiselle sanoman vastaanottajalle. 1.2 Dokumentaatio Rajapintadokumentaatio muodostuu seuraavista osista ja dokumenteista: Tämä dokumentti kuvaa sanoman sisältämien elementtien sisällön Rajapinnan XML-skeemakuvaus Esimerkkisanoma 2 Tietojen esitystavat 2.1 Numeerinen tieto Numeerisen tiedon tietotyyppinä rajapinnassa on integer, short tai decimal. XML-skeemassa ei rajata numeerisen tiedon pituutta. Desimaalierottimena käytetään XML-skeeman mukaisesti aina pistettä. 2.2 Päivämäärät ja kellonajat Kaikki päivämäärät määritellään sanomassa formaatissa: VVVV-KK-PP, esim. 2007-12-24 Kaikki kellonajat ilman päivämäärää määritellään sanomassa formaatissa: hh:mm:ss, esim. 09:30:00 Kellonajalla varustettu päivämäärä määritellään formaatissa: VVVV-KK- PPThh:mm:ss, esim. 2007-12-24T09:30:00
4(10) 2.3 Totuusarvot Totuusarvoinen tieto esitetään boolean-muodossa. Rajapinnassa sallitut arvot ovat näinollen ainoastaan true ja false. 3 Sanoman rakenne Vaaratilanneilmoituksen sanomarakenne jakaantuu juuritasolla (nearmissreport) kahteen alielementtiin: headers ja message-tasoihin (kuvat 1 ja 2). Kuva 1. Kuva 2. 3.1 Otsikkotiedot (headerstype) Elementin sisällä määritellään kaikki sanoman otsaketiedot (kuva 3), joiden avulla tunnistetaan mm. sanoman lähettävä- ja vastaanottava organisaatio, sanoman tyyppi, milloin sanoma on lähetetty jne. Kaikki otsaketiedot ovat rakenteeltaan samanlaiset jokaisessa välityspalvelun sanomatyypissä.
5(10) Kuva 3. P = pakollinen elementti messagetype P Sanoman tyyppi, joka on jokin seuraavista sanomatyypeistä: - vaaratilanneilmoitus - turvallisuushavainto - tapaturmailmoitus - taajuusilmoitus Tyyppi kirjataan sanomaan selväkielisenä merkkijonona. Sanoman tyyppiä ei välttämättä tarvitse tunnistaa tästä elementistä. Sanoman tyyppi voidaan tunnistaa myös sanoman sisällä olevasta juurielementistä, joka on jokin seuraavista: - nearmissreport - worksafetynotificationreport - accidentreport - monthlyreport destinationorganisation P Päätason elementti, jonka alla määritellään kaikki sanoman vastaanottavan organisaation tiedot. senderorganisation P Päätason elementti, jonka alla määritellään kaikki sanoman lähettävän organisaation tiedot. proxyinfo Välityspalvelun omia asetuksia ja metatietoja, jotka välityspalvelu itse täyttää. Elementtiä ei saa itse tuottaa sanomaan. Sanoman vastaanottaja voi lukea näistä tiedoista esim. sanoman lähetysajankohdan (päivä ja kellonaika). 3.1.1 Vastaanottavan organisaation tiedot (DestinationOrganisationType) Elementillä kuvataan sanoman vastaanottavan organisaation tiedot (kuva 3). Elementti on pakollinen elementti. OrganisationCode-elementin avulla välityspalvelu päättelee vastaanottavan organisaation tiedot (IP-osoitteet, käyttäjätunnukset jne) omasta tietokannasta. name P Sanoman vastaanottavan organisaation nimi. code P Sanoman vastaanottavan organisaation koodi. Koodina käytetään yrityksen y-tunnusta. Y-tunnus tuodaan muodossa 1234567-8 tai 12345678.
6(10) 3.1.2 Lähettävän organisaation tiedot (SenderOrganisationType) Elementillä kuvataan sanoman lähettävän organisaation tiedot (kuva 3). Elementti on pakollinen elementti. name P Sanoman vastaanottavan organisaation nimi code P Sanoman vastaanottavan organisaation koodi. Koodina käytetään yrityksen y-tunnusta. Y-tunnus tuodaan muodossa 1234567-8 tai 12345678. Tällä tiedolla määritellän se, mihin organisaatioon sanoma välitetään. 3.1.3 Välityspalvelun metatiedoto (ProxyInfo) Elementillä kuvataan sanomavälityspalvelun omia metatietoja ja asetuksia, jotka välityspalvelu itse tuottaa sanomaan (kuva 3). Elementtiä ja sen sisältöä ei saa itse tuottaa sanomaan. Tietoja käytetään mm. lokitapahtumien kirjaamiseen. messagereceivedtime Päivämäärä ja kellonaika, jolloin sanoma vastaanotettiin välityspalveluun, esim. jos sanoma lähetetään välityspalveluun jonkun kolmannen osapuolen toimesta. messagesendtime Elementin sisältö on tyhjää mikäli sanomaa ei vastaanotettu ulkopuolelta vaan se lähetettiin web-palvelusta. Päivämäärä ja kellonaika, jolloin sanoma lähetettiin välityspalvelusta sanoman vastaanottajalle. 3.2 Vaaratilanneilmoituksen tiedot (MessageType) Elementti sisältää kaikki vaaratilanneilmoituksen tiedot (kuva 4) mukaanlukien organisaatio-, henkilö- ja esimiestiedot. Elementti jakaantuu rakenteellisesti useampaan eri alielementtiin (kuva 4).
7(10) Kuva 4. organisation P Päätason elementin nimi, jonka alla määritellään vaaratilanteen organisaatiotiedot. Organisaatiolla tarkoitetaan ilmoittajan organisaatiota. Incident P Päätason elementin nimi, jonka alla määritellään varsinaisen vaaratilanteen tiedot CustomDataType Asiakaskohtaisia tietoja avain-arvopareina, joita ei tästä sanomakuvauksesta löydy. 3.2.1 Organisaatiotiedot (organisationtype) Elementillä määritellään ilmoittajan organisaation tiedot (kuva 5).
8(10) Kuva 5 name P Organisaation nimi code P Organisaation koodi (y-tunnus). Y-tunnus muodossa 1234567-8 tai 12345678. 3.2.2 Vaaratilanneilmoituksen tiedot (IncidentType) Elementillä määritellään varsinaisen vaaratilanteen tiedot (kuva 6). Kuva 6. ReferenceId P Vaaratilanteen yksilöivä ID / tunniste DateOfIncident P Vaaratilanteen tapahtumapäivä TimeOfIncident P Vaaratilanteen tapahtumakellonaika WhatAndWhere P Kuvaus mitä tapahtui ja missä WhyAndHow P Kuvaus miksi tapahtui ja miten Consequences P Kuvaus seuraamuksista
9(10) ActionProposals P Kuvaus korjaavista toimenpiteistä ImmediateActions P Kuvaus välittömistä toimenpiteistä Classifications Authorities Päätason elementti, jonka alla kuvataan luokittelutiedot, n-kpl classification-alielementtejä. Päätason elementti, jonka alla kuvataan viranomaistiedot 3.2.2.1 Luokittelutiedot (classificationstype) Elementillä määritellään vaaratilanteen luokittelutiedot (kuva 7). Ilmoituksella voi olla luokittelutietoja (classification elementtejä) n-kpl. Kuva 7 code Vaaratilanteen luokittelutiedon kooditettu arvo. Selväkielinen kuvaus vaaratilanteen luokittelutiedosta. Sallitut luokittelutiedot ovat: description 1 = Henkilövaara 2 = Tulipalo 3 = Ympäristövahinko 4 = Omaisuusvahinko Em. luokittelukoodin selväkielinen suomenkielinen kuvaus: 1 = henkilövaara 2 = tulipalo 3 = ympäristövahinko 4 = omaisuusvahinko 3.2.2.2 Viranomaistiedot (authorityinformedtype) Elementillä määritellään vaaratilanteen viranomaistiedot (kuva 6). Tiedot ovat pakollisia vain jos AuthoritiesInformed kenttä on määritelty arvoon true. AuthoritiesInformed Onko vaaratilanteesta ilmoitettu viranomaisille. Sallitut arvot: true tai false. AuthorityName P Viranomainen, jolle ilmoitus on tehty InformationDate P Päivä, jolloin ilmoitus viranomaisille on tehty
10(10) InformationTime P Kellonaika, jolloin ilmoitus viranomaisille on tehty InformerName P Henkilön nimi (etu- ja sukunimi), joka ilmoituksen teki 3.2.3 Päämiehen yhteyshenkilön tiedot (foremancontactperson) Elementillä määritellään päämiehen yhteyshenkilön tiedot. Kuva 8. Name P Päämiehen yhteyshenkilön nimi (etu- ja sukunimi) Email P Päämiehen yhteyshenkilön sähköpostiosoite 3.2.4 Asiakaskohtaiset tiedot (CustomDataType) Elementillä määritellään asiakaskohtaiset vaaratilanne tms. Tiedot. (kuva 4). Esim. tietoja, joille ei ole sanomassa varattu omaa elementtiä. Tiedot määritellään sanomaan avain-arvo-pareina ja näitä voi olla sanomassa n-kpl. Key Value Tiedon avain Tiedon varsinainen arvo 4 Vastaussanoma Vastaussanoman sisältö ja rakenne on kuvattu omaan dokumenttiinsa. 4.1 Poikkeuskäsittely Mikäli sanoman käsittelyssä tapahtui jokin virhe, sanoman lähettäjälle palautetaan virhesanoma. Virhesanoman sisältö ja rakenne on kuvattu omaan dokumenttiinsa.