Integracja z wagami GSW

Wstęp

Integracja z oprogramowniem GSW firmy GS Software.
Integracja polega na udostępnieniu WebAPI.PRO do programu GSW aby mógł komunikować się z Symfonią.

Opis funkcjonalny

System GSW ma możliwość przez WebAPI.PRO:

• pobrać kartoteki kontrahentów, towarów oraz magazynów
• pobrać niezrealizowane zamówienia kontrahentów
• wysłać informację o przeprowadzonym ważeniu, która spowoduje wystawienie w Symfonii odpowiedniego dokumentu magazynowego

WebAPI.PRO po instalacji i skonfigurowaniu jest bezobsługowe.WebAPI.PRO będzie codziennie restartowane w celu wyeliminowania zawieszeń/problemów w działaniu (dokładny opis w konfiguracji dodatku: link).

Drugą częścią aplikacji jest tzw. "Podgląd ważeń", czyli okno na którym możemy w czasie rzeczywistym sprawdzać jakie ważenia wpadają nam z systemu GSW.
Dodatkowo, w przypadku gdy WebAPI.PRO z jakiegoś powodu nie wystawiło dokumentu magazynowego to takie ważenie będzie podświetlone kolorem na podglądzie ważeń i będzie możliwość ręcznej próby wczytania do Symfonii.
Powodem nieudanego wystawienia dokumentu może być np. brak tego towaru na stanie w Symfonii.

Okno "Podgląd ważeń" możemy uruchomić w dwóch trybach, tzw. 'luźnym' i 'związanym'.

• Tryb 'luźny' pozwala na uruchomienie okna podglądu nie blokując przy tym Symfonii.
  Czyli mając uruchomione okno w tym trybie dalej możemy korzystać z Symfonii, a to okno przesunąć sobie np. na drugi monitor by mieć łatwy podgląd.
  UWAGA: okno uruchomione w tym trybie nie ma możliwości ręcznego wczytania ważenia do Symfonii
• Tryb 'związany' pozwala nam na ręczne wczytanie ważeń do Symfonii.
  Niestety okno w tym trybie blokuje dostęp do Symfonii.
• Założenie jest takie, że okno w trybie luźnym będzie uruchomione cały czas gdzieś na boku, a jeśli użytkownik będzie chciał wystawić ręcznie jakieś ważenie to musi uruchomić okno w trybie związanym.
  Po wystawieniu dokumentu użytkownik zamyka okno w trybie związanym i zostawia to w trybie luźnym.

Instalacja funkcjonalności

1. Instalacja HPP

Krok ten wykonujemy na każdym stanowisku z Symfonią, które ma mieć możliwość uruchamiania "Podglądu ważeń".

Intrukcja instalacji cz.1
Intrukcja instalacji cz.2

2. Instalacja WebAPI.PRO

Krok ten wykonujemy TYLKO na serwerze.

• Wypakować plik 'WebAPI.zip' w dowolnym miejscu na dysku.
  Proponujemy na dysku C utworzyć katalog 'WebAPI.PRO' i wkleić do niego zawartość pliku 'WebAPI.zip'
• Wejść do rozpakowanego katalogu
• Uruchomić skrypt "rejestracjaWebAPI.cmd" z uprawnieniami administratora
• Powinno nam się pokazać okienko jak poniżej.
  Klikamy dowolny klawisz i na tym kończy się instalacja WebAPI.PRO

3. Wgranie raportów do Symfonia Handel

Krok ten wykonujemy TYLKO raz z dowolnego stanowiska z Symfonią.

Instrukcja

Raporty do wgrania:

• hpp_runtime.sc - NET Runtime (BLOT)
• hpp_extr05.sc - ExtRun::WystawMg (BLOT)
• hpp_eitg_gsw01.sc - Podgląd ważeń (luźny) (BLOT)
• hpp_eitg_gsw02.sc - Podgląd ważeń (związany) (BLOT)
• hpp_eitg_gsw03.sc - Integracja GSW - Uruchomienie WebAPI (BLOT)

Konfiguracja dodatku

Konfiguracja całego rozwiązania jest jednorazowa.
Każdy z kroków opisanych poniżej wystarczy wykonać tylko raz. Wyjątkiem jest ścieżka do programu ustawiana w punkcie 3. Konfiguracja skryptu do automatycznego uruchamiania WebAPI.PRO.
Po każdej aktualizacji programu trzeba zaktualizować ścieżkę do Symfonii.

1. Konfiguracja WebAPI.PRO

• Zalogować się do Symfonii jako 'admin'
• Wejść w kartotekę raportów
• Otworzyć raport dostępny pod ścieżką Symfonia.Pro -> HPP -> "Integracja GSW - Uruchomienie WebAPI (BLOT)"
• Uzupełnić wszystkie pola

2. Konfiguracja HPP

• Zalogować się do Symfonii jako 'admin'
• Uruchomić jakikolwiek raport uruchomieniowy, np "Podgląd ważeń (luźny) (BLOT)" (prawy przycisk myszy na kartotece dokumentów magazynowych)
• Przy pierwszym uruchomieniu uzupełnić konfigurację bazy
• Przejść do zakładki "Ustawienia"
• Uzupełnić wszystkie parametry
  • Parametry są zapisywane automatycznie w bazie. Po uzupełnieniu parametru wystarczy kliknąć w dowolne miejsce na oknie.
  • Parametry WebAPI
    • "Czy wymagana autoryzacja"
      • Zaznaczenie tej opcji spowoduje, że wykonanie jakiegokolwiek zapytania do API będzie wymagało podania poniższego loginu i hasła (autoryzacja BASIC)
    • Login
      • Login jakie trzeba będzie używać przy próbie komunikacji z WebAPI jeśli jest włączona autoryzacja
    • Hasło
      • Hasło jakie trzeba będzie używać przy próbie komunikacji z WebAPI jeśli jest włączona autoryzacja
  • Parametry Symfonia
    • Typ dokumentu wydania
      • Typ dokumentu który zostanie użyty podczas wystawiania wydania z magazynu.
        Wpisany typ musi istnieć w ustawieniach w Symfonii
    • Seria dokumentu wydania
      • Seria dokumentu która zostanie użyta podczas wystawiania wydania z magazynu.
        Wpisana seria musi istnieć w ramach danego typu w ustawieniach w Symfonii.
    • Typ dokumentu przyjęcia
      • Typ dokumentu który zostanie użyty podczas wystawiania przyjęcia do magazynu.
        Wpisany typ musi istnieć w ustawieniach w Symfonii
    • Seria dokumentu przyjęcia
      • Seria dokumentu która zostanie użyta podczas wystawiania przyjęcia do magazynu.
        Wpisana seria musi istnieć w ramach danego typu w ustawieniach w Symfonii.

3. Konfiguracja skryptu do automatycznego uruchamiania WebAPI.PRO

W ramach rozwiązania otrzymają państwo plik o nazwie "GSW_restartWebAPI.bat".
Służy on automatycznemu uruchamianiu WebAPI.PRO.

Plik należy zapisać w konkretnym miejscu na dysku, tak żeby nie został później przypadkowo skasowany.
Np utworzyć katalog C:\SKRYPTY i wkleić go tam.

Poniżej opisany jest sposób jego konfiguracji.

• Otworzyć plik "GSW_restartWebAPI.bat" za pomocą notatnika.
• Uzupełnić w nim wszystkie pola zaznaczone poniżej na czerwono
  • Zamienić każde "<...>" na odpowiednią wartość Czyli np. "<adres_serwera>" zamienić na "SERWER\SQL2019" a "<login Symfoniowy>" zamienić na "admin"
• Zaktualizować ścieżkę do katalogu z Symfonią (zaznaczone na niebiesko)

4. Ustawienie skryptu na automatyczne uruchamianie WebAPI.PRO w harmonogramie zadań

• Ogólne: Utworzyć zadanie o dowolnej nazwie, skonfigurowane dla najbardziej aktualnej wersji Windowsa
  • Zadanie ma się uruchamiać tylko gdy zalogowany jest konkretny użytkownik Windowsowy
  • W celu poprawnego działania WebAPI wybrany wyżej użytkownik będzie musiał być zawsze zalogowany
  • Czyli np. po restarcie serwera trzeba zalogować się na wskazanego wyżej użytkownika
• Wyzwalacze: Zadanie to ma być wyzwalane codziennie o jakiejś godzinie, najlepiej nocnej kiedy nikt nie będzie korzystał z API
• Akcje: Zadanie to ma uruchamiać skrypt "GSW_restartWebAPI.bat"
  • Chodzi o skrypt opisany w punkcie 3. dodatku.
  • Akcja ma wskazywać na ten skrypt.
  • Bezwzględnie należy uzupełnić pole "Rozpocznij w", należy tam uzupełnić katalog w którym jest skrypt (bez nazwy samego skryptu).
• Zalecamy włączyć historię wszystkich zadań w harmonogramie zadań

Działające WebAPI na serwerze będzie wyglądało tak jak na poniższym zrzucie

• Adres URL - adres pod który działa WebAPI.PRO wpisany w konfiguracji
• Port - port pod który działa WebAPI.PRO wpisany w konfiguracji
• Status HTTP - informacja czy działa serwer HTTP, dzięki któremu możemy odbierać zapytania do naszego WebAPI.PRO
  • W razie problemów z działaniem można spróbować zatrzymać i uruchomić ponownie serwer HTTP.
    Ewentualnie zrestartować całą usługę WebAPI.PRO poprzez ręczne uruchomienie skryptu "GSW_restartWebAPI.bat" opisanego wcześniej
• Status Handel - informacja czy jest komunikacja z programem Symfonia Handel
• Status baza danych - informacja czy jest komunikacja z bazą danych na serwerze SQL
• Pozostałymi rzeczami na oknie takimi jak "Token" nie musimy się przejmować.

Uruchomienie

WebAPI.PRO

Uruchomienie WebAPI.PRO jest automatyczne, dokładniej zostało to opisane w punkcie 4. konfiguracji dodatku

Okno 'Podgląd ważeń'

Uruchomienie okna "Podgląd ważeń" odbywa się przez wejście do kartoteki dokumentów magazynowych w Symfonii, kliknięcie PPM w dowolne miejsce na liście dokumentów i wybranie jednej z dwóch opcji, "GSW - Podgląd ważeń (luźny) (BLOT)" lub "GSW - Podgląd ważeń (związany) (BLOT)".

Zakładka "Panel"

• Wczytaj do Symfonii
  • Guzik służy do wczytania ważenia jako dokument do Symfonii.
    Działa tylko w trybie związanym.
• Odśwież
  • Ręcznie odświeża listę dokumentów wg wskazanego zakresu dat.
• Autoodświeżanie co x sekund
  • Zaznaczenie tej opcji spowoduje, że lista ważeń zostanie odświeżona co okres sekund wpisany w dalszej części opcji.
    Za każdym razem ładowane są ważenia z wybranego zakresu dat.
• Zakres dat
  • Daty 'od' - 'do' czyli przedział ważeń które mamy wyświetlać na oknie.
    Data 'od' zawsze bierze wszystkie ważenia od godziny 00:00:00 danego dnia.
    Data 'do' zawsze bierze wszystkie ważenia do godziny 23:59:59 danego dnia.
• Szablon filtrów i kolumn
  • opis działania szablonu filtrów i kolumn

Opis kolumn:

• ID ważenia
  • Identyfikator ważenia z systemu GSW
• Numer ważenia
  • Numer ważenia z systemu GSW
• Numer rej. pojazdu
  • Numer rejestracyjny pojazdu
• Czy dostawa
  • Pole wskazujące czy dane ważenie jest wydaniem (niezaznaczone) czy dostawą (zaznaczone).
    Pole ustalane jest wg zależności "masa 1. ważenia" > "masa 2. ważenia".
• Masa 1. ważenia
  • Masa z pierwszego ważenia pojazdu
• Masa 2. ważenia
  • Masa z drugiego ważenia pojazdu
• Moment 1. ważenia
  • Dokładny moment (data, godzina) pierwszego ważenia
• Moment 2. ważenia
  • Dokładny moment (data, godzina) drugiego ważenia
• Masa netto
  • Różnica między masą z pierwszego i drugiego ważenia (przekazywana przez GSW)
• Magazyn
  • Kod magazynu w Symfonii
• Kod kontrahenta
• Nazwa kontrahenta
  • Dane kontrahenta w Symfonii
• Kod towaru
• Nazwa towaru
  • Dane towaru w Symfonii
• Numer dokumentu
  • Numer wystawionego dokumentu w Symfonii
    Jeśli puste to oznacza że wystawianie dokumentu nie udało się podczas przyjmowania ważenia przez webAPI.PRO. W takim wypadku wiersz całego ważenia będzie podświetlony.
    Ważeniom bez wystawionego dokumentu w Symfonii można wystawiać ręcznie dokumenty z poziomu okna.

Zakładka "Ustawienia"

• Dostępna jest tylko dla użytkownika 'admin'.
• Służy do skonfigurowania działania WebAPI.PRO oraz ustalenia jakiego typu mają być wystawiane dokumenty magazynowe.

Ręczny import ważeń do Symfonii

W przypadku gdy system GSW wyśle przez API informacje o ważeniu ale z jakiegoś powodu nie uda się wystawić dokumentu magazynowego w Symfonii to takie ważenie będzie podświetlone na liście kolorem (jak na przykładowym obrazku).
W takiej sytuacji można spróbować wczytać dane ważenie do Symfonii z tego okna.
WAŻNE! Ręczny import ważeń możliwy jest tylko w trybie związanym.
Aby to zrobić zaznaczamy wiersz danego ważenia i klikamy Wczytaj do Symfonii.

Jeśli wszystkie się uda to dostaniemy komunikat "Wystawianie dokumentu zakończone pomyślnie!".

Może jednak się zdarzyć że wystawianie dokumentu nie powiedzie się.
W takim wypadku powinien pokazać się komunikat "Błąd podczas wystawiania dokuemntu magazynowego!..."
Poniżej przykład takiego komunikatu wskazujący na to, że w magazynie nie ma wystarczającej ilości towaru do wystawienia danego towaru