Внешний клиент задач (External Task Client)

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

Внешний клиент задач OpenBPM Engine (OpenBPM Engine External Task Client) позволяет настраивать удалённые сервисные задачи для вашего workflow. Доступна поддерживаемая Java-реализация а также JavaScript-реализация.

Возможности

  • Завершение внешних задач (External Tasks)

  • Продление времени блокировки (lock duration) внешних задач

  • Разблокировка внешних задач

  • Сообщение об ошибках BPMN и сбоях (failures)

  • Обмен переменными с Workflow Engine

Инициализация клиента

Архитектура внешнего клиента задач (External Task Cient Architecture)

Клиент позволяет обрабатывать сервисные задачи типа "external". Для конфигурации и создания (instantiate) клиента все поддерживаемые реализации предоставляют удобный интерфейс. Взаимодействие между клиентом и OpenBPM Engine Workflow Engine осуществляется по HTTP. Поэтому соответствующий URL REST API является обязательной информацией.

Перехватчики запросов (Request Interceptors)

Чтобы добавлять дополнительные HTTP-заголовки к выполняемым REST API-запросам, можно использовать метод перехватчика запросов. Это становится необходимым, например, в контексте аутентификации.

Basic Authentication

В некоторых случаях необходимо защитить REST API OpenBPM Engine Workflow Engine с помощью Basic Authentication. Для таких ситуаций клиентом предоставляется реализация Basic Authentication. После настройки учётных данных пользователя заголовок basic authentication добавляется к каждому REST API-запросу.

Пользовательский перехватчик (Custom Interceptor)

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

Подписка на топик (Topic Subscription)

Если в workflow размещена Service Task типа "External", необходимо указать имя топика (topic name). Соответствующий BPMN 2.0 XML может выглядеть следующим образом:

...
<serviceTask id="checkCreditScoreTask"
  name="Check credit score"
  camunda:type="external"
  camunda:topic="creditScoreChecker" />
...

Как только Workflow Engine достигает External Task в BPMN-процессе, создаётся соответствующий экземпляр активности (activity instance), который ожидает, пока клиент выполнит выборку (fetch) и установит блокировку (lock).

Клиент подписывается на топик и непрерывно выполняет выборку вновь появляющихся External Tasks, предоставляемых Workflow Engine. Каждая полученная External Task помечается временной блокировкой. Таким образом, никакие другие клиенты не могут работать над этой конкретной External Task в течение этого времени. Блокировка действительна в течение указанного периода времени и может быть продлена.

При настройке новой подписки на топик обязательно указать имя топика и функцию-обработчик (handler function). После подписки на топик клиент может начать получать элементы работы (work items), опрашивая API process engine.

Обработчик (Handler)

Обработчики используются для реализации пользовательских методов, которые вызываются каждый раз, когда External Task успешно выбрана (fetched) и заблокирована (locked). Для каждой подписки на топик предоставляется интерфейс обработчика External Task.

Обработчики вызываются последовательно для каждой внешней задачи, которая была выбрана и заблокирована.

Завершение задач (Completing Tasks)

После завершения пользовательских методов, определённых в обработчике, External Task можно завершить. Для Workflow Engine это означает, что выполнение продолжится дальше. Для этого во всех поддерживаемых реализациях есть метод complete, который можно вызвать внутри функции-обработчика. Однако External Task может быть завершена только в том случае, если в данный момент она заблокирована этим клиентом.

Продление времени блокировки задач (Extending the Lock Duration of Tasks)

Иногда выполнение пользовательских методов занимает больше времени, чем ожидалось. В этом случае необходимо продлить время блокировки. Это действие можно выполнить, вызвав метод extendLock и передав новое значение времени блокировки. Время блокировки можно продлить только в том случае, если External Task в данный момент заблокирована этим клиентом.

Разблокировка задач (Unlocking Tasks)

Если External Task необходимо разблокировать, чтобы другие клиенты снова могли выбрать (fetch) и заблокировать (lock) эту задачу, можно вызвать метод unlock. External Task может быть разблокирована только в том случае, если задача в данный момент заблокирована этим клиентом.

Сообщение о сбоях (Reporting Failures)

Если клиент сталкивается с проблемой, из-за которой невозможно успешно завершить External Task, об этой проблеме можно сообщить Workflow Engine. О сбое можно сообщить только в том случае, если External Task в данный момент заблокирована этим клиентом. Подробную документацию по этому действию см. в OpenBPM Engine User Guide.

Сообщение об ошибках BPMN (Reporting BPMN Errors)

Пограничные события ошибок (Error boundary events) срабатывают при BPMN-ошибках. BPMN-ошибку можно сообщить только в том случае, если External Task в данный момент заблокирована этим клиентом. Подробную документацию по этому действию см. в OpenBPM Engine User Guide.

Переменные (Variables)

Оба клиента внешних задач совместимы со всеми типами данных, которые OpenBPM Engine поддерживает. Доступ к переменным и их изменение возможны через типизированный (typed) или нетипизированный (untyped) API.

Процессные и локальные переменные (Process and Local Variables)

Переменные могут рассматриваться как процессные или локальные переменные. Первые устанавливаются на максимально возможном уровне иерархии области видимости переменной (variable scope) и доступны дочерним областям видимости по всему процессу. Если же переменную, напротив, нужно установить строго в предоставленной области выполнения (execution scope), можно использовать локальный тип.

Установка переменных не гарантирует их сохранение (persisted). Переменные, которые были установлены локально на стороне клиента, доступны только во время выполнения (runtime) и будут потеряны, если они не будут переданы (shared) в Workflow Engine посредством успешного завершения External Task в рамках текущей блокировки.

Нетипизированные переменные (Untyped Variables)

Нетипизированные переменные сохраняются с использованием соответствующего типа их значений. Можно сохранять/получать как одну переменную, так и несколько переменных одновременно.

Типизированные переменные (Typed Variables)

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

Пример: использование типизированных переменных JSON, XML и Object
// obtained via subscription
ExternalTaskService externalTaskService = ..;
ExternalTask externalTask = ..;

VariableMap variables = Variables.createVariables();

JsonValue jsonCustomer = externalTask.getVariableTyped("customer");
// deserialize jsonCustomer.getValue() to customer object
// and modify ...
variables.put("customer", ClientValues.jsonValue(customerJsonString));

XmlValue xmlContract = externalTask.getvariableTyped("contract");
// deserialize xmlContract.getValue() to contract object
// and modify ...
variables.put("contract", ClientValues.xmlValue(contractXmlString));

TypedValue typedInvoice = externalTask.getVariableTyped("invoice");
Invoice invoice = (Invoice) typedInvoice.getValue();
// modify invoice object
variables.put("invoice", ClientValue.objectValue(invoice)
    .serializationDataFormat("application/xml").create();

externalTaskService.complete(externalTask, variables);

Логирование (Logging)

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

  • External Tasks не удалось успешно выбрать (fetch) и заблокировать (lock)

  • Произошло исключение…​

  • при вызове обработчика

  • при десериализации переменных

  • при вызове перехватчика запросов

  • …​

Подробнее см. документацию по интересующему вас клиенту.

Доступ к внутреннему Apache HttpClientBuilder

Если требуется ещё более тонко настроить взаимодействие клиента, вы можете получить доступ к Apache HttpClientBuilder, используя метод customizeHttpClient у ExternalTaskClientBuilder. Метод принимает параметром Consumer, который даёт доступ к внутреннему Apache HttpClientBuilder:

ExternalTaskClient.create()
  .baseUrl("localhost")
  .customizeHttpClient((HttpClientBuilder httpClientBuilder) ->
    httpClientBuilder.setDefaultRequestConfig(RequestConfig.custom()
      .setResponseTimeout(Timeout.ofSeconds(30))
      .build()))
  .build();

Примеры

Полные примеры настройки различных External Task Clients можно найти на GitHub (Java, JavaScript).

Пропускная способность внешних задач (External task throughput)

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

Практическое правило (rule of thumb) для длительно выполняющихся задач (возможно, более 30 секунд): выбирать и блокировать задачи по одной (maskTasks = 1) и настроить интервал Long Polling под ваши нужды (например, 60 секунд, asyncResponseTime = 60000). Java-клиент поддерживает экспоненциальную задержку (exponential backoff): по умолчанию 500 мс с коэффициентом 2, ограниченную значением 60000 мс. Это также можно сократить под ваши нужды.

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

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org