eFormidling

Hvordan konfigurere eFormidling integrasjon for en app.

På denne siden:

Aktivere integrasjon med eFormidling i applikasjonen din

For at applikasjonen din skal kunne sende instansdata videre til eFormidling må den referere til nugetversjon >= 4.22.0. [Se hvordan du oppdaterer nugetreferanser for applikasjonen din her](../update/#nuget-pakker).

Dersom man har behov for integrasjon med eFormidling i applikasjonen må dette aktiveres.

I filen appsettings.json i mappen App må følgende legges til i seksjonen AppSettings

"EnableEFormidling":  true

I tillegg må det i samme fil opprettes en ny seksjon; EFormidlingClientSettings. Innholdet i kodesnutten nedenfor kan kopieres i sin helhet. Denne setter opp url til integrasjonspunktet. Lenken peker på mocken som kan kjøres opp lokalt. Les mer om oppsettet av eFormidlings mocken her.

Når en app deployes til TT02 eller produksjon vil denne verdien overskrives og peke mot integrasjonspunktet i Altinn Platform.

"EFormidlingClientSettings": {
   "BaseUrl": "http://localhost:9093/api/"
 }

Dersom det ikke er ønskelig å teste integrasjonen med eFormidling når man kjører applikasjonen lokalt kan man overstyre denne konfigurasjonen i appsettings.Development.json.

Opprett AppSettings seksjonen dersom den ikke finnes og sett EnableEFormidling til false.

"AppSettings": {
    "EnableEFormidling": false
}

Legge til støtte for eFormidling i App.cs

Neste steg for å få støtte for eFormidling i tjenesten din er å tilgjengeliggjøre services som appen behøver. Endringene skal alle gjøres i filen App.cs som ligger i mappen _App/logic.

Øverst i filen, blant bibliotekreferansene legges disse tre linjene til.

using Altinn.Common.EFormidlingClient.Models;
using Altinn.Common.EFormidlingClient;
using Altinn.Common.AccessTokenClient.Services;

Videre skal vi injecte services i konstruktøren til både klassen og base klassen.

Konstruktøren vil se ut som eksempelet nedenfor, men hvilke services som sendes med kan variere fra tjeneste til tjeneste, så her er kun et eksempel på det vanligste oppsettet.

public App(
IAppResources appResourcesService,
(...)
IHttpContextAccessor httpContextAccessor):base(
appResourcesService,
(...)
httpContextAccessor)

Listen med services i konstruktøren skal utvides med de fire servicene vist nedenfor.

IEFormidlingClient eformidlingClient,
IOptions<AppSettings> appsettings,
IAccessTokenGenerator tokenGenerator,
IOptions<PlatformSettings> platformSettings

Videre skal disse servicene sendes med videre til baseklassen, da er det kun navnene som sendes med og ikke typene.

eformidlingClient,
appsettings,
platformSettings,
tokenGenerator

Endelig resultat skal se slik ut:

public App(
IAppResources appResourcesService,
(...)
IHttpContextAccessor httpContextAccessor,
IEFormidlingClient eformidlingClient,
IOptions<AppSettings> appsettings,
IAccessTokenGenerator tokenGenerator,
IOptions<PlatformSettings> platformSettings):base(
appResourcesService,
(...)
httpContextAccessor,
eformidlingClient,
appsettings,
platformSettings,
tokenGenerator)

Konfigurere nøkkelverdier for eFormidling i applikasjonen din

Det kreves en del metadata om eFormidlingsforsendelsen og denne defineres i applicationmetadata.json_. Filen finner du i repoet under mappen App/config.

Opprett seksjonen eFormidling og fyll ut verdier for følgende parametre.

Id Beskrivelse
serviceId Id som spesifiserer type forsendelse DPO, DPV, DPI eller DPF*
dpfShipmentType Forsendelsestype som benyttes til routing på mottakersiden
process Id som settes på scopet i StandardBusinessDocumentHeader**
dataTypes Liste av data typer som automatisk skal legges ved forsendelsen
sendAfterTaskId Id på tasken som skal avsluttes før forsendelsen sendes. Det er anbefalt at dette er et confirmation steg
receiver Organisasjonsnummer til mottaker. Støtter kun norske virksomheter. Kan sløyfes og defineres i applogikken
standard DocumentIdentification standard
type Id på meldingstypen
typeVersion Versjon av meldingstypen
securityLevel Sikkerhetsnivå som settes på StandardBusinessDocument

* per Januar 2022 støttes kun DPF.

** tilgjengelige prosesser for mottaker er tilgjengelig på https://platform.altinn.no/eformidling/api/capabilities/{mottaker-orgnummer}

Et eksempel for en konfigurasjon i application metadata:

"eFormidling": {
    "serviceId": "DPF",
    "dpfShipmentType": "altinn3.skjema",
    "process": "urn:no:difi:profile:arkivmelding:administrasjon:ver1.0",
    "dataTypes": [ "ref-data-as-pdf" ],
    "sendAfterTaskId": "Task_2",
    "receiver": "910075918",
    "standard": "urn:no:difi:arkivmelding:xsd::arkivmelding",
    "type": "arkivmelding",
    "typeVersion": "2.0",
    "securityLevel":  3
}

Generering av metadata til forsendelsen i applikasjonen

Apputvikler er selv ansvarlig for å sette opp meldingen til en forsendelse som skal via eFormidling. Les om de ulike meldingstypene tilgjengelig i eFormidling.

Dette gjøres ved å legge til funksjonen nedenfor i App.cs.

Forventet output fra denne metoden er en tuppel som inneholder navnet på metadatafilen som første element og en stream med metadataen som andre element.

/// <inheritdoc />
public override async Task<(string, Stream)> GenerateEFormidlingMetadata(Instance instance)
{
    Altinn.Common.EFormidlingClient.Models.Arkivmelding arkivmelding = new ();

    // bygg opp arkivmeldingen eller annet metadataobjekt her.

    MemoryStream stream = new MemoryStream();
    XmlSerializer serializer = new XmlSerializer(typeof(Altinn.Common.EFormidlingClient.Models.Arkivmelding));
    serializer.Serialize(stream, arkivmelding);
    stream.Position = 0;
    StreamContent streamContent = new StreamContent(stream);
    streamContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/xml");
    return await Task.FromResult(("arkivmelding.xml", stream));
}

Sette mottaker for forsendelse i applikasjonslogikken

I App.cs kan man overstyre metoden som henter ut mottaker av forsendelsen fra applicationmetadata.json_. Denne funksjonaliteten kan benyttes dersom mottaker av forsendelsen skal avgjøres dynamisk.

Det må tre steg til for å sette mottaker i applikasjonslogikken, og alle endringer gjøres i App.cs.

  1. Øverst i filen må det legges til en referanse til eFormidlings biblioteket.
using Altinn.Common.EFormidlingClient.Models.SBD;
  1. Legg til denne funksjonen i klassen. Forventet output fra denne metoden er en liste som inneholder minst ett receiver-objekt.

    public override async Task<List<Receiver>> GetEFormidlingReceivers(Instance instance)
    {
        Identifier identifier = new Identifier
        {
            Authority = "iso6523-actorid-upis"
        };
    
        // 0192 prefix for all Norwegian organisations.
        identifier.Value = "[INSERT ORGANISATION NUMBER HERE WITH PREFIX `0192:`]" ;
    
        Receiver receiver = new Receiver { Identifier = identifier };
        return new List<Receiver> { receiver };
    }
    
  2. Legg til egen logikk for å populere identifier.Value i funksjonen. Merk at det kun er norske organisasjonsnummer som støttes, og at prefiksen 0192: er påkrevd før organisasjonsnummeret.

Lokal test av applikasjon med eFormidling

Det er mulig å teste eFormidlingsintegrasjonen i applikasjonen lokalt på utviklingsmiljøet ditt. I tillegg til Altinn Localtest og applikasjonen er det to ting som må kjøre:

  1. eFormidling integrasjonspunkt
  2. mock av eFormidling

Forberedelser

  1. Installer siste versjon av Java. Finn nedlastingslenke og beskrivelse av nødvendige steg her

  2. Det skal nå lastes ned en rekke filer. Finn en egnet plassering for eFormidling lokalt på maskinen din og navigér dit i en terminal.

  3. Klon repoet som inneholder eFormidling mocken med følgende commando

    git clone --branch development https://github.com/felleslosninger/efm-mocks.git
    
  4. Last ned integrasjonspunktet herfra. Dette kan plasseres på samme nivå som mappen efm-mocks.

Kjøre eFormidling lokalt

  1. Åpne en terminal og navigér til efm-mocks (Command prompt eller bash er anbefalt, PowerShell funker ikke. )
  2. Kjør docker-compose up -d
  3. Navigér til mappen der integrasjonspunkt-filen ligger
  4. Kjør kommandoen java -Xmx2g -Dspring.profiles.active=mock -jar integrasjonspunkt-2.2.0.jar Dersom du har en nyere versjon av integrasjonspunktet enn 2.2.0 må kommandoen siste ledd i siste linje justeres for dette.

Verifiser at eFormidling er satt opp korrekt

Dette steget krever node og npm på maskinen din, men er ikke nødvendig for å bruke mocken.

  • Åpne en terminal og navigér til efm-mocks/tests/
  • Kjør npm i
  • Navigér inn i mappen next-move
  • Kjør node NextMove.js dpf
  • Verifiser i en broswer på localhost:8001 at det er nye innslag i tabellen med de sendte meldingene.

Les mer om mockløsningen her

Test av eFormidling integrasjon i testmiljø

Det oppfordres til grundig testing av eFormidlingsintegrasjonen i applikasjonene. Det er lagt inn sikringer og retry mekanismer for å få en forsendelse fram til mottaker dersom feil skyldes svakheter i nettverksforbindelse. I tilfellet ugyldige forsendelser, herunder manglende vedlegg eller feil i arkivmelding, vil forsendelsen feile uten eksplisitt varsling til sluttbruker eller tjenesteeier.

Integrasjonspunktet eksponerer endepunkter der man kan følge statusen for en forsendelse. https://platform.altinn.no/eformidling/api/conversations?messageId={instanceGuid}

Bytt ut {instanceGuid} med guiden til instansen som er blitt innsendt.