eFormidling
How to configure integration with eFormidling for an app.
Activate eFormidling integration for your application
Integration with eFormidling needs to be explicitly activated in the application.
In the file appsettings.json in the folder App, the following must be added to the AppSettings section.
"EnableEFormidling": true
In addition, continuing in the same file, a new section EFormidlingClientSettings
should be added.
The contents of the code snippet below can be copied in its entirety.
This sets up the url for the integration point.
The link points to the mock that can be ran locally.
Read more about setting up the local mock for the integration point here.
When an application is deployed to TT02 or production, this value will be substituted to point to the integration point hosted in Altinn Platform.
"EFormidlingClientSettings": {
"BaseUrl": "http://localhost:9093/api/"
}
In the case you do not wish to test the eFormidling integration when running your app locally, you can override this configuration in appsettings.Development.json.
Create the section AppSettings, if it does not already exist, and set EnableEFormidling to false.
"AppSettings": {
"EnableEFormidling": false
}
eFormidling integration is a part of the Altinn.App.Core nuget package, but is not enabled by default. In order to add support for eFormidling in your application you need to register it’s services by adding the following to Program.cs:
services.AddEFormidlingServices<EFormidlingMetadata, EFormidlingReceivers>(config);
Adding support for eFormidling in App.cs
The next step in setting up support of eFormidling , is to make the required services available for the application. All changes are made in App.cs, which you fill find in the _App/logic folder.
At the top of the file, among the library references, include the following three lines.
using Altinn.Common.EFormidlingClient.Models;
using Altinn.Common.EFormidlingClient;
using Altinn.Common.AccessTokenClient.Services;
Further, you need to inject services in the constructor of both the class and the base class.
Before making any changes, the constructor should look like the example below, but which services are included may vary from application to application. This shows the most common setup.
public App(
IAppResources appResourcesService,
(...)
IHttpContextAccessor httpContextAccessor):base(
appResourcesService,
(...)
httpContextAccessor)
The list of services in the constructor should be extended with the four services listed below.
IEFormidlingClient eformidlingClient,
IOptions<AppSettings> appsettings,
IAccessTokenGenerator tokenGenerator,
IOptions<PlatformSettings> platformSettings
Further, these services should be forwarded to the base class as well, but in this case only include the names, not the types.
eformidlingClient,
appsettings,
platformSettings,
tokenGenerator
Final result should look like this:
public App(
IAppResources appResourcesService,
(...)
IHttpContextAccessor httpContextAccessor,
IEFormidlingClient eformidlingClient,
IOptions<AppSettings> appsettings,
IAccessTokenGenerator tokenGenerator,
IOptions<PlatformSettings> platformSettings):base(
appResourcesService,
(...)
httpContextAccessor,
eformidlingClient,
appsettings,
platformSettings,
tokenGenerator)
Configuring key values for eFormidling in your application
Metadata related to the eFormidling shipment is required, and this is set up in applicationmetadata.json. You find the file in the App/config folder.
Create a new section eFormidling
and populate values for the
parameters defined in the table.
Id | Description |
---|---|
serviceId | Id that specifies the shipment type DPO*, DPV, DPI or DPF* |
dpfShipmentType | The DPF shipment type used for routing in the receiving system |
process | Id which wil be included in the scope of the StandardBusinessDocumentHeader** |
dataTypes | List of data types to automatically include in the shipment |
sendAfterTaskId | Id of the task to be completed before the shipment is sent. We recommend this be a confirmation task |
receiver | Organisation number of the receiver. Only Norwegian organisations supported. (Can be omitted) |
standard | DocumentIdentification standard |
type | Id for the message type |
typeVersion | Version of the message type |
securityLevel | Security lever set on the StandardBusinessDocument |
* per June 2023 there is support for DPF and DPO.
** available process for each receiver is available at https://platform.altinn.no/eformidling/api/capabilities/{mottaker-orgnummer}
An example of a configuration in 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
}
Shipment metadata generation in the application
The application developer is responsible for creating the message that will follow a shipment through eFormidling. Read about the various message types available in eFormidling.
In versions 4, 5 and 6 this was achieved by including the function below in App.cs. While in version 7 this is done by adding a class that implements the IEFormidlingMetadata
interface which has the same method signature. Remember that in version 7 your implementation need to be registered in Program.cs.
Expected output from this function is a tuple containing two elements. First, the name of the metadata file and then a stream containing the metadata.
/// <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));
}
Dynamically setting the shipment receiver
This functionally can be used whenever the receiver of a shipment is to be determined dynamically.
In version 7 the GetEformidlingReceivers method is moved to the IEFormidlingReceivers
interface. Create a class that implements this interface and register the implementation in Program.cs. Below is a skeleton example for the implementation.
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 };
}
In App.cs it is possible to override the method retrieving the receiver from applicationmetadata.json. Three steps are required when defining the receiver in the application logic, and all steps are executed in App.cs.
- At the top of the file, a reference to the eFormidling library must be included.
using Altinn.Common.EFormidlingClient.Models.SBD;
- Include the function below in the class.
Expected output from this method is a list containing at least one receiver object.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 }; }
- Add custom logic to populate identifier.Value in the function.
Note that only Norwegian organisations are supported, and that the prefix0192:
is required before the organisation number.
Testing eFormidling integration locally
It is possible to test the eFormidling integration for an application in your development environment. In addition to Altinn’s Local test, and the application, there are two things that need to run:
- eFormidling integration point (Integrasjonspunktet)
- A mock of eFormidling
Setup
- Install the latest version of Java.
Download link and installation guide is available here - In the next steps you will be downloading a number of files. Define a suitable placement for everything eFormidling related on your local machine and navigate there in your terminal.
- Clone the eFormidling mock repository with the following command
git clone --branch development https://github.com/felleslosninger/efm-mocks.git
- Download the integration point.
The contents can be places at the same level as theefm-mocks
folder.
Running eFormidling locally
- Open a terminal and navigate to
efm-mocks
(Command prompt or bash is recommended, PowerShell will not work.) - Run
docker-compose up -d
- Navigate to the folder where the integration point file exists.
- Run the command
java -Xmx2g -Dspring.profiles.active=mock -jar integrasjonspunkt-2.2.6.jar
If you have a newer version of the integration point, the commands last section should be adjusted to reflect this.
This has a known issue that prevents it from running on Docker Desktop on Windows, but works on Mac.
Verify that eFormidling is set up correctly
This requires that node and npm is present on your machine, but they are note required to use the mock.
- Open a terminal and navigate to
efm-mocks/tests/
- Run
npm i
- Navigate into the folder
next-move
- Run
node NextMove.js dpf
- Verify in a browser at localhost:8001 that there are new table entries containing the sent messages.
Testing eFormidling integration in a test environment
The integration point exposes endpoints that allow you to monitor the status of a shipment in the test environment.
https://platform.tt02.altinn.no/eformidling/api/conversations?messageId={instanceGuid}
Replace {instanceGuid}
with the guid of the instance that has been archived.