-

docs/integration.rst

@@ -136,7 +136,7 @@ ARTA Synergy генерирует событие в случае,
 чтобы предоставить возможность
 в маршрут активации/изменения/удаления реестра
 вставить асинхронный вызов внешнего модуля.
-Основное отличие блокирующего процесса от `события реестра`_
+Основное отличие блокирующего процесса от событий реестра
 заключается в том, что:
 
 * при использовании блокирующего процесса маршрут реестра
@@ -560,12 +560,12 @@ REST API ARTA Synergy доступно только авторизованным
 
 .. tip::  Если у вас нет необходимости разрабатывать WEB модуль,
           но есть необходимость в использовании авторизации по ключам,
-          можно создать такой модуль на уровне БД и отключить его использование
+          можно добавить внешний модуль и отключить его использование
           в административном приложении SynergyAdmin для всех элементов оргструктуры.
 
 Использование этого ключа для авторизации аналогично использованию сессионного ключа.
 Тип авторизации ``Basic HTTP``,
-в качестве логина пользователя надо использовать строку «``$key``»,
+в качестве логина пользователя надо использовать строку ``$key``,
 в качестве пароля — полученный с помощью API ключ.
 
 Таким образом заголовок ``Authorization`` должен иметь значение:
@@ -582,3 +582,91 @@ REST API ARTA Synergy доступно только авторизованным
 
 Внешний WEB-модуль
 ------------------
+
+Web-приложение внешнего модуля открывается
+в ``iframe`` в окне основного приложения.
+При этом рабочая область внешнего модуля
+занимает всю область страницы, кроме панели меню и панели задач:
+
+.. figure:: _static/img/integration/web-module.png
+   :scale: 50%
+
+   Внешний WEB-модуль
+
+Для добавления нового модуля нужно перейти в
+
+:menuselection:`Конфигуратор --> Настройки системы --> Управление модулями --> Внешние модули`
+
+и нажать на кнопку "Добавить".
+
+.. figure:: _static/img/integration/web-modules.png
+
+   Внешние модули
+
+В открывшемся окне нужно заполнить следующие поля:
+
+* **«Название»** - название модуля в соответствующем интерфейсе.
+* **«Код»** - поле должно содержать уникальное значение.
+* **«Адрес приложения»** - поле для ввода URL.
+* **«Описание модуля»** - поле для описания данного модуля.
+* **«Иконка»** - задает иконку модуля в пользовательской подсистеме
+  (по умолчанию внешний модуль имеет стандартную иконку). Для того,
+  чтобы изменить стандартную иконку, нужно кликнуть по кнопке
+  «Выберите файл» и в диалоге выбора файла указать файл формата PNG,
+  размер которого не превышает 28х26.
+
+  .. figure:: _static/img/integration/web-module-add.png
+
+     Добавление нового внешнего модуля
+
+.. hint:: Однако, если необходимо, это можно сделать с помощью SQL-запроса
+          в таблицу `outer_modules`, вставив запись со следующими полями:
+
+              * ``id`` — идентификатор модуля, должен совпадать с идентификатором
+                 вашего проекта в репозитории проектов
+              * ``nameru``, ``namekz``, ``nameen`` — название модуля на русском,
+                казахском и английском языках соответственно
+              * ``url`` — адрес приложения
+              * ``description`` — описание модуля
+              * ``active`` — активен ли модуль, 1/0.
+
+Для реализации механизма :abbr:`SSO (Single Sign-On)` приложений,
+ARTA Synergy при загрузке интегрированного модуля
+будет в строку URL добавлять три параметра:
+
+#. ``locale`` — локаль авторизованного пользователя
+#. ``sso_hash`` — hash-сумма для идентификации пользователя.
+#. ``host`` — адрес, с которого загружено приложение Synergy
+
+Например, если URL приложения
+
+    ``http://host:port/plans_module``,
+
+то при обращении к модулю будет вызываться
+
+    ``http://host:port/plans_module?locale=locale_value&sso_hash=sso_hash_value``
+
+Интегрированный модуль должен будет будет получить из URL
+параметр ``sso_hash`` и запросить по REST API у ARTA Synergy
+информацию об авторизованном пользователе (идентификатор, имя).
+Если метод REST API возвращает информацию о пользователе,
+это подтверждает, что данный пользователь
+действительно авторизован с данного хоста, в данном браузере.
+
+Далее строка ``sso_hash`` может быть использована для
+`Сессионная авторизация`_ и вызова REST API Arta Synergy.
+
+В ARTA Synergy реализована возможность обращения к ее модулям по относительной ссылке.
+Такая же возможность существует для внешних web-модулей. Переход по ссылке вида:
+
+``#submodule=outer&outerModuleID='код_модуля'&прочие_параметры_по_желанию_модуля``
+
+активирует в Synergy заданный модуль и передаст ему заданные в url-e параметры
+(параметры ``locale``, ``sso_hash``, ``host`` также будут переданы,
+несмотря на то, что они отсутствуют в ссылке).
+
+Часто возникает необходимость в этой ссылке передать ссылку на текущий документ.
+Для этого можно добавить в ссылку параметр,
+значение которого будет равно ``${docID}`` —
+эта строка в web-интерфейсе проигрывателя форм Synergy
+будет заменена на идентификатор данного документа.