Cel integracji i podział odpowiedzialności
Zakład ma system kontroli dostępu z czytnikami i kartami oraz system ewidencji czasu pracy. InnerWeb jest niezależnym systemem uzupełniającym: przyjmuje zdarzenia odbicia, łączy je z kwalifikacjami, zezwoleniami, obecnością i rejestracją czasu pracy, i nie zastępuje ani KD, ani RCP, ani HR.
InnerWeb nie produkuje ani nie wymienia czytników. Specyfikacja integracji jest przeznaczona dla dostawcy KD: to on konfiguruje wysyłanie zdarzeń. Zadaniem zakładu jest zapewnić, by dostawca dostał specyfikację i dostęp do środowiska testowego.
Pola zdarzenia: co dostawca KD ma wysłać
Zdarzenie odbicia karty zawiera między innymi czas, miejsce, imię, nazwisko, firmę, numer aktywnej karty, telefon, e-mail i język osoby. Nie wszystkie pola muszą być dostępne w systemie KD, dlatego specyfikację uzgadnia się na poziomie pól obowiązkowych i opcjonalnych.
Minimum praktyczne to czas odbicia, miejsce (bramka lub czytnik) i identyfikator osoby: numer aktywnej karty. Pozostałe pola ułatwiają dopasowanie osoby do konta, ale dane osobowe należy przekazywać w zakresie niezbędnym i zgodnym z podstawą prawną zakładu.
- czas odbicia z oznaczeniem strefy czasowej
- miejsce: identyfikator bramki lub czytnika
- numer aktywnej karty
- imię i nazwisko oraz firma, jeśli system KD je przechowuje
- język osoby, jeśli ma służyć komunikatom
Przykładowy harmonogram integracji webhooka (założenie)
Uwierzytelnienie: token z ograniczonym czasem ważności
InnerWeb przyjmuje zdarzenie odbicia karty przez webhook uwierzytelniony tokenem z ograniczonym czasem ważności: 12 godzin. Dostawca KD musi więc zaplanować odnawianie tokenu przed wygaśnięciem, a nie dopiero po odrzuceniu zdarzenia.
W specyfikacji warto zapisać, kto i jak odnawia token, co się dzieje ze zdarzeniami wysłanymi po wygaśnięciu oraz jak dostawca dowiaduje się o błędzie. Dobra praktyka to kolejka po stronie KD, która ponawia wysyłkę, gdy odbiór nie został potwierdzony.
Token nie może być zapisany w jawnym pliku konfiguracyjnym ani w treści zgłoszenia serwisowego. Przekazanie odbywa się kanałem uzgodnionym przez działy IT obu stron.
Kolejność prac: od testu do produkcji
Etap pierwszy: dostawca KD dostaje specyfikację i dane środowiska testowego. Etap drugi: wysyłka zdarzeń testowych z jednej bramki, sprawdzenie pól i czasu. Etap trzeci: wysyłka z wszystkich bramek jednej hali. Etap czwarty: włączenie całego zakładu i porównanie liczby odbić po obu stronach.
Porównanie liczby odbić jest kluczowym testem: liczba zdarzeń wysłanych przez KD i przyjętych przez InnerWeb w tym samym oknie czasowym powinna być taka sama. Różnice analizuje się według bramki i godziny, bo często wskazują konkretny czytnik albo moment wygaśnięcia tokenu.
Pułapki: czas, duplikaty i odbicia bez osoby
Pierwsza pułapka to strefa czasowa: czas odbicia zapisany w czasie lokalnym bez oznaczenia strefy daje błąd o godzinę w okresie zmiany czasu, co w ewidencji pracy wygląda jak godzina nadliczbowa. Czas należy przekazywać z oznaczeniem strefy.
Druga pułapka to duplikaty: ta sama karta odbita dwukrotnie w ciągu kilku sekund, bo czytnik odczytał ją i przy wejściu, i przy wyjściu. Reguły filtrowania ustala się z ochroną, nie w kodzie integracji.
Trzecia pułapka to odbicia bez osoby: numer karty, który nie ma przypisanego konta, albo przypisany do konta zdublowanego. Takie zdarzenie trafia do listy wyjątków, a kontrola par zdublowanych kont po imporcie kart ogranicza ich liczbę.
Odbiór i utrzymanie
Odbiór kończy się protokołem: lista bramek, wynik porównania liczby odbić, test wygaśnięcia i odnowienia tokenu, test awarii łącza. Utrzymanie to alarm braku zdarzeń z bramki w godzinach, w których zwykle są odbicia, bo cisza z jednej bramki bywa pierwszym objawem awarii.
Zakład powinien wskazać osobę, która odbiera alarmy, i dostawcę KD, który je rozwiązuje po stronie swojego systemu. Bez tego integracja działa, dopóki nie zdarzy się pierwszy problem.
Przy rozbudowie zakładu o nową halę lub bramę dostawca KD dopisuje nowe czytniki do wysyłki, a zakład aktualizuje listę miejsc, żeby zdarzenia z nowej bramy nie trafiały jako odbicia bez lokalizacji. Zmiana listy bramek powinna być krokiem w procedurze zmiany, równie obowiązkowym jak zamówienie czytnika.
Materiał wideo
Często zadawane pytania
Czy InnerWeb wymienia czytniki?
Nie. InnerWeb integruje się z istniejącym systemem KD, a specyfikacja jest przeznaczona dla jego dostawcy.
Jak długo ważny jest token webhooka?
12 godzin, więc dostawca KD musi zaplanować jego odnawianie.
Jakie dane zawiera zdarzenie odbicia?
Między innymi czas, miejsce, imię, nazwisko, firmę, numer aktywnej karty, telefon, e-mail i język osoby, w zakresie uzgodnionym z zakładem.
Jak sprawdzić, że integracja działa?
Porównaj liczbę odbić wysłanych przez KD i przyjętych przez InnerWeb w tym samym oknie czasowym, według bramki.
Źródła
Przekaż specyfikację dostawcy KD
Przygotujemy specyfikację pól i uwierzytelnienia dla Państwa dostawcy KD oraz plan testów z jednej bramki.
Porozmawiajmy