Grænseflade til afhentning af grundskoleprøvekarakterer fra Optagelse.dk Dato 24-06-2016 Version Status 1.0 Gældende fra og med den 1. juli 2016 Ansvarlig Tobias Thisted
Side 2 af 8 Indhold 1 Introduktion 3 2 Adgang og sikkerhed 3 3 Operationer/metoder 3 3.1 getmarks(string cpr) 4 3.1.1 Eksempel på indberetning 4 3.1.2 Resultat 4 3.2 setfs10marks(setfs10marksrequest requesttype) 5 3.2.1 Eksempel på indberetning setfs10marks() 6 3.2.2 Resultat setfs10marks(): 7 3.3 setfsamarks(setfsamarksrequest requesttype) 7 3.3.1 Eksempel på indberetning setfsamarks() 8 3.3.2 Resultat setfsamarks() 8
Side 3 af 8 1 Introduktion I forbindelse med krav til kommende studerendes gennemsnit i dansk og matematik for 9. og 10. klasse skal uddannelsesinstitutioner have mulighed for at indberette prøvekarakterer for deres elever. Endvidere skal modtagende uddannelsesinstitutioner have mulighed for at afhente prøvekarakterer for ansøgende elever. Derfor introduceres i Optagelse.dk tjenesten MarksService. Formålet med Marks- Service er at fungere som et opsamlingspunkt, hvor institutioner kan indberette og hente prøvekarakterer for elever i 9.klasse (FSA) og 10. klasse(fs10). Webservicen til afhentning af karakterer anvendes aktuelt kun på EUD-området. MarksService er ikke knyttet til anden logik i Optagelse.dk og er ikke underlagt eller afhængig af andre forretningsgange i applikationen. Målet har været at lave en selvstændig og simpel service, som er fleksibel i forhold til ændringer af typer af prøveeksaminer. Her findes to metoder til at sætte prøvekarakterer, én til FSA- og én til FS10- prøvekarakterer. Det kræves, at brugeren har brugerrollen opt_set_marks for at kalde metoderne. Alle prøvekarakterer overskrives ved hver indlæsning, hvorfor alle elevens prøvekarakterer skal sendes hver gang. Ved afhentning kræves brugerrollen opt_get_marks. Ved afhentning returneres prøvekarakterer samt gennemsnittet for prøvekarakterer, hvis alle prøvekaraktererne inden for et område, FSA Dansk/Matematik og FS10 Dansk/Matematik, er indberettet. 2 Adgang og sikkerhed MarksService på Optagelse.dk kan findes via følgende links: Test: https://test.optagelse.dk/security-proxy/webservice/marksservice?wsdl Produktion: https://www.optagelse.dk/securityproxy/webservice/marksservice?wsdl Servicen er beskyttet af login. Brugernavn og kodeord kan tildeles ved henvendelse til Styrelsen for It og Læring (STIL) på mailadressen optagelse@stil.dk, hvor der også kan fås nærmere vejledning. Anvendelse af MarksService kræver som ovenfor nævnt rollen opt_get_marks og/eller opt_set_marks. Ved forespørgsel via denne web service skal brugernavn og kodeord udfyldes som basic authentication i forespørgslens http-header. 3 Operationer/metoder Tjenesten består af følgende operationer/metoder: 1. getmarks(string cpr) 2. setfs10marks(setfs10marksrequesttype requesttype)
Side 4 af 8 3. setfsamarks(setfsamarksrequesttype requesttype) 3.1 getmarks(string cpr) getmarks anvendes til at hente indmeldte prøvekarakterer på en elev ud fra et cprnummer som parameter i søgningen: Navn Type Beskrivelse cpr Number* CPR nr. på 10 cifre * = Krævet felt Følgende resultater er mulige: StudentMarks hvis der findes studerende med det givne cpr-nummer, returneres liste af karakterer samt udregnede gennemsnit for FSA/FS10 Dansk og FSA/FS10 Matematik. "tom" hvis der ikke findes en person med det givne cpr-nummer, returneres tom body. Fault (throws AuthorizationFailedException) webservice-bruger har ikke rollen opt_get_marks. Fault - hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet. 3.1.1 Eksempel på indberetning getmarks() <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://optagelse.dk/marks/2014/11/06"> <soapenv:header/> <soapenv:body> <ns:getmarksrequest>1231231231</ns:getmarksrequest> </soapenv:body> </soapenv:envelope> 3.1.2 Resultat getmarks() <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <getmarksresponse xmlns="http://optagelse.dk/marks/2014/11/06"> <cpr> <cpr>1231231231</cpr> </cpr> <institutionnumber>183407</institutionnumber> <createddate>2015-02-25t11:31:22.829+01:00</createddate> <FSADanishMarkAvgNotComputable>true</FSADanishMarkAvgNotComputable> <FS10DanishMarkAvgNotComputable>true</FS10DanishMarkAvgNotComputable> <FSAMathematicsMarkAvgNotComputable>true</FSAMathematicsMarkAvgNotComputable> <FS10MathematicsMarkAvgNotComputable>true</FS10MathematicsMarkAvgNotComputable> <fs10marks> <testsubjectid>110_002</testsubjectid> <value>02</value>
Side 5 af 8 <testsubjectid>110_003</testsubjectid> <value>86</value> <testsubjectid>110_005</testsubjectid> <value>86</value> <testsubjectid>310_007</testsubjectid> <value>87</value> <testsubjectid>310_008</testsubjectid> <value>87</value> <testsubjectid>310_003</testsubjectid> <value>4</value> </fs10marks> <fsamarks> <testsubjectid>110_002</testsubjectid> <value>02</value> <testsubjectid>110_005</testsubjectid> <value>86</value> <testsubjectid>110_003</testsubjectid> <value>7</value> <testsubjectid>310_008</testsubjectid> <value>87</value> <testsubjectid>310_003</testsubjectid> <value>4</value> <testsubjectid>310_007</testsubjectid> <value>87</value> </fsamarks> </getmarksresponse> </soap:body> </soap:envelope> 3.2 setfs10marks(setfs10marksrequest requesttype) Metoden indberetter for en given elev FS10-prøvekarakterer inden for dansk og/eller matematik. Hvis eleven med det angivne cpr-nummer allerede har indberettede FS10-prøvekarakterer, vil disse blive overskrevet med de nye. Dvs. at alle elevens prøvekarakterer skal indberettes hver gang.
Side 6 af 8 Dette giver også mulighed for at fjerne en prøvekarakter i forbindelse med en fejlindberetning, ved blot at undlade at tilføje prøvekarakteren ved næste kald. Parametre i indberetningen er: Navn Type Beskrivelse cpr Number* CPR nr. på 10 tal institutionnumber String* Institutionsnummer på 6 tal marks:danishmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:danishmark:value Number En valid prøvekarakter marks:mathematicsmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:mathematicsmark:value Number En valid prøvekarakter * = Krævet felt Følgende resultater er mulige: True ved succesfuld overførsel og registrering af prøvekarakterer. Fault (throws AuthorizationFailedException) webservice-bruger har ikke rollen opt_set_marks. Fault (throws InvalidMarks) karakterer er ikke valide, eksempelvis hvis det samme testsubjectid optræder flere gange i requestet. Fault hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet. 3.2.1 Eksempel på indberetning setfs10marks() <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://optagelse.dk/marks/2014/11/06"> <soapenv:header/> <soapenv:body> <ns:setfs10marksrequest> <ns:cpr>1212121212</ns:cpr> <ns:institutionnumber>123</ns:institutionnumber> <ns:marks> <!--Zero or more repetitions:--> <ns:testsubjectid>110_001</ns:testsubjectid> <ns:value>10</ns:value> <ns:testsubjectid>110_002</ns:testsubjectid> <ns:value>10</ns:value> <ns:testsubjectid>110_003</ns:testsubjectid> <ns:value>12</ns:value> <ns:testsubjectid>110_005</ns:testsubjectid> <ns:value>12</ns:value>
Side 7 af 8 <!--Zero or more repetitions:--> </ns:marks> </ns:setfs10marksrequest> </soapenv:body> </soapenv:envelope> 3.2.2 Resultat setfs10marks(): <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <parameter xsi:type="xs:boolean" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:ns3="http://optagelse.dk/marks/2014/11/06" xmlns:ns2="http://rep.oio.dk/cpr.dk/xml/schemas/core/2002/06/28/">true</parameter> </soap:body> </soap:envelope> 3.3 setfsamarks(setfsamarksrequest requesttype) Metoden indberetter for en given elev FSA-prøvekarakterer inden for dansk og/eller matematik. Hvis eleven med det angivne cpr-nummer allerede har indberettede FSA-prøvekarakterer, vil disse overskrives med de nye. Dvs. at alle elevens prøvekarakterer skal indberettes hver gang. Dette giver også mulighed for at fjerne en prøvekarakter i forbindelse med en fejlindberetning ved blot at undlade at tilføje prøvekarakteren ved næste kald. Parametre i indberetningen er: Navn Type Beskrivelse Cpr Number* CPR nr. på 10 tal institutionnumber String* Institutionsnummer på 6 tal marks:danishmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:danishmark:value Number En valid prøvekarakter marks:mathematicsmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:mathematicsmark:value Number En valid prøvekarakter * = Krævet felt Følgende resultater er mulige: true ved succesfuld overførsel og registrering af prøvekarakterer. Fault (throws AuthorizationFailedException) webservice-bruger har ikke rollen opt_set_marks. Fault (throws InvalidMarks) karakterer er ikke valide, eksempelvis hvis det samme testsubjectid optræder flere gange i requestet. Fault hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet.
Side 8 af 8 3.3.1 Eksempel på indberetning setfsamarks() <soapenv:envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://optagelse.dk/marks/2014/11/06"> <soapenv:header/> <soapenv:body> <ns:setfsamarksrequest> <ns:cpr>1212121212</ns:cpr> <ns:institutionnumber>123</ns:institutionnumber> <ns:marks> <!--Zero or more repetitions:--> <ns:testsubjectid>110_001</ns:testsubjectid> <ns:value>10</ns:value> <ns:testsubjectid>110_002</ns:testsubjectid> <ns:value>10</ns:value> <ns:testsubjectid>110_003</ns:testsubjectid> <ns:value>12</ns:value> <ns:testsubjectid>110_005</ns:testsubjectid> <ns:value>12</ns:value> <!--Zero or more repetitions:--> </ns:marks> </ns:setfsamarksrequest> </soapenv:body> </soapenv:envelope> 3.3.2 Resultat setfsamarks() <soap:envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <parameter xsi:type="xs:boolean" xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:ns3="http://optagelse.dk/marks/2014/11/06" xmlns:ns2="http://rep.oio.dk/cpr.dk/xml/schemas/core/2002/06/28/">true</parameter> </soap:body> </soap:envelope>