Cursor

Описание команд всех сервисов, которые входят в состав Cursor.

Список версий

v1.8

Важные изменения

• Актуализирован Storybook (CURS-153)

• Исправлено множество багов в компонентах UI

• Data-model

  • В объект GetObjectLinksList добавить указание типа сущности, с которой нужно искать связь объекта (CURS-77)
    

v1.7.1

Важные изменения

• Data-model
  • Реализован Soft delete объектов модели данных (CURS-154, SUP-18)

v1.7

Важные изменения

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

• Data-model

  • Добавлен различный функционал связанный с хранением "Ключевых слов"

v1.6.1

Важные изменения

• Различные сервисы

  • Добавлена возможность разделить учётные данные кафки для доступов producer и consumer (SUP-132, CURS-2307)
  • Реализованы доработки позволяющие работать в системе без развернутого authzforce

• AppUi

  • Возможность завершить сеанс пользователя (SUP-135, CURS-2342)

v1.6

Важные изменения

• Full-text-search

  • В обработку команды fullTextSearchDSLV2 добавлен вариант поиска по строгой фразе (CURS-2146)
  • При поиске в поле с типом keyword теперь применяется WildcardQuery (CURS-2222)

• Indexation

  • Добавлен прототип поддержка OCR в индексации (шаг Erika) (CURS-2236)

• UI

  • Реализована вкладка "Виджеты" (CURS-1054)
  • Angular обновлен до 16 версии в Cursor в webclients, graph, ui-plugins и vespa (CURS-1124)
  • Добавлены кастомные типы связи в элемент "Таблица пересечений" (CURS-2204) и в документоцентричный граф (CURS-2218)
  • Добавлена поисковая строка в реестры (CURS-2205)
  • Установка по умолчанию типа поиска по тексту "Строгая фраза" (CURS-2255)

• Добавлены логи в формате CEF в сервисы Cursor/Verdi (CURS-36)

• В Slate внесены множественные изменения и исправления

• Полный список задач релиза зафиксирован в Confluence

v1.5.3

• service-common

  • Убрана зависимость от fs-client (SUP-66)

• Tolka

  • Исправлено: Не работает сортировка по умолчанию по проценту пересечений (CUR-2025)

• В нескольких сервисах выставлено дефолтное значение allowInternalCommands=true (SUP-77)

v1.5.2

Версия от 04.07.2023. Список изменений:

• DataModel:
  • Исправлен HealthCheck роут (SUP-48)

v1.5.1

Версия от 27.06.2023. Список изменений:

• AppUI
  • Исправлено: В поиске с исп. документа не работает фильтр по проценту содержательных пересечений

v1.5

Версия от 06.06.2023. Список изменений:

• Общее

  • Исправлена и дополнена документация в различных разделах Cursor
  • Исправлены различные баги в рамках исправлений по 9 этапу

• DataModel:

  • Добавлен фильтр RangeQuery по полям сущности (SUP-57)
  • Исправлено: при указании фильтра по полю created - фильтрация работает некорректно если указана комбинация фильтров

• DataModelClient:

  • Добавлена команда listFilesInfoWithTags (SUP-14)

• UI

  • Исправлено: Некорректно работает компонент ввода даты из двух полей
  • Исправлено: На странице настройки стартового экрана при нажатии отмены не сбрасываются изменения настроек
  • Исправлено: Различается отображение длинных текстовых/ссылочных наименований/ID в таблицах системы

• Indexation (+DataModel)

  • Добавлена постраничная обработка файлов при индексации сущностей

• Tolka

  • Создан сервис аналитики
  • Виджеты (хранение, вычисление данных)
  • Настройки порогов
  • Страница аналитики (виджеты и поисковая выдача) в appui (проект @corund/analytics)

v1.4.1

Версия от 03.05.2023. Список изменений:

• Appui

  • Исправлено:
  • В поиске с использованием документа напротив сниппетов не отображается процент пересечения

• Integration:

  • Добавлен http-route для проверки жизни сервиса с помощью ServiceHealthApi

• UI-Storage:

  • Добавлен http-route для проверки жизни сервиса с помощью ServiceHealthApi

• Marker-Service

  • Добавлен http-route для проверки жизни сервиса с помощью ServiceHealthApi

v1.4

Версия от 22.03.2023. Список изменений:

• Integration:
  • Доработано внешнее API для работы с отношениями
• Full-text-search:
  • Доработана обработка ошибок при неверном формате входных данных
  • Исправлена документация
  • Добавлена авторизация на все команды сервиса с публикацией всех нужных констант
  • Добавлена поддержка числовых фасетов во всех видах поиска в поле numberFacets
• DataModel:
  • Доработана обработка ошибок при неверном формате входных данных у команд для работы с тегами файлов, getFile, deleteObject
  • В команды listObjects и richListObjects добавлена сортировка по created
  • В командах, работающих по externalId для отношений возвращаются также externalId, а не внутренние id
  • Добавлена команда установки новых отношений по externalId
  • Исправлены ошибки команд для получения списков объектов
  • Служебные поля (id, entityType, created, и т.д.) теперь передаются с подчеркиванием в начале (_id, _entityType, _created, и т.д.) в результатах RichGet команд
  • Исправлена фильтрация по id файла в командах ListFilesInfoWithTags и ListTagsWithFilesCount
  • Добавлены команды для удаления нескольких объектов DeleteObjectBatch и DeleteObjectSearch
  • Добавлена генерация событий при удалении/изменении файлов у объектов
  • Исправлены ошибки сортировки команды richListObjects
• Indexation:
  • Исправлена ошибка, из-за которой не удалялись шаги удаленных индексаций
  • Добавлено удаление данных из LAMP при получении события об удалении файлов у объекта
• UI-Storage:
  • Добавлена публикация авторизационных констант в сервисе Attila

Общие типы данных

Search

Search - универсальный тип параметров списочного запроса. Он состоит из полей

Sorting

Sorting - параметры сортировки

Paging

Paging - параметры пейджинга

Page

Страница списка элементов (часть списка с примененным пейджингом)

PositionInList

Позиция объекта в списке

EntityObjectIdentity

EntityTypeId

Соответствует типу UUID.

ObjectId

Соответствует типу UUID.

Типы данных из verdi-libs

Описание типов данных дублирует документацию из Verdi. Добавлено для более удобной навигации.

CommandStatus

Описывает статус выполнения команды.

ErrorResponse

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

ErrorResponseCode

Код обозначающий тип ошибки в ответе.

FSConfigRep (FSClient)

Отображение FSConfig в "плоской форме", как он выглядит в конфиге приложения application.conf.

FSConfig (FSClient)

Конфигурация клиента файлового хранилища.

FSBucketConfig (FSClient)

Данные для аутентификации, которые привязаны к конкретному бакету.

FSCredentials (FSClient)

Данные для аутентификации.

VerdiCacheConfig (Verdi-cache)

Настройки кеширования

KafkaAuthConfig (senderlib)

Параметры для авторизации kafka-клиента (доступ к топикам).

TrustStoreConfig (senderlib)

Параметры для хранилища сертификатов (Java key store)

KafkaAuthSettings (senderlib)

Параметры для авторизации kafka-клиента (доступ к топикам).

RetrySettings (senderlib)

Настойки для повтороного вызова функций

CommandResultRetryConditionKind (senderlib)

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

Функционал фильтров и сортировки

Для некоторых команд можно передавать параметры запроса в виде объекта Search, который содержит информацию о том как нужно отфильтровать, отсортировать запрос и как разделить его на страницы.

Фильтрация

  {
     "query": "count && (created || modified)",
     "context": {
       "count": "1_1000",
       "created": "1630326000_",
       "modified": "_1630327000"
     }
   }

Фильтрация состоит из двух полей:

• query описывает условие для фильтрации с использованием названий полей
• context описывает значение для полей, указанных в query

Query поддерживает операторы && и || + скобки.
В Context-е можно описать несколько видов проверок для полей:

1) Условие равенства переданному значению.
{ "context": { "fieldName": "какое-то значение" } }

2) Условие равенства какому-то одному значению из предоставленного списка.
{ "context": { "fieldName": "[первое значение, второе, другое]" } } или { "context": { "fieldName": "any[первое значение, второе, другое]" } }

3) Условие наличия всех значений из предоставленного списка в массиве всех значений objectFieldName, которые присутствуют в объектах поля arrayFieldName. Работает только для полей arrayFieldName, содержащих массив. Предоставленный в запросе список должен содержать не менее двух значений.
{ "context": { "arrayFieldName.objectFieldName": "all[первое значение, второе, другое]" } }

4) Условие соответствия паттерну
Значение поля обязательно должно начинаться со слова like.
{ "context": { "fieldName": "like какое%значен__" } }

5) Условие вхождения значения в заданный диапазон. В данный момент, поддерживаются только целые числа. Начало и конец диапазона разделяются знаком _. Оба конца диапазона опциональны и они включаются в диапазон. Если передать просто _, то результатом будет пустой диапазон, в который не входит ни один элемент и ответ тоже будет пустой.

6) Условие текствого поиска PGSQL
Значение поля обязательно должно начинаться со слова ts.
{ "context": { "fieldName": "ts (this | that) & the:*" } }

Сортировка

{
  "sorting": {
    "fieldName": "number",
    "order": "desc"
  }
}

Сортировка определяется двумя полями:

• fieldName название поля, по которому будет производиться сортировка
• order направление сортировки. Бывает двух видов: asc, desc.

Адаптер сетевой папки

Основное

Адаптер сетевой папки позволяет экспортировать в Cursor все содержимое указанной папки и в дальнейшем синхронизировать состояние (удалять из Cursor удаленные из папки файлы, доэкспортировать новые и обновлять измененные).

Экспорт осуществляется в виде Cursor-объекта указанного в конфигурации вида, который должен содержать обязательное поле бинарного файла (тип file), а также может содержать часть (или все) из нижеперечисленных полей:

• Наименование файла (string/text)
• Путь до файла относительно корня папки (string/text)
• Владелец файла в файловой системе (string/text)
• Дата создания файла (dateTime)
• Дата редактирования файла (dateTime)

Поддерживаются:

• локальные папки
• протокол сетевых папок SMB

Экспорт происходит при старте адаптера, и далее перезапускается через указанный промежуток времени. Кроме того, адаптер предоставляет HTTP API для вызова внепланового экспорта и восстановления.

Конфигурирование адаптера сетевой папки

Требования к запуску адаптера сетевой папки

Для корректной минимальной работы адаптера требуется:

• Развернутый стенд Cursor, включая:
  • Доступ из адаптера к HTTP API интеграций Cursor (например https://cursorapp/integration/api/external)
  • Настроенная модель данных (см. шапку документации).
  • Зарегистрированный клиент адаптера, имеющий доступ к настроенной модели данных.
• Доступ из адаптера к папке, из которой будут выгружаться файлы
• Подключение к PostgreSQL для хранения состояния выгрузки (см. соответствующий раздел)

Список переменных окружения адаптера сетевой папки

Обязательные параметры выделены жирным

Настройки PostgreSQL:

Настройки адаптера:

Настройки рабочей папки:

Настройки обработки файлов:

Общие настройки взаимодействия с Cursor:

Настройки модели данных файла и взаимодействия с Cursor по данной модели (если код какого-либо поля не указан, и настройка этого кода является необязательной, поле не используется в объекте):

Формат ADAPTER_FOLDER_SOURCE_URI

Для локальных папок используется формат File URI. Примеры:

• file:///C:/users/ivanov%20ivan/dir/ в Windows
• file:///home/ivanov%20ivan/dir в Linux

Для папок, доступных по протоколу сетевых папок SMB, используется следующий формат: smb://server[:port]/share/[path/]. Примеры:

• smb://127.0.0.1/MyShare - все файлы конкретного share
• smb://127.0.0.1/MyShare/my%20directory/ - все файлы внутри определенной папки

Версии SMB

При использовании протокола SMB, из-за разницы между используемыми клиентом и сервером версий протокола, может возникнуть ошибка подключения.
Переменные ADAPTER_FOLDER_SOURCE_SMB_MIN_VER (по умолчанию SMB1) и ADAPTER_FOLDER_SOURCE_SMB_MAX_VER (по умолчанию SMB2.1) позволяют изменить используемые версии протокола на стороне клиента. Поддерживаемые значения: SMB1, SMB202, SMB210, SMB300, SMB302, SMB311

Состояние и восстановление состояния

В целях оптимизации количества сетевых запросов, адаптер хранит текущее состояние экспорта по каждому из файлов в базе данных.
В случаях сбоев (отсутствия соединения с БД, неожиданный перезапуск адаптера, потери данных БД или хранилища временных файлов и пр.) состояние иногда может перестать соответствовать действительности, что, в свою очередь, может значительно замедлить последующий экспорт и/или привести к артефактам синхронизации (когда удаленный из рабочей папки файл не будет удален из Cursor автоматически).

Для восстановления состояния при перезапуске используется "режим восстановления". Если переменная ADAPTER_FOLDER_RECOVER_ON_START будет указана как true, то при запуске адаптера сначала (единоразово) будет выполнена синхронизация состояния файлов с Cursor, и только потом запущен плановый экспорт.
Кроме того, режим восстановления может быть запущен в любой момент (когда адаптер не выполняет других задач).

Внеплановый запуск

Адаптер предоставляет HTTP API для внепланового запуска задач (при условии, что в данный момент адаптер не занят другой задачей):

• POST /export - запуск экспорта
• POST /recover - запуск режима восстановления
  

Хост и порт сервера API указываются в конфигурации (см. выше).

Каждый запрос может либо вернуть 423 Locked, если адаптер сейчас занят другой задачей, либо запустить задачу и сразу вернуть 202 Accepted.

Сервис ограниченных контекстов - ОК

В сервисе реализованы следующие команды

• Агрегирующий поиск в ограниченном контексте
• Поиск по ветке куста ограниченного контексте
• Создание ограниченного контекста
• Получение ограниченного контекста
• Получение списка ограниченных контекстов
• Удаление ограниченного контекста
• Обновление ограниченного контекста

Общее описание архитектуры сервиса ОК

Конфигурирование сервиса ОК

Требование к запуску сервиса ОК

Запуск сервиса осуществляется локально через sbt, на стенде в docker на jvm. Для корректной минимальной работы сервиса требуется обязательное подключение к Kafka, Consul, PostrgeSQL. Для нормальной работы сервису дополнительно требуется окружение Verdi: CommandStatus и ApiGateway.

Список переменных окружения сервиса ОК

Формат CEF для логов сервиса Bush

У логов есть возможность включить формат CEF для логирования по следующему шаблону:
2022-12-14T16:56:31+0500 CEF:Version|Device Vendor|Device Product|Device Version|EventClassId|Message|Severity|src=? dst=? shost=? suid=? suser=? msg=? end=currentTimeMillis|.

Чтобы включить логирование в формате CEF, нужно задать переменную LOG_OUTPUT = STDOUT_CEF. Если логи пишутся в формате CEF, то необходимо задать следующие переменные, которые по умолчанию не заданы:

• LOGGING_SRC_IP, для параметра src в логах
• LOGGING_SRC_HOST, для параметра shost в логах
• LOGGING_DST_IP, для параметра dst в логах

В файле src/main/resources/log4j.xml можно поменять class path для основного класса приложения (переменная projectMainClassPath), если это необходимо.

Модель сервиса ОК

Bush

Ограниченный контекст

BushcraftSearchRequest

Форма агрегирующего поиска в ограниченном контексте

EntityObjectIdentity

Полный идентификатор объекта

BranchUnfoldRequest

Форма агрегирующего поиска в отдельной ветке ограниченного контекста

BushCreateDTO

Форма создание ограниченного контекста

Команды сервиса ОК

bushSearch

Агрегирующий поиск в ограниченном контексте

На входе поисковый запрос

{
    "query": "электроконтактная",
    "paging": {
        "page": 1,
        "count": 40
    },
    "bushId": "fixedBush"
}

В результате куст объектов

{
  "status": "Completed",
  "timestamp": 1651387723970,
  "value": {
    "documents": [
      {
        "document": {
          "id": "508d1853-1648-4558-a9f9-e590876018b4",
          "entityType": "links",
          "highlight": {},
          "data": ... // doc data
        },
        "matchedChildren": {
          "Patent": 2
        }
      },
      {
        "document": {
          "id": "eaeda9a3-5454-4cc0-902a-a7f854a2bd96",
          "entityType": "1thesis",
          "highlight": {},
          "data": ... // doc data
        },
        "matchedChildren": {
          "RfbrDocument": 4
        }
      },
      ... // others docs
    ],
    "total": 25
  }
}

Поддерживается только синхронный вызов

• На входе: BushcraftSearchRequest
• На выходе: AggregationSearchResult

branchUnfold

Поиск по ветке куста ограниченного контексте

На входе поисковый запрос

{
    "query": "электроконтактная",
    "paging": {
        "page": 1,
        "count": 40
    },
    "bushId": "fixedBush",
    "root": {
        "entityType": "Patent",
        "objectId": "c7feabde-09cd-463c-ab4e-968178e7ab37"
    },
    "branchType": "RfbrDocument"
}

В результате ветка куста объектов

{
  "status": "Completed",
  "timestamp": 1651388234581,
  "value": {
    "documents": [
      {
        "id": "975975bb-ece6-4aca-80fc-5f227e982582",
        "entityType": "RfbrDocument",
        "highlight": {
          "newFileContent": [
            "И, действительно, !!!HL!!электроконтактная!!HL!!! методика, о которой я здесь\nрассказываю, в скором времени сыграла",
            "Результаты\nизмерений, полученные с помощью !!!HL!!электроконтактной!!HL!!! методики (в\nсочетании с другими), позволили",
            "С помощью !!!HL!!электроконтактной!!HL!!! методики уже в 1948 году были\nполучены первые экспериментальные данные о",
            "моей сохранилось чувство признательности и даже\nгордости от того, что в этой нашей работе по созданию !!!HL!!электроконтактной!!HL!!!",
            "Опыты намечалось проводить с применением !!!HL!!электроконтактной!!HL!!! методики измерения скоростей."
          ]
        },
        "data": ... // doc data
      },
      {
        "id": "1f398276-efb3-41c9-994d-6680681d59f5",
        "entityType": "RfbrDocument",
        "highlight": {
          "newFileContent": [
            "камера; 2 — пьезокварцевый датчик давления; З капсюльвоспламенитель; 4 — метаемое тело с полостью; 5 !!!HL!!электроконтактное!!HL!!!"
          ]
        },
        "data": ... // doc data
      }
    ],
    "total": 2
  }
}

Поддерживается только синхронный вызов

• На входе: BranchUnfoldRequest
• На выходе: AggregationSearchResult если найденные документы сами являются корнями или ByParentSearchResult если документы являются листьями

createBush

Создание ограниченного контекста

На входе форма создания

{
  "id": "fixedBush",
  "relations": {
    "links": {"Patent": {"RfbrDocument": {}}},
    "1thesis": {"RfbrDocument": {}},
    "poems": {"kate": {}}
  }
}

В результате идентификатор успешно созданного контекста

"fixedBush"

Поддерживается только синхронный вызов

• На входе: BushCreateDTO
• На выходе: String

getBush

Получение ограниченного контекста

На входе идентификатор ограниченного контекста

"fixedBush"

В результате ограниченный контекст

{
  "id": "fixedBush",
  "relations": {
    "links": {"Patent": {"RfbrDocument": {}}},
    "1thesis": {"RfbrDocument": {}},
    "poems": {"kate": {}}
  }
}

Поддерживается только синхронный вызов

• На входе: String
• На выходе: BushCreateDTO

listBush

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

Входных данных нет

В результате список ограниченных контекстов

[
  {
    "id": "fixedBush",
    "relations": {
      "links": {
        "Patent": {
          "RfbrDocument": {}
        }
      },
      "poems": {
        "kate": {}
      },
      "1thesis": {
        "RfbrDocument": {}
      }
    },
    "version": 1
  }
]

Поддерживается только синхронный вызов

• Команда не принимает параметров
• На выходе: Seq[Bush]

deleteBush

Удаление ограниченного контекста

На входе идентификатор контекста

"fixedBush"

В результате кол-во удаленных записей

Поддерживается только синхронный вызов

• На входе: String
• На выходе: Integer

updateBush

Обновление ограниченного контекста

На входе описание контекста

{
  "id": "fixedBush",
  "relations": {
    "links": {"Patent": {"RfbrDocument": {}}},
    "1thesis": {"RfbrDocument": {}},
    "newRoot": {"newLeaf": {}}
  },
  "version": 1
}

В результате кол-во обновленных записей

Поддерживается только синхронный вызов

• На входе: Bush
• На выходе: Integer

Сервис модели данных

Сервис модели данных (Data Model Service) позволяет настроить какие сущности, с какими полями и отношениями будут храниться в системе Cursor. На основе данных о сущностях сервис будет формировать описание модели данных и возвращать его в формате JsonSchema. Также сервис управляет созданием/изменением/удалением объектов сущностей в реестрах.
Сущности, полученные из внешних источников (клиентов), таких как сетевая папка или 1С, называются внешними. Отличие от внутренних сущностей состоит в том, что помимо внутреннего ID, они имеют ID из внешнего источника, по которому этот источник может совершать запросы.

Общая документация по сервису находится в разделе Confluence: Cursor/Техническая документация/Сервис Модели данных

В сервисе предусмотрены следующие команды:

• Список типов полей
• Список типов отношений
• Создать модель данных
• Получить модель данных
• Список моделей данных
• Получить полную схему всех сущностей и отношений
• Получить пример объекта сущности
• Сохранить объект
• Сохранить список объектов
• Сохранить внешний объект
• Получить объект
• Получить объект (внутренняя команда)
• Получить объект с определенными полями
• Получить объект с определенными полями (внутренняя команда)
• Получить список объектов по ID
• Получить внешний объект
• Обновить объект
• Обновить часть полей в объекте
• Обновить часть полей в объектах (по поисковому запросу)
• Обновить часть полей в объектах (по ID)
• Обновить внешний объект
• Отметить объект как удаленный
• Удалить объект
• Удалить объекты по списку
• Удалить объект по поиску
• Удалить внешний объект
• Сохранить дополнительную информацию в объект
• Сохранить дополнительную информацию в файлы объекта
• Список объектов
• Список объектов с определенными полями
• Список метаданных объектов
• Список наименований объектов (V1)
• Список наименований объектов (V2)
• Позиция объекта в списке
• Получение агрегированной статистики полей модели данных
• Сохранить отношение между объектами
• Сохранить несколько отношений между объектами
• Получить отношение между объектами
• Получить отношения для конкретного объекта с конкретной сущностью
• Получить отношения для конкретных объектов с конкретными сущностями
• Получить все отношения для конкретного объекта
• Удалить отношение между объектами
• Удалить отношения для конкретного объекта
• Удалить все отношения для конкретного объекта
• Обновить список отношений внешнего объекта
• Переиндексировать объект
• Получить связь между объектами
• Получить список связей конкретного объекта
• Получить список всех связей между указанными типами
• Создать связь между объектами
• Создать связи между объектами
• Удалить связь между объектами
• Удалить все связи для конкретного объекта
• Список файлов с подробным описанием и тегами
• Список тегов с количеством привязанных файлов
• Список уникальных расширений файлов
• Записать новые теги для конкретного файла
• Удалить выбранные теги для конкретного файла
• Удалить все теги для конкретного файла
• Получение информации о файле для скачивания
• Создать новые ключевые слова и прикрепить к объекту
• Получить список ключевых слов объектов
• Получить список ключевых слов

Конфигурирование сервиса модели данных

Требования к запуску сервиса модели данных

Запуск сервиса осуществляется локально через sbt, на стенде в docker на jvm.

Для корректной минимальной работы сервиса требуется обязательное подключение к PostgreSQL, Kafka, Consul. Для настройки подключения к ним нужно заполнить обязательные переменные окружения из раздела ниже.

Для нормальной работы сервису дополнительно требуется окружение Verdi: CommandStatus и ApiGateway. В этом случае нужно уделить внимание настройкам, связанным с ServiceDiscovery и CommandDiscovery.

Список переменных окружения сервиса модели данных

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

Формат CEF для логов сервиса Data model

У логов есть возможность включить формат CEF для логирования по следующему шаблону:
2022-12-14T16:56:31+0500 CEF:Version|Device Vendor|Device Product|Device Version|EventClassId|Message|Severity|src=? dst=? shost=? suid=? suser=? msg=? end=currentTimeMillis|.

Чтобы включить логирование в формате CEF, нужно задать переменную LOG_OUTPUT = STDOUT_CEF. Если логи пишутся в формате CEF, то необходимо задать следующие переменные, которые по умолчанию не заданы:

• LOGGING_SRC_IP, для параметра src в логах
• LOGGING_SRC_HOST, для параметра shost в логах
• LOGGING_DST_IP, для параметра dst в логах

В файле boot/src/main/resources/logback.xml можно поменять class path для основного класса приложения (переменная projectMainClassPath), если это необходимо.

Команды для сервиса Data model

Список реализованных в сервисе команд, моделей EntityType и действий Actions, которые можно использовать при настройке авторизации.
Не все поля EntityType доступны для использования в настройке авторизации.

GetFieldTypes

Входных данных нет

На выходе

[
  {
    "id": "string",
    "description": "Строка",
    "databaseType": "Varchar(64)",
    "settings": {}
  },
  {
    "id": "dateTime",
    "description": "Дата/время",
    "databaseType": "DateTime",
    "settings": {}
  }
]

Получение списка доступных типов полей для сущностей модели данных.

Имя команды для вызова: getFieldTypes. Поддерживается только синхронный вызов.

• Команда не принимает параметров
• На выходе: List[FieldType]

GetRelationTypes

Входных данных нет

На выходе

[
  {
    "id": "one-to-one",
    "title": "1 к 1",
    "description": "Один к одному"
  },
  {
    "id": "many-to-one",
    "title": "Многие к 1",
    "description": "Многие к одному"
  },
  {
    "id": "many-to-many",
    "title": "Многие ко многим",
    "description": "Многие ко многим"
  }
]

Получение доступных типов отношений между сущностями в модели данных.

Имя команды для вызова: getRelationTypes. Поддерживается только синхронный вызов.

• Команда не принимает параметров
• На выходе: List[RelationType]

CreateDataModel

На входе MigrationDSL в виде списка операций

[
  {
    "operation": "CreateEntity",
    "entityType": "Order",
    "title": "Договор"
  },
  {
    "operation": "AddField",
    "entityType": "Order",
    "fieldId": "date",
    "fieldType": "dateTime",
    "title": "Дата договора",
    "description": "Дата заключения договора",
    "example": 1582966800,
    "nullable": false
  },
  {
    "operation": "AddField",
    "entityType": "Order",
    "fieldId": "number",
    "fieldType": "number",
    "title": "Номер договора",
    "example": 555,
    "nullable": false
  },
  {
    "operation": "AddField",
    "entityType": "Order",
    "fieldId": "title",
    "fieldType": "string",
    "title": "Название договора",
    "example": "Договор аренды",
    "nullable": false,
    "settings": {
      "maxLength": 200
    }
  },
  {
    "operation": "AddField",
    "entityType": "Order",
    "fieldId": "places",
    "fieldType": "catalog",
    "title": "Места заключения договора",
    "nullable": true,
    "settings": {
      "code": "city",
      "multiple": true
    }
  },
  {
    "operation": "CreateEntity",
    "entityType": "Person",
    "title": "Человек"
  },
  {
    "operation": "AddField",
    "entityType": "Person",
    "fieldId": "name",
    "fieldType": "string",
    "title": "ФИО",
    "nullable": false
  },
  {
    "operation": "AddRelation",
    "relationType": "many-to-one",
    "entity1": "Order",
    "entity2": "Person",
    "title1": "Автор договора",
    "title2": "Договора автора",
    "entity1Field": "author",
    "entity2Field": "orders"
  }
]

На выходе признак успешного создания модели данных

true

Создание или изменение модели данных с использованием Migration DSL. Может использоваться для создания новых сущностей или для модификации уже существующих. Фактически, команда применяет переданную ей миграцию для модели данных, модифицируя текущую. Migration DSL позволяет описать создание или изменение модели данных в виде последовательности операций/шагов.

Доступные операции Migration DSL:

• Создать сущность CreateEntity
• Изменить сущность UpdateEntity
• Удалить сущность DeleteEntity
• Добавить поле сущности AddField
• Добавить дополнительное поле сущности AddAdditionalField
• Удалить поле у сущности DeleteField
• Изменить поле у сущности UpdateField
• Добавить отношение между сущностями AddRelation
• Изменить отношение между сущностями UpdateRelation
• Удалить отношение между сущностями DeleteRelation
• Выполнить операцию для сущностей с префиксом PrefixMigration

Каждой операции соответствует json-объект, список которых и образует MigrationDSL-запрос на создание модели данных. Объекты для операций указаны возле них в списке. Они различаются по коду операции, передаваемому в поле operation. Все объекты для описания шагов наследуются от общего типа MigrationDslOperation.

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

Имя команды для вызова: createDataModel. Поддерживается асинхронный и синхронный вызов. Результат выполнения команды журналируется.

• На входе: List[MigrationDslOperation]
• На выходе: Boolean

GetDataModel

На входе код типа сущностей

"Order"

На выходе Json-schema

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "definitions": {
    "date" : {
      "type" : "integer",
      "minimum" : 0
    },
    "relation" : {
      "type" : "string",
      "format" : "uuid"
    },
    "catalog" : {
      "type" : "string",
      "format" : "uuid"
    },
    "multi-catalog" : {
      "type" : "array",
      "items" : {
        "type" : "string",
        "format" : "uuid"
      }
    },
    "file": {
      "type": "object",
      "properties": {
        "fileId": {"type": "string", "format":  "uuid"},
        "name": {"type":  "string"},
        "extension": {"type":  "string"},
        "size": {"type": "integer", "minimum": 0},
        "url": {"type":  "string"},
        "additional": {"type": "object"},
        "created": {"type": "integer", "minimum": 0},
        "modified": {"type": "integer", "minimum": 0},
        "md5": {"type": "string", "pattern": "^[0-9a-fA-F]{32}$"}
      },
      "required": ["fileId"]
    }
  },
  "relations": [
    {
      "name": "Order_to_Person_on_author",
      "entity1": "Order",
      "entity2": "Person",
      "relationType": "many-to-one",
      "entity1Field": "author",
      "entity2Field": "orders"
    }
  ],
  "type": "object",
  "properties": {
    "author": {
      "$ref": "#/definitions/relation",
      "additional": false,
      "nullable": true,
      "readOnly": true,
      "multiple": false,
      "title": "Authorship",
      "to": "Person",
      "settings": {
        "to": "Person"
      }
    },
    "date": {
      "$ref": "#/definitions/date",
      "title": "Дата",
      "description": "Дата/время",
      "additional": false,
      "rawType": "dateTime"
    },
    "number": {
      "type": "number",
      "description": "Число",
      "additional": false,
      "rawType": "number"
    },
    "places" : {
      "$ref" : "#/definitions/multi-catalog",
      "code" : "city",
      "multiple" : true,
      "title" : "Места заключения договора",
      "additional" : false,
      "rawType": "catalog",
      "settings": {
        "code": "city",
        "multiple": true
      }
    },
    "title" : {
      "type" : "string",
      "maxLength" : 200,
      "title" : "Название договора",
      "additional" : false,
      "rawType": "string",
      "example": "Договор аренды",
      "exampleType": "string",
      "settings": {
        "maxLength": 200
      }
    }
  },
  "required": [
    "date",
    "number",
    "title"
  ]
}

Или ошибка, если такой модели данных не существует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}

Получение описания модели данных для конкретной сущности в виде JSON-Schema.

Имя команды для вызова: getDataModel. Поддерживается только синхронный вызов.

• На входе: JSON-строка
• На выходе: Json schema

ListDataModels

Входных данных нет

На выходе

[
  {
    "id": "Order",
    "title": "Договор",
    "description": "Описывает договор между несколькими агентами",
    "settings": {
      "titleRule": "title"
    }
  },
  {
    "id": "Person",
    "title": "Человек",
    "description": "Дополнительные человеческие аттрибуты для пользователя",
    "settings": {}
  }
]

Получение созданных типов сущностей.

Имя команды для вызова: listDataModels. Поддерживается только синхронный вызов.

• Команда не принимает параметров
• На выходе: List[EntityType]

GetAllDataModels

Входных данных нет

На выходе

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "definitions": {
    "date" : {
      "type" : "integer",
      "minimum" : 0
    },
    "relation" : {
      "type" : "string",
      "format" : "uuid"
    },
    "catalog" : {
      "type" : "string",
      "format" : "uuid"
    },
    "multi-catalog" : {
      "type" : "array",
      "items" : {
        "type" : "string",
        "format" : "uuid"
      }
    },
    "file": {
      "type": "object",
      "properties": {
        "fileId": {"type": "string", "format":  "uuid"},
        "name": {"type":  "string"},
        "extension": {"type":  "string"},
        "size": {"type": "integer", "minimum": 0},
        "url": {"type":  "string"},
        "additional": {"type": "object"},
        "created": {"type": "integer", "minimum": 0},
        "modified": {"type": "integer", "minimum": 0},
        "md5": {"type": "string", "pattern": "^[0-9a-fA-F]{32}$"}
      },
      "required": ["fileId"]
    },
    "Person": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 64,
          "description": "Строка",
          "additional": false,
          "rawType": "string"
        }
      },
      "required": [
        "name"
      ]
    },
    "Order": {
      "type": "object",
      "properties": {
        "number": {
          "type": "number",
          "description": "Число",
          "additional": false,
          "rawType": "number"
        },
        "date": {
          "$ref": "#/definitions/date",
          "description": "Дата/время",
          "additional": false,
          "rawType": "dateTime"
        },
        "author": {
          "$ref": "#/definitions/relation",
          "additional": false,
          "nullable": true,
          "readOnly": true,
          "multiple": false,
          "title": "Authorship",
          "to": "Person",
          "settings": {
            "to": "Person"
          }
        }
      },
      "required": [
        "number",
        "date"
      ]
    }
  },
  "relations": [
    {
      "name": "Order_to_Person_on_author",
      "entity1": "Order",
      "entity2": "Person",
      "relationType": "many-to-one",
      "entity1Field": "author",
      "entity2Field": "orders"
    }
  ],
  "oneOf": [
    {
      "$ref": "#/definitions/Order"
    },
    {
      "$ref": "#/definitions/Person"
    }
  ]
}

Получение JSON-Schema для всех моделей данных.

Имя команды для вызова: getAllDataModels. Поддерживается только синхронный вызов.

• Команда не принимает параметров
• На выходе: Json schema

GetExampleObject

На входе тип сущности

"Order"

На выходе пример объекта данной сущности

{
  "id": "d4db2633-62c7-4b61-956d-cb5461fe2a3e",
  "externalId": "0000000000000000",
  "entityType": "Order",
  "title": "Order d4db2633-62c7-4b61-956d-cb5461fe2a3e",
  "source": "example",
  "created": 1630326492,
  "modified": 1630326492,
  "data": {
    "date": 1577869200,
    "number": 555,
    "author": "00000000-0000-0000-0000-000000000000"
  },
  "additionalData": {},
  "version": 1
}

Получение примера объекта сущности. Объект собирается из примеров полей (example), которые указываются при добавлении поля сущности (AddField)

Генерация полей:

Поле title зависит от поля data.titleRule. Если этого поля нет, то title имеет вид <entityType> <id>

Значения полей в data зависят от параметра example при создании поля (AddField). Если не указано, то см. Значения по умолчанию

Имя команды для вызова: getExampleObject. Поддерживается только синхронный вызов

• На входе: строка с типом сущности
• На выходе: EntityObject

SaveObject

На входе общие свойства сохраняемого объекта и основные атрибуты

{
  "entityType": "Order",
  "source": "manual",
  "attributes": {
    "date": 1577869200,
    "number": 514
  }
}

На выходе ID созданного объекта

"18b1011b-9db3-4186-a53c-971016030068"

Сохранение объекта сущности.

Имя команды для вызова: saveObject. Поддерживается асинхронный и синхронный вызов. Результат выполнения команды журналируется.

• На входе: AddEntityObject
• На выходе: UUID созданного объекта

SaveObjectBatch

На входе общие свойства сохраняемых объектов и основные атрибуты

{
  "entityType": "Order",
  "source": "manual",
  "attributes": [
    {
      "date": 1577869200,
      "number": 512
    },
    {
      "date": 1577869200,
      "number": 513
    },{
      "date": 1577869200,
      "number": 514
    }
  ]
}

На выходе список ID созданных объектов

[
  "18b1011b-9db3-4186-a53c-971016030068",
  "20f95899-cd42-4afc-9903-84269db53543",
  "370a9981-ea0a-4830-93fe-e4e27ece167f"
]

Сохранение списка объектов сущности. Порядок в списке возвращаемых идентификаторов соответствует порядку в списке атрибутов attributes.

Имя команды для вызова: saveObjectBatch. Поддерживается асинхронный и синхронный вызов. Результат выполнения команды журналируется.
Команда только внутренняя (нельзя вызвать через Api Gateway), не требует аутентификации.

• На входе: AddEntityObjectBatch
• На выходе: Seq[UUID] созданных объектов

SaveExternalObject

На входе общие свойства сохраняемого объекта и основные атрибуты

{
  "entityType": "Order", 
  "externalId": "ExternalOrder",
  "source": "order-client",
  "attributes": {
    "date": 1577869200,
    "number": 514,
    "title": "External Order"
  }
}

На выходе внутренний ID созданного объекта

"18b1011b-9db3-4186-a53c-971016030068"

Сохранение объекта сущности, полученного из внешнего источника.

Имя команды для вызова: saveExternalObject. Поддерживается асинхронный и синхронный вызов.

Команда только внутренняя (нельзя вызвать через Api Gateway), не требует аутентификации. Результат выполнения команды журналируется.

• На входе: AddExternalEntityObject
• На выходе: внутренний UUID созданного объекта

GetObject

На входе ID получаемого объекта и его тип сущности

{
  "entityType": "Order",
  "objectId": "18b1011b-9db3-4186-a53c-971016030068"
}

На выходе данные запрашиваемого объекта

{
  "id": "18b1011b-9db3-4186-a53c-971016030068",
  "externalId": "ExternalOrder",
  "entityType": "Order",
  "title": "Аренда лошади",
  "source": "manual",
  "created": 1630326492,
  "modified": 1630326492,
  "data": {
    "date": 1577869200,
    "number": 514,
    "title": "Аренда лошади"
  },
  "additionalData": {},
  "version": 1
}

Или ошибка, если объект отсутствует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}

Получение данных объекта сущности.

Имя команды для вызова: getObject. Поддерживается только синхронный вызов

• На входе: EntityObjectIdentity
• На выходе: EntityObject

InternalGetObject

На входе ID получаемого объекта и его тип сущности

{
  "entityType": "Order",
  "objectId": "18b1011b-9db3-4186-a53c-971016030068"
}

На выходе данные запрашиваемого объекта

{
  "id": "18b1011b-9db3-4186-a53c-971016030068",
  "externalId": "ExternalOrder",
  "entityType": "Order",
  "title": "Аренда лошади",
  "source": "manual",
  "created": 1630326492,
  "modified": 1630326492,
  "data": {
    "date": 1577869200,
    "number": 514,
    "title": "Аренда лошади"
  },
  "additionalData": {},
  "version": 1
}

Или ошибка, если объект отсутствует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}

Получение данных объекта сущности. В отличии от команды getObject, в этой команде не проверяется авторизация.

Имя команды для вызова: internalGetObject. Поддерживается только синхронный вызов

Команда только внутренняя (нельзя вызвать через Api Gateway) и отличается от внешней getObject только отсутствием аутентификации.

• На входе: EntityObjectIdentity
• На выходе: EntityObject

GetObjectsBatch

На входе список из ID и типов сущности получаемых объектов

[
  {
    "entityType": "Order",
    "objectId": "18b1011b-9db3-4186-a53c-971016030068"
  },
  {
    "entityType": "Person",
    "objectId": "c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6"
  }
]

На выходе список объектов

[
  {
    "id": "18b1011b-9db3-4186-a53c-971016030068",
    "externalId": "ExternalOrder",
    "entityType": "Order",
    "title": "Аренда лошади",
    "source": "manual",
    "created": 1630326492,
    "modified": 1630326492,
    "data": {
      "date": 1577869200,
      "number": 514,
      "title": "Аренда лошади"
    },
    "additionalData": {},
    "version": 1
  },
  {
    "id": "c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6",
    "externalId": null,
    "entityType": "Person",
    "title": "Person c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6",
    "source": "manual",
    "created": 1645526774115,
    "modified": 1645526774115,
    "data": {
      "name": "Строка длиной не больше 64"
    },
    "additionalData": {},
    "version": 1,
    "orders": ["18b1011b-9db3-4186-a53c-971016030068"]
  }
]

Получение данных объектов по их ID и типу сущности. Порядок объектов в ответе совпадает с порядком идентификаторов в запросе.

Имя команды для вызова: getObjectsBatch. Поддерживается только синхронный вызов

• На входе: List[EntityObjectIdentity]
• На выходе: List[EntityObject]

RichGetObject

На входе ID получаемого объекта, тип его сущности и необходимые поля

{
  "id": {
    "entityType": "Order",
    "objectId": "18b1011b-9db3-4186-a53c-971016030068"
  },
  "fields": [
    "number",
    "date"
  ]
}

На выходе данные запрашиваемого объекта

{
  "id": "18b1011b-9db3-4186-a53c-971016030068",
  "externalId": "ExternalOrder",
  "entityType": "Order",
  "title": "Аренда лошади",
  "source": "manual",
  "created": 1630326492,
  "modified": 1630326492,
  "data": {
    "number": 514,
    "date": 1577869200
  },
  "additionalData": {},
  "version": 1
}

Или ошибка, если объект отсутствует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}

Или ошибка, если какое-либо из запрашиваемых полей отсутствует в json schema

{
    "businessError": null,
    "message": "ERROR: fields [first_field,second_field] for entityType 'Order' not found",
    "stackTrace": null,
    "data": null
}

Получение данных объекта сущности.

Для указания списка допустимых полей см. Методы Rich*.

Имя команды для вызова: richGetObject. Поддерживается только синхронный вызов

• На входе: EntityObjectFields
• На выходе: EntityObject

InternalRichGetObject

На входе ID получаемого объекта, тип его сущности и необходимые поля

{
  "id": {
    "entityType": "Order",
    "objectId": "18b1011b-9db3-4186-a53c-971016030068"
  },
  "fields": [
    "number",
    "date"
  ]
}

На выходе данные запрашиваемого объекта

{
  "id": "18b1011b-9db3-4186-a53c-971016030068",
  "externalId": "ExternalOrder",
  "entityType": "Order",
  "title": "Аренда лошади",
  "source": "manual",
  "created": 1630326492,
  "modified": 1630326492,
  "data": {
    "number": 514,
    "date": 1577869200
  },
  "additionalData": {},
  "version": 1
}

Или ошибка, если объект отсутствует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}

Или ошибка, если какое-либо из запрашиваемых полей отсутствует в json schema

{
    "businessError": null,
    "message": "ERROR: fields [first_field,second_field] for entityType 'Order' not found",
    "stackTrace": null,
    "data": null
}

Получение данных объекта сущности.

Для указания списка допустимых полей см. Методы Rich*.

Имя команды для вызова: internalRichGetObject. Поддерживается только синхронный вызов.

Команда только внутренняя (нельзя вызвать через Api Gateway) и отличается от внешней richGetObject только отсутствием аутентификации.

• На входе: EntityObjectFields
• На выходе: EntityObject

RichGetObjectsBatch

На входе список из типов сущностей, идентификаторов и требуемых полей у получаемых объектов

[
  {
    "entityType": "Order",
    "ids": [
      "18b1011b-9db3-4186-a53c-971016030068"
    ],
    "fields": [
      "date",
      "number"
    ]
  },
  {
    "entityType": "Person",
    "ids": [
      "c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6"
    ],
    "fields": [
      "name",
      "orders"
    ]
  }
]

На выходе список объектов, сгруппированный по типам сущностей

{
  "Order": [
    {
      "id": "18b1011b-9db3-4186-a53c-971016030068",
      "externalId": "ExternalOrder",
      "entityType": "Order",
      "title": "Аренда лошади",
      "source": "manual",
      "created": 1630326492,
      "modified": 1630326492,
      "data": {
        "date": 1577869200,
        "number": 514
      },
      "additionalData": {},
      "version": 1
    }
  ],
  "Person": [
    {
      "id": "c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6",
      "externalId": null,
      "entityType": "Person",
      "title": "Person c11df8f6-e8be-4e8e-a815-40e0d0a0cfb6",
      "source": "manual",
      "created": 1645526774115,
      "modified": 1645526774115,
      "data": {
        "orders": [
          "18b1011b-9db3-4186-a53c-971016030068"
        ],
        "name": "Строка длиной не больше 64"
      },
      "additionalData": {},
      "version": 1
    }
  ]
}

Получение данных объектов по их ID, типу сущности и списку требуемых полей. Порядок объектов в ответе совпадает с порядком идентификаторов в запросе.

Для указания списка допустимых полей см. Методы Rich*.

Имя команды для вызова: richGetObjectsBatch. Поддерживается только синхронный вызов

• На входе: List[EntityObjectsBatchWithFields]
• На выходе: Map[EntityTypeId, Seq[EntityObject]]

GetExternalObject

На входе внешний ID получаемого объекта и его тип сущности

{
  "entityType": "Order",
  "externalId": "ExternalOrder"
}

На выходе данные запрашиваемого объекта

{
  "id": "982fa393-423b-4e6b-8e7d-d2b65ff061c8",
  "externalId": "ExternalOrder", 
  "entityType": "Order",
  "title": "External Order",
  "source": "order-client",
  "created": 1639748410280,
  "modified": 1639748410280,
  "data": {
    "date": 1577869200,
    "title": "External Order",
    "number": 514
  },
  "additionalData": {},
  "version": 1
}

Получение данных объекта сущности.

Имя команды для вызова: getExternalObject. Поддерживается только синхронный вызов.

Команда только внутренняя (нельзя вызвать через Api Gateway), не требует аутентификации.

• На входе: EntityObjectExternalIdentity
• На выходе: EntityObject

UpdateObject

На входе общие свойства сохраняемого объекта и основные атрибуты

{
  "entityType": "Order",
  "objectId": "18b1011b-9db3-4186-a53c-971016030068",
  "version": 2,
  "attributes": {
    "date": 1577869200,
    "number": 514
  }
}

На выходе признак успешного сохранения

true

Или ошибка, если объект не существует

{
    "businessError": null,
    "message": "ERROR: Entity object not found",
    "stackTrace": null,
    "data": null
}