Dokumentoplysninger

Gældende version
DatoVersionGældende fraAnsvarlig
01.11.2016

1.1

Den 1. november 2017Anne Haislund Odgaard

Ændringshistorik

Gældende version
Dato

Version

Emne

Ændring

Ændret af
01.11.2016

1.1

Kapitel 3.1

Begrænsning ift. hvornår servicen kan aktiveres uden at CPR-nummer er fjernet.

AHO

Arkiveret ændringshistorik

Tidligere versioner
Dato

Version

Emne

Ændring

Ændret af

1.0

Generelt

Første version.


Indhold

Indledning

Netprøver.dk tilbyder, at de studieadministrative systemer på institutioner med gymnasiale uddannelser (stx, hhx, htx og hf) kan afhente karakterer, der er afgivet af bedømmere på de skriftlige prøver, som Netprøver.dk understøtter.

Den enkelte institution vil udelukkende kunne afhente karakterer fra egne elever.

Denne side beskriver kort karakter-webservicen tilhørende Netprøver.dk (herefter Webservicen).

Kontakt Webservicen

Webservicen findes i et testmiljø. Servicebeskrivelsen findes på denne adresse: https://<stil-server> /karakterWS/karakterService?WSDL.

I drift anvendes denne adresse: https://<stil-server> /karakterWS/karakterService?WSDL

Webservicens Get-metoder

Webservicen udstiller en Get-metode, som kort beskrives nedenfor.

GetKarakterer, dokumentation af forespørgsel

I webservicen kan der afgrænses på følgende parametre:

Felt

Beskrivelse

Format

Institutionskode

Der udvælges karakterer for alle elever fra denne institution.
Dette er en krævet afgrænsning.

Tekst, 6 tegn.
Eksempel: "320003".

ProeveTermin

Der udvælges karakterer for alle elever på prøvehold med denne prøvetermin.
Dette er en krævet afgrænsning.

Tekst, maksimalt 20 tegn.
Eksempel: "S 2016".

CprNummer

Der udvælges karakterer for eleven med dette CPR-nummer.
Dette er en frivillig afgrænsning.

Tekst, 10 tegn.
Eksempel: "1234561234".

ProeveStartdato

Der medtages karakterer hvor prøvens startdato ligger på eller efter denne dato.
Dette er en frivillig afgrænsning.

Datoformat i tekst, 10 tegn.
Eksempel: "01-01-2016".

ProeveSlutdato

Der medtages karakterer hvor prøvens slutdato ligger på eller før denne dato.
Dette er en frivillig afgrænsning.

Datoformat i tekst, 10 tegn.
Eksempel: "31-12-2016".

Derudover skal webservicen altid kaldes med et unikt transaktionsid og angivelse af kaldtidspunkt.

Felt

Beskrivelse

Format

Transaktionsid

Et unikt id, som kan bruges til at identificere kaldet i logfiler etc.
Dette er et krævet felt.

Tekst, maksimalt 200 tegn.

TransaktionsTid

Dato og tid for hvornår webservicekaldet foretages.
Dette er et krævet felt.

Datoformat i tekst, 20 tegn.
yyyy-mm-ddThh:mi:ssZ
Eksempel: "2016-12-31T12:00:00Z".


Herunder er XSD-skemaet illustreret:

GetKarakterer, dokumentation af svar

Webservicen svarer med følgende oplysninger:

Felt

Beskrivelse

Format

Proeveholdsid

Det id, som er registreret i XPRS for det pågældende prøvehold.

Tekst, maksimalt 50 tegn
Eksempel: "320003_11990782287_7020AS1+1".

Proeveholdsnavn

Prøveholdets navn i Netprøver.dk.

Tekst, maksimalt 50 tegn.
Eksempel: "2016 ma1p 1-2s S1".

Proevetermin

Prøveterminen for prøveholdet.

Tekst, maksimalt 20 tegn.
Eksempel: "S 2016".

Proevestart

Startdato og tid for prøveholdet.

Datoformat i tekst, 20 tegn.
yyyy-mm-ddThh:mi:ssZ
Eksempel: "2016-12-31T09:00:00Z".

Proeveslut

Startdato og tid for prøveholdet.

Datoformat i tekst, 20 tegn:
yyyy-mm-ddThh:mi:ssZ
Eksempel: "2016-12-31T12:00:00Z".

Fagnummer

Nummeret på faget.

Tekst, maksimalt 5 tegn.
Eksempel: "7020".

Fagniveau

Niveauet på faget.

Tekst, 1 tegn.
Eksempel: "A".

KarakterVaerdi

Karakteren, som blev givet.
Netprøver.dk håndterer pt. kun skriftlige karakterer givet i 7-trinsskalaen.

Tekst, maksimalt 10 tegn.
Eksempel: "12".

CPRNummer

Elevens CPR-nummer.

Tekst, 10 tegn.
Eksempel: "1234561234".


Herunder er XSD-skemaet illustreret (med fokus på ovenstående felter):

Herudover leverer webservicen altid nogle hovedoplysninger med i svaret.

Såfremt der er fejl i forbindelse med webservice kaldet, vil der desuden blive leveret oplysninger om fejlen i disse hovedoplysninger:

Felt

Beskrivelse

Format

Transaktionsid

Et id fra forespørgslen, således at forespørgsel og svar kan sammenholdes.

Tekst, maksimalt 200 tegn.

TransaktionsTid

Dato og tid for hvornår svaret på webservicekaldet blev genereret.

Datoformat i tekst, 20 tegn.
yyyy-mm-ddThh:mi:ssZ
Eksempel: "2016-12-31T12:00:00Z".

FejlKode

En kode som unikt identificerer fejltypen.

Tekst, 4 tegn.
Eksempel: "1001".

FejlBeskrivelse

En kort beskrivelse af fejlen.

Tekst, maksimalt 200 tegn.
Eksempel: "Du kan ikke forespørge på karakterer for elever der ikke er tilknyttet din institution".


Herunder er XSD-skemaet illustreret (med fokus på hovedoplysningerne):

GetKarakterer eksempler på svar

Denne metode returnerer de karakterer, der er forespurgt på. GetKarakterer returnerer en liste i XML-format i stil med nedenstående (forkortede) svar:

Eksempel på OK-svar

<net2016:KarakterSamling>
<net2016:Karakter>
<net2016:Proeveholdsid>320003_11990782287_7020CS1+1</net2016:Proeveholdsid>
<net2016:Proeveholdsnavn>2016 ma1p 1-2s S1</net2016:Proeveholdsnavn>
<net2016:Proevetermin>S 2016</net2016:Proevetermin>
<net2016:Proevestart>2016-05-31T09:00:00Z</net2016:Proevestart>
<net2016:Proeveslut>2016-05-31T12:00:00Z</net2016:Proeveslut>
<net2016:Fagnummer>7020</net2016:Fagnummer>
<net2016:Fagniveau>C</net2016:Fagniveau>
<net2016:KarakterVaerdi>12</net2016:KarakterVaerdi>
<net2016:CPRNummer>010101test</net2016:CPRNummer>
</net2016:Karakter>
…
<net2016:Karakter>
<net2016:Proeveholdsid>320003_11990782287_7020AS1+1</net2016:Proeveholdsid>
<net2016:Proeveholdsnavn>2016 ma1p 1-2s S1</net2016:Proeveholdsnavn>
<net2016:Proevetermin>S 2016</net2016:Proevetermin>
<net2016:Proevestart>2016-05-31T09:00:00Z</net2016:Proevestart>
<net2016:Proeveslut>2016-05-31T12:00:00Z</net2016:Proeveslut>
<net2016:Fagnummer>7020</net2016:Fagnummer>
<net2016:Fagniveau>A</net2016:Fagniveau>
<net2016:KarakterVaerdi>7</net2016:KarakterVaerdi>
<net2016:CPRNummer>010102test</net2016:CPRNummer>
</net2016:Karakter>
</net2016:KarakterSamling>

Eksempel på Fejl-svar

<?xml version="1.0" encoding="UTF-8"?>
<net2016:KarakterSamlingOutput xsi:schemaLocation="http://cgi.com/netproever/2016/06/30/ KarakterServiceOutput.xsd" xmlns:net2016="http://cgi.com/netproever/2016/06/30/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<net2016:Hovedoplysninger>
<net2016:Transaktionsid>ABCD-12334</net2016:Transaktionsid>
<net2016:Transaktionstid>2016-12-17T09:30:47Z</net2016:Transaktionstid>
<net2016:FejlSamling>
<net2016:FejlBesked>
<net2016:FejlKode>1001</net2016:FejlKode>
<net2016:FejlBeskrivelse>Du kan ikke forespørge på karakterer for elever der ikke er tilknyttet din institution</net2016:FejlBeskrivelse>
</net2016:FejlBesked>
</net2016:FejlSamling>
</net2016:Hovedoplysninger>
<net2016:KarakterSamling/>
</net2016:KarakterSamlingOutput>

Udviklingsværktøjer

Webservicen er udviklet i Java. Webservicen tilgås via WSDL'en (se evt. afsnit 2).

Følgende gratis udviklingsværktøjer kan anbefales til test og debug:

Bilag 1 og 2 er eksempler på hhv. soap request og tilhørende soap response.

Bilag 1: Eksempel på soap request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<wsse:Security>
<wsse:UsernameToken wsu:Id="netproever"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility">
<wsse:Username>320003</wsse:Username>
<wsse:Password>et-kodeord</wsse:Password>
<wsu:Created>2016-09-28T09:16:32</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soap:Body>
<net2016:KarakterForespoergselInput xsi:schemaLocation="http://cgi.com/netproever/2016/06/30/ karakterServiceInput.xsd" xmlns:net2016="http://cgi.com/netproever/2016/06/30/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<net2016:Hovedoplysninger>
<net2016:Transaktionsid>ABCD-1233234</net2016:Transaktionsid>
<net2016:Transaktionstid>2016-09-28T09:16:32Z </net2016:Transaktionstid>
</net2016:Hovedoplysninger>
<net2016:KarakterForespoergsel>
<net2016:Institutionskode>320003</net2016:Institutionskode>
<net2016:ProeveTermin>S 2016</net2016:ProeveTermin>
<net2016:ProeveStartdato>01-01-2016</net2016:ProeveStartdato>
<net2016:ProeveSlutdato>31-12-2016</net2016:ProeveSlutdato>
</net2016:KarakterForespoergsel>
</net2016:KarakterForespoergselInput>
</soap:Body>
</soap:Envelope>

Bilag 2: Eksempel på soap response

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<wsa:Action>GetKaraktererResponse</wsa:Action>
<wsa:MessageID>urn:uuid:cbb23720-adb1-41d9-a302-b76e029e3543</wsa:MessageID>
<wsa:RelatesTo>urn:uuid:abfaea8e-55d3-48bf-b6e3-7132bb17a284</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-7f510811-4bc3-493f-98d1-9ce2b44fafba">
<wsu:Created>2016-09-28T09:16:32Z</wsu:Created>
<wsu:Expires>2016-09-28T09:21:32Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<net2016:KarakterSamlingOutput xsi:schemaLocation="http://cgi.com/netproever/2016/06/30/ KarakterServiceOutput.xsd" xmlns:net2016="http://cgi.com/netproever/2016/06/30/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<net2016:Hovedoplysninger>
<net2016:Transaktionsid>ABCD-12334</net2016:Transaktionsid>
<net2016:Transaktionstid>2016-09-28T09:16:32</net2016:Transaktionstid>
</net2016:Hovedoplysninger>
<net2016:KarakterSamling/>
</net2016:KarakterSamlingOutput>
</soap:Body>
</soap:Envelope>