Edit

Deployment guidelines for the fiscal registration service integration sample for Germany (legacy)

  • Article

Important

Some or all of the functionality noted in this article is available as part of a preview release. The content and the functionality are subject to change. For more information about preview releases, see Service update availability.

Important

You must follow the guidelines in this article only if you're using Microsoft Dynamics 365 Commerce version 10.0.28 or earlier. As of Commerce version 10.0.29, the fiscal registration service integration sample for Germany is available in the Commerce software development kit (SDK). For more information, see Configure channel components.

This article provides guidelines for deploying the fiscal registration service integration sample for Germany from the Dynamics 365 Commerce Retail SDK on a developer virtual machine (VM) in Microsoft Dynamics Lifecycle Services (LCS). For more information about this fiscal integration sample, see Fiscal registration service integration sample for Germany.

The fiscal integration sample for Germany is part of the Retail SDK. For information about how to install and use the SDK, see Retail software development kit (SDK) architecture. This sample consists of extensions for the Commerce runtime (CRT) and Hardware station. To run this sample, you must modify and build the CRT and Hardware station projects. We recommend that you use an unmodified Retail SDK to make the changes that are described in this article. We also recommend that you use a source control system such as Azure DevOps where no files have been changed yet.

Development environment

Follow these steps to set up a development environment so that you can test and extend the sample.

Enable Commerce runtime extensions

The CRT extension components are included in the CRT samples. To complete the following procedures, open the CommerceRuntimeSamples.sln solution under RetailSdk\SampleExtensions\CommerceRuntime.

DocumentProvider.EFRSample component

  1. Find the Runtime.Extensions.DocumentProvider.EFRSample project, and build it.

  2. In the Runtime.Extensions.DocumentProvider.EFRSample\bin\Debug folder, find the Contoso.Commerce.Runtime.DocumentProvider.EFRSample.dll assembly file.

  3. Copy the assembly file to the CRT extensions folder:

    • Commerce Scale Unit: Copy the file to the \bin\ext folder under the Internet Information Services (IIS) Commerce Scale Unit site location.
    • Local CRT on Modern POS: Copy the file to the \ext folder under the local CRT client broker location.

  4. Find the extension configuration file for CRT:

    • Commerce Scale Unit: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Commerce Scale Unit site location.
    • Local CRT on Modern POS: The file is named CommerceRuntime.MPOSOffline.Ext.config, and it's under the local CRT client broker location.

  5. Register the CRT change in the extension configuration file.

    <add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.EFRSample" />

DocumentProvider.DataModelEFR component

  1. Find the Runtime.Extensions.DocumentProvider.DataModelEFR project, and build it.

  2. In the Runtime.Extensions.DocumentProvider.DataModelEFR\bin\Debug folder, find the Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR.dll assembly file.

  3. Copy the assembly file to the CRT extensions folder:

    • Commerce Scale Unit: Copy the file to the \bin\ext folder under the IIS Commerce Scale Unit site location.
    • Local CRT on Modern POS: Copy the file to the \ext folder under the local CRT client broker location.

  4. Find the extension configuration file for CRT:

    • Commerce Scale Unit: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Commerce Scale Unit site location.
    • Local CRT on Modern POS: The file is named CommerceRuntime.MPOSOffline.Ext.config, and it's under the local CRT client broker location.

  5. Register the CRT change in the extension configuration file.

    <add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR" />

Extension configuration file

  1. Find the extension configuration file for CRT:

    • Commerce Scale Unit: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Commerce Scale Unit site location.
    • Local CRT on Modern POS: The file is named CommerceRuntime.MPOSOffline.Ext.config, and it's under the local CRT client broker location.

  2. Register the CRT change in the extension configuration file.

    <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsGermany" />

Enable fiscal connector extensions

You can enable fiscal connector extensions on the Hardware station or the POS register.

Enable Hardware station extensions

The Hardware station extension components are included in the Hardware station samples. To complete the following procedures, open the HardwareStationSamples.sln solution under RetailSdk\SampleExtensions\HardwareStation.

EFRSample component

  1. Find the HardwareStation.Extension.EFRSample project, and build it.

  2. In the Extension.EFRSample\bin\Debug folder, find the following assembly files:

    • Contoso.Commerce.HardwareStation.EFRSample.dll
    • Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR.dll

  3. Copy the assembly files to the Hardware station extensions folder:

    • Shared hardware station: Copy the files to the bin folder under the IIS Hardware station site location.
    • Dedicated hardware station on Modern POS: Copy the files to the Modern POS client broker location.

  4. Find the extension configuration file for the Hardware station's extensions. The file is named HardwareStation.Extension.config.

    • Shared hardware station: The file is located under the IIS Hardware station site location.
    • Dedicated hardware station on Modern POS: The file is located under the Modern POS client broker location.

  5. Add the following line to the composition section of the configuration file.

    <add source="assembly" value="Contoso.Commerce.HardwareStation.EFRSample.dll" />

Enable POS extensions

The POS extension sample is located in the src\FiscalIntegration\PosFiscalConnectorSample folder of the Dynamics 365 Commerce Solutions repository.

To use POS extension sample in the legacy SDK, follow these steps.

  1. Copy the Pos.Extension folder to the POS Extensions folder of the legacy SDK (for example, C:\RetailSDK\src\POS\Extensions).

  2. Rename the copy of the Pos.Extension folder PosFiscalConnector.

  3. Remove the following folders and files from the PosFiscalConnector folder:

    • bin
    • DataService
    • devDependencies
    • Libraries
    • obj
    • Contoso.PosFiscalConnectorSample.Pos.csproj
    • RetailServerEdmxModel.g.xml
    • tsconfig.json

  4. Open the CloudPos.sln or ModernPos.sln solution.

  5. In the Pos.Extensions project, include the PosFiscalConnector folder.

  6. Open the extensions.json file, and add the PosFiscalConnector extension.

  7. Build the SDK.

Production environment

In the previous procedure, you enabled the extensions that are components of the fiscal registration service integration sample. In addition, you must follow these steps to create deployable packages that contain Commerce components, and to apply those packages in a production environment.

  1. Make the following changes in the package configuration files under the RetailSdk\Assets folder:

    • In the commerceruntime.ext.config and CommerceRuntime.MPOSOffline.Ext.config configuration files, add the following lines to the composition section.

      <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsGermany" />
<add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.EFRSample" />
<add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR" />

    • In the HardwareStation.Extension.config configuration file, add the following lines to the composition section.

      <add source="assembly" value="Contoso.Commerce.HardwareStation.EFRSample" />
<add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR" />

  2. Make the following changes in the Customization.settings package customization configuration file under the BuildTools folder:

    • Add the following lines to include the CRT extensions in the deployable packages.

      <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.DocumentProvider.EFRSample.dll" />
<ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR.dll" />

    • Add the following lines to include the Hardware station extensions in the deployable packages.

      <ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.HardwareStation.EFRSample.dll" />
<ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR.dll" />

  3. Start the MSBuild Command Prompt for Visual Studio utility, and run msbuild under the Retail SDK folder to create deployable packages.

  4. Apply the packages via LCS or manually. For more information, see Create deployable packages.

  5. Complete all the required setup tasks that are described in Set up Commerce for Germany.

Design of extensions

The fiscal registration service integration sample for Germany is based on the fiscal integration functionality. For more information about the design of the fiscal integration solution, see the overview of a fiscal integration sample design.

Commerce runtime extension design

The purpose of the extension that is a fiscal document provider is to generate service-specific documents and handle responses from the fiscal registration service.

The CRT extension is Runtime.Extensions.DocumentProvider.EFRSample. For more information about the design of the fiscal integration solution, see Overview of fiscal integration for Commerce channels.

Request handler

There is one request handler for the document provider, DocumentProviderEFRFiscalDEU. This handler is used to generate fiscal documents for the fiscal registration service. It's inherited from the INamedRequestHandler interface. The HandlerName method is responsible for returning the name of the handler. The handler name should match the connector document provider name that is specified in Commerce headquarters.

The connector supports the following requests:

  • GetFiscalDocumentDocumentProviderRequest – This request contains information about what document should be generated. It returns a service-specific document that should be registered in the fiscal registration service.
  • GetFiscalTransactionExtendedDataDocumentProviderRequest – This request returns the response together with extended data.

Configuration

The DocumentProviderFiscalEFRSampleGermany configuration file is located in the Configuration folder of the extension project. The purpose of this file is to enable settings for the document provider to be configured from Commerce headquarters. The file format is aligned with the requirements for fiscal integration configuration.

The following settings are added:

  • VAT rates mapping – The mapping of tax percentage values that are set up for the sales tax codes to values of the TaxG (tax group) attribute in requests that are sent to the fiscal service.
  • Tax group for gift cards and deposits – The value of the TaxG attribute in requests that are sent to the fiscal service, based on operations that involve gift cards or deposits.
  • Tender type mapping – The mapping of payment methods to values of the PayG (payment group) attribute in requests that are sent to the fiscal service.
  • Tax group for VAT exempt – The value of the TaxG attribute in requests that are sent to the fiscal service, based on operations that are exempt from tax obligations.
  • Include customer data – If this parameter is turned on, requests to the fiscal service will contain customer information, such as names and addresses, in cases where a customer is added to a transaction.

Hardware station extension design

The purpose of the extension that is a fiscal connector is to communicate with the fiscal registration service.

The Hardware station extension is HardwareStation.Extension.EFRSample. It uses the HTTP protocol to submit documents that the CRT extension generates to the fiscal registration service. It also handles the responses that are received from the fiscal registration service.

Request handler

The EFRHandler request handler is the entry point for handling requests to the fiscal registration service. This handler is inherited from the INamedRequestHandler interface. The HandlerName method is responsible for returning the name of the handler. The handler name should match the fiscal connector name that is specified in Commerce headquarters.

The connector supports the following requests:

  • SubmitDocumentFiscalDeviceRequest – This request sends documents to the fiscal registration service and returns a response from it.
  • IsReadyFiscalDeviceRequest – This request is used for a health check of the fiscal registration service.
  • InitializeFiscalDeviceRequest – This request is used to initialize the fiscal registration service.

Configuration

The configuration file is located in the Configuration folder of the extension project. The purpose of the file is to enable settings for the fiscal connector to be configured from Commerce headquarters. The file format is aligned with the requirements for fiscal integration configuration.

The following settings are added:

  • Endpoint address – The URL of the fiscal registration service.
  • Timeout – The amount of time, in milliseconds (ms), that the driver will wait for a response from the fiscal registration service.
  • Show fiscal registration notifications – If this parameter is turned on, notifications from the fiscal service will be shown as user messages at the POS.

POS fiscal connector extension design

The purpose of the POS fiscal connector extension is to communicate with the fiscal registration service from POS. It uses the HTTPS protocol for communication.

Fiscal connector factory

The fiscal connector factory maps the connector name to the fiscal connector implementation and is located in the Pos.Extension\Connectors\FiscalConnectorFactory.ts file. The connector name should match the fiscal connector name that is specified in Commerce headquarters.

EFR fiscal connector

The EFR fiscal connector is located in the Pos.Extension\Connectors\Efr\EfrFiscalConnector.ts file. It implements the IFiscalConnector interface that supports the following requests:

  • FiscalRegisterSubmitDocumentClientRequest – This request sends documents to the fiscal registration service and returns a response from it.
  • FiscalRegisterIsReadyClientRequest – This request is used for a health check of the fiscal registration service.
  • FiscalRegisterInitializeClientRequest – This request is used to initialize the fiscal registration service.

Configuration

The configuration file is located in the src\FiscalIntegration\Efr\Configurations\Connectors folder of the Dynamics 365 Commerce Solutions repository. The purpose of the file is to enable settings for the fiscal connector to be configured from Commerce headquarters. The file format is aligned with the requirements for fiscal integration configuration. The following settings are added:

  • Endpoint address – The URL of the fiscal registration service.
  • Timeout – The amount of time, in milliseconds, that the connector will wait for a response from the fiscal registration service.