Install and configure WorkZone e-Boks Push Service

As of the 2020.1 release, SmartPost supports Digital Post 2. The biggest difference between Digital Post 1 and Digital Post 2 is that the polling for new messages is replaced by a push. For information about Digital Post, see Vejledninger Digital Post and Kom godt igang - for virksomheder, Digital Post 2.

To use SmartPost with e-Boks using Digital Post 2, you need to install WorkZone e-Boks Push Service. WorkZone e-Boks Push Service is a web service that makes it possible to receive e-Boks messages using the Digital Post 2. e-Boks requires an end point that can receive messages. The WorkZone e-Boks push service exposes the required interface to e-Boks.

You can install the push service behind or in front of the firewall or in a DMZ at a separate location, for example in Azure. By default, the push service is installed behind the firewall, and then you need a hole in the firewall to allow access to the push service as illustrated in the diagram. This means that you must open port 443 on the server you have installed the push server on.

You can only install one instance of the push service for each retrieval system. The push service is self-contained with a data store. By default, the data store is placed in the same location as the push service. If you want the data store in a different location, for example in the location where you have your backup or where you have more space, you can change the location. You change the location of the data store as well as other settings in the app config file named Appsettings.json, which is placed in the same location as the push service. To change the location of the data store, change the configuration of the ConnectionStrings parameter.

Install and configure WorkZonee-Boks Push Service

To install and configure the push service, you need to complete the following steps:

1. Run the installer that sets the site for the push service. This step also involves configuring the service for the retrieval and dispatch systems in use.
2. Configure WorkZone Process to use the push service.
3. Set up the e-Boks Administrationsportal to send messages to the push service.

Install WorkZone e-Boks Push Service

Prerequisites:  

• WorkZone Process including SmartPost must be release 2018.0 or later.
• The WorkZone site must be configured to be able to run in https mode.
• .NET Core Windows Hosting Bundle (dotnet-hosting-3.0.0-win.exe) must be installed.
• Microsoft Visual C++ 2015 Redistributable (vc_redist.x64.exe) must be installed.

Install .NET Core Windows Hosting Bundle using a PowerShell scrip

1. Run Windows PowerShell as administrator.
2. Run the script:

Copy

Install WorkZone e-Boks Push Service using the WorkZone e-Boks Push Service Setup wizard

1. Run the WorkZone e-Boks Push Service Setup wizard, WorkZone.Dispatcher.Eboks.PushService.Setup.msi.
2. Click Next through the wizard until you get to the Complete the WorkZone e-Boks Push Service Setup page. If you see this page, the service has been installed successfully.
3. Click Finish to close the wizard.

After the installation, the EboksPushService web application is created under the WorkZone site as shown in IIS Manager.

Install using Olympus

You can deploy the push service automatically using Olympus by setting the InstallEboksPushService setting to True.

Verify the installation

You can verify that the e-Boks push service responds by invoking the URL:

https://<database>/EboksPushService/api/MeddelelseV2/afhentningssystem/0000/meddelelser

It should result in the following XML:

<MeddelelseReferenceSamling xmlns="urn:oio:dkal:2.0.0" />

Configure WorkZone Process to use the push service

To use the push service in SmartPost, the e-Boks end point must be changed for the e-Boks dispatcher to use the push service.

1. In WorkZone Configurator, click Process
2. Click Process dispatchers.
3. Point to next to the e-Boks dispatcher you want to use and click Edit.
4. Change the values for the ReceiverUrl and DP2Url parameters.

Parameter	Description	Example
ReceiverUrl	The URL for receiving messages using Digital Post 2. If the parameter is left empty, the default URL in the Url parameter is used.	https://<host-or-database>/EboksPushService/api/MeddelelseV2
DP2Url	The URL for sending messages using Digital Post 2 API methods. If the parameter is left empty, the Digital Post 1 API methods will be used.	https://demo-api.e-boks.com/oio/rest/srv.svc/2

Configure the e-Boks Administrationsportal to use Digital Post 2

You create or update a e-Boks dispatch systems and retrieval systems in the e-Boks Administrationsportal.

Set up the dispatch system to use Digital Post 2

1. In the e-Boks Administrationsportal, go Tilmeldingsmuligheder > Vis afsendersystemer (View dispatch systems).
2. Click the dispatch system you want to configure and set up the API version to use v2 in the API Version field.

Set up the retrival system to use Digital Post 2

1. In the e-Boks Administrationsportal, go to Kontaktmuligheder > Vis afhentningssystemer (View retrieval systems).
2. Click the retrieval system you want to configure and set up the URL to use the v2 end point of the push service:

https://<database>/EboksPushService/api/MeddelelseV2/afhentningssystem/<systemid>

3. Set up the API version to use v2 in the API Version field.
4. To verify the whole setup, click the Test button.



If the call to the push service does not return OK (http 200), the http error message is shown in the top of the page in the Administrationportal. If the configuration is correct, the test letter should be received in WorkZone.

Appsettings.json

The table below provides descriptions of parameters in the Appsettings.json file.

Name	Description
Logging	Configuration log levels for different components. Logging is done in the eventlog.
AllowedHosts	Configuration of hosts that are allowed to call the service. It should only be allowed to call the service from e-Boks and the servers that are running WorkZone Process. https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.hostfiltering.hostfilteringoptions.allowedhosts?view=aspnetcore-3.0
ConnectionStrings	Configuration of where the temporary store of the messages should be done. The connect string StoreContext” references a file that contains the temporary store. To move the file to another location, change the path to Meddelser.db. By default it is stored in the same folder as the service binaries. It is recommended that the database file is stored in a location that has backup. The user running the service must have read/write permission to the file.
TransformMessageV2ToV1XsltFile	Reference to an xslt file that can transform e-Boks from V2 to V1.
TransformMessageV1ToV2XsltFile	Reference to an xslt file that can transform e-Boks from V1 to V2.
UrlTransformXsltFile	Reference to a xslt file that can transform e-Boks entities that contains URL references.
EBoksUrlV1Demo	The e-Boks demo v1 endpoint. By default it is https://demo-rest.e-boks.dk/V1.svc.
EBoksUrlV2Demo	The e-Boks demo v2 endpoint. By default https://demo-api.e-boks.com/oio/rest/srv.svc/2.
EBoksUrlV1Prod	The e-Boks production v1 endpoint. By default it is https://rest.e-boks.dk/V1.svc.
EBoksUrlV2Prod	The e-Boks production v2 endpiont. By default it is https://api.e-boks.com/dp/rest/srv.svc/2.
EBoksUrlV1Custom	Can be used to setup a custom v1 endpoint for the RelayMessageCallsToCustomEndpoint setting on e-Boks systems.
EBoksUrlV2Custom	Can be used to setup a custom v2 endpoint for the RelayMessageCallsToCustomEndpoint setting on e-Boks systems.
ServiceUserName	The user name of the process user used for impersonation. It is filled out automatically during installation.
ServiceUserDomain	The domain of the process user. It is filled out automatically during installation.
ServiceUserPassword	The password of the process user encrypted. It is filled out automatically during installation.
ImpersonateProcessUserForDatabaseAccess	True or false. If True, the process user is impersonated when database calls are made.

 

Configuration per system in the array “EBoks”:”Systems”[]

Name	Description	Example
SystemId	SystemId of the e-Boks system	4259
EBoksSystemType	"AfsenderSystem" or “AfsenderSystem”. It must match the configuration in the e-Boks Administrationsportal.	AfsenderSystem
EBoksApiVersion	The API version of the configuration at e-Boks must match the API version set in the e-BoksAdministrationsportal .Only ‘1’ and ‘2’ are legal values that correspond to v1 and v2 in the e-Boks Administrationsportal.	1
UseEboksProduction	This can be either True or False. This value is used to resolve the URL for the endpoint of the e-Boksservice using the settings EBoksUrlVxProd and EBoksUrlVxCustom.	False
ClientCertificateStore	Configuration of where the certificate used for communicating with e-Boks is stored. The legal values are LocalMachine and CurrentUser.	LocalMachine
ClientCertificateThumbPrint	The thumbprint of the certificate used for communicating with e-Boks.	F63A18100F5AA0454E17D25AD85082362D96AFC2
ClientCertificateFile	File name that contains the client certificate. Storing the certificate in a file is an alternative to storing it in the certificate store. If the setting ClientCertificateFile is not empty, the ClientCertificateThumpPrint must be empty and vice versa.	/home/cert.pfx
ClientCertificatePassword	Contains the password that protects the ClientCertificateFile.	Secret
RelayMessageCalls-ToCustomEndpoint	This setting can be used to redirect calls to a remote installation of the EBoksProxy service that receives the messages from e-Boks.	False
RelatedSystem	The Id of the ‘reverse’ system. For SenderSystem it should be the ID of the reciversystem and vice versa.	4259