Grænseflade til afhentning og indberetning af prøvekarakterer i dansk og matematik på Optagelse.dk Dato 16-09-2015 Version Status 1.0 Gældende Ansvarlig Tobias Thisted
Side 2 af 11 Ændringshistorik Version Kapitel/afsnit Beskrivelse 1.0 Hele dokumentet Ny beskrivelse baseret på eksisterende beskrivelser hidtil publiceret på Optagelse.dk.
Side 3 af 11 Indhold 1 Introduktion... 4 2 Adgang og sikkerhed... 4 3 Operationer/metoder... 4 3.1.1 getmarks(string cpr)... 5 3.1.2 setfs10marks(setfs10marksrequest requesttype)... 6 3.1.3 setfsamarks(setfsamarksrequest requesttype)... 8 4 Eksempler... 8 4.1 Eksempel... 8 4.2 Ændringer af prøver... 9 5 Test... 10 5.1.1 Ændring af endpoint... 11 5.1.2 Testdata... 11
Side 4 af 11 1 Introduktion Formålet med MarksService er at fungere som et opsamlingspunkt, hvortil institutioner kan indberette og hente prøvekarakterer for elever i 9.(FSA) -og 10. klasse(fs10). 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. I forbindelse med krav til kommende studerendes gennemsnit i dansk og matematik for 9. og 10. klasse skal institutioner have mulighed for at indberette prøvekarakterer for eleverne. Yderligere skal de modtagende institutioner have mulighed for at afhente prøvekarakterer for de ansøgende elever. Derfor introduceres MarksService som et samlingspunkt, hvortil institutioner kan indberette samt afhente prøvekarakterer for en elev ud fra et cpr-nummer. Her findes to metoder til at sætte prøvekarakterer, én til FSA- og én til FS10- prøvekarakterer. Det kræver, 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 Servicen på Optagelse.dk kan findes via følgende links (kræver login): Test: https://test.optagelse.dk/security-proxy/webservice/marksservice?wsdl Produktion:https://www.optagelse.dk/securityproxy/webservice/MarksService?wsdl Tjenesten er beskyttet af UNI-Login og kræver rollen opt_get_marks og/eller opt_set_marks. I webservice-sammenhæng betyder det, at brugernavn og kodeord skal udfyldes som basic authentication i forespørgslens http-header. 3 Operationer/metoder Tjenesten består af følgende operationer: 1. getmarks(string cpr) 2. setfs10marks(setfs10marksrequesttype requesttype) 3. setfsamarks(setfsamarksrequesttype requesttype)
Side 5 af 11 3.1.1 getmarks(string cpr) getmarks anvendes til at hente indmeldte prøvekarakterer på en elev ud fra et cprnummer. return 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. return "tom" hvis der ikke findes en person med det givne cpr-nummer, returneres tom body. return Fault (throws AuthorizationFailedException) webservice-bruger har ikke rollen opt_get_marks. return Fault - hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet. 3.1.1.1 Parameter Navn Type Beskrivelse cpr Number* CPR nr. på 10 tal * = Krævet felt 3.1.1.2 Eksempel 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>0208887780</ns:getmarksrequest> </soapenv:body> </soapenv:envelope> Resultatet: 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> <testsubjectid>110_003</testsubjectid> <value>86</value>
Side 6 af 11 <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.1.2 setfs10marks(setfs10marksrequest requesttype) Metoden sætter 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 overskrivet 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. return true ved succesfuld overførsel og registrering af prøvekarakterer.
Side 7 af 11 return Fault (throws AuthorizationFailedException) webservice-bruger har ikke rollen opt_set_marks. return Fault (throws InvalidMarks) karakterer er ikke valide, eksempelvis hvis det samme testsubjectid optræder flere gange i requestet. return Fault hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet. 3.1.2.1 Parametre cpr Navn Type Beskrivelse Number* CPR nr. på 10 tal institutionnumber String* Institutionsnummer på 6 tal marks:danishmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:danishmark:value marks:mathematicsmark:testsubjectid String marks:mathematicsmark:value * = Krævet felt 3.1.2.2 Eksempel Number En valid prøvekarakter Id for prøvekarakter (testsubjectid) Number En valid prøvekarakter 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> <!--Zero or more repetitions:--> </ns:marks> </ns:setfs10marksrequest> </soapenv:body> </soapenv:envelope> Resultat:
Side 8 af 11 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.1.3 setfsamarks(setfsamarksrequest requesttype) Metoden sætter 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. return true ved succesfuld overførsel og registrering af prøvekarakterer. return Fault (throws AuthorizationFailedException) webservice bruger har ikke rollen opt_set_marks. return Fault (throws InvalidMarks) karakterer er ikke valid, eksempelvis hvis det samme testsubjectid optræder flere gange i requestet. return Fault hvis xml ikke overholder xsd'er, da der er skemavalidering på requestet. 3.1.3.1 Parametre cpr Navn Type Beskrivelse Number* CPR nr. på 10 tal institutionnumber String* Institutionsnummer på 6 tal marks:danishmark:testsubjectid String Id for prøvekarakter (testsubjectid) marks:danishmark:value marks:mathematicsmark:testsubjectid String marks:mathematicsmark:value * = Krævet felt 4 Eksempler 4.1 Eksempel Number En valid prøvekarakter Id for prøvekarakter (testsubjectid) Number En valid prøvekarakter 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:-->
Side 9 af 11 <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> 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> 4.2 Ændringer af prøver Servicen er lavet så tilpasningsvenlig som muligt, når der skal tilføjes eller fjernes typer af prøvekarakterer. I XSD'erne FSADanish -, FSAMathematics -, FS10Danish -, FS10MathematicsSubject.xsd tilrettes enumeration, så det passer de ønskede prøvekaraktertyper. Et eksempel ses nedenfor: FSADanishSubject.xsd <?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:tns="http://optagelse.dk/marks/2014/11/06" target- Namespace="http://optagelse.dk/marks/2014/11/06" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:simpletype name="fsadanishsubjectid"> <xs:restriction base="xs:string"> <xs:enumeration value="110_001"> <xs:annotation> <xs:documentation>testsubjectid 110_001:Dansk, læsning</xs:documentation> </xs:annotation> </xs:enumeration> <xs:enumeration value="110_002">
Side 10 af 11 <xs:annotation> <xs:documentation>testsubjectid 110_002: Dansk, retskrivning</xs:documentation> </xs:annotation> </xs:enumeration> <xs:enumeration value="110_003"> <xs:annotation> <xs:documentation>testsubjectid 110_003: Dansk, skriftlig fremstilling</xs:documentation> </xs:annotation> </xs:enumeration> <xs:enumeration value="110_005"> <xs:annotation> <xs:documentation>testsubjectid 110_005: Dansk, mundtlig</xs:documentation> </xs:annotation> </xs:enumeration> </xs:restriction> </xs:simpletype> </xs:schema> Yderligere skal der rettes i bindings.xml, under MarksService, så det afspejler de rigtige testsubjectids: FSADanishSubject.xsd <jxb:bindings xmlns:xs="http://www.w3.org/2001/xmlschema" xmlns:jxb="http://java.sun.com/xml/ns/jaxb" version="2.1"> <jxb:bindings schemalocation="fs10danishsubject.xsd"> <jxb:bindings node="//xs:simpletype[@name='fs10danishsubjectid']/xs:restriction/xs:enumeration[@value='110_001 ']"> <jxb:typesafeenummember name="dansklaesning"/> <jxb:bindings node="//xs:simpletype[@name='fs10danishsubjectid']/xs:restriction/xs:enumeration[@value='110_002 ']"> <jxb:typesafeenummember name="danskretskrivning"/> <jxb:bindings node="//xs:simpletype[@name='fs10danishsubjectid']/xs:restriction/xs:enumeration[@value='110_003 ']"> <jxb:typesafeenummember name="danskskriftligfremstilling"/> <jxb:bindings node="//xs:simpletype[@name='fs10danishsubjectid']/xs:restriction/xs:enumeration[@value='110_005 ']"> <jxb:typesafeenummember name="danskmundtlig"/>... Herefter skal modulet, service-ext, bygges, så de nye typer generes. 5 Test Webservicen kan testes ved at importere nedenstående projekt i SoapUI:
Side 11 af 11 MarksService-soapui-project.xml Vælg File -> Import project -> og vælg ovenstående fil som er gemt et lokalt sted: 5.1.1 Ændring af endpoint Det er vigtig at være opmærksom på, at endpoint skal ændres til at pege mod den testserver, man ønsker at udføre tests på: 5.1.2 Testdata Der kan findes eksempler på flere requests i projekterne. Her bør testdata ændres til at indeholde data, som er valide på testtidspunktet.