EDIELfikäyttöpaikkarekisterin. tekniset ohjeet

EDIELfikäyttöpaikkarekisterin tekniset ohjeet

1 (10) Sisällysluettelo 1 EDIELfi-käyttöpaikkarekisterin Web Service -rajapinta... 2 2 Lukurajapinta... 2 2.1 Tarkka haku... 2 2.2 Villikorttihaku... 2 3 Hakutoiminnot... 2 3.1 Osoitehaku... 2 3.2 Käyttöpaikkatunnushaku... 3 3.3 Hakujen tulokset... 3 4 Tietokannan kentät... 3 5 Tunnukset ja käyttöoikeus... 3 6 SFTP tiedonsiirto EDIELfi-portaalin käyttöpaikkarekisteriin... 3 6.1 SFTP Palvelin... 4 7 Avaintenluonti... 5 7.1 Avainten hallintaprosessi... 6 8 Tiedoston kuvaus ja tallennus... 7 8.1 Esimerkkejä... 7 9 EDIELfi-kannan virhelokit, ohjeita ja vinkkejä... 8 9.1 Yleistä... 8 10 Virhelokit... 9 10.1 Virheelliset rivit: <yhtiön osapuolitunnus>.csv_error_rows_log.txt... 9 10.2 Tuplarivit: <yhtiön osapuolitunnus>.csv_duplicates.txt... 9 11 Yleisiä vinkkejä... 9

2 (10) EDIELfi-käyttöpaikkarekisterin tekniset ohjeet 1 EDIELfi-käyttöpaikkarekisterin Web Service -rajapinta 2 Lukurajapinta 2.1 Tarkka haku Ediel.fi portaalin käyttöpaikkarekisterin SOAP Web Service -rajapinta löytyy osoitteessa: https://soap.ediel.fi/wsgetregistersoap Rajapintaan on toteutettu molemmat käyttöpaikkarekisteriä koskevat haut, käyttöpaikkatunnushaku ja osoitehaku. Rajapinnan kautta voi ainoastaan hakea tietoja tietokannasta, tietojen kirjoittaminen ei ole mahdollista. Haku olettaa aina annettujen hakuehtojen olevan tarkkoja ja näyttää vain hakuehtoja vastaavat tarkat tulokset. 2.2 Villikorttihaku Käyttäjillä on kaksi eri vaihtoehtoista hakutoiminallisuutta käytettävissään Web Service - hauissa. Vaihtoehtoisesti haluttaessa voi hyödyntää rajapintaa myös osoitteessa: https://soap.ediel.fi/wsgetregistersoapwildcard Vaihtoehtoinen rajapinta käyttää osoitehaussa joustavampaa hakumahdollisuutta tarkenteen osalta. Esim. jos haetaan tarkenteella 5a6, mutta verkonhaltija on tallentanut tarkenteen muodossa 5as6 käyttöpaikkaa ei löydy tarkan haun kautta. Mikäli haulla ei löydy tarkkaa tulosta, rajapinta tekee automaattisesti uuden haun käyttäen tarkenteeseen annettua ensimmäistä numeroa (esim. 5 mikäli annettu tarkenne oli alun perin 5a6 ). Molempiin rajapintoihin käy samat yhtiökohtaiset tunnukset sekä muut mahdolliset asetukset vain url-osoite on eri. Huomioksi, että vaihtoehtoista rajapintaa käyttämällä on mahdollisuus myös yhteen ei toivottuun osumaan, mikäli löytyy esim. tarkka tulos tarkenteella 5, mutta tämä ei olekaan etsitty käyttöpaikka. Mikäli järjestelmänne käyttää automaattisesti yhden tuloksen myötä löytynyttä käyttöpaikkaa, käytättehän vain tarkkoja hakuehtoja olettavaa rajapintaa. 3 Hakutoiminnot 3.1 Osoitehaku Osoitehakua kutsutaan funktiolla: wsrekisteri.identifiersearch(streetname,streetnumber,postnumber,networkid) Esimerkki: wsrekisteri.identifiersearch("mannerheimintie","66a2","00260","hke000");

3 (10) Tässä haussa kadun nimi on pakollinen tieto, muut kentät voivat olla tyhjiä ("") Huomioksi, että kadunnumero täytyy antaa kokonaisena esim. esimerkin käyttöpaikka ei löydy jos numero-osassa on vain 66 tai 66A 3.2 Käyttöpaikkatunnushaku Käyttöpaikkatunnushakua kutsutaan funktiolla: wsrekisteri.addresssearch(meteringpointid,networkid) Esimerkki: wsrekisteri.addresssearch("1666","hke000") Haussa käyttöpaikkatunnus on pakollinen 3.3 Hakujen tulokset Web Service rajapinta palauttaa käyttöpaikkarekisterin tietokannasta hakuehtoja vastaavat kentät. Hakutulokset on rajattu 200 riviin. 4 Tietokannan kentät Tietoja haettaessa rajapinnan yli on tärkeä muistaa, että joitain osoitetietoja on jouduttu käsittelemään tietojen tallennusvaiheessa, jolloin käyttöpaikkarekisterin tietokannan tiedot eivät täydellisesti vastaa kantaan alun perin toimitettuja tietoja. Käytännössä tämä tarkoittaa joidenkin jakeluverkon haltijoiden toimittamia tietoja, joissa kadunnimi ja rakenne on kirjoitettu samaan kenttään. Nämä osoitetiedot on katkaistu ensimmäisen numeron kohdalta ja jaoteltu kahteen kenttään: kadunnimi ja tarkenne. 5 Tunnukset ja käyttöoikeus Tarvittavat tunnukset palvelun käyttöä varten saat ottamalla yhteyttä Fingridin tiedonvaihtopalveluihin tiedonvaihto@fingrid.fi Käyttöpaikkarekisteri on tarkoitettu kaikille Suomessa toimiville sähkön vähittäismyyjille sekä jakeluverkon haltijoille, joilla on voimassaoleva osapuolitunnus ja jotka ovat solmineet tiedonvaihdon palvelusopimuksen Fingridin kanssa. Käyttöehdot ovat tarkemmin määritelty tiedonvaihdon palvelusopimuksessa. 6 SFTP tiedonsiirto EDIELfi-portaalin käyttöpaikkarekisteriin Käyttöpaikkarekisterin SFTP tiedonsiirtopalvelu on tarkoitettu Suomessa toimiville jakelunverkonhaltijoille, joilla on voimassa oleva Fingridin kanssa solmittu tiedonvaihdon palvelusopimus. Tiedonvaihdon palvelusopimuksessa on määritelty käyttöehdot tarkemmin. Palvelun tarkoituksena on mahdollistaa jakeluverkkojen toimittaa käyttöpaikkatietonsa (käyttöpaikkatunnus ja osoite) käyttöpaikkarekisteriin sähkön myyjäyhtiöiden hyödynnettäväksi.

4 (10) 6.1 SFTP Palvelin SFTP palvelu löytyy palvelimelta, jonka IP-osoite on 192.49.98.101 SFTP tiedonsiirtoon käytetty portti on 22, sama jota käytetään SSH yhteyksiin. Lisäksi jakeluverkonhaltijan on luotava yksityinen ja julkinen avain (ks. kappale 3), ja sen jälkeen asetettava oma FTP palvelimensa käyttämään yksityistä avainta aina ottaessaan yhteyden käyttöpakkarekisterin SFTP palvelimelle. Yhteysprotokollan pitää aina olla SFTP. Avainparin julkinen avain tulee toimittaa käyttöpaikkarekisterin SFTP-palvelimen ylläpitäjälle sähköpostilla (sd.fingrid@tieto.com), sähköpostissa tulee lisäksi mainita vähintään yhtiön nimi ja sähkömarkkinoiden osapuolitunnus. Osapuolitunnus toimii myös käyttäjänimenä otettaessa yhteys SFTP palvelimelle. Jokainen csvtiedosto tulee lähettää käyttäen käyttäjänimenä osapuolen osapuolitunnusta. Älä lähetä kumpaakaan avainta Fingridille! Kuva 1. Private keyn asetus ja yhteysparametrit siirtoon:

5 (10) Sama WinSCP:ssä: Jos lähetetään useampien eri yhtiöiden tiedostoja samalla kertaa, huomioksi että tietoturvasyistä jokainen tiedosto tulee kuitenkin lähettää kirjautuneena aina ko. yhtiön omalla tunnuksella (User / User name). 7 Avaintenluonti Avainparin voit luoda useilla eri tavoilla, internetistä löytyy useita ilmaisia avainparin luontiin soveltuvia sivustoja, esim: Windows: https://winscp.net/eng/docs/ui_puttygen Linux/Mac: https://help.github.com/articles/generating-ssh-keys Avaimen tulee olla muotoa RSA (tai SSH-2 RSA) ja pituus 2048 bittiä Jos avainpari luodaan PuTTYGenillä, vie se OpenSSH muotoon (voit kopioida avaimen ylhäältä laatikosta ja käyttää Conversions -painiketta tallentaaksesi avaimen tiedostoksi). Voit käyttää oletusasetuksia. Vanhemmissa PuTTY Generator -versioissa on suositeltuna muodon valintana SSH-2 RSA, kun taas uudemmista PuTTYGen-versioissa avaimen muodoksi tulee valita RSA (ks. Kuva2). Testeissä molemmat tyypit ovat toimineet tiedostojen siirrossa.

6 (10) Kuva 2 Esimerkki avaimen luonnista PuTTY Key Generatorilla: 1. Klikkaa ensin Generate -painiketta ja vie nuoli punaisella rajatun laatikon päälle niin saat avaimen näkyviin 2. Kopioi avain punaisella rajatusta laatikosta, kopioidun tekstin eli julkisen avaimen voi lähettää suoraan sähköpostilla. HUOM! Tarkista että avain kopioituu kokonaisuudessaan! 3. Tämän jälkeen tallenna avain tiedostoksi Conversation painikkeen avulla (menu valikossa) valitsemalla "Export OpenSSH key". Jos et ole asettanut salasanaa "Key passphrase" kenttään, sinulle tulee varoitus tässä vaiheessa, mutta voit tallentaa halutessasi avaimen myös ilman salasanaa. Tallenna avain paikkaan, josta löydät sen sillä sijaintia tarvitaan myöhemmin kun otat yhteyttä SFTP-palvelimelle (ks. Kuva1 Key file -kenttä). 7.1 Avainten hallintaprosessi Julkinen avain lähetetään palvelun ylläpitäjälle osoitteeseen sd.fingrid@tieto.com. Ole ensin yhteydessä Fingridin tiedonvaihtopalveluihin (tiedonvaihto@fingrid.fi) jos olet uusi käyttäjä tai sinulla on kysyttävää nykyisestä tunnuksestasi. Älä lähetä kumpaakaan avainta Fingridille! Luodut avaimet ovat voimassa vuoden, jonka jälkeen ne eivät enää toimi ja ne tulee uusia. Varoitus avaimen vanhentumisesta lähetetään etukäteen.

7 (10) 8 Tiedoston kuvaus ja tallennus Käyttöpaikkarekisteriin toimitettavan tiedoston tulee olla csv-muotoinen, jossa kentät on erotettu toisistaan puolipisteellä (;). Tiedostossa tulee käyttää UTF-8 tai ANSI merkistöä. Tiedoston kentät ja järjestys: 1. Käyttöpaikkatunnus (merkkijono, pakollinen) 2. Jakeluverkonhaltijan osapuolitunnus (pakollinen) 3. Kadun nimi (pakollinen) 4. Osoitteen tarkenne (ilman välilyöntejä, vapaaehtoinen) 5. Postinumero (numero, pakollinen) Tiedoston jokaisella rivillä tulee siis olla kaikki 5 kenttää ja jakeluverkonhaltijan kaikki käyttöpaikkatiedot tulee toimittaa yhdessä tiedostossa. Virheellisiä rivejä ei voida tallentaa käyttöpaikkarekisterin tietokantaan. Erityisesti tiedoston toisen rivin tulisi olla muodoltaan korrekti, sillä siitä tarkistetaan koko tiedoston ajokelpoisuus, ettehän siis unohda pakollisia kenttiä. Tiedosto tulee nimetä jakeluverkon haltijan osapuolitunnuksen mukaan ja tiedoston tyyppi on csv, esim. HKE000.csv. Jakeluverkonhaltijan lähettämä uusi tiedosto korvaa kaikki käyttöpaikkarekisterin tietokantaan tallennetut vanhat tiedot. Tietojen täydentäminen tai päivittäminen ei ole mahdollista vaan kaikki käyttöpaikkatiedot on toimitettava joka kerta yhdessä tiedostossa. Jos kadun nimen ja osoitteen tarkenteen (kentät 3 ja 4) kirjoittaminen eri kenttiin tiedostossa ei ole tietojen lähettäjälle mahdollista, voidaan tiedot kirjoittaa myös pelkästään kenttään 3 ja jättää kenttä 4 tyhjäksi. Jos kenttä 4 on jätetty tyhjäksi, tiedoston vastaanottava järjestelmä katkaisee kenttään 3 kirjoitetun tiedon ensimmäisen numeron kohdalta ja sijoittaa loppuosan kenttään 4. Tiedoston ei tule sisältää mitään muuta tietoa kuin edellä mainittujen 5 kentän tiedot jokaiselta käyttöpaikalta! Älä käytä minkäänlaisia otsikkorivejä ensimmäisenä rivinä, vaan aloita suoraan datarivillä. Tiedosto tallennetaan SFTP-palvelimella osapuolitunnuksen alaiseen csv-kansioon, esim. AAA000/csv. Mikäli siirtoon käytetään jotain ohjeessa mainitsematonta sovellusta, niin ilmoitetut määrittelyt voivat poiketa syntaksiltaan riippuen sovelluksesta. Huomioi myös, että hakemistosta löytyy ajojen jälkeen myös virhelokitiedostot, jotka kannattaa tarkistaa aina välillä. 8.1 Esimerkkejä Alla on esitetty joitain esimerkkejä tiedoston rivien tietosisällöstä. 1. 123456789;HKE000;VanhaViertotie;12A51;00320 2. 123456790;HKE000;VanhaViertotie;12A52;00320

8 (10) 3. 123456791;HKE000;VanhaViertotie12A53;;00320 Esimerkeissä 1 ja 2 on kaikki kentät täytetty. Esimerkissä 3 on kentät 3 ja 4 yhdistetty kenttään 3 ja kenttä 4 on jätetty tyhjäksi. Esimerkissä 3 tiedot tallentuvat käyttöpaikkarekisterin tietokantaan muodossa: 123456791;HKE000;VanhaViertotie;12A53;00320 9 EDIELfi-kannan virhelokit, ohjeita ja vinkkejä 9.1 Yleistä Käyttöpaikkarekisteriin lähetetyissä csv-tiedostoissa löytyy silloin tällöin kantaan ajoa edeltävien tarkastusten yhteydessä määrittelyistä ja ohjeista poikkeavia rivejä, jotka tulisi korjata, jotta kannassa löytyy mahdollisimman tarkkaa ja oikeaa tietoa. Ongelmarivien havaitsemiseksi on luotu virhelokitiedostot, joista näkyy mitkä rivit ei ole ajon myötä siirtyneet kantaan. Siirtoyhteyksiä luotaessa ja käyttöpaikkatiedostojen lähetystä kokeiltaessa ongelmia on aiheuttanut pääsääntöisesti kahdentyyppiset virheelliset rivit. Ongelmarivit olivat sen verran erityyppisiä, että ne jaoteltiin kahteen eri virhelokiin. Toiseen kerätään syntaktisesti eli sisällöltään virheelliset rivit ja toiseen rivit, joissa yhtiöllä esiintyy samaa käyttöpaikkatunnusta useamman kerran (duplikaattirivit). Virhelokit syntyvät joka kerta kun yhtiön csv-tiedosto ajetaan kantaan, käytännössä noin 15 minuutin sisällä ajon aloituksesta virherivit näkyvät tiedostoissaan. Ne löytyvät samasta hakemistosta minne yhtiöt siirtävät csv-hakemistonsa, ja ovat siellä vapaasti luettavissa heti luonnin jälkeen. Ne ovat tiedostotyypiltään.txt-muotoisia ja siten luettavissa tavallisimmilla tekstinkäsittelyohjelmilla, kuten esim. Notepad. Molemmat virhelokit syntyvät jokaisella ajokerralla, oli virheellisiä rivejä tai ei. Kumpikin kirjoitetaan edellisessä ajossa syntyneiden virhelokien päälle, eli vanhoja virhelokeja ei ole saatavilla, ainoastaan uusimmasta ajosta syntyneet. Virhelokeista näkee miten (ja milloin) yhtiön viimeisin ajo on sujunut, eli niitä kannattaa käydä tarkastelemassa aina aika-ajoin. Virhelokit syntyvät siis joka ajon yhteydessä, mutta jos lokitiedostojen koko on 0 KB se tarkoittaa, ettei yhtään virheellistä riviä löytynyt ajossa ja kaikki viimeisimmän csv-tiedoston rivit on saatu onnistuneesti ajettua kantaan. Jos syy jonkin rivin virhelokiin päätymiselle ei aukene tämän ohjeen avulla, voit kysyä syytä osoitteesta sd.fingrid@tieto.com. Liitä viestiin mukaan myös ko. virheloki tai kopio ongelmarivistä.

9 (10) 10 Virhelokit 10.1 Virheelliset rivit: <yhtiön osapuolitunnus>.csv_error_rows_log.txt Virheellisten rivien virhelokiin kerätään selvästi syntaktisesti virheelliset rivit, esim. o o o o o Postinumeron pitää olla kokonaan numeroita, eikä se saa olla yli viiden merkin mittainen, eikä pelkkä nolla. Postinumeron oikeellisuutta esim. tien nimeen nähden ei tarkisteta. Joka rivin toinen kenttä pitää olla sama kuin sen yhtiön hakemisto mistä csv:tä ajetaan kantaan, esim. jos yhtiön osapuolitunnus on JVH000, sen pitää löytyä myös joka rivin toisesta kentästä. Rivillä vain neljäs kenttä eli tarkenne saa olla tyhjä, muissa kentissä pitää olla jotain sisältöä. Kenttiä pitää olla joka rivillä 5 kpl. Kenttiä erottavana välimerkkinä pitää käyttää puolipistettä. Rivin lopussa puolipistettä ei tarvita. Ne rivit, jotka eivät mene tarkistuksista läpi siirretään tähän virhelokiin, ja jäljelle jääneet korrektit rivit ajetaan kantaan. Vinkki: Otsikkorivi on turha ja sen voi jättää pois. Ajoskripti tulkitsee sen syntaktisesti virheelliseksi datariviksi ja siirtää sen tähän virhelokiin. Yksi otsikkorivi ei kuitenkaan haittaa muiden rivien ajoa kantaan. 10.2 Tuplarivit: <yhtiön osapuolitunnus>.csv_duplicates.txt Tuplarivien virhelokiin kerätään kaikki ne rivit, joista löytyy samoja käyttöpaikkatunnuksia, eli riveillä on sama osapuolitunnus sekä käyttöpaikkatunnus useammalla kuin yhdellä rivillä. Kaikki duplikaattirivit poistettiin ajosta kokonaan, koska seurannan myötä löytyi paljon käyttöpaikkaduplikaatteja, joissa oli eri osoite ja/tai tarkenne siitä huolimatta, että käyttöpaikkatunnus oli riveillä sama. Automatiikka ei osaa päätellä tai arpoa kumpi osoitteista on se oikea, joten kaikki duplikaattirivit poistetaan. Duplikaattirivit listautuvat virhelokiin, ja uniikit rivit jatkavat normaaliin ajoon. Yhtiöt voivat tuplarivien virhelokilistauksen avulla löytää ja päivittää tiedot uniikkiriviksi yhtiön csv-tiedostoon seuraavaan ajoon. Vinkki: Tämä virheloki kannattaa kaikkien yhtiöiden ehdottomasti tarkistaa aluksi ainakin kerran, ja seurata lokia myös myöhemmin. Lokiin päätyneet rivit saattavat olla syntaksiltaan täysin korrekteja rivejä, eli tällöin tarvitsee vain tarkistaa, että käyttöpaikkatiedostoon jätetään jäljelle vain se oikea uniikki rivi (1 kpl). 11 Yleisiä vinkkejä Virhelokit nimettiin uudelleen ja otettiin käyttöön 19.5.2017, joten ohjeessa kuvatut virhelokit löytyvät vain sen jälkeen ajetuissa ajoissa. Tätä päivää aiemmissa ajoissa virhelokeja kyllä syntyi, mutta ne oli nimetty toisin. Vanhat virhelokikansiot on pääsääntöisesti poistettu yhtiöiden

10 (10) hakemistoista, mutta mikäli vanhoja (erinimisiä kuin tässä ohjeessa mainitut) virhelokeja vielä löytyy ne voi poistaa. Siirtovälineistä esim. WinSCP tallentaa välillä myös vanhoja näkymiä hakemistoista muistiin. Jos näyttää, että virhelokit hakemistonäkymässä vaikuttavat vanhoilta, klikkaa hiiren oikealla näppäimellä esim. tiedostojen koko sarakkeessa ja valitse Refresh, niin saat päivitettyä näkyville päivitetyn tilanteen.