eFormidling
Hvordan konfigurere eFormidling integrasjon for en app.
Aktivere integrasjon med eFormidling i applikasjonen din
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
}
eFormidlingsintegrasjonen er en del av Altinn.App.Core nuget pakken, men er ikke aktivert som standard. For å aktivere støtte for eFormidling in applikasjonen må du registrere tjenestene ved å legge til følgende i Program.cs:
services.AddEFormidlingServices<EFormidlingMetadata, EFormidlingReceivers>(config);
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 juni 2023 er det støtte for DPF og DPO.
** 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.
I versjon 4, 5 og 6 ble dette gjort ved å legge til funksjonen nedenfor i App.cs. Mens i versjon gjør man dette ved å legge til en klasse som implementerer IEFormidlingMetadata
grensesnittet som har samme metode og signatur. Husk at i versjon 7 må du også registrere implementeringen din i Program.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
Denne funksjonaliteten kan benyttes dersom mottaker av forsendelsen skal avgjøres dynamisk.
I App.cs kan man overstyre metoden som henter ut mottaker av forsendelsen fra applicationmetadata.json_.
I versjon 7 er GetEformidlingReceivers metoden flyttet til IEFormidlingReceivers
grensesnittet. Lag en klasse som implementerer dette grensesnittet og registrer den i Program.cs. Nedefor er et eksempel på rammene for en slik implementering:
public 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 };
}
Det må tre steg til for å sette mottaker i applikasjonslogikken, og alle endringer gjøres i App.cs.
- Øverst i filen må det legges til en referanse til eFormidlings biblioteket.
using Altinn.Common.EFormidlingClient.Models.SBD;
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 }; }
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:
- eFormidling integrasjonspunkt
- mock av eFormidling
Forberedelser
Installer siste versjon av Java. Finn nedlastingslenke og beskrivelse av nødvendige steg her
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.
Klon repoet som inneholder eFormidling mocken med følgende commando
git clone --branch development https://github.com/felleslosninger/efm-mocks.git
Last ned integrasjonspunktet herfra. Dette kan plasseres på samme nivå som mappen
efm-mocks
.
Kjøre eFormidling lokalt
- Åpne en terminal og navigér til
efm-mocks
(Command prompt eller bash er anbefalt, PowerShell funker ikke. ) - Kjør
docker-compose up -d
- Navigér til mappen der integrasjonspunkt-filen ligger
- Kjør kommandoen
java -Xmx2g -Dspring.profiles.active=mock -jar integrasjonspunkt-2.2.0.jar
Dersom du har en nyere versjon av integrasjonspunktet enn2.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ø
Integrasjonspunktet eksponerer endepunkter der man kan følge statusen for en forsendelse i testmiljø (tt02).
https://platform.tt02.altinn.no/eformidling/api/conversations?messageId={instanceGuid}
Bytt ut {instanceGuid}
med guiden til instansen som er blitt innsendt.