Vardef-forvaltning

Sist endret

June 4, 2025

Warning

Denne siden er under arbeid frem til Vardef er i produksjon.

Vardef-forvaltning er en tjeneste på Dapla Lab som lar brukere forvalte informasjon i Vardef med ferdiglagde notebooks i en instans av Jupyterlab. Tjenesten kommer med Python, dapla-toolbelt-metadata og tilhørende avhengigheter ferdig installert. I tillegg er det opprettet en kernel med navn variable_definitions som lar brukerne jobbe med Vardef uten noen ytterligere oppsett.

Notebooks’ene som ligger inne i tjenesten inneholder dokumentasjon for vanlige brukerflyter i Vardef. Les mer notebooks’ene under Funksjonalitet senere i artikkelen.

Forberedelser

Før man starter Vardef-forvaltning bør man ha lest kapitlet om Dapla Lab og gjort seg godt kjent med dokumentasjonen til Vardef. Deretter gjør du følgende:

Logg deg inn på Dapla Lab
Under Tjenestekatalog trykker du på Start-knappen for Vardef-forvaltning
Gi tjenesten et navn
Velg hvilket team og tilgangsgruppe du ønsker å representere (se Konfigurasjon)
Trykk Start når du er klar for å starte tjenesten

Konfigurasjon

Den eneste konfigurasjonen som må gjøres i Vardef-forvaltning er å velge hvilket team og tilgangsgruppe man ønsker å representere når man jobber i tjenesten. Dette er måten Vardef håndterer tilgangsstyring og det er viktig å være klar over når man jobber med Vardef fra Dapla Lab. Siden variabeldefinisjoner i Vardef forvaltes av team, så må man velge riktig team og tilgangsgruppe under Data i tjenestekonfigurasjonen før man starter tjenesten. F.eks. hvis dapla-felles-developers forvalter variabeldefinisjonen fnr, så må jeg velge dapla-felles-developers under Data før jeg starter tjenesten. Og tilsvarende hvis jeg ønsker å opprette en ny variabeldefinisjon, så må jeg representere det teamet jeg ønsker at skal forvalte variabeldefinisjonen før jeg oppretter den.

Funksjonalitet

Vardef-forvaltning er en tilrettelagt variant av Jupyter. Når man åpner tjenesten så er følgende tilrettelagt for brukeren:

dapla-toolbelt-metadata er installert
en kernel med navnet variable_definitions er opprettet
flere ferdigskrevne notebooks er installert (lenke i høyre marg)

Notebooks’ene består av kode og beskrivelser for vanlige brukerflyter i Vardef. F.eks. migrere fra Vardok, opprette ny variabeldefinisjon, redigere utkast, osv.. I hver notebook benyttes dapla-toolbelt-vardef til å jobbe mot Vardef. På den måten slipper brukerne i stor grad å skrive kode selv, og de kan benytte koden som finnes til utvikling av ny kode.

Migrere fra Vardok

Ønsker man å migrere en eller flere variabeldefinisjoner kan man kjøre notebooken migrer_variabeldefinisjoner.ipynb.

I variabelen min_id_liste som du finner i cellen nedenfor overskriften “Hente variabeldefinisjoner fra Vardok”, må det settes inn en eller flere variabeldefinisjons-ID’er. Alle seksjonsledere har oversikt over hvilke ID’er fra Vardok som deres seksjon er ansvarlig for. Kjør deretter gjennom notebook’en. Det vil skrives ut en oppsummering over hva som blir migrert.

Når notebook’en er kjørt gjennom så er variabeldefinisjonene migrert fra Vardok til Vardef, der de får status Utkast. I denne prosessen oppdaterer dapla-toolbelt-metadata all informasjon som kan utledes automatisk, og deretter må brukeren oppdatere gjenværende informasjon før de publiserer den internt eller eksternt.

Oppdatere utkast

Et utkast kan oppdateres ved å kjøre notebooken rediger_utkast_variabeldefinisjon.ipynb. Den skriver variabeldefinisjonen ned til en fil som brukeren kan gjøre endringer i. Når endringene er gjort, så kan man oppdatere utkastet i slutten av notebooken.

Publisere utkast

Når brukeren er fornøyd med utkastet og ønsker å publisere, så kan man velge å publisere internt eller eksternt. Ved migrering av tidligere eksternt publiserte definisjoner fra Vardok, så er hovedregelen at også man publiserer variabeldefinisjonen eksternt i Vardef.

Man kan publisere en variabeldefinisjon eksternt ved å kjøre notebook’en publiser_variabeldefinisjon_eksternt.ipynb.

Man kan publisere en variabeldefinisjon internt ved å kjøre notebook’en publiser_variabeldefinisjon_internt.ipynb.

Ny variabeldefinisjon

For å opprette en ny variabeldefinisjon må man først opprette et utkast, deretter redigere utkastet og til slutt publisere. Da vil man bruke følgende notebooks:

Ny gyldighetsperiode

Ny gyldighetsperiode i Vardef betyr at man ønsker å gjøre endringer i en eksisterende variabeldefinisjon som gjør at den får en ny betydning. Dette betyr at definisjonsteksten endres, og denne endringen krever at den får en ny gyldighetsperiode. Dette kan kun gjøres på variabeldefinisjoner som allerede er publisert internt eller eksternt.

For opprette en ny gyldighetsperiode kan man kjøre gjennom notebooken ny_gyldighetsperiode_variabeldefinisjon.ipynb.

Her blir man bedt om å oppgi kortnavnet til variabeldefinisjonen som skal ha ny gyldighetsperiode, deretter skrives den til en fil hvor endringer kan gjøres. Til slutt oppdateres variabeldefinisjonen i Vardef.

Mindre endringer (patch)

En patch i Vardef er en mindre endring som ikke endrer betydningen av variabeldefinisjonen. Man kan opprette en patch ved å kjøre notebook’en rediger_publisert_variabeldefinisjon.ipynb.

Lese ut informasjon

For å hente ut informasjon fra Vardef finnes det ulike notebooks avhengig av hva man ønsker å hente ut.

En variabeldefinisjon

Notebooken les_variabeldefinisjon.ipynb lar deg hente ut informasjon om en konkret variabeldefinisjon. Man kan hente ut all informasjon om variabeldefinisjonen, eller hente ut noen få informasjonselementer.

Alle variabeldefinisjoner

Notebooken les_variabeldefinisjoner.ipynb lar deg hente ut informasjon om alle variabeldefinisjoner og filtrere disse basert på ulike kriterier.

Ledige kortnavn

Notebooken sjekk_kortnavn_variabeldefinisjon.ipynb lar deg sjekke om et kortnavn er tatt eller ikke. Kortnavn i Vardef må være unikem, så det kan være lurt å sjekke om ønsket kortnavn er ledig før man prøver å publisere.

Arbeide med YAML-filer

Caution

Fargene i YAML-eksemplene er kun veiledende og kan variere fra verktøy til verktøy, ettersom de settes av automatisk syntaksutheving.

YAML-filstruktur

YAML-filene følger samme grunnstruktur, med små variasjoner avhengig av bruk.

Mal

Denne filen genereres når du vil opprette en ny variabeldefinisjon.

# --- Variabeldefinisjon mal ---

Filnavn mal

Lagres som variable_definition_template_<timestamp>.yaml

NB! Innholder eksempelverdier som må endres

contact:
    title:
        nb: |-
            generert tittel
        nn:
        en:

I noen tilfeller settes verdien automatisk av systemet. For eksempel:

variable_status: DRAFT

Variabeldefinisjon

Dette er en YAML-fil med alle lagrede verdier for en variabeldefinisjon.

# --- Variabeldefinisjon ---

Filnavn variabeldefinisjon

Lagres som variable_definition_<kortnavn>_<id>_<timestamp>.yaml

Redigere YAML-filen

Enkle verdier

Verdien skrives på samme linje som feltnavn (nøkkel)
Bruk doble fnutter ""

Felt med enkle verdier

classification_reference
measurement_type
external_reference_uri
owner.team

Korrekt plassering og format

short_name: "landbak"

measurement_type: "03"

Vanlige feil enkle verdier

Feil plassering av verdi

measurement_type: 
"03"

Feil innrykk mellom nøkkel og verdi

classification_reference:"91"

Mangler kolon

short_name"landbak"

Feil verdi type

# Hvis fnuttene fjernes vil verdien tolkes som et tall og validering vil feile.
measurement_type: 03

Flerspråklige felt

Et blokk symbol |- følger feltnavn(nøkkel).
Teksten må starte rett under blokk-symbolet
Riktig innrykk er viktig
Formattering (avsnitt/linjeskift) lagres.

Flerspråklige felt

name
definition
comment
contact.title

Korrekt plassering av tekst under blokk-symbol

contact:
    title:
        nb: |-
            Her starter teksten akkurat under blokk symbolet og vil lagres uten feil.
        nn:
        en:
    email: generert@ssb.no

Korrekt lagring av avsnitt

comment:
    nb: |-
        Her er det en god plan, først er det en beskrivelse som innledning.

        Deretter bevisst en blank linje:
          - Liste-element 1
          - Liste-element 2
    nn:
    en:

Bruk av spesialtegn

name:
    nb: |-
        Her er kan vi lagre spesialtegn som : men det kan føre til feil syntaksutheving.
    nn:
    en:

Vanlige feil flerspråklige felt

Uønsket tekstoppsett (linjeskift midt i ord)

name:
    nb: |-
        Her deles teksten opp
        plutselig. Og den vil lagres akku-
        rat slik du ser den.
    nn:
    en:

Feil indentering (mangler korrekt innrykk)

name:
    nb: |-
Her er teksten ikke indentert og vil føre til feil når du lagrer.
    nn:
    en:

Mangler blokk-symbolet

comment:
    nb: Her er blokk symbolet fjernet og tekst med ':' vil feile.
    nn:
    en: Also text with paragraphs
    will not be saved correctly.

Lister

Verdien skrives på samme linje som liste-symbolet -
Bruk doble fnutter ""

Felt med lister

unit_types
subject_fields
related_variable_definition_uris
owner.groups

Korrekt listeformat og indentering

unit_types:
    - "20"

Vanlige feil lister

Feil type i listeelementer

unit_types:
    - 01
    - 02

Feil indentering på liste-symbol

unit_types:
- "20"

Feil indentering ved listeverdi

subject_fields:
  -"bf"

Andre typer

Dato

valid_from: 2003-01-01

Boolean

contains_special_categories_of_personal_data: true

Variabel status


variable_status: DRAFT

variable_status: PUBLISHED_INTERNAL

variable_status: PUBLISHED_EXTERNAL

YAML-fil: Ny variabeldefinisjon

# --- Variabeldefinisjon mal ---
name:
    nb: |-
        Buss
    nn:
    en:
short_name: "bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn:
    en:
classification_reference:
unit_types:
    - "15"
subject_fields:
    - "tr01"
contains_special_categories_of_personal_data: false
measurement_type:
valid_from: 2025-04-01
valid_until:
external_reference_uri:
comment:
related_variable_definition_uris:
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn:
        en:
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: DRAFT

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-01-11 08:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Redigere utkast

Endre:

short_name
contains_special_categories_of_personal_data

Legge til:

classification_reference
external_reference_uri
subject_fields

# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss
    nn:
    en:
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn:
    en:
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type:
valid_from: 2025-01-01
valid_until:
external_reference_uri: "https://www.norges-motorvignforbund.no"
comment:
related_variable_definition_uris:
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn:
        en:
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: DRAFT

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-01-11 08:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Redigere publisert

Endre:

Rette skrivefeil i external_reference_uri

Legge til:

verdier på norsk nynorsk og engelsk:
- name
- definition
- contact.title
owner.groups
related_variable_definition_uris
measurement_type

# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss 
    nn: |-
        Buss
    en: |-
        Bus
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte mange passasjerer.
    nn: |-
        Buss er eit køyretøy som er spesialkonstruert for å frakte mange passasjerar.
    en: |-
        A bus is a motor vehicle that is specially designed to carry many passengers.
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type: "02"
valid_from: 2025-01-01
valid_until:
external_reference_uri: "https://www.norges-motorvognforbund.no"
comment:
related_variable_definition_uris:
    - "https://example.com/"
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn: |-
            Seksjon for Nærings- og miljøstatistikk
        en: |-
            Section for Industrial and Environmental Statistics
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: PUBLISHED_INTERNAL

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"
        - "arbmark-aku-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 1
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-03-25 10:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

YAML-fil: Ny gyldighetsperiode

Legge til:

comment

Endre:

valid_from
definition

# --- Variabeldefinisjon ---
name:
    nb: |-
        Buss 
    nn: |-
        Buss
    en: |-
        Bus
short_name: "reg_bus"
definition:
    nb: |-
        Buss er en motorvogn som er spesialkonstruert for å frakte flere enn 
        16 passasjerer.
    nn: |-
        Buss er eit køyretøy som er spesialkonstruert for å frakte flere enn 
        16 passasjerar.
    en: |-
        A bus is a motor vehicle that is specially designed to carry more than 
        16 passengers.
classification_reference: "111"
unit_types:
    - "15"
subject_fields:
    - "tr01"
    - "tr04"
contains_special_categories_of_personal_data: true
measurement_type: ""
valid_from: 2025-06-01
valid_until:
external_reference_uri: "https://www.norges-motorvognforbund.no"
comment:
    nb: |-
        Krav til spesifikasjon av antall passasjerer i en buss for å skille "buss" fra "minibuss".
    nn: |-
        Krav til spesifikasjon av talet på passasjerar i ein buss for å skilje 
        mellom «buss» og «minibuss».
    en: |-
        Requirements for specification of the number of passengers in a bus to distinguish 
        "bus" from "minibus".
related_variable_definition_uris:
    - "https://example.com/"
contact:
    title:
        nb: |-
            Seksjon for Nærings- og miljøstatistikk
        nn: |-
            Seksjon for Nærings- og miljøstatistikk
        en: |-
            Section for Industrial and Environmental Statistics
    email: s400@ssb.no

# --- Statusfelt. Verdi 'DRAFT' før publisering. Ikke rediger hvis du oppretter en ny variabeldefinisjon. ---
variable_status: PUBLISHED_INTERNAL

# --- Eierteam og grupper. Ikke rediger hvis du oppretter en ny variabeldefinisjon, verdien genereres ---
owner:
    team: "aordning-register"
    groups:
        - "aordning-register-developers"
        - "arbmark-aku-developers"

# --- Maskin-genererte felt. Ikke rediger. ---
id: "wypvb3wd"
patch_id: 2
created_at: 2025-01-11 08:15:19.038000+00:00
created_by: "ano@ssb.no"
last_updated_at: 2025-04-05 11:15:19.038000+00:00
last_updated_by: "ano@ssb.no"

Slette tjenesten

For å slette tjenesten kan man trykke på Slette-knappen i Dapla Lab under Mine tjenester. Når man sletter en tjeneste så sletter man hele disken inne i tjenesten og frigjør alle ressurser som er reservert. Vi anbefaler at man avslutter heller pauser tjenester som ikke benyttes.

Pause tjenesten

Man kan pause tjenesten ved å trykke på Pause-knappen i Dapla Lab under Mine tjenester. Når man pauser så slettes alt påden lokale disken som ikke er lagret under $HOME/work. Vi anbefaler at man avslutter heller pauser tjenester som ikke benyttes.

Monitorering

Man kan moniterere en instans av Jupyter ved å trykke på Jupyter-teksten under Mine tjenester i Dapla Lab, slik som vist i Figur 1.

Denne funksjonaliteten er under arbeid og mer informasjon kommer snart.

Viser Persitence-fanen i Jupyter-konfigurasjonen i Dapla Lab. — Figur 1: Monitorering av Jupyter-tjenesten i Dapla Lab