Dokumenthistorik

Indhold

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) ressortområde. De konkrete grunddata omfatter oplysninger om elevers tilknytning til institutioner og uddannelser, herunder trin, start- og slutdatoer mv. De overordnede dataområder, Elevdatabasen opererer med, er persondata, institutionsdata og uddannelsesdata.

I dag indhenter en række fagsystemer i STIL helt eller delvist egne elevdata. Hertil kommer også månedlige og kvartalsvise statistikindberetninger til Datavarehuset. Elevdatabasen vil minimere antallet af indberetningsprocesser fra institutionerne til STIL's systemer, således indberetningen af grunddata om elever fremover kun sker til ét sted. Dette skal medvirke til at STIL's fagsystemer fremover trækker elevdata fra Elevdatabasen. Den skal således udgøre et fælles datagrundlag for elevdata, som understøtter datakvalitet og de administrative og statistiske opgaver på tværs af STIL. Det er derfor nødvendigt, at Elevdatabasen leverer et højaktuelt billede af hvilke elever, som går på hvilke uddannelser. Dette sikres gennem højfrekvente indberetninger af elevdata fra uddannelsesinstitutionerne.

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 de eksterne systemer i sektoren. 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

Denne sektion beskriver i overordnede træk de tre dataområder i Elevdatabasen, der tilsammen udgør grunddata om elever, og mod hvilke kilder denne data valideres.

Elevdatabasens dataområder:

• Persondata - Indeholder elevens personnummer. Data valideres mod Det Centrale Personregister (CPR)
  
• Institutionsdata - Indeholder hovedinstitution og afdeling for den indberettende institution. Data valideres mod Institutionsregisteret
  
• Uddannelsesdata - Data om den uddannelse, eleven går på - eksempelvis uddannelseskode, uddannelsesversion, skoleperioder, mv. Data valideres mod Uddannelsesmodellen

For en detaljeret gennemgang af de enkelte valideringer, se afsnittet om Valideringsregler.

Håndtering af indberetninger, der ikke overholder valideringsreglerne, beskrives i afsnittet Fejlhåndtering.

Grundlæggende principper for indberetning

1. En indberetning skal indeholde gældende data for en elev.
2. En indberetning skal indeholde historisk data for eleven for den pågældende uddannelse og institution.
   
3. Ved ændringer til data på eleven, skal indberetning ske senest dagen efter at ændringen er trådt i kraft.
4. En indberetning må ikke indeholde forventede fremtidige ændringer

Omfattede uddannelser

Grundskole

Alle elever, der går på en grundskoleuddannelse, skal indberettes til Elevdatabasen, herunder folkeskoler, fri- og privatskoler, efterskoler mv.

Gymnasieområdet

Alle elever, der går på en gymnasieuddannelse under formålsgruppe 2 eller 33 i Uddannelsesmodellen, skal indberettes til Elevdatabasen.

Brobygningselever og prøvedeltagere skal ikke indberettes.

Integrationsmønstre

Denne sektion beskriver de krav som 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.
Det er tilladt at indberette parallelt, så længe det samlede antal requests holdes under denne grænse og kravet om indberetning på samme CPR-nummer (Håndtering af samtidighed) overholdes.
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.

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 blive overhalet, og dermed bliver data i Elevdatabasen forskellig fra den faktiske data i SA-systemet.
Rækkefølgen af indberetninger bliver først gjort endelig idet beskeden modtages af Elevdatabasen, og det er derfor ikke tilladt at indberette 2 ændringer på samme CPR-nummer i parallel.
Alle indberetninger på samme CPR-nummer skal således ske sekventielt - dvs. at næste indberetning først sendes, når svar er modtaget fra Elevdatabasen på den sidste indberetning for det pågældende CPR-nummer.
Ønsker man at parallelisere indberetningerne, er det derfor vigtigt at paralleliseringen sker grupperet på CPR-nummer.

Håndtering af udfald i netværk og infrastruktur

Alle indberetninger skal påsættes et IndberetningsId af typen UUID for at undgå dobbeltindberetninger ved fejl i netværk eller anden infrastruktur.
Hvis der ikke modtages et svar på en indberetning - f.eks. fordi svaret er gået tabt i netværket eller forbindelsen lukkes inden processeringen er færdig, forventes det at SA-systemet gensender den samme besked med samme IndberetningsId.
Hvis beskeden faktisk er behandlet korrekt ved første indberetning, vil svaret på gensendelsen af beskeden have status DUPLICATE. Var der valideringsfejl på den tidligere indberetning vil denne blive returneret som en SoapFault (se afsnittet SoapFaults for flere detajler).

IndberetningsId'et kan bruges til at tjekke status på en indberetning med Status-operationen. Se afsnittet Operationer for flere detaljer.

Se tabellen i afsnittet Fejlhåndtering for yderligere detaljer om hvornår SA-systemet forventes at gensende en indberetning på et IndberetningsId.

Webservice

Denne sektion beskriver webservicen til indberetning.

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 til services og dataadgange mellem institutioner og systemleverandører.

For at kunne indberette til Elevdatabasen er det påkrævet, at der er indgået en aftale om udveksling af data (dataadgang) mellem det studieadministrative system og den konkrete uddannelsesinstitution via Tilslutning. Dataadgangen skal oprettes på hovedinstitutionen, hvis der skal indberettes for en afdeling under en hovedinstitution.

Operationer

Der findes 4 operationer i Elevdatabasens indberetningswebservice.

De tekniske detaljer og eksempler på request/response kan findes i afsnittet Teknisk beskrivelse af operationer.

Indberet

Indberetning af data til Elevdatabasen sker med operationen Indberet for én elev af gangen.

Elevdatabasen returnerer en status for hver indberetning som angiver, om indberetningen er gået godt eller er fejlet. Alle fejl kastes som en SoapFault og er således ikke en del af Response-objektet. SoapFault indeholder fejlkoder og fejlbeskrivelser, som angiver, hvad der er galt. Se afsnittet Fejlhåndtering for en detaljeret beskrivelse om håndtering af disse fejl.

Status

Anvendes til at hente 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 operationen kan benyttes ved tvivl om hvorvidt en indberetning er gået godt.

Slet

Anvendes til at slette alle indberetninger for en elev på en institution. Operationen er udelukkende tiltænkt situationer hvor der er indberettet elevdata på et forkert personnummer eller en forkert uddannelse. I situationer hvor der er indberettet forkerte data om en elevs skoleperioder, laves der en ny almindelig indberetning med elevens korrekte skoleperioder og data på institutionen.

Ping

Anvendes til at pinge Elevdatabasen og angiver om Elevdatabasen kan modtage indberetninger.

Fejlhåndtering

Elevdatabasen opererer med 3 typer af fejlkoder, Elevdb-XXXX, Indb-XXXX og Pers-XXXX. Elevdb-XXXX dækker over interne fejl på Elevdatabasen. Indb-XXXX dækker over fejl i indberetningen fra de studieadministrative systemer til Elevdatabasen. Pers-XXXX dækker over fejl ved valideringen af personoplysninger mod CPR.

Tabellen nedenfor indeholder en oversigt over de enkelte fejlkoder og information om, hvordan disse fejl skal håndteres.

SoapFaults

Elevdatabasen returnerer både tekniske fejl og datafejl som SoapFaults. Elevdatabasens SoapFaults er bygget op omkring 2 overordnede elementer:

<soap:Reason> - Indeholder en overordnet beskrivelse af den pågældende fejl.

<soap:Detail> - Indeholder en mere detaljeret beskrivelse af fejlen (ErrorMessage) samt ErrorCode. I tilfælde af valideringsfejl indeholder fejlbeskeden en liste af valideringsfejlkoder og dertilhørende fejlbeskrivelser.

Parametre for SoapFault-besked ved interne fejl

Ved tekniske fejl benyttes følgende format

Parametre for SoapFault-besked ved valideringsfejl

Ved valideringsfejl benyttes ved følgende format

Indberetningsdetalje

Fault eksempel

Følgende viser et eksempel på en SoapFault ved indberetning af request hvor der er valideringsfejl.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <soap:Fault>
         <soap:Code>
            <soap:Value>soap:Sender</soap:Value>
         </soap:Code>
         <soap:Reason>
            <soap:Text xml:lang="en">Indberetningen på indberetningsid 7622c460-51cc-4d73-ad1d-6b72f761b8a8 er ugyldig</soap:Text>
         </soap:Reason>
         <soap:Detail>
            <InvalidIndberetning xmlns="http://service.elevdatabasen.stil.dk/">
               <ErrorCode>Indb-2004</ErrorCode>
               <ErrorMessage>Data på indberetningen er ugyldig.</ErrorMessage>
               <Status>FAILED</Status>
               <Indberetningsdetaljer>
                  <Indberetningsdetalje>
                     <Fejlkode>Udd-01</Fejlkode>
                     <Fejlbeskrivelse>Den indberettede kombination af uddannelseskode, uddannelsesversion, speciale og skoleperioder er ikke gyldig</Fejlbeskrivelse>
                  </Indberetningsdetalje>
                  <Indberetningsdetalje>
                     <Fejlkode>Udd-02</Fejlkode>
                     <Fejlbeskrivelse>Uddannelseskoden 1234 findes ikke i Uddannelsesmodellen</Fejlbeskrivelse>
                  </Indberetningsdetalje>
                  <Indberetningsdetalje>
                     <Fejlkode>Udd-03</Fejlkode>
                     <Fejlbeskrivelse>Versionen 2 findes ikke for uddannelsen 1234</Fejlbeskrivelse>
                  </Indberetningsdetalje>
                  <Indberetningsdetalje>
                     <Fejlkode>Udd-04</Fejlkode>
                     <Fejlbeskrivelse>Skoleperioden 1 gælder ikke for uddannelsen 1234 i version 2</Fejlbeskrivelse>
                  </Indberetningsdetalje>
               </Indberetningsdetaljer>
            </InvalidIndberetning>
         </soap:Detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

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

Institutionsdata

Uddannelsesdata

Teknisk beskrivelse af operationer

Dette afsnit beskriver de tekniske detaljer for hver operation på Elevdatabasens webservice.

Indberet

Operationen har følgende struktur for request og response:

Parametre for request

IndberetElevRequest

IndberetElev

Personoplysninger

Institutionsoplysninger

Uddannelsesoplysninger

Elevskoleperiode

Parametre for response

IndberetElevResponse

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:v1="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0" xmlns:ser="http://service.elevdatabasen.stil.dk/">
   <soap:Header/>
   <soap:Body>
      <v1:IndberetElevRequest>
         <v1:Identifier>
            <v1:SystemName>TESTSYSTEM</v1:SystemName>
            <v1:SystemTransactionID>123456789</v1:SystemTransactionID>
         </v1:Identifier>
         <v1:Message>
            <ser:IndberetElevRequest>
               <ser:IndberetningsId>32ed0545-b6a0-4e91-bf7b-0fc0dff8ef73</ser:IndberetningsId>
               <ser:IndberetElev>
                  <ser:Personoplysninger>
                     <ser:CPRNummer>0101011231</ser:CPRNummer>
                  </ser:Personoplysninger>
                  <ser:Institutionsoplysninger>
                     <ser:Hovedinstitution>961851</ser:Hovedinstitution>
                     <ser:Afdeling>961851</ser:Afdeling>
                  </ser:Institutionsoplysninger>
                  <ser:Uddannelsesoplysninger>
                     <ser:Uddannelseskode>3017</ser:Uddannelseskode>
                     <ser:Elevskoleperioder>
                        <ser:Elevskoleperiode>
                           <ser:Skoleperiode>2</ser:Skoleperiode>
                           <ser:Startdato>2021-08-01</ser:Startdato>
                           <ser:Uddannelsesversion>1</ser:Uddannelsesversion>
                           <ser:Speciale>3</ser:Speciale>
                           <ser:Adgangsvej>TD</ser:Adgangsvej>
                           <ser:Klassebetegnelse>2020TD</ser:Klassebetegnelse>
                        </ser:Elevskoleperiode>
                        <ser:Elevskoleperiode>
                           <ser:Skoleperiode>1</ser:Skoleperiode>
                           <ser:Startdato>2020-08-01</ser:Startdato>
                           <ser:Slutdato>2021-06-22</ser:Slutdato>
                           <ser:Uddannelsesversion>1</ser:Uddannelsesversion>
                           <ser:Speciale>3</ser:Speciale>
                           <ser:Adgangsvej>TD</ser:Adgangsvej>
                           <ser:Klassebetegnelse>2020TD</ser:Klassebetegnelse>
                        </ser:Elevskoleperiode>
                     </ser:Elevskoleperioder>
                  </ser:Uddannelsesoplysninger>
               </ser:IndberetElev>
            </ser:IndberetElevRequest>
         </v1:Message>
      </v1:IndberetElevRequest>
   </soap:Body>
</soap:Envelope>

<IndberetElevResponse xmlns="http://service.elevdatabasen.stil.dk/">
	<Status>COMPLETE</Status>
</IndberetElevResponse>

Status

Status-operationen er stadig under udarbejdelse, og vi forventer at response-strukturen kommer til at matche Indberet-operationen

Parametre for request

StatusRequest

Institutionsoplysninger

Parametre for response

StatusResponse

Indberetningsdetalje

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:v1="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0" xmlns:ser="http://service.elevdatabasen.stil.dk/">
   <soap:Header/>
   <soap:Body>
      <v1:StatusRequest>
         <v1:Identifier>
            <v1:SystemName>TESTSYSTEM</v1:SystemName>
            <v1:SystemTransactionID>123456789</v1:SystemTransactionID>
         </v1:Identifier>
         <v1:Message>
            <ser:StatusRequest>
               <ser:Institutionsoplysninger>
                  <ser:Hovedinstitution>961851</ser:Hovedinstitution>
                  <ser:Afdeling>961851</ser:Afdeling>
               </ser:Institutionsoplysninger>
               <ser:IndberetningsId>32ed0545-b6a0-4e91-bf7b-0fc0dff8ef73</ser:IndberetningsId>
            </ser:StatusRequest>
         </v1:Message>
      </v1:StatusRequest>
   </soap:Body>
</soap:Envelope>

<StatusResponse xmlns="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0">
    <Status>COMPLETE</Status>
</StatusResponse>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <soap:Fault>
         <soap:Code>
            <soap:Value>soap:Sender</soap:Value>
         </soap:Code>
         <soap:Reason>
            <soap:Text xml:lang="en">Input error</soap:Text>
         </soap:Reason>
         <soap:Detail>
            <ServiceFaultDetailerV2 xmlns:ns2="http://service.elevdatabasen.stil.dk/" xmlns="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0">
               <CorrelationID>9718cb0b-6072-45ce-9656-a0799f99a5de</CorrelationID>
               <Timestamp>2022-06-13T11:01:37</Timestamp>
               <ErrorCode>IPL171003</ErrorCode>
               <ErrorMessage>Indberetning is invalid</ErrorMessage>
               <Details>Indberetningen på indberetningsid 32ed0545-b6a0-4e91-bf7b-0fc0dff8ef73 er ugyldig</Details>
               <SourceSystemError>
                  <SourceSystemName>Elevdatabasen</SourceSystemName>
                  <ErrorCode>Indb-2004</ErrorCode>
                  <DetailsList>
                     <Detail>
                        <Code>Inst-04</Code>
                        <Description>Hovedinstitutionen 961851 er registreret som en hovedinstitution med afdelinger</Description>
                     </Detail>
                  </DetailsList>
               </SourceSystemError>
            </ServiceFaultDetailerV2>
         </soap:Detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Slet

Denne operation benyttes kun hvis der er indberettet data på et forkert CPR-nummer eller en forkert uddannelse.

Operationen har følgende struktur for request og response:

Parametre for request

SletRequest

Parametre for response

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:v1="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0" xmlns:ser="http://service.elevdatabasen.stil.dk/">
   <soap:Header/>
   <soap:Body>
      <v1:SletRequest>
         <v1:Identifier>
            <v1:SystemName>TESTSYSTEM</v1:SystemName>
            <v1:SystemTransactionID>123456789</v1:SystemTransactionID>
         </v1:Identifier>
         <v1:Message>
            <ser:SletRequest>
               <ser:CPRNummer>0101011231</ser:CPRNummer>
               <ser:Hovedinstitution>961851</ser:Hovedinstitution>
               <ser:Afdeling>961851</ser:Afdeling>
               <ser:Uddannelseskode>3017</ser:Uddannelseskode>
            </ser:SletRequest>
         </v1:Message>
      </v1:SletRequest>
   </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <soap:Fault>
         <soap:Code>
            <soap:Value>soap:Receiver</soap:Value>
         </soap:Code>
         <soap:Reason>
            <soap:Text xml:lang="en">Internal error</soap:Text>
         </soap:Reason>
         <soap:Detail>
            <ServiceFaultDetailerV2 xmlns:ns2="http://service.elevdatabasen.stil.dk/" xmlns="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0">
               <CorrelationID>4422fe65-0b42-451b-b942-f54df0ab95ac</CorrelationID>
               <Timestamp>2022-06-13T11:02:52</Timestamp>
               <ErrorCode>IPL171001</ErrorCode>
               <ErrorMessage>An internal server error occurred on the source service</ErrorMessage>
               <Details>Slette funktion ikke implementeret</Details>
               <SourceSystemError>
                  <SourceSystemName>Elevdatabasen</SourceSystemName>
                  <ErrorCode>Elevdb-1001</ErrorCode>
                  <Details>Ikke implementeret</Details>
               </SourceSystemError>
            </ServiceFaultDetailerV2>
         </soap:Detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Ping

Operationen har følgende struktur for request og response

Parametre for request

Parametre for response

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:v1="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0">
   <soap:Header/>
   <soap:Body>
      <v1:Ping/>
   </soap:Body>
</soap:Envelope>

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Body>
      <PingResponse xmlns="http://ipl.stil.dk/services/elevdatabasen/indberetning/v1.0">
         <Status>up</Status>
      </PingResponse>
   </soap:Body>
</soap:Envelope>