Fiks Arkiv

Slik setter du opp Fiks Arkiv som systemoppgave i appen din.

I v9 er Fiks Arkiv en systemoppgave. Du legger den til som et steg i prosessen (process.bpmn), og appen sender arkivmeldingen når prosessen kommer til steget. Oppgaven venter selv på svaret fra arkivet, så du trenger ikke lenger en tilbakemeldingsoppgave etter den. Når svaret har kommet, går prosessen alltid videre: en eksklusiv gateway rett etter oppgaven skiller en bekreftet arkivering fra en avvist, og appen nekter å starte uten den.

Fiks Arkiv ligger i en egen NuGet-pakke, Altinn.App.Clients.Fiks, som du legger til i appen. Det skiller den fra PDF og eFormidling, som følger med Altinn.App.Core.

Forutsetninger

Før du setter opp Fiks Arkiv i appen, må du ha dette på plass:

• Fiks Protokoll aktivert i Fiks forvaltningsportalen for organisasjonen din.
• Tilgang i Samarbeidsportalen til å administrere Maskinporten-klienter for organisasjonen din. Altinn Studio bruker denne tilgangen når du logger inn med Ansattporten og legger Maskinporten-scopes til appen.
• Et arkivsystem som er integrert med Fiks Arkiv.

Slik fungerer oppgaven

Plattformen kjører oppgaven på serveren som tjenesteeier når prosessen kommer til steget. Oppgaven er delt i to: et arbeidssteg som sender arkivmeldingen, og en postkasse som tar imot svarene fra arkivet. Mekanismen er den samme som for andre systemoppgaver med flere steg.

Slik går det steg for steg:

1. Appen sender. Arbeidssteget henter mottakeren, lager arkivmelding.xml med hoveddokument og vedlegg fra instansdataene, og lagrer arkivmeldingen på instansen som datatypen i Receipt.ArchiveRecord. Så åpner det en postkasse og sender meldingen til mottakerkontoen gjennom Fiks IO. Postkassens id følger med som klientKorrelasjonsId, og det er den som gjør at svaret finner tilbake til riktig oppgave. Feiler noe underveis, prøver plattformen steget på nytt med samme innhold.
2. Arkivet svarer. Arkivsystemet sender først en mottaksbekreftelse (arkivmelding.opprett.mottatt) og deretter en kvittering (arkivmelding.opprett.kvittering) når saken er opprettet. Kan det ikke opprette saken, sender det en feilmelding i stedet.
3. Lytteren sender svaret videre. Appen lytter på Fiks IO-kontoen sin, leser klientKorrelasjonsId fra hver melding og leverer den til postkassen som venter. Meldinger uten korrelasjons-id blir logget og forkastet, siden ingen oppgave venter på dem.
4. Oppgaven konkluderer. Mottaksbekreftelsen holder oppgaven ventende. Kvitteringen lagres på instansen som datatypen i Receipt.ConfirmationRecord, instansen markeres som fullført med mindre du har slått det av, og prosessen går videre med handlingen i SuccessHandling.Action, som standard uten handling. En feilmelding fra arkivet sender prosessen videre med handlingen i ErrorHandling.Action, som standard reject. Gatewayen etter oppgaven skiller de to veiene. Kommer det ingen kvittering på 7 døgn, feiler oppgaven.

Mens oppgaven venter, ser brukeren lastevisningen. Ingen bruker eller tjenesteeier trenger å gjøre noe, og ingenting spør arkivet om status. Se Hva brukeren ser mens en systemoppgave kjører for hvordan du tilpasser ventingen og feilsiden.

Sette opp Fiks Arkiv i appen

Steg 1: Legg til Maskinporten-scopes i Altinn Studio

Legg til dette scopet på appen i Altinn Studio:

• ks:fiks

Fiks IO-klienten bruker appens innebygde Maskinporten-klient til å autentisere seg mot Fiks med dette scopet. Tjenesteeier-scopene mot Altinn-plattformen har alle v9-apper allerede, så dem trenger du ikke legge til. Når appen publiseres, oppretter Altinn Studio Maskinporten-klienten og legger innstillingene inn i appen.

Se Legge til scopes i Altinn Studio for fremgangsmåten.

Steg 2: Opprett en Fiks Arkiv-konto

• Generer et x509-sertifikat for Fiks Arkiv-kryptering.

  Formatkrav:

  • Offentlig del: PEM-fil, som du laster opp i Fiks Forvaltning.
  • Privat del: PEM-formatert streng, base64-kodet, som du legger inn som en secret for Altinn-appen.

  Bruk det verktøyet du foretrekker for å generere sertifikatet. En veiledning ligger nederst i dette steget.

• Sett opp et nytt system under Fiks Protokoll for organisasjonen din i Fiks Forvaltning. Se KS Digitals veiledning for systemoppsett.

• Opprett en konto knyttet til dette systemet. Se KS Digitals veiledning for kontooppsett.

  Kontoen skal ha disse egenskapene:

  Egenskap	Verdi
  Protokolltype	no.ks.fiks.arkiv
  Versjon	v1
  Protokollparter	klient.arkivering / klient.full*

  * Bruk klient.arkivering med mindre kontoen skal brukes til andre oppgaver også.

• Ta vare på disse verdiene til oppsettet av appen:

  • Integrasjons-ID og passord for Fiks-systemet
  • Konto-ID for Fiks-kontoen
  • Privat del av x509-sertifikatet som en base64-streng

Steg 3: Legg til pakken og registrer tjenestene

Legg til en referanse til NuGet-pakken Altinn.App.Clients.Fiks i prosjektfilen. Bruk samme versjon som for Altinn.App.Core og Altinn.App.Api.

<PackageReference Include="Altinn.App.Api" Version="9.0.0">
  <CopyToOutputDirectory>lib\$(TargetFramework)\*.xml</CopyToOutputDirectory>
</PackageReference>
<PackageReference Include="Altinn.App.Core" Version="9.0.0" />
<PackageReference Include="Altinn.App.Clients.Fiks" Version="9.0.0" />

Registrer så Fiks Arkiv-tjenestene og pek dem til konfigurasjonsseksjonene dine i RegisterCustomAppServices i Program.cs:

void RegisterCustomAppServices(IServiceCollection services, IConfiguration config, IWebHostEnvironment env)
{
    services
        .AddFiksArkiv()
        .WithFiksIOConfig("FiksIOSettings")
        .WithFiksArkivConfig("FiksArkivSettings");
}

Utvidelsesmetodene ligger i navnerommet Altinn.App.Clients.Fiks.Extensions, så husk using for dette.

AddFiksArkiv() registrerer alt oppgaven trenger: Fiks IO-klienten, lytteren som tar imot svar, generatoren som lager arkivmeldingen, og selve systemoppgaven. Fiks IO-klienten bruker appens innebygde Maskinporten-klient og trenger ingen egen Maskinporten-konfigurasjon. Du velger selv navnene på konfigurasjonsseksjonene, men de må stemme med seksjonsnavnene du bruker i appsettings.json og i Key Vault.

Steg 4: Legg til oppgaven i prosessen

Legg oppgaven inn i process.bpmn som en bpmn:serviceTask med oppgavetypen fiksArkiv, og legg en eksklusiv gateway rett etter den. Oppgaven går alltid videre når arkiveringen er avgjort: med handlingen i SuccessHandling.Action når arkivet har bekreftet saken, og med handlingen i ErrorHandling.Action, som standard reject, når arkiveringen ikke kan lykkes. Gatewayen er der de to veiene skiller lag, og appen nekter å starte hvis oppgaven ikke er fulgt av en gateway med minst to utganger. Plasser oppgaven etter oppgaven som lager dataene du vil arkivere, vanligvis etter PDF-oppgaven, og ikke legg en tilbakemeldingsoppgave etter den.

Merk: Du kan ennå ikke dra en Fiks Arkiv-oppgave direkte inn i Prosess-editoren i Altinn Studio. Inntil videre anbefaler vi denne fremgangsmåten:

1. Dra en vanlig dataoppgave inn i Prosess-editoren.
2. Del endringene i Studio.
3. Rediger process.bpmn på din egen maskin.
4. Gjør dataoppgaven om til en bpmn:serviceTask (se eksemplet nedenfor).

Slik sikrer du at sekvensflytene og diagrammet holder seg korrekte.

<bpmn:serviceTask id="Task_FiksArkiv" name="Fiks Arkiv">
  <bpmn:extensionElements>
    <altinn:taskExtension>
      <altinn:taskType>fiksArkiv</altinn:taskType>
    </altinn:taskExtension>
  </bpmn:extensionElements>
  <bpmn:incoming>Flow_2</bpmn:incoming>
  <bpmn:outgoing>Flow_3</bpmn:outgoing>
</bpmn:serviceTask>
<bpmn:sequenceFlow id="Flow_3" sourceRef="Task_FiksArkiv" targetRef="Gateway_FiksArkiv" />
<bpmn:exclusiveGateway id="Gateway_FiksArkiv">
  <bpmn:incoming>Flow_3</bpmn:incoming>
  <bpmn:outgoing>Flow_4</bpmn:outgoing>
  <bpmn:outgoing>Flow_5</bpmn:outgoing>
</bpmn:exclusiveGateway>
<bpmn:sequenceFlow id="Flow_4" sourceRef="Gateway_FiksArkiv" targetRef="EndEvent_1">
  <bpmn:conditionExpression>["notEquals", ["gatewayAction"], "reject"]</bpmn:conditionExpression>
</bpmn:sequenceFlow>
<bpmn:sequenceFlow id="Flow_5" sourceRef="Gateway_FiksArkiv" targetRef="Task_Oppfolging">
  <bpmn:conditionExpression>["equals", ["gatewayAction"], "reject"]</bpmn:conditionExpression>
</bpmn:sequenceFlow>

Flow_4 tas når handlingen ikke er reject. Med standardinnstillingene betyr det at arkivet har bekreftet saken. Flow_5 tas når handlingen er reject, og fører her til en oppgave der noen kan følge opp saken. Hva den oppgaven gjør, bestemmer du. Endrer du SuccessHandling.Action eller ErrorHandling.Action, må uttrykkene i gatewayen endres tilsvarende. All konfigurasjon av selve meldingen ligger i appsettings.json, ikke i prosessen. Se flytkontroll for mer om gatewayer og gatewayAction.

Steg 5: Gi tjenesteeieren tilgang

Plattformen flytter prosessen ut av oppgaven som tjenesteeier. Oppgavetypen fiksArkiv krever handlingen write, som tilgangsfilen fra appmalen allerede gir tjenesteeieren. Fordi oppgaven går videre med reject når arkiveringen ikke kan lykkes, trenger tjenesteeieren reject i tillegg. Se Gi tilgang til oppgaven for regelen og hva som skjer når den mangler.

Steg 6: Konfigurer appen

Legg konfigurasjonen i appsettings.json, og legg alle sensitive verdier i Azure Key Vault i stedet for å sjekke dem inn. Appen må ha Key Vault som konfigurasjonskilde. Se siden om hemmeligheter for hvordan du setter det opp. Endrer du hemmelighetene for Fiks IO i Key Vault etter publisering, henter appen de nye verdiene innen fem minutter og kobler seg til Fiks IO på nytt. Du trenger ikke publisere appen på nytt.

"FiksIOSettings": {
  "AccountId": "c3c87fac-06be-44ed-a11c-aa137d12863c",
  "IntegrationId": "08b3d8b9-5026-46dc-936c-8e6709efa72c",
  "IntegrationPassword": "hentes fra Key Vault",
  "AccountPrivateKeyBase64": "hentes fra Key Vault"
}

FiksArkivSettings
├─ Receipt
│  ├─ ConfirmationRecord
│  └─ ArchiveRecord
├─ Recipient
│  ├─ FiksAccount
│  ├─ Identifier
│  ├─ Name
│  └─ OrganizationNumber
├─ Metadata
│  ├─ SystemId
│  ├─ RuleId
│  ├─ CaseFileId
│  ├─ CaseFileTitle
│  ├─ JournalEntryTitle
│  ├─ CaseFileAdministrativeUnit
│  └─ CaseFileClassifications[]
├─ Documents
│  ├─ PrimaryDocument
│  └─ Attachments[]
├─ ErrorHandling
│  └─ Action
└─ SuccessHandling
   ├─ Action
   └─ MarkInstanceComplete

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

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

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

"FiksArkivSettings": {
  "Metadata": {
    "CaseFileTitle": {
      "DataModelBinding": { "DataType": "HelperDataModel", "Field": "CaseFileTitle" }
    },
    "JournalEntryTitle": {
      "Value": "Søknad om skjenkebevilling"
    },
    "CaseFileAdministrativeUnit": {
      "Value": "Næringsavdelingen"
    },
    "CaseFileClassifications": [
      { "Source": "InstanceOwner" },
      { "SystemId": "Fagklasse", "ClassificationId": "U63", "Title": "Skjenkebevilling" },
      { "SystemId": "Tilleggsklasse", "ClassificationId": "&18", "Title": "Unntatt offentlighet", "IsRestricted": true }
    ]
  }
}

"FiksArkivSettings": {
  "Documents": {
    "PrimaryDocument": {
      "DataType": "ref-data-as-pdf",
      "Filename": "Soknad.pdf",
      "Format": { "Code": "PDF/A" },
      "Variant": { "Code": "A", "Description": "Arkivformat" }
    },
    "Attachments": [
      { "DataType": "DataModel" },
      { "DataType": "vedlegg" }
    ]
  }
}

"FiksArkivSettings": {
  "SuccessHandling": {
    "Action": null,
    "MarkInstanceComplete": true
  }
}

"FiksArkivSettings": {
  "ErrorHandling": {
    "Action": "reject"
  }
}

Arkivmeldingen appen sender

Standardgeneratoren lager en NOARK 5-arkivmelding med dette innholdet:

• Saksmappe med tittel, administrativ enhet, saksår og saksdato, en ekstern nøkkel som består av app-ID-en og CaseFileId, og klassifikasjonene du har konfigurert.
• Journalpost med tittel, journalstatus Journalført og journalposttype Inngående dokument.
• Korrespondanseparter: mottakeren fra Recipient, med lenken til instansen som referanse, og eieren av instansen som avsender, med navn, person- eller organisasjonsnummer og kontaktinformasjon fra registeret.
• Dokumentbeskrivelser for hoveddokumentet og hvert vedlegg, med filnavn, format og eventuelt variantformat.
• system fra SystemId og regel fra RuleId.

Alle datoer og tidspunkter er i UTC og er hentet fra det samme tidspunktet, så en oppgave som prøves på nytt sender samme arkivmelding som første gang. Dekker ikke standardmeldingen behovet ditt, kan du lage din egen.

Overstyre standardatferd

Lage din egen arkivmelding

Implementer IFiksArkivPayloadGenerator og registrer klassen din. Grensesnittet har to metoder: GeneratePayload, som får oppgave-ID, mottaker, meldingstype, referansetidspunktet og tilgang til instansdataene, og returnerer filene som skal sendes, og ValidateConfiguration, som appen kaller ved oppstart med datatypene og prosessoppgavene i appen.

services
    .AddFiksArkiv()
    .WithPayloadGenerator<MinArkivmeldingGenerator>();

Bruk referansetidspunktet til alle datoer i meldingen, og les dokumentene gjennom IInstanceDataAccessor du får inn. Da sender en oppgave som prøves på nytt den samme meldingen som første gang.

Reagere på svar fra arkivet

Trenger appen å gjøre noe med svarene fra arkivet, for eksempel kopiere saksnummeret fra kvitteringen inn i skjemadataene, implementerer du IFiksArkivMessageHandler og registrerer klassen din. Oppgaven kaller HandleMessage én gang for hver melding arkivet sender, før den tolker meldingen selv.

services
    .AddFiksArkiv()
    .WithMessageHandler<MinMeldingshandterer>();

public class MinMeldingshandterer : IFiksArkivMessageHandler
{
    public Task HandleMessage(FiksArkivReceivedMessage message, ServiceTaskContext context)
    {
        if (message.IsReceipt)
        {
            // Les kvitteringen fra message.Payloads og lagre det du trenger
            // gjennom context.InstanceDataMutator.
        }

        return Task.CompletedTask;
    }
}

Fire ting å vite om handleren:

• Den kjører inne i prosessovergangen som behandler meldingen. Alt du lagrer gjennom context.InstanceDataMutator, lagres sammen med kvitteringen.
• Den skal ikke flytte prosessen. Oppgaven gjør det selv etter SuccessHandling og ErrorHandling, og et kall til process/next fra handleren blir avvist.
• Kaster den en feil, prøver plattformen meldingen på nytt, og oppgaven konkluderer ikke før handleren lykkes.
• Meldinger kan komme mer enn én gang. Bruk message.MessageId til å oppdage gjentakelser hvis handleren gjør noe som ikke tåler å skje to ganger.

message.IsAcknowledgement, message.IsReceipt og message.IsError sier hva slags melding det er, og message.Payloads inneholder innholdet, ferdig tolket der plattformen kjenner meldingstypen.

Når noe går galt

En avvist arkivering feiler altså ikke oppgaven; den er avgjort, og saken går reject-veien ut av gatewayen til oppgaven du har lagt der. Når oppgaven derimot feiler, ser brukeren feilsiden, og feilen dukker opp i overvåkingen med en melding som sier hva som skjedde. En som har handlingen for oppgaven kan gjenoppta den med Prøv igjen, og en reject-flyt gir brukeren mulighet til å gå tilbake. Se Hva brukeren ser mens en systemoppgave kjører.

Kommer du fra v8?

Dette er endret fra v8:

• Ingen tilbakemeldingsoppgave. Oppgaven venter selv på kvitteringen fra arkivet, og prosessen går først videre når den har kommet. Fjern tilbakemeldingsoppgaven du hadde etter Fiks Arkiv-oppgaven.
• MoveToNextTask finnes ikke lenger. Oppgaven går alltid videre når arkiveringen er avgjort: med SuccessHandling.Action etter en kvittering, og med ErrorHandling.Action, som standard reject, etter en avvisning. Legg en eksklusiv gateway rett etter oppgaven, og gi tjenesteeieren reject. Appen nekter å starte uten gatewayen.
• SuccessHandling gjelder når arkivet har bekreftet saken, ikke når meldingen er sendt, og MarkInstanceComplete er true som standard.
• Fiks IO-klienten bruker appens innebygde Maskinporten-klient. Du peker den ikke lenger til en egen MaskinportenSettings-seksjon.
• Klassifikasjon av eieren er valgfri. Den legges ikke lenger på automatisk. Legg inn { "Source": "InstanceOwner" } i Metadata.CaseFileClassifications for å beholde den. Systemene heter nå PNR og ORGNR, og eieren av instansen klassifiseres, ikke den som sendte inn.
• IFiksArkivResponseHandler er erstattet av IFiksArkivMessageHandler, og .WithResponseHandler<T>() av .WithMessageHandler<T>(). Handleren kalles for hver melding arkivet sender, og skal ikke flytte prosessen.
• IFiksArkivHost er fjernet. Meldinger sendes bare gjennom systemoppgaven.
• klientKorrelasjonsId er postkassens id, ikke lenken til instansen. Lenken ligger fortsatt i arkivmeldingen, som referansen på mottakerens korrespondansepart.
• Tidspunktene i arkivmeldingen er i UTC, og dokumentobjekt har ikke lenger en systemID.

studioctl app upgrade v9 legger inn tilgangsreglene tjenesteeieren trenger, fjerner MoveToNextTask fra Fiks Arkiv-konfigurasjonen og sier fra hvis verdien var false eller oppgaven mangler gatewayen. Resten av Fiks Arkiv-konfigurasjonen lar den stå.

Konfigurasjon for mottak av meldinger i arkivsystemet

Digdir leverer verken arkivsystemet eller Fiks Arkiv, så vi har ikke fullstendig dokumentasjon for mottakersiden. Bruk KS Digitals dokumentasjon sammen med dokumentasjonen fra arkivsystemleverandøren. Oppsettet av mottakerkontoen er likevel det samme uansett arkivsystem.

Opprett en Fiks Arkiv-konto for mottak

1. Sett opp et nytt system under Fiks Protokoll for organisasjonen din.

2. Opprett en konto knyttet til dette systemet, med disse egenskapene:

   Egenskap	Verdi
   Protokolltype	no.ks.fiks.arkiv
   Versjon	v1
   Protokollparter	arkiv.full

   Gi kontoen et navn som gjenspeiler appen, siden vi anbefaler én konto per Altinn-app.

3. Se dokumentasjonen for arkivsystemet for krav til krypteringsnøkkelparet.

4. Under kontoen, gå til fanen Søk etter systemer og slå opp systemet som ble opprettet for å sende meldinger. Gi systemet tillatelse til å sende til mottakerkontoen ved å klikke Gi tilgang.

Ekstern dokumentasjon

Mer om Fiks Arkiv:

• https://developers.fiks.ks.no/felles/integrasjoner/
• https://github.com/ks-no/fiks-arkiv-specification/wiki