Fra FSWS-FC til FS GraphQL API

FSWS-FC (Feide Connect) er under utfasing, og funksjonaliteten er nå erstattet av FS GraphQL API. FC-tjenesten tilbyr gruppemedlemskap fra FS for bruk i Feide-økosystemet, inkludert:

Henting av alle grupper en bruker tilhører (studieprogram, kull, klasse, emne, studieretning)
Støtte for både studenter og fagpersoner

Under gir vi eksempler for endepunktet som skal migreres. GraphQL gir imidlertid stor fleksibilitet når det gjelder hvordan du henter dataene. Vi anbefaler at du bruker tid på å sette sammen spørringer som passer ditt behov.

Merk: FS GraphQL API bruker base64-enkodede sammensatte nøkler som IDer. FC-tjenesten brukte Feide-brukernavn og sammensatte gruppe-IDer på formen fc:fs:<type>:<domene>:<koder>. I GraphQL erstattes disse med strukturerte spørringer og base64-IDer.

Oversikt

FSWS-FC endepunkt	Beskrivelse	FS GraphQL API erstatning
`GET /fc/user/feide:{brukernavn}@{domene}/groups`	Hent alle grupper for en Feide-bruker	`personProfilerGittFeideBrukere`
`GET /fc/user/nin:{personnr}@{domene}/groups`	Hent alle grupper for en person gitt personnummer	`personProfilerGittFodselsnumre`

Viktige forskjeller

Identifikasjon: FC brukte feide:brukernavn@domene og nin:personnr@domene. GraphQL bruker eierOrganisasjonskode med Feide-brukernavn eller fødselsnummer.
Gruppemodell: FC samlet alle gruppetyper i en flat liste med type-prefiks (fc:fs:prg, fc:fs:kull, fc:fs:klasse, fc:fs:emne, fc:fs:str). I GraphQL hentes disse som separate, typede felt på PersonProfil.
Respons: FC returnerte en egendefinert JSON-struktur med id, type, displayName, membership. GraphQL returnerer rike, typede objekter med alle tilgjengelige felt.
Roller: FC skilte mellom member (student) og owner (fagperson). I GraphQL har studenter og fagpersoner egne typer (StudentVedLarested, FagpersonVedLarested) som nås via PersonProfil.
Domene-basert tilgang: FC brukte Feide-domene for tilgangskontroll. I GraphQL brukes eierOrganisasjonskode (institusjonsnummer).
Paginering: Flere av feltene i GraphQL-spørringene er paginerte (f.eks. programStudieretter, emneStudieretter, klassemedlemskap, emneroller). Standardverdien for first er typisk 10. FC returnerte alle grupper uten paginering, så du bør justere first-argumentet til et passende tall for ditt bruk, f.eks. programStudieretter(first: 100).

GET /fc/user/feide:{brukernavn}@{domene}/groups

FC returnerte en samlet liste med alle grupper en bruker tilhører, for både studenter og fagpersoner. I GraphQL oppnås tilsvarende med personProfilerGittFeideBrukere, som gir tilgang til både student og fagperson via PersonProfil.

FSWS-FC eksempel:

GET /fc/user/feide:ola@uio.no/groups

FSWS-FC respons (forenklet):

[
  {
    "id": "fc:fs:prg:uio.no:INFORMATIKK",
    "type": "fc:fs:prg",
    "displayName": { "nb": "Informatikk", "nn": "Informatikk", "en": "Informatics" },
    "membership": {
      "basic": "member",
      "fsroles": ["STUDENT"],
      "active": true,
      "notBefore": "2023-08-01T00:00:00Z",
      "notAfter": "2026-06-30T00:00:00Z"
    }
  },
  {
    "id": "fc:fs:kull:uio.no:INFORMATIKK:2023:HØST",
    "type": "fc:fs:kull",
    "displayName": { "nb": "Studiekull 2023-HØST", "en": "Study cohort 2023-HØST" },
    "membership": { "basic": "member", "active": true }
  },
  {
    "id": "fc:fs:klasse:uio.no:INFORMATIKK:2023:HØST:A",
    "type": "fc:fs:klasse",
    "displayName": { "nb": "Klasse A" },
    "membership": { "basic": "member", "active": true }
  },
  {
    "id": "fc:fs:emne:uio.no:INF1000:1:2025:VÅR",
    "type": "fc:fs:emne",
    "displayName": { "nb": "Grunnkurs i programmering", "en": "Introduction to Programming" },
    "membership": {
      "basic": "member",
      "active": true,
      "subjectRelations": "undervisning"
    }
  },
  {
    "id": "fc:fs:str:uio.no:DATATEKNOLOGI",
    "type": "fc:fs:str",
    "displayName": { "nb": "Datateknologi", "nn": "Datateknologi", "en": "Computer Science" },
    "membership": { "basic": "member", "active": true }
  }
]

FS GraphQL API spørring:

query HentGrupperForBruker {
  personProfilerGittFeideBrukere(
    eierOrganisasjonskode: "1234"
    feideBrukere: ["ola@uio.no"]
  ) {
    # Studentgrupper
    student {
      # Studieprogram (fc:fs:prg), kull (fc:fs:kull), klasse (fc:fs:klasse), studieretning (fc:fs:str)
      programStudieretter(first: 100) {
        nodes {
          studieprogram {
            kode
            navnAlleSprak {
              nb
              nn
              en
            }
          }
          studentstatus {
            kode
            girAktivStudierett
          }
          studierettperiode {
            fraDato
            tilDato
          }
          kull {
            navnAlleSprak {
              no
              en
            }
            terminV2 {
              arstall
              betegnelse {
                kode
              }
            }
          }
          klassemedlemskap(first: 100) {
            nodes {
              klasse {
                kode
                navnAlleSprak {
                  und
                }
                erAktiv
              }
            }
          }
          studieretning {
            kode
            navnAlleSprak {
              nb
              nn
              en
            }
          }
        }
      }
      # Emner (fc:fs:emne)
      emneStudieretter(first: 100) {
        nodes {
          emne {
            kode
            versjonskode
            navnAlleSprak {
              nb
              nn
              en
            }
          }
          termin {
            arstall
            betegnelse {
              kode
            }
          }
        }
      }
    }
    # Fagpersongrupper
    fagperson {
      erAktiv
      # Emneroller (tilsvarer fc:fs:emne med basic=owner)
      emneroller(first: 100) {
        nodes {
          emne {
            kode
            versjonskode
            navnAlleSprak {
              nb
              nn
              en
            }
          }
          fsRolle {
            kode
            navnAlleSprak {
              nb
              nn
              en
            }
          }
          erAktiv
          gyldighetsperiode {
            fraDato
            tilDato
          }
        }
      }
      # Studieprogramroller (tilsvarer fc:fs:prg med basic=owner)
      studieprogramroller {
        studieprogram {
          kode
          navnAlleSprak {
            nb
            nn
            en
          }
        }
        fsRolle {
          kode
          navnAlleSprak {
            nb
            nn
            en
          }
        }
        erAktiv
        gyldighetsperiode {
          fraDato
          tilDato
        }
      }
      # Kullroller (tilsvarer fc:fs:kull med basic=owner)
      kullroller {
        kull {
          navnAlleSprak {
            no
            en
          }
          studieprogram {
            kode
          }
          terminV2 {
            arstall
            betegnelse {
              kode
            }
          }
        }
        fsRolle {
          kode
          navnAlleSprak {
            nb
            nn
            en
          }
        }
      }
      # Klasseroller (tilsvarer fc:fs:klasse med basic=owner)
      klasseroller {
        klasse {
          kode
          navnAlleSprak {
            und
          }
        }
        fsRolle {
          kode
          navnAlleSprak {
            nb
            nn
            en
          }
        }
      }
    }
  }
}

Eksempel på respons:

{
  "data": {
    "personProfilerGittFeideBrukere": [
      {
        "student": {
          "programStudieretter": {
            "nodes": [
              {
                "studieprogram": {
                  "kode": "INFORMATIKK",
                  "navnAlleSprak": {
                    "nb": "Informatikk",
                    "nn": "Informatikk",
                    "en": "Informatics"
                  }
                },
                "studentstatus": {
                  "kode": "AKTIV",
                  "girAktivStudierett": true
                },
                "studierettperiode": {
                  "fraDato": "2023-08-01",
                  "tilDato": "2026-06-30"
                },
                "kull": {
                  "navnAlleSprak": {
                    "no": "Studiekull 2023-HØST",
                    "en": null
                  },
                  "terminV2": {
                    "arstall": 2023,
                    "betegnelse": {
                      "kode": "HØST"
                    }
                  }
                },
                "klassemedlemskap": {
                  "nodes": [
                    {
                      "klasse": {
                        "kode": "A",
                        "navnAlleSprak": {
                          "und": "Klasse A"
                        },
                        "erAktiv": true
                      }
                    }
                  ]
                },
                "studieretning": {
                  "kode": "DATATEKNOLOGI",
                  "navnAlleSprak": {
                    "nb": "Datateknologi",
                    "nn": "Datateknologi",
                    "en": "Computer Science"
                  }
                }
              }
            ]
          },
          "emneStudieretter": {
            "nodes": [
              {
                "emne": {
                  "kode": "INF1000",
                  "versjonskode": "1",
                  "navnAlleSprak": {
                    "nb": "Grunnkurs i programmering",
                    "nn": "Grunnkurs i programmering",
                    "en": "Introduction to Programming"
                  }
                },
                "termin": {
                  "arstall": 2025,
                  "betegnelse": {
                    "kode": "VÅR"
                  }
                }
              }
            ]
          }
        },
        "fagperson": {
          "erAktiv": true,
          "emneroller": {
            "nodes": [
              {
                "emne": {
                  "kode": "INF1000",
                  "versjonskode": "1",
                  "navnAlleSprak": {
                    "nb": "Grunnkurs i programmering",
                    "nn": "Grunnkurs i programmering",
                    "en": "Introduction to Programming"
                  }
                },
                "fsRolle": {
                  "kode": "FORELESER",
                  "navnAlleSprak": {
                    "nb": "Foreleser",
                    "nn": "Førelesar",
                    "en": "Lecturer"
                  }
                },
                "erAktiv": true,
                "gyldighetsperiode": {
                  "fraDato": "2025-01-01",
                  "tilDato": "2025-06-30"
                }
              }
            ]
          },
          "studieprogramroller": [
            {
              "studieprogram": {
                "kode": "INFORMATIKK",
                "navnAlleSprak": {
                  "nb": "Informatikk",
                  "nn": "Informatikk",
                  "en": "Informatics"
                }
              },
              "fsRolle": {
                "kode": "STUDIEPROGRAMLEDER",
                "navnAlleSprak": {
                  "nb": "Studieprogramleder",
                  "nn": "Studieprogramleiar",
                  "en": "Programme Director"
                }
              },
              "erAktiv": true,
              "gyldighetsperiode": {
                "fraDato": "2023-01-01",
                "tilDato": null
              }
            }
          ],
          "kullroller": [],
          "klasseroller": []
        }
      }
    ]
  }
}

GET /fc/user/nin:{personnr}@{domene}/groups

For oppslag med fødselsnummer i stedet for Feide-brukernavn, bruk personProfilerGittFodselsnumre med samme nøsting:

query HentGrupperForPersonnummer {
  personProfilerGittFodselsnumre(
    eierOrganisasjonskode: "1234"
    fodselsnumre: ["XXXXXXXXXXX"]
  ) {
    student {
      programStudieretter(first: 100) {
        nodes {
          studieprogram {
            kode
            navnAlleSprak { nb nn en }
          }
          studentstatus {
            kode
            girAktivStudierett
          }
          studierettperiode {
            fraDato
            tilDato
          }
          kull {
            navnAlleSprak { no en }
            terminV2 {
              arstall
              betegnelse { kode }
            }
          }
          klassemedlemskap(first: 100) {
            nodes {
              klasse {
                kode
                navnAlleSprak { und }
                erAktiv
              }
            }
          }
          studieretning {
            kode
            navnAlleSprak { nb nn en }
          }
        }
      }
      emneStudieretter(first: 100) {
        nodes {
          emne {
            kode
            versjonskode
            navnAlleSprak { nb nn en }
          }
          termin {
            arstall
            betegnelse { kode }
          }
        }
      }
    }
    # Fagpersongrupper
    fagperson {
      erAktiv
      emneroller(first: 100) {
        nodes {
          emne {
            kode
            versjonskode
            navnAlleSprak { nb nn en }
          }
          fsRolle {
            kode
            navnAlleSprak { nb nn en }
          }
          erAktiv
          gyldighetsperiode { fraDato tilDato }
        }
      }
      studieprogramroller {
        studieprogram {
          kode
          navnAlleSprak { nb nn en }
        }
        fsRolle {
          kode
          navnAlleSprak { nb nn en }
        }
        erAktiv
        gyldighetsperiode { fraDato tilDato }
      }
      kullroller {
        kull {
          navnAlleSprak { no en }
          studieprogram { kode }
          terminV2 {
            arstall
            betegnelse { kode }
          }
        }
        fsRolle {
          kode
          navnAlleSprak { nb nn en }
        }
      }
      klasseroller {
        klasse {
          kode
          navnAlleSprak { und }
        }
        fsRolle {
          kode
          navnAlleSprak { nb nn en }
        }
      }
    }
  }
}

Feltmapping: FSWS-FC til FS GraphQL API

Group-objektet

FSWS-FC felt	FS GraphQL API
`group.id` (f.eks. `fc:fs:prg:uio.no:INFO`)	`Studieprogram.kode`, `Emne.kode` + `versjonskode`, `Kull.id`, `Klasse.kode`, `Studieretning.kode`
`group.type` (`fc:fs:prg`, `fc:fs:kull`, etc.)	Implisitt gjennom GraphQL-typen (`Studieprogram`, `Kull`, `Klasse`, `Emne`, `Studieretning`)
`group.displayName.nb/nn/en`	`*.navnAlleSprak { nb nn en }` på den aktuelle typen
`group.membership.basic` = `member`	Implisitt: data finnes under `PersonProfil.student`
`group.membership.basic` = `owner`	Implisitt: data finnes under `PersonProfil.fagperson` med roller (`emneroller`, `studieprogramroller`, `kullroller`, `klasseroller`)
`group.membership.active`	Student: `ProgramStudierett.studentstatus.girAktivStudierett`. Fagperson: `Emnerolle.erAktiv`, `Studieprogramrolle.erAktiv`
`group.membership.notBefore`	Student: `ProgramStudierett.studierettperiode.fraDato`. Fagperson: `*.gyldighetsperiode.fraDato`
`group.membership.notAfter`	Student: `ProgramStudierett.studierettperiode.tilDato`. Fagperson: `*.gyldighetsperiode.tilDato`
`group.membership.fsroles`	`Studieprogramrolle.fsRolle.kode`, `Emnerolle.fsRolle.kode`, `Kullrolle.fsRolle.kode`, `Klasserolle.fsRolle.kode`
`group.membership.subjectRelations`	Implisitt gjennom GraphQL-typen (`EmneStudierett`)

Gruppetyper (student - `basic: "member"`)

FC gruppetype	FC ID-format	GraphQL-sti fra `PersonProfil`
`fc:fs:prg`	`fc:fs:prg:<domene>:<programkode>`	`student.programStudieretter.studieprogram`
`fc:fs:kull`	`fc:fs:kull:<domene>:<prog>:<år>:<termin>`	`student.programStudieretter.kull`
`fc:fs:klasse`	`fc:fs:klasse:<domene>:<prog>:<år>:<termin>:<klasse>`	`student.programStudieretter.klassemedlemskap.klasse`
`fc:fs:emne`	`fc:fs:emne:<domene>:<emne>:<versjon>:<år>:<termin>`	`student.emneStudieretter.emne`
`fc:fs:str`	`fc:fs:str:<domene>:<retningskode>`	`student.programStudieretter.studieretning`

Gruppetyper (fagperson - `basic: "owner"`)

FC gruppetype	FC ID-format	GraphQL-sti fra `PersonProfil`
`fc:fs:prg`	`fc:fs:prg:<domene>:<programkode>`	`fagperson.studieprogramroller.studieprogram`
`fc:fs:kull`	`fc:fs:kull:<domene>:<prog>:<år>:<termin>`	`fagperson.kullroller.kull`
`fc:fs:klasse`	`fc:fs:klasse:<domene>:<prog>:<år>:<termin>:<klasse>`	`fagperson.klasseroller.klasse`
`fc:fs:emne`	`fc:fs:emne:<domene>:<emne>:<versjon>:<år>:<termin>`	`fagperson.emneroller.emne`

Kontakt oss for hjelp ved behov

Kontakt kontakt@sikt.no dersom du trenger hjelp til å komme i gang, eller underveis i migreringen.

Oversikt​

Viktige forskjeller​

GET /fc/user/feide:{brukernavn}@{domene}/groups​

GET /fc/user/nin:{personnr}@{domene}/groups​

Feltmapping: FSWS-FC til FS GraphQL API​

Group-objektet​

Gruppetyper (student - basic: "member")​

Gruppetyper (fagperson - basic: "owner")​

Kontakt oss for hjelp ved behov​