Enable Certified POS system for France in Microsoft Dynamics AX 2012 R3 for Retail (binary)

Applies to: Dynamics AX 2012 R3

Introdution


This update is a binary part of the combined update that enables Microsoft Dynamics AX 2012 R3 for Retail localization functionality for France. With this combined update, Microsoft Dynamics AX 2012 R3 for Retail is certified per the NF 525 certification requirements. See KB 4058329 for the application part of the update.

This article provides an overview of the steps required to configure Microsoft Dynamics AX 2012 R3 for Retail points-of-sales (POS) to be used in stores located in France, as well as an overview of the components of the Retail localization solution for France included in Retail SDK.

See KB 4058329 for more information about the Microsoft Dynamics AX 2012 R3 for Retail localization for France and the required localization setup steps.

Configuring POS for France


The below sections describe the procedures that are required to configure point-of-sale (POS) for France.

Configure Enterprise POS for France

To enable digital signing of sales transactions in Enterprise POS, you need to install a certificate and add the required settings to the application configuration file POS.exe.config:

  1. Install a valid digital certificate to the local certificate storage on the Enterprise POS machine.
  1. Copy the following code to the configSections section of the POS.exe.config file:

<sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >

<section name="Microsoft.Dynamics.Retail.FiscalRegistrationServices.DigitalSignatureFiscalRegister.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" />

<section name="Microsoft.Dynamics.Retail.FiscalRegistrationServices.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" allowExeDefinition="MachineToLocalUser" requirePermission="false" />

</sectionGroup>  

  1. Copy the following code to the applicationSettings section of the POS.exe.config file:

<Microsoft.Dynamics.Retail.FiscalRegistrationServices.Properties.Settings>

<setting name="FiscalRegisterAssembly_FR" serializeAs="String">

<value>DigitalSignatureFiscalRegister.dll</value>

</setting>

<setting name="FiscalRegisterClass_FR" serializeAs="String">

<value>Microsoft.Dynamics.Retail.FiscalRegistrationServices.DigitalSignatureFiscalRegister.DigitalSignatureFiscalRegister</value>

</setting>

</Microsoft.Dynamics.Retail.FiscalRegistrationServices.Properties.Settings>

<Microsoft.Dynamics.Retail.FiscalRegistrationServices.DigitalSignatureFiscalRegister.Properties.Settings>

<setting name="CertificateStoreName" serializeAs="String">

<value>My</value>

</setting>

<setting name="CertificateStoreLocation" serializeAs="String">

<value>LocalMachine</value>

</setting>

<setting name="EncodingName" serializeAs="String">

<value>UTF-8</value>

</setting>

<setting name="DataHashAlgorithm" serializeAs="String">

<value>SHA1</value>

</setting>

<setting name="CertificateThumbprint" serializeAs="String">

<value></value>

</setting>

</Microsoft.Dynamics.Retail.FiscalRegistrationServices.DigitalSignatureFiscalRegister.Properties.Settings>

  1. Setup correct CertificateStoreName, CertificateStoreLocation and CertificateThumbprint values of the installed certificate in the applicationSettings section of the POS.exe.config file.

Configure Modern POS for France

To enable digital signature feature in Modern POS, you need to install a certificate and add the required settings to the Commerce Run-time configuration file commerceRuntime.config.

  1. Install a valid digital certificate to the local certificate storage on the Modern POS machine.
  1. Add the following code to the composition section of the commerceRuntime.config file located in the Retail Server installation folder:

<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.Services.FiscalRegisterServiceFrance, Version=6.3.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL" />

<add source="assembly" value="Microsoft.Dynamics.Commerce.Runtime.Services.DigitalSignature, Version=6.3.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL" />

  1. Make the same changes to the commerceRuntime.config file located in the Client Broker installation folder to support offline mode.
  1. Setup correct certificateStoreName, certificateStoreLocation and certificateThumbprint values of the installed certificate in the Microsoft.Dynamics.Commerce.Runtime.Services.FiscalRegisterServiceFrance.dll.config file.

SDK overview


The below sections provide an overview of the components of the Retail localization solution for France included in Retail SDK. You can modify these components to customize or extend the localization functionality.

Enterprise POS

The solution consists of three new projects, two new interfaces and three new database tables. Besides that, several existing interfaces are extended with new methods.

  • The DigitalSignatureFiscalRegister project is in the Retail SDK\POS Plugins\FiscalRegistrationServices and is part of the FiscalRegistrationServices solution.
  • The FranceTriggers project is located in the Retail SDK\POS Plug-ins\Triggers folder and is part of the Triggers solution.
  • The new interfaces of IAuditEventTrigger and IBatchOperationTrigger are parts of the Contracts assembly.
  • The existing interface of IApplicationTrigger is extended with two new methods:
    • ApplicationSettingChanged is called after an application setting such as training mode or offline mode is changed;
    • PostPurgeChannelData is called after cleaning transactions from the Channel database.
  • The existing interface of IPrintingTrigger is extended with two new methods:
    • GetReceiptFieldInfo is called before printing a field on a receipt;
    • PostPrintReceiptCopy is called after printing a copy of a receipt.
  • The new RetailLogTransactionReference table is used to store references between audit log events and corresponding retail transactions such as reference between the event of printing of a copy of a receipt and the original retail transaction.
  • The new RetailLogFiscalTransaction table is used to store registration information for audit log events.
  • The new RetailFiscalRegistrationSequence table is used to store last sequential numbers for several types of signed objects such as retail transactions and audit events.

Audit event trigger

The new AuditEvent trigger is added to enable the customization of the audit event creation process. This trigger works the same way as other triggers and is loaded by MEF. It provides two methods of PreLogEvent and PostLogEvent, which are called before and after logging an audit event, respectively.

The new IAuditEventTrigger interface was added to the Contracts library. This interface describes the PreLogEvent and PostLogEvent methods.

The PreLogEvent method can interrupt the logging process and show messages via the standard PreTriggerResult object. To use the AuditEvent trigger, a new class needs to be created. This class should implement the IAuditEventTrigger interface. In this case, MEF will load the class during the application startup.

FranceTriggers

The FranceTriggers project contains standard POS triggers that are loaded if the ISO code field of the functionality profile of POS is set to FR.

  • The BatchOperationTrigger implements the IBatchOperationTrigger interface and overrides the SaveCloseBatch method. The method logs an audit event of closing a shift.
  • The FranceApplicationTrigger implements the IApplicationTrigger interface and overrides the ApplicationStart and PostLogon methods. 
    • The ApplicationStart method initializes the registration state of the RegistrationManager by calling the ActualizeRegistrationState method;
    • The PostLogon method checks the shift state by calling the CheckShiftClosing method of the ShiftClosingChecker class if a logon operation was successful. The method displays a warning if the current shift lasts longer than the pre-defined time.
  • The FranceAuditEventTrigger implements the IAuditEventTrigger interface and overrides the PreLogEvent and PostLogEvent methods.
    • The PreLogEvent method receives the IAuditEvent object and performs the registration of the audit event if audit is enabled.
    • The PostLogEvent method receives the IAuditEvent object and finalizes the registration of the audit event if audit is enabled by saving fiscal registration information.
  • The FranceOperationTrigger implements the IOperationTrigger interface and overrides the PreProcessOperation method. The method checks the shift state by calling the CheckShiftClosing method of the ShiftClosingChecker class. The method blocks the operation if the current shift lasts longer than the pre-defined time and displays a warning message. 
  • The FrancePaymentTrigger implements the IPaymentTrigger interface and overrides the PrePayment method. The method behaves the same way as the PreProcessOperation method and blocks the payment if the current shift lasts longer than the pre-defined time.
  • The FrancePrintingTrigger implements the IPrintingTrigger interface and overrides the GetReceiptFieldInfo method. The method receives the IReceiptField and the IReceiptPrintingContext objects and calculates the value of the receipt field being printed.
  • The FranceTransactionTrigger implements the ITransactionTrigger and overrides the PreEndTransaction and SaveTransaction methods.
    • The PreEndTransaction method receives the IPosTransaction object and performs registration of the retail transaction. Additionally, it checks the shift state and blocks the transaction if the current shift lasts longer than the pre-defined time.
    • The SaveTransaction method receives the IPosTransaction object and finalizes the registration of the retail transaction by saving the fiscal registration information.

DigitalSignatureFiscalRegister

The DigitalSignatureFiscalRegister project provides the functionality to digitally sign retail transactions and audit events. 

  • The CertificateHelper class provides methods for loading certificates from the certificate store.
  • The DigitalSignatureFiscalRegister class implements the IFiscalRegisterDriver interface and overrides the Initialize and RegisterFiscalData methods.
    • The Initialize method loads digital signature settings such as the certificate thumbprint and location from the configuration file.
    • The RegisterFiscalData method receives the serialized fiscal information and calculates the digital signature.
  • The DigitalSignatureFiscalRegisterResponse class represents the digital signature register response.

Registration process

The registration processes for audit events and retail transactions are similar. There are adapter classes implementing the IRegistrableEvent interface for each registerable object type in the FranceTriggers project:

  • The RegistrableEventAuditEventAdapter class to support audit event registration
  • The RegistrableEventRetailTransactionAdapter to support retail transaction registration
  • The RegistrableEventShiftTransactionEventAdapter to support registration of the event of closing a shift

The adapters are responsible for extracting and serializing the information used for registration from the registerable objects. An adapter of the appropriate type is created inside trigger methods such as PreEndTransaction, PreLogEvent and SaveCloseBatch by the RegistrableEventFactory class.

Registration of any registerable event object is performed by the RegistrationManager class located in the FranceTriggers project. The RegistrationManager uses the DefaultFiscalRegistrationService service which implements the IFiscalRegister interface and is loaded by MEF. 

DefaultFiscalRegistrationService creates and sets an instance of IFiscalRegisterDriver. It uses the FiscalRegisterFactory class to create an appropriate instance of IFiscalRegisterDriver and produce an instance of the DigitalSignatureFiscalRegister class under the France country/region context.

Serialized fiscal registration data is stored in the JSON format in the RetailTransactionFiscalTransaction and RetailLogFiscalTransaction database tables for retail transactions and audit events, respectively.

Retail Server

Four new Retail Server, requests were added to support the Retail localization for France:

  • GetFiscalRegistrationSequenceTypeValue to get fiscal registration sequence type for a specified transaction type or audit event type.
  • GetLastRegisteredFiscalData request to get last registered fiscal data for a specified transaction type or audit event type.
  • RegisterAuditEvent request to register audit events.
  • GetShiftClosingStateInfo request to get the state of shift and the time of closing of the shift.

Corresponding methods could be found in the ShiftManager and StoreOperationsManager retail proxy adapters in Retail SDK\Proxies\RetailProxy\Adapters.

Commerce Run-time

The Commerce Run-time localization consists of two new projects, a new request and handlers:

  • The SDK.DigitalSignature project is in Retail SDK\Commerce Run-time\SDK.DigitalSignature and is part of the Sdk.CommerceRuntime solution.
  • The SDK.FiscalRegisterServiceFrance project is in Retail SDK\Commerce Run-time\SDK.DigitalSignature and is part of the Sdk.CommerceRuntime solution.

SDK.DigitalSignature

The project is similar to the Enterprise POS’s DigitalSignatureFiscalRegister project. It provides the functionality to digitally sign retail transactions and audit events. 

  • The CertificateHelper class provides methods for loading certificates from the certificate store.
  • The DataSignatureRequestHandler class implements the IRequestHandler interface and handles the DigitalSignatureServiceRequest request.

DigitalSignatureServiceRequest is used to sign the specified data with the certificate.

SDK.FiscalRegisterServiceFrance

The SDK.FiscalRegisterServiceFrance project contains FiscalRegistrationService which handles a number of new requests:

  • GetFiscalRegistrationSequenceTypeServiceRequest is a new request to determine the fiscal sequence type from a sales transaction type or audit event type.
  • GetLastRegisteredFiscalDataServiceRequest is a new request to retrieve the last saved fiscal data for a specified fiscal sequence type.
  • GetFiscalRegistrationSequenceServiceRequest is a new request to retrieve the current sequential number for a specific store, terminal and sequence type.
  • GetSalesOrderFiscalRegistrationInfoRequest is a new request to retrieve fiscal data from a sales order.
  • ParseFiscalRegisterDataRequest is a new request to parse a serialized register response in the JSON format to an object.
  • SaveSalesTransactionDataRequest is an overridden request that performs the registration of sales transaction and then calls the original request handler to save the transaction. 
  • RegisterAuditEventServiceRequest is a new request to register audit events.
  • RegisterShiftCloseAuditEventRequest is a new request to register events of closing of shifts.

Modern POS

Localization of Modern POS includes changes in several views and view models located in Retail SDK\ POS Clients\Framework.

Pre-operation handlers

The new IPreOperationHandler interface was introduced. It describes the following method:

executeHandler(operationId: Commerce.Operations.operationTypeEnum): IAsyncResult<ICancelableResult>;

The purpose of the method is to implement additional checks before performing Modern POS operations. The executeHandler method receives the type of the current operation and can block the operation by returning an appropriate ICancelableResult asynchronously.

An instance of the IPreOperationHandler interface is registered by calling the registerPreOperationHandler method of OperationsManager.

Shift state check

Shift state check is managed by ShiftClosingManagerFrance implementing the IShiftClosingManager interface. ShiftClosingManagerFactory is responsible for the creation of the appropriate instance of IShiftClosingManager and creates ShiftClosingManagerFrance under the France country/region context. 

ShiftClosingManagerFrance also implements the IPreOperationHandler interface and is used to block several operations if the shift last longer than the specified time. It is registered as a pre-operation handler of the OperationsManager class under the France country/region context.

ShiftClosingManagerFrance requests shift state before each payment and sales operation using the GetShiftClosingStateInfo Retail Server request.

Registration process

The registration of sales transactions and audit events is managed by the FiscalRegistrationManagerFrance class implementing the IFiscalRegistrationManager interface. The FiscalRegistrationManagerFactory class is responsible for the creation of the appropriate implementation of IFiscalRegistrationManager and creates FiscalRegistrationManagerFrance under the France country/region context.

The registration of sales transactions starts in the CartViewModel class in the checkOutCart method. CartViewModel uses FiscalRegistrationManagerFrance to execute registration logic before and after the checkout. 

The pre-checkout logic extracts the registration information (register response) for the last registered sales transaction from the local storage (if it exists) or requests it from Retail Server using the GetLastRegisteredFiscalData request. The last register response passed as extension properties of the Cart object to the checkout. The extension property storing the last register response is then extracted while handling SaveSalesTransactionDataRequest in Commerce Run-time and is used to produce the digital signature of the current transaction.

The post checkout logic saves the current register response to the local storage to be used in future requests.

The registration of audit events is performed by the registerAuditEvent method of the FiscalRegistrationManagerFrance class and is initiated from various points:

  • The registration of the Logon audit event is initiated from LoginViewModel after a successful operator logons.
  • The registration of the Logoff audit event is initiated from LogoffOperationHandler.
  • The registration of the Purge audit event is initiated from the BlindCloseShiftOperationHandler and CloseShiftOperationHandler classes.
  • The registration of the events of starting and ending of the offline mode is initiated from the ChainedRequestFactory class.
  • The registration of the event of printing of a copy of a receipt is initiated from ReceiptViewModel.

Modern POS registers audit events by sending the RegisterAuditEvent request to Retail Server. The request then passed to the Commerce Run-time service FiscalRegistrationService.

Hotfix information


How to obtain the Microsoft Dynamics AX updates files

This update is available for manual download and installation from the Microsoft Download Center.

Prerequisites

You must have one of the following products installed to apply this hotfix:

  • Microsoft Dynamics AX 2012 R3

Restart requirement

You must restart the Application Object Server (AOS) service after you apply the hotfix.

If you are encountering an issue downloading, installing this hotfix, or have other technical support questions, contact your partner or, if enrolled in a support plan directly with Microsoft, you can contact technical support for Microsoft Dynamics and create a new support request. To do this, visit the following Microsoft website:

https://mbs.microsoft.com/support/newstart.aspx

You can also contact technical support for Microsoft Dynamics by phone using these links for country specific phone numbers. To do this, visit one of the following Microsoft websites:

Partners

https://mbs.microsoft.com/partnersource/resources/support/supportinformation/Global+Support+Contacts

Customers

https://mbs.microsoft.com/customersource/northamerica/help/help/contactus

In special cases, charges that are ordinarily incurred for support calls may be canceled if a Technical Support Professional for Microsoft Dynamics and related products determines that a specific update will resolve your problem. The usual support costs will apply to any additional support questions and issues that do not qualify for the specific update in question.

Note This is a "FAST PUBLISH" article created directly from within the Microsoft support organization. The information contained here in is provided as-is in response to emerging issues. As a result of the speed in making it available, the materials may include typographical errors and may be revised at any time without notice. See Terms of Use for other considerations.