-

docs/integration.rst

@@ -337,6 +337,164 @@ ARTA Synergy генерирует событие в случае,
         }
     }
 
+Дополнительный обработчик для стандартного процесса
+---------------------------------------------------
+
+Цель данного вида интеграции — дать возможность повлиять на
+запуск стандартного процесса и, при необходимости, прервать его.
+
+Стандартная функциональность платформы ARTA Synergy дает возможность запретить
+отправку документов на согласование, утверждение, если количество уровней
+оргструктуры между отправителем и получателем превышает некоторое
+настроенное значение. Но в некоторых компаниях существуют более сложные
+правила, ограничивающие возможность отправки документов/работ. В этих
+случаях необходима разработка данного обработчика.
+
+Обработчик может быть применён к процессам:
+
+*   «работа» (`assignment-single`)
+*   «согласование» (`agreement-single`)
+*   «утверждение» (`approval-single`)
+*   «ознакомление» (`acquaintance-single`)
+*   «отправка документа» (`send-document`)
+*   «общий процесс при запуске по формам» (`common-process-by-form`)
+*   «отправка документа по форме» (`send-document-by-form`)
+
+Обработчик представляет собой Java-класс, реализующий интерфейс
+
+``kz.arta.synergy.integration.api.bp.StartHandlerIF``.
+
+Данный интерфейс находится в библиотеке ``integration-api.jar``,
+которую можно найти в установленном экземпляре ARTA Synergy в директории
+``/opt/synergy/jboss/standalone/deployments/Synergy.ear/lib``.
+
+Интерфейс содержит два метода:
+
+*   ``makeDecision()`` — проверяет возможно ли выполнение процесса
+*   ``getResolution()`` — возвращает текст, который должен быть записан в ход
+    исполнения
+
+Более подробную информацию о полях методов можно посмотреть в javadoc
+к этим методам, которые доступны в `integration-api.jar` (библиотека
+содержит и скомпилированные классы, и исходный код).
+
+Установка обработчика для процесса осуществляется с помощью
+конфигурационного файла
+``${jboss.server.config.dir}/arta/process-handlers-configuration.xml``,
+имеющего следующий формат:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <process-handlers-configuration
+      xmlns="http://www.arta.kz/xml/ns/ai"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://www.arta.kz/xml/ns/arta
+      http://www.arta.kz/xml/ns/ai/process-handlers-configuration .xsd">
+     <handlers>
+         <handler>
+             <process>assignment-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+         <handler>
+             <process>agreement-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+         <handler>
+             <process>approval-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+         <handler>
+             <process>acquaintance-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+         <handler>
+             <process>send-document</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+     </handlers>
+    </process-handlers-configuration>
+
+
+Обработчики выполняются последовательно до тех пор, пока метод
+``makeDecision()`` одного из них не вернет ``false``, после этого процесс
+прерывается.
+
+Библиотеку, содержащую обработчик необходимо скопировать в папку
+``/opt/synergy/jboss/standalone/deployments/Synergy.ear/lib``.
+
+После копирования библиотеки обработчика и изменения файла
+``process-handlers-configuration.xml`` необходимо перезапустить JBoss.
+
+.. attention:: Процесс ``common-process-by-form`` запускает процессы
+               ``agreement-single``, ``approval-single``, ``acquaintance-single``,
+               ``assignment-single`` (подпроцессы). Поэтому, если обработчик будет
+               запрещать выполнение подпроцесса и при этом разрешать выполнение процесса
+               ``common-process-by-form``, то подпроцессы все равно будут прерваны.
+               Аналогично, если выполнение ``common-process-by-form`` разрешено, а
+               выполнение подпроцесса запрещено, подпроцессы будут прерваны.
+
+Пример использования
+~~~~~~~~~~~~~~~~~~~~
+
+С использованием этого способа интеграции был реализован внешний модуль,
+ограничивающий перепоручение и отправку каких-либо работ на согласование
+пользователям определенных групп.
+
+Для установки внешнего модуля из репозитория необходимо установить пакет
+``arta-synergy-ext-sendcontrol``.
+
+Далее на остановленном JBoss в конфигурационном файле
+``${jboss.server.config.dir}/arta/process-handlers-configuration.xml``
+необходимо прописать следующие обработчики процесса:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <process-handlers-configuration
+      xmlns="http://www.arta.kz/xml/ns/ai"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://www.arta.kz/xml/ns/arta
+      http://www.arta.kz/xml/ns/ai/process-handlers-configuration .xsd">
+     <handlers>
+         <handler>
+             <process>assignment-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+         <handler>
+             <process>agreement-single</process>
+             <handler-providers>kz.arta.synergy.ext.blocking.SendControlHandler</handler-providers>
+         </handler>
+     </handlers>
+    </process-handlers-configuration>
+
+Установка групп (каким группам пользователей Synergy) разрешать либо
+блокировать процессы осуществляется с помощью конфигурационного файла
+``${jboss.server.config.dir}/arta/ext/send-control.xml``. Пример настройки:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <send-control>
+
+        <!--
+            Идентификаторы групп, членам которых разрешено отправлять
+            что-либо из блоков `deny`
+        -->
+        <from>
+            <allow>35</allow>
+        </from>
+
+        <!--
+            Идентификаторы групп, членам которых могут отправлять что-либо
+            только пользователи групп из блоков `allow`, если таковые есть.
+            В противном случае, никто ничего этим пользователям отправить
+            не сможет.
+        -->
+        <to>
+            <deny comment="Вы не можете отправлять что-либо на согласование данному пользователю">111</deny>
+        </to>
+    </send-control>
 
 Способы авторизации в ARTA Synergy
 ----------------------------------