Deployment guidelines for cash registers for Norway

Important

This topic applies to Dynamics 365 for Retail and Dynamics 365 for Finance and Operations.

This topic is a deployment guide that shows how to enable the Microsoft Dynamics 365 for Retail localization for Norway. The localization consists of several extensions of Retail components. For example, the extensions let you print custom fields on receipts, register additional audit events, sales transactions, and payment transactions in Point of Sale (POS), digitally sign sales transactions, and print X and Z reports in local formats. For more information about the Retail localization for Norway, see Cash registers for Norway.

This sample is part of the Retail software development kit (SDK). For information about how to install and use the Retail SDK, see the Retail SDK documentation.

This sample consists of extensions for the Commerce runtime (CRT), Retail Server, and POS. To run this sample, you must modify and build the CRT, Retail Server, and POS projects. We recommend that you use an unmodified Retail SDK to make the changes that are described in this topic. We also recommend that you use a source control system, such as Microsoft Visual Studio Online (VSO), where no files have been changed yet.

Note

Some steps in the procedures in this topic differ, depending on the version of Retail that you're using. For more information, see What's new or changed in Dynamics 365 for Retail.

Development environment

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

The CRT extension components

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

ReceiptsNorway component

  1. Find the Runtime.Extensions.ReceiptsNorway project, and build it.

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

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

    • Retail Server: Copy the assembly to the \bin\ext folder under the Microsoft Internet Information Services (IIS) Retail Server site location.
    • Local CRT on Modern POS: Copy the assembly to the \ext folder under the local CRT client broker location.
  4. Find the extensions configuration file for CRT:

    • Retail Server: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Retail Server 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 extensions configuration file.

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

    Warning

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

SalesPaymentTransExt component

  1. Find the Runtime.Extensions.SalesPaymentTransExt project, and build it.

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

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

    • Retail Server: Copy the assembly to the \bin\ext folder under the IIS Retail Server site location.
    • Local CRT on Modern POS: Copy the assembly to the \ext folder under the local CRT client broker location.
  4. Find the extensions configuration file for CRT:

    • Retail Server: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Retail Server 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 extensions configuration file.

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

    Warning

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

XZReportsNorway component

  1. Find the Runtime.Extensions.XZReportsNorway project, and build it.

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

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

    • Retail Server: Copy the assembly to the \bin\ext folder under the IIS Retail Server site location.
    • Local CRT on Modern POS: Copy the assembly to the \ext folder under the local CRT client broker location.
  4. Find the extensions configuration file for CRT:

    • Retail Server: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Retail Server 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 extensions configuration file.

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

    Warning

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

RegisterAuditEvent sample component

  1. Find the Runtime.Extensions.RegisterAuditEventSample project, and build it.

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

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

    • Retail Server: Copy the assembly to the \bin\ext folder under the IIS Retail Server site location.
    • Local CRT on Modern POS: Copy the assembly to the \ext folder under the local CRT client broker location.
  4. Find the extensions configuration file for CRT:

    • Retail Server: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Retail Server 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 extensions configuration file.

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

    Warning

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

SalesTransactionSignature sample component

  1. Find the Runtime.Extensions.SalesTransactionSignatureSample project.

  2. Modify the App.config file by specifying the thumbprint, store location, and store name for the certificate that should be used to sign sales transactions.

  3. Build the project.

  4. In the Extensions.SalesTransactionSignatureSample\bin\Debug folder, find the following files:

    • The Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll assembly file
    • The Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll.config configuration file
  5. Copy the files to the CRT extensions folder:

    • Retail Server: Copy the assembly to the \bin\ext folder under the IIS Retail Server site location.
    • Local CRT on Modern POS: Copy the assembly to the \ext folder under the local CRT client broker location.
  6. Find the extensions configuration file for CRT:

    • Retail Server: The file is named commerceruntime.ext.config, and it's in the bin\ext folder under the IIS Retail Server 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.
  7. Register the CRT change in the extensions configuration file.

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

    Warning

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

The Retail Server extension components

SalesTransactionSignature Retail Server sample component

  1. In the RetailSDK\SampleExtensions\RetailServer\RetailServer.Extensions.SalesTransactionSignatureSample folder, find the RetailServer.Extensions.SalesTransactionSignatureSample project, and build it.

  2. In the RetailServer\Extensions.SalesTransactionSignatureSample\bin\Debug folder, find the Contoso.RetailServer.SalesTransactionSignatureSample.dll assembly file.

  3. Copy the assembly file to the Retail Server extensions folder.

    The folder is the \bin folder under the IIS Retail Server site location.

  4. Find the configuration file for Retail Server. The file is named web.config, and it's in the root folder under the IIS Retail Server site location.

  5. Register the Retail Server extensions in the extensionComposition section of the configuration file.

    <add source="assembly" value="Contoso.RetailServer.SalesTransactionSignatureSample" />
    
  6. Register the dependencies of the Retail Server extensions.

    1. In the CommerceRuntime\Extensions.SalesTransactionSignatureSample\bin\Debug folder, find the following files:

      • The Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll assembly file
      • The Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll.config configuration file
    2. Copy the files to the \bin folder under the IIS Retail Server site location.

    3. Register the CRT change in the extensions configuration file for CRT. This file is named commerceruntime.ext.config, and it's in the bin folder under the IIS Retail Server site location.

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

The Modern POS extension components

Implement the proxy code for offline mode

This part is equivalent to the Retail Server controller, but it extends the local CRT that is used when the client isn't connected.

  1. In the customization.settings file, change the @(RetailServerLibraryPathForProxyGeneration) section so that it uses the new Retail Server assembly for proxy generation.

  2. Implement the following interface methods in the StoreOperationsManager class. For the first iteration, add the following code:

        public Task<bool> SalesTransactionSignatureServiceIsReady()
        {
            throw new NotImplementedException();
        }
        public Task<FiscalTransaction> GetLastFiscalTransaction(string storeNumber, string terminalId)
        {
            throw new NotImplementedException();
        }
    
  3. To regenerate the proxy code, build the Proxies folder from the command line by using the msbuild /t:Rebuild command.

  4. Resolve the Proxies.RetailProxy project dependencies:

    Open RetailSDK\Proxies\RetailProxy\Proxies.RetailProxy.csproj, add the RetailSDK\SampleExtensions\CommerceRuntime\Extensions.SalesTransactionSignatureSample\CommerceRuntime.Extensions.SalesTransactionSignatureSample project to the solution, and add a project reference to the RetailProxy project to reference SalesTransactionSignatureSample.

  5. Adjust the interface methods in the StoreOperationsManager class:

        public Task<bool> SalesTransactionSignatureServiceIsReady()
        {
            return Task.Run(() => CommerceRuntimeManager.Runtime.Execute<SalesTransactionSignatureServiceIsReadyResponse>(new SalesTransactionSignatureServiceIsReadyRequest(), null).IsReady);
        }
        public Task<FiscalTransaction> GetLastFiscalTransaction(string storeNumber, string terminalId)
        {
            return Task.Run(() => CommerceRuntimeManager.Runtime.Execute<GetLastFiscalTransactionResponse>(new GetLastFiscalTransactionRequest(), null).FiscalTransaction);
        }
    
  6. Update the dllhost.exe.config file so that the client broker loads the new RetailProxy assembly.

    <add key="RetailProxyAssemblyName" value="Contoso.Commerce.RetailProxy" />
    <add key="AdaptorCallerFullTypeName" value="Contoso.Commerce.RetailProxy.Adapters.AdaptorCaller" />
    

Retail proxy extension component (Retail 7.3.1 and later)

Complete the following procedure only if you're using Retail 7.3.1 and later.

  1. In the RetailSDK\SampleExtensions\RetailProxy\RetailProxy.Extensions.SalesTransactionSignatureSample folder, find the RetailServer.Extensions.SalesTransactionSignatureSample project, and build it.

  2. In the RetailProxy\RetailProxy.Extensions.SalesTransactionSignatureSample\bin\Debug folder, find the Contoso.Commerce.RetailProxy.SalesTransactionSignatureSample assembly file.

  3. Copy the assembly files to the \ext folder under the local CRT client broker location.

  4. Register the Retail proxy change in the extensions configuration file. The file is named RetailProxy.MPOSOffline.ext.config, and it's under the local CRT client broker location.

    <add source="assembly" value="Contoso.Commerce.RetailProxy.SalesTransactionSignatureSample" />
    

Modern POS extension components

  1. Open the solution at RetailSdk\POS\ModernPOS.sln, and make sure that it can be compiled without errors. Additionally, make sure that you can run Modern POS from Microsoft 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. Include the following existing source code folders in the Pos.Extensions project.

    • AuditEventExtensionSample
    • SalesTransactionSignatureSample
  3. Enable the extensions to be compiled in tsconfig.json by removing the following folders from the exclude list.

    • AuditEventExtensionSample
    • SalesTransactionSignatureSample
  4. Enable the extensions to be loaded in extensions.json by adding the following lines in the appropriate place.

    {
        "baseUrl": "AuditEventExtensionSample"
    },
    {
        "baseUrl": "SalesTransactionSignatureSample"
    }
    

    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.

  5. Rebuild the solution.

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

Cloud POS extension components

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

  2. Include following existing source code folders in the Pos.Extensions project.

    • AuditEventExtensionSample
    • SalesTransactionSignatureSample
  3. Enable the extensions to be compiled in tsconfig.json by removing following folders from the exclude list.

    • AuditEventExtensionSample
    • SalesTransactionSignatureSample
  4. Enable the extensions to be loaded in extensions.json by adding the following lines in the appropriate place.

    {
        "baseUrl": "AuditEventExtensionSample"
    },
    {
        "baseUrl": "SalesTransactionSignatureSample"
    }
    

    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.

  5. Rebuild the solution.

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

  7. Test the functionality.

Set up required parameters in Retail headquarters

For more information, see Cash registers for Norway.

Production environment

Follow these steps to create deployable packages that contain Retail components, and to apply those packages in a production environment.

  1. Complete the steps in the Cloud POS extension components or Modern POS extension components section earlier in this topic.

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

    1. 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.ReceiptsNorway" />
          <add source="assembly" value="Contoso.Commerce.Runtime.RegisterAuditEventSample" />
          <add source="assembly" value="Contoso.Commerce.Runtime.SalesPaymentTransExt" />
          <add source="assembly" value="Contoso.Commerce.Runtime.SalesTransactionSignatureSample" />
          <add source="assembly" value="Contoso.Commerce.Runtime.XZReportsNorway" />
      
    2. Enable Retail Proxy customization:

      In the dllhost.exe.config configuration file, add the following lines to the appSettings subsection of the configuration section.

      <add key="RetailProxyAssemblyName" value="Contoso.Commerce.RetailProxy"/>
      <add key="AdaptorCallerFullTypeName" value ="Contoso.Commerce.RetailProxy.Adapters.AdaptorCaller"/>
      
  3. Make the following changes in the Customization.settings package customization configuration file:

    1. Enable Retail Proxy customization

      Add the following lines to the <ItemGroup Condition="'@(RetailServerLibraryPathForProxyGeneration)' == ''"> section.

      <RetailServerLibraryPathForProxyGeneration Include="$(SdkReferencesPath)\Contoso.RetailServer.SalesTransactionSignatureSample.dll"/>
      
    2. Add the following lines to the ItemGroup section to include the CRT extensions in the deployable packages:

         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.ReceiptsNorway.dll" />
         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.RegisterAuditEventSample.dll" />
         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.SalesPaymentTransExt.dll" />
         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll" />
         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll.config" />
         <ISV_CommerceRuntime_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.XZReportsNorway.dll" />
      
    3. Add following lines to the ItemGroup section to include the Retail Server extension in the deployable packages:

         <ISV_RetailServer_CustomizableFile Include="$(SdkReferencesPath)\Contoso.RetailServer.SalesTransactionSignatureSample.dll" />
         <ISV_RetailServer_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll" />
         <ISV_RetailServer_CustomizableFile Include="$(SdkReferencesPath)\Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll.config" />
      
  4. Modify the certificate's configuration file by specifying the thumbprint, store location, and store name for the certificate that should be used to sign sales transactions. Then copy the configuration file to the References folder.

    The file is named Contoso.Commerce.Runtime.SalesTransactionSignatureSample.dll.config, and it's under CommerceRuntime\Extensions.SalesTransactionSignatureSample\bin\Debug.

  5. Update Retail Server configuration file. In the RetailSDK\Packages\RetailServer\Code\web.config file, add the following lines to the extensionComposition section.

        <add source="assembly" value="Contoso.RetailServer.SalesTransactionSignatureSample" />
    
  6. Run msbuild for the whole Retail SDK to create deployable packages.

  7. Apply the packages via Microsoft Dynamics Lifecycle Services (LCS) or manually. For more information, see Retail SDK packaging.

Enable the digital signature in offline mode for Modern POS

To enable the digital signature in offline mode for Modern POS, you must follow these steps after you activate Modern POS on a new device.

  1. Sign in to POS.
  2. On the Database connection status page, make sure that the offline database is fully synchronized. When the value of the Pending downloads field is 0 (zero), the database is fully synchronized.
  3. Sign out of POS.
  4. Wait a while for the offline database to be fully synchronized.
  5. Sign in to POS.
  6. On the Database connection status page, make sure that the offline database is fully synchronized. When the value of the Pending transactions in offline database field is 0 (zero), the database is fully synchronized.
  7. Restart Modern POS.