Dokumentoplysninger
Ændringshistorik
Indhold
Indledning
Dette dokument beskriver kort webservicen tilhørende indberetning af kursistaktiviteter til DVH (herefter Webservicen). Webservicen er udviklet og driftes af Styrelsen for It og Læring. Indholdet er beskrevet i dokumentet "Indberetningsstruktur for kursistindberetning til DVH".
Ændringer i forhold til seneste foregående version af Webservicen fremgår af ændringshistorikoversigten i starten af dokumentet.
Kontakt webservicen
Testversion
Webservicen er sat i drift i et testmiljø. Servicebeskrivelsen findes på denne adresse: http://test-data.stil.dk/VUCIndberetning/UploadService.asmx?WSDL.
Webservicen udstiller blandt andet en simpel HelloWorld-metode, der blot returnerer "Hello World". Det anbefales at foretage den første test mod denne metode.
Direkte kald til webservicen er beskyttet af brugernavn og adgangskode. Se Bilag 2 for en guide til at sætte brugernavn og adgangskode op i SoapUI.
Det anbefales, at nye brugere tester via Integrationsplatformens testmiljø, hvor servicebeskrivelsen findes på adressen: https://et.integrationsplatformen.dk/services/DVH/Kursist/v1.0/?wsdl.
Se afsnit 2.2 nedenfor, hvor Integrationsplatformen er nærmere beskrevet.
Produktionsversion
Webservicen kaldes via STIL's integrationsplatform (Integrationsplatformen).
Integrationsplatform understøtter udveksling af data mellem STIL's centrale systemer og eksterne systemer. Integrationsplatformen anvendes af uddannelsesinstitutioner, myndigheder og organisationer på førskole-, grundskole-, ungdomsuddannelses-, voksen- og efteruddannelsesområdet.
Platformen tilbyder ensartede webservices for indberetning til og hentning af data fra STIL's centrale systemer inkl. autentificering, autorisering og logning af hændelser i forbindelse med dataudvekslingen. Integrationsplatformen er en ren infrastrukturkomponent og har ingen brugergrænseflade, ligesom den ikke opbevarer data. Platformen understøtter, at systemleverandører, blandt andet leverandører af studieadministrative systemer på de ovennævnte uddannelsesområder, kan udveksle data med STIL's systemer på en institutions vegne på en ensartet, transparent og sikker måde.
Yderligere oplysninger om tilslutning og tekniske detaljer kan findes på STIL's supportsite via https://viden.stil.dk/display/OFFintegrationsplatformen.
Servicebeskrivelsen findes på: https://integrationsplatformen.dk/services/DVH/Kursist/v1.0?wsdl.
Webservicens HelloWorld-metoder
Webservicen udstiller nogle simple metoder til at teste tilgængelighed/adgang til webservicen.
HelloWorld()
Metoden returnerer "HelloWorld", når den kaldes.
HelloWorldCredentials()
Metoden 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 userids/passwords.
Eksempel på kald af HelloWorldCredentials
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:kar="http://statistik.uni-c.dk/VUCIndberetning/"> <soap:Header> <vuc:Credentials> <!-Optional:-> <vuc:Username>?</vuc:Username> <!-Optional:-> <vuc:Password>?</vuc:Password> <!-Optional:-> <vuc:Institutionsnummer>10000</vuc:Institutionsnummer> </vuc:Credentials> </soap:Header> <soap:Body> <kar:HelloWorldCredentials/> </soap:Body> </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 studieadministrative 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 <ValidationError>, hvori hver fejlbesked kan hentes fra <ErrorMessage>. Fejlbeskeden vil typisk indeholde en reference i form af et linjenummer eller cpr-nr, 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 XML-format med fejlmeddelelser. Fejlmeddelelserne er henvendt til udviklere og lister dels .Net-fejlmeddelelsen, dels 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 studieadministrative systemer.
Se Bilag 1 for eksempel på XML-data, der overholder det aktuelle skema og returnerer et OK-svar.
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://statistik.uni-c.dk/VUCenkeltfag/"> <ValidateXmlAgainstSchemaResult> <Message>XML blev modtaget og validerer korrekt mod schema definitionen.</Message> <ErrorCount>0</ErrorCount> <ValidationErrors/> </ValidateXmlAgainstSchemaResult> </ValidateXmlAgainstSchemaResponse> </soap:Body> </soap:Envelope>
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://statistik.uni-c.dk/VUCenkeltfag/">
<ValidateXmlAgainstSchemaResult>
<Message>Der er 1 valideringsfejl</Message>
<ErrorCount>1</ErrorCount>
<ValidationErrors>
<ValidationError>
<ErrorMessage>Linje: 15 udløser fejlen: \[The 'http://statistik.uni-c.dk/VUCenkeltfag/:CoesaFormaal' element is invalid - The value 'a000' is invalid according to its datatype 'Integer' - The Pattern constraint failed.\]</ErrorMessage>
</ValidationError>
</ValidationErrors>
</ValidateXmlAgainstSchemaResult>
</ValidateXmlAgainstSchemaResponse>
</soap:Body>
</soap:Envelope>
\\ I eksemplet på fejlsvar er der udløst en fejlmeddelelse, som skyldes, at der er indrapporteret et forkert/ukendt CØSA-formål.
UploadXmlData(XmlDocument xml)
Denne metode skal anvendes til at overføre XML-data til indberetning af kursist-aktiviteter. 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 (jvf. afsnit 4.4.1).
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.
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>
<UploadXmlDataResponse xmlns="http://statistik.uni-c.dk/VUCenkeltfag/">
<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: 15 udløser fejlen: \[The 'http://statistik.uni-c.dk/VUCenkeltfag/:CoesaFormaal' element is invalid - The value 'a000' is invalid according to its datatype 'Integer' - The Pattern constraint failed.\]</ErrorMessage>
<ErrorType>XmlValidationError</ErrorType>
</ExtendedValidationError>
</ValidationErrors>
</UploadXmlDataResult>
</UploadXmlDataResponse>
</soap:Body>
</soap:Envelope>
\\
Såfremt data er fejlfrie/accepteres, returneres nedenstående svar.
\\
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> <UploadXmlDataResponse xmlns="http://statistik.uni-c.dk/VUCenkeltfag/"> <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> </soap:Body> </soap:Envelope>
Liste med fejlmeddelelser for metoden UploadXmlData
Fejlmeddelelse | Forklaring |
|---|---|
Indberetningsaar er forkert. | Der er fundet et forkert indberetningsår i XML. Det korrekte er "september2016". |
Institutionsnummeret findes ikke i institutionsregisteret. | Institutionsnummer for indberettende eller afholdende institution findes ikke i institutionsregisteret. Kontakt STIL for at få det oprettet. |
Versionsnummer er forkert. | Det korrekte versionsnummer er "2.1". |
Der skal foreligge mindst én kursusdeltagelse- eller kompetencevurdering- eller bevispost for kursisten. | Der er i XML'en fundet en Kursist, der hverken har tilknyttet nogen Kursus-deltagelse, nogen Prøveresultater, nogen Kompetencevurdering eller nogen Beviser. Der skal være mindst én af disse tilknyttet. |
Coesakombination ikke tilladt: Cøsaformål | Kombinationen af CØSA-formål og version på Kursist skal være gyldig iht. det udmeldte i "Indberetningsstruktur for kursistindberetning til DVH". |
UvmFagkombination ikke tilladt: UvmFag | Kombinationen af fag og niveau på Kursusdeltagelse eller Kompetencevurdering skal være gyldig iht. det udmeldte i "Indberetningsstruktur for kursistindberetning til DVH". |
Rekvirenttype er ugyldig. | Rekvirenttypen på Kursusdeltagelse skal være gyldig iht. det udmeldte i "Indberetningsstruktur for kursistindberetning til DVH". |
Tilskudsmærke er ugyldig. | Tilskudsmærket (TMK) på Kursusdeltagelse skal være gyldigt iht. det udmeldte i "Indberetningsstruktur for kursistindberetning til DVH". |
Afholdelsesform er ugyldig. | Afholdelsesformen på Kursusdeltagelse skal være gyldig iht. det udmeldte i "Indberetningsstruktur for kursistindberetning til DVH". |
Kun for OBU må ForbrugteLektioner og UdbudteLektioner yy ' være udfyldt. | Kun hvis faget på Kursusdeltagelse er 5953 (Ordblindeundervisning), må ForbrugteLektioner og UdbudteLektioner være udfyldt. |
UvmFagEvalkombination ikke tilladt: UvmFag | Kombinationen af fag, niveau og Evalueringsform på ProeveresultaterPaaBeviser skal være gyldig ihht. det udmeldte. |
Institutionsnummeret for bevisudsteder findes ikke i institutionsregisteret. | Institutionsnummer for bevisudstedende institution på indberettet bevis findes ikke i institutionsregisteret. Kontakt STIL for at få det oprettet. |
, Version
.Udviklingsværktøjer
Webservicen 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 2 og 3 er eksempler på hhv. soap request og tilhørende soap response.
Bilag 1. Eksempel på valid XML-data
Eksempel med kun én kursist og ét kursus m.m.
<Indberetning xsi:schemaLocation="http://statistik.uni-c.dk/VUCenkeltfag/ KursistVers2.xml" xmlns="http://statistik.uni-c.dk/VUCenkeltfag/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Version>1.0</Version> <SystemVersion>a</SystemVersion> <JournalNummer>a</JournalNummer> <IndberetningsAar>september2016</IndberetningsAar> <InstitutionsNummer>100000</InstitutionsNummer> <AfholdInstitutionListe> <AfholdInstitution> <AfholdInstitutionsNummer>100000</AfholdInstitutionsNummer> <KursistListe> <Kursist> <CprNummer>1212120000</CprNummer> <CoesaFormaal>3015</CoesaFormaal> <Version>1</Version> <Fornavn>a</Fornavn> <Efternavn>a</Efternavn> <KursusdeltagelsesListe> <Kursusdeltagelse> <LokalHoldID>a</LokalHoldID> <Uvm_fag>1257</Uvm_fag> <Niveau>a</Niveau> <HoldDeltagelseStart>2022-01-01</HoldDeltagelseStart> <HoldDeltagelseSlut>2022-01-01</HoldDeltagelseSlut> <Afholdelsesform>Egen inst</Afholdelsesform> <Medtaelles>2</Medtaelles> <Undervisningsform>1</Undervisningsform> <ForbrugteLektioner xsi:nil="true"/> <UdbudteLektioner xsi:nil="true"/> <Provekode>4</Provekode> <FagligDokumentation>2</FagligDokumentation> <Afkortet>a</Afkortet> <KursusdeltagelsesUnderfagListe> <KursusdeltagelsesUnderfag> <Underfag>1257</Underfag> <UnderFagNiveau>A</UnderFagNiveau> </KursusdeltagelsesUnderfag> </KursusdeltagelsesUnderfagListe> <BidragListe> <Bidrag> <TMK>ENORD</TMK> <RekvirentType>UVM</RekvirentType> <VarighedKlokketimer>0.1</VarighedKlokketimer> <VarighedDage>0.1</VarighedDage> <Bidraget>0.001</Bidraget> <RestBidrag>0.001</RestBidrag> </Bidrag> </BidragListe> </Kursusdeltagelse> </KursusdeltagelsesListe> <ProveresultatListe> <Proveresultater> <Uvm_fag>1257</Uvm_fag> <Niveau>A</Niveau> <Evalueringsform>MDT</Evalueringsform> <ProveHoldID>a</ProveHoldID> <ProveHoldNavn>a</ProveHoldNavn> <ProveStartDato>2022-01-01</ProveStartDato> <ProveSlutDato>2022-01-01</ProveSlutDato> <Provetermin>a</Provetermin> <KarakterSkala>7TRIN</KarakterSkala> <Karakter>12</Karakter> <ProveresultatUnderfagListe> <ProveresultatUnderfag> <Underfag>1257</Underfag> <UnderFagNiveau>A</UnderFagNiveau> </ProveresultatUnderfag> </ProveresultatUnderfagListe> </Proveresultater> </ProveresultatListe> <KompetencevurderingsListe> <Kompetencevurdering> <Uvm_fag>1257</Uvm_fag> <Niveau>A</Niveau> <Anerkendt>9</Anerkendt> <AnerkendtDato>2010-01-01</AnerkendtDato> </Kompetencevurdering> <Kompetencevurdering> <Uvm_fag>1257</Uvm_fag> <Niveau>A</Niveau> <Anerkendt>9</Anerkendt> <AnerkendtDato>2010-01-02</AnerkendtDato> </Kompetencevurdering> </KompetencevurderingsListe> <BevisListe> <Bevis> <Bevistype>1</Bevistype> <Bevisdato>2022-01-01</Bevisdato> <BevisudstederInstNr>100000</BevisudstederInstNr> <ProeveresultaterPaaBevisListe> <ProeveresultaterPaaBevis> <Uvm_fag>1257</Uvm_fag> <FagNiveau>A</FagNiveau> <Evalueringsform>MDT</Evalueringsform> <KarakterSkala>7TRIN</KarakterSkala> <Karakter>12</Karakter> </ProeveresultaterPaaBevis> </ProeveresultaterPaaBevisListe> </Bevis> <Bevis> <Bevistype>1</Bevistype> <Bevisdato>2022-01-01</Bevisdato> <BevisudstederInstNr>100001</BevisudstederInstNr> <ProeveresultaterPaaBevisListe> <ProeveresultaterPaaBevis> <Uvm_fag>1257</Uvm_fag> <FagNiveau>A</FagNiveau> <Evalueringsform>MDT</Evalueringsform> <KarakterSkala>7TRIN</KarakterSkala> <Karakter>12</Karakter> </ProeveresultaterPaaBevis> </ProeveresultaterPaaBevisListe> </Bevis> </BevisListe> </Kursist> </KursistListe> </AfholdInstitution> </AfholdInstitutionListe> </Indberetning>
Bilag 2. Eksempel på soap request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:vuc="http://statistik.uni-c.dk/VUCenkeltfag/">
<soapenv:Header>
<vuc:Credentials>
<!--Optional:-->
<vuc:Username>?</vuc:Username>
<!--Optional:-->
<vuc:Password>?</vuc:Password>
<!--Optional:-->
<vuc:Institutionsnummer>100000</vuc:Institutionsnummer>
</vuc:Credentials>
</soapenv:Header>
<soapenv:Body>
<vuc:UploadXmlData>
<!--Optional:-->
<vuc:xml>
[…Indsæt XML som i Bilag 1…]
</vuc:xml>
</vuc:UploadXmlData>
</soapenv:Body>
</soapenv:Envelope>
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>
<UploadXmlDataResponse xmlns="http://statistik.uni-c.dk/VUCIndberetning/">
<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>
</soap:Body> </soap:Envelope>