Notat Vedrørende: Skrevet af: Indberetning af elev-trivselsdata på erhvervsuddannelserne 2016: Webservice uhl Version: 1.2 Fordeling: Systemleverandører Styrelsen for It og Læring Vester Voldgade 123 1552 København V Tlf.nr.: 35 87 88 89 E-mail: stil@stil.dk www.stil.dk CVR-nr.: 13223459 Dette notat beskriver kort webservicen tilhørende indberetning af besvarelser om elevtrivselsundersøgelser på erhvervsskolerne. Seneste version af notatet kan altid hentes på 30.09.2016 https://statistik.uni-c.dk/erhvervelevtrivsel/dok/uploadserviceeud.pdf Kontakt webservicen i testversion Webservicen er sat i drift i et testmiljø. Servicebeskrivelsen findes på denne adresse: http://statistik-ext.uni-c.dk/erhvervelevtrivsel /UploadService.asmx?WSDL Bemærk at der kan anvendes SSL i testfasen, så testdata overføres på en sikker forbindelse, men URL på http-protokollen kan også anvendes, hvis kald skal analyseres med fx Fiddler (se også afsnittet vedr. udviklingsværktøjer i dette notat). Kontakt webservicen i produktionsversion (åbnes først primo oktober 2016) Webservicens produktionsversion placeres på https://statistik.uni-c.dk/erhvervelevtrivsel /UploadService.asmx Bemærk at der kræves https. Credentials Username/password til testformål kan rekvireres hos Styrelsen for It og Læring. Webservicens HelloWorld metoder Webservicen udstiller nogle simple metoder til at teste tilgængelighed/adgang til webservicen
2 HelloWorld() Returnerer HelloWorld, når den kaldes. HelloWorldCredentials() Returnerer Hello [navn] ved kald af servicen med korrekt angivelse af loginoplysninger i soapheaderen. Userid/password kan vælges tilfældigt, idet der ikke valideres mod de officielle userid/passwords. 1.0 Eksempel på kald af HelloWorldCredentials <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:kar="http://statistik.uni-c.dk/erhvervelevtrivsel/"> <soap:header> <eud:credentials> <!--Optional:--> <eud:username>?</eud:username> <!--Optional:--> <eud:password>?</eud:password> <!--Optional:--> <eud:institutionsnummer>10000</eud:institutionsnummer> </eud:credentials> </soap:header> <kar:helloworldcredentials/> Webservicens Get metoder GetXmlSchema() Denne metode returnerer det skema, 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 skema, der udstilles via GetXmlSchema, og validerer xml-data mod skemaet før overførelse til webservicen. GetXmlSchema returnerer skemaet i xml-format. Webservicens metoder til dataoverførsel Der udstilles 2 metoder til at validere og overføre data. ValidateXmlAgainstSchema, der i testregi kan anvendes til at undersøge, at xml-data overholder skemaet, samt UploadXmlData, der anvendes til at overføre data. Begge metoder returnerer xml i form af: <message>, der i tekst angiver antallet af fundne fejl og <ErrorCount>, der angiver antallet af fejl. Listen med de aktuelle fejl er lagt i et <ValidationErrors>, der indeholder en liste af, hvori hver fejlbesked kan hentes fra <ErrorMessage>. Fejlbeskeden vil typisk indeholde en reference i form af et linjenummer eller cprnr, der understøtter fejlrettelse. ValidateXmlAgainstSchema(XmlDocument xml) Denne metode validerer overførte xml-data mod det aktuelle skema. Der returneres enten et OK-svar, hvis skemaet validerer, eller en liste i xmlformat med fejlmeddelelser. Fejlmeddelelserne er henvendt til udviklere og
3 lister dels.net fejlmeddelelsen samt den linje i xml-filen, der fejler i forhold til skemaet. ValidateXmlAgainstSchema har alene til formål at teste xml-data mod det aktuelle skema og er en hjælp til udvikling af xml-eksport fra de administrative systemer. Se Bilag 1 for eksempel på xml-data, der overholder det aktuelle skema og returnerer et OK-svar. 1.1 Eksempel på OK-svar <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <ValidateXmlAgainstSchemaResponse xmlns="http://statistik.unic.dk/eudtrivsel/"> <ValidateXmlAgainstSchemaResult> <Message>XML blev modtaget og validerer korrekt mod schema definitionen.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> 1.2 Eksempel på fejl-svar <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <ValidateXmlAgainstSchemaResponse xmlns="http://statistik.unic.dk/eudtrivsel/"> <ValidateXmlAgainstSchemaResult> <Message>Der er 17 valideringsfejl</message> <ErrorCount>17</ErrorCount> <ValidationErrors> <ErrorMessage>Linje: 17 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm5' element is invalid - The value '5' is invalid according to its datatype 'Int' - The Enumeration <ErrorMessage>Linje: 23 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm7' element is invalid - The value '4' is invalid according to its datatype 'http://statistik.unic.dk/eudtrivsel/:kravtype' - The Enumeration constraint failed.]</errormessage> <ErrorMessage>Linje: 49 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm19b' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:enigtype' - The Enumeration <ErrorMessage>Linje: 63 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm5' element is invalid - The value '5' is invalid according to its datatype 'Int' - The Enumeration <ErrorMessage>Linje: 66 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm6c' element is invalid - The value '5' is invalid according to its datatype 'http://statistik.unic.dk/eudtrivsel/:enigtype' - The Enumeration constraint failed.]</errormessage>
4 <ErrorMessage>Linje: 73 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm11' element is invalid - The value '5' is invalid according to its datatype 'http://statistik.unic.dk/eudtrivsel/:enigtype' - The Enumeration constraint failed.]</errormessage> <ErrorMessage>Linje: 75 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm13a' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:enigtype' - The Enumeration <ErrorMessage>Linje: 76 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm13b' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:enigtype' - The Enumeration <ErrorMessage>Linje: 79 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm14b' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:oftetype' - The Enumeration <ErrorMessage>Linje: 82 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm14e' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:oftetype' - The Enumeration <ErrorMessage>Linje: 83 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm14f' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:oftetype' - The Enumeration <ErrorMessage>Linje: 84 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm14g' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:oftetype' - The Enumeration <ErrorMessage>Linje: 85 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm14h' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:oftetype' - The Enumeration <ErrorMessage>Linje: 89 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm16c' element is invalid - 'http://statistik.uni-c.dk/eudtrivsel/:enigtype' - The Enumeration </ValidationErrors> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> I eks 1.2 er der udløst ni fejlmeddelelser, som alle skyldes, at der er indrapporteret svar på spørgsmål vedr. praktik, selvom eleven har angivet at være på grundforløbet.
5 UploadXmlData(XmlDocument xml) Denne metode skal anvendes til at overføre xml-data til indberetning af afgangsbeviser for grundskolen. Bemærk at der skal medtages credentials/login i soapheaderen. Ved fejl i credentials returneres en soapfejl/exception. UploadXmlData vil først validere xml-data mod skemaet og dernæst foretage en række krydsvalideringer og tabelopslag. Såfremt data accepteres, gemmes disse, og et positivt svar returneres. Hvis der findes fejl ved validering mod xml-skemaet, vil metoden returnere samme svarmeddelelse som ValidateXmlAgainstSchema ovenfor. Hvis der findes fejl under kryds/datavalideringen, vil metoden returnere en eller flere <DataValidationError> noder (jf. figur 1.3). Såfremt xml-data er OK, vil metoden først slette alle tidligere indberettede data fra institutionen, og dernæst overføres de nye xml-data. 1.1.1 1.3 Eksempel på fejl-svar <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <UploadXmlDataResponse xmlns="http://statistik.unic.dk/eudtrivsel/"> <UploadXmlDataResult> <Message>Der er fejl i skolens indberetning til STIL! Data er ikke modtaget. Skolens kontaktperson vil om få minutter modtage en e-mailkvittering med oversigt over fejlene. Ret venligst fejlene i det administrative system og overfør herefter data igen.</message> <ErrorCount>1</ErrorCount> <ValidationErrors> <ExtendedValidationError> <ErrorMessage>Linje: 40 udløser fejlen: [The 'http://statistik.uni-c.dk/eudtrivsel/:spm15a' element is invalid - The value '6' is invalid according to its datatype 'Int' - The Enumeration <ErrorType>XmlValidationError</ErrorType> </ExtendedValidationError> </ValidationErrors> </UploadXmlDataResult> </UploadXmlDataResponse> Såfremt data er fejlfrie/accepteres, returneres nedenstående svar (figur 1.4). 1.4 Eksempel på OK-svar <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <UploadXmlDataResponse xmlns="http://statistik.unic.dk/eudtrivsel/"> <UploadXmlDataResult> <Message>Skolens indberetning til STIL er gået godt! Data er modtaget og vil indgå i den samlede statistik. Kontaktpersonen vil - såfremt email-adresse er angivet - om få minutter modtage en emailkvittering med oversigter over, hvor mange elever der er indberettet oplysninger om.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </UploadXmlDataResult> </UploadXmlDataResponse>
6 Liste med fejlmeddelelser for metoden UploadXmlData Fejlmeddelelse Ukendt institutionsnummer Der er midlertidigt lukket for indberetning for denne inst. Indberetningsaar er forkert Cpr-nummer må kun bestå af tal og datodelen skal være en eksisterende dato. Der må ikke være svar på Spm19A vedr. skolepraktik, når svaret på spm15 er praktikplads/uddannelsesaftale Der må ikke være svar på Spm16A vedr. praktik, når svaret på spm15 er skolepraktik Der må ikke være svar på Spm16A vedr. praktik, når svaret på spm15 er ingen af delene Forklaring Den pågældende institution findes ikke i listen med institutioner, der skal indberette. Institutionen kan kontakte Styrelsen for It og Læring for at blive tilføjet. Der er lukket for indberetning for denne institution. Kontakt Styrelsen for It og Læring for yderligere information. Der er fundet et forkert indberetningsår i XML. Det korrekte er 2016. Der er fundet en ugyldig dato eller bogstaver i cpr-nr. Note: der udføres ikke modulus-11 tjek. Når der i spm. 15 er svaret 1 (Praktikplads/uddannelsesaftale), må der ikke være svar på spørgsmål vedr. skolepraktik (Spm19 Spm21) * Når der i spm. 15 er svaret 2 (Skolepraktik), må der ikke være svar på spørgsmål vedr. praktikplads/uddannelsesaftale (Spm16 Spm18) * Når der i spm15 er svaret 3 ( Ingen af delene (dvs. du går på byggemontagetekniker, sundhedsservicesekretær eller webintegrator uddannelsen) ), må der ikke være svar på resten af spørgsmålene. Versionsnummer er forkert Den korrekte er 1.1. *) note: Se flow i spørgeskemaet i vejledning til indberetning af data: https://statistik.uni-c.dk/erhvervelevtrivsel/dok/eudelevtrivseldata.pdf
7 Udviklingsværktøjer IndbKarakterWs er udviklet i.net 4.0 frameworket og kan umiddelbart tilgås 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.fiddler2.com/fiddler2/) analyserer webservicekald og svar. Bemærk: Anvendes webservicekald til https:// er disse kald krypteret. Webservicen kan også kaldes via http:// Bilag 1 og 2 er eksempler på hhv. soap request og tilhørende soap response.
8 Bilag 1. Eksempel på valid XML data og soap request <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:eud="http://statistik.uni-c.dk/eudtrivsel/"> <soapenv:header> <eud:credentials> <!--Optional:--> <eud:username>uhl</eud:username> <eud:password>test</eud:password> <eud:institutionsnummer>100000</eud:institutionsnummer> </eud:credentials> </soapenv:header> <soapenv:body> <eud:uploadxmldata> <!--Optional:--> <eud:xml> <ns1:indberetning xsi:schemalocation="http://statistik.unic.dk/eudtrivsel/ ErhvervElevTrivsel.xsd" xmlns:ns1="http://statistik.uni-c.dk/eudtrivsel/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <ns1:version>1.1</ns1:version> <ns1:systemversion>1.1</ns1:systemversion> <ns1:journalnummer>10-11-2015</ns1:journalnummer> <ns1:indberetningsaar>2015</ns1:indberetningsaar> <ns1:institutionsnummer>100000</ns1:institutionsnummer> <ns1:kontaktperson>ulla Høeg Larsen</ns1:KontaktPerson> <ns1:kontaktemail>uhl@stil.dk</ns1:kontaktemail> <ns1:elevliste> <ns1:elev> <ns1:cprnummer>2902001111</ns1:cprnummer> <ns1:spm1>2</ns1:spm1> <ns1:spm2>12</ns1:spm2> <ns1:spm3>2</ns1:spm3> <ns1:spm5a>5</ns1:spm5a> <ns1:spm5b>2</ns1:spm5b> <ns1:spm5c>5</ns1:spm5c> <ns1:spm6a>4</ns1:spm6a> <ns1:spm6b>3</ns1:spm6b> <ns1:exspm6a>3</ns1:exspm6a> <ns1:exspm6b>3</ns1:exspm6b> <ns1:exspm6c>3</ns1:exspm6c> <ns1:exspm6d>3</ns1:exspm6d> <ns1:exspm6e>1</ns1:exspm6e> <ns1:exspm6f>3</ns1:exspm6f> <ns1:spm7>3</ns1:spm7> <ns1:spm8>8</ns1:spm8> <ns1:spm9>5</ns1:spm9> <ns1:spm10>8</ns1:spm10> <ns1:spm11>2</ns1:spm11> <ns1:spm12>10</ns1:spm12> <ns1:spm13a>3</ns1:spm13a> <ns1:spm13b>4</ns1:spm13b> <ns1:spm13c>1</ns1:spm13c> <ns1:spm13d>4</ns1:spm13d> <ns1:spm13e>4</ns1:spm13e> <ns1:spm14a>3</ns1:spm14a> <ns1:spm14b>3</ns1:spm14b> <ns1:spm14c>2</ns1:spm14c> <ns1:spm14d>2</ns1:spm14d> <ns1:spm14e>1</ns1:spm14e> <ns1:spm14f>3</ns1:spm14f> <ns1:spm14g>2</ns1:spm14g> <ns1:spm14h>1</ns1:spm14h> <ns1:spm15>2</ns1:spm15> <ns1:spm16a xsi:nil="true"/> <ns1:spm16b xsi:nil="true"/> <ns1:spm16c xsi:nil="true"/> <ns1:spm17a xsi:nil="true"/> <ns1:spm17b xsi:nil="true"/> <ns1:spm17c xsi:nil="true"/> <ns1:spm18 xsi:nil="true"/> <ns1:spm19a>2</ns1:spm19a> <ns1:spm19b>5</ns1:spm19b> <ns1:spm19c>1</ns1:spm19c> <ns1:spm20a>2</ns1:spm20a> <ns1:spm20b>3</ns1:spm20b>
9 <ns1:spm20c>2</ns1:spm20c> <ns1:spm21>1</ns1:spm21> </ns1:elev> <ns1:elev> <ns1:cprnummer>0101721111</ns1:cprnummer> <ns1:spm1>2</ns1:spm1> <ns1:spm2>12</ns1:spm2> <ns1:spm3>2</ns1:spm3> <ns1:spm5a>5</ns1:spm5a> <ns1:spm5b>2</ns1:spm5b> <ns1:spm5c>5</ns1:spm5c> <ns1:spm6a>4</ns1:spm6a> <ns1:spm6b>3</ns1:spm6b> <ns1:exspm6a>3</ns1:exspm6a> <ns1:exspm6b>3</ns1:exspm6b> <ns1:exspm6c>3</ns1:exspm6c> <ns1:exspm6d>3</ns1:exspm6d> <ns1:exspm6e>1</ns1:exspm6e> <ns1:exspm6f>3</ns1:exspm6f> <ns1:spm7>2</ns1:spm7> <ns1:spm8>8</ns1:spm8> <ns1:spm9>8</ns1:spm9> <ns1:spm10>2</ns1:spm10> <ns1:spm11>5</ns1:spm11> <ns1:spm12>8</ns1:spm12> <ns1:spm13a>5</ns1:spm13a> <ns1:spm13b>5</ns1:spm13b> <ns1:spm13c>1</ns1:spm13c> <ns1:spm13d>4</ns1:spm13d> <ns1:spm13e>4</ns1:spm13e> <ns1:spm14a>1</ns1:spm14a> <ns1:spm14b>3</ns1:spm14b> <ns1:spm14c>4</ns1:spm14c> <ns1:spm14d>2</ns1:spm14d> <ns1:spm14e>2</ns1:spm14e> <ns1:spm14f>1</ns1:spm14f> <ns1:spm14g>2</ns1:spm14g> <ns1:spm14h>3</ns1:spm14h> <ns1:spm15>1</ns1:spm15> <ns1:spm16a>1</ns1:spm16a> <ns1:spm16b>2</ns1:spm16b> <ns1:spm16c>5</ns1:spm16c> <ns1:spm17a>4</ns1:spm17a> <ns1:spm17b>3</ns1:spm17b> <ns1:spm17c>1</ns1:spm17c> <ns1:spm18>2</ns1:spm18> <ns1:spm19a xsi:nil="true"/> <ns1:spm19b xsi:nil="true"/> <ns1:spm19c xsi:nil="true"/> <ns1:spm20a xsi:nil="true"/> <ns1:spm20b xsi:nil="true"/> <ns1:spm20c xsi:nil="true"/> <ns1:spm21 xsi:nil="true"/> </ns1:elev> </ns1:elevliste> </ns1:indberetning> </eud:xml> </eud:uploadxmldata> </soapenv:body> </soapenv:envelope> Bilag 2. Eksempel på soap response <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <UploadXmlDataResponse xmlns="http://statistik.unic.dk/eudtrivsel/"> <UploadXmlDataResult> <Message>Skolens indberetning til STIL er gået godt! Data er modtaget og vil indgå i den samlede statistik. Skolens kontaktperson vil om få minutter modtage en e-mailkvittering med oversigter over, hvor mange elever der er indberettet oplysninger om.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </UploadXmlDataResult>
</UploadXmlDataResponse> 1