Fiks Arkiv

Maskinporten-klienter opprettes i selvbetjeningsportalen:

• For produksjonsmiljøet opprettes klienter fra: https://sjolvbetjening.samarbeid.digdir.no.
• For testmiljøet opprettes klienter fra: https://sjolvbetjening.test.samarbeid.digdir.no.

1. Start med å logge inn på kontoen din med valgt metode.
2. Når du er logget inn på kontoen din, vises organisasjonen du representerer i toppmenyen til høyre.

   

   Hvis du logget inn for å representere en syntetisk organisasjon, vil du også kunne endre den organisasjonen du representerer i nedtrekksmenyen på det elementet.

   

3. Velg Opprett klient-knappen for å begynne å opprette en ny klient for organisasjonen du representerer.
4. Velg Maskinporten på Legg til klient-siden.
5. På Legg til Maskinporten klient-siden fyll inn visningsnavn, beskrivelse og legg til dine nødvendige scopes (disse verdiene kan også endres senere). Klikk deretter Opprett-knappen.

   

6. Du har nå opprettet en Maskinporten-klient for din organisasjon. For å bruke denne klienten må du legge til minst én autentiseringsnøkkel. Klienten støtter JWK- og PEM-nøkler. Start med å enten finne en eksisterende nøkkel eller opprette en ny. Du kan bruke Altinn JWKS-verktøyet eller annen nøkkelgenerator du ønsker til dette formålet. Naviger deretter til nøkkelseksjonen på klientsiden din og velg Legg til.

   

   I feltet JWK eller PEM format lim inn din offentlige nøkkel og klikk Lagre. Nøkkelen er nå lagt til klienten. Lagre din private nøkkel fra din JWK eller PEM på et sikkert sted, da den brukes til å autorisere bruken av denne klienten. Hvis du bruker Azure Key Vault for å lagre dine private nøkler, må de være base64-kodet før opplasting.

   

7. Hvis du ikke gjorde det i trinn 5, må du legge til ønskede scopes til klienten din før den kan brukes.

   

   

Forutsetninger

• OpenSSL installert på maskinen din.
  Et raskt Google-søk vil peke deg til installasjonsanvisninger for ditt operativsystem.

1. Generer SSL-sertifikat og privatnøkkel

   Åpne en konsoll der openssl er tilgjengelig, naviger til en passende katalog, og kjør kommandoen:

   openssl req -x509 -newkey rsa:2048 -nodes -keyout private.pem -out public.pem -days 720
   

   Forklaring av flagg

   • req -x509: Generer et X.509-sertifikat.
   • -newkey rsa:2048: Opprett en ny RSA-nøkkel med 2048-bit kryptering.
   • -nodes: Ikke krypter privatnøkkelen.
   • -keyout private.pem: Skriv privatnøkkel til private.pem.
   • -out public.pem: Skriv sertifikat til public.pem.
   • -days 720: Gyldig i 720 dager.

   Svar på eventuelle spørsmål med verdier som representerer din organisasjon, eller la dem stå tomme hvis du foretrekker det.

   Resultat: To filer vil bli opprettet i katalogen:

   • public.pem (sertifikat)
   • private.pem (privatnøkkel)

2. Base64-kode privatnøkkelen

   Windows

   Bruk certutil til å kode privatnøkkelen:

   certutil -encode -f "private.pem" "privatebase64.txt"
   

   Dette genererer en fil privatebase64.txt som inneholder privatnøkkelen som en Base64-kodet streng.

   Linux / macOS Bruk base64-kommandoen:

   base64 private.pem > privatebase64.txt
   

   Dette oppretter privatebase64.txt med den Base64-kodede privatnøkkelen.

Merknader

• Hold privatnøkkelen din sikker. Ikke del private.pem eller dens Base64-representasjon offentlig.
• Det genererte sertifikatet (public.pem) kan distribueres etter behov.

Feilsøking

• OpenSSL ikke funnet: Sørg for at det er installert og lagt til i system-PATH.
• Tillatelsesproblem: Kjør kommandoene med passende rettigheter eller i en katalog der du har skrivetilgang.
• Ugyldig Base64-utdata: Bekreft at den opprinnelige filen eksisterer og er lesbar før koding.

Klient-id for Maskinporten-klienten generert i steg 1 og den base64-kodede offentlige og private nøkkelen bør legges til som ClientId og JwkBase64 i MaskinportenSettings-seksjonen.

Konfigurasjonseksempel

• Seksjonsnavn: MaskinportenSettings
• Service-registrering:

services
    .AddFiksArkiv()
    .WithMaskinportenConfig("MaskinportenSettings");

Application settings

"MaskinportenSettings": {
    "Authority": "https://[test.]maskinporten.no/",
    "ClientId": "retrieved from secrets",
    "JwkBase64": "retrieved from secrets"
}

Key Vault Secrets

• MaskinportenSettings--ClientId
• MaskinportenSettings--JwkBase64

For at applikasjonen skal kunne lese hemmelighetene fra Azure Key Vault, må den konfigureres til å gjøre det. Se hemmeligheter-seksjonen for å oppnå dette.

Merk: Hemmelighetene leses av applikasjonen ved oppstart, så hvis du gjør endringer etter at applikasjonen er publisert, må du publisere applikasjonen på nytt for at de skal tre i kraft.

Konfigurasjonseksempel

Det anbefales å lagre alle sensitive FiksIO-innstillingsverdier sikkert i Azure Key Vault eller hemmelighetsadministrasjonsleverandøren som brukes av applikasjonen din.

• Seksjonsnavn: FiksIOSettings
• Service-registrering:

services
    .AddFiksArkiv()
    .WithFiksIOConfig("FiksIOSettings");

Application settings

"FiksIOSettings": {
    "AccountId": "c3c87fac-06be-44ed-a11c-aa137d12863c",
    "IntegrationId": "08b3d8b9-5026-46dc-936c-8e6709efa72c",
    "IntegrationPassword": "retrieved from secrets",
    "AccountPrivateKeyBase64": "retrieved from secrets"
}

Key Vault Secrets

• FiksIOSettings--IntegrationPassword
• FiksIOSettings--AccountPrivateKeyBase64

Service-registrering

• Seksjonsnavn: FiksArkivSettings
• Service-registrering:

services
    .AddFiksArkiv()
    .WithFiksArkivConfig("FiksArkivSettings");

Overordnet struktur

FiksArkivSettings
├─ Receipt
│  ├─ ConfirmationRecord
│  └─ ArchiveRecord
├─ Recipient
│  ├─ FiksAccount
│  ├─ Identifier
│  ├─ Name
│  └─ OrganizationNumber
├─ Metadata
│  ├─ SystemId
│  ├─ RuleId
│  ├─ CaseFileId
│  ├─ CaseFileTitle
│  └─ JournalEntryTitle
├─ Documents
│  ├─ PrimaryDocument
│  └─ Attachments{}
├─ ErrorHandling
│  ├─ MoveToNextTask
│  └─ Action
└─ SuccessHandling
   ├─ MoveToNextTask
   ├─ Action
   └─ MarkInstanceComplete

Videre bryter vi ned hver underseksjon av FiksArkivSettings, viser hvordan verdier bindes (statisk vs. dynamisk), og gir et komplett appsettings.json-eksempel.

Seksjoner og innstillinger

• Receipt (FiksArkivSettings.Receipt)

  Innstillinger relatert til postene som opprettes etter en vellykket forsendelse.

  Merk: Datatypene som defineres her må ha tilsvarende oppføringer i datatype-definisjonen i applicationmetadata.

  Innstillingsnavn	Formål	Format
  ConfirmationRecord	Definerer datatypen og navnet for arkivkvitteringen.	{ "DataType": "string", "Filename": "string" }
  ArchiveRecord	Definerer datatypen og navnet for arkivmeldingen.	{ "DataType": "string", "Filename": "string" }

  Eksempel på konfigurasjon:

"FiksArkivSettings": {
  "Receipt": {
    "ConfirmationRecord": {
      "DataType": "fiks-receipt",
      "Filename": "Arkivkvittering.xml"
    },
    "ArchiveRecord": {
      "DataType": "fiks-archive-record", 
      "Filename": "Arkivmelding.xml"
    }
  }
}

{
  "dataTypes":[
    {
      "id": "fiks-receipt",
      "allowedContributers": [ "app:owned" ],
      "maxCount": 1,
      "minCount": 0,
      "enablePdfCreation": false,
      "enableFileScan": false,
      "validationErrorOnPendingFileScan": false
    },
    {
      "id": "fiks-archive-record",
      "allowedContributers": [ "app:owned" ],
      "maxCount": 1,
      "minCount": 0,
      "enablePdfCreation": false,
      "enableFileScan": false,
      "validationErrorOnPendingFileScan": false
    }
  ]
}

• Recipient (FiksArkivSettings.Recipient)

  Innstillinger relatert til hvem som skal motta Fiks Arkiv-meldingen.

  Innstillingsnavn	Formål	Type
  FiksAccount	Mottaker-konto GUID som meldinger skal sendes til.	GUID (påkrevd)
  Identifier	Mottaker-identifikator (f.eks. kommunenummer).	string (påkrevd)
  Name	Mottakernavn.	string (påkrevd)
  OrganizationNumber	Valgfritt organisasjonsnummer for mottaker.	string (valgfritt)

  Mottaker-innstillinger støtter både statiske og dynamiske konfigurasjonsformater - se Hvordan verdier oppgis for syntaks og bruk DataModelBinding når felt varierer per instans.

  Eksempel på konfigurasjon:

  "FiksArkivSettings": {
    "Recipient": {
      "FiksAccount": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.AccountId"
        }
      },
      "Identifier": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.Identifier"
        }
      },
      "OrganizationNumber": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.OrgNumber"
        }
      },
      "Name": {
        "DataModelBinding": {
          "DataType": "HelperDataModel",
          "Field": "Recipient.Name"
      }
    }
  }
}

• Metadata (FiksArkivSettings.Metadata)

  Kontekstuell informasjon brukt av arkivsystemet.

  Innstillingsnavn	Formål	Standardatferd
  SystemId	System-ID brukt i den genererte arkivmelding.xml.	Standard til Altinn Studio hvis ikke oppgitt.
  RuleId	Valgfri regel-ID for behandling av innkommende melding i systemer som støtter regel-IDer.	Utelatt hvis ikke oppgitt.
  CaseFileId	ID for den genererte saksmappen (saksmappe element).	Standard til instansidentifikatoren hvis ikke oppgitt.
  CaseFileTitle	Tittel for det genererte saksmappe tittel elementet.	Standard til applikasjonstittel hvis ikke oppgitt.
  JournalEntryTitle	Tittel for det genererte journalpost tittel elementet.	Standard til applikasjonstittel hvis ikke oppgitt.

  Metadata støtter både statiske og dynamiske konfigurasjonsformater - se Hvordan verdier oppgis for syntaks og bruk DataModelBinding når felt varierer per instans.

  Eksempel på konfigurasjon:

"FiksArkivSettings": {
  "Metadata": {
   "JournalEntryTitle": {
      "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "JournalEntryTitle"
      }
    },
    "CaseFileTitle": {
      "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "CaseFileTitle"
      }
    }
  }
}

• Documents (FiksArkivSettings.Documents)

Definisjon av dokumentene som skal inkluderes i arkivmeldingen (arkivmelding) som sendes til Fiks Arkiv.

Hver dokumentoppføring bruker typisk DataType for å indikere kilde og/eller format. For eksempel "ref-data-as-pdf" for en PDF generert fra referansedata.

Eksempel på konfigurasjon:

"FiksArkivSettings": {
  "Documents": {
    "PrimaryDocument": {
      "DataType": "ref-data-as-pdf"
    },
    "Attachments": [
      {
        "DataType": "DataModel"
      },
      {
        "DataType": "vedlegg-datatype"
      }
    ]
  }
}

• ErrorHandling (FiksArkivErrorHandlingSettings)

Hva applikasjonen skal gjøre når et sendingsforsøk feiler.

Eksempel på konfigurasjon:

"FiksArkivSettings": {
  "ErrorHandling": {
    "MoveToNextTask": true
  }
}

• SuccessHandling (FiksArkivSuccessHandlingSettings)

Hva applikasjonen skal gjøre når et sendingsforsøk lykkes.

Eksempel på konfigurasjon:

"FiksArkivSettings": {
  "SuccessHandling": {
      "MoveToNextTask": true,
      "MarkInstanceComplete": true
  }
}

Praktiske tips

• Start enkelt: Konfigurer Recipient og Metadata først; legg til Documents og Receipt detaljer etter behov.
• Bruk binding for variabilitet: Foretrekk DataModelBinding for felt som varierer per instans eller miljø.
• Husk standardverdier: Hvis du utelater visse metadatafelt, brukes fornuftige standardverdier (som applikasjonstittel).
• Handlinger og flyt: Sett ErrorHandling og SuccessHandling til å samsvare med prosessen din (f.eks. gå til neste oppgave, merk instans som fullført).

Hvordan verdier oppgis

Hver innstilling kan oppgis på en av to måter:

1. Statisk (hardkodet) verdi

   "JournalEntryTitle": {
     "Value": "Hallo"
   }
   

2. Dynamisk verdi via datamodell-binding

   "CaseFileTitle": {
     "DataModelBinding": {
       "DataType": "HelperDataModel",
       "Field": "CaseFileTitle"
     }
   }
   

Bruk Value når du kjenner teksten på forhånd; bruk DataModelBinding når verdier skal komme fra runtime-dataene dine (f.eks. felt samlet inn i et skjema eller hjelpemodell).

Feilsøking

• Manglende titler: Hvis journalpost- eller saksmappetitler er tomme, sjekk at din DataModelBinding peker til eksisterende felt, eller oppgi en Value.
• Feil mottaker: Bekreft at FiksAccount inneholder en gyldig GUID og samsvarer med den tiltenkte mottakeren.
• Vedleggsoppløsning: Sørg for at hver vedleggs DataType er definert i applicationmetadata.