Интеграция с внешними информационными системами (ВИС)

Платформа НЕЙРОСС может обеспечивать взаимодействие с информационными системами «сторонних» производителей в части получения и передачи авторизованных HTTP-запросов.

Общие сведения

В качестве интегрируемой системы может выступать прикладное программное средство, приложение, программа, выполняющая функции по назначению, и в своих бизнес-процессах использующая данные сети НЕЙРОСС и возможности управления.

В качестве средства интеграции выступает «Плагин НЕЙРОСС ВИС», устанавливаемый на узел Платформа НЕЙРОСС. Плагин НЕЙРОСС ВИС предназначен для интеграции с «внешней» информационной системой (ВИС) в части функций системы контроля и управления доступом (СКУД):

Управление данными владельцев и пропусков — создание, изменение владельцев и пропусков с загрузкой данных из ВИС в НЕЙРОСС и наоборот, — из НЕЙРОСС в ВИС.
Удалённый СКУД — инициирование транзакций доступа из ВИС в НЕЙРОСС на конкретной ТД и уведомление ВИС от НЕЙРОСС о результате транзакции.

Плагин реализует HTTP-API, позволяющее:

Получить из НЕЙРОСС список всех уровней доступа, разрешенных «внешней» системе (УД ВИС);
Получить из НЕЙРОСС список всех точек доступа ВИС, которые которые указаны хотя бы в одном УД ВИС (ТД ВИС);
Получить из НЕЙРОСС список всех владельцев пропусков, которым назначен хотя бы один УД ВИС (пропуска ВИС);
Создавать новых владельцев пропусков ВИС;
Инициировать из ВИС транзакцию доступа владельцев пропусков ВИС через ТД ВИС.

Содержание:

Лицензирование

Для обеспечения функции взаимодействия по HTTP API, проверьте наличие требуемых лицензий в параметрах лицензии [Основные настройки]. В противном случае требуется приобрести лицензии [Лицензирование | Платформа НЕЙРОСС].

Тип узла	Параметр лицензии	Комментарий
Платформа НЕЙРОСС	Плагин НЕЙРОСС ВИС	Использование сервиса взаимодействия с внешней информационной системой (ВИС) посредством утвержденного API.
Платформа НЕЙРОСС	Плагин НЕЙРОСС ВИС: максимальное количество точек доступа	Управление одним виртуальным считывателем из внешней информационной системы (виртуальный считыватель точки доступа БОРЕЙ). Лицензирование по количеству точек доступа, запросы к считывателям которых требуется отправлять.

ВАЖНО

Обращаем внимание, что передача лицензии на использование плагина НЕЙРОСС ВИС и представленное API НЕЙРОСС ВИС осуществляются на условиях «КАК ЕСТЬ» («AS IS»), в соответствии с общепринятым в международной практике принципом, и не накладывает на компанию ИТРИУМ обязательств по бесплатному сопровождению разработки интегрированного решения. Для обсуждения условий сотрудничества по разработке обратитесь в отдел продаж ИТРИУМ.

Подготовка к настройке

В разделе АРМ НЕЙРОСС Доступ перейдите в раздел Уровни доступа [Уровни доступа] и настройте УД ВИС — уровни доступа, которые следует разрешить внешней информационной системе. Вы можете создать новые уровни доступа с требуемым префиксом, либо просто переименовать созданные ранее уровни, добавив к в начало имени префикс [И] и пробел.
«Внешней» информационной системе предоставляется доступ только к уровням доступа НЕЙРОСС, помеченных как «ВИС» определённым образом: имя уровня доступа содержит префикс в виде
[И] - русская заглавная буква И в квадратных скобках, отделённая от имени пробелом
Например:
[И] Уровень доступа ВИС 1
Пример уровней доступа для интеграции с ВИС

Плагину интеграции станут доступны точки доступа, которые которые указаны хотя бы в одном УД ВИС — ТД ВИС. В настройках плагина можно дополнительно ограничить ТД ВИС, доступных для управления из ВИС [Настройка плагина интеграции].
Задайте пропускам, транзакция по которым может быть инициирована из ВИС один или несколько УД ВИС.

Одному пропуску могут быть назначены как УД ВИС, так и «чисто внутренние» УД НЕЙРОСС. Для задания нескольких уровней используйте режим доступа [Режимы доступа].
ОГРАНИЧЕНИЯ ВИС
АРМ НЕЙРОСС обеспечивает полное управление владельцами, пропусками и уровнями доступа ВИС. Внешняя информационная система может:
1. Получить из НЕЙРОСС только УД ВИС;
2. Получить из НЕЙРОСС и управлять только ТД ВИС;
3. Получить из НЕЙРОСС только тех владельцев и пропуска, которые содержат хотя бы один УД ВИС;
4. Создавать любых новых владельцев и их пропуска, но назначать им может только УД из множества УД ВИС.
ВИС оперирует только разрешённым подмножеством ТД, УД, владельцев и пропусков. При помощи добавления или удаления префикса в названии УД администратор НЕЙРОСС может управлять подмножеством данных, видимых для ВИС. ВИС не может:
1. Удалять владельцев и пропуска;
2. Создавать, удалять и изменять УД;
3. Создавать, удалять и изменять ТД.

Настройка плагина интеграции

Добавление плагина

Сервис работы с ВИС поставляется в виде плагина интеграции — независимого программный модуля, предназначенного для расширения функционала Платформы НЕЙРОСС. Установка плагина является стандартной процедурой и не зависит от предоставляемых функций. Перечень разработанных плагинов и порядок их установки приведён в разделе [Плагины и скрипты].

Право использования функции плагина задано в параметрах лицензии. Дополнительная активация плагина не требуется.

Дождитесь окончания процедуры установки плагина.

Установка плагина может занимать длительное время. Не перезагружайте компьютер и не отключайте его от сети. Перезапуск осуществляется только после полной установки плагина и отображения требования о перезагрузке.

Настройка плагина

После установки наведите указатель мыши на строку с плагином и нажмите на кнопку Настроить.

Откроется окно настройки плагина. Задайте настройки согласно таблице ниже и сохраните изменения.

Параметр	Комментарий
Максимальное количество точек доступа ВИС	Параметр, заданный в лицензии. Определяет количество точек доступа, которыми может управлять «внешняя» информационная система.
Таймаут ожидания транзакции доступа, мс	Период времени, в течение которого ожидается ответ от НЕЙРОСС о результате транзакции доступа, инициированной из ВИС (удалённое предъявление идентификатора на точку доступа НЕЙРОСС). Транзакция доступа завершается по факту получения события «Доступ разрешён» или «Доступ запрещён» от контроллера доступа [События БОРЕЙ]. Если точка доступа не готова обработать транзакцию (например, — еще не закрыта дверь в результате предыдущей транзакции, или точка доступа находится в состоянии Взлом), плагин НЕЙРОСС ВИС будет ожидать ответа в течение заданного времени таймаута, после чего завершит транзакцию ВИС с ошибкой.
API-токен	Данный токен должен передаваться ВИС в каждом запросе в следующем виде: Autorization: Bearer TOKEN , где TOKEN — указанный в поле символьный ряд, например: Autorization: Bearer ce6b228c-9f09-47bd-b5d6-933abc894905 Вы можете изменить автоматически сгенерированный токен на собственный.
Точки доступа	Перечень точек доступа НЕЙРОСС, которые будут «видимы» для ВИС и разрешены для транзакций доступа, инициируемых из ВИС. Количество точек доступа ограничивается параметрами лицензии. При выборе количества, превышающего значение в поле «Максимальное количество точек доступа ВИС», вы получите сообщение об ошибке.
Текущее количество владельцев пропусков ВИС	Количество владельцев пропусков, в режиме доступа которых задан хотя бы один уровень доступа ВИС. Владельцы и пропуска ВИС могут создаваться и изменяться как из ВИС, так и напрямую в АРМ НЕЙРОСС Доступ. Удаление владельцев и пропусков доступно только из сети НЕЙРОСС.

Перезагрузите Платформу НЕЙРОСС.

Перезапуск требуется, если изменяли значение таймаута ожидания транзакции доступа, и в некоторых других случаях.

Описание интеграционного HTTP-API

Для передачи запроса и ответа используется формат JSON и соответствующий Content-Type: application/json.

Авторизация

Все запросы в рамках взаимодействия ВИС-НЕЙРОСС должны быть авторизованы.

Авторизация запроса осуществляется посредством HTTP-заголовка Authorization, в котором передаётся API-токен в следующем виде:

Autorization: Bearer TOKEN

Список УД ВИС

URL запроса:

GET /plugin/eis-pacs-integration/access-levels/

Тело ответа:

[
   {
      "uuid": String, // обязательно, сквозной идентификатор УД
      "name": String, // обязательно, название УД
      "accessPoints": List[String] // обязательно, массив идентификаторов ТД
   }
]

Запрос уровней доступа посредством расширения браузера Google Chrome — Talend API Tester. JSON с запросами может быть предоставлен.

Пример ответа:

[
   {
      "uuid": "820a1259-fbe0-4594-913e-4ab869e60b19",
      "name": "[И] КПП 2",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:6e71dce6-e1aa-4ff4-b213-55391c989b2c"
      ]
   },
   {
      "uuid": "3260b54b-03f9-48cc-8593-4387b9e867e6",
      "name": "[И] КПП 3",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba"
      ]
   },
   {
      "uuid": "3db2237d-04bc-4932-8d03-86d1677c020d",
      "name": "[И] КПП 4",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:1e1614f2-372a-402a-90ee-13fa3c5899fe"
      ]
   },
   {
      "uuid": "0dfb462d-d5c3-402d-9075-e726ea94bd49",
      "name": "[И] КПП 1",
      "accessPoints":[
      "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd"
      ]
   }
]

Полученные уникальные идентификаторы (UUID) уровней доступа ВИС должны использоваться при создании пропусков [Создание и изменение владельцев и пропусков ВИС].

Список ТД ВИС

URL запроса:

GET /plugin/eis-pacs-integration/access-points/

Тело ответа:

[
   {
      "token": String, // обязательно, сквозной идентификатор ТД
      "name": String // обязательно, название ТД
   }
]

Пример ответа:

[
   {
      "token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:987f1ea2-93c9-449f-b38f-5e20d7e8edcd",
      "name": "Точка доступа 0.1"
   },
   {
      "token": "uuid:fe53892b-2e0e-44a8-98e1-5de2795b289f:f5d4ba84-ab03-42e4-8e4d-2fc4e12de1ba",
      "name": "Точка доступа 2.1"
   }
]

Полученные уникальные идентификаторы (UUID) точек доступа ВИС должны использоваться при инициировании транзакции доступа [Инициирование транзакции доступа].

Количество владельцев пропусков ВИС

URL запроса:

GET /plugin/eis-pacs-integration/persons/count/

Тело ответа:

{
    "count": Long // обязательно, количество владельцев пропусков в подмножестве ВИС
}

Пример ответа:

{
      "count": 7
}

Список владельцев ВИС

URL запроса:

GET /plugin/eis-pacs-integration/persons/search/?limit=$LIMIT&offset=$OFFSET

Параметры запроса (могут отсутствовать):

$LIMIT – максимальное количество владельцев в выдаче. Значение по умолчанию 1000
$OFFSET – сдвиг владельцев в выдаче (для постраничной выдачи). Значение по умолчанию 0

Тело ответа:

[
   {
      "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
      "surname": String, // обязательно, фамилия сотрудника
      "name": String, // обязательно, имя сотрудника
      "patronymic": Option[String], // опционально, отчество сотрудника
      "phone": Option[String], // опционально, номер телефона
      "email": Option[String], // опционально, адрес электронной почты
      "accessLevels": Option[List[String]], // опционально, массив идентификаторов уровней доступа ВИС в формате UUID
      "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
      "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
      "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
      "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
         "anyKey": "anyValue"
      }
   }
]

Пример ответа:

[
   {
      "uuid": "21e10f5d-7af7-44ba-b1a3-d0b9cf429437",
      "surname": "Аспидов",
      "name": "Иван",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{
      "inactivity": "false",
      "Birthday": "1994-12-05"
      }
   },
   {
      "uuid": "022abfc4-3809-4ce3-bfc4-cbdb4a07f726",
      "surname": "Акимов",
      "name": "Сергей",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{
      "inactivity": "false",
      "Birthday": "1994-02-18"
      }
   },
   {
      "uuid": "54b9fa8c-4a36-4431-8f74-c6ad5897fb7f",
      "surname": "Петров",
      "name": "Петр",
      "patronymic": "Сергеевич",
      "accessLevels":[
      "0dfb462d-d5c3-402d-9075-e726ea94bd49"
      ],
      "passType": "REGULAR",
      "info":{"pacs:folder": "c84e7f59-d37a-4d09-9cf9-fab38b11221a", "neyross:automation:responsibleTelegramChatId": "1055492440", "inactivity": "false",…}
   },

]

Владельцы пропусков отсортированы по UUID.

В ответе выдаются только UUID УД ВИС.

Создание и изменение владельцев и пропусков ВИС

URL запроса:

POST /plugin/eis-pacs-integration/persons/upsert/

Тело запроса:

{
   "uuid": String, // обязательно, сквозной идентификатор владельца в формате UUID
   "surname": String, // обязательно, фамилия сотрудника
   "name": String, // обязательно, имя сотрудника
   "patronymic": Option[String], // опционально, отчество сотрудника
   "phone": Option[String], // опционально, номер телефона
   "email": Option[String], // опционально, адрес электронной почты
   "accessLevels": List[String], // обязательно, массив идентификаторов уровней доступа ВИС в формате UUID
   "passType": Option[String], // опционально, тип пропуска. Возможные значения: REGULAR - постоянный, TEMPORARY - временный, ONETIME - разовый. Если значение не указано - используется тип REGULAR
   "activation_date": Option[Long], // опционально, дата начала действия пропуска в формате Unix timestamp (в секундах)
   "expiration_date": Option[Long], // опционально, дата окончания действия пропуска в формате Unix timestamp (в секундах)
   "info": { // опционально, произвольные данные о сотруднике в формате "ключ-значение"
      "anyKey": "anyValue"
   },
   "photo": Option[String] // опционально, фото сотрудника в формате BASE64. Если не передано - создаётся владелец без фотографии \ не изменяется сохранённая ранее фотография
}

Тело ответа:

{
    "result": String, // обязательно, возможные значения: "success" - владелец создан \ обновлён, "error" - возникли ошибки
    "error": Option[String] // обязательно для result == error, текстовое пояснение ошибки
}

Поле accessLevels в запросе не может быть пустым и должно содержать один или несколько UUID УД ВИС.

Изменять можно только тех владельцев пропусков, у которых на момент перед получением запроса в БД НЕЙРОСС уже есть хотя бы один УД ВИС.

В случае, если у владельца пропуска на момент изменения имеются и УД ВИС, и прочие УД, то алгоритм формирования итогового списка УД для владельца следующий:

Старые УД ВИС удаляются из пропуска.
Переданные УД ВИС устанавливаются в пропуск.
Прочие УД (не ВИС) остаются в пропуске без изменений.

При изменении владельца и пропуска из ВИС в БД НЕЙРОСС у него могут быть дополнительные поля (в частности, номера карт). Они останутся без изменений.

При создании новых владельцев и пропусков они размещаются в папке НЕЙРОСС Все. Администратор НЕЙРОСС, при необходимости, может поменять папку размещения.

Инициирование транзакции доступа

URL запроса:

POST /plugin/eis-pacs-integration/pacs-transaction/

Тело запроса:

{
   "person": String, // обязательно, идентификатор владельца пропуска, осуществляющего доступ
   "accessPoint": String // обязательно, идентификатор ТД, через которую осуществляется доступ
}

Тело ответа:

{
   "result": String, // обязательно, результат транзакции. Возможные значения: success - проход совершён, error - проход не совершён, нет прав на ТД и т. п.
   "meta": { // обязательно, метаданные о транзакции
     "person": String,
     "accessPoint": String,
     "transactionBegin": String, // дата и время старта транзакции в формате ISO (UTC). Пример: 2020-07-10 15:00:00
     "transactionEnd": String // дата и время окончания транзакции
   },
   "error": Option[String] // обязательно при result == error. Текстовое описание ошибки
}

Ответ с result == success возвращается по факту получения события «Проход совершён» от контроллера доступа.

Ответ с result == error возвращается в следующих случаях:

Не найден владелец или ТД, либо они не находятся в подмножестве ВИС.
В уровне доступа владельца нет прав на переданную ТД ВИС.
Не удалось отправить запрос на контроллер (сетевые проблемы и т. п.)
Получено событие о запрете доступа от контроллера в результате детальной проверки прав (просрочен пропуск и т. п.).

Если в течение заданного таймаута ожидания транзакции доступа не удалось получить информацию о решении контроллера (не дошло событие), транзакция также завершается с ошибкой.

Работа с событиями доступа ВИС

Плагин НЕЙРОСС ВИС позволяет внешней системе осуществлять подписку на получение событий доступа, связанных с пропусками ВИС, асинхронно получать их в реальном времени и инициировать процедуру «довычитывания» пропущенных событий (например, за период отсутствия связи).

События доступа ВИС – это такие события доступа, которые удовлетворяют следующим критериям:

Событие отправлено от точки доступа ВИС;
Событие связано с владельцем пропуска ВИС.

«Внешняя» информационная система может оформить подписку на Платформу НЕЙРОСС, указав URL, на который Платформа будет посылать все события доступа ВИС. Данная функция может быть использована «внешней» системой для самостоятельного формирования данных по учёту рабочего времени.

Подписки на события в реальном времени

Оформление подписки

URL запроса:

POST /plugin/eis-pacs-integration/events/subscriptions

Тело запроса:

{
     "consumerReference": String // обязательно, полный URL-адрес получателя событий, например: https://webhook.site/2a8f447d-d0ed-40c2-a6ae-d8c1a41e09f0
}

Тело ответа:

{
    "subscriptionId": String // обязательно, уникальный строковый идентификатор подписки
}

Удаление подписки

URL запроса:

DELETE /plugin/eis-pacs-integration/events/subscriptions/:subscriptionId

Получение событий

При получении события доступа, связанного с пропуском ВИС, оно пересылается в реальном времени на URL-адрес каждой подписки посредством HTTP-запроса с методом POST. Запрос имеет заголовок Content-Type: application/json и тело в следующем формате:

{
     "eventId": Long // обязательно, id события ВИС
     "headline": String, // обязательно, текстовое описание события
     "person": String, // обязательно, идентификатор владельца пропуска ВИС
     "eventTags": List[String], // обязательно, метки событий
     "sent": String, // обязательно, время отправки события с контроллера, дата и время в ISO 8601
     "registered": String // обязательно, время получения события Платформой НЕЙРОСС, дата и время в ISO 8601
}

Пример отправляемого события:

{
    "eventId": 21,
    "headline": "Доступ разрешен",
    "person": "54b9fa8c-4a36-4431-8f74-c6ad5897fb7f",
    "eventTags": [
        "PACS",
        "AccessGranted"
    ],
    "sent": "2024-06-15T08:34:19+03:00",
    "registered": "2024-06-15T08:34:19+03:00"
}

Поле eventId содержит последовательно возрастающее уникальное число, такое, что каждое последующее событие имеет eventId больше предыдущего. Анализ данного поля может быть использован «внешней» системой для детектированиz пропущенных событий.

Поле eventTags содержит массив меток — строк, определяющих тип и семантику события. В общем случае метки могут быть любые, для типовых сценариев учёта рабочего времени необходимо понимать смысл следующих меток:

AccessGranted – доступ разрешён
AccessDenied – доступ запрещён

Сетевой таймаут ожидания ответа от подписчика равен 10 секундам, может быть изменён в конфигурационном файле.

После регистрации события от пропуска ВИС оно остаётся «событием ВИС» навсегда, даже в случае, если администратор изменит настройки УД ВИС таким образом, что пропуск, с которым связано событие, перестанет быть пропуском ВИС. Аналогичным образом, уже полученное событие от не-ВИС пропуска не может стать «видимым» для ВИС, даже при назначении пропуску УД ВИС.

Вычитывание исторических событий

«Внешняя» информационная система может инициативно выполнить процедуру вычитывания архивных событий ВИС из Платформы с различными параметрами. Типовые сценарии использования данной функции:

Вычитывание событий ВИС, которые были зарегистрированы до момента оформления подписки на «живые» события;
Детектирование «внешней» системой пропущенных «живых» событий и их довычитывание.

Получение исторического события по конкретному eventId

URL запроса:

GET /plugin/eis-pacs-integration/events/history_events_by_id/?id=:eventId

В ответ отправляется событие по данному eventId, если оно есть (формат см. выше).

Получение исторических событий по нескольким eventId

URL запроса:

POST /plugin/eis-pacs-integration/events/history_events_by_ids/

Тело запроса:

{
    "eventIds": List[Long] // обязательно, массив eventId
}

В ответ отправляется массив событий по данным eventIds

Получение исторических событий за указанный промежуток времени

URL запроса:

POST /plugin/eis-pacs-integration/events/history_events_by_date_time/

Тело запроса:

{
    "timeFrom": String, // обязательно, дата и время начала поиска в формате ISO 8601
    "timeTo": String, // обязательно, дата и время конца поиска в формате ISO 8601
    "limit": Option[Long], // опционально, максимальное количество возвращаемых событий. Значение по умолчанию 1000
    "offset": Option[Long] // опционально, сдвиг для постраничного поиска. Значение по умолчанию 0
}

В ответ отправляется массив событий для указанных параметров.

Быстрые ссылки

Дерево страниц

Общие сведения

Лицензирование

Подготовка к настройке

Настройка плагина интеграции

Добавление плагина

Настройка плагина

Описание интеграционного HTTP-API

Авторизация

Список УД ВИС

Список ТД ВИС

Количество владельцев пропусков ВИС

Список владельцев ВИС

Создание и изменение владельцев и пропусков ВИС

Инициирование транзакции доступа

Работа с событиями доступа ВИС

Подписки на события в реальном времени

Получение событий

Вычитывание исторических событий