แก้ไข

แชร์ผ่าน

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

  • บทความ

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

The fiscal integration sample for Austria is part of the Retail SDK. For information about how to install and use the SDK, see Retail software development kit (SDK) architecture. The fiscal integration sample consists of extensions for the Commerce runtime (CRT), Hardware station, and point of sale (POS). To run this sample, you must modify and build the CRT, Hardware station, and POS 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.ReceiptsAustria" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.RegisterAuditEventAustria" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.XZReportsAustria" />

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

Enable Modern POS extension components

  1. Open the ModernPOS.sln solution under RetailSdk\POS, and make sure that it can be compiled without errors. Additionally, make sure that you can run Modern POS from Visual Studio by using the Run command.

    Note

    Modern POS must not be customized. You must enable User Account Control (UAC), and you must uninstall previously installed instances of Modern POS as required.

  2. Enable the extensions to be loaded by adding the following lines in the extensions.json file.

    {
    "extensionPackages": [
        {
            "baseUrl": "Microsoft/AuditEvent.AT"
        }
    ]
}

    Note

    For more information, and for samples that show how to include source code folders and enable extensions to be loaded, see the instructions in the readme.md file in the Pos.Extensions project.

  3. Rebuild the solution.

  4. Run Modern POS in the debugger, and test the functionality.

Enable Cloud POS extension components

  1. Open the CloudPOS.sln solution under RetailSdk\POS, and make sure that it can be compiled without errors.

  2. Enable the extensions to be loaded by adding the following lines in the extensions.json file.

    {
    "extensionPackages": [
        {
            "baseUrl": "Microsoft/AuditEvent.AT"
        }
    ]
}

    Note

    For more information, and for samples that show how to include source code folders and enable extensions to be loaded, see the instructions in the readme.md file in the Pos.Extensions project.

  3. Rebuild the solution.

  4. Run the solution by using the Run command and following the steps in the Retail SDK handbook.

Production environment

The previous procedure enables 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="Contoso.Commerce.Runtime.DocumentProvider.EFRSample" />
<add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.DataModelEFR" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsAustria" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.RegisterAuditEventAustria" />
<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.XZReportsAustria" />

    • In the HardwareStation.Extension.config configuration file, add the following line 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 line to include the Hardware station extension 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 Austria.

Design of extensions

The fiscal registration service integration sample for Austria 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.

Request handler

There are two request handlers for document providers:

  • DocumentProviderEFRFiscalAUT – This handler is used to generate fiscal documents for the fiscal registration service.
  • DocumentProviderEFRNonFiscalAUT – This handler is used to generate non-fiscal documents for the fiscal registration service.

These handlers are 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.
  • GetNonFiscalDocumentDocumentProviderRequest – This request contains information about what non-fiscal document should be generated. It returns a service-specific document that should be registered in the fiscal registration service.
  • GetSupportedRegistrableEventsDocumentProviderRequest – This request returns the list of events to subscribe to. Currently, the following events are supported: sales, printing X report, printing Z report, customer account deposits, customer order deposits, audit events, and non-sales transactions.
  • GetFiscalRegisterResponseToSaveDocumentProviderRequest – This request returns the response from the fiscal registration service. This response is serialized to form a string so that it's ready to be saved.

Configuration

The configuration files are located in the Configuration folder of the extension project:

  • DocumentProviderFiscalEFRSampleAustria – For fiscal documents.
  • DocumentProviderNonFiscalEFRSampleAustria – For non-fiscal documents.

The purpose of these files 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 setting is added:

  • VAT rates mapping

Hardware station extension design

The purpose of the fiscal connector extension is to communicate with the fiscal registration service. The Hardware station extension is named HardwareStation.Extension.EFRSample. It uses the HTTP or HTTPS 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.

The 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, that the driver will wait for a response from the fiscal registration service.

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.