Dokumentoplysninger
Ændringshistorik
Indhold
Indledning
Dette dokument beskriver strukturen for de oplysninger, der skal indberettes til Lærepladsen.dk fra studieadministrative systemer på erhvervsskolernes EUD-uddannelser, herunder EUX, og giver en beskrivelse af webservicen til ' Indberetning af oplysninger om elever og undervisningsenheder' (herefter webservicen).
Indberetning af data fra institutionernes studieadministrative systemer skal foretages via STIL's integrationsplatform (herefter IPL). IPL er udviklet til, at der skal ske en 'system til system'-udveksling. Det betyder i praksis, at institutionens studieadministrative system skal have funktioner til at eksportere data og varetage selve dataudvekslingen.
Institutionens studieadministrative system skal have funktioner til at forsøge gentagelse af overførslen, et nærmere defineret antal gange efter et nærmere defineret tidsrum, såfremt overførslen fejler. Den enkelte institution eller det enkelte studieadministrative system skal dagligt overvåge eventuelle fejlmeldinger fra dataoverførslen og enten selv afhjælpe eventuelle problemer eller indberette dem til leverandøren af det studieadministrative system, der kan indberette disse til STIL's support, hvis det er nødvendigt.
Såfremt en institution skifter administrativt system eller fusionerer, skal dette meddeles til STIL.
Hvem skal indberette?
Alle institutioner som administrerer grundforløb og/eller hovedforløb på erhvervsuddannelsesområdet.
Hvad skal indberettes
Institutionerne skal indberette oplysninger om alle elever og deres elevforhold for elever under CØSA's formålsgruppe 01 (EUD). Indberetningen skal indeholde oplysninger om: person, elevforhold, afgangsårsag, elevtypeperiode, specialeperiode, skoleophold samt kvalifikation til hovedforløb (se bilag 1).
Hvilke personer skal indberetningen omfatte?
Alle nyoprettede eller tidligere indberettede (men ændret siden sidst) oplæringsrelevante personer på institutionen. Oplæringsrelevante personer defineres som personer, der er tilknyttet en uddannelse under CØSA's formålsgruppe 01 (EUD).
Hvornår skal der indberettes?
Der skal indberettes, når der sker ændringer (oprettelser, opdateringer, sletninger) for en person. Hvis en person slettes i det studieadministrative system, skal dette ligeledes indberettes (se '7.8. Slet en indberettet person').
Hvilke oplysninger skal indberettes?
Der skal indberettes et fuldt billede af skolens registreringer på indberetningstidspunktet, dvs.:
- Alle elevernes personoplysninger, elevforhold, elevtypeperioder, specialeperioder, skoleophold, kvalifikationer og elevdeltagelse.
- Ved elever, der deles mellem flere institutioner, er det kun den institution, der ejer eleven (dvs. som får tilskud for eleven), der skal indberette elevens skoleophold.
- Ved elever, der udlånes, er det kun den institution, eleven er udlånt til, der skal indberette elevens skoleophold.
Objekttyper
Nedenfor er objekttyperne for webservicen bekrevet. For obligatoriske felter underforstås også, at feltet ikke må være tomt eller kun indeholde blanktegn
Person
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
cpr | Personens CPR-nummer uden adskillelsestegn. | Tekst | Præcist 10 tegn. | Ja | Ja |
navn | Personens navn. | Tekst | Højst 200 tegn. | Ja | Nej |
foedselsdag | Personens fødselsdag. | Dato | Skal overholde formatet YYYY-MM-DD | Ja | Nej |
elevforhold | Liste over elevforhold. | Liste af Elevforhold | Nej | Nej |
Elevforhold
Et elevforhold defineres ud fra kombinationen person, uddannelse og uddannelsesinstitution.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
---|---|---|---|---|---|
uddannelsesinstitution | Uddannelsesansvarlige hovedinstitution som angivet i Institutionsregisteret. | Tekst | Skal findes i Institutionsregisteret. | Ja | Nej |
coesaFormaal | Identifikation af CØSA-formål. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO i formålsgruppe 1. | Ja | Ja |
startdato | Første dato på skoleophold, oplæringsperiode eller aftale. | Dato | Skal overholde formatet YYYY-MM-DD. Der må ikke være tidsmæssigt overlap mellem elevforhold på samme CØSA-formål. | Ja | Ja |
slutdato | Sidste dato på skoleophold, oplæringsperiode eller aftale. | Dato | Skal overholde formatet YYYY-MM-DD. Der må ikke være tidsmæssigt overlap mellem elevforhold på samme CØSA-formål. | Nej | Nej |
afgangsaarsager | Afgangsårsager. Der skal kun indberettes afgangsårsager for eleven, hvis der er en hændelse. | Liste af Afgangsaarsag | Nej | Nej | |
elevtypeperioder | Periodeangivelser af, hvornår elevtyper er eller har været gældende. | Liste af Elevtypeperiode | Nej | Nej | |
kvalifikationerTilHovedforloeb | Elevens kvalifikationer til hovedforløb. | Liste af KvalifikationTilHovedforloeb | Nej | Nej | |
skoleophold | Elevens skoleophold. | Liste af Skoleophold | Nej | Nej | |
specialeperioder | Periodeangivelser af, hvornår specialer er eller har været gældende. | Liste af Specialeperiode | Nej | Nej |
Afgangsaarsag
Den centralt udmeldte afgangsårsag, som eleven evt. er registreret med i det studieadministrative system. Der skal IKKE tages hensyn til, om der i CØSA er anført, om afgangsårsagen skal indberettes. Alle afgangsårsager skal indberettes. Der skal kun indberettes afgangsårsager for eleven, hvis der er en hændelse.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
afgangsaarsag | Identifikation af afgangsårsag. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO. | Ja | Nej |
dato | Dato for hændelsen.Nøglefelt. | Dato | Dato for hændelsen.Nøglefelt. | Ja | Ja |
Elevtypeperiode
I tabellen indberettes elevtyper på eleven. Der må ikke være tidsmæssigt overlappende perioder for den enkelte elev.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
elevtype | Identifikation af elevtypen. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO for elevforholdets CØSA-formål og elevtypeperiodens uddannelsesversion. | Ja | Ja |
uddannelseVersion | Nummer, der identificerer uddannelsesversionen. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Heltal | Skal findes i UMO for elevforholdets CØSA-formål. | Ja | Ja |
startdato | Startdato for elevtypen på eleven. | Dato | Der må ikke være tidsmæssigt overlap mellem elevtypeperioder på elevforholdet. | Ja | Ja |
slutdato | Slutdato for elevtypen på eleven. | Dato | Der må ikke være tidsmæssigt overlap mellem elevtypeperioder på elevforholdet. | Nej | Nej |
Specialeperiode
Information om et speciale med periodeangivelse.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
---|---|---|---|---|---|
speciale | Identifikation af specialet. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO for elevforholdets CØSA-formål og specialeperiodens uddannelsesversion. | Ja | Ja |
uddannelseVersion | Nummer, der identificerer uddannelsesversionen. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Heltal | Skal findes i UMO for elevforholdets CØSA-formål. | Ja | Ja |
startdato | Startdato for specialet på eleven. | Dato | Skal overholde formatet YYYY-MM-DD. | Ja | Ja |
slutdato | Slutdato for specialet på eleven. | Dato | Skal overholde formatet YYYY-MM-DD. | Ja | Nej |
Skoleophold
Bemærk, at der skal angives et unik id for at sikre mod dubletter ved overlappende datoer.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
id | Fast og entydig identifikation af skoleopholdet. | Tekst | Skal være unik for indberetningen.Højst 50 tegn. | Ja | Ja |
uddannelseVersion | Nummer, der identificerer uddannelsesversionen. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Heltal | Skal findes i UMO for elevforholdets CØSA-formål. | Ja | Nej |
speciale | Identifikation af specialet. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO for elevforholdets CØSA-formål og skoleopholdets uddannelsesversion. | Nej | Nej |
skoleperiode | Identifikation af skoleperioden. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO for elevforholdets CØSA-formål og skoleopholdets uddannelsesversion samt skoleopholdes speciale eller, hvis denne ikke er angivet, uden speciale. | Ja | Nej |
undervisningssted | Institutionsnummer på afdeling, hvor undervisningen foregår. | Tekst | Skal findes i Institutionsregisteret. | Ja | Nej |
startdato | Elevens startdato for skoleopholdet, dvs. elevens første dag. | Dato | Skal overholde formatet YYYY-MM-DD. | Ja | Nej |
slutdato | Elevens slutdato for skoleopholdet, dvs. elevens sidste dag på skoleopholdet. | Dato | Skal overholde formatet YYYY-MM-DD. | Ja | Nej |
KvalifikationTilHovedforloeb
Alle elevens kvalifikationer til hovedforløb, som er opnået på den indberettende institution, skal indberettes.
Såfremt eleven har kvalificeret sig til alle specialer under uddannelsen, indberettes der kun én kvalifikation på uddannelsen uden angivelse af speciale.
Såfremt eleven kun har kvalificeret sig til nogle af specialerne under uddannelsen, indberettes der en kvalifikation pr. speciale, som eleven har kvalificeret sig til.
Felt | Beskrivelse | Type | Lovlige værdier | Obligatorisk | Nøglefelt |
id | Fast og entydig identifikation af kvalifikationen. | Tekst | Skal være unik for indberetningen. Højst 50 tegn. | Ja | Ja |
coesaFormaal | Identifikation af CØSA-formål. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Tekst | Skal findes i UMO i formålsgruppe 1. | Ja | Nej |
uddannelseVersion | Nummer, der identificerer uddannelsesversionen. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). | Heltal | Skal findes i UMO for kvalifikationens CØSA-formål. | Ja | Nej |
speciale | Identifikation af specialet. Yderligere oplysninger kan hentes fra Uddannelsesmodellen (UMO). Hvis det ikke angives gælder kvalifikationen for alle specialer i uddannelsesversionen. | Tekst | Skal findes i UMO for kvalifikationens CØSA-formål og uddannelsesversion. | Nej | Nej |
opnaaelsesdato | Dato for opnåelse af kvalifikation. | Dato | Skal overholde formatet YYYY-MM-DD. | Ja | Nej |
Slet en indberettet person
Benyttes udelukkende ved fejlindberetning og ved skift af CPR-nummer for at fjerne den gamle nøgle. Ved udmeldelse af institutionen anvendes indberetning af afgangsårsag i stedet.
Felt | Beskrivelse | Type | Obligatorisk |
cpr | Personens CPR-nummer uden adskillelsestegn. | Tekst | Ja |
institution | Den indberettende institutions 6-cifrede institutionsnummer, jf. Institutionsregisteret. | Tekst | Ja |
system | Navn på det administrative system, der indberetter data. | Tekst | Ja |
Fejlhåndtering
SoapFaults
Lærepladsens API returnerer både interne fejl og datafejl som SoapFaults. I tilfælde af valideringsfejl indeholder fejlbeskeden en liste af valideringsfejl og dertilhørende fejlbe-skrivelser indeholdt i elementet ServiceFaultDetailerV2.
Parametre for ServiceFaultDetailerV2 besked ved Lærepladsen.dk's fejlbeskeder
Ved valideringsfejl benyttes følgende format:
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
ServiceFaultDetailerV2 | ServiceFaultDetailerV2 | Ingen/Ikke relevant | J | 1 | Element, der rummer felterne med detaljer vedrørende fejlen |
ServicefaultDetailerV2
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
CorrelationID | string | Ingen/Ikke relevant | J | 1 | Unik ID der genereres af Integrationsplatformen. Skal medsendes i supportsager. |
Timestamp | dateTime | Ingen/Ikke relevant | J | 1 | Tidspunkt for svar |
ErrorCode | string | Ingen/Ikke relevant | J | 1 | IPL fejlkode |
ErrorMessage | string | Ingen/Ikke relevant | J | 1 | IPL fejlbeskrivelse |
Details | string | Ingen/Ikke relevant | N | 1 | Overordnet beskrivelse af fejlen |
SourceSystemError | SourceSystemError | Ingen/Ikke relevant | N | 1 | Element, der rummer felterne med detajler vedrørende fejlen fra Lærepladsen.dk |
SourceSystemError
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
SourceSystemName | string | Ingen/Ikke relevant | J | 1 | System der sender fejlsbeskeden via Integrationsplatformen. Dette vil ved brug af Lærepladsens services altid være Lærepladsen. |
ErrorCode | string | Ingen/Ikke relevant | J | 1 | Overordnet fejlkode |
DetailsList | DetailsList | Ingen/Ikke relevant | N | 1 | Liste, der rummer valideringsfejlene |
DetailsList
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
Detail | Detail | Ingen/Ikke relevant | N | Unbounded | Element, der indeholder de enkelte fejl |
Detail
Felt | Datatype | Begrænsninger | Krævet | Kardinalitet | Beskrivelse |
Code | string | Ingen/Ikke relevant | N | 1 | Lærepladsen.dk’s valideringsfejlkode |
Description | string | Ingen/Ikke relevant | N | 1 | Lærepladsen.dk’s fejlbeskrivelse |
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">Input er ikke gyldigt jf. specifikation.</soap:Text> </soap:Reason> <soap:Detail> <ServiceFaultDetailerV2 xmlns:ns2="http://stil.dk/praktikpladsen/indberetelevoplysninger/v1.0" xmlns="http://ipl.stil.dk/services/praktikpladsen/indberetelevoplysninger/v1.0"> <CorrelationID>1b7fcc4f-7137-48d3-85c7-ab021f3d7f49</CorrelationID> <Timestamp>2022-08-25T09:24:09</Timestamp> <ErrorCode>IPL141001</ErrorCode> <ErrorMessage>Input error</ErrorMessage> <SourceSystemError> <SourceSystemName>Praktikpladsen-IndberetElevoplysninger</SourceSystemName> <ErrorCode>S-1000</ErrorCode> <DetailsList> <Detail> <Code>institutionsnummer-eksisterer-ikke</Code> <Description>institution skal findes i Institutionsregisteret : 961850</Description> </Detail> <Detail> <Code>nøgle-under-elevforhold-ikke-unik</Code> <Description>requestBody.elevforhold[0].elevtypeperioder[0] skal have en unik nøgle (elevtype + uddannelseVersion + startdato) blandt elevtypeperioder inden for elevforholdet : Elevtypeperiode.Key{elevtype='EU9+G', uddannelseVersion=10, startdato=2020-02-01}</Description> </Detail> <Detail> <Code>nøgle-under-elevforhold-ikke-unik</Code> <Description>requestBody.elevforhold[0].elevtypeperioder[1] skal have en unik nøgle (elevtype + uddannelseVersion + startdato) blandt elevtypeperioder inden for elevforholdet : Elevtypeperiode.Key{elevtype='EU9+G', uddannelseVersion=10, startdato=2020-02-01}</Description> </Detail> <Detail> <Code>institutionsnummer-eksisterer-ikke</Code> <Description>requestBody.elevforhold[0].uddannelsesinstitution skal findes i Institutionsregisteret : 961850</Description> </Detail> </DetailsList> </SourceSystemError> </ServiceFaultDetailerV2> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope> |
Følgende viser et eksempel på en SoapFault ved indberetning af request, hvor der er interne fejl:
<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="http://ipl.stil.dk/services/praktikpladsen/indberetelevoplysninger/v1.0"> <CorrelationID>e0b49fcd-5311-4dc0-bfc6-cd7c36f02c6f</CorrelationID> <Timestamp>2022-08-25T09:41:10.029</Timestamp> <ErrorCode>IPL100001</ErrorCode> <ErrorMessage>An internal server error occurred on the source service.</ErrorMessage> <SourceSystemError> <SourceSystemName>Praktikpladsen-IndberetElevoplysninger</SourceSystemName> <ErrorCode>S-1000</ErrorCode> </SourceSystemError> </ServiceFaultDetailerV2> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope> |
Følgende viser et eksempel på en SoapFault ved indberetning af request, der overtræder skemadefinitionen:
<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="http://ipl.stil.dk/services/praktikpladsen/indberetelevoplysninger/v1.0"> <CorrelationID>3422a89b-34bc-43a6-8647-2e7d8d2953ff</CorrelationID> <Timestamp>2022-08-29T11:09:04.511</Timestamp> <ErrorCode>IPL000002</ErrorCode> <ErrorMessage>The request is invalid according to the schema definition. Check details for further information</ErrorMessage> <Details>Validation failed for: com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchema@591f7993 errors: [ org.xml.sax.SAXParseException: cvc-maxLength-valid: Value '11223344556' with length = '11' is not facet-valid with respect to maxLength '10' for type '#AnonType_cprPerson'., Line : 10, Column : 46 org.xml.sax.SAXParseException: cvc-type.3.1.3: The value '11223344556' of element 'v11:cpr' is not valid., Line : 10, Column : 46 ]. Exchange[ID-praktikpladsen-indberetelevoplysninger-f55c5c8c4-x2tz7-1659196337029-0-190]</Details> </ServiceFaultDetailerV2> </soap:Detail> </soap:Fault> </soap:Body> </soap:Envelope> |
Eksempel på svar ved succes
Følgende viser et eksempel på indberetning af request, hvor der ikke er nogen fejl:
<soap: Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body> <IndberetElevoplysningerResponse xmlns="http://ipl.stil.dk/services/praktikpladsen/indberetelevoplysninger/v1.0"> <Identifier> <SystemName>DLS</SystemName> <SystemTransactionID>foo</SystemTransactionID> </Identifier> <CorrelationID>11092e9f-125c-407c-93f4-02a880f74f9c</CorrelationID> </IndberetElevoplysningerResponse> </soap:Body> </soap:Envelope> |
Valideringsregler
Nedenfor er listet de valideringer, der foretages på Lærepladsen.dk. Valideringerne er delt op i tre dele: Institutionsdata, Uddannelsesdata og Indberetningsdata
Ved brud på valideringsregler returneres en liste af valideringsfejl som Indberetningsdetaljer i en SoapFault.
Institutionsdata
Fejlkode | Fejltekst |
institutionsnummer-eksisterer-ikke | skal findes i Institutionsregisteret |
Uddannelsesdata
Fejlkode | Fejltekst |
umo-afgangsårsag-eksisterer-ikke | skal findes i Uddannelsesmodellen |
umo-cøsa-formål-eksisterer-ikke | skal findes i Uddannelsesmodellen i formålsgruppe 1 |
umo-elevtype-eksisterer-ikke | skal findes i Uddannelsesmodellen for CØSA-formål {coesaFormaal} og uddannelsesversion {uddannelseVersion} |
umo-skoleperiode-eksisterer-ikke | skal findes i Uddannelsesmodellen for CØSA-formål {coesaFormaal}, uddannelsesversion {uddannelseVersion} og speciale {speciale} |
umo-speciale-eksisterer-ikke | skal findes i Uddannelsesmodellen for CØSA-formål {coesaFormaal} og uddannelsesversion {uddannelseVersion} |
umo-uddannelsesversion-eksisterer-ikke | skal findes i Uddannelsesmodellen for CØSA-formål {coesaFormaal} |
Datakonsistens
nøgle-under-elevforhold-ikke-unik | skal have en unik nøgle ({noeglefelter}) blandt {elevforholdFelt} inden for elevforholdet |
elevforhold-nøgle-ikke-unik | skal have en unik nøgle (coesaFormaal) blandt elevforhold inden for indberetningen |
perioder-overlapper | må ikke overlappe andre {elevforholdFelt} i forhold til startdato og slutdato |
slutdato-ikke-lig-eller-efter-startdato | skal være samme som eller efter startdato {startdato} |
id-ikke-unik | skal være unik for indberetningen |
Indberetningsdata
Fejlkode | Fejltekst |
system-ukendt | skal være registreret hos STIL |
Webservicen
Webservicen kaldes via STIL's integrationsplatform IPL.
IPL er en integrationsplatform, som understøtter udveksling af data mellem STIL's centrale systemer og eksterne systemer. IPL anvendes af uddannelsesinstitutioner, myndigheder og organisationer på førskole-, grundskole-, ungdomsuddannelses-, voksen- og efteruddannelsesområdet. Platformen tilbyder ensartede webservices for indberetning til og hentning af data fra STIL's centrale systemer, inkl. autentificering, autorisering og logning af hændelser i forbindelse med dataudvekslingen. IPL er et ren infrastrukturkomponent og har ingen brugergrænseflade, ligesom den ikke opbevarer data.
Platformen understøtter, at systemleverandører, blandt andet leverandører af studieadministrative systemer på de ovennævnte uddannelsesområder, kan udveksle data med STIL's systemer, på en institutions vegne, på en ensartet, transparent og sikker måde.
Yderligere oplysninger om tilslutning og tekniske detaljer kan findes på STIL's support-site: https://viden.stil.dk/display/OFFintegrationsplatformen.
Endpoints til webservicen findes her: https://viden.stil.dk/display/OFFintegrationsplatformen/Services.
Bilag 1 Indberetningsstruktur