Sidehistorik
Dokumenthistorik
Dato | Version | Ændring | Ændret af |
---|---|---|---|
| 0.9 | Første offentliggørelse af foreløbig grænsefladebeskrivelse | |
| 0.9 | Sammenfletning af Elevdata og Uddannelsesdata | |
| 0.9 | Opdatering af links | Thor Thomsen Krarup |
| 0.9 | Opdatering af valideringsregler vedr. Institutionsdata | |
| 0.9 | Præcisering af fejlbeskeder | |
| 0.9 | Afgangsårsager udgår og fejlvalideringsregler opdateres | |
| 0.9 | Eksempler på fejlbeskeder, request og response er opdateret |
Indhold
Indholdsfortegnelse maxLevel 3 exclude Indhold
Bemærk | ||
---|---|---|
| ||
Indberetning af afgangsårsager er udgået fra Elevdatabasens indberetningsflade |
Elevdatabasen
Elevdatabasen er et nyt grunddatasystem i Styrelsen for It og Læring (STIL) indeholdende grunddata om elever på uddannelser under Børne- og Undervisningsministeriets (BUVM) resortområde. De konkrete grunddata omfatter oplysninger om elevers aktuelle tilknytning til institutioner og uddannelser, herunder trin, start- og slutdatoer mv. samt elevernes årsager til afgang fra de enkelte uddannelsesforløb. De overordnede dataområder Elevdatabasen opererer med er persondata, institutionsdata og uddannelsesdata.
...
Indberetninger til Elevdatabasen sker fra uddannelsesinstitutionernes studieadministrative systemer (SA-systemer) via en webservice udstillet på STIL’s integrationsplatform (Integrationsplatformen). Integrationsplatformen er knudepunktet for STIL’s eksternt rettede webservices. Den er en infrastrukturkomponent som via autentificering, autorisering, logning og kryptering (https) understøtter en sikker, ensartet og effektiv udveksling af data mellem STIL's centrale systemer og eksterne systemer. Yderligere oplysninger om tilslutning samt tekniske detaljer kan findes på STIL’s supportside for Integrationsplatformen. Det overordnede flow kan ses i diagrammet nedenfor:
Indberetning til Elevdatabasen
Grunddata om elever
Følgende sektion beskriver i overordnede træk de tre dataområder i Elevdatabasen, der til sammen udgør grunddata om elever, og mod hvilke kilder denne data valideres.
...
Håndtering af indberetninger, der ikke overholder valideringsreglerne, beskrives i afsnittet Fejlhåndtering.
Grundlæggende principper for indberetning
- En indberetning skal indeholde gældende data for en elev pr. indberetningsdatoen.
- En indberetning skal indeholde historisk data frem til indberetningsdatoen
- Ved ændringer til data på eleven skal indberetning ske senest dagen efter, at ændringen træder i kraft
- En indberetning må ikke indeholde forventede ændringer
- Brobygningselever og prøvedeltagere skal ikke indberettes
Omfattede uddannelser
I første omgang er det alene grunddata om elever på det gymnasiale område der skal indberettes. Det gymnasiale område defineres af de uddannelser der til enhver tid fremgår under formålsgruppe 2 og 33 i Uddannelsesmodellen.
...
Uddannelseskode (CØSA formål) | Uddannelse | Formålsgruppe |
---|---|---|
1064 | FGU-kombi med htx fagelementer | 2 |
1080 | Studierettet påbygning, tekniske uddannelser | 2 |
1980 | Studierettet påbygning, merkantile uddannelser | 2 |
3010 | Højere Handelseksamen | 2 |
3044 | 2-årigt hhx kursus | 2 |
3310 | Højere teknisk eksamen | 2 |
3311 | EUX, tekniske uddannelser | 2 |
3315 | EUX, merkantile uddannelser | 2 |
1063 | FGU-kombi med hf-fagelementer | 33 |
2992 | European Baccalaureate | 33 |
2999 | Ingeniør Adgangskurser | 33 |
3000 | Optagelsesprøve gymnasiale uddannelser | 33 |
3001 | Et- og flerårige enkeltfag | 33 |
3003 | Pre International Baccalaureate | 33 |
3009 | stx | 33 |
3017 | hf | 33 |
3021 | Studenterkursus | 33 |
3028 | International Baccalaureate | 33 |
3042 | Laboratoriekurser for enkeltfagselever | 33 |
3046 | hf 3 årigt forløb | 33 |
3047 | 3 årigt studenterkursus | 33 |
3079 | stx 4 årigt forløb | 33 |
3312 | Dansk-Tysk studentereksamen | 33 |
3313 | Dansk-Fransk Bacalaurétte | 33 |
Integrationsmønstre
Følgende sektion beskriver de krav det SA-systemet skal opfylde ved integration til Elevdatabasen. Kravene er vigtige for at sikre en stabil service og data af høj kvalitet.
Sikring af stabil drift
For at sikre stabil drift af Elevdatabasen, skal integrationen designes så der maksimalt sendes 20 requests i sekundet per SA-system.
...
Hvis en indberetning fejler, og der automatisk prøves igen, skal disse indberetninger stadig ske kontrolleret jf. dette krav. Det anbefales ydermere, at man ved gentagende fejl øger forsinkelsen for hvornår der prøves igen, da fejlen kan være relateret til en overbelastning internt i Elevdatabasen.
Håndtering af samtidighed
Da beskeder kan skifte rækkefølge i både netværk og på Integrationsplatformen (IPL), giver det en risiko for, at ændringer kan bliver overhalet, og dermed bliver data i Elevdatabasen forskellig fra den faktiske data i SA-systemet.
...
Ønsker man at parallelisere indberetninger er det vigtigt, at paralleliseringen sker grupperet på CPR-nummer eller institution.
Håndtering af udfald i netværk og infrastruktur
Alle indberetninger skal påsættes et IndberetningsID af typen GUID, for at undgå dobbeltindberetninger ved fejl i netværk elleranden infrastruktur.
...
Se tabellen i afsnittet Fejlhåndtering for yderligere detaljer om hvornår man forventes at gensende- eller generere en nyt IndberetningsID.
Webservice
Denne sektion beskriver den webservice der skal anvendes til brug for indberetning.
Anker Adgang til webservice Adgang til webservice
Adgang til webservice
Adgang til webservice | |
Adgang til webservice |
Elevdatabasens webservice udstilles på STIL's integrationsplatform (Integrationsplatformen). Integrationsplatformen anvender STIL's system Tilslutning til brug for oprettelse, administration og vedligehold af tilslutninger og dataadgange mellem institutioner og systemleverandører (udbydere).
...
Yderligere oplysninger om tilslutning samt tekniske detaljer kan findes på STIL’s supportside for Integrationsplatformen.
Operationer
Der findes følgende 3 operationer i Elevdatabasen, Indberet, Status og Ping.
Operation | Beskrivelse |
---|---|
Indberet | Selve indberetningen, dvs. data om elev, uddannelse mv. |
Status | Henter status for en indberetning ud fra IndberetningsId |
Ping | Angiver om Elevdatabasen er funktionel |
Anker Indberet Indberet
Indberet
Indberet | |
Indberet |
Indberetning af data til Elevdatabasen sker med operationen Indberet for én elev af gangen.
...
De tekniske detajler, og eksempel på request/response kan findes i afsnittet Teknisk beskrivelse af operationer
Anker Status Status
Status
Status | |
Status |
Anvendes til at hente - eller genhente - status for en indberetning ud fra det ID som indberetningen er foretaget på. Ved status FAILED
, vil responset indeholde valideringsfejlene, der efterfølgende kan behandles af afhenter. Svaret fra Status-operationen er identisk med svaret på en indberetning, og kan benyttes ved tvivl om hvorvidt en indberetning er gået godt.
De tekniske detajler, og eksempel på request/response kan findes i afsnittet Teknisk beskrivelse af operationer
Ping
Anvendes til at pinge Elevdatabasen.
De tekniske detajler, og eksempel på request/response kan findes i afsnittet Teknisk beskrivelse af operationer
Anker Fejlhåndtering Fejlhåndtering
Fejlhåndtering
Fejlhåndtering | |
Fejlhåndtering |
Elevdatabasen opererer med 3 typer af fejlkoder, Elevdb-XXXX, Indb-XXXX og Pers-1000. Elevdb-XXXX fejlkoderne dækker over interne fejl på Elevdatabasen. Indb-XXXX fejlkoderne dækker over fejl i indberetningen fra de studieadministrative systemer til Elevdatabasen. Pers-XXXX dækker over fejl i forbindelse med validering af CPR-oplysninger og kommunikation med CPR-registeret.
...
Errorcode | Exception (SoapFault type) | Fejlbeskrivelse | Forklaring | Automatisk gensendelse mulig | Nyt IndberetningsID ved genindberetning |
---|---|---|---|---|---|
<ingen> | <ingen> | - | Hvis kaldet timer ud, eller andet går galt der gør at svar ikke kommer tilbage fra Elevdatabasen, vil fejlkode typisk være implementationsspecifikke for det enkelte system. Som eksempel kunne dette være en "ConnectionClosed" eller "TimeoutException". | Ja | Nej |
Elevdb-1000 | InternalServerException | Varierer alt efter fejl opstået i Elevdatabasen. Kendte scenarier listet op nedenfor fordelt på operationer: Status: Elevdatabasen kender ikke indberetningsId:
Der forespørges en status på en anden afdeling under hovedinstitutionen end den oprindelige indberetning blev lavet på:
Indberet: Indberetningen er endt i en ugyldig tilstand. Dette sker hvis indberetningen er fejlet under behandlingen af request og der forsøges indberettet igen på samme indberetningsid:
Tilfælde hvor fejlen ikke er kendt eller modeleret:
Nedenstående tilfælde bør ikke opstå, derfor bør disse håndteres straks ved detektering af fejlene.Hvis det ikke er muligt for Elevdatabasen at hente request data ud af databasen som en XML streng og deserialisere denne til Java objekt repræsentationen før validering:
Hvis det ikke er muligt for Elevdatabasen at konvertere Javas objekt repræsentationen af request data om til en XML streng, før data gemmes i databasen:
Hvis Elevdatabasen ikke kan hashe requestet før tjek af duplikat data:
Hvis der er blevet tilføjet en ny fejlkode, men denne ikke bliver håndteret i mapningen til SOAP faults:
| Intern server fejl på Elevdatabasen | Ja | Ja |
Elevdb-1001 | InternalServerException | Ikke defineret | Denne fejl vises, hvis en operation endnu ikke er færdigimplementeret. Fejlen bør aldrig opstå på operationer beskrevet her. Kontakt STIL support hvis denne alligevel opstår. | Nej; Kontakt STIL support | N/A |
Indb-2003 | IndberetningOutOfOrderException | Data er tidligere modtaget med et højere transaktionsId end #transaktionsId | Denne fejl opstår, hvis Elevdatabasen modtager 2 indberetninger på samme elev samtidig. Dette kan kun ske, hvis kravet om håndtering af samtidighed (se afsnittet Integrationsmønstre) ikke overholdes. Kontakt STIL's support, hvis fejlen opstår på trods af en korrekt implementering. | Nej; Der er lavet en implementationsfejl der bør rettes | N/A |
Indb-2004 | InvalidIndberetning | Indberetningen på indberetningsid #IndberetningsId er ugyldig | Data på indberetningen er ugyldig. | Nej; Data skal rettes manuelt | Ja |
Pers-1000 | InternalServerException | Der skete en fejl ved kald til Persondatamodulet | Fejl ved validering af CPR-oplysninger. Selvom dette er en intern fejl der opstår, hvis fx CPR-registeret ikke svarer, så skal der i dette tilfælde genereres et nyt IndberetningsID for at sikre indberetningen håndteres igen. | Ja | Ja |
SoapFaults
Elevdatabasen returnere både Interne fejl, og ugyldig datafejl som SoapFaults. Elevdatabasens Soapfaults er bygget op omkring 2 overordnede elementer:
...
<soap:Detail> - Indeholder en exception og en mere detaljeret beskrivelse af fejlen samt errorcode. I tilfælde af valideringsfejl indeholder den en liste med valideringsfejlkoder og dertilhørende fejlbeskrivelser.
Parametre for SoapFault besked ved interne fejl
Ved interne fejl benyttes følgende format
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
ErrorCode | String | Ingen/Ikke relevant | J | 1 | Fejlkode |
ErrorMessage | String | Ingen/Ikke relevant | J | 1 | Beskrivelse af fejlen |
Parametre for SoapFault besked ved valideringsfejl
Ved valideringsfejl benyttes ved følgende format
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
ErrorCode | String | Ingen/Ikke relevant | J | 1 | Fejlkode |
ErrorMessage | String | Ingen/Ikke relevant | J | 1 | Beskrivelse af fejlen |
Status | Enum | DUPLICATE, FAILED | J | 1 | Status på indberetningen. DUPLICATE angiver, at data tidligere er modtaget på IndberetningsID'et, og behandlet uden fejl. Ingen data er blevet behandlet i dette request, og fejl listet i Indberetningsdetaljer er således fejl fra den tidligere indberetning
|
Indberetningsdetaljer | List<Indberetningsdetalje> | Ingen/Ikke relevant | J | Unbounded | Udspecificeret liste med fejlkoder og beskrivelser |
Indberetningsdetalje
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Fejlkode | String | Ingen/Ikke relevant | J | 1 | Elevdatabasens valideringsfejlkode |
Fejlbeskrivelse | String | Ingen/Ikke relevant | J | 1 | Beskrivelse af valideringsfejlen |
Fault eksempel
Følgende viser et eksempel på en SoapFault ved indberetning af validt request, men hvor der er valideringsfejl.
UI Expand | |||||
---|---|---|---|---|---|
| |||||
|
...
Nedenfor er listet de valideringer, der foretages på Elevdatabasen. Valideringerne er delt op i tre dele: Persondata, Institutionsdata og Uddannelsesdata.
Ved brud på valideringsregler returneres en liste af valideringsfejl som Indberetningsdetaljer i en SoapFault.
Persondata
...
Fejlkode
...
Fejltekst
...
Institutionsdata
...
Afhængig af #Flyttekode.
(#Flyttekode=1): Institution #Institutionsnummer er flyttet til institution #NyInstitutionsnummer.
(#Flyttekode=2): Institution #Institutionsnummer er flyttet til institution #NyInstitutionsnummer.
...
Institutionen #Hovedinstitution er indberettet som en institution uden afdelinger, men institutionen er registreret som en afdeling eller hovedinstitution.
Uddannelsesdata
...
Den indberettede kombination af uddannelseskode, uddannelsesversion, speciale og skoleperioder er ikke gyldig
...
|
Anker Valideringsregler Valideringsregler
Valideringsregler
Valideringsregler | |
Valideringsregler |
Nedenfor er listet de valideringer, der foretages på Elevdatabasen. Valideringerne er delt op i tre dele: Persondata, Institutionsdata og Uddannelsesdata.
Ved brud på valideringsregler returneres en liste af valideringsfejl som Indberetningsdetaljer i en SoapFault.
Persondata
Fejlkode | Fejltekst |
---|---|
Pers-01 | CPR-nummeret #CPRnummer findes ikke i Det Centrale Personregister (CPR) |
Pers-02 | CPR-nummeret #CPRnummer er ikke aktivt i Det Centrale Personregister (CPR) |
Institutionsdata
Fejlkode | Fejltekst |
---|---|
Inst-01 | Institutionsnummeret #Institutionsnummer er ikke aktivt |
Inst-02 | Afhængig af #Flyttekode. (#Flyttekode=1): Institution #Institutionsnummer er flyttet til institution #NyInstitutionsnummer. (#Flyttekode=2): Institution #Institutionsnummer er flyttet til institution #NyInstitutionsnummer. |
Inst-03 | Afdelingen #Afdelingsinstitutionsnummer hører ikke til den hovedinstitution #Hovedinstitutionsnummer der indberettes på. |
Inst-04 | Institutionen #Hovedinstitution er indberettet som en institution uden afdelinger, men institutionen er registreret som en afdeling eller hovedinstitution. |
Uddannelsesdata
Fejlkode | Fejltekst |
---|---|
Udd-01 | Den indberettede kombination af uddannelseskode, uddannelsesversion, speciale og skoleperioder er ikke gyldig |
Udd-02 | Uddannelseskoden #uddannelseskode findes ikke i Uddannelsesmodellen. |
Udd-03 | Versionen #uddannelsesversion findes ikke for uddannelsen #uddannelseskode |
Udd-04 | Skoleperioderne #skoleperioder gælder ikke for uddannelsen #uddannelseskode i version #version. |
Udd-05 | Specialet #specialekode gælder ikke for uddannelsen #uddannelseskode i version #version med skoleperioderne #skoleperioder |
Udd-07 | Tidligste registrering af eleven #TidligsteSkoleperiodeStartdato ligger før startdato for uddannelsen med Uddannelseskoden #Uddannelseskode i version #Version |
Udd-10 | Elevskoleperiodens startdato #elevskoleperiodestart skal være før elevskoleperiodens slutdato #elevskoleperiodeslut |
Udd-12 | Adgangsvejen #adgangsvej er ukendt |
Udd-13 | Adgangsvejen #adgangsvej er ugyldig for skoleperioderne #skoleperioder |
Anker Teknisk beskrivelse af operationer Teknisk beskrivelse af operationer
Teknisk beskrivelse af operationer
Teknisk beskrivelse af operationer | |
Teknisk beskrivelse af operationer |
Dette afsnit beskriver de tekniske detaljer for hver Operation på Elevdatabasens webservice.
Anker Indberet Indberet
Indberet
Indberet | |
Indberet |
Operationen har følgende struktur for request og response:
Parametre for request
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
IndberetElevRequest | IndberetElevRequest | Ingen/Ikke relevant | J | 1 | Request på Indberetning Se beskrivelsen i afsnittet IndberetElevRequest herunder. |
IndberetElevRequest
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
IndberetningsId | GUID | Ingen/Ikke relevant | J | 1 | GUID for indberetning. Id'et genereres af det indberettende system |
IndberetElev | IndberetElev | Ingen/Ikke relevant | J | 1 | Elev der indberettes data på |
IndberetElev
...
Dette afsnit beskriver de tekniske detaljer for hver Operation på Elevdatabasens webservice.
...
Operationen har følgende struktur for request og response:
...
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|
Personoplysninger |
Personoplysninger | Ingen/Ikke relevant | J | 1 |
Se beskrivelsen i afsnittet IndberetElevRequest herunder.
IndberetElevRequest
IndberetningsId
Personoplysninger om eleven | |
Institutionsoplysninger | Institutionsoplysninger |
Ingen/Ikke relevant | J | 1 |
IndberetElev
Oplysninger om institutionen, hvor eleven går | ||||
Uddannelsesoplysninger | Uddannelsesoplysninger | Ingen/Ikke relevant | J | 1 |
Elev der indberettes data på
Oplysninger om uddannelsen eleven er i gang med |
PersonoplysningerIndberetElev
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|
CPRNummer |
String | Længde: 10 |
J | 1 |
Personoplysninger
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
CPRNummer | String | Længde: 10 | J | 1 | CPR-nummer (personnummer) på eleven. Der kan ikke indberettes elever uden CPR-nummer. |
...
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Skoleperiode | String | Ingen/Ikke relevant | J | 1 | Skoleperiode eller trin for elevskoleperioden. |
Startdato | Date | Ingen/Ikke relevant | J | 1 | Startdato for elevskoleperioden |
Slutdato | Date | Ingen/Ikke relevant | N | 1 | Slutdato for elevskoleperioden |
Parametre for response
Felt | Datatype | Begrænsninger | Krævet | Beskrivelse |
---|---|---|---|---|
IndberetElevResponse | IndberetElevResponse | Ingen/Ikke relevant | J | Response på Indberetning. |
...
UI Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
Anker Status Status
Status
Status | |
Status |
Status-operationen er stadig under udarbejdelse, og vi forventer response-strukturen kommer til at matche response-strukturen for Indberet-operationen
Parametre for request
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
StatusRequest | StatusRequest | Ingen/Ikke relevant | J | 1 | Request på status for indberetning. Se beskrivelsen i afsnittet StatusRequest herunder. |
...
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Hovedinstitution | Heltal | Max cifre: 6 | J | 1 | Hovedinstitutionen for den afdeling hvor eleven modtager undervisning |
Afdeling | Heltal | Max cifre: 6 | J | 1 | Institutionsnummeret for afdelingen hvor eleven modtager undervisning Er institutionen en selvstændig institution uden hovedinstitution skal samme institutionsnummer angives i Hovedinstitution og Afdeling. |
Parametre for response
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
StatusResponse | StatusResponse | Ingen/Ikke relevant | J | 1 | Response på status. Se beskrivelsen i afsnittet StatusResponse herunder. |
StatusResponse
...
Kardinalitet | Beskrivelse | ||||
---|---|---|---|---|---|
StatusResponse | StatusResponse | Ingen/Ikke relevant | J | 1 | Response på status. Se beskrivelsen i afsnittet StatusResponse herunder. |
StatusResponse
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Status | Enum | CREATED, RECEIVED, DUPLICATE, PROCESSING, COMPLETE | J | 1 | Status for behandling af indberetningen. Se afsnittet Fejlhåndtering for information om status FAILED. |
Indberetningsdetaljer | List<Indberetningsdetalje> | Ingen/Ikke relevant | N | Unbounded | Udspecificeret liste med fejlkoder og beskrivelser |
Indberetningsdetalje
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Fejlkode | String | Ingen/Ikke relevant | J | 1 | Elevdatabasens valideringsfejlkode |
Fejlbeskrivelse | String | Ingen/Ikke relevant | J | 1 | Beskrivelse af valideringsfejlen |
UI Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
UI Expand | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||
|
Indberetningsdetalje
...
UI Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
UI Expand | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||
|
Ping
Operationen har følgende struktur for request og response
Parametre for request
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
Ping | Ping | Ingen/Ikke relevant | J | 1 | Ping kald til Elevdatabasen |
Parametre for response
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
---|---|---|---|---|---|
PingReponse | PingSvar | Ingen/Ikke relevant | J | 1 | Ping svar fra Elevdatabasen |
Status | String | up, down | J | 1 | Status på ping svar fra Elevdatabasen |
UI Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|
UI Expand | |||||||
---|---|---|---|---|---|---|---|
| |||||||
|