Install and configure WorkZone e-Boks Push Service

WorkZone e-Boks Push Service is a web service that makes it possible for WorkZone 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 below. This means that you must open port 443 on the server that you have installed the push service 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 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 one server that acts as both 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 most significant 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 2022.0 release, SmartPost supports NgDP in production. 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 routers 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 WorkZone e-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 on all web and agent servers. This step also involves configuring the service for the retrieval and dispatch systems in use.
2. Configure the e-Boks dispatcher to use the push service.
3. Set up the e-Boks Administrationsportal to send messages to the push service.

Install .NET Core Windows Hosting Bundle

You can run the Microsoft .Net 5.07 Windows Server Hosting installer (dotnet-hosting-6.0.9-win.exe) which is delivered with WorkZone Process to install .NET Core Windows Hosting Bundle, or you can install it with a PowerShell script.

Install with 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 with the WorkZone e-Boks Push Service Setup wizard

You must run the installer with elevated privileges on both web and agent servers 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 with 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 automatically deploy the push service 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 by using the WorkZonee-Boks Push Service Setup wizard. See Install WorkZone e-Boks Push Service with 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:

It should result in the following XML:

You can also use the following URL:

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

which results in the following XML:

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

Install a stand-alone e-Boks Push Service

You can install the e-Boks Push Service on a Windows server that does not have a WorkZone database or WorkZone Process installed.

For the NgDP PUSH dispatcher to work, you need to install the hosting bundle supplied with the WorkZone Process (dotnet-hosting-X.X.X-win.exe).

When installing the push service, you must run the MSI installer manually from an elevated PowerShell session.

If you invoke the installation through a remote PowerShell session, you can add the /quite flag the arguments.

Verify the installation

You can verify that the push service is installed and works by running the administration script Init-PushServiceModule.ps1 located in

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

Invoke the cmdlet Get-PushServiceConfiguration.

The service is installed correctly if no errors occur.

Whitelist IP addresses

Make sure to whiteliste IP addresses from NgDP to WorkZone. Please refer to Technical Integration NgDP v1.30 on the Agency for Digitisation's website (Digitaliseringsstyrelsen). You also need to make sure that the WorkZone web and agent servers are whitelisted.

Method level access control

It is possible to control access to the web service for external and internal methods. External methods are methods that are called by NgDP and internal methods are methods that are called by WorkZone server-side modules.

It is possible to whitelist certificates when installing the push service from command line using new arguments INTERNAL_CERTIFICATE_WHITELIST and EXTERNAL_CERTIFICATE_WHITELIST.

Installation example:

When whitelisting is enabled, it is required that IIS accepts the client certificates that are in use. This means, for example, that the root certificates must be trusted and not be expired.

If the web service is protected with certificates, the push service PowerShell administration module must also use this certificate. This can be done by initializing the module with one of the whitelisted client certificates.

PowerShell example:

.\Init-PushServiceModule.ps1 -Certificate (dir Cert:\LocalMachine\My\344CDEA8138E11AB1CB216A0AB6FAA07E08F19DD)
				

It is also possible to white list ip addresses using arguments INTERNAL_IP_WHITELIST and EXTERNAL_IP_WHITELIST. Note that IP access permissions have lower priority than certificate access permissions.

Please refer on the Agency for Digitisation's website (Digitaliseringsstyrelsen) for finding certificates that can be used with NgDP.

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

The push service has its own 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 another 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.

You can do manual configuration from a WorkZone database 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 the rights 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 if it is possible to send NgDP messages to a specific contact point. Contact points can be assigned to addresses in the WorkZone database by using custom address info with the label NgDpCp.

To test if it is possible to send NgDP messages, it is required to create the metadata for the address property and address type. This can be done with 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 informing that the title column exceeds the maximum length:

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

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