Tilaus. Sanomasuositus ja sen yleinen soveltamisohje FI1005,

Transkriptio

1 Toteutettu yhteistyössä Elintarviketeollisuusliitto ry:n ja Päivittäistavarakauppa ry:n kanssa osana maa- ja metsätalousministeriön kansallista elintarviketalouden laatustrategiaa Sanomasuositus ja sen yleinen soveltamisohje Tilaus FI1005, Käyttö: Kaupan toimiala Sanasto: UBL Versio: 2.0 Sanoma: Order

2 Sisällysluettelo 1 Dokumenttien hallinta Päivitykset Esitietovaatimukset Aiheeseen liittyvä aineisto Huomioitavaa Soveltamisohjeen lukuohje Lyhenteet ja termit Johdanto Soveltamisohjeen perusteet, tarkoitus ja käyttö Soveltamisohjeen sisältö Tekniset määritykset Kooste-elementtien esittämistapa Graafisten kuvausten merkinnät Soveltamisohjeessa käytetyt attribuutit Sanomamääritys Katettava skenaario Reunaehdot Toimialakohtaiset laajennukset Otsikkotason laajennukset Sanoman otsikkotaso Sanoman rivitaso Rivitiedot (LineItem) Sanomakohtaiset kooste-elementit Toimitus (Delivery) Tuote (Item) Toimituserä (Shipment) Sanomaesimerkki XML esimerkki... 14

3 1 Dokumenttien hallinta Tämä dokumentti sisältää sanomakuvauksen ja soveltamisohjeen UBL 2.0 -versioon perustuvan Order -sanomaformaatin käyttämiseksi tilauksena kaupan toimialalla. Tätä dokumenttia ei tule käsitellä itsenäisenä kokonaisuutena vaan yhdessä komponenttikirjaston kanssa. 1.1 Päivitykset Pvm/Laatija Juha Ikävalko Muutokset Ensimmäinen versio 1.2 Esitietovaatimukset Soveltamisohje soveltuu sekä johto- että asiantuntijatason käyttöön. Soveltamisohjeen teknisen taustan ymmärtämistä edesauttaa seuraavien aihealueiden tuntemus: XML, UBL ja ebxml ydinkomponentit. 1.3 Aiheeseen liittyvä aineisto Komponenttikirjasto ebxml Core Components Technical Specification (CCTS) 2.01 Universal Business Language 2.0 UBL sanomien laajennusohje (TIEKE) NES työryhmä ( NES-työryhmä on yhteistyöelin, jonka tavoitteena on edistää maidenvälistä tiedonvälitystä. Vuonna 2006 työryhmässä oli mukana edustajia seuraavista maista: Tanska, Ruotsi, Norja, Islanti, Iso-Britannia ja Suomi. 1.4 Huomioitavaa Soveltamisohje perustuu UBL 2.0 spesifikaatioon. Määrityksissä on noudatettu kansainvälisen NES työryhmän suosituksia sanomien tietosisällön ja käytön osalta. Tämä soveltamisohje valmistui ennen NES määritysten lopullista julkaisuajankohtaa, minkä seurauksena määrityksissä saattaa esiintyä joitain eroavaisuuksia. Kansainvälisen yhteentoimivuuden kannalta on tärkeää noudattaa NES-ohjeistuksia mm. osapuoli-, vero-, toimitus- ja maksamistietojen esittämistavasta. Ohjeistukset löytyvät NES:in kotisivuilta. 1.5 Soveltamisohjeen lukuohje Kappaleessa 2 Johdanto käsitellään lyhyesti tämän soveltamisohjeen tarkoitus, sisältö ja esittämistapa. Kappaleessa 3 Sanomamääritys osiossa kukin sanoman kooste-elementti (ABIE) on esitetty omana kappaleenaan. Kappaleessa 4 "Sanomaesimerkki on havainnollistettu sanoman rakennetta esittämällä XML- esimerkki sanoman minimitietosisällöstä. 1.6 Lyhenteet ja termit Lyhenteet ja termit on kuvattu komponenttikirjaston vastaavassa kappaleessa. 3/15

4 2 Johdanto 2.1 Soveltamisohjeen perusteet, tarkoitus ja käyttö Perusteena työn tekemiselle oli kansallisen suosituksen luominen, joka ehkäisisi yhteentoimimattomien standardien syntymistä ja laskisi näin liiketoimintaprosessien integrointikustannuksia. Tavoitteena on myös nopeuttaa uuden tiedonsiirtotavan omaksumista kansainvälisen kilpailukyvyn säilyttämiseksi ja parantamiseksi. Soveltamisohje on tarkoitettu apuvälineeksi uusien kauppakumppanien välisiin neuvotteluihin sekä pohjaksi mahdollisten kumppanikohtaisten soveltamisohjeiden laatimisille. 2.2 Soveltamisohjeen sisältö Tekniset määritykset Tekniset määritykset on kuvattu komponenttikirjaston johdanto-osassa Kooste-elementtien esittämistapa Kappaleeseen 3 Sanoman rakenne esitellään tälle sanomalle spesifit kooste-elementit omina kappaleinaan. Tässä kappaleessa kuvataan kooste-elementtien esittämistapa. Kukin kappale on otsikoitu kooste-elementin nimen mukaisesti. Mikäli kooste-elementti sisältää viittauksia muihin kooste-elementteihin (ASBIE), on nämä esitetty kyseisen kappaleen alaotsikkoina. Kunkin otsikon alla on notaatio tai notaatiot, jotka ilmaisevat, mitkä ovat kyseisen koosteelementin mahdolliset käyttökohteet. Esimerkiksi notaatio Address.Country ilmaisee, että kooste-elementti Country tiedot voidaan esittää Address kooste-elementin alla. XMLsyntaksina tämä vastaa rakennetta: <Address> <Country> </Country> </Address> Käyttökohteiden jälkeen on tarvittaessa kappale, joka selventää kooste-elementin käyttöä sanomalla. Tätä seuraa kuva kooste-elementin standardimuotoisesta rakenteesta sisältäen myös tiedot, joita ei ole otettu osaksi tämän soveltamisohjeen rajaamaa sanoman tietosisältöä. Kuvan alla on taulukko, jossa on listattu kooste-elementin osat, joita soveltamisohjetyössä on nähty katettavan käyttötarpeen osalta tarvittavan. Listaan on sisällytetty myös mahdolliset lisäykset, jotka on räätälöity osaksi sanomamääritystä. Käytettävät elementtien attribuutit on esitetty taulukossa muodossa ELEMENTIN_NIMI[@ATTRIBUUTIN_NIMI]. Jotta erityyppiset taulukon rivit erottuisivat toisistaan, on taulukkoon lisätty Tyyppi sarake, jonka mahdollisia arvoja ovat: Tyyppi BBIE ATTR Kuvaus (Basic Business Information Entity) on UBL/CCTS termi, joka ilmaisee kyseessä olevan yksinkertaisen tietoelementin, jolla ei ole sisäistä rakennetta. Tällaisia ovat esimerkiksi tunniste-, koodi- ja päivämäärätiedot. (Attribute) ilmaisee, että kyseessä on BBIE - tietoelementin tarkenne. Esimerkiksi notaatio ID[@schemeID] ilmaisee schemeid:n olevan ID tietoelementin tarkenne. Tarkenne esitetään sanomalla XML - elementin attribuuttina. 4/15

5 ASBIE (Association Business Information Entity) on UBL/CCTS termi, joka ilmaisee, että kyseessä on viittaus toiseen kooste-elementtiin eli tietoelementtiin, jolla on sisäinen rakenne. Tällaisia ovat esimerkiksi osapuoli- ja osoitetiedot. Attribuuttien osalta Toisto sarake ilmaisee, montako kertaa ko. attribuutti toistuu sen sisältävää elementtiä kohden eli käytännössä, onko se kyseisen elementin suhteen pakollinen vai vapaaehtoinen. Taulukon alla on listattu niiden koodien (Code) ja tunnisteiden (ID) arvot, joille on yleisesti sovittu merkintätapa. Pääosin näitä listoja käytetään elementtien tietosisällön tarkentamiseen eli teknisellä tasolla elementtien attribuuttien arvojen määrittämiseen. Käytettävien koodien osalta on pyritty seuraamaan NES - työryhmän suosituksia. Käytössä on sekä ISO, UN/ECE ja NES koodilistoja, joita on tarpeen vaatiessa täydennetty kotimaisilla Z-koodeilla Graafisten kuvausten merkinnät Sanoman eri tasot on kuvattu tietosisältöä visuaalisesti havainnollistavalla mallilla, jona on käytetty <oxygen/> XML editorin pyykkinaru kuvaa elementtien suhteista. Tässä on listattu mallissa käytettyjen notaatioiden määritelmät: Notaatio blankko Määritelmä Pakollinen, esiintyy yhden kerran 0..1 Ei pakollinen, mutta voi esiintyä vain kerran 1.. Elementin tulee esiintyä vähintään kerran ja se voi esiintyä useita kertoja. 0.. Elementin käyttö on vapaaehtoista, mutta se voi esiintyä useita kertoja Soveltamisohjeessa käytetyt attribuutit Soveltamisohjeessa käytetyt attribuutit on kuvattu komponenttikirjaston johdanto-osassa. 3 Sanomamääritys Kappaleessa käsitellään tällä soveltamisohjeella katettava skenaario sekä UBL sanoman rakenne, jonka esittämistapa on kuvattu kappaleessa Kooste-elementtien esittämistapa. Seuraava UML - luokkamalli kuvaa tilauksen yleisen rakenteen. Kuva ei sisällä kaikkia sanomaan sisältyviä tietoja vaan ainoastaan ne, jotka ovat sanoman rakenteen ymmärtämisen kannalta keskeisiä. 5/15

6 3.1 Katettava skenaario Tällä soveltamisohjeella pyritään kattamaan elintarviketeollisuuden ja keskusliikkeiden sekä myymälöiden välisten sähköisten tilausten tietosisältötarpeet EU:n sisäisessä kaupankäynnissä. On todennäköistä, että määriteltyä sanomarakennetta voidaan käyttää sellaisenaan myös suurella osalla muuta kaupan toimialaa Reunaehdot Tuotteilla on standardoitu tuotetunniste (EAN/GTIN) ja osapuolten välillä on olemassa oleva puitesopimus, joka kattaa kaupalliset ehdot. 6/15

7 3.2 Toimialakohtaiset laajennukset Otsikkotason laajennukset Elementti Tyyppi Toisto Kuvaus Shipment BBIE 0..1 Lähetyserän tiedot Käytetään tilauksissa, joihin liittyy terminaalitoimitus. 3.3 Sanoman otsikkotaso Sanoman otsikkotasolla välitetään koko dokumenttia koskevat tiedot, kuten dokumentin tunniste ja päiväys. 7/15

8 8/15

9 Elementti Tyyppi Toisto Kuvaus UBLVersionID BBIE 1 UBL versio UBL versio, johon sanoman rakenne perustuu. Tämän soveltamisohje perustuu UBL 2.0 versioon, joten sanomissa käytetään tekstiä 2.0 CustomizationID BBIE 0..1 Räätälöintitunniste ProfileID BBIE 0..1 Profiilitunniste Yksilöi käyttäjäryhmän, jonka tarpeisiin sanoma on räätälöity. Yksilöi profiilin, johon tämä sanoma liittyy. ID BBIE 1 Tilauksen yksilöivä tunniste IssueDate BBIE 1 Tilauksen päiväys Tilauksen kaupallisella tasolla yksilöivä tunniste eli ostotilausnumero. Tilauksen luontipäivämäärä tilausjärjestelmässä IssueTime BBIE 0..1 Tilauksen kellonaika Note BBIE 0..n Lisätiedot Tilauksen luontikellonaika tilausjärjestelmässä Tilaukseen liittyvät lisätiedot, joita ei voida esittää muualla sanoman rakenteessa. Vain yksi lisätietokenttä per kieli. AdditionalDocumentReference ASBIE 0..n Lisäliitteen- tai viitteen tiedot Tilaukseen liittyvä liite ja viite, jota ei voida esittää muualla sanoman rakenteessa. BuyerCustomerParty ASBIE 1 Ostajan osapuolitiedot SellerSupplierParty ASBIE 1 Myyjän osapuolitiedot AccountingCustomerParty ASBIE 0..1 Laskutettavan osapuolitiedot 9/15 Välitetään vain mikäli laskutettava osapuoli on eri kuin ostajaosapuoli. Voidaan määrittää erillisellä sopimuksella, jolloin ei ole pakollinen tilauksella.

10 Delivery ASBIE 0..1 Toimitusta koskevat tiedot DeliveryTerms ASBIE 0..1 Toimitusehto OrderLine ASBIE 1..n Tilausrivin tiedot Annetaan otsikkotasolla, kun tilaukseen liittyy vain yksi toimitus. 3.4 Sanoman rivitaso Elementti Tyyppi Toisto Kuvaus Note BBIE 0..1 Lisätiedot LineItem ASBIE 1 Tilausrivin tiedot Tilausriviin liittyvät lisätiedot, joita ei voida esittää muualla tilausrivin rakenteessa. DocumentReference ASBIE 0..n Lisäliitteen- tai viitteen tiedot Tilausriviin liittyvä liite ja viite, jota ei voida esittää muualla tilausrivin rakenteessa. 10/15

11 3.4.1 Rivitiedot (LineItem) Elementti Tyyppi Toisto Kuvaus ID BBIE 1 Rivitunniste / rivinumero Quantity BBIE 1 Tilattu määrä Tilauksella ostajan järjestelmän luoma rivin yksilöivä tunniste, jonka myyjä palauttaa viitetietona tilausvahvistuksella samassa kentässä. Määrän yksikkö annetaan suhteessa tuotteen standarditunnisteeseen. Molemmat ilmaistaan joko toimitus- tai kuluttajapakkauksissa. 11/15

12 Delivery ASBIE 0..1 Toimitustiedot DeliveryTerms ASBIE 0..1 Toimitusehto OrderedShipment ASBIE 0..1 Lähetyserän tiedot Item ASBIE 1 Tuotteen tiedot Välitetään rivitasolla vain mikäli tilaukseen liittyy useita toimituksia, muuten sanoman otsikkotasolla. Terminaalitoimitukseen liittyvät lähetyserän kuljetusta koskevat tiedot 3.5 Sanomakohtaiset kooste-elementit Sanomaan sisältyvät kooste-elementit, joita käytetään sellaisenaan myös muissa sanomissa, on listattu omassa dokumentissaan komponenttikirjasto. Tähän kappaleeseen on koottu ne kooste-elementit, joiden sisältöä on rajattu tai tarkennettu suhteessa näihin määrityksiin Toimitus (Delivery) Käyttökohde: Order.Delivery Order.OrderLine.LineItem.Delivery Elementti Tyyppi Toisto Kuvaus DeliveryLocation ASBIE 1 Toimitusosoite Toimitusosoite (Location.Address) sekä mahdollinen yksilöity paikkatieto (Location.ID), kuten hyllytysohje. RequestedDeliveryPeriod ASBIE 0..1 Pyydetty toimitusajankohta Ostajan määrittämä ajankohta, jolloin tuotteet tulisi toimittaa vastaanottajalle. DeliveryParty ASBIE 1 Toimituksen vastaanottaja (osapuoli) Tuote (Item) Käyttökohde: Order.OrderLine.LineItem.Item Elementti Tyyppi Toisto Kuvaus Name BBIE 0..1 Tuotenimi BuyersItemIdentification ASBIE 0..1 Ostajan tuotetunniste 12/15

13 SellersItemIdentification ASBIE 0..1 Myyjän tuotetunniste StandardItemIdentification ASBIE 1 Standardi tuotetunniste EAN (GTIN) tuotetunniste. ID:llä pakollinen attribuutti: schemeid= GTIN AdditionalItemIdentification ASBIE 0..1 Tuotteen lisätunniste AdditionalItemProperty ASBIE 0..n Tuotteen lisäominaisuus ItemInstance ASBIE 0..n Yksilöity tuote Esimerkiksi kuluttajapakkausten määrä toimituspakkauksessa Lisätiedot tuotteen yksilöintiin, mm. tuote-erää koskevat tiedot. Voidaan käyttää tilauksella välittämään tieto ostajan pyytämästä tuotteen parasta ennen päiväyksestä (ItemInstance. LotIdentification. AdditionalItemProperty) Toimituserä (Shipment) Käyttökohde: Order. OrderLine.LineItem.OrderedShipment.Shipment Order.UBLExtensions.UBLExtension.ExtensionContent.Order.Shipment Käytetään tilauksissa, joihin liittyy terminaalitoimitus. Elementti Tyyppi Toisto Kuvaus ID BBIE 1 Toimituserän yksilöivä tunniste Consignment ASBIE 1 Lähetyserän tiedot ShipmentStage ASBIE 0..1 Kuljetusetapin tiedot Välitetään ainoastaan terminaalin tiedot: Consignment.ConsigneeParty Tiedot liittyen kuljetusetappiin terminaalista toimituksen vastaanottajalle - Reittitunniste ShipmentStage.TransportMeans.JourneyID - Edelleenlähetyspaikan sijainti ShipmentStage.LoadingLocation 13/15

14 4 Sanomaesimerkki Tässä kappaleessa on XML esimerkki tilauksen minimitietosisällöstä. Tämä ei välttämättä vastaa sanoman kaupallista minimitietosisältö vaan kyseessä on esimerkki, mitä tietoja tilaussanomaan tulee sisältyä jokaiseen asianyhteydestä riippumatta. Kattavampi XML esimerkki on esitetty erillisessä tiedostossa. 4.1 XML esimerkki <?xml version="1.0" encoding="utf-8"?> <Order xmlns="urn:oasis:names:specification:ubl:schema:xsd:order-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:commonaggregatecomponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:commonbasiccomponents-2" xmlns:qdt="urn:oasis:names:specification:ubl:schema:xsd:qualifieddatatypes-2" xmlns:udt="urn:un:unece:uncefact:data:draft:unqualifieddatatypesschemamodule:2" xmlns:ccts="urn:oasis:names:specification:ubl:schema:xsd:corecomponentparameters-2"> <cbc:ublversionid>2.0</cbc:ublversionid> <cbc:id>tilauksen_tunniste</cbc:id> <cbc:issuedate>tilauksen_päiväys</cbc:issuedate> <cac:buyercustomerparty> <cac:party> <cac:partyidentification> <cbc:id schemeid="tunnistejärjestelmän_tunniste">ostajan_ovt_tunniste</cbc:id> </cac:partyidentification> <cac:partyname> <cbc:name>ostajan_nimi</cbc:name> </cac:partyname> </cac:party> </cac:buyercustomerparty> <cac:sellersupplierparty> <cac:party> <cac:partyidentification> <cbc:id schemeid="tunnistejärjestelmän_tunniste">myyjän_ovt_tunniste</cbc:id> </cac:partyidentification> <cac:partyname> <cbc:name>myyjän_nimi</cbc:name> </cac:partyname> </cac:party> </cac:sellersupplierparty> <cac:delivery> <cac:deliverylocation> <cac:address> <cbc:streetname>katuosoite</cbc:streetname> <cbc:cityname>postitoimipaikka</cbc:cityname> <cbc:postalzone>postinumero</cbc:postalzone> <cac:country> <cbc:identificationcode>iso3166-1_maakoodi</cbc:identificationcode> </cac:country> </cac:address> </cac:deliverylocation> <cac:deliveryparty> <cac:partyidentification> <cbc:id schemeid="tunnistejärjestelmän_tunniste"> TOIMITUKSEN_VASTAANOTTAJAN_OVT_TUNNISTE </cbc:id> </cac:partyidentification> <cac:partyname> 14/15

15 <cbc:name>toimituksen_vastaanottajan_nimi</cbc:name> </cac:partyname> </cac:deliveryparty> </cac:delivery> <cac:orderline> <cac:lineitem> <cbc:id>tilausrivin_tunniste</cbc:id> <cbc:quantity unitcode="tilausyksikkö">tilattu_määrä</cbc:quantity> <cac:item> <cac:standarditemidentification> <cbc:id schemeid="tunnistejärjestelmän_tunniste"> TILATUN_MÄÄRÄN_MUKAINEN_EAN_TUNNISTE </cbc:id> </cac:standarditemidentification> </cac:item> </cac:lineitem> </cac:orderline> </Order> 15/15