God hygiejne er også dit valg.
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> <!--Optional:--> <kar:Username>1</kar:Username> <!--Optional:--> <kar:Password>1</kar:Password> <!--Optional:--> <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>
© Copyright 2024