Пример расширения Службы фоновых операций

Расширение получает ID карточки документа и конвертирует приложенные файлы в формат PDF/A.

Ссылка на пример на GitHub: SampleWorkerExtension.

Пример рассчитан на версию Web-клиента dv6 или выше.

Перечень необходимых инструментов:

NodeJS v22.14.0 и выше
Microsoft Visual Studio 2022.
Консоль управления Docsvision версии 6.2 и выше
Пример "Пример взаимодействия с сервисом конвертации"

Сборка

Откройте /Samples.sln.
Соберите проект Others > SampleWorkerExtension.
Соберите проект Samples\Others\SampleWorkerExtension\SampleWorkerExtension.WebClientExtension\SampleWorkerExtension.WebExtension.
Выполните npm i, npm run build.
Соберите пример взаимодействия с сервисом конвертации.

Установка

Создайте папку /usr/lib/docsvision/common/SampleWorker в Linux и C:\Program Files\Docsvision\Common\SampleWorker в Windows и поместите в неё файлы:

DocsVision.SampleWorkerExtension.Manager.dll
DocsVision.SampleWorkerExtension.ObjectModel.dll
DocsVision.SampleWorkerExtension.WorkerService.dll

ru\DocsVision.SampleWorkerExtension.WorkerService.resources.dll

Может потребоваться выдать для этой папки права, т.к. сервисы Docsvision могут быть запущены под разными пользователями (Web-клиент запускается от от имени УЗ Docsvision и н требует ROOT привилегий).
Если Web-клиент, Служба фоновых операций или Консоль управления Docsvision установлены на разных серверах, этот пункт надо повторить для каждого сервера.

Создайте папку /usr/lib/docsvision/managementconsole/Extensions/SampleExtension в Linux и C:\Program Files\Docsvision\WorkerService\SampleWorker в Windows. Добавьте сборки DocsVision.SampleWorkerExtension.Role.dll вместе с ресурсами ru\DocsVision.SampleWorkerExtension.Role.resources.dll и конфигурационный файл SampleWorkerExtension.json (находится в проекте SampleWorkerExtension.Role) в папку Консоли управления Docsvision.
Создайте папку /usr/lib/docsvision/workerservice/Extensions в Linux и C:\Program Files\Docsvision\WorkerService\SampleWorker в Windows и добавьте в неё сборку DocsVision.SampleWorkerExtension.WorkerExtension.dll.
Установите серверное и клиентское расширения для Web-клиент из папки Others\SampleWorkerExtension\SampleWorkerExtension.WebClientExtension по инструкции.
Отредактируйте конфигурационный файл /usr/lib/docsvision/managementconsole/config/managementConsoleWorkerExtension.json в Linux и C:\Program Files\Docsvision\ManagementConsole\config\managementConsoleWorkerExtension.json в Windows, добавьте в секцию Libraries параметр SampleWorkerExtension.WorkerService:
```
    "Libraries": [
      "DocsVision.BackOffice.ObjectModel, Version=6.0.0.0, Culture=neutral, PublicKeyToken=7148afe997f90519",
      "DocsVision.SampleWorkerExtension.WorkerService, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4a2caa47aa5b6b29",
    ]
```

Проверка

В Консоли управления Docsvision создайте процесс Службы фоновых операций с типом конфигурации Расширение для WorkerService.
В разметке документа Web-клиента (например, просмотр) создайте кнопку и добавьте обработчик события При щелчке элемента управления sendConversionTask.
Создайте документ в Web-клиенте, приложите файл. После сохранения документа, нажмите созданную кнопку в разметке. Через некоторое время в секции файлов появится сконвертированный pdf-файл. Чтобы файл отобразился, обновите страницу.

Проект "SampleWorkerExtension.WebClientExtension"

Откройте /Samples.sln.
Соберите проект Others SampleWorkerExtension SampleWorkerExtension.WebClientServerExtension.
Откройте консоль в папке Others SampleWorkerExtension SampleWorkerExtension.WebClientExtension SampleWorkerExtension.WebExtension и выполнить команду npm install, потом npm update и в конце npm run build:prod.
Скопируйте каталог SamplesOutput\Site\Content\Modules\SampleWorkerWebExtension в каталог Каталог-установки-Web-клиента\Content\Modules.
Скопируйте каталог SamplesOutput\Site\Extensions\SampleWorkerExtension.ServerExtension в каталог Каталог-установки-Web-клиента\Extensions.
Перезапустите службу Web-клиента.

Проект "SampleWorkerExtension.WebClientServerExtension"

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

Разработка

При разработке собственного расширения необходимо дорабатывать или переписывать класс:

public class SampleEventHandlerService : EventHandlerService, ISampleEventHandlerService

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

  public static readonly EventDescription ConvertCardFiles = new EventDescription { Id = new Guid("B2C6F070-C7F1-4F07-914F-94652804DD1C"), AutoSendToSelf = true, Concurrent = false };

        private readonly Dictionary<Guid, EventHandlerInfo> handlersInfo = new Dictionary<Guid, EventHandlerInfo>
        {
            {
                ConvertCardFiles.Id,
                new EventHandlerInfo
                    { EventId = ConvertCardFiles.Id, EventArgsType = typeof(SampleEventArgs), EventHandlerName = nameof(ProcessCardFiles) }
            }
        };

Также при доработке компонента логики будет реализована своя логика обработки этих событий:

private const string SampleComponentTypeName = "SampleWorkerExtension.Manager.SampleApiManager, SampleWorkerExtension.Manager, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4a2caa47aa5b6b29";

Очередь сообщений

Служба фоновых операций версии 5.5.136 и выше поддерживает поиск сообщений с определенным типом сервиса. Для этого в своем расширении для фабрики задания нужно задать свойство MessageTypes. Все сообщения с этим типом будут передаваться для обработки.

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

Для формирования таймера или выполнения события по завершении промежутка времени можно использовать отложенные сообщения. Ниже дан пример формирования задания с отложенным исполнением:

EventService.RaiseDelayedEvent(approvalStage, ApprovalStage.NextTaskRequestedEvent.Id,
     new ApprovalStageNextTaskRequestedEventArgs
     {
         CardId = reconcileCard.GetObjectId(),
         PathId = approvalPath.GetObjectId(),
         StageId = approvalStage.GetObjectId()
     }, DateTime.Now);

Упрощённый подход

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

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

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

Если ваша логика добавляет задержки, использует асинхронные операции, упрощённый подход использовать не рекомендуется, поскольку это затормозит обработку существующих карточек (согласования, рассылка заданий). В этом случае потребуется реализовать полноценное собственное расширение. Однако пока Консоль управления Docsvision не поддерживает отображение и вывод своих настроек для расширения, обеспечить их считывание требуется самостоятельно.

Чтобы задать читаемое название для собственных сервисов, отображаемое в виджетах и на страницах Консоли управления Docsvision, потребуется реализовать собственный ResDescriptionAttribute, унаследованный от DescriptionAttribute. Реализация атрибута привязана к сборке и её ResourceManager.