SOLENOVO OY Käyttöönottosuunnitelman liite 5d: asiakkuuden hallinta (tuonti) StudentaPlus www.solenovo.fi
STATUS 17.11.2011 / jketo 24.1.2012 / jketo Päivitetty kuvaus CSV import tyyppiseksi, koska järjestelmät pystyvät tuottamaan tätä muotoa. 12.9.2012 / ktanska Tarkistettu sisältö ja ajantasaistettu muutoksien osalta. vesak REST rajapinta kuvattu vesak Lisätty koodistoryhmien täsmäystiedot integraatioarvojen kanssa. / mattim Lisätty kenttien tyypit ja maksimipituudet Sisällysluettelo 1. Johdanto... 3 2. Tiedonsiirtotapa... 3 3. Tietosisältö... 4 4. Esimerkkiaineisto... 7 www.solenovo.fi 2
1. Johdanto StudentaPlus-järjestelmään on toteutettu yhdensuuntainen tuontirajapinta asiakastietojen ja asiakkaisiin liittyvien henkilöiden siirtämistä varten asiakkuuden hallinta-järjestelmästä () StudentaPlus-järjestelmään. Asiakastietojen ja henkilöiden vientiä StudentaPlussasta :ään ei toteuteta, koska on määritelty näiden tietojen suhteen primäärilähteeksi. StudentaPlussassa on kuitenkin raportteja (esim. yritysluettelo), joiden perusteella voi tehdä manuaalista tarkistusta sen suhteen onko StudentaPlussaan lisätty esim. yrityksiä, joita ei ole :ssä. HUOM! Rajapinnan käyttö ei ole StudentaPlussan näkökulmasta pakollista. Asiakkaat ja heidän henkilönsä voidaan perustaa StudentaPlussaan myös suoraan ulkopuolisina organisaatioina ja ulkopuolisina henkilöinä. Lisäksi siirron onnistumista varten on varmistuttava, että :n ja StudentaPlussan koodistojen arvot vastaavat toisiaan. Nämä tiedot on aina rajapinnan käyttöönoton yhteydessä synkronoitava järjestelmien välillä. -tietojen siirto tehdään kerran yössä ja avaintietoina käytetään :n tarjoamaa asiakkaan tai henkilön yksilöivää avainta (ID). StudentaPlus päättelee :n tarjoaman ID:n perusteella, mitkä asiakkaista tai henkilöistä lisätään uusiksi tiedoiksi ja mitkä päivitetään jo olemassa olevien tietojen tilalle. Rajapinta ei mahdollista tietojen poistoa. 2. Tiedonsiirtotapa :stä tulevien asiakas- ja henkilötietojen siirto toteutetaan REST rajapintana, missä välitetään kerralla yksi asiakasorganisaation tai asiakasorganisaation henkilötieto. -järjestelmästä on siis muodostettava kaksi eri siirtoa: yksi asiakastietoja ja yksi henkilötietoja varten. Tiedot voivat sisältää kaikki :stä tarvittavat tiedot tai vain muuttuneet tietot. Kertaluonteisesti tiedot voidaan ladata myös CSV muodossa konversion yhteydessä. CSV formaatti kuvattu dokumentin lopussa. www.solenovo.fi 3
Yksilöitävien tietojen perusteella päivitetään olemassa olevaa tietoa, jos tietoa ei löydy yksilöintitiedon perusteella tieto lisätään uutena. 3. Tietosisältö Siirrettävissä olevat tiedot asiakkaan (ulkopuolinen organisaatio) ja henkilöiden (ulkopuolinen henkilö) osalta :sta StudentaPlussaan on esitetty taulukoissa alla: Taulukko 1: Siirrettävät asiakastiedot :sta Studentaan :n asiakkaan ID StudentaPlus (*=pakollinen) Tietotyypp i Pituus (max) Huomio Tunniste* Merkkijono 100 Oltava yksilöivä tieto. Voisi olla esimerkiksi _$_ID, jotta nähtäisiin suoraan :sta tulleet StudentaPlussaa n perustetuista. Nimi Nimi* Merkkijono 100 Nimi suomeksi. Lyhenne Lyhenne* Merkkijono 100 Voidaan muodostaa nimen perusteella. Aakkosnimi Aakkosnimi* Merkkijono 100 Voidaan muodostaa nimen perusteella. Y-tunnus Y-tunnus Merkkijono 100 Alkamispäivä Päättymispäivä Organisaatiotyyppi Asiakastieton voimassaolon alkamispäivä* Asiakastieton voimassaolon päättymispäivä* Organisaatiotyyppi * Päiväys 10 Pakollinen arvo, voi olla es tiedonsiirtopvm. Tiedon muoto pp.kk.vvvv Päiväys 10 Pakollinen arvo, voi olla es. 21.12.2112, jos päättymisaika ei tiedossa. Tiedon muoto pp.kk.vvvv Merkkijono 40000 0 Koodistojen sisällön täsmättävä www.solenovo.fi 4
Yrityssektori Yrityssektori Merkkijono 40000 0 Toimiala Toimiala Merkkijono 40000 0 Henkilökuntaluokk a Yrityksen koko Merkkijono 40000 0 integraatio arvon kanssa** Koodistoryhmä: ULKORGTYYP Koodistojen sisällön täsmättävä integraatio arvon kanssa** Koodistoryhmä: YRITSEKT Koodistojen sisällön täsmättävä integraatio arvon kanssa** Koodistoryhmä: TOIMALA Koodistojen sisällön täsmättävä integraatio arvon kanssa** Koodistoryhmä: YRITKOKO Puhelinnumero Puhelinnumero Merkkijono 255 Faksi Fax-numero Merkkijono 255 Sähköposti Sähköpostiosoite Merkkijono 255 WWW-sivut WWW-sivut Merkkijono 255 Pankki (BIC) Pankki (BIC) Merkkijono 255 Tilinumero (IBAN) Tilinumero (IBAN) Merkkijono 255 Postiosoite1 Postiosoite1 Merkkijono 150 Osoitteen rooli = Postiosoite. Postiosoite2 Postiosoite2 Merkkijono 150 Postinumero Postinumero Merkkijono 50 Postitoimipaikka Postitoimipaikka Merkkijono 150 Maa Maa Merkkijono 150 Käyntiosoite1 Käyntiosoite1 Merkkijono 150 Osoitteen rooli = Käyntiosoite. Käyntiosoite2 Käyntiosoite2 Merkkijono 150 Postinumero Postinumero Merkkijono 50 Postitoimipaikka Postitoimipaikka Merkkijono 150 Maa Maa Merkkijono 150 www.solenovo.fi 5
Laskutusosoite1 Laskutusosoite1 Merkkijono 150 Osoitteen rooli = Laskutusosoite. Laskutusosoite2 Laskutusosoite2 Merkkijono 150 Postinumero Postinumero Merkkijono 50 Postitoimipaikka Postitoimipaikka Merkkijono 150 Maa Maa Merkkijono 150 **Virhetilanteeksi luetaan tapaukset, joissa :stä tulevia tietoja ei saada täsmättäyä StudentaPlussan vastaaviin tietoihin koodiarvojen tai avaintietojen perusteella. Taulukko 2: Siirrettävät henkilötiedot :sta Studentaan :n asiakkaan ID Henkilön rooli ( roolit: työntekijä, päätöksentekijä, vaikuttaja yms.) StudentaPlus (*=pakollinen) Ulkopuolinen organisaatio* Henkilön rooli organisaatiossa* Tietotyyppi Pituus (max) Huomio Merkkijono 100 Tiedon perusteella henkilö liitetään oikeaan asiakkaaseen. Merkkijono 400000 Koodistojen sisällön täsmättävä integraatio arvon kanssa.** Sovitaan käyttöönoton yhteydessä, mitkä roolit ovat käytössä ja miten roolit yhteensovitetaan Studentan rooleihin. Koodistoryhmä: ULKORGHLOROOL Sukunimi Sukunimi* Merkkijono 100 Etunimi Etunimet* Merkkijono 100 Kutsumanimi Kutsumanimi* Merkkijono 100 Aakkosnimi Aakkosnimi* Merkkijono 100 Oltava muotoa Sukunimi, Etunimi. Henkilön tunniste Henkilönumero* Merkkijono 50 Oltava yksilöivä tieto. Arvoalueet eivät saa mennä päällekkäin StudentaPlussan kanssa. www.solenovo.fi 6
Työpuhelin tai Puhelinnumero Merkkijono 255 matkapuhelin Sähköposti Sähköpostiosoite Merkkijono 100 Pankki (BIC) Pankki (BIC) Merkkijono 255 Tilinumero Tilinumero (IBAN) Merkkijono 255 (IBAN) Postiosoite1 Postiosoite1 Merkkijono 150 Osoitteen rooli = Postiosoite. Postiosoite2 Postiosoite2 Merkkijono 150 Postinumero Postinumero Merkkijono 50 Postitoimipaikka Postitoimipaikka Merkkijono 150 Maa Maa Merkkijono 150 Muuosoite1 Muuosoite1 Merkkijono 150 Osoitteen rooli = Muu osoite. Muuosoite2 Muuosoite2 Merkkijono 150 Postinumero Postinumero Merkkijono 50 Postitoimipaikka Postitoimipaikka Merkkijono 150 Maa Maa Merkkijono 150 HUOM! :n ja StudentaPlussan koodistojen synkronointia ei ole määritelty toteutettavaksi, joten StudentaPlussan pääkäyttäjien on huolehdittava siitä, että organisaatiotyyppi-, yrityssektori-, toimiala- ja yrityksen koko - luokitukset ja ulkopuolisen henkilön rooli-kooditukset ovat yhtenevät. Organisaation henkilöroolin päivitys poistaa mahdollisen henkilönumeron perusteella samalle henkilölle kuuluvan muun roolin organisaatiosta. Liittymässä tuleva henkilörooli lisätään aina organisaatiolle. Henkilön organisaation roolin poistoa ei voi liittymän kautta tehdä. 4. Esimerkkiaineisto REST rajapinta Rajapinta palauttaa http -statuskoodin 200 OK, jos päivitys/lisäys onnistuu. Jos tapahtuu virhetilanne paluukoodina on 400: Bad Request. Rajapinnan käyttö on mahdollista vain _API_ALLOWED_IP_MASK ohjausparametrilla määritellyistä IP osoitteista. Lisääjä/muokkaaja käyttäjäksi tulee rajapinnan kautta lisätyille/päivitetyille tiedoille INTEGRATION_USER_ID parametrilla määritelty käyttäjä. www.solenovo.fi 7
URL -osoitteen muoto asiakasrajapinnalle: https://localhost/integration/rest/crm/organizationupdate Lähetettävä tiedostomuoto Content-type: application/xml HUOM! companysector arvon täsmättävä YRITSEKT koodistoryhmän integraatioarvon kanssa. companyfield arvon täsmättävä TOIMALA koodistoryhmän integraatioarvon kanssa. type arvon täsmättävä ULKORGTYYP koodistoryhmän integraatioarvon kanssa. companysize arvon täsmättävä YRITKOKO koodistoryhmän integraatioarvon kanssa. Esimerkkitiedosto: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <organization> <identification>tunniste24</identification> <name>nimi</name> <abbreviation>lyhennysxxxx</abbreviation> <alphabeticalname>organisaatio aakkosin</alphabeticalname> <startdate>1.1.2000</startdate> <enddate>12.12.2013</enddate> <companybusinessid>xxaabb</companybusinessid> <companysector>kunta</companysector> <companyfield>elektroniikka</companyfield> <type>asiakas</type> <companysize>5-9 henkiloa</companysize> <fax>fax</fax> <postaddressstreetname>katu</postaddressstreetname> <postaddresspostalcode>054634564</postaddresspostalcode> www.solenovo.fi 8
<postaddresscity>pello</postaddresscity> <officeaddressstreetname>toimistokatu 432</officeAddressStreetName> <officeaddresspostalcode>234223</officeaddresspostalcode> <officeaddresscity>tornio</officeaddresscity> <billingaddressstreetname>rahoitustie 43</billingAddressStreetName> <billingaddresspostalcode>234234</billingaddresspostalcode> <billingaddresscity>vaasa</billingaddresscity> <bic>bicc</bic> <iban>ibani</iban> <telephone>544-23423423</telephone> <email>asdf@asdfasdf.com</email> <webpage>http://asdfasdf.com</webpage> </organization> Esimerkkikutsu wget:llä: wget --post-file=organization.xml https://localhost/integration/rest/crm/organizationupdate --header "Content-type: application/xml" URL -osoitteen muoto asiakasrajapinnalle: https://localhost/integration/rest/crm/organizationpersonupdate wget --post-file=person.xml https://localhost/integration/rest/crm/organizationpersonupdate --header "Content-type: application/xml" Lähetettävä tiedostomuoto Content-type: application/xml HUOM! role arvon täsmättävä ULKORGHLOROOL koodistoryhmän integraatioarvon kanssa. www.solenovo.fi 9
Esimerkkitiedosto: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <organizationperson> <organizationidentification>tunniste24</organizationidentification> <role>johtaja</role> <lastname>pekkkala</lastname> <firstnames>pekka</firstnames> <callname>pekka</callname> <alphabeticalname>sukula</alphabeticalname> <personnumber>6345</personnumber> <phonenumber>2304-234234234</phonenumber> <email>p.sukula@asdfasdf.com</email> <bic>bic</bic> <iban>ibaa</iban> <postaddressstreetname>postitie 23</postAddressStreetName> <postaddressstreetname2>--</postaddressstreetname2> <postaddresspostalcode>23424</postaddresspostalcode> <postaddresscity>postila</postaddresscity> <postaddressnation>finland</postaddressnation> <homeaddressstreetname>kotitie 234</homeAddressStreetName> <homeaddressstreetname2>--</homeaddressstreetname2> <homeaddresspostalcode>423424</homeaddresspostalcode> <homeaddresscity>kotila</homeaddresscity> <homeaddressnation>finland</homeaddressnation> </organizationperson> Konversio CSV tiedostomuodot: asiakastiedot: identification;name;abbreviation;alphabeticalname;companybusinessid;startdate;endda te;type;companysector;companyfield;companysize;telephone;fax;email;webpage;bic;iban www.solenovo.fi 10
;postaddressstreetname;postaddressstreetname2;postaddresspostalcode;postaddresscity ;postaddressnation;officeaddressstreetname;officeaddressstreetname2;officeaddresspo stalcode;officeaddresscity;officeaddressnation;billingaddressstreetname;billingaddr essstreetname2;billingaddresspostalcode;billingaddresscity;billingaddressnation ABC_1;Name 1;Abrev 1;Aakkosnimi 1;Y00001;1.1.2000;12.12.2112;Asiakas;Kunta;;5-9 henkiloa;004-34534;005-345345;;http://www.google.com;bic1;iban1;kauppakatu 1;kerros 1;00043;Kerava;Finland;Toimistotie 1;kerros 4;00545;Keitele;;Laskuosoite 5;;00023;HELSINKI; ABC_2;Name 2;Abrev 2;Aakkosnimi 2;Y00002;1.1.2000;12.12.2112;Asiakas;Kunta;;6-9 henkiloa;004-34535;005-345346;;http://www.google.com;bic2;iban2;kauppakatu 2;kerros 2;00044;Kerava;Finland;Toimistotie 2;kerros 5;00546;Keitele;;Laskuosoite 6;;00024;HELSINKI; ABC_3;Name 3;Abrev 3;Aakkosnimi 3;Y00003;1.1.2000;12.12.2112;Asiakas;Kunta;;7-9 henkiloa;004-34536;005-345347;;http://www.google.com;bic3;iban3;kauppakatu 3;kerros 3;00045;Kerava;Finland;Toimistotie 3;kerros 6;00547;Keitele;;Laskuosoite 7;;00025;HELSINKI; Organisaation henkilötiedot: organizationidentification;role;lastname;firstnames;callname;alphabeticalname;perso nnumber;phonenumber;email;bic;iban;postaddressstreetname;postaddressstreetname2;pos taddresspostalcode;postaddresscity;postaddressnation;homeaddressstreetname;homeaddr essstreetname2;homeaddresspostalcode;homeaddresscity;homeaddressnation ABC_1;johtaja;Johtaja 1;Jokke 1;Jokke 1;Johtaja, Jokke 1;EXT_100000;023-62343;tmp234@osoite.com;bic 1;iban 1;Postitie 1;;00432;Porvoo;;Kotitie 1;;00466;KOTILA; ABC_2;johtaja;Johtaja 2;Jokke 1;Jokke 1;Johtaja, Jokke 2;EXT_100001;023-62344;tmp234@osoite.com;bic 2;iban 2;Postitie 2;;00433;Porvoo;;Kotitie 2;;00467;KOTILA; ABC_3;johtaja;Johtaja 3;Jokke 1;Jokke 1;Johtaja, Jokke 3;EXT_100002;023-62345;tmp234@osoite.com;bic 3;iban 3;Postitie 3;;00434;Porvoo;;Kotitie 3;;00468;KOTILA; missä kenttien välisenä erottimena on puolipiste (;). Jos jokin tieto puuttuu, niin se esitetään tyhjänä erotinmerkkien välissä. HUOM! Esimerkkiaineisto ei luonnollisestikaan ole tosiaineistoa. www.solenovo.fi 11