InnerWeb
Przejdź do treści

KD OSDP a webhook zdarzeń: uwagi wdrożeniowe dla administratora

Po wymianie czytników Wiegand na OSDP administrator KD obawia się, że integracje z systemami zewnętrznymi przestaną działać. Zasada jest prosta: InnerWeb odbiera zdarzenia z systemu KD, a nie z czytnika, więc zmiana łącza czytnik–kontroler nie zmienia kontraktu webhooka. Poniżej lista rzeczy do sprawdzenia przy przełączeniu.

443
port połączenia wychodzącego integracji
Źródło: karta wewnętrzna integracji
12 godz.
ważność tokenu JWT
Źródło: karta wewnętrzna integracji
2 100
odbić dziennie w podobnej integracji
Źródło: karta wewnętrzna wdrożenia

Gdzie kończy się OSDP, a zaczyna webhook

OSDP dotyczy łącza między czytnikiem a kontrolerem. Webhook dotyczy drogi od systemu KD do InnerWeb. To dwie niezależne warstwy: po wymianie czytników kontroler nadal ma odbicie karty, a oprogramowanie KD nadal może wysłać komunikat HTTPS.

InnerWeb działa jako niezależny system uzupełniający istniejące systemy klienta (KD, RCP, HR, ERP), więc zmiana protokołu czytnik–kontroler nie wymaga zmian po stronie InnerWeb, o ile system KD nadal wysyła zdarzenia. Warunek jest jeden, ale to na nim kończą się przeglądy po migracji.

Co zawiera komunikat i co może się zmienić po wymianie

Komunikat odbicia zawiera czas odbicia z kontrolera, identyfikator czytnika, osobę, numer karty w postaci kod_obiektu-numer oraz opcjonalnie kierunek i identyfikator zdarzenia dla idempotencji. Po wymianie czytnika zmienić się może identyfikator czytnika, jeśli nowy czytnik dostał inny adres lub nazwę w systemie KD.

Dlatego przed przełączeniem uzgodnij, czy identyfikatory czytników pozostają te same, czy mapa czytnik–lokalizacja po stronie InnerWeb wymaga aktualizacji. Bez tego odbicia nadal docierają, ale przypisują się do złego miejsca.

Kierunek wejścia i wyjścia

Jeśli nowe czytniki OSDP umożliwiają osobne wejście i wyjście, system KD może zacząć wysyłać pole kierunku. Gdy kierunku nie ma, parowanie wejścia z wyjściem odbywa się w oprogramowaniu InnerWeb: okno do 13 godzin, duplikat odbicia poniżej 180 s. Warto przetestować oba warianty przed zmianą ustawień.

Parametry integracji KD z InnerWeb

Parametry integracji KD z InnerWebWykres słupkowy poziomy: 2100 odbić dziennie, okno parowania 780 minut, token 12 godzin, próg duplikatu 180 sekund.05001000150020002500wartośćOdbicia dziennieOdbicia dziennie: 2100 wartość2100Okno parowania (min)Okno parowania (min): 780 wartość780Token JWT (godz.)Token JWT (godz.): 12 wartość12Próg duplikatu (s)Próg duplikatu (s): 180 wartość180
Źródło: Karta wewnętrzna integracji KD; okno 13 godzin przeliczone na 780 minut

Sieć i uwierzytelnienie bez zmian

W integracji z systemem KD połączenie inicjuje strona zakładu jako ruch wychodzący na porcie 443, więc nie trzeba otwierać portów przychodzących w sieci zakładu. Wymiana czytników nie zmienia tej zasady i nie wymaga zmian reguł zapory.

Uwierzytelnienie integracji odbywa się kontem technicznym i tokenem JWT ważnym 12 godzin. Przy przełączeniu sprawdź, czy serwer KD odnawia token na czas, bo długie okno serwisowe może przekroczyć ważność tokenu i wstrzymać wysyłkę.

Test odbioru po przełączeniu bramy

Po każdej bramie wykonaj test: odbicie testową kartą na nowym czytniku, sprawdzenie zdarzenia w KD, sprawdzenie, czy zdarzenie dotarło do InnerWeb, i kontrola lokalizacji czytnika. Zapisz godzinę testu i wynik w protokole odbioru.

Zdarzenia z KD trafiają do ewidencji obecności i, jeśli moduł jest włączony, do rejestracji czasu pracy. Moduł czasu pracy dostarcza się domyślnie wyłączony i włącza ustawieniem administratora, więc brak odbić nie zawsze oznacza błąd integracji.

  • odbicie testowe i potwierdzenie zdarzenia w KD
  • zdarzenie widoczne w InnerWeb z właściwym czytnikiem
  • lokalizacja czytnika zgodna z mapą
  • brak duplikatów po odbiciu powtórzonym w krótkim czasie
  • zapis wyniku w protokole odbioru

Idempotencja i zdarzenia po przerwie

Jeśli podczas przełączenia kolejka zdarzeń w KD zbierała odbicia, po wznowieniu wysyłki mogą przyjść zdarzenia z opóźnieniem lub powtórzone. Identyfikator zdarzenia zapewnia idempotencję: to samo zdarzenie wysłane dwa razy nie tworzy dwóch odbić.

Przy dużym ruchu skala ma znaczenie: w podobnej integracji działającej od 2024 r. przetwarzanych jest ok. 2 100 odbić dziennie w dni robocze. Przy takim wolumenie okno serwisowe w środku zmiany generuje setki zaległych zdarzeń, więc warto je planować na przerwę produkcyjną.

Materiał wideo

Często zadawane pytania

Czy wymiana czytników na OSDP wymaga zmian w InnerWeb?

Nie, o ile system KD nadal wysyła zdarzenia odbicia. Warto zweryfikować identyfikatory czytników i mapę lokalizacji.

Czy trzeba otwierać porty przychodzące po zmianie czytników?

Nie. Połączenie inicjuje strona zakładu jako ruch wychodzący na porcie 443.

Co z odbiciami zebranymi podczas przerwy?

Po wznowieniu mogą dotrzeć z opóźnieniem. Identyfikator zdarzenia zapewnia, że to samo zdarzenie nie zostanie zapisane dwa razy.

Źródła

Wymieniasz czytniki w KD?

Opisz nam system KD i plan wymiany. Pomożemy przygotować test zdarzeń, żeby odbicia nie zniknęły z InnerWeb po przełączeniu.

Porozmawiajmy