Instrukcja instalacji Comarch POS we współpracy z Comarch ERP XL w systemie rozproszonym

Instrukcja prezentuje instalacje Comarch POS we współpracy z Comarch ERP XL w strukturze rozproszonej. Oznacza to, że Comarch ERP XL i Comarch POS nie znajdują się na jednej maszynie, a na przykład do utrzymania połączeń usług wykorzystuje się router.

Słownik pojęć

• Comarch ERP Auto Update – narzędzie niezbędne do instalacji produktu Comarch Retail i jego komponentów, przy instalacji tworzony jest profil główny, aplikacja umożliwia tworzenie dodatkowych profili o niezależnej konfiguracji
• Comarch POS Agent – działa jako samodzielna usługa z własną bazą danych, dostarcza aktualne informacje o stanach magazynowych na każdym stanowisku, podczas wystawiania dokumentów
• Comarch POS Agent Broker – zapewnia komunikacje pomiędzy usługą POS Agent a systemem ERP, komponent ten agreguje kolejkę wiadomości, przekazując aktualizację stanów magazynowych do właściwego POS Agenta. Należy pamiętać że komponent POS Agent Broker może być dodany tylko na jednym profilu w programie Comarch ERP Auto Update.

• Usługa synchronizacji Data service – dzięki usłudze możliwa jest synchronizacja system ERP <-> POS. Nazwę usługi i jej port definiuje się w systemie ERP, brak usługi uniemożliwia pracę z aplikacją Comarch POS.
• Kafka message queue – rozproszona platforma przesyłania strumieniowego typu „open source”, która umożliwia tworzenie aplikacji i protokołów danych przesyłania strumieniowego w czasie rzeczywistym. Kafka pełni funkcję usługi brokera komunikatów. Działa po zainstalowaniu komponentu Comarch POS Agent Broker.
• Zookeeper Service – usługa, działająca po zainstalowaniu komponentu Comarch POS Agent Broker. Służy do utrzymywania wspólnego stanu dla wszystkich instancji Kafki, zarządzania konfiguracją, monitorowania.

1. System ERP i usługa synchronizacji wysyła żądanie do Comarch POS Agent Brokera
2. Żądanie zapisuje się w kolejce zadań
3. Żądanie jest odczytywane
4. Comarch POS Agent Broker wysyła żądanie do POS Agenta
5. Następuje procesowanie w POS Agencie
6. POS Agent wysyła odpowiedź do Brokera
7. Odpowiedź zapisuje się w kolejce odpowiedzi
8. Odpowiedź jest odczytywana przez Broker
9. Comarch POS Agent Broker wysyła odpowiedź do systemu ERP i usługi synchronizacji

Informacje o logach

Szczegółowe informacje o zdarzeniach występujących na stanowisku POS dotyczące samej aplikacji Comarch POS, któregoś komponentu lub usługi, rejestrowane są w plikach txt (logach). Domyślne ścieżki zapisywania logów:

• dla stanowiska POS to: C:\Retail\POS2\mainprofile\Logs

Uwaga

W przypadku innego profilu niż główny w Auto Update, ścieżka do logowania znajduje się w pliku POS2.exe.config w katalogu Comarch POS.

• dla usługi POS Agent: C:\Retail\POS Agent\mainprofile\Logs i C:\Retail\POSAgentConfig\Log
• dla usługi synchronizacji Data Service: C:\Program Files (x86)\Comarch ERP XL\XLDataService\POS_LOG\Comarch.XL.POS.Data.Service
• dla kolejki wiadomości: C:\Kafka\kafka\logs (All + Own)
• dla POS Agent Brokera: C:\Program Files (x86)\Comarch Retail\Comarch POS Agent Broker\Logs
• dla aplikacji Comarch ERP Auto Update: C:\Program Files (x86)\Comarch ERP Auto Update\Logs

Informacje ogólne

Od wersji Comarch ERP XL 2021.0 oraz Comarch POS 2021.0 do współpracy między systemami konieczne jest wykorzystywanie nowych komponentów: Comarch POS Agent oraz Comarch POS Agent Broker.

Komponenty te należy zainstalować za pomocą Comarch ERP Auto Update wraz z instalacją produktu Comarch POS.

Aktualizacja Comarch ERP Auto Update do wersji 2020.0 lub wyższej

1.Aby móc w pełni korzystać ze wszystkich możliwości sieci agentów należy zaraz po podniesieniu agenta nadrzędnego zaktualizować agentów podrzędnych. Jest to wymagane, ponieważ nie ma możliwości wykonywania akcji zdalnych pomiędzy wersjami 2019.0 i 2020.0.

2. W celu dokonania procesu aktualizacji należy uruchomić lub zrestartować UI agenta nadrzędnego (w zależności od tego, czy był on aktualnie uruchomiony w momencie udostepnienia paczki z nową wersją Comarch ERP Auto Update)

3. W zależności od tego, czy parametr na oknie konfiguracji AU „Aktualizuj automatycznie przy starcie programu” jest zaznaczony proces aktualizacji rozpocznie się sam lub będzie wymagane potwierdzenie go przez użytkownika

4. Następnie powinno pojawić się okno z progressbarem:

5. W czasie aktualizacji agent nadrzędny automatycznie przełączy się do serwera update.comarch.com z portu 8466 na port 9466. Po ukończeniu aktualizacji najlepiej sprawdzić czy usługa RabbitMQ jest uruchomiona. Można także w oknie przeglądarki wejść na adres http://localhost:15672 i zalogować się jako admin (Login: admin, Hasło: admin). Jeżeli nie będzie z tym żadnych problemów oznacza to, że usługa rabbita została poprawnie skonfigurowana.

6.Wszyscy agenci podrzędni będą widnieć na liście, jako „Offline”, aż do momentu podniesienia ich do wersji 2020.0. Kropka zmieni się na „Online” gdy uzyskają oni połączenie do kolejki rabbita. Agentów podrzędnych można podnieść albo wszystkich na raz przy pomocy przycisku „Aktualizuj wszystkich” albo po jednym, po rozwinięciu danego agenta i wybraniu „Aktualizuj agenta” . Wtedy rozpocznie się jego proces aktualizacji.

7. W czasie aktualizacji podrzędnego, jeżeli wymagane porty są otwarte w kolumnie „Status” będą wyświetlane kroki jego aktualizacji.

8. Po zakończeniu aktualizacji agent podrzędny stanie się „Online” a w kolumnie „Wersja” pojawi się informacja o zainstalowanych na nim komponentach. Zielony „check” w kolumnie „Nazwa” oznacza, że dany agent podrzędny znajduje się w aktualnej wersji.

Po aktualizacji AutoUpdate do wersji 2020.0 będzie on domyślnie używał komunikacji WCFowej.

9.Do zmiany formy komunikacji agent nadrzędny <-> agenci podrzędni na RESTa należy na oknie konfiguracji w sekcji „Konfiguracja komunikacji” zaznaczyć „Używaj komunikacji RESTowej”. Po zapisaniu konfiguracji nastąpi restart UI I usługi AU i forma komunikacji pomiędzy agentem nadrzędnym i podrzędnymi ulegnie zmianie. Zmiana formy komunikacji zalecana jest dopiero po podniesieniu sieci agentów podrzędnych, ponieważ komunikacja AU 2019.0 <-> AU 2020.0 może odbyć się tylko przy pomocy WCFa.

10. Wymagana konfiguracja portów dla AU 2020.0, jeżeli zarówno agent nadrzędny, jak i agenci podrzędni zostali podniesieni do nowej wersji:

Na agencie nadrzędnym:

1. Połączenia przychodzące:

• 5672
• 8009
• 11365

2.Połączenia wychodzące:

• 9466

Na lokalnym agencie nadrzędnym:

1. Połączenia przychodzące:

• 8009

2. Połączenia wychodzące:

• 5672
• 8009
• 11365

Na agencie podrzędnym:

1. Połączenia wychodzące:

• 5672
• 8009
• 11365

Instalacja i konfiguracja po stronie Comarch ERP XL

Pełna instrukcja konfiguracji stanowiska POS znajduje się pod linkiem:

https://pomoc.comarch.pl/xl/index.php/dokumentacja/xl137-instalacja-i-konfiguracja-pos/ 

1. Na komputerze na którym znajduje się Comarch ERP XL należy zainstalować Auto Update w wersji nadrzędnej nazwa profilu i kod musi być taki sam jak dla agenta podrzędnego. Instrukcja instalacji agenta nadrzędnego znajduje się pod linkiem:

https://pomoc.comarch.pl/pos/20240/documentation/instalacja-comarch-erp-auto-update/

2. Na komputerze na którym będzie znajdował się POS należy zainstalować agenta podrzędnego, nazwa profilu i kod musi być taki sam jak dla agenta nadrzędnego, informacje na temat zrządzania strukturą agentów podrzędnych, znajdują się w dokumentacji:

https://pomoc.comarch.pl/autoupdate/documentation/struktura-agentow-i-agent-podrzedny/

3. Przy definiowaniu stanowiska POS w systemie Comarch ERP XL należy określić typ licencji:

Od rodzaju licencji określonej na poziomie danego stanowiska zależy dostępność funkcji dla poszczególnych modułów aplikacji:

• Back office (funkcjonalność magazynowa)
• Front office (funkcjonalność sprzedażowa)

4. Na zakładce POS Agent w konfiguracji Oddziału Comarch POS należy zdefiniować kod POS Agenta.

Komponent POS Agent Broker

Przed instalacją komponentu POS Agent Broker należy włączyć dodatkowe funkcje systemu Windows – Internetowe usługi informacyjne (IIS).  W tym celu należy przejść do Panelu sterowania → Programy i funkcje → Włącz lub wyłącz funkcje systemu Windows → Internetowe usługi informacyjne (IIS) i włączyć:

• Narzędzia zarządzania siecią Web
• Usługi WWW

1.Na komputerze gdzie zainstalowany jest agent nadrzędny (serwer centralny na którym znajduje się system ERP) należy dodać produkt Comarch Retail i komponent Comarch POS Agent Broker.

2. Po dodaniu komponentu Comarch POS Agent Broker w aplikacji Comarch ERP Auto Update należy zainstalować odpowiednią wersję Brokera. (Tabela 1 Współpraca pomiędzy systemami a komponentami)

3. Po instalacji komponentu, należy wprowadzić adres kolejki wiadomości POS Agent Brokera. W tym celu należy przejść do System -> Konfiguracja -> POS w systemie Comarch ERP XL.

W celu sprawdzenia pod jakim adresem została udostępniona usługa Comarch POS Agent Broker należy:

• Otworzyć Menedżer internetowych usług informacyjnych (IIS)
• W widoku Połączenia rozwinąć Witryny -> Default Web Site
• Wskazać pozycję zawierającą w nazwie ’POSAgentBroker’
• W widoku Akcje wybrać Przeglądaj *:80 (http)

4. Po wybraniu [Przeglądaj] w domyślnej przeglądarce w pasku adresu znajdzie się poprawny link do usługi POS Agent Broker.

Jeżeli POS Agent Broker zainstalowany został na profilu o nazwie: 2021_2 to adres prezentowany w przeglądarce będzie wyglądał następująco: localhost/POSAgentBroker_2021_2

Localhost = IP komputera na którym zainstalowano Comarch POS Agent Brokera, przy problemach z połączeniem z Brokerem i POS Agentem, warto zmienić tą nazwę na IP komputera.

Przy problemach z połączeniem i synchronizacją można również w oknie Menedżera internetowych usług IIS dla puli aplikacji POS Agent Broker wybrać Odtwarzanie.

5. W Usługach Windows należy zweryfikować czy uruchomione są usługi:

• Kafka Message Queue
• Zookeeper Service

6. Jeżeli obie usługi są uruchomione, należy w Comarch ERP XL przejść do zakładki System -> Konfiguracja -> POS -> [test połączenia].

W przypadku gdy weryfikacja połączenia zakończy się niepowodzeniem, należy sprawdzić w przeglądarce poprawność linku:

http://localhost/POSAgentBroker_2021_2/health?Auth=MjhlMWUxMmEtNDc5OS00ZTRkLWIwMWMtNzk2ZDA2MmZmYjlj

W pogrubionej części należy wprowadzić adres dostępny z poziomu System -> Konfiguracja -> POS w Comarch ERP XL.

Jeżeli po wykonaniu wszystkich powyższych czynności test połączenia w Comarch ERP XL kończy się niepowodzeniem. Należy w Menedżerze internetowych usług (IIS) wybierając Witryny -> Default Web Side -> prawy przycisk myszy -> Powiązania usunąć powiązanie https port 443, jeżeli pojawia się na liście.

Komponent Comarch POS

Po poprawnej instalacji i konfiguracji komponentu Comarch POS Agent Broker należy dodać komponent Comarch POS dla produktu Comarch Retail.

Okno konfiguracji otwierane jest poprzez zaznaczenie komponentu oraz wybranie z głównego menu przycisku [Konfiguracja]. W oknie należy wprowadzić dane dotyczące połączenia bazy danych stanowiska POS.

Następnie na zakładce Więcej -> Struktura agentów należy dodać agenta podrzędnego oraz wybrać jakie komponenty będą instalowane dla danego profilu.

W oknie należy uzupełnić:

• Kod agenta – kod agenta podrzędnego, który należy wprowadzić w Auto Update podczas konfiguracji
• Lokalizację – opcjonalnie
• Tagi – oznaczenia wykorzystywane podczas wyszukiwania agenta podrzędnego na liście
• Profile – wraz ze wskazaniem produktów, które mają być zainstalowane na agencie podrzędnym
• Lokalny nadrzędny – czy dany agent pełni rolę lokalizacji

Po dodaniu agenta podrzędnego będzie on widoczny w strukturze agentów. Z poziomu tego okna istnieje możliwość:

• Dodania nowego agenta podrzędnego
• Dodania nowej lokalizacji
• Wykonanie aktualizacji wszystkich agentów do najnowszej wersji
• Wymuszenie synchronizacji z agentami podrzędnymi
• Wykonanie akcji zdalnej na agencie podrzędnym – pobranie, instalacja, możliwość przywrócenia wersji i dezinstalacji dla wskazanego produktu. Istnieje możliwość zaznaczenia na liście kilku agentów i wykonania dla nich akcji zdalnej.

• Pokazania/ukrycia szczegółów
• Zmiany profilu

Komponent POS Agent

Po poprawnej instalacji i konfiguracji komponentu Comarch POS Agent Broker należy dodać komponent Comarch POS Agent dla produktu Comarch Retail.

Po zainstalowaniu na agencie podrzędnym komponentu Comarch POS Agent należy przejść do katalogu gdzie znajduje się zainstalowany i pobrany POS Agent (domyślna ścieżka C:\Program Files (x86)\Comarch Retail\Comarch Retail POS Agent).

1.W folderze Comarch Retail -> Comarch Retail POS Agent dostępna jest aplikacja exe.

2.Przy pierwszym uruchomieniu pojawi się okno z wyborem języka.

3.Podczas pierwszego uruchomienia, pojawi się błąd dotyczący odinstalowanej usługi.

4.Wyświetlony komunikat należy potwierdzić przyciskiem [OK], w kolejnym kroku wyświetlone zostanie okno konfiguratora:

W aplikacji przed wybraniem przycisku [Instaluj] należy podać:

• Adres IP usługi POS Agent – pole uzupełniane automatycznie adresem IP komputera na którym zainstalowano usługę POS Agent. W przypadku gdy IP jest zmienne, należy ustawić dla usługi POS Agent stałe przekierowanie na IP, zamiast nazwy localhost przy zmiennym IP można wprowadzić 127.0.0.1.

• Port usługi POS Agent – domyślnym portem jest 8098, należy pamiętać, że usługa POS Agent i usługa synchronizacji XL – POS nie może działać na tym samym porcie, wprowadzony może być dowolny wolny port
• Adres serwera OMS – domyślnym adresem jest http://localhost:8099/DataService/, adres ten składa się z:
  • localhost – IP komputera na którym, znajduje się XL i usługa synchronizacji
  • 8099 – domyślny port dla usługi synchronizacji, należy podać port, jaki został wprowadzony dla usługi synchronizacji w Comarch ERP XL na zakładce Oddziały -> Konfiguracja automatu synchronizacji. Na poniższym rysunku uzupełniony jest port: 51426, więc adres przy IP = 10.138.37.7 w aplikacji POS Agent Konfigurator wyglądałby tak: http://10.138.37.7:51426/DataService/

• Kod POS Agenta – kod POS Agent wprowadzony w systemie ERP w oknie Konfiguracji oddziału -> Comarch POS

• GUID – wartość nadawana automatycznie, po poprawnym zarejestrowaniu usługi

5.Po uzupełnieniu powyższych danych w Konfiguratorze POS Agent należy wybrać przycisk:

• [Instaluj]
• [Odśwież]
• [Uruchom] – powinien pojawić się komunikat dotyczący uruchomienia usługi
• [Sprawdź] (przy wpisanym kodzie POS Agenta) – po wybraniu przycisku pojawi się okno z informacją o stanie połączenia

• [Odśwież]
• [Zarejestruj] – automatycznie uzupełnione zostanie pole GUID w konfiguratorze, a także pola HOST, PORT i GUID w systemie Comarch ERP XL. Dodatkowo pojawi się okno z informacją o poprawnym zarejestrowaniu Agenta.

6.Po włączeniu usług i wykonaniu prawidłowej konfiguracji, dodatkową i najlepszą weryfikacją poprawności działania usług jest wystawienie w systemie Comarch ERP XL dokumentu magazynowego (rozchód wewnętrzny, wydanie zewnętrzne) z magazynu POSowego – tutaj przy dodawaniu elementu na dokument, jeżeli połączenie będzie niepoprawne otrzymamy o tym komunikat: „Nie można wykonać akcji ze względu na niedostępność usługi POS Agent. Operacje na magazynach POS wymagają połączenia z usługą.”

7.Po wykonaniu wszystkich kroków na stanowisku POS zaleca się włączenie Uzgadniania stanów – funkcjonalność synchronizuje stany magazynowe pomiędzy sklepem a systemem centralnym ERP. Dodatkowe informacje na temat uzgadniania znajdują się pod linkiem:

https://pomoc.comarch.pl/pos/20240/documentation/uzgadnianie-stanow-magazynowych/

O czym należy pamiętać:

1. Przede wszystkim należy pamiętać aby porty były dostępne dla dwóch komputerów, w tym celu należy zrobić przekierowanie na routerze danych portów usług synchronizacji.
2. Zalecanym sposobem weryfikacji jest korzystanie z wiersza poleceń (cmd), gdzie za pomocą poleceń:

• netstat -aon
• telnet

można zweryfikować dostępność danych portów.