Webservice til EUD-indberetning til Datavarehuset Dato 24-02-2017 Version Status 1.1 Gældende fra og med den 1. marts 2017 Ansvarlig Lars Strange
Side 2 af 9 Indhold 1 Indledning... 3 2 Kontakt Webservicen... 3 3 Webservicens Get-metoder... 3 3.1 GetXmlSchema... 3 4 Validere data... 3 4.1 ValidateXmlAgainstSchema... 3 4.1.1 Eksempel på OK-svar... 4 4.1.2 Eksempel på Fejl-svar... 4 5 Overføre data... 5 5.1 UploadData... 5 5.1.1 Eksempel på OK-svar... 5 5.1.2 Eksempel på Fejl-svar... 5 6 Udviklingsværktøjer... 6 Bilag 1: Eksempel på valid XML-data... 7 Bilag 2: Eksempel på SoapUI request... 9 Bilag 3: Eksempel på SoapUI response... 9
Side 3 af 9 1 Indledning Dette notat beskriver kort webservicen tilhørende EUD-indberetningen til Datavarehuset (herefter Webservicen). Webservicen er udviklet og driftes af Styrelsen for It og Læring. Indholdet er beskrevet i dokumentet Indberetningsstruktur for EUD-indberetning til Datavarehuset. 2 Kontakt Webservicen Webservicen findes i et testmiljø. Servicebeskrivelsen findes på denne adresse: https://statistik-ext.unic.dk/eudindberetningws/uploadservice.svc?singlewsdl Webservicen udstiller en simpel HelloWorld-metode, der blot returnerer Hello World. Det anbefales at foretage den første test mod denne metode. Der findes pt. ikke en adresse til driftversionen. 3 Webservicens Get-metoder Webservicen udstiller en række Get-metoder, som kort beskrives nedenfor. 3.1 GetXmlSchema Denne metode returnerer det aktuelle schema, som XML-data forventes at overholde, når der overføres data fra de administrative systemer til Webservicen. Det anbefales, at leverandøren altid sikrer sig, at XML-data overholder det schema, der udstilles via GetXmlSchema og validerer XML-data lokalt (i klienten) mod schemaet før overførelse til Webservicen. GetXmlSchema returnerer schemaet i XML-format. 4 Validere data 4.1 ValidateXmlAgainstSchema Denne metode validerer overførte XML-data mod det aktuelle schema. Der returneres et ValidateXmlAgainstSchemaResult som resultat af valideringen. Hvis valideringen ikke finder fejl, vil ErrorCount være 0. Ellers vil ErrorCount være større end 0, og der vil være en liste af ValidationError-elementer med fejlmeddelser. Fejlmeddelelserne er henvendt til udviklere og lister.net fejlmeddelelsen samt den linje i XMLfilen, der fejler i forhold til schemaet. ValidateXmlAgainstSchema har alene til formål at teste XML-data mod det aktuelle schema og er en hjælp til udvikling af XML-eksport i de administrative systemer. Se Bilag 1 for eksempel på XML-data, der overholder det aktuelle schema og returnerer et OK-svar.
Side 4 af 9 4.1.1 Eksempel på OK-svar <ValidateXmlAgainstSchemaResult xmlns:i="http://www.w3.org/2001/xmlschema-instance"> <ErrorCount>0</ErrorCount> <Message>Data blev modtaget og valideret korrekt.</message> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> 4.1.2 Eksempel på Fejl-svar <ValidateXmlAgainstSchemaResult xmlns:i="http://www.w3.org/2001/xmlschema-instance"> <ErrorCount>2</ErrorCount> <Message>Der er 2 valideringsfejl</message> <ValidationErrors> <ErrorMessage>Linje: 81 udløser fejlen: [The 'http://www.stil.dk/euddvhindberetning/:karaktervaerdi' element is invalid - The value '03' is invalid according to its datatype 'String' - The Enumeration constraint failed.]</errormessage> <ErrorMessage>Linje: 84 udløser fejlen: [The 'http://www.stil.dk/euddvhindberetning/:evalueringsform' element is invalid - The value 'Skriftlig dansk' is invalid according to its datatype 'http://www.stil.dk/euddvhindberetning/:evalueringsformtype' - The Enumeration constraint failed.]</errormessage> </ValidationErrors> </ValidateXmlAgainstSchemaResult>
Side 5 af 9 5 Overføre data 5.1 UploadData Denne metode anvendes til at overføre data, der skal indberettes. Der valideres mod det aktuelle schema, som ved anvendelse af metoden ValidateXmlAgainst- Schema beskrevet i afsnit 4.1. Derudover foretages krydsvalideringer i indberetningen (fx startdatoer mod slutdatoer). Såfremt data er fejlfrie, gemmes data og erstatter evt. tidligere overførelser foretaget i indberetningsperioden. Hvis valideringen ikke finder fejl, vil ErrorCount være 0. Ellers vil ErrorCount være større end 0, og der vil være en liste af ValidationError-elementer med fejlmeddelser. 5.1.1 Eksempel på OK-svar <UploadDataResponse xmlns="http://www.stil.dk/euddvh"> <UploadDataResult xmlns:i="http://www.w3.org/2001/xmlschemainstance"> <ErrorCount>0</ErrorCount> <Message>Data blev modtaget og valideret korrekt.</message> <ValidationErrors/> </UploadDataResult> </UploadDataResponse> 5.1.2 Eksempel på Fejl-svar <UploadDataResponse xmlns="http://www.stil.dk/euddvh"> <UploadDataResult xmlns:i="http://www.w3.org/2001/xmlschemainstance"> <ErrorCount>4</ErrorCount> <Message>Der er 4 valideringsfejl</message> <ValidationErrors> <ErrorMessage>Koen: Personens køn (Mand) stemmer ikke med sidste ciffer i PersonId (2).</ErrorMessage> <ErrorMessage>PersonId: Personens køn (Mand) stemmer ikke med sidste ciffer i PersonId (2).</ErrorMessage> <ErrorMessage>Startdato: Startdato ('2015-05-26') skal ligge indenfor Elevens Startdato ('2015-07-14') og Elevens Slutdato ('2017-09- 26')</ErrorMessage> <ErrorMessage>Startdato: Startdato ('2016-09-21') skal være før Slutdato ('2016-08-02')</ErrorMessage> </ValidationErrors> </UploadDataResult> </UploadDataResponse>
Side 6 af 9 6 Udviklingsværktøjer Webservicen er udviklet i.net-frameworket og kan umiddelbart tilgås i Visual Studio ved at tilføje WSDL som service reference. Følgende gratis udviklingsværktøjer kan anbefales til test og debug: soupui (http://www.soapui.org/) kan bl.a. oprette soap requests, der kan sendes mod webservicen. Fiddler (http://www.telerik.com/fiddler) analyserer webservicekald og webservicesvar. Bilag 2 og 3 er eksempler på hhv. soap request og tilhørende soap response, når XML-data i bilag 1 anvendes.
Side 7 af 9 Bilag 1: Eksempel på valid XML-data <Indberetning xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns="http://www.stil.dk/euddvhindberetning/"> <Version>1.0</Version> <SystemVersion>bc640df7-eed1-4130-abb7-49da40271631</SystemVersion> <JournalNummer>18e20c18-bbb9-4530-b1c7-4c68696d1563</JournalNummer> <IndberettendeEnhed>999999</IndberettendeEnhed> <Email>fake@stil.dk</Email> <Person> <PersonId>2572111142</PersonId> <Fornavne>449eca56-4b78-4214-a5a0-50e68fb4b015</Fornavne> <Efternavn>f7eff888-d3f0-4166-a709-6e3a11289485</Efternavn> <Foedselsdato>2016-09-04</Foedselsdato> <Koen>2</Koen> <Elev> <Uddannelsesinstitution>100136</Uddannelsesinstitution> <Uddannelse>c850</Uddannelse> <Startdato>2014-07-14</Startdato> <Slutdato>2017-09-26</Slutdato> <Speciale> <Version>b7f6</Version> <Speciale>dd46</Speciale> <Startdato>2016-09-21</Startdato> <Slutdato>2016-10-02</Slutdato> </Speciale> <Elevtype> <Elevtype>03710f45-a</Elevtype> <Version>fa5e</Version> <Startdato>2015-05-26</Startdato> <Slutdato>2015-12-08</Slutdato> </Elevtype> <Afgangsaarsag> <Dato>2017-03-25</Dato> <Aarsag>750a0</Aarsag> </Afgangsaarsag> <Elevdeltagelse> <UndervisningsenhedRef>218f27d2-bcdb-45ce-8d71- f06ad9d761a0</undervisningsenhedref> <Version>6693</Version> <Fag> <Fagnummer>0</Fagnummer> <Fagniveau>C</Fagniveau> </Fag> <Startdato>2016-04-29</Startdato> <Slutdato>2016-07-11</Slutdato> </Elevdeltagelse> <Skoleophold> <Skoleperiode>0a09</Skoleperiode> <Version>5c0e</Version> <Speciale>a065</Speciale> <Startdato>2017-02-05</Startdato> <Slutdato>2018-01-17</Slutdato> <Undervisningssted>100036</Undervisningssted> <UVMafdeling>100037</UVMafdeling> <TMK>09a18</TMK> <AAEBidragUndervisning> <Taelledato>2018-06-23</Taelledato> <Bidrag>198</Bidrag> <Restbidrag>86</Restbidrag> <PeriodeStart>2018-05-25</PeriodeStart> <PeriodeSlut>2016-07-27</PeriodeSlut> </AAEBidragUndervisning> </Skoleophold> <Skolepraktikophold> <Skoleperiode>914d</Skoleperiode> <Version>0742</Version> <Speciale>fc3a</Speciale> <Startdato>2017-11-02</Startdato> <Slutdato>2016-12-30</Slutdato> <TMK>04ff5</TMK> <AAEBidragSkolepraktik>
Side 8 af 9 <Taelledato>2018-02-15</Taelledato> <UdlosBidrag>N</UdlosBidrag> <Bidrag>176</Bidrag> </AAEBidragSkolepraktik> </Skolepraktikophold> <KvalifikationTilHovedforloeb> <Dato>2017-01-17</Dato> <Uddannelse>fdff</Uddannelse> </KvalifikationTilHovedforloeb> <LaererstyretUndervisning> <Dato>2017-04-10</Dato> <Timer>213</Timer> <Periodetype>ALM</Periodetype> </LaererstyretUndervisning> <Karakter> <Fag> <Fagnummer>0</Fagnummer> <Fagniveau>B</Fagniveau> </Fag> <Vaerdi>IB</Vaerdi> <Skala>7TRIN</Skala> <Type>TER</Type> <Evalueringsform>SS</Evalueringsform> <Dato>2018-11-05</Dato> <Termin>200001</Termin> </Karakter> </Elev> <Optagelsesgrundlag> <Uddannelse>7877</Uddannelse> <Version>0f97</Version> <Studiestart>2017-07-13</Studiestart> <Uddannelsessted>106499</Uddannelsessted> <Undervisningssted>106500</Undervisningssted> <KarakterDansk>-3</KarakterDansk> <KarakterMatematik>-2</KarakterMatematik> <OptagelsesproeveDansk>N</OptagelsesproeveDansk> <OptagelsesproeveMatematik>N</OptagelsesproeveMatematik> <ResultatOptagelsesproeveDansk>IB</ResultatOptagelsesproeveDansk> <ResultatOptagelsesproeveMatematik>BE</ResultatOptagelsesproeveMatematik> <OptagetAndetgrund>J</OptagetAndetgrund> <OptagetSamtale>N</OptagetSamtale> </Optagelsesgrundlag> </Person> <Undervisningsenhed> <UndervisningsenhedsId>218f27d2-bcdb-45ce-8d71- f06ad9d761a0</undervisningsenhedsid> <Undervisningssted>132193</Undervisningssted> <UndervisningsenhedensNavn>6da04006-666b-471b-9dee- 30b5523431d6</UndervisningsenhedensNavn> <Startdato>2017-10-13</Startdato> <Slutdato>2018-09-16</Slutdato> <FagPaaUndervisningsenhed> <Fag> <Fagnummer>0</Fagnummer> <Fagniveau>C</Fagniveau> </Fag> <Lokation>b59636ee-611a-45d3-9fe1-fd7bb67048d2</Lokation> <Startdato>2017-03-04</Startdato> <Slutdato>2016-01-07</Slutdato> </FagPaaUndervisningsenhed> </Undervisningsenhed> </Indberetning>
Side 9 af 9 Bilag 2: Eksempel på SoapUI request <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eud="http://www.stil.dk/euddvh"> <soapenv:header/> <soapenv:body> <eud:validatexmlagainstschema> <eud:xml> [ Indsæt XML som i Bilag 1 ] </eud:xml> </eud:validatexmlagainstschema> </soapenv:body> </soapenv:envelope> Brugernavn og adgangskode sættes i SoapUI via knappen Auth: Bilag 3: Eksempel på SoapUI response <s:envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"> <s:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.stil.dk/euddvh"> <ValidateXmlAgainstSchemaResult xmlns:i="http://www.w3.org/2001/xmlschema-instance"> <ErrorCount>0</ErrorCount> <Message>Data blev modtaget og valideret korrekt.</message> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </s:body> </s:envelope>