Integrating EAS (Electronic Article Surveillance) systems with Ginesys POS

Summary

This document explains how to integrate EAS anti-theft systems in a retail store running Ginesys POS. Standard EAS work on RF / RFID (Radio Frequency) systems, AM (Acoustic Magnetic) systems and EM (Electro Magnetic) systems. Ginesys POS EAS integration works generically and can integrate with any type of EAS systems that the brand may choose to have.

Background

The EAS system integration with Ginesys is based on an open integration mechanism via events hooks available in Ginesys POS. Generally, it requires manual removal of the anti-theft tags from the purchased items and there is a scope for reducing the billing time by automating the process. Ginesys being a retail ERP product, does not provide device or hardware specific solutions for such integrations. Instead, Ginesys provides events hooks for such integrations and partners can run custom code inside Ginesys that can work with specific hardware of EAS systems.

Automated EAS systems would require to know from Ginesys, which items have been invoiced at the cash counter. Once known, the item information has to be sent to the EAS gates for the hardware to allow the "purchased" items through the gates without triggering the alarm. This integration is achieved by creating a .NET Assembly by the EAS integration developers which would receive the event hooks calls from Ginesys POS.

Event Hooks in Ginesys POS

For the needs of business, both Ginesys POS and the third party EAS integration DLL will need to update their respective software as necessary. If Ginesys POS calls the hardware driver interfaces directly, then the proprietary response from the devices would have to be understood and processed by Ginesys. This approach would create a situation where if a software update in the EAS system changes the response in any manner, the integration would break as Ginesys would fail to understand the new response. Subsequently, Ginesys would also have to release a new build that would understand the new response and all Ginesys POS locations using this integration would need to update to the latest version, often causing an operational load.

The event hook assembly solves this problem as it works as an interpreter between Ginesys and the EAS system. Event Hooks are outbound calls from Ginesys POS, sent when specified events occur in the POS system. The EAS system developer would need to develop a .NET assembly and configure the same in Ginesys as a plugin. The plugin once distributed to the stores, would automatically be called by Ginesys POS and necessary information would be supplied as input parameters with the call. The assembly can then interact with the EAS hardware interfaces/drivers and take necessary actions to achieve the integration. Subsequently, once the processing is done, the assembly will give a response back to Ginesys POS via output parameters.

To let the custom EAS systems know about the "purchased" items Ginesys provides an event hook named POSBILL_AFTERSAVE_1 under the event category named ProcessPOSBill. This event allows any custom .NET DLL code to receive notifications about the invoiced items from Ginesys POS. The partner will then use the Plugin Manager feature of Ginesys to configure the .NET Assembly (DLL) as a POS Plugin and distribute it to the respective stores.

Deployment and maintenance

Deployment of the plugin assemblies are handled by a software update utility at Ginesys POS named Auto Update. In most cases, deploying the assemblies would require some dependencies and configuration files in the same location. The Auto Update utility makes sure that the software updates (application and database) are safely deployed by ensuring logout of all users and shutting down all running windows services and jobs. Hence, the deployment of the plugin assemblies and its dependencies are also done by Auto Update.

Steps to deploy and configure the event hook plugins

To ensure that Ginesys POS runs custom codes by approved plugin partners only, the partner would need to register with Ginesys. Once a partner is registered with Ginesys, a shortcode is assigned to the partner and the partner record is created in Ginesys. Only approved partners can run their plugin code in Ginesys POS. The following are the steps to be executed in sequence for successful integration and execution of the plugin.

1. Once a plugin partner is approved by Ginesys team the shortcode and information of the partner is created in Ginesys.
2. The plugin partner runs a PoC with Ginesys team and verifies the POS version that their code is compatible with. Let 's assume the POS version be 2.9.0.
3. The plugin partner decides a version for the plugin. Let's assume that version be 1.0
4. The plugin assembly and all its dependency files is handed over to Ginesys Tech team for uploading to the POS software update server along with the version information.
5. Ginesys team (Tech Team) uploads the plugin assemblies, dependency files and configuration file to Ginesys POS update server.
6. The plugin assembly name, class name, method name and configuration file name (if any) is configured in Ginesys POS Plugin Manager.
7. The stores are selected in the plugin manager configuration where the plugin should run.
8. Run sync at HO and POS.

Configuring the event hook plugin in Ginesys Plugin Manager

1. Open Ginesys Web in Head Office
2. Go to Retail > Setup > Configure > Plugin Manager
3. Click on 'Add'
4. Provide the following information in the window that appears - 
   1. Plugin Short Code: This is a short code to identify the plugin. During deployment a folder will be created under Ginesys POS application folder with this name and the plugin files will be deployed in this location. prefer not to use a space in the short code, rather use underscores if required, e.g. "TagID_GateNotifier" (example)
   2. Plugin Vendor: Once a plugin partner is registered with Ginesys, the vendor registration is released in a particular version of Ginesys POS and the vendor name is available in the drop down. Select "TagId" as the vendor here.
   3. Plugin Type: The plugin type is a collection of event hook handlers which are compiled and packaged into a single assembly. Many vendors likes to handle multiple hooks by supplying a single assembly. The Plugin Type for EAS gate integration would be "ProcessPOSBill". This type allows to handle all events related to processing a POS Bill ()except payment). E.g. there is a separate event type called "ProcessPOSPay" which caters to all events related to POS payment processing.
   4. Plugin Assembly Name: The project/assembly name of the plugin. This is typically the name of the dll without the extension. E.g. if the file name is TagID.dll then this value should be TagID.
   5. Target Config File Name: This is the name of the config file that the assembly would expect to be in the same folder as the plugin. Any configuration file required by the assembly should added to the plugin repository via the second tab (Config Files) in the window.

   6. Hook Map: Select the correct hook that the plugin will be handling.

      1. Hook Type: The event and the data structure that the plugin would like to handle. For EAS integration it should be POSBILL_AFTERSAVE_1.
      2. Plugin Class Name: The class implemented by the developer for handling the hook call specifically for POSBILL_AFTERSAVE_1. Any class name can be chosen by the plugin partner.
      3. Plugin Method Name: The method name of the class which would be called by Ginesys for processing the hook. This method should be public. Any method name can be chosen by the plugin partner.

      4. More information about hooks - 

         Hooks are areas in code when the plugin will be called by Ginesys POS. A hook indicates the timing of call and also the data structure that would be passed to the plugin. One event type can have more than one hooks. For example, a "ProcessPOSBill" event type can have hooks like "POSBILL_AFTERSAVE_1" and "POSBILL_BEFORESAVE_1". The "_1" indicates that the hook may have different sets of data structures for different needs. For example, POSBILL_AFTERSAVE_1 has only the basic bill and item data in a denormalized format. There can be a POSBILL_AFTERSAVE_2 in a future release where the data structure can be a hierarchical one with more bill header and item information. These structures are decided by Ginesys and are released along with software updates.

   7. Site Allocation: Select the POS stores where the plugin should work. IMPORTANT: For the first time, allocate to only one site and test the same there to prevent any disruption in operations.
5. Run sync at HO and POS.

Developer Notes

Once the plugin is configured via Ginesys POS Plugin Manager and the files are uploaded to Ginesys POS update server, the POS Auto Update utility is enabled to download and install the plugin in the Ginesys POS application folder.

The plugins are installed in the following location in Ginesys POS application folder. All plugin assemblies, dependencies and configuration files will be found in this folder
\Ginesys POS\Plugins\<PluginVendorShortCode>\<PluginShortCode> 

The plugin will have WRITE permission in the above folder. So if there is a need to write log file, the plugin can use the plugin folder to create log files. However, to avoid clutter it is recommended that the plugins write logs under a \log folder where the plugin is deployed. If a plugin generates log files, it is also the responsibility of the plugin to clean up the logs 

The plugin application version information is packaged and deployed to the plugin folder as a .ver file named as "plugin.ver". This file indicates the version of the plugin that is deployed.

After the bill is successfully saved and also printing is completed in Ginesys POS, the event hook is dynamically determined based on the following three parameters. These parameters would be set via the POS Plugin Manager utility given in Ginesys ERP Retail Management module. Once the plugin manager is configured and the plugin assemblies and are uploaded to Ginesys POS update server. 

• Plugin Assembly Name : The name of the assembly name to be called
• Plugin Class Name : The class in the assembly that will be created dynamically by Ginesys POS
• Plugin Method Name : The method in the respective class that will be dynamically called by Ginesys POS

The event hook assembly has to be developed using C# .NET on .NET Framework 4.6.2.

Description of input parameters received from Ginesys

JSON data structure understanding

Description of output parameters supplied to Ginesys by the plugin

Store cashier operation

For the EAS gate integration to work, the cashier need not do anything special. He would perform his standard operations in POS and the system would automatically invoke the EAS event hook workflow as soon as the bill is successfully printed. During this stage, the control remains with the plugin assembly. Once the call is successfully handled by the plugin, the control comes back to Ginesys POS and operations are resumed normally.

Known Issues

None at this point.