Jak korzystać z funkcjonalności Zdarzeń Biznesowych?

Aby skonfigurować Zdarzenia biznesowe w aplikacji, wykonaj poniższe kroki:

1. Przejdź do menu Ustawienia / Ustawienia programu / Ustawienia zdarzeń biznesowych

2. W sekcji Konfiguracja wysyłki:

• Włącz rejestrację zdarzeń biznesowych
• Włącz usługę wysyłania zdarzeń, jeśli zdarzenia mają być przekazywane do zewnętrznych systemów
• Podaj adres wysyłki, na którym serwis zewnętrzny będzie nasłuchiwać i uruchamiać integrację - np. URL webhooka w platformie n8n
• Ustaw częstotliwość i zakres czasu wysyłki zdarzenia

3. W zakładce Zdarzenia rejestrowane zaznacz, które typy zdarzeń mają być monitorowane np. rozliczenie czy usunięcie faktury, utworzenie towaru, dodanie kontrahenta.

4. W zakładce Zdarzenia wysyłane zaznacz, które typy zdarzeń mają być wysyłane do zewnętrznych systemów (przeważnie będzie to ustawienie tożsame ze zdarzeniami rejestrowanymi).

5. W zakładce Czyszczenie zdarzeń skonfiguruj (opcjonalnie), jak często starsze zdarzenia mają być automatycznie usuwane.

6. Na koniec kliknij OK, aby zapisać ustawienia.

Usługa ELISOFT Business Server to dodatkowa usługa instalowana wraz z aplikacją, która odgrywa kluczową rolę w obsłudze zdarzeń biznesowych. Jeśli usługa nie jest uruchomiona, funkcjonalność wysyłki zdarzeń nie będzie działać.

Gdzie znaleźć ELISOFT Business Server?

• Ikona w pasku zadań Windows

  Na głównym pasku zadań (obok godziny) znajduje się strzałka, która rozwija menu ukrytych ikon. Po rozwinięciu menu powinna być widoczna ikona naszej usługi Business Server:

• Wyszukiwanie ręczne

  Jeśli ikona nie jest widoczna, można wyszukać usługę ręcznie, wpisując w pasku wyszukiwania systemu Windows: Business Server.

Jak uruchomić usługę ELISOFT Business Server?

Po otwarciu usługi, w głównym oknie widoczny jest przycisk umożliwiający jej uruchomienie:

Ważne: Jeśli aplikacja działa na kilku komputerach, usługa Business Server powinna być uruchomiona tylko na jednym stanowisku, aby uniknąć problemów z funkcjonalnością zdarzeń.

Po włączeniu rejestracji zdarzeń, możesz monitorować je w zakładce Zdarzenia (główne menu aplikacji).

Dla każdego zdarzenia wyświetlane są podstawowe informacje w kolumnach, takie jak:

• Rodzaj zdarzenia
• Powiązany dokument
• Numer dokumentu (jeśli jest to zdarzenie dotyczące utworzenia faktury czy zlecenia)
• Data utworzenia
• Dane podmiotu powiązane z zarejestrowanym zdarzeniem

Statusy zdarzeń

Kolumna status wskazuje, czy zdarzenie zostało przetworzone i wysłane:

• Niebieski status “Nieogłoszone” - zdarzenie jest zapisane w systemie, ale nie zostało wysłane do innych serwisów / narzędzi typu low-code
• Zielony “Ogłoszono”- zdarzenie zostało pomyślnie wysłane i przetworzone w zewnętrznych systemach.
• Czerwony “Błąd” - wysyłka zdarzenia nie powiodła się. Szczegóły błędu znajdują się w zawartości zdarzenia- zakładka Informacje.

Podgląd zawartości zdarzeń

Aby wyświetlić szczegóły konkretnego zdarzenia, kliknij przycisk Pokaż zawartość zdarzenia.

Otworzy się nowe okno z dwoma zakładkami:

1. Ładunek zdarzenia

Ładunek zdarzenia to zestaw danych w formacie JSON, który opisuje szczegóły zarejestrowanego zdarzenia biznesowego. Dane te są kluczowe dla integracji z systemami zewnętrznymi, gdyż pozwalają precyzyjnie określić:

• Typ zdarzenia (np. utworzenie faktury, dodanie kontrahenta)
• Dane dokumentu (np. numer faktury, dane kontrahenta, sprzedawcy)
• Czas zdarzenia
• Identyfikator zdarzenia (GUID), który umożliwia jego jednoznaczną identyfikację.

Przykładowy ładunek zdarzenia, do utworzonej faktury w programie, wygląda następująco:

{
                  "Guid": "2969caed-6bab-4c29-a964-cede478254c3",
                  "DataZdarzenia": "2024-11-29T11:25:22.8854217+01:00",
                  "Zdarzenie": "Utworzono",
                  "PowiazanyDokument": "FakturaSprzedazy",
                  "KontekstZgloszenia": {
                    "OriginID": "7089B8D7BA3440B5AB6B698B50A08F64",
                    "Aplikacja": "ELISOFT Firma Premium 2025 19.12.0.0 ",
                    "Uzytkownik": "Administrator",
                    "Sesja": 3,
                    "BazaDanych": "bdFaktury11",
                    "IdPodmiotu": 1
                  },
                  "Dokument": {
                    "NrFaktury": "FV 2024/0001",
                    "DataWystawienia": "2024-11-29T00:00:00",
                    "DataSprzedazy": "2024-11-29T00:00:00",
                    "MiejsceWystawienia": "",
                    "DataTerminZaplaty": "2024-11-29T00:00:00",
                    "Sprzedawca": {
                      "Nazwa": "RENO",
                      "Adres": {
                        "Miasto": "",
                        "Ulica": "",
                        "KodPocztowy": "",
                        "Panstwo": ""
                      },
                      "Nip": "1234567890",
                      "NipKraj": ""
                    },
                    "Nabywca": {
                      "Nazwa": "Jan Kowalski",
                      "Adres": {
                        "Miasto": "",
                        "Ulica": "",
                        "KodPocztowy": "",
                        "Panstwo": ""
                      },
                      "Nip": "1123447890",
                      "NipKraj": ""
                    },
                    "PozycjeFaktury": [
                      {
                        "Id": 1,
                        "Nazwa": "Narożnik Vanessa",
                        "Kod": "",
                        "KodGTU": "",
                        "KodPKWiU": "",
                        "KodCN": "",
                        "Jednostka": "",
                        "Ilosc": 1.0,
                        "Rabat": 0.0,
                        "StawkaVat": 23.0,
                        "StawkaVatRodzaj": "Procentowa",
                        "CenaNetto": 1000.0,
                        "CenaBrutto": 1230.0,
                        "WartoscNetto": 1000.0,
                        "WartoscBrutto": 1230.0
                      }
                    ],
                    "PlatnoscInformacje": {
                      "FormaPlatnosci": "Gotówka",
                      "SplitPayment": false,
                      "Waluta": "PLN",
                      "RachunekNazwaBanku": "",
                      "RachunekNumerKonta": ""
                    },
                    "KwotaInformacje": {
                      "WartoscZaplacona": 0.0,
                      "PozostaloDoZaplaty": 1230.0,
                      "WartoscNetto": 1000.0,
                      "WartoscBrutto": 1230.0
                    },
                    "FaktureWystawil": "",
                    "FaktureOdebral": "",
                    "Oznaczenie": "",
                    "Informacje": "",
                    "JPKKodyProcedur": "",
                    "IdFaktury": 1,
                    "GuidFaktury": "d2394c05-2c48-4b04-b945-f2c3c1776396"
                  }
                }

2. Informacje

Zakładka ta prezentuje szczegóły dotyczące statusu wysyłki zdarzenia:

• Jeśli wysyłka przebiegła pomyślnie- w tej zakładce będą widoczne szczegóły wysyłki.
• Jeśli wysyłka zakończyła się błędem- znajdziesz tu komunikat z szczegółami problemu.
• Jeśli zdarzenie nie zostało wysłane (status "Nieogłoszone")- zakładka pozostaje pusta.

Workflow (przepływ pracy) to proces opisujący sposób przetwarzania zdarzeń i wynikających z nich działań w sposób automatyczny. Dzięki integracji zdarzeń biznesowych z narzędziami typu low-code, takimi jak n8n, możliwe jest tworzenie zaawansowanych automatyzacji, które ułatwiają codzienną pracę.

Poniżej przygotowaliśmy dokładny przykład utworzenia workflowu wykorzystującego zdarzenia z naszej aplikacji.

Czym są diagramy Workflow?

Diagramy workflow to graficzne przedstawienie procesów biznesowych lub operacyjnych, które pokazują przepływ danych między różnymi etapami działania. Tego rodzaju diagramy składają się z prostych elementów (klocków), które mogą reprezentować czynności, decyzje, punkty wejścia/wyjścia czy warunki.

Każdy "klocek" w diagramie odpowiada za wykonanie konkretnego zadania np. filtrowanie danych, wysyłanie e-maili czy logowanie zdarzeń. Klocki można łączyć w dowolny sposób aby zautomatyzować procesy w oparciu o dane wyjściowe, takie jak zdarzenia biznesowe. Takie rozwiązanie pozwala na:

• Proste i intuicyjne budowanie procesów bez konieczności pisania kodu.
• Automatyzację powtarzalnych zadań.
• Integrację z innymi narzędziami i aplikacjami.

Instrukcja: Tworzenie workflow w n8n na podstawie Zdarzeń Biznesowych.

Poniżej przedstawiamy przykład workflow, który wykorzystuje zdarzenie utworzenia faktury z naszej aplikacji. Automatyzacja ta generuje powiadomienie e-mail, jeśli wartość faktury przekracza określoną kwotę.

Krok 1 Utworzenie nowego workflow

1. Zaloguj się do aplikacji n8n i utwórz nowy workflow.

2. Możesz nadać nazwę swojemu workflow np. Powiadomienie o wysokiej fakturze:

Krok 2 Dodanie węzła Webhook

1. Z listy elementów po prawej stronie, przeciągnij na diagram węzeł Webhook.

2. W ustawieniach węzła:

• ustaw metodę na POST (1).
• Skopiuj wygenerowany adres URL i wklej do ustawień zdarzeń w aplikacji – posłuży on jako punkt wejścia, do którego aplikacja wyśle dane zdarzenia. (3).

Uwaga: Webhook generuje dwa różne adresy URL. (2) W trakcie konfiguracji i testowania należy używać Test URL. Po zakończeniu testów i uruchomieniu workflowa w środowisku produkcyjnym użyj Production URL.

3. Testowanie węzła Webhook:

• Ważne: Zanim przejdziesz do dodawania kolejnych węzłów, upewnij się, że węzeł Webhook przeszedł test.
• Kliknij Listen for test event w ustawieniach węzła Webhook i wywołaj zdarzenie testowe w aplikacji, aby sprawdzić, czy odbiera on poprawnie dane.
• Jeśli test zakończy się sukcesem, węzeł zostanie podświetlony na zielono, co oznacza, że działa poprawnie.
• Dopiero po tym możesz przejść do kolejnych węzłów i połączyć je w pełne workflow.

W n8n każdy węzeł (np. Webhook, Filter, Gmail) musi zostać przetestowany osobno!

Krok 3: Dodanie filtra (IF)

1. Dodaj na diagram węzeł Filter, który pozwoli przetwarzać dane z ładunku zdarzenia.

2. Połącz węzeł Webhook z węzłem Filter, przeciągając strzałkę między nimi.

3. W ustawieniach filtra zdefiniuj ładunek:

• Przed wprowadzeniem wartości pola, przestaw opcję na Expression (1).
• do miejsca fx przeciągnij z listy pól wartości faktury, pole odpowiadające za wartość brutto faktury : {{ $json.body.Dokument.PozycjeFaktury[0].WartoscBrutto }} (2)
• Operator z sekcji Number: is greater than (3)
• Po prawej stronie: 10000 (lub inna kwota graniczna). (4)

• Możesz zmienić nazwę węzła w poniżej wskazanym miejscu:

• Oczywiście nie zapomnij o przetestowaniu nowo dodanego węzła za pomocą opcji Test step!

• Wróć do okna głównego za pomocą poniższej opcji:

Krok 4 - Dodanie węzła Gmail

1. Przeciągnij na diagram węzeł Gmail Send a message

2. Ustaw odpowiednie wartości:

• Operacja Send (1)
• Adres odbiorcy powiadomienia (2)
• Temat wiadomości mailowej (3)
• Przestaw opcję na Expression (4) i stwórz treść powiadomienia- można wykorzystać do niej listę pól wartości zdarzeń z aplikacji (5) np. Faktura {{ $json.body.Dokument.NrFaktury }} o wartości {{ $json.body.Dokument.PozycjeFaktury[0].WartoscBrutto }} {{ $json.body.Dokument.PlatnoscInformacje.Waluta }} została wystawiona i przekroczyła ustaloną kwotę 10000 PLN.

• Połącz się ze swoim kontem Google:

Krok 5- Testowanie workflow

1. Przed wykonaniem testów, upewnij się, że w aplikacji masz włączoną wysyłkę zdarzeń (1), wklejony adres URL Webhooka (2) oraz wybrane odpowiednie zdarzenie (w tym przykładzie jest to Tworzenie faktury) (3).

Ważne: Po zakończeniu testów pamiętaj, aby zamienić Test URL na Production URL w ustawieniach zdarzeń aplikacji.

2. Wywołaj w aplikacji zdarzenie testowe (np. utworzenie faktury z kwotą powyżej progu).

3. Wróć do n8n i kliknij przycisk Test Workflow, aby sprawdzić, czy wszystkie kroki działają poprawnie:

• Webhook odbiera dane.
• Warunek „IF” prawidłowo sprawdza wartość kwoty.
• Jeśli kwota jest powyżej progu, wysyłany jest e-mail.

Jeśli test przebiegnie prawidłowo, cały workflow będzie podświetlony na zielono, tak jak powyżej. Treść wysłanej wiadomości wygląda następująco:

W poniższym przykładzie przedstawimy workflow w aplikacji n8n, który po rozliczeniu faktury w systemie przesyła powiadomienie mailowe do klienta. Pamiętaj, że ta funkcjonalność będzie działać tylko wtedy, gdy w kartotece kontrahenta będzie uzupełniony jego adres e-mail. Przed przystąpieniem do konfiguracji workflow upewnij się, że adres e-mail klienta jest poprawnie wprowadzony w systemie, w poniżej wskazanym miejscu. Workflow wykorzystuje te dane do wysłania powiadomienia mailowego.

Krok 1 Utworzenie nowego workflow

1. Zaloguj się do aplikacji n8n i utwórz nowy workflow.

2. Możesz nadać nazwę swojemu workflow np. Powiadomienie o rozliczeniu faktury (patrz przykład 1, krok 1).

Krok 2 Dodanie węzła Webhook

1. Dodanie węzła

• Z listy elementów po prawej stronie przeciągnij na diagram węzeł Webhook.

2. Konfiguracja węzła:

• W ustawieniach węzła ustaw metodę na POST
• Skopiuj wygenerowany adres URL i wklej go do ustawień zdarzeń w aplikacji – posłuży on jako punkt wejścia, do którego aplikacja wyśle dane zdarzenia.

Uwaga: Webhook generuje dwa różne adresy URL. (2) W trakcie konfiguracji i testowania należy używać Test URL. Po zakończeniu testów i uruchomieniu workflowa w środowisku produkcyjnym użyj Production URL.

3. Testowanie węzła Webhook:

• Kliknij Listen for test event w ustawieniach Webhooka i wywołaj zdarzenie testowe w aplikacji (np. rozliczenie faktury).
• Jeśli test przebiegnie pomyślnie, węzeł zostanie podświetlony na zielono. Dopiero wtedy przejdź do dodawania kolejnych węzłów.

Krok 3 - Dodanie filtra

1. Dodanie węzła Filter

• Dodaj na diagram węzeł Filter, który pozwoli przetwarzać dane otrzymane z Webhooka.
• Połącz węzeł Webhook z węzłem Filter, przeciągając strzałkę między nimi.

2. Konfiguracja filtra

• Przestaw opcję na Expression w polu fx.
• Z listy pól wartości zdarzeń, przeciągnij pole odpowiadające za wysłane zdarzenie: {{ $json.body.Zdarzenie }}.
• Ustaw warunek: is equal to i wpisz wartość: Rozliczono. Dzięki temu filtr przepuści tylko te zdarzenia, które dotyczą rozliczenia faktury.

3. Testowanie węzła Filter

• Wykonaj test nowo dodanego węzła za pomocą opcji Test step.
• Jeśli test przebiegnie pomyślnie, węzeł zostanie podświetlony na zielono.

Krok 4 - dodanie węzła Gmail

1. Dodanie węzła Gmail:

• Przeciągnij na diagram węzeł Gmail Send a message

2. Konfiguracja węzła Gmail:

• Operation (1): Send
• To: Przeciągnij pole odpowiadające za adres mailowy wprowadzony w kartotece kontrahenta (2): {{ $json.body.Dokument.Kontrahent.Email1 }}
• Subject (3) - np. "Twoja faktura została rozliczona"
• Treść wiadomości (4) - np. Szanowni Państwo, faktura {{ $json.body.Dokument.NrFaktury }} została pomyślnie rozliczona.

• Połącz węzeł Gmail ze swoim kontem Google, aby umożliwić wysyłkę wiadomości.

Krok 5 - Testowanie Workflow

1. Testowanie każdego węzła osobno:

• Webhook: Sprawdź, czy odbiera dane poprawnie.
• Filter: Upewnij się, że rozpoznaje zdarzenia o statusie "Rozliczono".
• Gmail: Potwierdź, że e-mail jest wysyłany na właściwy adres.

2. Testowanie całego workflow:

• Kliknij przycisk Test Workflow i wywołaj zdarzenie w aplikacji (np. rozlicz fakturę).
• Wszystkie węzły, które działają poprawnie, powinny zostać podświetlone na zielono.

• Przykład wiadomości wysłanej do klienta: