Support Hub/API & Integrations/Jak obsługiwać zduplikowane zdarzenia odbić i zdarzenia w…
Translated from the English article and reviewed by a person. Read the English original
Developer

Jak obsługiwać zduplikowane zdarzenia odbić i zdarzenia w niewłaściwej kolejności

Jak obsługiwać zduplikowane zdarzenia odbić i zdarzenia w niewłaściwej kolejności

 

Rejestracja obecności w czasie rzeczywistym wygląda prosto: ktoś przykłada kartę lub palec, Twój system odbiera zdarzenie i je zapisuje. W praktyce dane o obecności są bardziej chaotyczne. To samo zdarzenie może dotrzeć dwa razy. Pracownik może dwukrotnie szybko przyłożyć palec do czytnika. Urządzenie, które straciło połączenie, może wysłać poranne wyjście dopiero po południu. Ktoś może nacisnąć niewłaściwy przycisk wejścia. Jeśli Twój system zapisuje każde zdarzenie dokładnie w takiej postaci, w jakiej je otrzymuje, te drobne problemy przekładają się na błędne liczby przepracowanych godzin, spory dotyczące wynagrodzeń i raporty, którym nikt nie ufa. Ten przewodnik wyjaśnia różne rodzaje zduplikowanych i niewłaściwie uporządkowanych zdarzeń odbić, ich przyczyny oraz zestaw jasnych zasad opartych na polach OperationID i LogTime, które pozwalają utrzymać czystość rejestrów obecności.

01 · Problem

Dlaczego czyste dane o obecności są trudniejsze, niż się wydaje

Zdarzenia obecności pochodzą z urządzeń fizycznych, są rozproszone między lokalizacjami, używane przez prawdziwych ludzi i przesyłane przez sieci, które czasami się rozłączają. Każdy z tych czynników tworzy sposób, w jaki dane mogą dotrzeć w niedoskonałej postaci. Żaden z nich nie jest usterką systemu biometrycznego. To po prostu to, co dzieje się, gdy świat fizyczny spotyka się z oprogramowaniem.

Dobra wiadomość jest taka, że każde zdarzenie odbicia z Cams Biometrics Gateway zawiera informacje potrzebne do jego oczyszczenia. Większość pracy wykonują dwa pola:

Pole Czym jest Co pozwala zrobić
OperationID Unikalne odniesienie do każdego zdarzenia wysłanego przez Gateway Rozpoznać dokładnie to samo zdarzenie, jeśli dotrze więcej niż raz
LogTime Czas, w którym osoba faktycznie się odbiła, wraz z przesunięciem strefy czasowej urządzenia Ułożyć zdarzenia w rzeczywistej kolejności ich wystąpienia, niezależnie od tego, kiedy dotrą

Trzy kolejne pola pomagają w trudniejszych przypadkach: UserId identyfikuje osobę, SerialNumber identyfikuje urządzenie, a Type określa, czy osoba nacisnęła wejście, czy wyjście.

Zdarzenie odbicia z Callback API

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

02 · Nie wszystkie duplikaty są takie same

Cztery rodzaje zduplikowanych zdarzeń odbić

Najczęstszym błędem jest traktowanie każdego duplikatu w ten sam sposób. Istnieją cztery różne rodzaje, a każdy wymaga innego rozwiązania. Niektóre są techniczne, a niektóre wynikają ze sposobu, w jaki ludzie korzystają z urządzeń.

Rodzaj duplikatu Jak wygląda Jak go rozpoznać Co zrobić
Ponownie dostarczone zdarzenie Dokładnie to samo zdarzenie przychodzi dwa razy Ten sam OperationID Zignorować drugą kopię, ale nadal odpowiedzieć done
Nakładający się import Zdarzenie odebrane przez callback zostaje ponownie zaimportowane podczas uzgadniania Ten sam UserId, LogTime i SerialNumber, ale z innego źródła Zignorować drugą kopię
Podwójne odbicie Osoba dwukrotnie przykłada kartę lub palec w ciągu kilku sekund Różne OperationID, ta sama osoba, czasy LogTime bardzo blisko siebie Traktować jako jedno odbicie, stosując regułę minimalnego odstępu
Błędnie oznaczone odbicie Osoba naciska wejście, choć chciała się wylogować Dwa wejścia pod rząd bez wyjścia między nimi Stosować regułę parowania przy obliczaniu godzin

Duplikaty techniczne a duplikaty wynikające z działania człowieka

Dwa pierwsze rodzaje są techniczne: to to samo odbicie widziane dwukrotnie przez Twój system i powinny po prostu zostać zignorowane. Dwa ostatnie wynikają z działania człowieka: są to prawdziwe, odrębne odbicia, a decyzja o ich znaczeniu to kwestia reguły biznesowej. Oba typy obsługuj osobno. Odbiornik zdarzeń powinien usuwać wyłącznie duplikaty techniczne. Logika obecności powinna decydować, co oznaczają duplikaty wynikające z działania człowieka.

Dlaczego dochodzi do ponownego dostarczania

Callback to wymiana: Gateway wysyła zdarzenie, a Twój serwer odpowiada potwierdzeniem done. Jeśli odpowiedź nigdy nie dotrze, bo serwer działał wolno, został zrestartowany lub na chwilę był nieosiągalny, zdarzenie może zostać wysłane ponownie. Twój serwer mógł już zapisać pierwszą kopię. Dlatego zasada jest zawsze taka sama: jeśli już widziałeś dany OperationID, nie zapisuj go ponownie, ale odpowiedz done, aby Gateway wiedział, że zdarzenie dotarło. Zweryfikuj dokładne zachowanie przy ponownym dostarczaniu w swojej konfiguracji w dokumentacji Cams Web API.

Odpowiedź, jaką Twój odbiornik wysyła na każde zdarzenie, także na duplikaty

{ "status": "done" }

03 · Kolejność przybycia to nie rzeczywista kolejność

Dlaczego zdarzenia odbić docierają w niewłaściwej kolejności

Twój serwer odbiera zdarzenia w kolejności ich przybycia. Obecność musi być jednak obliczana w kolejności odbić. Najczęściej obie kolejności są takie same. Czasami jednak nie są.

Przyczyna Co się dzieje Przykład
Urządzenie lub lokalizacja przestaje być online Urządzenia zapisują odbicia lokalnie, a po przywróceniu połączenia wysyłają je wszystkie naraz Wyjście o 13:01 dociera o 13:41, po odbiciu o 13:35 z innego urządzenia
Opóźnienia sieciowe Zdarzenia z różnych urządzeń pokonują różne trasy i zajmują różny czas Dwa odbicia w odstępie jednej sekundy docierają w odwrotnej kolejności
Wiele urządzeń na osobę Pracownik wchodzi przez główną bramę, a wychodzi przez boczne drzwi Zdarzenia z dwóch urządzeń przeplatają się w nieprzewidywalny sposób
Importy uzgadniające Brakujące zdarzenia są uzupełniane później na podstawie logów urządzeń Zdarzenie z poniedziałku zostaje dodane do Twojego systemu we wtorek

Sama wiadomość już pokazuje tę różnicę. LogTime to moment, w którym nastąpiło odbicie. Time to znacznik czasu samej wiadomości, podany w GMT. W przykładowej wiadomości powyżej odbicie nastąpiło o 07:48 czasu lokalnego, ale wiadomość została wysłana o 04:19 GMT, czyli o 09:49 w tej samej strefie czasowej, dwie godziny później. Ta różnica dokładnie odpowiada okresowi offline. Gdybyś sortował według czasu przybycia, to odbicie trafiłoby w złe miejsce.

Czas przybycia mówi, kiedy Twój serwer się o tym dowiedział. LogTime mówi, kiedy to się wydarzyło. Obecność musi zawsze odpowiadać LogTime.

04 · Osiem zasad

Podręcznik czystych danych o obecności

Te osiem zasad obsługuje wszystkie przypadki opisane powyżej. Pierwsze cztery dotyczą odbiornika callback i przechowywania danych. Ostatnie cztery dotyczą logiki, która przekształca zapisane zdarzenia w obecność.

1

Najpierw zapisz każde surowe zdarzenie

Zapisz każdą wiadomość dokładnie tak, jak została otrzymana, zanim zrobisz z nią cokolwiek innego. Jeśli reguła później okaże się błędna, możesz przetworzyć dane ponownie na podstawie surowych danych.

2

Ignoruj powtórzone OperationID

Zadbaj, aby OperationID był unikalny w Twoim magazynie danych. Jeśli ten sam OperationID przychodzi ponownie, pomiń zapis i nadal odpowiedz done.

3

Używaj klucza naturalnego dla importów

Dla zdarzeń importowanych podczas uzgadniania traktuj połączenie UserId, LogTime i SerialNumber jako tożsamość odbicia, tak aby to samo odbicie nigdy nie zostało zapisane dwukrotnie z dwóch źródeł.

4

Sortuj według LogTime, nigdy według czasu przybycia

Parsuj LogTime wraz z przesunięciem strefy czasowej i zawsze sortuj według niego przy obliczaniu obecności.

5

Przeliczaj z opóźnieniem, a nie w momencie przybycia

Nie finalizuj godzin dnia w chwili, gdy przychodzi wyjście. Przeliczaj, gdy przychodzą opóźnione zdarzenia, i blokuj dzień dopiero po oknie rozliczeniowym, na przykład przed uruchomieniem wynagrodzeń.

6

Łącz podwójne odbicia z minimalnym odstępem

Traktuj odbicia tej samej osoby w krótkim oknie, na przykład dwóch minut, jako jedno odbicie. Wybierz okno odpowiednie dla Twojego miejsca pracy.

7

Parowanie odbić zgodnie z jasną regułą

Określ, jak obsługiwać błędnie oznaczone odbicia, na przykład parując odbicia w kolejności czasowej lub przyjmując pierwsze odbicie jako wejście, a ostatnie jako wyjście. Stosuj tę samą regułę wszędzie.

8

Prowadź rejestr każdej korekty

Gdy reguła łączy, ignoruje lub przepisuje odbicie, zapisz, co się wydarzyło i dlaczego. Dział HR i audytorzy muszą widzieć, w jaki sposób surowe odbicia stały się przepracowanymi godzinami.

Dbaj o dokładność zegarów urządzeń

LogTime pochodzi z zegara urządzenia. Jeśli czas urządzenia jest błędny, każde odbicie na nim jest błędne, a żadne sortowanie tego nie naprawi. Upewnij się, że każde urządzenie ma poprawną datę, godzinę i strefę czasową, i sprawdzaj je po zanikach zasilania lub aktualizacjach oprogramowania.

05 · Zastosowanie zasad w praktyce

Przykład praktyczny: jeden pracownik, jeden chaotyczny dzień

Oto realistyczny dzień pracownika 2 w lokalizacji Burj Khalifa, przedstawiony w kolejności, w jakiej zdarzenia dotarły na serwer. Lokalizacja straciła połączenie na część dnia.

Przybyło OperationID Type LogTime Co robią zasady
09:02 op-1001 CheckIn 08:58 Zapisano
09:03 op-1001 CheckIn 08:58 Ten sam OperationID: zignorowano, wysłano done
09:04 op-1002 CheckIn 08:59 W ciągu dwóch minut od 08:58: połączono jako podwójne odbicie
13:40 op-1004 CheckIn 13:35 Zapisano
13:41 op-1003 CheckOut 13:01 Dotarło spóźnione z okresu offline: umieszczono przed 13:35 według LogTime
18:05 op-1005 CheckIn 18:04 Drugie wejście z rzędu: sparowano jako końcowe wyjście dnia

Po posortowaniu według LogTime i oczyszczeniu dzień składa się z dwóch jasnych okresów pracy:

Okres Początek Koniec Czas trwania
Rano 08:58 13:01 4 godziny 3 minuty
Popołudnie 13:35 18:04 4 godziny 29 minut
Łącznie przepracowano 8 godzin 32 minuty

Bez tych zasad te same surowe zdarzenia mogłyby dać trzy wejścia rano, wyjście pojawiające się po popołudniowym wejściu i brak wyjścia na koniec dnia. Wynagrodzenia zgłosiłyby błędy lub, co gorsza, obliczyłyby błędne godziny bez zauważenia tego przez nikogo.

06 · Stworzone dla czystych danych

Jak Cams Gateway pomaga utrzymać czystość rejestrów

Czyste dane o obecności zaczynają się od zdarzeń, które niosą właściwe informacje. Cams Biometrics Gateway został zaprojektowany tak, aby każde zdarzenie otrzymane przez Twój system można było zidentyfikować, uporządkować i prześledzić.

Możliwość Cams Jak pomaga
OperationID przy każdym zdarzeniu Zapewnia Twojemu systemowi niezawodny sposób rozpoznawania i ignorowania ponownie dostarczonych zdarzeń
LogTime z przesunięciem strefy czasowej Pozwala ułożyć zdarzenia w ich rzeczywistej kolejności, gdziekolwiek i kiedykolwiek dotrą
UserId, SerialNumber i LabelName Identyfikują osobę, urządzenie i lokalizację, które razem tworzą klucz naturalny dla importów
Pamięć podręczna offline i kolejka Przechowuje zdarzenia w czasie przerw w łączności i dostarcza je z oryginalnymi znacznikami czasu
Potwierdzenie done Stanowi wyraźny sygnał, że każde zdarzenie dotarło, dzięki czemu dostarczenie może zostać potwierdzone
Operacje RESTful do ładowania logów Pozwalają pobierać logi urządzeń na żądanie, aby uzgadniać dane i uzupełniać wszelkie luki
Podpowiedzi generatora kodu AI Generują odbiornik callback, który weryfikuje tokeny i zapisuje każde zdarzenie, gotowy do dodania zasad z tego przewodnika

Kto za co odpowiada

Cams Gateway dostarcza każde zweryfikowane odbicie wraz z informacjami potrzebnymi do jego oczyszczenia. Usuwanie duplikatów technicznych należy do Twojego odbiornika callback. Łączenie podwójnych odbić, parowanie odbić i obliczanie godzin należą do Twojego systemu HRMS, wynagrodzeń lub logiki obecności, gdzie już funkcjonują Twoje reguły biznesowe.

Najczęściej zadawane pytania

Czy mój odbiornik powinien odrzucać zduplikowane zdarzenia z błędem?

Nie. Odpowiadaj done także na duplikaty. Zdarzenie dotarło bezpiecznie, a odpowiedź z błędem może spowodować jego ponowne wysłanie. Po prostu pomiń jego zapis.

Czy mogę użyć samego LogTime do wykrywania duplikatów?

Nie w pojedynkę. Dwie różne osoby mogą odbić się w tej samej sekundzie. Dla ponownie dostarczonych zdarzeń używaj OperationID, a dla importów połączenia UserId, LogTime i SerialNumber.

Jak długie powinno być okno podwójnego odbicia?

Wystarczająco długie, by wychwycić przypadkowe powtórne przyłożenia, i wystarczająco krótkie, by nie łączyć prawdziwych, odrębnych odbić. Okno od jednej do dwóch minut odpowiada większości miejsc pracy, ale wybierz wartość dopasowaną do Twoich zmian i układu lokalizacji.

Kiedy należy zablokować obecność z danego dnia?

Po oknie rozliczeniowym, które pozwala opóźnionym zdarzeniom dotrzeć, na przykład następnego ranka lub tuż przed uruchomieniem wynagrodzeń. Do tego czasu przeliczaj dane dnia za każdym razem, gdy przychodzą nowe zdarzenia.

Czy dotyczy to także skanów twarzy, kart i kodów PIN?

Tak. Każdy typ wejścia przychodzi w tym samym formacie zdarzeń, z tymi samymi polami OperationID i LogTime, więc te same zasady obowiązują niezależnie od sposobu weryfikacji osoby.

Podsumowanie: zaufanie bierze się z zasad, a nie ze szczęścia

Zduplikowane i niewłaściwie uporządkowane zdarzenia odbić to nie rzadkie przypadki brzegowe. To normalna część prowadzenia rejestracji obecności biometrycznej na prawdziwych urządzeniach, w prawdziwych sieciach i z udziałem prawdziwych ludzi. Różnica między danymi o obecności, którym ufa dział HR, a danymi powodującymi spory, nie wynika ze szczęścia. Wynika z niewielkiego zestawu jasnych zasad, stosowanych konsekwentnie.

Ignoruj powtórzone OperationID. Sortuj wszystko według LogTime. Traktuj duplikaty wynikające z działania człowieka jako reguły biznesowe, a nie błędy techniczne. Przeliczaj z opóźnieniem, zapisuj każdą korektę i dbaj o dokładność zegarów urządzeń. Dzięki tym zasadom każde zweryfikowane odbicie staje się wiarygodnym rekordem.

Cams Biometrics Gateway dostarcza dane, dzięki którym te zasady mogą działać. Każde zdarzenie Callback zawiera OperationID, LogTime wraz z przesunięciem strefy czasowej oraz dane o użytkowniku, urządzeniu i lokalizacji potrzebne do zidentyfikowania każdego odbicia, z urządzeń ponad 15 marek. Pamięć podręczna offline i kolejka chronią zdarzenia podczas przerw, a operacje RESTful pozwalają uzgadniać dane z logami urządzeń, kiedy tylko zajdzie taka potrzeba. Poznaj platformę na stronie CamsBiometrics.com, przeczytaj pełną dokumentację Web API pod adresem developer.camsbiometrics.com i wygeneruj swój odbiornik callback za pomocą Podpowiedzi generatora kodu AI.

Was this article helpful?