Vejledning Vedrørende: Skrevet af: Webservice til Optagelse.dk Lars Strange Vester Voldgade 123 1552 København V Tlf.nr.: 35 87 88 89 E-mail: stil@stil.dk www.stil.dk CVR-nr.: 13223459 1 Indledning Dette notat beskriver kort webservicen tilhørende Optagelse.dk. Optagelse.dk webservicen (fremover OptagelseWs) er i et testforløb, hvorfor dette notat forventes at blive opdateret løbende. 03.03.2015 2 Kontakt Webservicen Webservicens servicebeskrivelse findes på adressen https://statistik.uni-c.dk/optagelse/uploadservice.asmx?wsdl Den centrale metode i OptagelseWs er UploadXmlData, der modtager XmlData og validerer disse mod relevante Xml schemaer. OptagelseWs udstiller en række andre metoder, heriblandt en simpel HelloWorld metode, der blot returnerer Hello World. Det anbefales at foretage den første test mod denne metode. Endvidere udstilles metoden HelloWorldWithCredentials, der kan anvendes til at teste webservicen med angivelse af login-oplysninger i SOAP headeren. En egentlig testversion findes under afsnittet Testmiljø i dette dokument.
2 3 Webservicens Get-metoder OptagelseWs udstiller en række Get-metoder, som kort beskrives nedenfor. 3.1 GetXmlSchemaNames() Denne metode returnere en liste med navne på aktuelle XML Schemaer, der kan hentes via GetXmlSchema metoden. 3.2 GetXmlSchema(string schemaname) Denne metode returnerer det navngivne Schema som XML data forventes at overholde, når der overføres data fra de administrative systemer til OptagelseWs. 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 OptagelseWs. GetXmlSchema returnerer schemaet i XML format. 3.3 GetFagkoder() Denne metode returnerer de fagkoder, der er valide i den aktuelle indberetning. Koderne udmeldes af UNI C og opdateres før indberetningen åbnes. GetFagkoder returnerer en liste i XML format i stil med nedenstående (forkortede) svar: <GetFagkoderResult> <FagkodeEntry> <Fag>Dansk</Fag> <FagDisciplin/> <FagKode>110</FagKode> <FagDisciplinKode>000</FagDisciplinKode> <IndberetningKode>110_000</IndberetningKode> </FagkodeEntry> <FagkodeEntry> <Fag>Dansk</Fag> <FagDisciplin>Læsning</FagDisciplin> <FagKode>110</FagKode> <FagDisciplinKode>001</FagDisciplinKode> <IndberetningKode>110_001</IndberetningKode> </FagkodeEntry> </GetFagkoderResult> 4 Webservicens metoder til dataoverførelse 4.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 i XML format med fejlmeddelser. Fejlmeddelserne er henvendt til udviklere og lister dels.net fejlmeddelelsen samt den linje i XML filen, der fejler i forhold til schemaet.
3 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. 4.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"> <soap:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.unic.dk/optagelse"> <ValidateXmlAgainstSchemaResult> <Message>XML blev modtaget og validerer korrekt mod schema definitionen.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:body> </soap:envelope> 4.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"> <soap:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.unic.dk/optagelse"> <ValidateXmlAgainstSchemaResult> <Message>Der er 2 valideringsfejl</message> <ErrorCount>2</ErrorCount> <ValidationErrors> <ValidationError> <ErrorMessage>Linje: 10 udløser fejlen: [Elementet 'urn:optagelse.dk:ftu:1.0.0:value' er ugyldigt - Værdien '13' er ugyldig ifølge sin datatype 'urn:optagelse.dk:ftu:1.0.0:mark7scaletype' - Optællingsbegrænsningen mislykkedes..]</errormessage> </ValidationError> <ValidationError> <ErrorMessage>Linje: 33 udløser fejlen: [Elementet 'urn:optagelse.dk:ftu:1.0.0:yearsfrenchexameducation' er ugyldigt - Værdien '10' er ugyldig ifølge sin datatype 'urn:optagelse.dk:ftu:1.0.0:numberofyearstype' - Begrænsningen MaxInclusive lykkedes ikke..]</errormessage> </ValidationError> </ValidationErrors> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:body> </soap:envelope> 4.2 UploadXmlData(XmlDocument xml) Denne metode er den korrekte måde at overføre XML data til Optagelse.dk indberetningen. UploadXmlData vil først validere XML data mod schemaet og dernæst gemme data til videre databehandling. Hvis der findes fejl ved validering mod XML schemaet vil metoden returnere samme svarmeddelelse som ValidateXmlAgainst- Schema ovenfor.
4 5 Testmiljø OptagelseWs er sat i test i et testmiljø. Servicebeskrivelsen findes på denne adresse; https://statistik-ext.uni-c.dk/optagelse/uploadservice.asmx?wsdl I testmiljøet kan både anvendes overførelse med og uden SSL. Testdata kan overføres via http-protokollen, hvis kald skal analyseres med fx Fiddler (se også afsnittet vedr. udviklingsværktøjer nedenfor). 6 Udviklingsværktøjer OptagelseWs er udviklet i.net 3.5 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 webservice kald og svar. Bemærk: Anvendes webservicekald til https:// er disse kald krypteret. Webservicen kan også kaldes via http:// Bilag 2 og 3 er eksempler på hhv. soap request og tilhørende soap response, når XML data i bilag 1 anvendes.
5 7 Bilag 1: Eksempel på valid XML data <StudentMarksList xmlns="urn:optagelse.dk:ftu:1.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <StudentMarks> <CivilRegistrationNumber>FakeCPR</CivilRegistrationNumber> <MarkSets> <NinthGradeProficiencyMarkSet> </NinthGradeProficiencyMarkSet> <NinthGradeExamMarkSet> </NinthGradeExamMarkSet> <TenthGradeProficiencyMarkSet> </TenthGradeProficiencyMarkSet> <YearsGermanExamEducation>0</YearsGermanExamEducation> <YearsFrenchExamEducation>0</YearsFrenchExamEducation> </MarkSets> </StudentMarks> </StudentMarksList>
6 8 Bilag 2: Eksempel på soap request <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tem="http://www.uni-c.dk/optagelse"> <soapenv:header/> <soapenv:body> <tem:validatexmlagainstschema> <!--Optional:--> <tem:xml> <StudentMarksList xmlns="urn:optagelse.dk:ftu:1.0.0" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance"> <StudentMarks> <CivilRegistrationNumber>FakeCPR</CivilRegistrationNumber> <MarkSets> <NinthGradeProficiencyMarkSet> </NinthGradeProficiencyMarkSet> <NinthGradeExamMarkSet> </NinthGradeExamMarkSet> <TenthGradeProficiencyMarkSet> </TenthGradeProficiencyMarkSet> <YearsGermanExamEducation>0</YearsGermanExamEducation> <YearsFrenchExamEducation>0</YearsFrenchExamEducation> </MarkSets> </StudentMarks> </StudentMarksList> </tem:xml> </tem:validatexmlagainstschema> </soapenv:body> </soapenv:envelope>
7 9 Bilag 3: 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"> <soap:body> <ValidateXmlAgainstSchemaResponse xmlns="http://www.unic.dk/optagelse"> <ValidateXmlAgainstSchemaResult> <Message>XML blev modtaget og validerer korrekt mod schema definitionen.</message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:body> </soap:envelope>