Install and configure WorkZone e-Boks Push Service

WorkZonee-Boks Push Service is a web service that makes it possible to receive e-Boks messages using Digital Post 2 and Next generation Digital Post (NgDP).

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. 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.

Regardless of whether your setup is with only server that acts as bot web server and agent server or the push service is installed on a separate server, the database must be populated. See Replicate the configuration from the WorkZone database to the push service (NgDP).

Digital Post 2

As of the WorkZone 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. e-Boks requires an end point that can receive messages. The WorkZone e-Boks push service exposes the required interface to e-Boks.

NgDP

As of the WorkZone 2021.2 release, SmartPost supports NgDP in an experimental version. For more information, see Configure SmartPost to use next generation Digital Post (NgDP).

WorkZonee-Boks Push Service receives messages and receipts on incoming calls from a Next generation Digital Post (NgDP) system and transforms messages between the MeMo format and Digital Post 1 or 2.

For more information about MeMO, please refer to Det nye meddelelsesformat on the Agency for Digitisation's website (Digitaliseringsstyrelsen).

The push service must be accessible from NgDP and from the local web servers. Because of the incoming NgDP calls, it is required to configure firewalls and router to allow these requests and ensure that a legal HTTPS server certificate is installed.

The IIS server should be configured to only allow requests with NgDP client certificates, and the certificate that your organization uses.

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 e-Boks dispatcher 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

 

Install.NET Core Windows Hosting Bundle using a PowerShell script

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

powershell -NoProfile -ExecutionPolicy unrestricted -Command "[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; &([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'https://dot.net/v1/dotnet-install.ps1'))) -channel 5.0 -Runtime aspnetcore"

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

You must run the installer elevated on a server where the WorkZone Process web profile is already installed.

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

If you have a test setup with only one server that acts as both web server and agent server, you can use the Olympus installation to deploy the push service automatically by setting the InstallEboksPushService parameter to True in the <WZP> configuration element.

In a more complex setup, you need to deploy the push service manually using the WorkZonee-Boks Push Service Setup wizard. See Install WorkZone e-Boks Push Service using the WorkZone e-Boks Push Service Setup wizard.

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" />

Replicate the configuration from the WorkZone database to the push service (NgDP)

The push service has its only local configuration database that must be populated. In a one-server test installation, the database is populated automatically when the push service application pool is recycled. If the push service is installed manually on a different server, the database can be populated using the PowerShell interface for the push service.

If the push service is installed on a separate server, it is recommended to turn of the auto-configure feature by setting the configure-pushservice -AutoconfigureSystems to False.

configure-pushservice -AutoconfigureSystems $false

Manual configuration from a WorkZone database is done using the cmdlet AutoConfigure-PushServiceSystems. This cmdlet takes the ODataEndpoint of the database as an argument and returns the number of configuration items that are returned from the system.

The credentials of the current user is used to access OData. The current user must have privilege to access OData and read the configuration data.

This cmdlet must be called on a regular basis or manually after a change of the configuration.

Use contact points on outgoing messages (NgDP)

You can test that it is possible to send NgDP messages to a specific contact point. Contact points can be assigned to addresses in the WorkZone database using custom address info with the label NgDpCp.

To test that it is possible to send NgDP messages, it is required to create the meta data for the address property and address type. This can be done using the cmdlet New-NgDpMetadata.

To create WorkZone addresses for a specific CVR contact that corresponds to the contact point that is defined in the NgDP system for the same CVR number, use the cmdlet Add-ContactPointAddresses.

PowerShell cmdlets

The following e-Boks Push Service cmdlets are available:

• Initialize-PushServiceModule

• Get-SubscriptionStatus

• Configure-PushService

• AutoConfigure-PushServiceSystems

• Get-PushServiceConfiguration

• Configure-PushServiceSystem

• Get-PushServiceSystemConfiguration

• Delete-PushServiceSystemConfiguration

• Get-PushServiceLogs

• Delete-PushServiceLogs

• New-Receipt

• Get-Receipt

• Delete-Receipt

• Get-PendingRecipients

• Create-PendingReceipts

• Push-TestMessage

• Ship-TestMessage

• Configure-Material

• Get-Material

• Delete-Material

• Get-ContactPoints

• New-NgDpMetadata

• Add-ContactPointAddresses

Map NgDP error messages to e-Boks error messages

Errors that are returned from the NgDP system are mapped to e-Boks errors using in the appsettings.json file of the service. The default location this file is:

“C:\Program Files (x86)\KMD\WorkZone\Process\WorkZone.Dispatcher.Eboks.PushService\WebService”

Below is an example of a mapped error regarding exceeding the length of the title column:

		  "NgDpErrorCodes": {
    "message.create.label.size": {
      "ErrorCode": 4071,
      "ErrorText": "Feltet MeddelelsesTitelTekst indeholder mere end 256 tegn."
    }
  }

				

See also e-Boks errors.

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-5.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