-

docs/index.rst

@@ -17,3 +17,4 @@
    interpreter
    extcmp
    dashboards
+   integration

docs/integration.rst

+Способы интеграции
+==================
+
+Существует два основных подхода для интеграции с Synergy:
+
+* Прямая интеграция — интеграционные модули разрабатываются
+  с использованием API Synergy и интегрируемых систем.
+  Синхронизация данных между системами и координация обмена между ними
+  остаётся за разработчиком интеграционного модуля
+
+* Событийная интеграция — когда какая-либо из подсистем Synergy
+  генерирует различные события, связанные с какими-либо данными.
+  Обработчики этих событий (на стороне Synergy) при необходимости
+  преобразовывают данные событий и передают их интегрируемой системе
+  через какой-либо транспортный уровень
+
+Прямая интеграция
+-----------------
+
+ARTA Synergy предоставляет API для доступа к своим функциям
+с помощью rest сервисов. Описание методов API можно
+посмотреть в javadoc.
+Авторизация для всех методов API — ``Basic HTTP``.
+
+Событийная интеграция
+---------------------
+
+Под «событием» мы будем подразумевать сообщение о каком-либо изменении
+в Arta Synergy, содержащее тип события
+и минимально необходимые для получения связанной с событием информации
+либо воздействия на Synergy данные. Обработчик события (или событий) —
+программный модуль, читающий сообщения о событиях из ``JMS Queue`` или ``JMS Topic``
+и осуществляющий, при необходимости, доступ к экземпляру Synergy,
+сгенерировавшему сообщение, с помощью API Synergy.
+
+Обработчик событий является отдельным от Arta Synergy приложением,
+которое может работать как на том же сервере приложений,
+что и Arta Synergy, так и на удалённом.
+
+Кроме этого, обработчик события может иметь собственные конфигурационные файлы,
+необходимые для реализации целевого назначения.
+
+Обработчик событий может обрабатывать как конкретное событие
+(например, ``event.registers.formdata.add``),
+так и класс событий (например, ``event.registers.*``).
+
+Обработка события может происходить в 3 этапа:
+
+1. Получение события
+2. Получение и преобразование необходимых обработчику данных
+3. Передача сформированного пакета данных далее (опционально)
+
+ARTA Synergy генерирует событие в случае,
+если для этого события настроены обработчики.
+Обработчики событий настраиваются в конфигурационном файле
+``${jboss.home}/standalone/configuration/arta/api-observation-configuration.xml``.
+
+Сообщение, помещаемое в очередь ``JMS``,
+представляет собой экземпляр ``javax.jms.TextMessage``.
+Тело сообщения зависит от типа события,
+его описание можно посмотреть ниже среди описаний типов событий.
+Каждое событие содержит свойство ``api_event``, указывающее на тип события,
+вызвавшего его (содержимое тега ``<event>event.registers.formdata.add</event>`` в конфигурационном файле).
+
+Например:
+
+.. code-block:: xml
+
+    <configuration>
+        <listener>
+            <queue>java:jboss/queues/Synergy/UsersQueue</queue>
+            <event>event.users.*</event>
+        </listener>
+        <listener>
+            <queue>java:jboss/queues/Synergy/RegisterCreateDocQueue</queue>
+            <event>event.registers.formdata.add</event>
+        </listener>
+    </configuration>
+
+В этом примере настроены обработчики:
+
+1. ``java:jboss/queues/Synergy/UsersQueue`` для всех событий класса
+   ``event.users.*``, т.е. всех событий, связанных с пользователями:
+   ``event.users.account.change``,
+   ``event.users.formdata.change``,
+   ``event.users.account.add`` и т.д.
+2. ``java:jboss/queues/Synergy/RegisterCreateDocQueue``
+    для события добавления записи реестра ``event.registers.formdata.add``.
+
+Рассмотрим, например, код обработчика очереди ``UsersQueue``:
+
+.. code-block:: java
+
+    public class UsersMessagesListener implements MessageListener {
+
+        public void onMessage(Message message) {
+            //Получаем идентификатор пользователя, для которого
+            //сгенерировано событие
+            String userID = ((TextMessage) message).getText();
+            //Получаем тип события
+            String eventType = message.getStringProperty("api_event");
+
+            //Выполнение действие по получению дополнительных данных через API
+            //и прочих операций, зависящих от условий решаемой задачи
+        }
+    }
+
+Ниже описаны типы событий, которые могут быть сгенерированы ARTA Synergy.
+
+Для события ``[event.orgstructure.department.formdata.change]`` -
+идентификатор подразделения, для события
+``[event.orgstructure.position.formdata.change]`` - идентификатор
+должности, для события ``[event.users.formdata.change]`` - идентификатор
+пользователя будет передаваться как основной параметр, остальные как
+свойства. Получить их можно следующим образом:
+
+.. code-block:: java
+
+    public void onMessage(Message message) {
+        //Получение идентификатора пользователя/должности/подразделения (В зависимости от события на которое подписаны)
+        String userID = ((TextMessage) message).getText();
+        //Получаем идентификатор формы
+        String formUUID = message.getStringProperty("formUUID");
+    }

docs/interpreter/api.rst

@@ -51,7 +51,7 @@
 .. js:data:: key
 
     Ключ пользователя, от имени которого выполняется данный скрипт
-    (указывается в настройках скрипт)
+    (указывается в настройках скрипта)
 
 .. hint:: Типовое начало скрипта выглядит так: