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.