Интеграция с Directum RX

Раздел: Интеграции
Тип: Серверный коннектор (по запросу из UI)
Направление: LSUS → Directum RX (создание документа + задача согласования)

Коннектор LSUS → Directum RX (Directum Company): отправка Акта о проведении тестирования обновлений как простого документа в Directum RX со стартом задачи на свободное согласование участникам тестирования. Позволяет оформить результаты пилотного тестирования обновлений формальным документом и пустить его по маршруту согласования без ручного переноса данных.

Руководство по интеграции: Directum RX 25.3. Интеграция с внешними системами (разделы «Аутентификация», стр. 13–19; «Создание документа», стр. 80–82; функция CreateFreeApprovalTask, стр. 114).

Как это работает¶

  Сессия тестирования LSUS (акт PDF)
      │  run_directum_act_export()  — кнопка «Отправить акт в Directum RX»
      ▼
  Коннектор: генерация PDF + маппинг участников → сотрудники RX
      │  1) POST  /Integration/odata/ISimpleDocuments        → docId
      │  2) GET   /Integration/odata/IAssociatedApplications → appId (pdf)
      │  3) POST  .../ISimpleDocuments(docId)/Versions       → verId
      │  4) PUT   .../Versions(verId)/Body/$value            (octet-stream, байты PDF)
      │  5) POST  /Integration/odata/Docflow/CreateFreeApprovalTask → taskId
      │  6) PATCH /Integration/odata/IFreeApprovalTasks(taskId) {Author:{Id:<initiator>}}
      │  7) GET   /Integration/odata/IFreeApprovalTasks(taskId)
      │  8) GET   /Integration/odata/IFreeApprovalAssignments?$filter=MainTask/Id eq taskId
      │  Authorization: Basic <base64(service_user:password)>
      ▼
  Directum RX (простой документ + задача свободного согласования)

Коннектор создаёт простой документ (ISimpleDocuments), загружает PDF-тело акта в версию 1, затем одной встроенной [Public]-функцией Docflow/CreateFreeApprovalTask(documentId, text, deadline, approverIds) создаёт и стартует задачу на свободное согласование. После создания задачи коннектор меняет инициатора (Author) на текущего администратора LSUS.

Аутентификация¶

Basic auth от выделенной сервисной учётной записи (рекомендация руководства для headless-интеграции, стр. 13–14). Заголовок Authorization: Basic <base64(user:pass)> передаётся на каждый запрос.

infoНастройка на стороне Directum RX

Создайте учётную запись (напр. IntegrationUser).
Включите методы аутентификации в конфигурации Сервиса интеграции (AUTH_BASIC_SCHEME_ENABLED).
Добавьте пользователя в предопределённые роли:
- «Пользователи сервиса интеграции» — право вызывать Сервис интеграции;
- «Неинтерактивные пользователи» — доступ без интерактивного входа.
Убедитесь, что у этого пользователя есть права на создание простых документов и запуск задач свободного согласования.

Альтернативы (Basic → JWT Bearer, Kerberos/Negotiate, NTLM) описаны в руководстве; для данной задачи Basic — самый простой и рекомендуемый вариант.

Сопоставление участников (маппинг)¶

Участники тестирования LSUS сопоставляются с сотрудниками Directum RX (сущность Employee) для подстановки в approverIds:

Приоритет	Ключ	Поле RX	Источник в LSUS
1	Email	`Email`	`AdminUser.email` / LDAP-кэш
2	Логин	`UserName`	`username` участника (домен отсекается)

Поиск выполняется через GET /Integration/odata/IEmployees?$filter=Email eq '...' or UserName eq '...'&$expand=Person. Перед отправкой доступен предпросмотр маппинга (эндпоинт approvers-preview) — в UI видно, кто найден в RX, а кто нет.

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

priority_highВажно

Отправка невозможна, если ни один участник не сопоставлен. Проверьте совпадение логинов/email между LSUS и Directum RX перед первой отправкой (кнопка «Проверить связь» + предпросмотр маппинга).

Настройка¶

Настройки хранятся в data/server_settings.env (ключи directum_*, через read_connector_settings/upsert_connector_settings).

Параметр	По умолчанию	Описание
`directum_enabled`	`false`	Включить коннектор
`directum_url`	—	URL Сервиса интеграции (напр. `https://rx.corp.loc/Integration`)
`directum_username`	—	Логин сервисной учётной записи RX
`directum_password`	—	Пароль (маскируется в GET; пусто при сохранении = «не менять»)
`directum_verify_ssl`	`false`	Проверять SSL-сертификат RX
`directum_default_deadline_days`	`5`	Срок согласования по умолчанию, дней (1–60)
`directum_act_name_template`	`Акт о проведении тестирования обновлений #{session_code} — {session_name}`	Шаблон имени документа (`{session_code}`, `{session_name}`, `{id}`)

API управления¶

Метод	Путь	Назначение
`GET`	`/api/v1/admin/directum/settings`	Текущие настройки (пароль замаскирован)
`POST`	`/api/v1/admin/directum/settings`	Сохранить настройки
`POST`	`/api/v1/admin/directum/test`	Проверка связи (`GET $metadata` с Basic auth)
`GET`	`/api/v1/admin/directum/sessions/<id>/approvers-preview`	Предпросмотр маппинга участников сессии
`POST`	`/api/v1/admin/directum/send-act`	Отправить акт сессии на согласование
`GET`	`/api/v1/admin/directum/runs`	Журнал отправок (`?session_id=`, `?limit=`)
`GET`	`/api/v1/admin/directum/runs/<id>`	Детали одной отправки
`POST`	`/api/v1/admin/directum/runs/<id>/sync-status`	Ручной опрос и обновление статусов согласования
`GET`	`/api/v1/admin/directum/sessions/<id>/approval-status`	Последний статус по сессии + статусы согласующих

Права: admin.settings.view на все эндпоинты.

UI¶

Настройки коннектора — вкладка «Хосты → API-интеграции», карточка «Directum RX — согласование актов»: URL, учётка, пароль, проверка SSL, срок по умолчанию, шаблон имени; кнопка «Проверить связь»; таблица последних отправок.

Отправка акта — вкладка «Тестирование» → карточка сессии → меню «Действия» → «Отправить акт в Directum RX». В модалке:
- список участников с чекбоксами (отмечены подтвердившие согласие) и статусом маппинга (✅ найден / ⚠️ не найден);
- срок согласования (дней);
- текст задачи (необязательно);
- кнопка «Отправить».

Журнал отправок¶

Каждая отправка фиксируется в таблице directum_export_runs (модель DirectumExportRun, миграция 142):

Поле	Описание
`status`	`success` / `error` / `running`
`session_id`	Сессия тестирования LSUS (FK, NULL при удалении сессии)
`document_id`	ID созданного документа в RX
`task_id`	ID созданной задачи согласования в RX
`approvers_total` / `approvers_resolved`	Сколько выбрано / сколько сопоставлено
`http_status`	HTTP-статус последней ошибки OData
`error_message`	Текст ошибки
`payload_preview`	JSON: имя документа, список согласующих (resolved/unresolved), deadline
`initiated_by_username` / `initiator_employee_id`	Инициатор LSUS и его employee ID в RX
`initiator_change_status` / `initiator_change_error`	Статус смены `Author` задачи и причина ошибки
`approval_status` / `approval_status_rx`	Нормализованный и исходный статус согласования
`approval_comment` / `approval_synced_at` / `approval_sync_error`	Последний комментарий, время sync, ошибка sync

Детализация по согласующим хранится в directum_export_run_approvers: lsus_username, rx_employee_id, assignment_id, status, result, completed_at, comment.

Обработка ошибок и откат¶

При ошибке до создания документа — ничего в RX не создаётся, статус error.
При ошибке после создания документа (напр., на шаге версии/body/задачи) — документ уже существует в RX и не откатывается автоматически. В error_message указывается созданный document_id для ручной чистки (OData DELETE требует прав и настроен не везде).
Отсутствие сопоставленных участников → статус error с перечнем неразрешённых.

Ограничения¶

Тип документа — только простой документ (ISimpleDocuments). Официальный документ (IOfficialDocuments с указанием вида) — отдельно, при необходимости.
Срок согласования задаётся календарно (RX интерпретирует срок самостоятельно).
Статусы согласования кэшируются периодическим worker-задачником и ручным endpoint. Ошибки очередного опроса не меняют факт успешной отправки документа.
Лимиты RX: GET URL ≤ 2048 символов; время выполнения запроса ≤ 350 с; тело до 350 МБ (Base64 — до ~100 МБ). Акт тестирования (~десятки КБ) — далеко от лимитов.