Выполнение заданий через сервис интеграции Directum RX: какое значение result у какого задания

Коротко. У каждого типа задания Directum RX свой набор значений result: Complete у простого задания, Accepted у приёмки, Approved у согласования, Acquainted у ознакомления. Тип берётся из @odata.type в ответе на запрос задания. «На доработку» бывает и ForRework, и ForRevision. В RX 25 свободное согласование порождает задания EntityApprovalAssignment нового модуля. Задачи, созданные через сервис интеграции, нужно отдельно стартовать, а задания на подписание оставлять человеку в RX.

Интеграция выполняет задания Directum RX через сервис интеграции: портал, бот, ИИ-помощник. На простых заданиях всё работает, а на согласовании или ознакомлении действие падает с непонятной ошибкой. Причина почти всегда в параметре result: у каждого типа задания свой набор значений, и в документации их одной таблицей нет. Собрали её и описали, как найти нужное значение самому.

Симптом

Вызов действия Docflow/CompleteAssignment возвращает одно из двух:

404 с пустым телом. Так сервис интеграции отвечает, когда не передан обязательный параметр. Чаще всего забыт result, реже задание не найдено или недоступно.
400 с текстом вида «Элемент перечисления "Result" со значением "Complete" недопустим». Результат передан, но этому типу задания он не подходит.

Второй случай особенно обиден: значение Complete работает для простых заданий, и кажется, что оно универсальное.

Почему так

В RX нет одного общего «выполнено». Результат задания это перечисление, и у каждого типа задания оно своё: приёмка работ принимает или возвращает, согласование согласует, ознакомление отмечает «ознакомлен». CompleteAssignment принимает строку и проверяет её по перечислению конкретного типа.

Добавляет путаницы то, что похожие по смыслу значения называются по-разному. «На доработку» у приёмки работ и у свободного согласования это ForRework, а у согласования по регламенту ForRevision.

Диагностика: тип задания

Тип виден в ответе сервиса интеграции на запрос задания, в поле @odata.type:

curl -s -u "$LOGIN:$PASSWORD" \
  "https://rx.company.ru/Integration/odata/IAssignments(12345)?\$select=Id,Subject,Status"

{
  "@odata.type": "#Sungero.IntegrationService.Models.Generated.DocflowApproval.IEntityApprovalAssignmentDto",
  "Id": 12345,
  "Subject": "Согласуйте: договор поставки",
  "Status": "InProcess"
}

Нужна последняя часть без I в начале и Dto в конце: здесь это EntityApprovalAssignment. Если в решении тип переопределён доработкой, пространство имён в начале будет другим, а имя типа обычно то же.

Таблица результатов

Значения ниже взяты из метаданных стандартных модулей Directum RX 25.2. Первое значение в строке подходит в большинстве случаев как «выполнить».

Задание	Тип	Допустимые значения result
Простое задание	`SimpleAssignment`	`Complete`
Приёмка работ по простой задаче	`ReviewAssignment`	`Accepted`, `ForRework`
Согласование (свободное, RX 25)	`EntityApprovalAssignment`	`Approved`, `WithSuggestions`, `ForRework`, `Forward`
Доработка после согласования (RX 25)	`EntityReworkAssignment`	`ForReapproval`, `Forward`
Задание автору после согласования (RX 25)	`AdvancedAssignment`	`Complete`, `ForRework`, `Forward`
Согласование по регламенту	`ApprovalAssignment`	`Approved`, `WithSuggestions`, `ForRevision`, `Forward`
Свободное согласование (прежний механизм)	`FreeApprovalAssignment`	`Approved`, `ForRework`, `Forward`
Доработка после свободного согласования	`FreeApprovalReworkAssignment`	`Reworked`
Доработка после согласования по регламенту	`ApprovalReworkAssignment`	`ForReapproving`, `Forward`
Проверка в согласовании	`ApprovalCheckingAssignment`	`Accept`, `ForRework`
Задание в согласовании	`ApprovalSimpleAssignment`	`Complete`
Исполнение в согласовании	`ApprovalExecutionAssignment`	`Complete`, `ForRevision`
Печать	`ApprovalPrintingAssignment`	`Execute`, `ForRevision`
Отправка контрагенту	`ApprovalSendingAssignment`	`Complete`, `ForRevision`
Ознакомление	`AcquaintanceAssignment`	`Acquainted`
Завершение ознакомления (автору)	`AcquaintanceFinishAssignment`	`Complete`
Рассмотрение документа	`DocumentReviewAssignment`	`Informed`, `DocsRework`, `Forward` и другие
Рассмотрение руководителем	`ReviewManagerAssignment`	`Explored`, `ForRework`, `Forward`, `AddResolution`, `AddAssignment`
Подписание	`ApprovalSigningAssignment`, `SigningAssignment`	`Sign`, `ForRevision` и другие, см. ниже

Forward (переадресовать) и значения про резолюции и поручения требуют дополнительных данных, которых у CompleteAssignment нет. Через сервис интеграции разумно использовать только результаты, которые ничего больше не спрашивают.

Свободное согласование в RX 25

В RX 25 свободное согласование документа идёт через новый модуль согласования. Задание согласующему приходит не как FreeApprovalAssignment, а как EntityApprovalAssignment, и после согласования автор получает ещё одно задание AdvancedAssignment («Согласование завершено»). Интеграция, написанная под прежние типы, на новых версиях перестаёт узнавать задания согласования, хотя пользователь в интерфейсе разницы не видит. Поэтому тип задания стоит каждый раз брать из ответа системы.

Что сделать

Определять тип задания перед выполнением, по @odata.type, и выбирать результат по таблице.
Держать свой результат по умолчанию для каждого типа. Если тип неизвестен, не угадывать, а просить человека выбрать.
Передавать ошибку 400 пользователю как есть. В её тексте RX называет недопустимое значение, по нему быстро понятно, что пошло не так.
Создавая задачи через сервис интеграции, помнить про старт. Действия Docflow/CreateSimpleTask, RecordManagement/CreateAcquaintanceTask, Docflow/CreateFreeApprovalTask и Docflow/CreateApprovalTask только сохраняют черновик и возвращают его Id. Чтобы задачу получили исполнители, нужен ещё вызов Docflow/StartTask. У простой задачи без срока RX ответит 404: срок обязателен.

curl -s -u "$LOGIN:$PASSWORD" -H "Content-Type: application/json" \
  -d '{"assignmentId": 12345, "result": "Approved"}' \
  "https://rx.company.ru/Integration/odata/Docflow/CompleteAssignment"

Чего не делать

Не выполнять через сервис интеграции задания на подписание. В интерфейсе результат «Подписать» идёт вместе с подписью документа, иногда квалифицированной. Подпись ставит владелец сертификата в RX, интеграция её за него не поставит.
Не подставлять Complete всем подряд. Оно подходит простым заданиям и части заданий согласования, а на остальных даст 400.
Не завязываться на названия процессов. После обновления RX тот же процесс может порождать задания другого типа, как это случилось со свободным согласованием в RX 25.