Gå til hovedinnhold

Fra FSWS-BAS til FS GraphQL API

FSWS-BAS er under utfasing, og deler av tjenesten er nå erstattet av FS GraphQL API. BAS-tjenesten består av endepunkter som er laget til litt forskjellige formål:

  • Oppdatering av brukernavn og studentbilder
  • Full- og inkrementell eksport av brukerdata (basData og basExport)

Under gir vi eksempler for hvert enkelt endepunkt. GraphQL gir imidlertid stor fleksibilitet når det gjelder hvordan du henter og oppdaterer dataene. Vi anbefaler at du bruker tid på å sette sammen spørringer og mutasjoner som passer ditt behov.

Merk: FS GraphQL API bruker base64-enkodede sammensatte nøkler som IDer. Hvis du trenger å finne PersonProfil-ID fra et fødselsnummer, se eksempelet under Klienten må bruke FS GraphQL APIs ID for objektet.

POST /bas/oppdater/brukernavn - Oppdater brukernavn​

FSWS-BAS tillot oppdatering av en persons brukernavn ved å oppgi fødselsnummer. I FS GraphQL API erstattes dette av mutasjonen angiBrukerinformasjonForPersonProfiler.

Viktige forskjeller:

  • FS GraphQL API bruker PersonProfil-ID i stedet for fødselsnummer
  • Feltet heter feideBruker i stedet for brukernavn
  • Du kan også oppdatere institusjonsEpost i samme mutasjon

Eksempel på mutasjon:

mutation {
  angiBrukerinformasjonForPersonProfiler(
    input: {
      id: "NzY6MTIzNCw4ODE"
      feideBruker: "test"
      institusjonsEpost: "bruker@institusjon.no"
    }
  ) {
    personProfiler {
      id
      feideBruker
      institusjonsEpost
    }
  }
}

Eksempel på svar:

{
  "data": {
    "angiBrukerinformasjonForPersonProfiler": {
      "personProfiler": [
        {
          "id": "NzY6MTIzNCw4ODE",
          "feideBruker": "test@spusers.feide.no",
          "institusjonsEpost": "bruker@institusjon.no"
        }
      ]
    }
  }
}

Her bruker vi mutasjon for å slette eller blanke ut disse feltene: NB! Det er også mulig å bruke en tom streng "" i stedet for null

mutation MyMutation {
  angiBrukerinformasjonForPersonProfiler(
    input: {
      id: "NzY6MTIzNCw4ODE"
      feideBruker: null
      institusjonsEpost: null
    }
  ) {
    personProfiler {
      id
      feideBruker
      institusjonsEpost
    }
  }
}

Eksempel på svar:

{
  "data": {
    "angiBrukerinformasjonForPersonProfiler": {
      "personProfiler": [
        {
          "id": "NzY6MTIzNCw4ODE",
          "feideBruker": null,
          "institusjonsEpost": null
        }
      ]
    }
  }
}

POST /bas/oppdater/bilde - Last opp/oppdater bilde​

FSWS-BAS tillot opplasting av bilder for personer. I FS GraphQL API kan du opprette og oppdatere studentbilder med mutasjonen angiStudentbilder.

Viktige forskjeller:

  • Krever StudentVedLarested-ID i stedet for fødselsnummer
  • Bildet må være Base64-kodet
  • Krever eksplisitt spesifikasjon av filtype

Eksempel på mutasjon:

mutation {
    angiStudentbilder(
        input: {
            studentVedLarestedId: "OTk6MTIzNCwxNDQw"
            bilde: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
            filtype: JPG
        }
    ) {
        studentbilder {
            id
            bilde
            filtype
        }
        errors {
            ... on Error {
                path
                message
                __typename
            }
        }
    }
}

POST /bas/oppdater/email - Oppdater e-postadresse​

FSWS-BAS tillot oppdatering av en persons e-postadresse (PERSON.EMAILADRESSE) ved å oppgi fødselsnummer. I FS GraphQL API erstattes dette av mutasjonen endreEpostadresserForPersonProfiler.

Oppdatering av en persons e-postadresse er en del av tilgangsstyringsprosessen. Se Tilgangstyring for studenter og ansatte for en beskrivelse av prosessen og tilhørende GraphQL-mutasjoner.

Viktige forskjeller:

  • FS GraphQL API bruker PersonProfil-ID i stedet for fødselsnummer
  • Du kan oppdatere privatEpost, arbeidsEpost og institusjonsEpost i samme mutasjon
  • Sett feltet til null for å slette en e-postadresse

Eksempel på mutasjon:

mutation {
  endreEpostadresserForPersonProfiler(
    input: [
      {
        id: "NzY6MTIzNCw4ODM"
        privatEpost: "bruker@example.com"
        arbeidsEpost: "bruker@arbeid.no"
      }
    ]
  ) {
    personProfiler {
      id
      privatEpost
      arbeidsEpost
      institusjonsEpost
    }
    errors {
      __typename
      ... on UgyldigInput {
        message
        path
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "endreEpostadresserForPersonProfiler": {
      "personProfiler": [
        {
          "id": "NzY6MTIzNCw4ODM",
          "privatEpost": "bruker@example.com",
          "arbeidsEpost": "bruker@arbeid.no",
          "institusjonsEpost": null
        }
      ],
      "errors": null
    }
  }
}

POST /bas/oppdater/fagperson - Opprett eller oppdater fagperson​

FSWS-BAS tillot opprettelse og oppdatering av fagpersoner ved å sende inn en XML-representasjon. I FS GraphQL API erstattes dette av mutasjonen opprettFagpersonerGittFodselsnumre for opprettelse, samt egne mutasjoner for oppdatering av enkeltfelt.

Opprettelse og oppdatering av fagpersoner er en del av tilgangsstyringsprosessen. Se Tilgangstyring for studenter og ansatte for en beskrivelse av prosessen og tilhørende GraphQL-mutasjoner.

Viktige forskjeller:

  • FSWS-BAS brukte én XML-payload for å opprette og oppdatere fagpersoner. I FS GraphQL API er dette splittet i én mutasjon for opprettelse og egne mutasjoner for oppdatering av enkeltfelt
  • eierOrganisasjonskode og fodselsnummer er påkrevde felt for opprettelse
  • Oppdateringsmutasjoner inkluderer blant annet endreArbeidsadresseForFagpersoner, angiCampusForFagpersoner, aktiverFagpersoner, deaktiverFagpersoner og plasserFagpersonerPaaRom

Eksempel på opprettelse av fagperson:

mutation {
  opprettFagpersonerGittFodselsnumre(
    input: [
      {
        eierOrganisasjonskode: "1234"
        fodselsnummer: "XXXXXXXXXXX"
        fornavn: "Ola"
        etternavn: "Nordmann"
        arbeidsEpost: "ola.nordmann@institusjon.no"
        feideBruker: "olanord"
      }
    ]
  ) {
    result {
      personProfil {
        id
        navn {
          fornavn
          etternavn
        }
      }
      fagperson {
        id
        erAktiv
        ansattVed {
          id
          navnAlleSprak {
            nb
          }
        }
      }
    }
    errors {
      __typename
      ... on Error {
        message
        path
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "opprettFagpersonerGittFodselsnumre": {
      "result": [
        {
          "personProfil": {
            "id": "NzY6MTIzNCwzNzgw",
            "navn": {
              "fornavn": "Ola",
              "etternavn": "Nordmann"
            }
          },
          "fagperson": {
            "id": "MzE6MTIzNCwzNzgw",
            "erAktiv": true,
            "ansattVed": null
          }
        }
      ],
      "errors": null
    }
  }
}

GET /bas/hent/fagpersoner - Hent alle fagpersoner​

Henter alle aktive fagpersoner med kontaktinfo, tilknytning (stedref) og roller. I FS GraphQL API erstattes dette av spørringen fagpersoner.

query AlleFagpersoner {
  fagpersoner(
    filter: {
      eierOrganisasjonskode: "1234"
    }
    first: 3
  ) {
    edges {
      node {
        id
        personProfil {
          fodselsnummer
          navn {
            fornavn
            etternavn
          }
        }
        erAktiv
        ansattVed {
          id
          navnAlleSprak {
            nb
          }
        }
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "fagpersoner": {
      "edges": [
        {
          "node": {
            "id": "MzE6MTIzNCw4ODM",
            "personProfil": {
              "fodselsnummer": "XXXXXXXXXXX",
              "navn": {
                "fornavn": "Njål",
                "etternavn": "Øye"
              }
            },
            "erAktiv": true,
            "ansattVed": {
              "id": "Nzk6MTIzNCwxODQsMywwLDA",
              "navnAlleSprak": {
                "nb": "Det medisinske fakultet, UiB"
              }
            }
          }
        }
      ]
    }
  }
}

Viktige forskjeller:

  • FSWS-BAS returnerer XML, FS GraphQL API returnerer JSON
  • Stedkoden (stedref) erstattes av nøstet ansattVed-objekt (Organisasjonsenhet)
  • Roller (undervisningsaktivitetsroller, studieprogramroller, etc.) kan hentes som nøstede felt på FagpersonVedLarested

GET /bas/hent/fagperson - Hent en fagperson​

Henter en enkelt fagperson basert på fødselsnummer. I FS GraphQL API erstattes dette av spørringen fagpersonerGittFodselsnumre.

query EnFagperson {
  fagpersonerGittFodselsnumre(
    eierOrganisasjonskode: "1234"
    fodselsnumre: ["XXXXXXXXXXX"]
  ) {
    id
    personProfil {
      fodselsnummer
      navn {
        fornavn
        etternavn
      }
    }
    erAktiv
    ansattVed {
      id
      navnAlleSprak {
        nb
      }
    }
    bilde {
      bilde
      filtype
    }
  }
}

Eksempel på svar:

{
  "data": {
    "fagpersonerGittFodselsnumre": [
      {
        "id": "MzE6MTIzNCw4ODM",
        "personProfil": {
          "fodselsnummer": "XXXXXXXXXXX",
          "navn": {
            "fornavn": "Njål",
            "etternavn": "Øye"
          }
        },
        "erAktiv": true,
        "ansattVed": {
          "id": "Nzk6MTIzNCwxODQsMywwLDA",
          "navnAlleSprak": {
            "nb": "Det medisinske fakultet, UiB"
          }
        },
        "bilde": {
          "bilde": "",
          "filtype": "PNG"
        }
      }
    ]
  }
}

Viktige forskjeller:

  • FSWS-BAS bruker nin-parameter (fødselsnummer), FS GraphQL API bruker fodselsnumre-parameter
  • FSWS-BAS returnerer XML, FS GraphQL API returnerer JSON
  • I FS GraphQL API kan du hente bilde og roller i samme spørring

GET /bas/hent/kull - Hent alle kull​

Henter alle aktive kull. I FS GraphQL API erstattes dette av spørringen kull.

Viktige forskjeller:

  • FSWS-BAS returnerer XML med kull-ID på formen STUDIEPROGRAMKODE_ÅRSTALL_TERMIN, FS GraphQL API returnerer JSON med base64-enkodet ID og nøstede felt for studieprogram og termin
  • FSWS-BAS returnerer bare kullnavn, FS GraphQL API gir tilgang til alle nøstede felt
query AlleAktiveKull {
  kull(
    filter: {
      eierOrganisasjonskode: "1234"
      erAktiv: true
    }
    first: 3
  ) {
    edges {
      node {
        id
        studieprogram {
          kode
        }
        termin {
          arstall
          betegnelse {
            navnAlleSprak {
              nb
            }
          }
        }
        navnAlleSprak {
          en
          no
        }
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "kull": {
      "edges": [
        {
          "node": {
            "id": "NTg6MTIzNCwxMCwxOTkzLEjDmFNU",
            "studieprogram": {
              "kode": "10"
            },
            "termin": {
              "arstall": 1993,
              "betegnelse": {
                "navnAlleSprak": {
                  "nb": "Høst"
                }
              }
            },
            "navnAlleSprak": {
              "en": null,
              "no": "Studiekull 1993-HØST"
            }
          }
        }
      ]
    }
  }
}

GET /bas/hent/sted - Hent steder ved en institusjon​

Henter organisasjonsenheter (steder) ved en institusjon. I FS GraphQL API erstattes dette av spørringen organisasjonsenheter.

Viktige forskjeller:

  • FSWS-BAS bruker stedkode (institusjonsnr_faknr_instituttnr_gruppenr), FS GraphQL API bruker base64-enkodet ID
  • FSWS-BAS returnerer XML, FS GraphQL API returnerer JSON
  • Stedakronym og navneoversettelser er tilgjengelig via nøstede felt
query AlleSteder {
  organisasjonsenheter(
    filter: {
      eierOrganisasjonskode: "1234"
    }
    first: 3
  ) {
    edges {
      node {
        id
        navnAlleSprak {
          nb
          nn
          en
        }
        erAktiv
        organisasjon {
          organisasjonskode
        }
        fakultet {
          fakultetsnummer
        }
        instituttnummer
        gruppenummer
      }
    }
  }
}

Eksempel på svar:

{
  "data": {
    "organisasjonsenheter": {
      "edges": [
        {
          "node": {
            "id": "Nzk6MTIzNCwwLDAsMCww",
            "navnAlleSprak": {
              "nb": "Uniwersytet w Bialymstoku",
              "nn": null,
              "en": null
            },
            "erAktiv": true,
            "organisasjon": {
              "organisasjonskode": "0"
            },
            "fakultet": {
              "fakultetsnummer": "0"
            },
            "instituttnummer": "0",
            "gruppenummer": "0"
          }
        }
      ]
    }
  }
}

GET /bas/hent/baseksport - Inkrementell dataeksport​

I FS GraphQL API kan du abonnere på endringer gjennom hendelses-systemet:

  • Abonner på relevante person-, student- og ansatthendelser via Query.personProfilhendelser og Query.studenthendelser
  • Bygg din egen synkronisering basert på hendelsesstrømmer
  • Les mer om hendelser her: FS GraphQL API: Hendelser

GET /bas/hent/basdata - Full dataeksport​

For å hente samme type data som du er vant til fra basData, kan du bruke GraphQL til å konstruere spørringer som henter nøyaktig de dataene du trenger. Her er to enkle eksempler:

Eksport av studenter med tilknytninger:

query {
  studenterGittFodselsnumre(
    eierOrganisasjonskode: "1234"
    fodselsnumre: ["XXXXXXXXXXX"]
  ) {
    id
    personProfil {
      fodselsnummer
      feideBruker
      institusjonsEpost
      navn {
        fornavn
        etternavn
      }
    }
    lanetakerId
    studentkort {
      gyldighetsperiode {
        fraDato
        tilDato
      }
    }
    vurderingsmeldinger {
      id
      vurderingsenhet {
        emne {
          kode
          navnAlleSprak {
            nb
          }
        }
      }
    }
    semesterregistreringer {
      nodes {
        termin {
          arstall
          betegnelse {
            kode
          }
        }
        harBetaltSemesteravgiftV2
      }
    }
  }
}

Eksport av fagpersoner med roller:

query {
  fagpersonerGittFodselsnumre(
    eierOrganisasjonskode: "1234"
    fodselsnumre: ["XXXXXXXXXXX"]
  ) {
    personProfil {
      navn {
        fornavn
        etternavn
      }
    }
    studieprogramroller {
      gyldighetsperiode {
        fraDato
        tilDato
      }
    }
    bilde {
      bilde
      filtype
    }
  }
}

Disse spørringene kan tilpasses videre for å hente akkurat de feltene du trenger. Ta kontakt med kontakt@sikt.no for å få hjelp til å sette opp en spørring som passer ditt spesifikke behov.

Kontakt oss for hjelp ved behov​

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