Gå til hovedinnhold

Folkeregister (FREG) integrasjon

Denne dokumentasjonen beskriver hvordan batch-applikasjonen integrerer med Folkeregisteret (FREG) for å holde persondata i FS oppdatert.

Oversikt​

Folkeregister-integrasjonen er en batch-jobb som periodisk synkroniserer persondata mellom Folkeregisteret og FS. Integrasjonen håndterer tre hovedtyper av hendelser:

  1. Navnendringer - Oppdaterer personnavn når disse endres i Folkeregisteret
  2. Fødselsnummer/D-nummer endringer - Håndterer endringer i personidentifikatorer
  3. Dødsfall - Registrerer når personer er døde

Arkitektur​

Komponenter​

Folkeregister-integrasjonen består av følgende hovedkomponenter:

Scheduler
┌─────────────────────────────────────────────────┐
│  - Starter jobber med konfigurert intervall     │
│  - Håndterer flere institusjoner parallelt      │
└─────────────────────────┬───────────────────────┘
                          │
                          |
folkeregister.xml         V
┌─────────────────────────────────────────────────┐
│  - JBeret jobb-definisjon                       │
│  - Parametrisert for gjenbruk                   │
└─────────────────────────┬───────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        V                 V                 V
     Reader          Processor           Writer
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Les hendelser│ │ Filtrer      │ │ Oppdater FS  │
│ fra FREG API │ │ hendelser    │ │ via GraphQL  │
└──────────────┘ └──────────────┘ └──────────────┘

Jobben struktur​

Jobben er definert i XML-filen src/main/resources/META-INF/batch-jobs/folkeregister.xml:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<job xmlns="http://xmlns.jcp.org/xml/ns/javaee" id="folkeregister" version="1.0">
    <properties>
        <property name="eierOrganisasjonskode" value="#{jobParameters['eierOrganisjonskode']}"/>
        <property name="jobbtype" value="#{jobParameters['jobbtype']}"/>
        <property name="scope" value="OFFENTLIG_UTEN_HJEMMEL"/>
        <property name="startdato" value="#{jobParameters['startdato']}"/>
    </properties>
    <step id="folkeregisterSynkroniser">
        <chunk item-count="50">
            <reader ref="folkeregisterItemReader"/>
            <processor ref="#{jobParameters['jobbtype']}Processor"/>
            <writer ref="#{jobParameters['jobbtype']}Writer"/>
        </chunk>
    </step>
</job>

Implementasjonsklasser​

ItemReader​

FolkeregisterItemReader (src/main/java/no/fellesstudentsystem/batch/folkeregister/job/FolkeregisterItemReader.java)

  • Henter hendelser fra Folkeregisteret via REST API
  • Bruker sekvensnummer for å holde styr på prosesserte hendelser
  • Sikrer at samme jobb ikke kjører parallelt for samme institusjon
  • Håndterer checkpoint/restart av jobber

Processors​

Hver jobbtype har sin egen processor som filtrerer relevante hendelser:

  • FolkeregisterNavnProcessor - Filtrerer ut navnendringshendelser
  • FolkeregisterFoedselsnummerProcessor - Filtrerer ut fødselsnummerendringer
  • FolkeregisterDoedsfallProcessor - Filtrerer ut dødsfallhendelser

Writers​

Hver jobbtype har sin egen writer som oppdaterer FS-plattformen:

  • FolkeregisterNavnWriter - Oppdaterer personnavn via GraphQL
  • FolkeregisterFoedselsnummerWriter - Oppdaterer fødselsnummer/D-nummer
  • FolkeregisterDoedsfallWriter - Registrerer dødsfall

Konfigurasjon​

Jobbtypene konfigureres per institusjon i application.properties. Her er et eksempel på en slik konfigurasjon:

# Eksempel konfigurasjon for institusjon 184 (UiB)
fs_batch.jobbtyper.institusjon.184 = folkeregisterFoedselsnummer,folkeregisterDoedsfall,folkeregisterNavn

# Intervall mellom kjøringer (minutter)
fs_batch.intervall_i_minutter = 30

# Startdato for nye institusjoner
fs_batch.startdato = 2024-01-01

# FREG API endpoint
folkeregister/mp-rest/url = https://folkeregisteret.api.skatteetaten.no/folkeregisteret/api/offentligutenhjemmel/v1

# Maskinporten autentisering
folkeregister.maskinporten.wellknown_url = https://maskinporten.no/
folkeregister.maskinporten.client_id = ${fs_batch_maskinporten_client_id}
folkeregister.maskinporten.kid = ${fs_batch_maskinporten_kid}
folkeregister.maskinporten.jwks = ${fs_batch_maskinporten_jwks}

Scheduler​

Jobbene starter automatisk ved applikasjonsoppstart. Scheduler.java bruker konfigurasjonen til å styre når og hvor mange ganger jobbene skal kjøres.

Dataflyt​

  1. Hendelsesinnhenting

    • ItemReader henter hendelser fra FREG API basert på sekvensnummer
    • Bruker OAuth2/Maskinporten for autentisering
    • Henter hendelser i batches (chunks)

  2. Prosessering

    • Processor filtrerer ut relevante hendelser basert på hendelsestype
    • Kun hendelser som matcher jobbtypens kriterier prosesseres

  3. Oppdatering

    • Writer henter berørte personer fra FS-plattformen via GraphQL
    • Henter oppdaterte data fra FREG for disse personene
    • Oppdaterer FS-plattformen med nye data

  4. Checkpoint

    • Sekvensnummer lagres i database for restart-støtte
    • Ved feil kan jobben restarte fra siste checkpoint

Database​

Infrastruktur​

Batch-applikasjonen bruker en felles PostgreSQL database som:

Tabeller​

  • folkeregisteret_jobb - Lagrer sekvensnummer per institusjon/jobbtype
  • JBeret tabeller - Standard JBeret tabeller for jobbhistorikk og checkpoint

Sikkerhet​

  • Maskinporten: Bruker OAuth2 med JWT for autentisering mot FREG
  • Scope: Bruker OFFENTLIG_UTEN_HJEMMEL for tilgang til offentlige data
  • Secrets: Hemmelige nøkler lagres i Vault og injiseres som miljøvariabler

Overvåking​

Logger​

Viktige loggmeldinger​

  • "Folkeregister jobb {jobbtype} for institusjon {kode} starter fra sekvensnummer {seq}" - Oppstart
  • "Fant {antall} hendelser fra FREG" - Antall hendelser hentet
  • "Oppdatert {antall} personer med nye navn" - Resultat av navneoppdatering
  • "Ingen av hendelser var navnendring" - Når ingen relevante hendelser finnes

Referanser​