The following article discusses the installation of Comarch POS in cooperation with Comarch ERP XL in a distributed structure. It means that Comarch POS and Comarch ERP XL are not located on a single machine and, for instance, a router is used to maintain service connections.
Glossary
- Comarch ERP Auto Update – it is a tool necessary for the installation of Comarch Retail product and its components. During the installation of the tool, the main profile is created. The application enables the user to create additional profiles with independent configuration.
- Comarch POS Agent – it works as an independent service with its own database and provides up-to-date information on stock levels on each workstation while issuing documents.
- Comarch POS Agent Broker – this component provides communication between the Comarch POS Agent service and the ERP system. It aggregates the message queue, transferring stock level updates to an appropriate POS Agent service. Please note that the Comarch POS Agent Broker component can only be added on a single profile in Comarch ERP Auto Update.
In Comarch ERP Auto Update, several profiles have been configured; for instance:
Profile I:
- Comarch ERP XL version 2021.0
- Comarch POS version 2021.0
- Comarch POS Agent version 2021.0
- Comarch POS Agent Broker – none
Profile II:
- Comarch ERP XL version 2021.1
- Comarch POS version 2021.6
- Comarch POS Agent version 2021.6
- Comarch POS Agent Broker version 2021.6
In Comarch ERP XL 2021.0 configuration, the address of Comarch POS Agent Broker should be entered based on Profile II.
- Data Service (synchronization service) – the service makes it possible to synchronize data between the ERP system and Comarch POS. The service’s name and port is defined in the ERP system. If the service is missing, it is not possible to work with Comarch POS application.
- Kafka message queue – it is an open-source distributed streaming platform allowing the creation of applications and data streaming protocols in real time. Kafka is used as a message broker service. It can be used after the installation of the Comarch POS Agent Broker component.
- Zookeeper Service – this service also can be used after the installation of the Comarch POS Agent Broker component. It is used to maintain a common status for all Kafka instances, manage configuration, and perform monitoring tasks.
1. The ERP system and the synchronization service send a request to Comarch POS Agent Broker
2. The request is saved in the task queue
3. The request is read
4. Comarch POS Agent Broker sends the request to Comarch POS Agent
5. Comarch POS Agent processes the request
6. Comarch POS Agent sends a response to Comarch POS Agent Broker
7. The response is saved in the response queue
8. The response is read by Comarch POS Agent Broker
9. Comarch POS Agent Broker sends the response to the ERP system and the synchronization service
Log information
Detailed information about events occurring on a POS workstation, concerning Comarch POS application itself or any component or service, is recorded in txt files (logs). Default log saving paths:
- for a POS workstation: C:\Retail\POS2\mainprofile\Logs
- for the Comarch POS Agent service: C:\Retail\POS Agent\mainprofile\Logs and C:\Retail\POSAgentConfig\Logs
- for Data Service: C:\Program Files (x86)\Comarch ERP XL\XLDataService\POS_LOG\Comarch.XL.POS.Data.Service
- for the message queue: C:\Kafka\kafka\logs (All + Own)
- for Comarch POS Agent Broker: C:\Program Files (x86)\Comarch Retail\Comarch POS Agent Broker\Logs
- for Comarch ERP Auto Update application: C:\Program Files (x86)\Comarch ERP Auto Update\Logs
General information
Beginning with Comarch ERP XL version 2021.0 and Comarch POS version 2021.0, new components are required for cooperation between the systems: Comarch POS Agent and Comarch POS Agent Broker.
The components need to be installed using Comarch ERP Auto Update along with the installation of Comarch POS product.
Upgrading Comarch ERP Auto Update to version 2020.0 or higher
1. To be able to take full advantage of all the capabilities of the agent network, it is necessary to upgrade the child agents right after the parent agent is upgraded. This is obligatory because it is not possible to perform remote actions between versions 2019.0 and 2020.0.
For the AU upgrade process to run smoothly, make sure that all the required ports are correct:
On the parent agent:
1. Inbound connections:
- 5672
- 8009
- 11365
2. Outbound connections:
- 11366 – default port, but other ports may also be required depending on which port is configured on the child agent to connect to the parent agent
- 8466 – port to connect to update.comarch.com for AU 2019.0
- 9466 – port to connect to update.comarch.com for AU 2020.0
On the child agent:
1. Inbound connections:
- 11366 – default port, but other ports may also be required depending on which port is configured in the child agent to connect to the parent agent,
2. Outbound connections:
- 5672
- 8009
- 11365
2. In order to upgrade Comarch ERP Auto Update, run or restart the parent agent’s UI (depending on whether it was running when the package with the new Comarch ERP Auto Update version was made available).
3. Depending on the selection of the parameter Upgrade automatically at program startup in the AU configuration window, the upgrade process will begin automatically or will require the user’s confirmation.
4. The installation progress bar should then be displayed:
5. During the upgrade, the parent agent will switch automatically to update.comarch.com server from port 8466 to port 9466. After the upgrade is completed it is advisable to check whether the RabbitMQ service is running. In the browser window, the user can also type the address http://localhost:15672 and log on as the administrator (login: admin, password: admin). If no problems occur, it means that the rabbit service has been configured properly.
6. All the child agents will be displayed on the agent list as Offline until they are upgraded to version 2020.0. The dot symbol will change to Online when they are connected to the rabbit queue. Child agents can be upgraded either all the once using the button [Upgrade All] or one at a time by expanding a given agent and selecting the button [Upgrade Agent]. Its upgrade process will then begin.
7. If the required ports are open in the Status column during upgrade of the child agent, the subsequent steps of its upgrade process will be displayed.
8. After the upgrade process is finished, the child agent will change to Online and the information about the components installed on that agent will be displayed in the Version column. The green icon with the tick symbol in the Name column means that a given child agent is available in the current version.
After Comarch ERP Auto Update is upgraded to version 2020.0, it will use WCF communication by default.
9. To change the communication between the parent agent and child agents to REST, in the configuration window select the parameter Use REST communication available under Communication Configuration. After saving the configuration, the UI of the AU service will restart and the communication mode between the parent agent and the child agents will change. It is recommended to change the communication mode not until the child agent network is upgraded because AU 2019.0 <-> AU2020.0 can communicate only through WCF.
10. Required port configuration for AU 2020.0 if both the parent agent and the child agents are upgraded to the new version:
On the parent agent:
1. Inbound connections:
- 5672
- 8009
- 11365
2. Outbound connections:
- 9466
On the local parent agent:
1. Inbound connections:
- 8009
2. Outbound connections:
- 5672
- 8009
- 11365
On the child agent:
1. Outbound connections:
- 5672
- 8009
- 11365
Solving the rabbit service-related problems
The rabbit service-related problems, if they occur, can be solved as follows:
1. run exe as administrator and execute the instructions below:
2. cd C:\Program Files\RabbitMQ Server\rabbitmq_server-3.7.5\sbin
3. rabbitmq-service.bat remove
4. rabbitmq-service.bat install
5. rabbitmq-service.bat start
6. rabbitmq-plugins enable rabbitmq_management
7. rabbitmqctl stop (after this command, it is necessary to wait a moment; sometimes it is also necessary to stop the RabbitMQ service manually)
8. rabbitmq-server -detached
9. rabbitmqctl start_app (after this command, it is necessary to wait a moment; sometimes it is also necessary to start the RabbitMQ service manually)
10. rabbitmqctl add_user admin admin
11. rabbitmqctl set_user_tags admin administrator
12. rabbitmqctl set_permissions -p / admin “.*” “.*” “.*”
When executing the above commands, the user may encounter an authentication problem and a problem with the erlang cookie file. In order to solve them, copy the following: C:\Windows\System32\config\systemprofile\.erlang.cookie
to
C:\Users\UserName\.erlang.cookie
Installation and configuration in Comarch ERP XL
Full instructions on how to set up a POS workstation can be found at the link (Polish version only):
https://pomoc.comarch.pl/xl/pl/index.php/dokumentacja/xl137-instalacja-i-konfiguracja-pos/
1. On the computer where Comarch ERP XL is located, it is necessary to install a parent agent in Comarch ERP Auto Update; its profile name and code must be the same as the child agent’s. Instructions for installing the parent agent can be found at the link:
https://help.comarch.com/pos/20221/index.php/knowledge-base/installation-of-comarch-erp-auto-update/
2. On the computer where the POS workstation will be located, it is necessary to install a child agent; its profile name and code must be the same as the parent agent’s. Information on managing the child agent structure may be found in the following article:
https://help.comarch.com/pos/20221/index.php/knowledge-base/managing-the-agent-structure/
3. When defining a POS workstation in Comarch ERP XL system, it is necessary to define a license type:
The availability of features for each application module depends on the type of license specified for a given workstation:
- Back Office (warehouse-related functionality)
- Front Office (sales-related functionality)
4. On the POS Agent tab of the Comarch POS subsidiary configuration window, it is necessary to define a POS Agent code.
Comarch POS Agent Broker component
Before the installation of POS Agent Broker, it is necessary to turn on additional Windows features – Internet Information Services (IIS). To do so, open Control Panel → Programs → Turn Windows features on or off → Internet Information Services and select:
- Web Management Tools
- WWW Services
1. On the computer where the parent agent (i.e. the central server where the ERP system is located) has been installed, add the Comarch Retail product and the Comarch POS Agent Broker
1. After adding the Comarch POS Agent Broker component in Comarch ERP Auto Update application, the appropriate broker version should be installed. (see table: Cooperation between system versions and component versions)
2. After installing the component, enter the address of Comarch POS Agent Broker’s message queue. To do so, navigate to System → Configuration → POS in Comarch ERP XL system.
3. In order to verify the address of the Comarch POS Agent Broker service, it is necessary to:
- Open Internet Information Services (IIS) Manager
- In the Connections view, expand Sites → Default Web Site
- Select the item with ‘POSAgentBroker’ in its name
- In the Actions view, select Browse *:80 (http)
4. The default browser will show the link to the Comarch POS Agent Broker service on the address bar.
If Comarch POS Agent Broker is installed on a profile named 2021_2, then the address presented in the browser will look as follows: localhost/POSAgentBroker_2021_2
Localhost = IP of the computer on which Comarch POS Agent Broker is installed. When having problems connecting to the broker and the Comarch POS Agent service, it is a good idea to change this name to the computer IP.
In the case of connection and synchronization problems, the user can also select the option Recycle for the Comarch POS Agent Broker application pool in Internet Information Services (IIS) Manager.
5. In Windows Services, verify that the following services are running:
- Kafka Message Queue
- Zookeeper Service
6. If both the services are running, in Comarch ERP XL system, go to System → Configuration → POS → [Configuration test].
If the configuration test fails, check if the following link works correctly in the browser:
http://localhost/POSAgentBroker_20211/health?Auth=MjhlMWUxMmEtNDc5OS00ZTRkLWIwMWMtNzk2ZDA2MmZmYjlj
In the bold part, enter the address displayed in System → Configuration → POS in Comarch ERP XL.
If the configuration test still fails in Comarch ERP XL after performing all the above steps, go to Internet Information Services (IIS) Manager, select Sites, right click on Default Web Site → Edit Bindings and remove the https port 443 binding if it appears on the list.
Comarch POS component
After the proper installation and configuration of Comarch POS Agent Broker, add the Comarch POS component for the Comarch Retail product.
The configuration window is opened by selecting a component and choosing the [Configuration] button from the main menu. In the window, enter the database connection information for the POS workstation.
Next, expand the tab More, select [Agent Structure], add a child agent, and select which components are to be installed on a given profile.
In the window, it is necessary to enter the following information:
- Agent Code – the child agent’s code to be entered in Comarch ERP Auto Update during configuration
- Location (optionally)
- Tags – used when searching for a child agent on the list
- Profiles and products to be installed for a child agent
- Local parent agent – the parameter specifies whether a given agent performs the function of a location
Once a child agent is added, it is displayed in the agent structure. Here, it is possible to:
- Add a new child agent
- Add a new location
- Upgrade all agents to the latest version
- Enforce synchronization with child agents
- Perform a remote action on a child agent – download, install, roll back, or uninstall a selected product. It is possible to select several agents on the list and perform a given remote action for all of them.
- Display/hide details
- Change profile
Comarch POS Agent component
After the proper installation and configuration of Comarch POS Agent Broker, add the Comarch POS Agent component for the Comarch Retail product.
After installing the Comarch POS Agent component on the child agent, navigate to the folder where Comarch POS Agent is located (the default path is C:\Program Files (x86)\Comarch Retail\Comarch Retail POS Agent).
1. The Comarch Retail\Comarch Retail POS Agent folder contains the POSAgentConfigurator.exe application.
2. When the application is opened for the first time, a language selection window is displayed.
3. Also, when the application is opened for the first time, an error message is displayed, informing about the uninstalled service.
4. The error message needs to be confirmed with the [OK] button. Next, the configuration tool’s window is displayed:
Before selecting the [Install] button, it is necessary to specify the following information:
- POS Agent Service IP Address – the field is automatically filled in with the IP address of a computer where the Comarch POS Agent service has been installed. In the case where the IP address is dynamic, it is necessary to set a permanent IP redirection for the Comarch POS Agent service; instead of the localhost name, the address 0.0.1 may be entered.
- POS Agent Service Port – the default port is 8098. Please note that the Comarch POS Agent service and the XL-POS synchronization service cannot run on the same port. It is possible to enter any available port.
- OMS Server Address – the default address is http://localhost:8099/DataService/; it is composed of:
- localhost – the IP of a computer where Comarch ERP XL and the synchronization service are located
- 8099 – the default port for the synchronization service. It is necessary to enter a port entered for the synchronization service in Comarch ERP XL on the tab [Subsidiaries] → [Automatic synchronisation logon configuration]. The port entered in the screenshot below is 51426, so with the IP address = 10.138.37.7, the address in the Comarch POS Agent configuration tool would be as follows: http://10.138.37.7:51426/DataService/
- POS Agent Code – the POS Agent code entered for Comarch POS in the ERP system’s subsidiary configuration
- POS Agent GUID – this value is assigned automatically after the correct registration of the service
5. After filling in all the abovementioned data in the Comarch POS Agent configuration tool, select the button:
- [Install]
- [Refresh]
- [Start] – a notification should be displayed, concerning the start of the service
- [Verify] (if the POS Agent code is entered) – it displays a window with information on the connection status
- [Refresh]
- [Register] – it automatically fills in the POS Agent GUID field in the configuration tool, as well as HOST, PORT, and GUID fields in Comarch ERP XL system. Additionally, a window with information on the correct registration of the agent will be displayed.
1. After enabling the services and performing proper configuration, the additional and best way to verify the correctness of the services is to issue a warehouse document in Comarch ERP XL (an internal release, SO release) from the POS warehouse; if connection is not established, the user will receive the following notification: “Cannot perform the action, as the POS Agent service is unavailable. Operations on POS warehouses require connection with the service.”
2. Once all the steps have been completed, it is recommended to run the stock reconciliation process on the POS Workstation – the feature synchronizes stock levels between the shop and the central ERP system. Additional information on stock reconciliation may be found in the following article:
https://help.comarch.com/pos/20221/index.php/knowledge-base/stock-reconciliation/
Please note:
1. First of all, the user needs to make sure that ports are available for two computers; for this purpose, the synchronization service ports should be forwarded on the router.
2. The recommended verification method is the use of the following commands in the command line (cmd):
- netstat -aon
- telnet
The commands make it possible to verify the availability of given ports.