Notat Vedrørende: Indberetning af elevdata september 2015: Web-service Skrevet af: Version: 1.2 Fordeling: Henrik Rosendahl-Kaa Vester Voldgade 123 1552 København V Tlf.nr.: 35 87 88 89 E-mail: stil@stil.dk www.stil.dk CVR-nr.: 13223459 01.09.2015 Dette notat beskriver baggrund, data og webservice vedrørende Indberetning af Elevdata for Grundskolen. Webservicen (fremover ElevDataWs) bliver taget i anvendelse første gang til indsamling i september 2015 og forventes genanvendt fremover. Ændringer september 2015 Ændringer i teksten markeret med rødt. - Indberetningsaar er sat til 201509 - Adressen til testmiljøet er ændret: Den nye adresse er https://statistik-ext.uni-c.dk/elevdataws/uploadservice.asmx og der skal anvendes https Ændringer september 2014 Ændringer i version 1.2 - i klassetypekode tillades også koderne 71,72,91 og 92 - ekstra valideringer er implementeret, se afsnit 5.2 udgår i år - I afsnit 5.1.5 er det præciseret hvilke felter, der tillades at indeholde en tom tekststreng - tilpasset pdf-kvittering Ændringer i version 1.1 - der er tilføjet et nyt felt indberetningsaar under indberetningselementet - for en del tekstfelter tillades det nu, at der indberettes en tom tekststreng. De berørte felter kan udledes af kolonne feltlængde i feltbeskrivelse - for ElevCPRidentifikator er den numeriske validering fjernet, således at midlertidige cprnr med bogstaver i løbenummerdelen nu tillades. Fx 2412030HA1 - felttypen for klassetypekode (kan indeholde værdierne 40,41,50 og 55) er ændret fra string til int - for ElevNiveauKode og KlassetrinKode tillades nu heltal mellem 0-12 - Adressen til testmiljøet er ændret: Den nye adresse er https://statistik-ext.unic.dk/ext15/uploadservice.asmx, og der skal anvendes https
2 1 Hvilke skoler skal indberette? Alle folkeskoler, friskoler og private grundskoler, ungdomsskoler med heltidsundervisning, efterskoler, specialskoler for børn, samt dagbehandlingstilbud og anbringelsessteder skal indberette oplysninger om deres elever. 2 Hvordan foregår indberetningen? Indberetningen gennemføres som en system-til-system overførsel, hvor data fra skolens administrative system sendes til en web-service hos STIL, Styrelsen for It og Læring. Web-servicen beskrives nedenfor i afsnit 5. 3 Hvornår finder indberetningen sted? Indberetningen finder sted i september måned 2015. De endelige datoer er endnu ikke fastsat. 4 Hvad skal indberettes? Der skal indberettes en række oplysninger om alle elever, der har været indskrevet på skolen i perioden 6. september 2014 5. september 2015. Tællingsperioden dækker over to skoleår, og skal derfor afspejle elevernes niveau/klassetrin før og efter sommerferien 2015. Alle elever, der har været indskrevet på skolen i tællingsperioden, skal medtages i indberetningen, uanset hvor lang tid eleven har været indskrevet.
3 For hver elev skal der indberettes følgende oplysninger: Elevens cpr-nummer Elevens efternavn Elevens fornavn Dato for tilgang til givet klassetrin Dato for afgang fra et givet klassetrin Afgangsart Er eleven modtagelsesklasse-elev (ja/nej) Modtager eleven undervisning i dansk som andetsprog (ja/nej) Elevens niveau/klassetrin Klassens klassebetegnelse Klassetype I afsnit 5 ses en nærmere beskrivelse af de oplysninger, der skal indberettes.
4 Nedenstående Figur 1 viser en række eksempler på elevforløb på en given skole. Elev A starter på 0. niveau/klassetrin i juli 2014 og afslutter 0. niveau/klassetrin i juni 2015. Herefter påbegynder vedkommende 1. niveau/klassetrin i juli 2015. I data vil Elev A således optræde med to poster en for hvert niveau/klassetrin. Elev B er en ny elev, der starter på 0. niveau/klassetrin juli 2015. Elev C er en elev, der forlader skolen efter 9. niveau/klassetrin. Elev D er omgænger og starter juli 2015 igen på 0. niveau/klassetrin. Elev E er ny elev på skolen december 2014 på 4. niveau/klassetrin. Vedkommende starter juli 2015 på 5. niveau/klassetrin. Elev F forlod skolen marts 2015, men kom igen maj 2015. Vedkommende starter juli 2015 på 5. niveau/klassetrin. Figur 1 Illustration af elevforløb - eksempler
Tabellen nedenfor viser, hvordan de viste elevforløb i Figur 1 skal indberettes mht. tilgangs- og afgangsdatoer. Bemærk at vi i eksemplet opererer med, at en almindelig elev går ud af sit gamle niveau/klassetrin pr. 30. juni, og går ind på nyt niveau/klassetrin pr. 1. juli. Tabel 2 Elevforløbenes tilgangs- og afgangsdatoer Tilgangsdato Afgangsdato Niveau/klassetrin Elev A 01072014 30062015 0 Elev A 01072015 1 Elev B 01072015 0 Elev C 01072014 30062015 9 Elev D 01072014 0 Elev E 16012014 30062015 4 Elev E 01072015 5 Elev F 01072014 05032015 4 Elev F 27052014 30062014 4 Elev F 01072014 5 5 5 Feltbeskrivelse for webservice Der skal indberettes data på to niveauer Indberetningsoplysninger her afgives oplysninger om den indberettende institution dvs. institutionsnummer, samt informationer af mere teknisk art, såsom xml-skema version og indberetningskilde (leverandør). Derudover kan angives en kontaktperson, som vil få tilsendt en kvittering for indberetningen. Uddannelsesforløbsstruktur dette niveau omhandler oplysninger på elevniveau, og kan anføres flere gange pr. elev. En elevs tilgang/afgang fra en institution eller skift af niveau udløser en post af denne type. Oplysninger indeholder bl.a. cpr-nr., navn, klassetype, niveau/klassetrin og tilgangs-/afgangsdatoer. Indberetningen består altså af ét element vedrørende indberetningsoplysninger og et eller flere elementer vedrørende uddannelsesforløbsstruktur.
6 5.1.1 Indberetningsoplysninger Der kan kun forekomme én post på dette niveau i indberetningen. Feltnavn Type Felt- Længde XML Nillable/ udeladt Version string 1.0 IndberetningsAar int 201509 Validering i Schema InstitutionsNummer Int Min:100000 Max:999999 SystemVersion string 0-255 Ja Leverandørs interne versionsnr. KontaktPerson* string 0-255 Ja Kontaktperson på institution KontaktEmail* string 0-255 Ja E-mailadresse på kontaktperson *Hvis skolen ikke angiver en kontaktperson eller kontaktemail, vil kvitteringen blive sendt til skolens officielle e-mailadresse.
7 5.1.2 Uddannelsesforloebstruktur Oplysninger på dette niveau kan afgives flere gange pr. elev pr. indberetning. Felt Type Feltlængde XML Nillable/ udeladt Beskrivelse / Validering i Schema ElevEfternavnTekst string 0-24 Elevens efternavn ElevFornavneTekst string 0-24 Elevens fornavn(e) ElevCPRidentifikator string 10 Cpr-nummer, inkl. erstatnings-cprnumre ElevNiveau- TilgangsDato date ElevNiveauKode int Angivelse af elevens niveau/klassetrin. Min:0 Max:12 Dato for begyndelse af niveau/klassetrin ElevNiveau- AfgangsDato ElevAfgangsartKode int Ja Type af afgang fra det pågældende niveau/klassetrin. 1:Fuldført niveau med prøve 2:Fuldført niveau uden prøve 4: Afbrudt niveau i løbet af skoleåret date Ja Dato for afgang fra pågældende niveau/klassetrin. Udfyldes kun hvis eleven har afsluttet niveauet/ klassetrinnet Modtagelsesklasseelev- Indikator DanskSomAndetSprog- Indikator int int KlasseBetegnelseTekst string 0-30 Klassens navn Elev er modtagelsesklasseelev 0: Nej 1: Ja Eleven modtager undervisning i dansk som andetsprog 0:Nej 1: Ja KlassetypeKode int Klassetype 40: Normalklasse, fuldt årgangsdelt 41: Normalklasse, ikke fuldt årgangsdelt 50: Specialklasse 55: Klasse for ældre tosprogede elever 71: Privatister/enkeltfagskursister 72: Privatister 91: P20.2 klasse for førskolebørn 92: P20.3 og P20.5 klasse for førsko-
8 lebørn KlassetrinKode int Ja Angivelse af klassens niveau/klassetrin Min:0 Max:12 5.1.3 Xml-schema Det aktuelle schema kan hentes via web-servicens getxmlschema metode
5.1.4 Eksempel på valide xml-data Eksempel med kun én elev <?xml version="1.0" encoding="utf-8"?> <Indberetning xmlns="http://statistik.uni-c.dk/elevdata" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <Version>1.0</Version> <IndberetningsAar>201509</indberetningsAar> <InstitutionsNummer>100000</InstitutionsNummer> <SystemVersion>STIL TestData 1.21</SystemVersion> <KontaktPerson>Henrik</KontaktPerson> <KontaktEmail>henrik.rosendahl-kaa.uni-c.dk</KontaktEmail> <UddannelsesForloebStrukturSamling> <UddannelsesForloebStruktur> <ElevCPRidentifikator>2412000000</ElevCPRidentifikator> <ElevEfternavnTekst>Henriksen</ElevEfternavnTekst> <ElevFornavneTekst>Henrik</ElevFornavneTekst> <ElevNiveauTilgangsDato>2014-10-13</ElevNiveauTilgangsDato> <ElevNiveauKode>4</ElevNiveauKode> <ElevNiveauAfgangsDato>2015-07-31</ElevNiveauAfgangsDato> <ElevAfgangsartKode>4</ElevAfgangsartKode> <ModtagelsesklasseelevIndikator>1</ModtagelsesklasseelevIndikator> <DanskSomAndetSprogIndikator>0</DanskSomAndetSprogIndikator> <KlasseBetegnelseTekst>4b</KlasseBetegnelseTekst> <KlasseTypeKode>40</KlasseTypeKode> <KlasseTrinKode>4</KlasseTrinKode> </UddannelsesForloebStruktur> <UddannelsesForloebStruktur> <ElevCPRidentifikator>2412000000</ElevCPRidentifikator> <ElevEfternavnTekst>Henriksen</ElevEfternavnTekst> <ElevFornavneTekst>Henrik</ElevFornavneTekst> <ElevNiveauTilgangsDato>2015-08-01</ElevNiveauTilgangsDato> <ElevNiveauKode>5</ElevNiveauKode> <ElevNiveauAfgangsDato xsi:nil="true"/> <ElevAfgangsartKode xsi:nil="true"/> <ModtagelsesklasseelevIndikator>1</ModtagelsesklasseelevIndikator> <DanskSomAndetSprogIndikator>0</DanskSomAndetSprogIndikator> <KlasseBetegnelseTekst>5b</KlasseBetegnelseTekst> <KlasseTypeKode>40</KlasseTypeKode> <KlasseTrinKode>5</KlasseTrinKode> </UddannelsesForloebStruktur> </UddannelsesForloebStrukturSamling> </Indberetning> 5.1.5 Tomme elementer Hvis værdien af et felt er tomt, bør der i xml data anvendes attributten xsi:nil='true'. Dog tillades i 2014 indberetningen at det givne element helt udelades. Således kan der ved et tomt KlasseTrinKode vælges følgende to former <UddannelsesForloebStruktur> <ElevCPRidentifikator>1234567890</ElevCPRidentifikator> <ElevEfternavnTekst>Sørensen</ElevEfternavnTekst> <ElevFornavneTekst>Emil</ElevFornavneTekst> <ElevNiveauTilgangsDato>2012-08-01</ElevNiveauTilgangsDato> <ElevNiveauKode>01</ElevNiveauKode> <ElevNiveauAfgangsDato>2013-06-28</ElevNiveauAfgangsDato> <ElevAfgangsartKode>2</ElevAfgangsartKode> <ModtagelsesklasseelevIndikator>0</ModtagelsesklasseelevIndikator> <DanskSomAndetSprogIndikator>0</DanskSomAndetSprogIndikator>
10 <KlasseBetegnelseTekst>1.klasse</KlasseBetegnelseTekst> <KlasseTypeKode>40</KlasseTypeKode> <KlasseTrinKode xsi:nil='true'/> </UddannelsesForloebStruktur> Eller UddannelsesForloebStruktur> <ElevCPRidentifikator>1234567890</ElevCPRidentifikator> <ElevEfternavnTekst>Sørensen</ElevEfternavnTekst> <ElevFornavneTekst>Emil</ElevFornavneTekst> <ElevNiveauTilgangsDato>2012-08-01</ElevNiveauTilgangsDato> <ElevNiveauKode>01</ElevNiveauKode> <ElevNiveauAfgangsDato>2013-06-28</ElevNiveauAfgangsDato> <ElevAfgangsartKode>2</ElevAfgangsartKode> <ModtagelsesklasseelevIndikator>0</ModtagelsesklasseelevIndikator> <DanskSomAndetSprogIndikator>0</DanskSomAndetSprogIndikator> <KlasseBetegnelseTekst>1.klasse</KlasseBetegnelseTekst> <KlasseTypeKode>40</KlasseTypeKode> </UddannelsesForloebStruktur> I 2015 tillades tomme tekststrenge for ElevEfternavnTekst, ElevFornavneTekst og KlasseBetegnelseTekst. Fx <ElevEfternavnTekst></ElevEfternavnTekst> for ElevEfternavnTekst 5.2 Ekstra valideringer ud over xml-schema 6 Kontakt webservicen 6.1 Produktionsversion Produktionsversionen af webservicens servicebeskrivelse findes på adressen: https://statistik.uni-c.dk/elevdataws/uploadservice.asmx Produktionsversionen bliver først gjort tilgængelig primo september 2015 Bemærk: I produktionsversionen er det kun muligt at anvende sikker overførelse (SSL). Til testformål kan testversionen anvendes, også uden SSL. Se afsnittet Testmiljø i dette notat for hvordan testversionen kontaktes. 6.2 Testmiljø ElevDataWs testmiljø kan findes på adressen https://statistik-ext.uni-c.dk/elevdataws/uploadservice.asmx Testdata kan overføres via http-protokollen, hvis kald skal analyseres med fx Fiddler (se også afsnittet vedr. udviklingsværktøjer nedenfor). I drift vil https:// være krævet ved overførelser. ElevDataWs udstiller en række metoder, heriblandt en simpel Hello- World metode, der blot returnerer Hello World. Den første test kan med fordel køres mod denne metode.
11 Note: Der udsendes også e-mailkvittering i testversion, så anfør venligst egnede KontaktPerson og KontaktEmail data i xml. 6.3 Credentials Nogle metoder kræver at soap headeren er beriget med valide Credentials, som bla. indeholder brugernavn, adgangskode. Der udstedes et sæt credentials pr. leverandør, og disse kan genanvendes på tværs af statistikrelaterede indberetninger til STIL. 7 Webservicens Get-metoder ElevDataWs udstiller en enkelt Get-metode til at returnere det XML Schema, som XML data forventes at overholde, når der overføres data fra de administrative systemer. 7.1.1 GetXmlSchema() Det anbefales, at leverandøren altid sikrer sig, at XML data overholder de schemaer, der udstilles via GetXmlSchema og validerer XML data mod schemaet før overførelse til ElevDataWs. GetXmlSchema returnerer schemaet i XML format. 7.2 Webservicens metoder til dataoverførelse 7.2.1 ValidateXmlAgainstSchema(XmlDocument xml) Denne metode validerer overførte XML data mod de aktuelle schemaer. Der returneres enten et OK-svar, hvis schemaet validerer eller en liste med fejlmeddelelser. Fejlmeddelelserne er henvendt til udviklere og lister dels.net fejlmeddelelsen samt den linje i XML filen, 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.
12 7.2.1.1 Eksempel på OK-svar <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <soap:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.unic.dk/>elevdata"> <ValidateXmlAgainstSchemaResult> <Message>XML blev modtaget og validerer korrekt mod schema definitionen.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:body> </soap:envelope> 7.2.1.2 Eksempel på Fejl-svar <soap:envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <soap:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.unic.dk/elevdata"> <ValidateXmlAgainstSchemaResult> <Message>Der er 2 valideringsfejl</message> <ErrorCount>2</ErrorCount> <ValidationErrors> <ValidationError> <ErrorMessage>Linje: 7 udløser fejlen: [The 'http://statistik.uni-c.dk/elevdata/:klasstype' element is invalid - The value 'BB' is invalid according to its datatype Int - The Enumeration constraint failed.]</errormessage> </ValidationError> <ValidationError> <ErrorMessage>Linje: 37 udløser fejlen: [The 'http://statistik.uni-c.dk/elevdata/:klassetrin' element is invalid - The value 'B' is invalid according to its datatype 'Int' - The string 'B' is not a valid Int32 value.]</errormessage> </ValidationError> </ValidationErrors> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:body> </soap:envelope>
13 7.2.2 UploadXmldata Denne metode er den korrekte måde at overføre XML data til ElevData, når data skal gemmes. Bemærk: Metoden UploadXmlData kræver, at soap headeren er beriget med valide Credentials, som indeholder brugernavn, adgangskode og institutionsnummer. Der udstedes et sæt credentials pr. leverandør, og disse kan genanvendes på tværs af statistikrelaterede indberetninger. UploadXmlData vil først validere XML mod schemaet og dernæst foretage en krydsvalidering mellem felter. Hvis begge valideringer går godt, bliver data overført til databasen, og et OK-svar returneres. Hvis der findes fejl ved validering mod XML schemaet, vil metoden returnere samme svarmeddelelse som ved ValidateXmlAgainst- Schema ovenfor. Ved datavalideringsfejl vil CPR-nummeret stå angivet som en node under ErrorMessage-noden, hvor det er muligt. Dermed får slutbrugeren lettere ved at fremsøge eleven og rette i det administrative system, såfremt det administrative system formidler denne information til brugeren. Det anbefales at oplysninger i noderne ErrorMessage og ErrorCprNumber som minimum formidles til slutbrugeren, hvis der er fejl i de overførte data. Ved hvert upload/uploadforsøg sendes der en e-mailkvittering af resultatet af indberetningen til kontaktpersonen. 7.3 Udviklingsværktøjer ElevDataWS er udviklet i.net 4.5 Framework 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 webservice kald og svar. Bemærk: Anvendes webservicekald til https:// er disse kald krypteret. Webservicen kan også kaldes via http:// i testmiljøet.