Versio: 0.5 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)... 6 3.1.2 Lähettävän organisaation tiedot (SenderOrganisationType)...6 3.1.3 Välityspalvelun metatiedoto (ProxyInfo)... 6 3.2 Turvallisuushavaintoilmoituksen tiedot (MessageType)...7 3.2.1 Organisaatiotiedot (organisationtype)... 7 3.2.2 Turvallisuushavaintoilmoituksen 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 turvallisuushavaintoilmoituksen 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. Teknisesti ja sisällöllisesti turvallisuushavaintoilmoitussanomakuvaus on sama kuin vaaratilanneilmoitussanomakuvaus. 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
4(10) 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 2.3 Totuusarvot Totuusarvoinen tieto esitetään boolean-muodossa. Rajapinnassa sallitut arvot ovat näinollen ainoastaan true ja false. 3 Sanoman rakenne Turvallisuushavaintoilmoituksen sanomarakenne jakaantuu juuritasolla (worksafetynotificationreport) 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). 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
6(10) 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. Tällä tiedolla määritellän se, mihin organisaatioon sanoma välitetään. 3.1.2 Lähettävän organisaation tiedot (SenderOrganisationType) Elementillä kuvataan sanoman lähettävän organisaation tiedot (kuva 3). 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. 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.
7(10) 3.2 Turvallisuushavaintoilmoituksen tiedot (MessageType) Elementti sisältää kaikki turvallisuushavaintoilmoituksen tiedot (kuva 4) mukaanlukien organisaatio, henkilö ja esimiestiedot. Elementti jakaantuu rakenteellisesti useampaan eri alielementtiin. Kuva 4. organisation P Päätason elementin nimi, jonka alla määritellään turvallisuushavaintoilmoituksen organisaatiotiedot. Organisaatiolla tarkoitetaan ilmoittajan organisaatiota. Incident P Päätason elementin nimi, jonka alla määritellään varsinaisen turvallisuushavaintoilmoituksen 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 Turvallisuushavaintoilmoituksen tiedot (IncidentType) Elementillä määritellään varsinaisen turvallisuushavaintoilmoituksen tiedot (kuva 6). Kuva 6. ReferenceId P turvallisuushavaintoilmoituksen yksilöivä ID / tunniste DateOfIncident P turvallisuushavaintoilmoituksen tapahtumapäivä TimeOfIncident P turvallisuushavaintoilmoituksen tapahtumakellonaika WhatAndWhere P Kuvaus mitä tapahtui ja missä WhyAndHow P Kuvaus miksi tapahtui ja miten Consequences P Kuvaus seuraamuksista ActionProposals P Kuvaus korjaavista toimenpiteistä
9(10) 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 turvallisuushavaintilmoituksen luokittelutiedot (kuva 7). Ilmoituksella voi olla luokittelutietoja n-kpl. Classification Kuva 7 Vaaratilanteen luokittelutiedon kooditettu arvo. Selväkielinen kuvaus vaaratilanteen luokittelutiedosta. Sallitut luokittelutiedot ovat: Code 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 turvallisuushavaintoilmoituksesta ilmoitettu viranomaisille. Sallitut arvot: true tai false. AuthorityName P Viranomainen, jolle ilmoitus on tehty InformationDate P Päivä, jolloin ilmoitus viranomaisille on tehty InformationTime P Kellonaika, jolloin ilmoitus viranomaisille on tehty InformerName P Henkilön nimi (etu- ja sukunimi), joka ilmoituksen teki
10(10) 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 turvallisuushavaintoilmoitus 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.