Fra FSWS-Alumni til FS GraphQL API
⚠ Denne tjenesten avvikles etter 31. mars 2027. Nye integrasjoner bør bygges direkte på FS GraphQL API. Se Sikts avviklingspraksis og avviklingsloggen. Kilde: Teknisk dokumentasjon for FSWS-Alumni
FSWS-Alumni har ett endepunkt, <dataporten-url>/data, som returnerer ett AlumniPerson-objekt for den innloggede brukeren:
- Persondata (navn, e-post, telefon, adresse)
- Aktive studier med studieprogram-, studieretnings- og kullinformasjon
- Oppnådde kvalifikasjoner (grader)
Denne guiden hjelper deg migrere fra FSWS-Alumni til FS GraphQL API. Listen med eksempler under er ikke komplett. Ta kontakt med fs-support@sikt.no dersom du trenger hjelp til å finne en spørring som passer ditt behov.
Før du starter
Sett deg inn i disse tingene før du går videre:
- Tilgang, endepunkt og kontraktsnivå (
Feature-Flags-header): Kom i gang - Paginering: Spørringer
- Autorisasjon (RAS): Tilgangsstyring med RAS
- Bruker du en integrasjonsplattform (Gravitee/IntArk): FS GraphQL API og IntArk
- Utforsk skjemaet selv: Introspeksjon
Viktigst: tilgangsmodellen er en annen
Dette er den største forskjellen fra FSWS-Alumni, og den har konsekvenser for personvernet i applikasjonen din.
I FSWS-Alumni var tokenet brukerens eget. Dataporten avgjorde hvem som var innlogget, og tjenesten returnerte kun den brukerens data. Du kunne ikke be om noen andres.
FS GraphQL API har ingen slik brukerdelegering. Du autentiserer deg med en API-bruker knyttet til lærestedet ditt, og oppgir selv hvilket Feide-brukernavn du vil slå opp — API-et kontrollerer ikke om det er den innloggede brukeren du spør etter.
Applikasjonen din må derfor selv sikre at en innlogget bruker bare får se sine egne data: ta Feide-brukernavnet fra den innloggede brukerens ID-token og send akkurat det inn i spørringen — aldri en verdi klienten selv kan påvirke. Denne guiden bruker ingen egen navngitt RAS-rolle utover vanlig autentisert institusjonstilgang — se Tilgangsstyring med RAS for hvordan API-brukeren din bestilles.
Kontraktsnivå i eksemplene
Persondata og aktive studier (Eksempel A under) er stable. Oppnådde kvalifikasjoner (Eksempel B) ligger foreløpig kun på experimental-nivå og krever headeren Feature-Flags: experimental. Er kvalifikasjonsdelen kjernen i integrasjonen din, si fra til fs-support@sikt.no — vi trenger å vite om reelle behov for å prioritere å løfte feltet.
Institusjonsnummer i eksemplene
FS GraphQL API krever at du oppgir hvilket lærested dataene tilhører. Argumentet heter eierOrganisasjonskode og tar institusjonsnummeret. Eksemplene under bruker "1234" — bytt til ditt eget institusjonsnummer.
Paginering: nytt i forhold til FSWS-Alumni
FSWS-Alumni returnerte hele AlumniPerson-objektet i ett svar. I FS GraphQL API er programStudieretter paginert med standard sidestørrelse 10 — har studenten flere studieretter enn det, mangler de i svaret uten at noe feiler. Sett first eksplisitt til et tall som dekker behovet ditt, eller paginer med pageInfo/after. Se Spørringer § Paginering.
oppnaddKvalifikasjon (Eksempel B) er også paginert, med standard sidestørrelse 100.
IDer: er de samme som i FSWS-Alumni?
Nei. FSWS-Alumni sin id var et rent tall (personens løpenummer). Ingen ID i FS GraphQL API er identisk med den — behandle alle GraphQL-IDer som ugjennomsiktige. Du kan base64-dekode dem, men innholdet er en intern implementasjonsdetalj som kan endres uten varsel.
| FSWS-Alumni-verdi | Hva du gjør i FS GraphQL API |
|---|---|
id (heltall, personens løpenummer) | personProfil.personlopenummer gir samme verdi, men som String |
activeStudy.place, qualification.place ("185_11_2_0") | Finnes ikke som ett felt. Sett den sammen av eierOrganisasjonskode + studieansvarligOrganisasjonsenhet { fakultet { fakultetsnummer } instituttnummer gruppenummer } |
activeStudy.program.code, qualifications.areaOfStudy.code | Uendret: studieprogram.kode |
activeStudy.field.code | Uendret: studieretning.kode |
Trenger du bare persondelen, eller er personen ikke lenger registrert som student ved lærestedet, bruk det stabile oppslaget personProfilerGittFeideBrukere i stedet for studenterGittFeideBrukere.
Feide-brukernavn må inneholde domenet
feideBrukere må sendes med full form, inkludert domene ("brukernavn@dittlarested.no"). Et brukernavn uten @ blir stille ignorert, og spørringen returnerer en tom liste uten feilmelding.
Hent persondata og aktive studier
Kontraktsnivå: stable
query HentAlumniData(
$eierOrganisasjonskode: String!
$feideBrukere: [String!]!
) {
studenterGittFeideBrukere(
eierOrganisasjonskode: $eierOrganisasjonskode
feideBrukere: $feideBrukere
) {
studentnummer
personProfil {
personlopenummer
navn {
fornavn
etternavn
}
privatEpost
institusjonsEpost
mobilTelefon {
landnummer
nummer
}
postadresse {
co
gate
postnummerOgSted
land
}
}
programStudieretter(filter: { aktivStatus: [AKTIV] }, first: 50) {
nodes {
studierettperiode {
fraDato
tilDato
}
studieretning {
kode
navnAlleSprak {
nb
nn
en
}
}
studieprogram {
kode
navnAlleSprak {
nb
nn
en
}
studienivaintervallkode
studieansvarligOrganisasjonsenhet {
fakultet {
fakultetsnummer
}
instituttnummer
gruppenummer
}
forerTilKvalifikasjon {
navnAlleSprak {
nb
nn
en
}
}
}
kull {
navnAlleSprak {
no
en
}
terminV2 {
arstall
betegnelse {
kode
}
}
}
}
}
}
}
first: 50 er tatt med fordi standard sidestørrelse er 10 — en alumni har ofte flere studieretter enn det.
Variabler:
{
"eierOrganisasjonskode": "1234",
"feideBrukere": ["brukernavn@dittlarested.no"]
}
Eksempel på svar:
{
"data": {
"studenterGittFeideBrukere": [
{
"studentnummer": "123456",
"personProfil": {
"personlopenummer": "938",
"navn": {
"fornavn": "Ola",
"etternavn": "Nordmann"
},
"privatEpost": "ola.nordmann@example.com",
"institusjonsEpost": "ola.nordmann@student.uio.no",
"mobilTelefon": {
"landnummer": "+47",
"nummer": "12345678"
},
"postadresse": {
"co": null,
"gate": "Storgata 1",
"postnummerOgSted": "0123 Oslo",
"land": "Norge"
}
},
"programStudieretter": {
"nodes": [
{
"studierettperiode": {
"fraDato": "2020-08-01",
"tilDato": null
},
"studieretning": {
"kode": "SRETN",
"navnAlleSprak": {
"nb": "Studieretning",
"nn": "Studieretning",
"en": "Study Field"
}
},
"studieprogram": {
"kode": "SPROG",
"navnAlleSprak": {
"nb": "Bachelorprogram i informatikk",
"nn": null,
"en": "Bachelor's Programme in Informatics"
},
"studienivaintervallkode": "BACHELOR",
"studieansvarligOrganisasjonsenhet": {
"fakultet": { "fakultetsnummer": "11" },
"instituttnummer": "2",
"gruppenummer": "0"
},
"forerTilKvalifikasjon": {
"navnAlleSprak": {
"nb": "Bachelor",
"nn": "Bachelor",
"en": "Bachelor"
}
}
},
"kull": {
"navnAlleSprak": {
"no": "Kull 2016",
"en": "Cohort 2016"
},
"terminV2": {
"arstall": 2016,
"betegnelse": { "kode": "VÅR" }
}
}
}
]
}
}
]
}
}
Hent oppnådde kvalifikasjoner
Kontraktsnivå: experimental. Send headeren { "Feature-Flags": "experimental" }. Uten den finnes ikke feltet, og du får feilen FieldUndefined.
oppnaddKvalifikasjon er en paginert connection, ikke en liste — du må selektere via nodes (eller edges { node }).
query HentOppnaddeKvalifikasjoner(
$eierOrganisasjonskode: String!
$feideBrukere: [String!]!
) {
studenterGittFeideBrukere(
eierOrganisasjonskode: $eierOrganisasjonskode
feideBrukere: $feideBrukere
) {
oppnaddKvalifikasjon(first: 50) {
totalCount
pageInfo {
hasNextPage
endCursor
}
nodes {
datoOppnadd
erKunngjort
kvalifikasjon {
kode
navnAlleSprak {
nb
nn
en
}
}
studieprogram {
kode
navnAlleSprak {
nb
nn
en
}
}
}
}
}
}
{
"data": {
"studenterGittFeideBrukere": [
{
"oppnaddKvalifikasjon": {
"totalCount": 1,
"pageInfo": { "hasNextPage": false, "endCursor": "..." },
"nodes": [
{
"datoOppnadd": "2016-01-01",
"erKunngjort": true,
"kvalifikasjon": {
"kode": "GRAD2",
"navnAlleSprak": {
"nb": "Grad 2",
"nn": "Grad 2",
"en": "Degree 2"
}
},
"studieprogram": {
"kode": "SPROG2",
"navnAlleSprak": {
"nb": "Studieprogram2",
"nn": null,
"en": "Study Programme 2"
}
}
}
]
}
}
]
}
}
erKunngjort har ingen motpart i FSWS-Alumni: kvalifikasjonen regnes som kunngjort når den er gyldig og enten vitnemålet er produsert eller den ble oppnådd for mer enn to år siden. Vil du etterligne FSWS-Alumni nøyaktig, ta med alle rader uavhengig av erKunngjort.
Feltmapping
AlumniPerson (persondata)
| FSWS-Alumni felt | FS GraphQL API felt | Kontraktsnivå |
|---|---|---|
id | personProfil.personlopenummer (String, ikke heltall) | stable |
firstName | personProfil.navn.fornavn | stable |
lastName | personProfil.navn.etternavn | stable |
email | personProfil.institusjonsEpost (e-post tildelt av lærestedet) eller personProfil.privatEpost | stable |
phoneNumber | personProfil.mobilTelefon.landnummer + .nummer (landnummer har plusstegn foran, f.eks. "+47") | stable |
startOfStudy | Tidligste programStudieretter.nodes[].studierettperiode.fraDato — beregn selv, det finnes ikke ett eget felt for den | stable |
AlumniAddress (adresse)
FSWS-Alumnis address har ingen 1:1 GraphQL-motpart — feltene er fordelt annerledes:
| FSWS-Alumni felt | FS GraphQL API felt |
|---|---|
street | personProfil.postadresse.gate |
city, postCode | Begge inngår i personProfil.postadresse.postnummerOgSted (kombinert, f.eks. "0123 Oslo") |
country | personProfil.postadresse.land (fritekst, f.eks. "Norge" — ikke en to-bokstavs landkode) |
AlumniActiveStudy (aktive studier)
Alle stier under er relative til programStudieretter.nodes[].
| FSWS-Alumni felt | FS GraphQL API felt | Kontraktsnivå |
|---|---|---|
field.code | studieretning.kode | stable |
field.nameNorwegian / .nameEnglish | studieretning.navnAlleSprak.nb / .en | stable |
place | studieprogram.studieansvarligOrganisasjonsenhet — sett sammen eierOrganisasjonskode + fakultet.fakultetsnummer + instituttnummer + gruppenummer | stable |
program.code | studieprogram.kode | stable |
program.nameNorwegian / .nameEnglish | studieprogram.navnAlleSprak.nb / .en | stable |
qualification.code | studieprogram.forerTilKvalifikasjon.kode | experimental |
qualification.nameNorwegian / .nameEnglish | studieprogram.forerTilKvalifikasjon.navnAlleSprak.nb / .en | stable |
qualification.nameShort | Ingen tilsvarende felt. Kontakt fs-support@sikt.no hvis du er avhengig av det | – |
qualification.place, qualification.program | FSWS-Alumni kan oppgi et annet sted/program for selve kvalifikasjonen enn for studieretten — vi har ikke funnet en bekreftet GraphQL-motpart for dette. Kontakt fs-support@sikt.no og beskriv behovet | – |
studyClass.year | kull.terminV2.arstall | stable |
studyClass.term (FSWS: "V"/"H") | kull.terminV2.betegnelse.kode (GraphQL: "VÅR"/"HØST", fulle ord) | stable |
studyClass.nameNorwegian / .nameEnglish | kull.navnAlleSprak.no / .en (merk: no, ikke nb) | stable |
qualification.level fantes ikke i FSWS-Alumni. Trenger du studienivået, ligger det på studieprogram.studienivaintervallkode (FAGSKOLE, BACHELOR, MASTER, PHD).
AlumniQualification (oppnådde kvalifikasjoner)
Hele denne tabellen er experimental — krever Feature-Flags: experimental. Alle stier er relative til oppnaddKvalifikasjon.nodes[].
| FSWS-Alumni felt | FS GraphQL API felt |
|---|---|
code | kvalifikasjon.kode |
nameNorwegian / nameEnglish | kvalifikasjon.navnAlleSprak.nb / .en |
date | datoOppnadd |
areaOfStudy.code | studieprogram.kode |
areaOfStudy.nameNorwegian / .nameEnglish | studieprogram.navnAlleSprak.nb / .en |
program | studieprogram.kode |
place | Samme begrensning som for qualification.place over — ingen bekreftet motpart |
nameShort | Ingen tilsvarende felt. Kontakt fs-support@sikt.no |
level fantes ikke i FSWS-Alumni. Trenger du studienivået, bruk studieprogram.studienivaintervallkode.
Kontakt oss for hjelp ved behov
Kontakt fs-support@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen. Det gjelder også hvis du finner at et felt du er avhengig av bare finnes på experimental-nivå — vi trenger å vite om reelle behov for å kunne prioritere å løfte dem.