Назначение сервиса и автоматизированный процесс

Сервис управления подпиской и оповещением об изменениях справочной информации (далее СПО) обеспечивает процесс управления подписками на изменения справочной информации клиентами и оператором сервиса, а также автоматическую рассылку сообщений-уведомлений по средствам SOCKET API, E-mail и telegram.

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

Термины и определения


Термин

Определение

Подписчик

Пользователь или сторонняя ИС с базовыми параметрами подписки, имеющая учетную запись в сервисе НСИ.

Подписка

Совокупность всех данных подписки одного подписчика.

Единица подписки

Параметры подписки одного подписчика на один справочник.

Событие нотификации

Инициируемое извне событие, стартующее процесс оповещения.

Итерация оповещения

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

Данные оповещения

Содержание сообщения оповещения об изменениях справочных данных справочника.

Авторизация при работе с СПО

Для управления данными подписчика и его подписок используется REST-сервис.

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

  • ФИО, информационная система;
  • контактный телефон;
  • электронная почта;
  • цель доступа к сервису нотификации;
  • guid-токен к сервису НСИ при наличии.

Сценарии взаимодействия с СПО

Последовательность действий для подписки на оповещения об изменениях справочной информации:

  1. Зарегистрироваться в системе НСИ для работы с СПО: получить авторизационный токен (см. «Авторизация при работе с сервисом»).
  2. Создать подписчика в системе: задать параметры взаимодействия сервиса с подписчиком.
  3. Создать подписку на справочники, по которым необходимо получать оповещения.
  4. Протестировать взаимодействие с сервисом.

Управление подписчиками СПО

Информационный объект «Подписчик»


Параметр

Наименование параметра

Обязательность

Тип

Описание

code

Код

Обязательный

Текстовый атрибут

GUID пользователя

display

Наименование

Обязательный

Текстовый атрибут

Наименование подписчика: ФИО, название ИС

descr

Описание

Не обязательный

Текстовый атрибут

Дополнительная информация о подписчике

contact

Контактная информация

Не обязательный

Текстовый атрибут

Любая контактная информация: доп. Email, моб. телефон

endpoint_status

Активность API уведомления

Не обязательный

Логический

Вкл/выкл использования канала для уведомления:
true - уведомления по API высылаются;
false- уведомления по API не высылаются;

endpoint

Endpoint

Не обязательный

Текстовый атрибут

Endpoint, на который будут приходить оповещения об изменениях

email_status

Активность email уведомления

Не обязательный

Логический

Вкл/выкл использования канала для уведомления:
true - уведомления по email высылаются;
false- уведомления по email не высылаются;

email

Email

Не обязательный

Текстовый атрибут

E-mail адрес, на который будет осуществляться рассылка e-mail-оповещений

rabbit_status

Активность очереди Rabbit MQ

Не обязательный

Логический

Вкл/выкл использования канала для уведомления:
true - уведомления по Rabbit MQ высылаются;
false- уведомления по Rabbit MQ не высылаются;

telegram_status

Активность Telegram уведомления

Не обязательный

Логический

Вкл/выкл использования канала для уведомления:
true - уведомления по Telegram высылаются;
false- уведомления по Telegram не высылаются;

telegram_bot_token

Токен бота Telegram

Не обязательный

Текстовый атрибут

Ключ авторизации в канале Telegram, на который будет осуществляться рассылка оповещений

telegram_channel_identifier

Идентификатор канала Telegram

Не обязательный

Текстовый атрибут

Уникальный идентификатор, который принадлежит каналу Telegram

event_notification

Оповещение по событию

Не обязательный

Логический

Вкл/выкл уведомлений по событию:
true - оповещения об изменениях высылаются по событию изменения справочных данных с учетом заданного минимального периода оповещения

timetable_notification

Уведомление по расписанию

Не обязательный

Логический

Вкл/выкл уведомлений по расписанию:
true - оповещения об изменениях высылаются в рамках настроенного расписания рассылки

Создание подписчика

ПРИМЕЧАНИЕ: подписчик может быть создан и изменен оператором-администратором НСИ в соответствующем служебном справочнике «Подписчики».

Либо путем POST-запроса в СПО:

[base]/subscribers/

HEADERS: Authorization: авторизационный токен

BODY:

{
    "code": "3cd4a3a1-2bb4-48c5-8919-adc5a7090418",
    "display": "Васин Алексей",
    "descr": "Описание Подписчика",
    "contact": "+79111",
    "endpoint": "http://endpointhere1",
    "email": "email@email.com1",
    "endpoint_status": true,
    "email_status": true,
    "timetable_notification": true,
    "event_notification": true,
    "rabbit_status": true,
    "telegram_status": true,
    "telegram_bot_token": "1149250835:AAHXM",
    "telegram_channel_identifier": "-111166685932"
}


Ответ сервиса на выполняемый запрос:

  • Если подписчик был успешно создан, будет получен следующий ответ:

HTTP-статус: 201 Created

  • Если подписчик не был создан, так как ему не был присвоен авторизационный токен (GUID токен) в НСИ (см. пункт «Авторизация при работе с сервисом»), ответ будет следующим:

HTTP-статус: 500 Internal Server Error

Content-Type: text/plain; charset=utf-8

BODY: Нельзя создать подписчика, если он отсутствует в списке пользователей.

  • Если подписчик не был создан, так как у пользователя недостаточно прав для создания подписчика:

HTTP-статус: 401 Unauthorized

Примечание: нельзя создать подписчика, если в системе НСИ отсутствует соответствующая учетная запись.

Изменение параметров подписчика, в том числе деактивация подписчика

Изменению доступны все параметры подписчика. Для изменения данных подписчика необходимо выполнить запрос в примере п. 3.1.2 с актуальными данными подписчика.

Для деактивации подписчика, то есть отключение его от оповещений по email и endpoint (без удаления записей о его подписках на конкретные справочники), необходимо установить значение «false» для параметров endpoint_status и email_status.

Для изменения данных подписчика необходимо выполнить PUT-запрос по URL в формате:

[base]/subscribers/[GUID подписчика]

HEADERS: Authorization: авторизационный токен

BODY:

{
    "code": "3cd4a3a1-2bb4-48c5-8919-adc5a7090418",
    "display": "Васин Алексей",
    "descr": "Описание Подписчика",
    "contact": "+79111",
    "endpoint": "http://endpointhere1",
    "email": "email@email.com1",
    "endpoint_status": true,
    "email_status": true,
    "timetable_notification": true,
    "event_notification": true,
    "rabbit_status": false,
    "telegram_status": true,
    "telegram_bot_token": "1149250835:AAHXM",
    "telegram_channel_identifier": "-111166685932"
}


Ответ сервиса на выполняемый запрос:

  • Если подписчик был успешно изменен:

HTTP-статус: 200 OK

  • Если у пользователя нет прав на изменение данных о подписчике, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

  • Если пользователь пытается изменить несуществующего подписчика:

HTTP-статус: 500 Internal Server Error

Content-Type: text/plain; charset=utf-8

BODY: Подписчик не найден.

Получение информации о подписчике

Для получения текущих параметров подписчика необходимо выполнить GET-запрос по URL в формате:
[base]/nsinotification/api/subscribers/[GUID подписчика]

HEADERS: Authorization: авторизационный токен

Если подписчик был найден и у пользователя есть права на чтение данных о нем, будет получен следующий ответ:

{
    "code": "3cd4a3a1-2bb4-48c5-8919-adc5a7090418",
    "display": "Васин Алексей",
    "descr": "Описание Подписчика",
    "contact": "+79111",
    "endpoint": "http://endpointhere1",
    "email": "email@email.com1",
    "endpoint_status": true,
    "email_status": true,
    "timetable_notification": true,
    "event_notification": true,
    "rabbit_status": false,
    "telegram_status": true,
    "telegram_bot_token": "1149250835:AAHXM",
    "telegram_channel_identifier": "-111166685932"
}


Ответ сервиса на выполняемый запрос:

  • Если подписчик не найден, будет получен следующий ответ:

HTTP-статус: 404 Not Found

Content-Type: text/plain; charset=utf-8

BODY: Подписчик не найден.

  • Если у пользователя нет прав на чтение данных о подписчике, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

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

Для удаления информации о подписчике необходимо выполнить DELETE-запрос по URL в формате:
[base]/subscribers/[GUID подписчика]

HEADERS: Authorization: авторизационный токен

Ответ сервиса на выполняемый запрос:

  • Если подписчик был успешно удален:

HTTP- статус: 200 OK

  • Если у пользователя нет прав на удаление данных о подписчике, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

  • Если пользователь пытается удалить несуществующего подписчика, будет получен ответ:

HTTP-статус: 404 Not Found

Content-Type: text/plain; charset=utf-8

BODY: Подписчик не найден.

Управление подписками СПО

Информационный объект «Подписка»


Параметр

Наименование параметра

Обязательность

Тип

Описание

code

Код

Обязательный

Текстовый атрибут

Автогенерируемый код

display

Наименование

Обязательный

Текстовый атрибут

Наименование подписки

oid

OID справочника

Не обязательный

Текстовый атрибут

OID справочника, на изменения которого идет подписка

subscriber

Подписчик

Не обязательный

Ссылка на справочник notification_subscriber

Подписчик

send_delta_data

Полный список изменений

Не обязательный

Логический

Управление содержанием данных нотификации:

true - уведомление о факте изменения + статистика + информация по каждой измененной записи

false - уведомление о факте изменения + статистика

min_send_freq

Минимальный интервал между уведомлениями (мин)

Обязательный

Числовой атрибут

Период времени (в минутах) в течении которого в справочнике могут производиться изменения, но подписчику не будут формироваться оповещения об изменениях

dictionary_version_old

Младшая версия справочника

Не обязательный

Текстовый атрибут

Последняя младшая версия справочника относительно которой подписчику были высланы изменения справочника

error

Ошибка

Не обязательный

Текстовый атрибут

Расшифровка ошибки, если она возникла при попытке отправить уведомление об изменении справочника

last_successful_notif_date

Дата и время последней успешной нотификации

Не обязательный

Текстовый атрибут

Автогенерируемое поле

last_processing_date

Дата и время последней обработки

Не обязательный

Логический

Автогенерируемое поле

Создание и обновление подписки

ПРИМЕЧАНИЕ: подписки могут быть созданы и изменены оператором-администратором НСИ в соответствующем служебном справочнике «Подписки».

Создание и обновление подписок подписчика происходит типовым запросом. По переданному oid справочника, для которого предполагается создать подписку, сервис анализирует уже существующие подписки пользователя. Если для переданного oid уже существует подписка, происходит ее обновление, иначе – создается новая. 

Для создания или обновление подписки/подписок на справочники необходимо выполнить POST-запрос:

[base]/subscribers/[GUID подписчика]/subscriptions/

HEADERS: Authorization: авторизационный токен

BODY:

[
   {"display": "Подписка Васин Алексей ",
    "oid": "1.2.643.5.1.13.13.99.2.225",
    "subscriber": "3cd4a3a1-2bb4-48c5-8919-adc5a7090418",
    "min_send_freq": 4},
   {"display": "Подписка Васин Алексей ",
    "oid": "1.2.643.5.1.13.13.11.1359",
    "subscriber": "3cd4a3a1-2bb4-48c5-8919-adc5a7090418",
    "min_send_freq": 0}
]

Ответ сервиса на выполняемый запрос:

  • Пользователь в ответ получает информацию по созданию/обновлению подписки

HTTP-статус: 200 OK

Content-Type: application/json; charset=utf-8

BODY:

[
   {"oid": "1.2.643.5.1.13.13.99.2.225",
    "result": true,
    "error": ""},
   {"oid": "1.2.643.5.1.13.13.11.1359",
    "result": false,
    "error": "Справочник с oid 1.2.643.5.1.13.13.11.1359 не найден среди доступных подписчику 3cd4a3a1-2bb4-48c5-8919-adc5a7090418. Справочник отсутствует или нет прав на доступ к указанному справочнику."}
]
  • Если у пользователя нет прав на создание/обновление подписки, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

Получение списка справочников, доступных для подписки

Для получения списка доступных к оформлению подписки справочников необходимо выполнить GET-запрос по URL в формате:
[base]/nsinotification/api/dictionaries

HEADERS: Authorization: авторизационный токен

Ответ сервиса на выполняемый запрос:

HTTP-статус: 200 OK

BODY:

[{
                "uri": ["1.2.643.5.1.13.2.1.1.773"],
                "guid": "84c82899-ef00-4f11-9634-cd8c86c6502e",
                "name": "Ведомственая принадлежность в Российской Федерации",
                "versioning": 0,
                "has_hierarchy": true,
                "id_dictionary": 293,
                "dictionary_type": 0,
                "dictionary_group": [0]
},
…
{
                "uri": ["1.2.643.5.1.13.2.1.1.736"],
                "guid": "bb11f504-e49c-43c9-8b3b-6894acc6b6c6",
                "name": "Документы, удостоверяющие личность",
                "versioning": 1,
                "has_hierarchy": false,
                "id_dictionary": 120,
                "dictionary_type": 0,
                "dictionary_group": [3]
}]


, где:

  • uri – массив публичных OID-ов справочника (основной и дополнительные)
  • name – наименование справочника
  • versioning – версионирование справочника (0 – двухуровневое, 1 – одноуровневое, 2 – не ведется)
  • Если у пользователя нет прав на получение списка справочников, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

Получение данных подписки

Для получения данных подписки подписчика на конкретный справочник (OID) необходимо выполнить GET-запрос по URL в формате:
[base]/subscribers/[GUID подписчика]/subscriptions/[OID справочника]

HEADERS: Authorization: авторизационный токен

Для получения данных о всех подписках подписчика необходимо выполнить GET-запрос по URL в формате:

[base]/subscribers/ [GUID подписчика]/subscriptions/

HEADERS: Authorization: авторизационный токен

Ответ сервиса на выполняемый запрос:

  • Информация о подписке на конкретный справочник, либо массив подписок (в зависимости от выполняемого запроса)

HTTP-статус: 200 OK

Content-Type: application/json; charset=utf-8

BODY:

[
   {"code": "5052ec58-78bf-496e-8148-6ee5518756a6",
    "display": "Подписка Васин Алексей",
    "oid": "1.2.643.5.1.13.13.99.2.225",
    "subscriber": "Васин Алексей",
    "send_delta_data_in_notification": "true",  
    "min_send_freq": 0,
    "dic_version_old": "1.34",
    "error": null,
    "date_of_last_successful_notification": "2022-06-03 18:03:24",
    "date_of_last_processing": "2022-06-03 18:03:24"},
   {"code": "d91ff902-9166-4cd0-b24a-2afcfb2fc429",
    "display": "Подписка Васин Алексей",
    "oid": "1.2.643.5.1.13.13.11.1359",
    "subscriber": "Васин Алексей",
    "send_delta_data_in_notification": "true",  
    "min_send_freq": 5,
    "dic_version_old": "84",
    "error": null,
    "date_of_last_successful_notification": "2022-05-30 18:57:43",
    "date_of_last_processing": "2022-05-30 18:57:43"}
]
  • Если у подписчика нет прав на получение данных о подписке, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

  • Если подписчик запрашивает несуществующую подписку, будет получен следующий ответ:

HTTP-статус: 404 Not Found

Content-Type: text/plain; charset=utf-8

BODY: Подписки не найдены.

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

Для удаления существующей подписки необходимо выполнить DELETE-запрос по URL в формате:
[base]/subscribers/ [GUID подписчика]/subscriptions/[OID справочника]

HEADERS: Authorization: авторизационный токен

Ответ сервиса на выполняемый запрос:

  • Если подписка была успешно удалена, будет получен следующий ответ:

HTTP-статус: 200 OK

  • Если подписчик пытается удалить несуществующую подписку, будет получен следующий ответ:

HTTP-статус: 404 Not Found

  • Если у пользователя нет прав на получение удаление подписки, будет получен следующий ответ:

HTTP-статус: 401 Unauthorized

Формат SOCKET оповещения: получение и обработка

Для получения нотификаций по средствам Rabbit MQ требуется:
  1. В справочнике OID notification_subscriber для атрибута «Активность очереди Rabbit MQ» присвоить значение «true».
  2. Использовать запрос следующего формата в консольном приложении:
let socket = new WebSocket("ws://[base]/nsinotification/DictionaryChange?subscriberId=[GUID подписчика]");

Описание параметров данных нотификации:

№

Контейнер

Параметр

Тип

Описание

1.

Root




2.

/entry


array

Блок данных с изменением версий

3.

entry/resource


object

Блок данных

4.

resource/parameter


array

Массив параметров блока данных

5.

parameter

name

string

Имя параметра «system»

6.

parameter

valueString

string

url справочника

7.

parameter

name

string

Имя параметра «version_old»

8.

parameter

valueString

string

Значение младшей версии справочника

9.

parameter

name

string

Имя параметра «version_new»

10.

parameter

valueString

string

Значение старшей версии справочника


Пример структуры нотификации:

Data received from server: {
    "oid": "1.2.643.5.1.13.13.11.1359",
    "version_old": "95",
    "version_new": "96",
    "serialized_bundle": {
        "resourceType": "Bundle",
        "type": "searchset",
        "entry": [{
                "resource": {
                    "resourceType": "Parameters",
                    "parameter": [
                        {   "name": "system",
                            "valueString": "urn:oid:1.2.643.5.1.13.13.11.1359"},
                        {   "name": "version_old",
                            "valueString": "95"},
                        {   "name": "version_new",
                            "valueString": "96"}]},
                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "created"},
                            {   "name": "CODE",
                                "valueString": "741"},
                            {   "name": "code",
                                "valueString": "741"},
                            {   "name": "display",
                                "valueString": "Аортокоронарное шунтирование"}],
                        "resourceType": "Parameters"}},
                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "updated"},
                            {   "name": "CODE",
                                "valueString": "7421"},
                            {   "name": "code",
                                "valueString": "7421"},
                            {   "name": "display",
                                "valueString": "Ангиопластика коронарных артерий"}],
                        "resourceType": "Parameters"}},
                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "delete"},
                            {   "name": "CODE",
                                "valueString": "912020"},
                            {   "name": "code",
                                "valueString": "912020"},
                            {   "name": "display",
                                "valueString": "Стентирование"}],
                        "resourceType": "Parameters"}}}]}}


Сообщение содержит данные нотификации в JSON-формате. Данные нотификации содержат уведомление об изменении версий справочника.

Блок уведомления об изменении справочника содержит информацию с OID-ом справочника, старой и новой версией:


    "oid": "1.2.643.5.1.13.13.11.1359",
    "version_old": "95",
    "version_new": "96",
    "serialized_bundle": {
        "resourceType": "Bundle",
        "type": "searchset",
        "entry": [{
                "resource": {
                    "resourceType": "Parameters",
                    "parameter": [
                        {   "name": "system",
                            "valueString": "urn:oid:1.2.643.5.1.13.13.11.1359"},

                        {   "name": "version_old",
                            "valueString": "95"},
                        {   "name": "version_new",
                            "valueString": "96"}]}


Блок дельта-данных содержит информацию по изменениям записей справочника:


                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "created"},
                            {   "name": "CODE",
                                "valueString": "741"},
                            {   "name": "code",
                                "valueString": "741"},
                            {   "name": "display",
                                "valueString": "Аортокоронарное шунтирование"}],
                        "resourceType": "Parameters"}},
                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "updated"},
                            {   "name": "CODE",
                                "valueString": "7421"},
                            {   "name": "code",
                                "valueString": "7421"},
                            {   "name": "display",
                                "valueString": "Ангиопластика коронарных артерий"}],
                        "resourceType": "Parameters"}},
                {
                    "resource": {
                        "parameter": [
                            {   "name": "operation",
                                "valueString": "delete"},
                            {   "name": "CODE",
                                "valueString": "912020"},
                            {   "name": "code",
                                "valueString": "912020"},
                            {   "name": "display",
                                "valueString": "Стентирование"}],
                        "resourceType": "Parameters"}}}]}}

Наверх