Notat
Vedrørende:
Skrevet af:
Version:
Fordeling:
Grundskolekarakterindberetning 2014: Webservice
hrk, uhl
1.3
Systemleverandører
Dette notat beskriver kort webservicen tilhørende indberetning af karakterer for grundskolen. Webservicen er i et testforløb, hvorfor dette notat
forventes at blive opdateret løbende. Seneste version af notatet kan altid
hentes på
https://statistik.uni-c.dk/GrundskoleKarakter/Dok/UploadService.pdf
I forhold til sidste år er der følgende ændringer i xml-skemaet:
1. På indberetningsniveau er der tilføjet 2 nye oplysninger:
KontaktPerson og KontaktEmail, som dog ikke er obligatoriske, men
bruges til at sende kvittering for modtagelse af indberetning via
webservicen. Hvis disse ikke findes, sendes kvittering til institutionens officielle e-mailadresse (hentet fra institutionsregisteret).
2. På elevniveau for feltet KlasseType er værdien 53 ændret til 50 for
specialskoler for at ensrette det med vores øvrige grundskoleindberetninger.
3. På elevniveau for feltet KlasseBetegnelse er maxlængde ændret fra
10 til 30 tegn.
I forhold til sidste år er følgende ændret i soapheaderen:
1. Feltet InstitutionsNummer er tilføjet, således at headeren indeholder felterne Username, Password og InstitutionsNummer
I forhold til sidste år er følgende ændret i fejlmeddelelser:
2. Selve teksten i ErrorMessage er forlænget og indeholder en opfordring til brugeren om at tjekke sin mail for kvittering med resultatet
af overførslen. Vi vil gerne have og anbefaler, at I videreformidler
disse tekster på jeres webside.
UNI•C København
Vester Voldgade 123
1552 København V
Tlf.nr.: 35 87 88 89
E-mail: [email protected]
www.uni-c.dk
CVR-nr.: 13223459
11.04.2014
2
Kontakt webservicen i testversion
Webservicen er sat i drift i et testmiljø. Servicebeskrivelsen findes på denne
adresse:
http://statistik-ext.uni-c.dk/GsKarWS/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 juni 2014)
Webservicens produktionsversion placeres på
https://statistik.uni-c.dk/GrundskoleKarakterWS/UploadService.asmx
Bemærk at der kræves https.
Credentials
Username/password til testformål kan rekvireres hos UNI•C. Eksisterende
leverandører kan genanvende test username/password fra indberetning til
Optagelse.dk.
Bemærk: Fra dette år skal institutionsnummeret indgå i credentials.
Webservicens HelloWorld metoder
Webservicen udstiller nogle simple metoder til at teste tilgængelighed/adgang til webservicen
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/Karakterer/">
<soap:Header>
<kar:Credentials>

<kar:Username>1</kar:Username>

<kar:Password>1</kar:Password>

<kar:Institutionsnummer>10000</kar:Institutionsnummer>
</kar:Credentials>
</soap:Header>
<soap:Body>
<kar:HelloWorldCredentials/>
</soap:Body>
3
</soap:Envelope>
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.
GetInstAntal(InstitutionsNummer)
Denne metode returnerer antallet af indberettede elever (evt. 0) for den
givne institution. Bemærk at der skal medtages credentials/login i soapheaderen. Ved fejl i credentials eller institutionsnummer returneres en soapfejl/exception.
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 <ValidationError>, 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
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://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
4
<soap:Body>
<ValidateXmlAgainstSchemaResponse xmlns=”http://statistik.unic.dk/Karakterer/">
<ValidateXmlAgainstSchemaResult>
<Message>Skolens indberetning til UNI-C 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 og karaktergennemsnit for de enkelte fag, der
er indberettet oplysninger om.</Message>
<ErrorCount>0</ErrorCount>
<ValidationErrors/>
</ValidateXmlAgainstSchemaResult>
</ValidateXmlAgainstSchemaResponse>
</soap:Body>
</soap:Envelope>
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://statistik.unic.dk/Karakterer/">
<ValidateXmlAgainstSchemaResult>
<Message>Der er 2 fejl i skolens indberetning til UNI-C!
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>2</ErrorCount>
<ValidationErrors>
<ValidationError>
<ErrorMessage>Linje: 2 udløser fejlen: [Elementet
'http://statistik.uni-c.dk/Karakterer/:Version' er ugyldigt - Værdien
'1.1' er ugyldig ifølge sin datatype 'String' - Optællingsbegrænsningen mislykkedes..]</ErrorMessage>
</ValidationError>
<ValidationError>
<ErrorMessage>Linje: 201 udløser fejlen: [Der er en
identisk nøglesekvens '0000000000' for nøglen 'http://statistik.unic.dk/Karakterer/:ElevKey' eller en entydig identitetsbegrænsning.]</ErrorMessage>
</ValidationError>
</ValidationErrors>
</ValidateXmlAgainstSchemaResult>
</ValidateXmlAgainstSchemaResponse>
</soap:Body>
</soap:Envelope>
I eks 1.2 er der udløst to fejlmeddelelser: Første fejl rapporterer om et forkert angivet versionsnummer, anden fejl rapporterer om en dublet i cpr-nr.
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).
5
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://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>
<UploadXmlDataResponse xmlns="http://statistik.unic.dk/Karakterer/">
<UploadXmlDataResult>
<Message>Der er 1 fejl i skolens indberetning til UNI-C!
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>
<ValidationError>
<ErrorMessage>Linje: 12 udløser fejlen: [The
'http://statistik.uni-c.dk/Karakterer/:Klassetype' element is invalid
- The value '53' is invalid according to its datatype
'http://statistik.uni-c.dk/Karakterer/:KlassetypeType' - The Enumeration constraint failed.]</ErrorMessage>
</ValidationError>
</ValidationErrors>
</UploadXmlDataResult>
</UploadXmlDataResponse>
</soap:Body>
</soap:Envelope>
Såfremt data er fejlfrie/accepteres, returneres nedenstående svar (figur
1.4).
1.4 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>
<UploadXmlDataResponse xmlns="http://statistik.unic.dk/Karakterer/">
<UploadXmlDataResult>
<Message>Skolens indberetning til UNI-C 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 og karaktergennemsnit for de enkelte fag, der
er indberettet oplysninger om.</Message>
<ErrorCount>0</ErrorCount>
<ValidationErrors/>
</UploadXmlDataResult>
</UploadXmlDataResponse>
</soap:Body>
</soap:Envelope>
6
Liste med fejlmeddelelser for metoden UploadXmlData:
Element
Valideringsnr. Forklaring
Fejlbesked
Indberetning VAL01
Indberetningsaar skal være
2013/2014
Indberetningsaar er forkert({0})
Bilag
VAL02
Antal bilag må ikke overstige
max antal beskrevet i DataBeskrivelse2014.pdf
Antal bilag stemmer ikke med
klassetrin. Klassetrin({0}), Antal
bilag({1})
Elev
VAL03
Valid datodel i cpr-nummer
Datodel i cpr-nummer forkert.
Cprnr({0})
Elev
VAL04
Specialskoler kan kun indberette på klassetype=50 eller
klassetype=71
Specialskoler kan kun indberette
klassetype=50 eller klassetype=71
(Elev({0}), Trin({1}))
Fag
VAL05
Kombination af Fagid,
ProeveNivaue, BedoemmelsesForm, Klassetrin, og
Proeveform tjekkes mod
prædefineret liste beskrevet i
DataBeskrivelse2014.pdf
Fagkombination ikke tilladt:
trin({0}), fag({1}), Prøveniveau({2}), Bedømmelsesform({3})
Prøveform({4})
Fag
VAL06
Værdien ”Syg” tillades ikke i
denne indberetning (særskilt
indberetningssystem for sygeprøver)
ProeveArt af typen Syg er ikke
tilladt. Sygeprøver indberettes
andetsteds.(Elev({0}), Trin({1}),
Fag({2}))
Fag
VAL07
Der kan ikke anføres en karak- Der kan ikke anføres en karakter
ter såfremt KarakterAarsag
såfremt karakterårsag !=N
!=N
(Elev({0}), Trin({1}), Fag({2}))
Fag
VAL08
Kun privat- og friskoler kan
indberette fagid=181_000 og
181_005 klassetrin=8
Kun privat- og friskoler kan indberette historie på 8 klassetrin
(Elev({0}), Trin({1}), Fag({2}))
Fag
VAL09
Karakterårsag mangler
Karakterårsag mangler (Elev({0}),
Trin({1}), Fag({2}))
Fag
VAL10
Hvis BedoemmelsesForm er
lig ”P” kan KarakterAarsag
ikke være ”E
Kun standpunktkarakterer kan
have årsag=E (Elev({0}), Trin({1}),
Fag({2}))
Fag
VAL11
Hvis BedoemmelsesForm er
lig ”S” kan Karakterårsagen
ikke være ”U”, ”S”, ”D15” eller ”D16”
Karakterårsagen for (Elev({0}),
Trin({1}), Fag({2})) er ikke tilladt
for standpunktskarakterer
Fag
VAL12
Der skal anføres en karakter
såfremt KarakterAarsag =N
Karakter mangler (Elev({0}),
Trin({1}), Fag({2}))
Bilag
VAL13
BilagId tjekkes mod prædefi-
Bilagkombination ikke tilladt:
7
Element
Valideringsnr. Forklaring
neret liste (beskrevet i DataBeskrivelse2014.pdf)
Fejlbesked
trin({0}), bilag({1})
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.
Bilag 1. Eksempel på valid XML data og soap request
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:kar="http://statistik.uni-c.dk/Karakterer/">
<soap:Header>
<kar:Credentials>
<kar:Username>?</kar:Username>
<kar:Password>?</kar:Password>
<kar:Institutionsnummer>?</kar:Institutionsnummer>
</kar:Credentials>
</soap:Header>
<soap:Body>
<kar:UploadXmlData>
<kar:xml>
<ns1:Indberetning xsi:schemaLocation="http://statistik.unic.dk/Karakterer/ IndbKarakter.xsd" xmlns:ns1="http://statistik.unic.dk/Karakterer/" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
<ns1:Version>1.2</ns1:Version>
<ns1:SystemVersion>Test Schema v5</ns1:SystemVersion>
<ns1:JournalNummer>Intern tst</ns1:JournalNummer>
<ns1:IndberetningsAar>2013/2014</ns1:IndberetningsAar>
<ns1:InstitutionsNummer>100000</ns1:InstitutionsNummer>
<ns1:KontaktPerson>Jette Jensen</ns1:KontaktPerson>
<ns1:KontaktEmail>[email protected]</ns1:KontaktEmail>
<ns1:Elev>
<ns1:CprNummer>2412950000</ns1:CprNummer>
<ns1:KlasseBetegnelse>9.a</ns1:KlasseBetegnelse>
<ns1:Klassetype>41</ns1:Klassetype>
<ns1:KlasseTrin>9</ns1:KlasseTrin>
<ns1:KarakterListe>
<ns1:Fag>
<ns1:FagId>134_003</ns1:FagId>
<ns1:ProeveArt>Ord</ns1:ProeveArt>
<ns1:BedoemmelsesForm>S</ns1:BedoemmelsesForm>
<ns1:ProeveNiveau>FSA</ns1:ProeveNiveau>
<ns1:Karakter>4</ns1:Karakter>
<ns1:KarakterAarsag>N</ns1:KarakterAarsag>
<ns1:ProeveForm>B</ns1:ProeveForm>
</ns1:Fag>
</ns1:KarakterListe>
</ns1:Elev>
</ns1:Indberetning>
</kar:xml>
</kar:UploadXmlData>
</soap:Body>
</soap:Envelope>
8
1
Bilag 2: Eksempel på soap response
<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>
<UploadXmlDataResponse xmlns=”http://statistik.unic.dk/Karakterer/">
<UploadXmlDataResult><Message>Skolens indberetning til UNI-C
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 og karaktergennemsnit for de
enkelte fag, der er indberettet oplysninger om.</Message>Message>XML
blev validerer og modtaget korrekt</Message>
<ErrorCount>0</ErrorCount>
<ValidationErrors/>
</UploadXmlDataResult>
</UploadXmlDataResponse>
</soap:Body>
</soap:Envelope>