Нужна интеграция с Directum RX? Новинка версии 4.0 для вас

Простая интеграция Directum RX с внешними системами позволяет наладить бизнес-процессы, основанные на специфичных возможностях разных систем. Кроме этого, она упрощает пользовательские сценарии работы.

Для интеграции Directum RX c 1С, службой каталогов Active Directory, редакторами ONLYOFFICE и некоторыми другими системами существуют готовые решения. Это здорово, но недостаточно, так как количество и разнообразие систем, которые использует бизнес, огромно: ERP, MDM, CRM, почтовые клиенты, мессенджеры, системы управления проектами и т.д. На основе этого была сформирована цель:

Создать понятный, современный механизм, который позволит просто, а значит дешево, объединять Directum RX с любыми системами, которые предоставляют инструменты интеграции.

 

Новый сервис

В системе Directum RX 4.0 появился сервис интеграции. Он умеет получать от внешней системы HTTP-запросы по веб-протоколу OData и выполнять их. Ответ преобразовывается в формат JSON и передается обратно внешней системе:

Сервис кроссплатформенный и входит в дистрибутив. Разворачивается вместе с остальными компонентами Directum RX на компьютерах с ОС Windows с помощью программы установки, а на Linux – с помощью скриптов. Если нужно масштабировать систему, сервис можно перенести с основного сервера, где развернут веб-сервер, на выделенный. Инструкция по переносу сервиса входит в комплект поставки.

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

Как настроить интеграцию

Настроить интеграцию Directum RX с внешними системами можно на раз-два-три.

Раз. Создать функции для интеграции

Интеграционными могут быть только серверные и разделяемые функции. В базовом решении по умолчанию есть функции, к которым можно обратиться через сервис интеграции. На своем слое разработки эти функции можно переопределить. Кроме этого, на слое можно любую серверную или разделяемую функцию базового решения сделать интеграционной или же с нуля написать свою функцию интеграции.

Чтобы функция стала интеграционной, к ней нужно добавить модификатор public и один из атрибутов:

• [Public(WebApiRequestType = {RequestType.Get})], если функция получает данные из Directum RX;
• [Public(WebApiRequestType = {RequestType.Post})], если функция выполняет действия в Directum RX.

Также следует проверить типы данных у параметров и возвращаемого значения функции. Из-за использования протокола OData к ним есть ряд требований, которые описаны в справке.

Два. Создать типы сущностей для интеграции

Что касается типов сущностей, через сервис интеграции можно получать, создавать, обновлять или удалять только те типы, для которых в среде разработки в редакторе установлен флажок Использовать в сервисе интеграции:

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

Три. Написать HTTP-запросы

Когда в среде разработки все готово, остается написать HTTP-запросы к интеграционным функциям или типам сущностей. Для обращения к функциям используются методы POST и GET. Для обращения к типам сущностей – POST, GET, PATCH и DELETE. Другие методы для обмена с Directum RX не используются.

В запросах важно:

• указывать данные для аутентификации в Directum RX. Пока можно использовать только учетные данные пользователей с типом аутентификации по паролю;
• проверять, что значения параметров и свойств написаны правильно. Например, некоторые нужно писать в кавычках, а некоторые нет;
• учитывать особенности сервиса интеграции.

Пример POST-запроса к функции AddValue(), которая на вход получает параметры Name, PlannedValue, ActualValue:

Чтобы быстро разобраться в понятиях «строка запроса», «заголовки» и «тело», изучите раздел с описанием структуры запроса.

От теории к практике. Рассмотрим кейс интеграции.

Пример

Ситуация

Для работы с договорами компания использует узкоспециализированную систему. В Directum RX создаются и хранятся все остальные типы документов. Чтобы упростить поиск и сделать Directum RX хранилищем для всех документов, нужно:

• в Directum RX создать договорные документы на основе документов из внешней системы;
• обновлять документы в Directum RX, когда они изменяются во внешней системе.

Далее рассмотрим, как реализовать первый пункт. Этого достаточно для понимания принципов.

Решение

Раз. Для этой ситуации не нужны функции интеграции, пункт пропускаем.

Два. В среде разработки для типа документа «Договор» (Contract) из базового решения по умолчанию установлен флажок Использовать в сервисе интеграции. То есть никаких дополнительных настроек не требуется, идем дальше.

Три. Чтобы в Directum RX создать документы на основе договоров из внешней системы:

1. Напишем запрос, который в системе создаст карточку договора и заполнит свойства документа.
2. С помощью второго запроса заполним содержимое, т.е. создадим версию документа.

В первом POST-запросе для создания карточки нужно указать:

• URL формата:

• имя и пароль пользователя для аутентификации в сервисе интеграции;
• заголовки Content-Type и Accept со значением application/json;
• заголовок Return со значением minimal, чтобы в ответе не получать данные сущности;
• свойства документа.

Пример:

В примере для заполнения свойств-ссылок таких как DocumentKind (Вид документа) используется упрощенный синтаксис, можно вместо него использовать синтаксис OData.

Запрос вернет ответ с кодом 201. В заголовке ответа Location будет указан URL созданной сущности с идентификатором (Id): https://DirectumRXServer.com/DrxIntegrationService/odata/IContracts(102).

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

Второй POST-запрос для заполнения версии, т.е. свойства с типом Коллекция, строится так же, как при создании сущности. Особенности:

• используется URL формата:

  {Протокол https или http}://{имя сервера, на котором установлен сервис интеграции}/{имя сервиса интеграции}/odata/{Интерфейс типа сущности во множественном числе}(ИД)/{Имя свойства-коллекции}

• в теле запроса указываются дочерние свойства в свойстве-коллекции и их значения.

Пример:

Таким образом мы создали договор в Directum RX.

Примеры запросов к функциям предлагаю посмотреть в справке: тут и тут. Если будут вопросы, пишите. У меня на этом все. Спасибо за внимание!