Dersom du mener at noe er feil, mangelfullt, eller utdatert, ta gjerne kontakt med oss i #team-rocket eller #felles-kodeverk.

Definisjoner

Ressurstyper

• Kodeverk - i sin kjerne er et kodeverk en navngitt liste av konstante kodenavn. Utviklere flest ville kanskje kalt dem “enumer”, men Navs kodeverk legger på noen ekstra dimensjoner i form av gyldighetsperioder og beskrivende tekster på ulike språk.
• Hierarki - hierarkier lar oss bygge opp en struktur ved å koble sammen koder fra forksjellige kodeverk.

Roller

• Administrator - en bruker som har alle rettigheter som løsningen byr på. Dersom eieren av et kodeverk forsvinner vil administratoren kunne tildele kodeverket en ny eier. Denne rollen styres i Identrutinen.
• Kodeverkseier - en bruker som er eieren av et eller flere kodeverk. Som eier kan man publisere endringer på kodeverkene sine, og gjøre endringer som å skifte eier eller legge til forvaltere. Denne rollen blir tildelt av en administrator.
• Kodeverksforvalter - en bruker som er gitt tillatelse til å manipulere eksisterende kodeverk av kodeverkseieren. Endringer inkluderer handlinger som å legge til nye koder og oppdatere beskrivelsene til gyldighetsperiodene deres. Denne rollen blir tildelt av en administrator eller av kodeverkseieren.
• Hierarkieier - en bruker som er eieren av et eller flere hierarkier. Som eier kan man publisere endringer på hierarkiene sine, og gjøre endringer som å skifte eier eller legge til forvaltere. Denne rollen blir tildelt av en administrator.
• Hierarkiforvalter - en bruker som er gitt tillatelse til å manipulere eksisterende hierarkier av hierarkieieren. Endringer inkluderer handlinger som å legge til eller fjerne noder fra hierarkiet. Denne rollen blir tildelt av en administrator eller av hierarkieieren.

Handlinger

• Publisering - når et kodeverk eller hierarki er endret, og disse endringene gjøres tilgjengelige for API-konsumentene.

For API‐konsumenter

Overblikk

Applikasjoner som ønsker å konsumere felles kodeverk må bruke REST API’et til prod-gcp instansen av kodeverk-api, selv om de kjører i dev-fss eller dev-gcp. For å gjøre dette mulig er kodeverk-api eksponert på ingressen https://kodeverk-api.nav.no som er tilgjengelig fra internett. Den validerer også access tokens fra både nav.no og trygdeetaten.no Entra ID tenantene.

Hente kodeverk i utkast

Følgende endepunkter har et query parameter, inkluderUtkast, som kan settes til true (false by default) hvis du ønsker at eventuelle endringer på kodeverkene skal returneres før de er publisert. Dette kan brukes for å verifisere disse endringene på kodeverkene og bør antakeligvis kun benyttes i dev.

• GET /api/v1/kodeverk
• GET /api/v1/kodeverk/{kodeverksnavn}/koder
• GET /api/v1/kodeverk/{kodeverksnavn}/koder/betydninger

Eksempel på bruk:

GET /api/v1/kodeverk/NAVSkjema/koder/betydninger?inkluderUtkast=true

Ta i bruk tjenestene

Gi applikasjonen din tilgang

Be om at den konsumerende applikasjonen legges inn i kodeverk-api sine access policies. Dette kan gjøres ved å kontakte oss i #team-rocket eller i #felles-kodeverk. Vi vil trenge applikasjonsnavn, namespace og cluster for å gi tilgang.

Konfigurer endepunkt

Konfigurasjonen av klienten din avhenger i stor grad av hvor den kjører, så velg det delkapittelet nedenfor som passer den best:

Konsument i dev-gcp

1. Sett base URL til https://kodeverk-api.nav.no

2. Legg til en outbound external host i nais.yml-filen:

    spec:
      accessPolicy:
        outbound:
          external:
            - host: kodeverk-api.nav.no
   

3. Sett scope i token-kallet fra Entra ID-klienten til api://dev-gcp.team-rocket.kodeverk-api/.default

Konsument i prod-gcp

Her kan man velge å bruke ingressen https://kodeverk-api.nav.no eller Kubernetes service discovery siden klienten og kodeverk-api kjører i samme cluster.

Ingress

1. Sett base URL til https://kodeverk-api.nav.no

2. Legg til en outbound external host i nais.yml-filen:

    spec:
      accessPolicy:
        outbound:
          external:
            - host: kodeverk-api.nav.no
   

3. Sett scope i token-kallet fra Entra ID-klienten til api://prod-gcp.team-rocket.kodeverk-api/.default

Service discovery

1. Sett base URL til enten http://kodeverk-api.team-rocket eller http://kodeverk-api.team-rocket.svc.cluster.local

2. Legg til en outbound rule i nais.yml-filen:

    spec:
      accessPolicy:
        outbound:
          rules:
            - application: kodeverk-api
              namespace: team-rocket
   

3. Sett scope i token-kallet fra Entra ID-klienten til api://prod-gcp.team-rocket.kodeverk-api/.default

Konsument i dev-fss

1. Sett base URL til https://kodeverk-api.nav.no
2. Sett scope i token-kallet fra Entra ID-klienten til api://dev-gcp.team-rocket.kodeverk-api/.default
3. Hvis det ikke er gjort enda, aktiver webproxy på klienten, blant annet ved å sette spec.webproxy: true i nais.yml-filen.

Konsument i prod-fss

1. Sett base URL til https://kodeverk-api.nav.no
2. Sett scope i token-kallet fra Entra ID-klienten til api://prod-gcp.team-rocket.kodeverk-api/.default
3. Hvis det ikke er gjort enda, aktiver webproxy på klienten, blant annet ved å sette spec.webproxy: true i nais.yml-filen.

For hierarkieiere og ‐forvaltere

Oppdatere hierarkidetaljer

🔒 Hvem kan gjøre dette: Administrator, hierarkieier

Det finnes en knapp som heter “Rediger hierarki” oppe i det høyre hjørnet på siden om et gitt hierarki. Denne åpner en modal som lar deg gjøre endringer på hierarkidetaljene.

• Navn - navnet på hierarkiet kan endres helt til det har blitt publisert for første gang.
• Beskrivelse - litt informasjon om hva hierarkiet faktisk er, slik at potensielle konsumenter kan avgjøre om de kan ta det i bruk eller ikke.
• Eier - dersom hierarkiet har behov for en ny eier kan NAV-identen til den nye eieren skrives inn her. NB: Et hierarki kan bare ha én eier, så når denne endres vil den forrige eieren miste eierskapet, og kan derfor ikke lenger gjøre videre endringer på hierarkiet.
• Forvaltere - et hierarki kan ha opptil flere forvaltere. Disse vil ha tilgang til å opprette nye noder, og slette de eksisterende, men de vil ikke kunne publisere disse endringene. Nye forvaltere kan legges til ved å skrive inn NAV-identene deres.
• Nivåer - et hierarki definerer en liste av kodeverk som dikterer hvilke koder man kan velge mellom når man oppretter noder for det gitte nivået i hierarkiet. Nivåene kan endres helt frem til hierarkiet har blitt publisert for første gang.

Opprette en node

🔒 Hvem kan gjøre dette: Administrator, hierarkieier, hierarkiforvalter

Treet til venstre på siden om et gitt hierarki viser strukturen på hierarkiet. Etter å ha navigert deg frem til en konkret node i treet kan du trykke på knappen som heter “Legg til ny hierarkinode” til høyre på siden. Den åpner en modal som lar deg velge hvilken kode det skal opprettes en node for. Kodene stammer fra kodeverket som er definert på de forskjelige nivåene i hierarkiet.

Slette en node

🔒 Hvem kan gjøre dette: Administrator, hierarkieier, hierarkiforvalter

Treet til venstre på siden om et gitt hierarki viser strukturen på hierarkiet. Etter å ha navigert deg frem til en konkret node i treet ser du en tabell med undernodene for den valgte noden. Hver av disse undernodene har en søppelkasseknapp i “Handlinger”-kolonnen. Denne lar deg fjerne undernoden fra treet. Husk at alle undernoder av noden du sletter også blir slettet.

Publisere endringer

🔒 Hvem kan gjøre dette: Administrator, hierarkieier

Det finnes en knapp som heter “Publiser hierarki” oppe i det høyre hjørnet på siden om et gitt hierarki. Denne åpner en modal som har deg inspisere endringene som har blitt gjort siden forrige gang hierarkeit ble publisert. Herfra kan du også velge å publisere alle disse endringene ved å trykke på knappen som heter “Publiser”. Alle endringene vil da bli tilgjengeliggjort på tjenestene som Navs applikasjoner benytter seg av.

For kodeverkseiere og ‐forvaltere

Oppdatere kodeverksdetaljer

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier

Det finnes en knapp som heter “Rediger kodeverk” oppe i det høyre hjørnet på siden om et gitt kodeverk. Denne åpner en modal som lar deg gjøre endringer på kodeverksdetaljene.

• Navn - navnet på kodeverket kan endres helt til det har blitt publisert for første gang.
• Beskrivelse - litt informasjon om hva kodeverket faktisk er, slik at potensielle konsumenter kan avgjøre om de kan ta det i bruk eller ikke.
• Eier - dersom kodeverket har behov for en ny eier kan NAV-identen til den nye eieren skrives inn her. NB: Et kodeverk kan bare ha én eier, så når denne endres vil den forrige eieren miste eierskapet, og kan derfor ikke lenger gjøre videre endringer på kodeverket.
• Forvaltere - et kodeverk kan ha opptil flere forvaltere. Disse vil ha tilgang til å opprette nye koder, og gjøre endringer på eksisterende, men de vil ikke kunne publisere disse endringene. Nye forvaltere kan legges til ved å skrive inn NAV-identene deres.

Opprette en ny kode

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier, kodeverksforvalter

Det finnes en knapp som heter “Legg til ny kode” oppe i det høyre hjørnet på siden om et gitt kodeverk. Denne åpner en modal som lar deg fylle inn detaljer om den nye koden du ønsker å legge inn.

• Navn - navnet på koden slik Navs applikasjoner skal forholde seg til den, f.eks NOR. For enkelhets skyld anbefaler vi å unngå spesialtegn i den grad det er mulig. Navnet kan endres helt til koden er blitt publisert for første gang.
• Startdato - starten på gyldighetsperioden til den nye koden på formatet DD.MM.YYYY.
• Sluttdato - slutten på gyldighetsperioden til den nye koden på formatet DD.MM.YYYY. Det finnes også en sjekkboks som heter “Ingen sluttdato” som fungerer som en snarvei til å sette sluttdatoen til 31.12.9999, som ofte tolkes som “åpen gyldighetsperiode”.
• Beskrivelse - en kodes gyldighetsperiode må ha en menneskeleselig tekstlig beskrivelse på bokmål. I tillegg kan man legge til beskrivelser på nynorsk, engelsk og samisk.

Oppdatere en kode

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier, kodeverksforvalter

For hver kode som ikke er publisert enda finnes det en blyantknapp i kolonnen “Handlinger” i tabellen på siden om et gitt kodeverk. Denne åpner en modal som lar deg endre navnet på koden. Denne muligheten forsvinner når koden er blitt publisert.

Opprette en gyldighetsperiode for en kode

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier, kodeverksforvalter

Det finnes en knapp som heter “Legg til ny gyldighetsperiode” oppe i det høyre hjørnet på siden om en gitt kode. Denne åpner en modal som lar deg legge til fylle inn detaljer om den nye gyldighetsperioden som du ønsker å legge inn.

• Startdato - starten på den nye gyldighetsperioden på formatet DD.MM.YYYY.
• Sluttdato - slutten på den nye gyldighetsperioden på formatet DD.MM.YYYY. Det finnes også en sjekkboks som heter “Ingen sluttdato” som fungerer som en snarvei til å sette sluttdatoen til 31.12.9999, som ofte tolkes som “åpen gyldighetsperiode”.
• Beskrivelse - en gyldighetsperiode må ha en menneskeleselig tekstlig beskrivelse på bokmål. I tillegg kan man legge til beskrivelser på nynorsk, engelsk og samisk.

Det kan hende at den nye gyldighetsperioden overlapper med en eksisterende gyldighetsperiode. I såfall vil den overlappende gyldighetsperioden vises nederst i modalen. Som standard blir overlappende gyldighetsperioder avsluttet dagen før startdatoen på den nye, men her vil man kunne velge å ikke gjøre denne endringen.

Oppdatere en gyldighetsperiode for en kode

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier, kodeverksforvalter

Det finnes en knapp som heter “Handlinger på gyldighetsperiode” til høyre for hver gyldighetsperiode på siden om en gitt kode. Denne lar deg velge mellom å opprette en ny menneskeleselig tekstlig beskrivelse av gyldighetsperioden på et annet språk, eller å endre på gyldighetsperiodens start- og sluttdatoer. I tillegg finnes det en blyantknapp ved siden av hver tekstlige beskrivelse som lar deg endre termen og teksten på de ulike språkene. Du kan også velge å slette beskrivelsen for et gitt språk ved å trykke på søppelbøtteknappen, men beskrivelsen for bokmål kan ikke slettes.

Slette en kode

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier, kodeverksforvalter

For hver kode som ikke er publisert enda så finnes det en søppelbøtteknapp i kolonnen “Handlinger” i tabellen på siden om et gitt kodeverk. Denne åpner en modal som lar deg slette koden. Denne muligheten forsvinner når koden er blitt publisert.

Publisere endringer

🔒 Hvem kan gjøre dette: Administrator, kodeverkseier

Det finnes en knapp som heter “Publiser endringer i kodeverk” oppe i det høyre hjørnet på siden om et gitt kodeverk. Denne åpner en modal som lar deg inspisere endringene som har blitt gjort siden forrige gang kodeverket ble publisert. Herfra kan du også velge å publisere alle disse endringene ved å trykke på knappen som heter “Publiser”. Alle endringene vil da bli tilgjengeliggjort på tjenestene som Navs applikasjoner benytter seg av.