Deployment guidelines for the control unit integration sample for Sweden (legacy)

This article provides guidelines for deploying the control unit integration sample for Sweden from the Retail software development kit (SDK) on a developer virtual machine (VM) in Microsoft Dynamics Lifecycle Services (LCS). For more information about this fiscal integration sample, see Control unit integration sample for Sweden.

The fiscal integration sample for Sweden 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), 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 CRT 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.CleanCashSample component

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

2. In the Runtime.Extensions.DocumentProvider.CleanCashSample\bin\Debug folder, find the Contoso.Commerce.Runtime.DocumentProvider.CleanCashSample.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.CleanCashSample" />
   

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

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.

CleanCash component

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

2. In the Extension.CleanCashSample\bin\Debug folder, find the Contoso.Commerce.HardwareStation.CleanCashSample.dll and Interop.CleanCash_1_1.dll assembly files.

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 under the IIS Hardware station site location.
   • Dedicated hardware station on Modern POS: The file is 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.CleanCashSample" />
   

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 that must be loaded by adding the following lines in the extensions.json file.

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

   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 that must be loaded by adding the following lines in the extensions.json file.

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

   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 control unit 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.CleanCashSample" />
     <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSweden" />
     

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

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

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

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

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

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

     <ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.HardwareStation.CleanCashSample.dll" />
     <ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Interop.CleanCash_1_1.dll" />
     

3. Enable the POS extension by adding the following lines in the extensions.json file under the RetailSDK\POS\Extensions folder.

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

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

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

6. Complete all the required setup tasks that are described in Setting up the integration with control units.

Design of the extensions

CRT extension design

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

The CRT extension is Runtime.Extensions.DocumentProvider.CleanCashSample.

For more information about the design of the fiscal integration solution, see Fiscal registration process and fiscal integration samples for fiscal devices and services.

Request handler

There is a single DocumentProviderCleanCash request handler for the document provider. This handler is used to generate fiscal documents for the control unit.

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 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 control unit.
• GetSupportedRegistrableEventsDocumentProviderRequest – This request returns the list of events to subscribe to. Currently, sales events and audit events are supported.

Configuration

The DocumentProviderFiscalCleanCashSample configuration file is 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 codes mapping

Hardware station extension design

The purpose of the extension that is a fiscal connector is to communicate with the control unit.

The Hardware station extension is HardwareStation.Extension.CleanCashSample. It uses the HTTP protocol to submit documents that the CRT extension generates to the control unit. It also handles the responses that are received from the control unit.

Request handler

The CleanCashHandler request handler is the entry point for handling requests to the control unit.

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 control unit and returns a response from it.
• IsReadyFiscalDeviceRequest – This request is used for a health check of the control unit.
• InitializeFiscalDeviceRequest – This request is used to initialize the control unit.

Configuration

The configuration file is 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:

• Connections string – The control unit connection settings.
• Timeout – The amount of time, in milliseconds, that the driver will wait for a response from the control unit.

Migrating from the earlier integration sample

If you're using the earlier sample for POS integration with control units for Sweden, you might have to migrate from it to the current integration sample. To uptake the change and receive timely updates for the features for Sweden in the future, you might have to upgrade, make minor code and configuration adjustments in the extensions that you built, and rebuild your solutions. No major changes are required in the extension logic that you created. The earlier integration sample and your customizations will continue to work if no changes are made from your side. Therefore, you can plan, prepare for, and do the uptake for your environment.

Migration process

The migration from the earlier integration sample to the current control unit integration sample should be based on the concept of a gradual update. In other words, all Commerce headquarters and Commerce Scale Unit components should already be updated before you start to update the POS and Hardware station components.

To help prevent a situation where an event or transaction is signed twice (that is, it's signed by both the earlier extension and the current extension), or where an event or transaction can't be signed because of the missing configuration, we recommend that you turn off all POS and Hardware station devices that use the earlier sample, and then update them simultaneously. This simultaneous update can be done, for example, on a store-by-store basis by updating the store's functionality profile and the Hardware station's hardware profile.

The migration process should consist of the following steps.

1. Update the Commerce headquarters components.

2. Update the Commerce Scale Unit components, and enable the extensions of the current sample.

3. Make sure that all offline transactions are synced from offline-enabled MPOS devices.

4. Turn off all devices that use the components of the earlier sample.

5. Complete all the required setup tasks that are described in Setting up the integration with control units.

6. Update the POS and Hardware station components, disable the extensions that are parts of the earlier sample, and enable the extensions of the current sample.

   Note

   Depending on the type of environment, you can find more technical details about the migration process in either the Migration in a development environment section or the Migration in a production environment section of this article.

Migration in a development environment

Update CRT

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

2. In the Runtime.Extensions.DocumentProvider.CleanCashSample\bin\Debug folder, find the Contoso.Commerce.Runtime.DocumentProvider.CleanCashSample.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 in the bin\ext folder under the local CRT client broker location.

   Warning

   Do not edit the CommerceRuntime.config and CommerceRuntime.MPOSOffline.config files. These files aren't intended for any customizations.

5. Find and remove the earlier CRT extension from the extension configuration file.

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

   Warning

   Don't complete this step until you update all POS devices that work with this CRT instance.

6. Register the current sample CRT extensions in the extension configuration file by adding the following lines.

   <add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.CleanCashSample" />
   <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSweden" />
   

Update Hardware station

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

2. In the Extension.CleanCashSample\bin\Debug folder, find the Contoso.Commerce.HardwareStation.CleanCashSample.dll and Interop.CleanCash_1_1.dll assembly files.

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 HardwareStation.Extension.config extension configuration file:

   • Remote Hardware station: The file is under the IIS Hardware station site location.
   • Local Hardware station on Modern POS: The file is under the Modern POS client broker location.

   Warning

   Do not edit the CommerceRuntime.config and CommerceRuntime.MPOSOffline.config files. These files aren't intended for any customizations.

5. Find and remove the earlier Hardware station extension from the extension configuration file.

   Retail 7.3 and earlier

   <add source="assembly" value="Contoso.Commerce.HardwareStation.Extension.FiscalRegisterSample" />
   

   Retail 7.3.1 and later

   <add source="assembly" value="Contoso.Commerce.HardwareStation.Extension.FiscalRegisterSample" />
   

   Retail 10.0 and later

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

6. Add the following line to the composition section of the extension configuration file.

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

Update Modern POS

1. Open the CloudPOS.sln solution under RetailSdk\POS.

2. Disable the earlier POS extension by removing the following lines from the extensions.json file.

   {
       "baseUrl": "FiscalRegisterSample"
   }
   

3. Enable the current sample POS extension by adding the following lines in the extensions.json file.

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

Update Cloud POS

1. Open the ModernPOS.sln solution under RetailSdk\POS.

2. Disable the earlier POS extension by removing the following lines from the extensions.json file.

   {
       "baseUrl": "FiscalRegisterSample"
   }
   

3. Enable the current sample POS extension by adding the following lines in the extensions.json file.

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

Migration in a production environment

Update CRT

1. Remove the earlier CRT extension from the CommerceRuntime.ext.config and CommerceRuntime.MPOSOffline.Ext.config configuration files under the RetailSdk\Assets folder.

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

   Warning

   Don't complete this step until you update all POS devices that work with this CRT instance.

2. Enable the current sample CRT extensions by making the following changes in the CommerceRuntime.ext.config and CommerceRuntime.MPOSOffline.Ext.config configuration files under the RetailSdk\Assets folder.

   <add source="assembly" value="Contoso.Commerce.Runtime.DocumentProvider.CleanCashSample" />
   <add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.ReceiptsSweden" />
   

3. In the Customization.settings package customization configuration file under the BuildTools folder, add the following line to include the current sample CRT extension in deployable packages.

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

Update Hardware station

1. Remove the earlier Hardware station extension by modifying the HardwareStation.Extension.config configuration file.

   Retail 7.3 and earlier

   Remove the following section from the HardwareStation.Shared.config and HardwareStation.Dedicated.config configuration files.

   <add source="assembly" value="Contoso.Commerce.HardwareStation.Extension.FiscalRegisterSample" />
   

   Retail 7.3.1 and later

   Remove the following section from the HardwareStation.Extension.config configuration file.

   <add source="assembly" value="Contoso.Commerce.HardwareStation.Extension.FiscalRegisterSample" />
   

   Retail 10.0 and later

   Remove the following section from the HardwareStation.Extension.config configuration file.

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

2. Enable the current sample Hardware station extension by adding the following line to the composition section in the HardwareStation.Extension.config configuration file.

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

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

   • Remove the following line to exclude the earlier Hardware station extension from deployable packages.

     <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.HardwareStation.Extension.FiscalRegisterSample.dll" />
     

   • Add the following lines to include the current sample Hardware station extension in deployable packages.

     <ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.HardwareStation.CleanCashSample.dll" />
     <ISV_HardwareStation_CustomizableFile Include="$(SdkReferencesPath)\Interop.CleanCash_1_1.dll" />
     

Update Modern POS

1. Open the CloudPOS.sln solution at RetailSdk\POS.

2. Disable the earlier POS extension:

   • In the tsconfig.json file, add the FiscalRegisterSample folder to the exclude list.

   • Remove the following lines from the extensions.json file under the RetailSDK\POS\Extensions folder.

     {
         "baseUrl": "FiscalRegisterSample"
     }
     

3. Enable the current sample POS extension by adding the following lines in the extensions.json file under the RetailSDK\POS\Extensions folder.

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

Update Cloud POS

1. Open the ModernPOS.sln solution under RetailSdk\POS.

2. Disable the earlier POS extension:

   • In the tsconfig.json file, add the FiscalRegisterSample folder to the exclude list.

   • Remove the following lines from the extensions.json file under the RetailSDK\POS\Extensions folder.

     {
         "baseUrl": "FiscalRegisterSample"
     }
     

3. Enable the current sample POS extension by adding the following lines in the extensions.json file under the RetailSDK\POS\Extensions folder.

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

Create deployable packages

Run msbuild for the whole Retail SDK to create deployable packages. Apply the packages via LCS or manually. For more information, see Retail SDK packaging.