Support Hub/API & Integrations/Як обробляти дубльовані події відміток і події, що…
Translated from the English article and reviewed by a person. Read the English original
Developer

Як обробляти дубльовані події відміток і події, що надходять не за порядком

Як обробляти дубльовані події відміток і події, що надходять не за порядком

 

Облік відвідуваності за допомогою біометрії в реальному часі здається простим: людина проходить сканування, ваша система отримує подію і зберігає її. На практиці дані про відвідуваність буває важче зберегти чистими. Та сама подія може надійти двічі. Працівник може двічі поспіль приставити палець до сканера. Пристрій, який втратив з'єднання, може надіслати ранкову відмітку виходу вдень. Людина може натиснути не ту кнопку входу. Якщо ваша система зберігає кожну подію саме в тому вигляді, в якому вона надійшла, ці дрібні проблеми перетворюються на неправильно розраховані робочі години, спори щодо зарплати та звіти, яким ніхто не довіряє. У цьому посібнику пояснюються різні типи дубльованих подій відміток і подій, що надійшли не за порядком, причини їх появи та чіткий набір правил, що спираються на OperationID і LogTime і допомагають зберігати записи про відвідуваність чистими.

01 · Проблема

Чому чисті дані про відвідуваність складніші, ніж здається

Події відвідуваності надходять з фізичних пристроїв, розміщених на різних об'єктах, які використовують реальні люди і які підключені до мереж, що інколи переривається. Кожен із цих чинників створює можливість для того, щоб дані надійшли з помилками. Жоден із них не є несправністю біометричної системи. Це просто те, що відбувається, коли фізичний світ стикається з програмним забезпеченням.

Гарна новина полягає в тому, що кожна подія відмітки від Cams Biometrics Gateway містить інформацію, необхідну для її очищення. Більшість роботи виконують два поля:

Поле Що це Що це дозволяє зробити
OperationID Унікальний ідентифікатор кожної події, яку надсилає Gateway Розпізнати точно ту саму подію, якщо вона надійшла більше одного разу
LogTime Час, коли особа фактично пройшла сканування, із зсувом часового поясу пристрою Розташувати події у справжньому порядку, в якому вони відбулися, незалежно від того, коли вони надійшли

Ще три поля допомагають у складніших випадках: UserId визначає особу, SerialNumber визначає пристрій, а Type вказує, чи особа відзначила вхід або вихід.

Подія відмітки з 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 · Не всі дублікати однакові

Чотири типи дубльованих подій відміток

Найпоширеніша помилка полягає в тому, щоб обробляти всі дублікати однаково. Існує чотири різні типи, і кожен потребує окремого рішення. Одні є технічними, а інші виникають через те, як люди користуються пристроями.

Тип дубліката Як це виглядає Як його розпізнати Що робити
Повторно надіслана подія Та сама подія надходить двічі Однаковий OperationID Ігнорувати другу копію, але все одно відповісти done
Імпорт з перетином Подія, отримана через callback, повторно імпортується під час звірки Однакові UserId, LogTime і SerialNumber, але з іншого джерела Ігнорувати другу копію
Подвійне сканування Людина двічі торкається сканера протягом кількох секунд Різні OperationID, та сама особа, LogTime дуже близькі один до одного Розглядати як одну відмітку, використовуючи правило мінімального інтервалу
Відмітка з хибним типом Людина натискає вхід, коли мала на увазі вихід Два входи поспіль без виходу між ними Застосовувати правило парування під час розрахунку годин

Технічні дублікати та дублікати, спричинені людьми

Перші два типи є технічними: це одне й те саме сканування, яке бачить ваша система двічі, і їх слід просто ігнорувати. Останні два є спричиненими людьми: це справжні, окремі сканування, і визначення їхнього значення є бізнес-правилом. Розділяйте ці два типи обробки. Ваш приймач має видаляти лише технічні дублікати. Логіка обліку відвідуваності має визначати, що означають дублікати, спричинені людьми.

Чому виникає повторне надсилання

Callback є діалогом: Gateway надсилає подію, а ваш сервер відповідає підтвердженням done. Якщо відповідь не надходить, тому що ваш сервер працював повільно, перезапускався або був тимчасово недоступний, подію можуть надіслати повторно. Ваш сервер міг уже зберегти першу копію. Тому правило завжди однакове: якщо ви вже бачили OperationID, не зберігайте його повторно, але обов'язково відповідайте done, щоб Gateway знав, що подію отримано. Точну поведінку повторного надсилання для вашої конфігурації уточнюйте в документації Cams Web API.

Відповідь, яку ваш приймач надсилає на кожну подію, включно з дублікатами

{ "status": "done" }

03 · Порядок надходження не є справжнім порядком

Чому події відміток надходять не за порядком

Ваш сервер отримує події в порядку надходження. Відвідуваність має розраховуватися в порядку сканувань. Здебільшого ці порядки збігаються. Інколи — ні.

Причина Що відбувається Приклад
Пристрій або об'єкт офлайн Пристрої продовжують локально записувати сканування, а потім надсилають їх усі, коли з'єднання відновлюється Вихід о 13:01 надходить о 13:41, після скcanування о 13:35 з іншого пристрою
Затримки мережі Події з різних пристроїв проходять різні маршрути і витрачають різний час Два сканування з різницею в одну секунду надходять у зворотному порядку
Кілька пристроїв на одну особу Працівник відмічає вхід на головній брамі, а вихід — на бічних дверях Події з двох пристроїв чергуються непередбачувано
Імпорти зі звірки Відсутні події пізніше заповнюються з журналів пристроїв Подія з понеділка додається до вашої системи у вівторок

Корисне навантаження вже містить інформацію про різницю. LogTime — це час, коли відбулося сканування. Time — це позначка часу самого повідомлення в GMT. У наведеному вище прикладі корисного навантаження сканування відбулося о 07:48 за місцевим часом, а повідомлення було надіслано о 04:19 за GMT, що відповідає 09:49 у тому самому часовому поясі, тобто на дві години пізніше. Саме така затримка є типовою для періоду офлайн-роботи. Якби ви сортували за часом надходження, це сканування опинилося б не на своєму місці.

Час надходження показує, коли ваш сервер про це дізнався. LogTime показує, коли це сталося. Відвідуваність завжди має слідувати за LogTime.

04 · Вісім правил

Посібник з чистих даних про відвідуваність

Ці вісім правил охоплюють кожен із описаних вище випадків. Перші чотири належать до вашого приймача callback і сховища. Останні чотири належать до логіки, яка перетворює збережені події на дані про відвідуваність.

1

Спочатку зберігайте кожну необроблену подію

Зберігайте кожне корисне навантаження точно в тому вигляді, в якому його отримано, перш ніж робити з ним щось інше. Якщо правило згодом виявиться неправильним, ви зможете повторно обробити необроблені дані.

2

Ігноруйте повторювані OperationID

Зробіть OperationID унікальним у вашому сховищі. Якщо той самий OperationID надходить знову, пропускайте збереження, але все одно відповідайте done.

3

Використовуйте природний ключ для імпорту

Для подій, імпортованих під час звірки, розглядайте комбінацію UserId, LogTime і SerialNumber як ідентичність сканування, щоб одне й те саме сканування ніколи не зберігалося двічі з двох джерел.

4

Упорядковуйте за LogTime, а не за часом надходження

Аналізуйте LogTime разом із зсувом часового поясу і завжди сортуйте за ним під час розрахунку відвідуваності.

5

Розраховуйте із затримкою, а не в момент надходження

Не фіксуйте робочі години за день у момент, коли надходить вихід. Перераховуйте їх, коли надходять запізнілі події, і закривайте день лише після періоду стабілізації, наприклад перед запуском нарахування зарплати.

6

Об'єднуйте подвійні сканування з мінімальним інтервалом

Розглядайте сканування однієї й тієї самої особи в межах короткого вікна, наприклад двох хвилин, як одну відмітку. Оберіть вікно, що підходить для вашого робочого місця.

7

Пари відміток за чітким правилом

Визначте, як обробляти відмітки з хибним типом, наприклад парувати сканування в часовому порядку або використовувати перше сканування як прихід, а останнє як вихід. Застосовуйте одне й те саме правило всюди.

8

Ведіть журнал кожного виправлення

Коли правило об'єднує, ігнорує або перепозначає сканування, фіксуйте, що сталося і чому. HR і аудитори мають бачити, як необроблені сканування перетворилися на відпрацьовані години.

Стежте за точністю годинників пристроїв

LogTime береться з годинника пристрою. Якщо час пристрою неправильний, кожне сканування на ньому також неправильне, і жодне сортування цього не виправить. Переконайтеся, що кожен пристрій має правильну дату, час і часовий пояс, і перевіряйте їх після відключень електроенергії або оновлень прошивки.

05 · Застосування правил разом

Практичний приклад: один працівник, один заплутаний день

Ось реалістичний день для працівника 2 на об'єкті Burj Khalifa, показаний у порядку, в якому події надійшли на сервер. Частину дня об'єкт був без з'єднання.

Надійшло OperationID Type LogTime Що роблять правила
09:02 op-1001 CheckIn 08:58 Збережено
09:03 op-1001 CheckIn 08:58 Той самий OperationID: проігноровано, надіслано done
09:04 op-1002 CheckIn 08:59 У межах двох хвилин від 08:58: об'єднано як подвійне сканування
13:40 op-1004 CheckIn 13:35 Збережено
13:41 op-1003 CheckOut 13:01 Надійшло із запізненням з періоду офлайн-роботи: розміщено перед 13:35 за LogTime
18:05 op-1005 CheckIn 18:04 Другий вхід поспіль: сparено як останній вихід дня

Після впорядкування за LogTime і очищення день перетворюється на два чіткі робочі періоди:

Період Початок Кінець Тривалість
Ранок 08:58 13:01 4 години 3 хвилини
Після полудня 13:35 18:04 4 години 29 хвилин
Усього відпрацьовано 8 годин 32 хвилини

Без правил ті самі необроблені події могли б створити три входи вранці, вихід, що з'явився після вхідної відмітки вдень, і відсутність виходу в кінці дня. Система нарахування зарплати або видала б помилки, або, що гірше, розрахувала б неправильні години, і ніхто б цього не помітив.

06 · Створено для чистих даних

Як Cams Gateway допомагає зберігати чисті записи

Чисті дані про відвідуваність починаються з подій, які містять правильну інформацію. Cams Biometrics Gateway створено так, щоб кожну подію, яку отримує ваша система, можна було ідентифікувати, впорядкувати і простежити.

Можливість Cams Як це допомагає
OperationID для кожної події Дає вашій системі надійний спосіб розпізнавати і ігнорувати повторно надіслані події
LogTime із зсувом часового поясу Дозволяє розташовувати події у їхньому справжньому порядку, незалежно від того, де і коли вони надійшли
UserId, SerialNumber і LabelName Визначають особу, пристрій і об'єкт, які разом утворюють природний ключ для імпорту
Офлайн-кеш і черга Зберігає події під час перерв зв'язку і доставляє їх з оригінальними позначками часу
Підтвердження done Дає чіткий сигнал про те, що кожну подію отримано, тож доставку можна підтвердити
RESTful-операції для завантаження журналів Дозволяють запитувати журнали пристроїв за потреби, щоб звірити дані та заповнити будь-які прогалини
AI Code Generator Prompts Генерують приймач callback, який перевіряє токени і журналює кожну подію, готовий для додавання правил із цього посібника

Хто що робить

Cams Gateway доставляє кожне перевірене сканування з інформацією, необхідною для його очищення. Видалення технічних дублікатів належить до вашого приймача callback. Об'єднання подвійних сканувань, парування відміток і розрахунок годин належать до вашої HRMS, системи нарахування зарплати або логіки обліку відвідуваності, де вже зберігаються ваші бізнес-правила.

Поширені запитання

Чи має мій приймач відхиляти дубльовані події з помилкою?

Ні. Відповідайте done і на дублікати. Подія надійшла безпечно, а відповідь із помилкою може призвести до її повторного надсилання. Просто пропустіть її збереження.

Чи можна використовувати лише LogTime для виявлення дублікатів?

Ні, самостійно — не можна. Двоє різних людей можуть відсканувати в ту саму секунду. Для повторно надісланих подій використовуйте OperationID, а для імпортів — комбінацію UserId, LogTime і SerialNumber.

Яким має бути вікно подвійного сканування?

Достатньо довгим, щоб зловити випадкові повторні дотики, і достатньо коротким, щоб не об'єднувати справжні окремі відмітки. Вікно від однієї до двох хвилин підходить для більшості робочих місць, але оберіть варіант, який відповідає вашим змінам і плануванню об'єкта.

Коли слід закривати дані відвідуваності за день?

Після періоду стабілізації, який дозволяє надійти із запізненням подіям, наприклад наступного ранку або безпосередньо перед запуском нарахування зарплати. До того часу перераховуйте дані щоразу, коли для цього дня надходять нові події.

Чи стосується це також сканувань обличчя, картки та PIN-коду?

Так. Кожен тип введення надходить у тому самому форматі подій, з тими самими полями OperationID і LogTime, тому ті самі правила застосовуються незалежно від того, як особу було верифіковано.

Висновок: довіра з'являється завдяки правилам, а не випадковості

Дубльовані події відміток і події, що надходять не за порядком, — це не рідкісні винятки. Це звичайна частина роботи обліку відвідуваності за допомогою біометрії на реальних пристроях, у реальних мережах і з реальними людьми. Різниця між даними про відвідуваність, яким довіряє HR, і даними, що спричиняють спори, полягає не в удачі. Вона полягає в невеликому наборі чітких правил, які послідовно застосовуються.

Ігноруйте повторювані OperationID. Упорядковуйте все за LogTime. Розглядайте дублікати, спричинені людьми, як бізнес-правила, а не технічні помилки. Розраховуйте із затримкою, фіксуйте кожне виправлення і стежте за точністю годинників пристроїв. Коли ці правила запроваджено, кожне перевірене сканування стає надійним записом.

Cams Biometrics Gateway надає дані, потрібні для роботи цих правил. Кожна подія Callback містить OperationID, LogTime із зсувом часового поясу, а також дані про особу, пристрій і об'єкт, необхідні для ідентифікації кожного сканування, з пристроїв більш ніж 15 брендів. Офлайн-кеш і черга захищають події під час перерв, а RESTful-операції дозволяють звіряти дані з журналами пристроїв щоразу, коли це потрібно. Ознайомтеся з платформою на CamsBiometrics.com, прочитайте повну документацію Web API на developer.camsbiometrics.com, а також згенеруйте свій приймач callback за допомогою AI Code Generator Prompts.

Was this article helpful?