Produktinfo WebService. integrasjonsbeskrivelse

Transkript

1 Produktinfo WebService integrasjonsbeskrivelse

2 Innhold PRODUKTINFO WEBSERVICE 1 INTEGRASJONSBESKRIVELSE 1 DOKUMENTINFORMASJON 3 1. ARKITEKTUR OG TEKNOLOGI ARKITEKTUR OG DATAFLYT TEKNOLOGI Valg av teknologi Dokument- og bildetyper Om Dokument- og bildelenker 6 2. IMPLEMENTASJON WEB SERVICES Visual Studio.Net Legg til "Web Reference" Dokumentlenkefunksjoner ProduktInfo.HentDokumentLenkerXML Bildelenkefunksjoner ProduktInfo.HentBildeLenkerXML ProduktInfo.HentBildeLenkerXMLTyped ProduktInfo.HentBildeLenkerHTML Kombinert bilde- og dokumentlenkefunksjoner ProduktInfo.HentDokumentBildeLenkerXML ProduktInfo.HentDokumentBildeLenkerXMLTyped ProduktInfo.HentDokumentBildeLenkerHTML Sortimentsfunksjoner ProduktInfo.SendSortiment ProduktInfo.SendSortimentTyped Diverse funksjoner ProduktInfo.HentProdukterForVareeier ProduktInfo.HentPREDokumentHTML Datasett DokumentLenker Produkter JAVASCRIPT HentPreDokHTML HentDokLenker HentBildeLenkerJS HentDokumentBildeLenkerJS STATISKE LENKER Html kode for en statisk lenke Lenker til enkeltbilder Feil! Bokmerke er ikke definert HentBilde HentBildeData STILARK 24 2 of 24

3 Dokumentinformasjon TEKNISK MANUAL ProduktInfoService integrasjonsbeskrivelse for vareeiere Author Kjetil Gullen Created 8-Jun-04 Changed 3-May-07 Customer Norsk byggtjeneste oda as Customers ref Hans Hope Projectname ProduktInfoService Proj.no Doc.no. Revision 2 Pages 24 3 of 24

4 1. Arkitektur og teknologi 1.1. Arkitektur og dataflyt 1. Sluttbruker navigerer inn på vareeiers nettsider. 2. Vareeiers webserver leser dokumentlenker og produktinfo fra NBT server og integrerer dette i nettsidene som returneres til sluttbruker. 3. Sluttbruker klikker på en dokumentlenke som peker direkte til siste versjon av dokumentet på NBT s server. 2. Vareeier server Internett Teknologi Vareeiers system henter dokumentlenker via en av følgende teknologier: NBT Server 3. Dokument Sluttbruker Vareeier NBT.Net HTTP XML Web Service Javascript HTTP Javascript kode Aspx web page Statiske lenker HTTP Dokument Aspx web page Implementering kan gjøres uavhengig av vareeiers plattform, da Javascript og statiske lenker blir tolket og utført av sluttbrukerens nettleser. 4 of 24

5 Valg av teknologi Hva kan jeg bruke og hva bør jeg bruke? Web services Anbefalt Ved å bruke web services kan vareeier sy sammen data fra Byggtjenestens produktinfo-tjeneste med egne websider. Denne metodikken overlater ingenting til klienten. Dokumenter lastes direkte ned fra produktinfo databasen til Byggtjenesten og vil derfor alltid være oppdatert. Egner seg bra til Microsoft.Net løsninger og andre løsninger med XML Web Services støtte. Javascript Her overlates jobben til sluttbrukerens nettleser, og krever støtte for å kjøre Javascript i nettleseren. Kan enkelt integreres i publiseringsløsninger og eksisterende sider. Dokumenter lastes direkte ned fra produktinfo databasen til Byggtjenesten og vil derfor alltid være oppdatert. Nettleseren til sluttbrukeren prosesserer et skript som integrerer innholdet i nettsiden til vareeier. Strenge sikkerhetsinnstillinger i klientens nettleser kan gi problemer. Statiske lenker Her overlates mer manuelt arbeid til vareeier. Vareeier må selv legge inn lenker og produktinformasjon i sine websider. Sluttbrukerens nettleser trenger ikke å prosessere noe mer enn den gjør ved bruk av "Web services". Ved endringer av data i databasen hos Byggtjenesten må vareeier selv manuelt oppdatere innholdet sitt. Dette krever ingen kommunikasjon mellom vareeiers og Byggtjenestens system ved generering av sider. Dette kan derfor gå noe raskere. Man må linke til enkeltdokumenter, og har ingen mulighet for å hente ut alle tilgjengelige dokumenter som en liste. 5 of 24

6 Dokument- og bildetyper Det blir brukt forkortelser for de ulike dokumenttypene. I denne tabellen finner du forklaringer på dokumenttypene. FDV Forvaltning, drift og vedlikehold HMF Helse, miljø og sikkerhet faktablad HMS Helse, miljø og sikkerhet datablad MAN Monteringsanvisning MLJ Miljødeklarasjon PB Produktbilde PRE Produktdatablad SER Sertifikater TEK Teknisk beskrivelse Om dokument- og bildelenker Produktinfoservice gir klienter muligheten til bruke en vares varenummer til å finne dokumentasjon for varen i tilfeller der dokumentasjonen er assosiert med vare, modul eller modulnummer. Det er også mulig å bruke varenummer eller modulnummeret til å finne dokumentasjon assosiert med dokumentmodulnummeret til en vare. Vær oppmerksom på at det ikke er mulig å hente lenker til dokumenter ved å spesifisere modulnummer eller dokumentmodulnummer til varer som har dokumentasjonen assosiert med varenummer. Det er heller ikke mulig å bruke dokumentmodulnummeret til en vare dersom dokumentasjonen er assosiert med varenummer eller modulnummer. Dette skyldes at det kan eksistere mange varer i den modulen som blir spesifisert. HMS dokumentasjon og bilder kan ikke assosieres med dokumentmodulnummer. 6 of 24

7 2. Implementasjon 2.1. Web services En "Web Service" er en applikasjon som eksponerer funksjoner over internett, slik at andre applikasjoner kan bruke disse. Disse kan da gjøre interne ressurser (i dette tilfellet produktinfo databasen til NBT) eller funksjoner som er avhengig av slike ressurser tilgjengelig for andre eksterne systemer. "Web Services" er basert på XML og SOAP. I Visual Studio.Net, som vi skal ta for oss, er det innebygd støtte for dette, slik at dette enkelt kan taes i bruk Visual Studio.Net Første skritt er å legge til en "Web Reference" til prosjektet man ønsker å integrere web servicen med. For å kunne legge til en referanse til Byggtjenesten sin tjeneste må man være tilknyttet internett Legg til "Web Reference" Velg "Project" på hovedmenyen og "Add Web Reference" fra nedtrekksmenyen. Etter å ha valgt "Add Web reference" vises en dialog, se neste side. 7 of 24

8 Følgende dialog vises. Sett markøren i URL feltet og skriv: Dette er adressen til Byggtjenestens produktinfotjeneste. Klikk på ved siden av adressefeltet. Når Visual Studio har hentet informasjon om tjenesten vises denne informasjonen i området nedenfor. (se bildet øverst på siden) Deretter klikker du på, slik at referansen legges til i prosjektet ditt. Et nytt "Namespace" er nå tilgjengelig i din Visual Studio.Net applikasjon. Dette er no.byggtjeneste.produktinfo. 8 of 24

9 Dette betyr at hvis du skriver "no.byggtjeneste.produktinfo." i Visual Studio.Net vil tilgjengelige klasser i produktinfotjenesten vises. (se bildet nedenfor) For å aksessere funksjoner i Byggtjenestens system må ProduktInfo-klassen benyttes. Resten av kapitlet beskriver disse funksjonene. 9 of 24

10 Dokumentlenkefunksjoner ProduktInfo.HentDokumentLenkerXML Parametere: Vare/Modul nummer til ønsket produkt. Metoden returnerer et typet datasett med alle tilgjengelige dokumentlenker og url er til disse for et angitt produkt. Eksemplet under lister disse for produktet i en datagrid. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); DataGrid1.DataSource = pinfo.hentdokumentlenkerxml(" "); } DataGrid1.DataBind(); Neste eksempel itererer igjennom alle dokumentlenker og henter ut URL og pulikasjonstype i 2 variabler i en løkke. no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); no.byggtjeneste.produktinfo.dokumentlenker dl = pinfo.hentdokumentlenkerxml(" "); foreach(no.byggtjeneste.produktinfo.dokumentlenker.dokumentlenkerow DokLenke in dl.dokumentlenke) { string sdokumenturl = DokLenke.Url; } string spublikasjonstype = DokLenke.Publikasjonstype; 10 of 24

11 Bildelenkefunksjoner Følgende funksjoner returnerer sett med lenker til bilder ProduktInfo.HentBildeLenkerXML Parametere: Vare/Modul nummer til ønsket produkt og størrelse på bilde. Metoden returnerer et typet datasett med alle tilgjengelige bildelenker og url er til disse for et angitt produkt. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); DataGrid1.DataSource = pinfo.hentbildelenkerxml(" ", "small"); } DataGrid1.DataBind(); ProduktInfo.HentBildeLenkerXMLTyped Parametere: Vare/Modul nummer til ønsket produkt og størrelse på bilde. Metoden returnerer et typet datasett med alle tilgjengelige bildelenker og url er til disse for et angitt produkt. Bildestørrelse angis som en verdi av typen ImageSize. Størrelsene som støttes er ImageSize.small og ImageSize.large. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); DataGrid1.DataSource = pinfo.hentbildelenkerxmltyped(" ", no.byggtjeneste.produktinfo.imagesize.small); } DataGrid1.DataBind(); 11 of 24

12 ProduktInfo.HentBildeLenkerHTML Parametere: Vare/Modul nr til ønsket produkt Metoden returnerer en liste med lenker i form av en HTML formatert tekst streng som kan settes direkte inn i websiden, via f.eks. en Label-kontroll slik eksemplet under viser. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); string shtml = pinfo.hentbildelenkerhtml( " " ); } Label1.Text = shtml; Kombinert bilde- og dokumentlenkefunksjoner Følgende funksjoner returnerer lenker til både bilder og dokumenter i samme lenkesett ProduktInfo.HentDokumentBildeLenkerXML Parametere: Vare/Modul nummer til ønsket produkt og størrelse på bilde. Metoden returnerer et typet datasett med alle tilgjengelige bilde- og dokumentlenker og url er til disse for et angitt produkt. Bildestørrelse angis som en verdi av typen ImageSize. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); DataGrid1.DataSource = pinfo.hentdokumentbildelenkerxml(" ", "small"); } DataGrid1.DataBind(); ProduktInfo.HentDokumentBildeLenkerXMLTyped Parametere: Vare/Modul nummer til ønsket produkt og størrelse på bilde. Metoden returnerer et typet datasett med alle tilgjengelige bilde- og dokumentlenker og url er til disse for et angitt produkt. Bildestørrelse angis som en verdi av typen ImageSize. Størrelsene som støttes er ImageSize.small og ImageSize.large. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); DataGrid1.DataSource = pinfo.hentdokumentbildelenkerxmltyped(" ", no.byggtjeneste.produktinfo.imagesize.small); 12 of 24

13 } DataGrid1.DataBind(); ProduktInfo.HentDokumentBildeLenkerHTML Parametere: Vare/Modul nr til ønsket produkt Metoden returnerer en liste med lenker i form av en HTML formattert tekst streng som kan settes direkte inn i websiden, via f.eks. en Label-kontroll slik eksemplet under viser. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); string shtml = pinfo.hentdokumentbildelenkerhtml( " " ); } Label1.Text = shtml; 13 of 24

14 Sortimentsfunksjoner Følgende funksjoner gjør det mulig å sende en samling dokumenter/bilder som et ziparkiv til en gitt epostadresse ProduktInfo.SendSortiment Parametere: string EpostAdresse, string[] VareListe, int[] DoktypeListe Metoden lager et ZIP arkiv med angitte dokumenter og/eller bilder for angitte produkter og sender lenke til denne via e-post til angitt adresse. Metoden returnerer også lenken til arkivet. Lenken er gyldig i 1-2 dager før arkivet slettes. Ved bruk av utypede data (for eksempel hvis du benytter Java eller PHP, eller andre språk som ikke har støtte for.net objekter), benyttes disse verdiene: Navn Tallverdi ALLE 0 HMS 1 PRE 2 TEK 3 FDV 4 MAN 5 SER 6 MLJ 7 HMF 8 PB 9 Disse verdiene bør med fordel lagres i en enum datatype eller tilsvarende, slik at man har kontroll på verdiene på ett sted. Eksemplet under viser kode for å sende HMS dokument for og ALLE dokumenter for no.byggtjeneste.produktinfo.produktinfo p = new no.byggtjeneste.produktinfo.produktinfo(); p.sendsortiment( "navn@firma.no", new string[] {" ", " "}, new int[] {1, 0} ); 14 of 24

15 ProduktInfo.SendSortimentTyped Parametere: string EpostAdresse, string[] VareListe, DokumentTypeValg[] DoktypeListe Denne metoden gjør det samme som SendSortiment men med typet variabel for valg av dokumenttyper. Typene for dokumenttyper finnes i WebServicen under namespacet no.byggtjeneste.produktinfo.dokumenttypevalg Gyldige verdier for dokumenttypen er: Eksemplet under viser kode for å sende HMS dokument for og ALLE dokumenter for p.sendsortimenttyped( "navn@firma.no", new string[] {" ", " "}, new no.byggtjeneste.produktinfo.dokumenttypevalg[] {no.byggtjeneste.produktinfo.dokumenttypevalg.hms, no.byggtjeneste.produktinfo.dokumenttypevalg.alle} ); Første parameter inneholder da en liste med NOBB Modul/varenummer, mens andre parameter inneholder en liste med dokumenttypene for de respektive NOBB modul/varenummer. Disse 2 listene må være like lange, og index 0 i NOBB Modul/varenummer listen vil få dokumenter av typen spesifisert i index 0 for dokumenttype listen. Ønsker du f. eks. å sende flere dokumenttyper for et produkt men ikke alle dokumenttyper må samme produkt spesifiseres flere ganger, se eksemplet under. p.sendsortimenttyped( "navn@firma.no", new string[] {" ", " "}, new no.byggtjeneste.produktinfo.dokumenttypevalg[] {no.byggtjeneste.produktinfo.dokumenttypevalg.hms, no.byggtjeneste.produktinfo.dokumenttypevalg.pre} ); I eksemplet er samme produktet ( ) spesifisert 2 ganger med PRE og HMS dokument. 15 of 24

16 Diverse funksjoner ProduktInfo.HentProdukterForVareeier Parametere: Navn på ønsket vareeier av produkter. Metoden henter alle produkter til en gitt vareeier og returnerer NOBB Modul numrene til disse i et typet datasett. Eksempel: Bygg og Tre AS er kun et eksempel og ligger ikke nødvendigvis i Byggtjeneste databasen. For å få eksemplet til å fungere er det viktig at du har lagt en DataGrid komponent på websiden din og at Button1_Click metoden er koblet til en Click hendelse på en knapp på samme siden. Bytt også ut Bygg og tre AS med ditt eget firmanavn ProduktInfo.HentPREDokumentHTML Parametere: VareModul nr til ønsket produkt Metoden returnerer PRE dokument i en HTML formatert tekst streng som kan settes direkte inn i websiden, via f.eks. en Label-kontroll slik eksemplet under viser. private void Button1_Click(object sender, System.EventArgs e) { no.byggtjeneste.produktinfo.produktinfo pinfo = new WebServiceTest.no.byggtjeneste.produktinfo.ProduktInfo(); string shtml = pinfo.hentpredokumenthtml( " " ); } Label1.Text = shtml; - Ønsker du å definere hvordan dokumentlenkene skal se ut se kapittel of 24

17 Datasett Datasettene er klasser som gir brukervennlig og type sikker tilgang til data som returneres fra produktinfo tjenesten DokumentLenker Datasett som inneholder lenker til forskjellige publikasjonstyper av dokumenter. Skjemaet kan lastes ned fra Feltnavn Beskrivelse Type NOBBModulNr Produktets NOBB Tekststreng (string) modulnummer Publikasjonstype Publikasjonstype for Tekststreng (string) dette dokumentet. Url Url til dokumentet Tekststreng (string) Produkter Datasett som inneholder modulnummer til produkter. Skjemaet kan lastes ned fra Feltnavn ModulNr Type Tekststreng (string) 17 of 24

18 2.2. JavaScript JavaScript er kode som kjøres av sluttbrukerens nettleser. Ved å legge med kodelenker (til funksjonene beskrevet nedenfor) i vareeiers nettsider, vil systemet hente inn informasjon fra Byggtjenestens system direkte inn i vareeiers nettsider HentPreDokHTML Adresse: Parametere: NOBBModulNr Returnerer: PRE dokument i HTML for angitt produkt direkte inn i vareeiers nettsider. Følgende HTML element vil be nettleseren til sluttbruker om å hente produktinformasjon fra NBT sin web server for produkt med nr Sett dette elementet inn der du f.eks. ellers ville lagt inn PRE dokumentet i din webside, bytt ut NOBBModulNr parameteren med dine produktnummer. - Ønsker du å definere hvordan dokumentlenkene skal se ut se punkt of 24

19 HentDokLenker Adresse: Parametere: NOBBModulNr, Direction, IconFile (nærmere beskrivelse lenger ned) Returnerer: HTML med lenker til angitt produkt direkte inn i vareeiers nettsider. Følgende HTML element vil be nettleseren til sluttbruker om å hente dokument lenker til produktet i en horisontal liste. Resultatet ser slik ut i sluttbrukers nettleser: Parametere: Navn NOBBModulNr * Direction * Beskrivelse Produktnummeret du ønsker dokumentlenkene til. Retning lenkene vises på skjerm. Verdier H Horisontalt V Vertikalt (illustrert i bildet til høyre) IconFile Eksempel: Direction=H URL til ikon Eksempel: IconFile= gif Ikonene vises foran dokumenttekstene illustrert på bildet under: * Er påkrevet - Ønsker du å definere hvordan dokumentlenkene skal se ut, se kapittel of 24

20 HentBildeLenkerJS Adresse: Parametere: VareModulNr, direction og size. Returnerer: HTML med lenker til angitt produkt direkte inn i vareeiers nettsider. Resultatet ser slik ut i sluttbrukers nettleser: Parametere: - Parameterene er av samme type som i kapittel Ønsker du å definere hvordan dokumentlenkene skal se ut se kapittel HentDokumentBildeLenkerJS Adresse: Parametere: VareModulNr, direction og size. Returnerer: HTML med lenker til angitt produkt direkte inn i vareeiers nettsider.. Resultatet ser slik ut i sluttbrukers nettleser: Parametere: - Parameterene er av samme type som i tabellen i kapittel. - Ønsker du å definere hvordan dokumentlenkene skal se ut se kapittel of 24

21 2.3. Statiske lenker Dette brukes typisk fordi vareeier selv ønsker full kontroll over egne websider og/eller ikke ønsker å benytte de andre tilgjengelige metodene å integrere seg mot. Tilgjengelige statiske lenker for et angitt produkt kan hentes ut fra denne webadressen: Html kode for en statisk lenke Lenker defineres i html med et <a> tag. Denne har et attributt som heter href, som er adressen du finner i Url kolonnen på produktlenker listen ovenfor (i produktlenker.aspx). Et eksempel på dette kan være følgende: 21 of 24

22 HentBilde Adresse: Parametere: Vare eller modulnummer Returnerer: URL til et bilde. Parametere: Navn VareModulNr size Beskrivelse Produktnummeret du ønsker dokumentlenkene til. Størrelsen på bildet, må være enten small eller large. Dersom size parameteren utelukkes, vil bildet være i størrelse small. HentBilde.aspx vil returnere en vanlig lenke direkte til bildet hos leverandøren av bildet. Forskjellen på HentBilde.aspx og HentBildeData.aspx er at HentBildeData.aspx (kapittel 2.3.3) laster ned bildet fra serveren til bildeleverandøren til produktinfoservice serveren og returnerer en lenke dit istedet. Eksempel: HentBilde.aspx bør hente en url som ser slik ut: 22 of 24

23 HentBildeData Adresse: Parametere: VareModulNr Returnerer: URL til et bilde. Parametere: Navn VareModulNr size Beskrivelse Produktnummeret du ønsker dokumentlenkene til. Størrelsen på bildet, må være enten small eller large. Dersom size parameteren utelukkes, vil bildet være i størrelse small. Eksempel: HentBildeData forutsetter at VareModulNr er det nummeret bildet er registrert på i bildedatabasen. Dvs man kan ikke sende inn et varenummer å få et bildet som er registrert på varenummerets modulnummer i bildedatabasen. 23 of 24

24 2.4. Stilark Ønsker du å definere hvordan dokumentlenkene skal se ut kan dette defineres med følgende stilark: Eksempel:.NBTHEADER { font-weight : bold; font-size : 10pt; color : black; }.NBTLINK { font-size : 10pt; font-weight : normal; color : Black; }.NBTIMAGE { border : 0px; } Ønsker du å skjule f.eks. overskriften kan du legge til følgende i.nbtheader stilen: display : none; 24 of 24