Installation of Comarch POS in cooperation with Comarch ERP XL in a distributed system

Contents

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.

Cooperation between system versions and component versions

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.

Example

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.

Note

If several versions of Comarch ERP XL and Comarch POS are installed on a single machine, please note that Comarch ERP XL system must have up-to-date registries for the relevant version in order for the synchronization service to work correctly. Additionally, in the PATH section of environment variables, in the first place there has to be an entry referring to an appropriate version of Comarch ERP XL the user wants to work with. It is then necessary to restart the computer in order for the changes to be read correctly and run the registries of the selected Comarch ERP XL version.

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 are 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

Note

For a profile other than the main profile in Comarch ERP Auto Update, the log path can be found in the POS2.exe.config file in Comarch POS directory.

POS application log path in POS2.exe.config file

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.

Hint

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

Note

Comarch ERP Auto Update 2020.0 requires .NET Framework 4.7.2 in order to run properly.

Example

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

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/20225/ 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/20225/ 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.

Note

Note that the POS Agent code ≠ the POS workstation code, but there is no objection to the names being the same.

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

Comarch POS Agent Broker component on parent agent

2. 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)

Note

After turning on additional Windows features and installing POS Agent Broker, it may be necessary to restart the workstation.

3. 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.

Comarch POS Agent Broker connection test in Comarch ERP XL

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)

Note

Note that port 80 is the default port – when configuring, verify that the port is not already in use.

4. The default browser will show the link to the Comarch POS Agent Broker service on the address bar.

Comarch POS Agent Broker service address on the browser 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].

Broker connection test in Comarch ERP XL system

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.

Checking connection with authorization link

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.

Bindings in Internet Information Services (IIS) Manager

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.

Note

It is recommended that Comarch POS Agent be on the same machine as the Comarch POS product, so a parent-child structure is used.

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.

Comarch POS Agent configuration tool – Language selection window

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:

Note

Verify the automatically entered port and IP address.

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.

Note

The Comarch POS Agent service requires a fixed IP of the computer on which it is installed.

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/

Note

The port for the synchronization service, for example 51426, should be forwarded on the router. This includes the Comarch POS Agent service port – 8098, by default.

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.

Note

The Comarch POS Agent service should run continuously, i.e. the machine it runs on should be on all the time to ensure correct operation in POS warehouses.

6. 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.”

7. 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/20225/ index.php/knowledge-base/stock-reconciliation/

Note

The stock reconciliation process should be run when no one is working on POS workstations and performed one at a time on each POS workstation. After the initial reconciliation is performed, the functionality should be used on an ad hoc basis when stock discrepancies are detected.

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.

How can we help you?

Installation of Comarch POS in cooperation with Comarch ERP XL in a distributed system

Glossary

Log information

General information

Upgrading Comarch ERP Auto Update to version 2020.0 or higher