# Общие сведения и базовая настройка интеграции

Модуль интеграции и репликации используется для настройки информационного обмена между Global ERP и внешними информационными системами. Через модуль настраиваются каналы обмена, правила импорта и экспорта данных, расписания обработки, а также контроль выполнения интеграционных сессий.

Обмен может выполняться через доступные серверу каталоги и через web-сервисы. Конкретный способ передачи данных определяется настройками канала информационного обмена и прикладной реализацией интеграционного сценария.

Система фиксирует сессии импорта и экспорта в журналах. По журналам можно контролировать состояние обмена, видеть успешно обработанные объекты, ошибки обработки, повторные попытки и сообщения, по которым превышен лимит ошибок.

Основной пользовательский интерфейс модуля — приложение **Интеграция и репликация**. Перед настройкой импорта или экспорта обычно выполняются базовые действия: создается запись внешней системы, настраиваются метасхемы и XML-схемы, создается канал информационного обмена, указывается состав бизнес-объектов и настраивается расписание выполнения. Мониторинг выполняется после запуска канала и описан в отдельном разделе.

## Внешние системы и метасхемы

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

### Внешние системы

Справочник **Внешние системы** содержит перечень информационных систем, с которыми Global ERP обменивается данными. Записи справочника используются в каналах информационного обмена и в настройках идентификаторов внешних систем.

Путь: `Интеграция и репликация > Настройки > Внешние системы`.

| Поле | Описание |
|---|---|
| **Код** | Код внешней системы. |
| **Наименование** | Наименование внешней системы. |
| **Описание** | Дополнительное описание внешней системы. |

### Метасхемы обмена данными

Метасхема объединяет набор XML-схем, которые используются для формирования исходящих XML-файлов или разбора входящих XML-файлов. Метасхема задает допустимые версии XML-схем и связывает их с внешней системой, идентификаторами и правилами обработки.

Путь: `Интеграция и репликация > Настройки > Метасхемы`.

Метасхема для выгрузки должна включать схемы выгрузки XML-данных, которые участвуют в формировании файла. Метасхема для загрузки должна включать схемы загрузки XML-данных, которые используются при обработке входящего файла. Схемы XML-данных добавляются на вкладке **Допустимые версии**: каждая строка связывает метасхему с конкретной схемой и ее версией.

| Поле | Описание |
|---|---|
| **XML-схема** | Ссылка на схему загрузки или выгрузки XML-данных. |
| **Версия** | Версия схемы загрузки или выгрузки. Поле обязательно для заполнения: без версии при формировании или обработке XML-файла возникает ошибка. |
| **Условие** | В базовом сценарии не используется. |
| **Идентификатор версии** | Текстовый идентификатор версии. Его можно использовать в настройке схемы выгрузки как константу, например в поле **Значение/Функция** со значением `ClassID`. |
| **Основной класс** | Заполняется автоматически и показывает, что схема является основной в иерархии схем. |
| **Внешняя система для GUID** | Внешняя система, идентификатор которой нужно использовать при выгрузке. Настройка применяется, когда в файл нужно передать идентификатор Global ERP или идентификатор другой системы, сохраненный в атрибуте `jIdExt_dz`. |

![](img/rpl_metaschema_versions.jpg)

Если при выгрузке нужно передать внешний идентификатор, в поле **Внешняя система для GUID** указывается нужная внешняя система, а в настройках выгружаемых атрибутов в поле **Имя атрибута** указывается `jIdExt_dz`. Такая настройка применяется, когда внешний контур ожидает не внутренний идентификатор Global ERP, а идентификатор объекта в другой системе.

![](img/rpl_metaschema_external_guid.jpg)

### Проверка XML-схем

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

Для проверки загрузки XML-файлов используется операция **Загрузить из файла XML**. Она позволяет выбрать XML-файл с локального диска или из общей сетевой папки и проверить, как система обработает файл по настроенным схемам.

Для проверки выгрузки используется операция **Показать XML-структуру**. Она открывается из объекта системы, который в схеме формирования XML-файла является корневым объектом.

![](img/rpl_show_xml_structure_operation.jpg)

Если операция **Показать XML-структуру** не отображается в интерфейсе объекта, для соответствующей выборки должны быть активны операции `ACCEPTCLONE` и `ACCEPTROOT`.

```{note}
Активация операций выполняется через настройки проекта. Для изменения доступности операций требуются права администратора или разработчика.
```

## Каналы информационного обмена

Канал информационного обмена определяет правила обмена данными между Global ERP и внешней системой. В канале указывается внешняя система, направление обмена, способ обработки сообщений, список бизнес-объектов, параметры импорта и экспорта, а также настройки логирования и диагностики.

Путь: `Интеграция и репликация > Настройки > Каналы информационного обмена`.

Один канал может использоваться для импорта, экспорта или двустороннего обмена. По расписанию для канала открывается отдельная сессия обмена, а результаты обработки фиксируются в журнале.

### Основные параметры канала

Основные параметры идентифицируют канал и связывают его с заданием, которое будет запускать обмен. Эти поля заполняются до настройки импорта, экспорта и бизнес-объектов.

| Поле | Описание | Тип данных |
|---|---|---|
| **Системное имя** | Системное имя канала. | Текст |
| **Наименование** | Наименование канала. | Текст |
| **Тип контура** | Назначение канала, например репликация или внешняя XML-интеграция. | Ссылка на справочник типов каналов |
| **Агент** | Задание, которое управляет запуском канала. | Ссылка |
| **Описание** | Дополнительное описание канала. | Текст |

### Параметры интеграции

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

![](img/rpl_channel_integration_parameters.jpg)

| Поле | Описание | Тип данных |
|---|---|---|
| **Тип интеграции** | Формат интеграции, например JSON-интеграция или XML-интеграция. | Ссылка на справочник типов интеграции |
| **Тип обмена данными по интеграции** | Подтип типа интеграции. | Ссылка на справочник типов обмена |
| **Внешняя система** | Внешняя система, с которой выполняется обмен. | Ссылка на справочник внешних систем |
| **Работа контура через журнал** | Признак работы канала через журнал. Используется для совместимости с предыдущими вариантами интеграции. | Логический |
| **Функция генерации XML** | Функция, которая формирует XML-файл при XML-обмене. Базовая функция — `Rpl_GenerateMessagePkg().genXMLStub`. | Текст |
| **Функция загрузки XML** | Функция загрузки XML. Используется в сценариях совместимости. | Текст |
| **Функция интеграции** | Основной метод, который запускается при старте работы канала по расписанию, например `Rpl_RunIntegrationPkg.run("системное имя контура")`. | Текст |
| **Функция подтверждения импорта** | Метод, который выполняется после импорта и на основе логов подтверждает импорт для внешней системы. | Текст |
| **Хранить лог сессий, дней** | Количество дней хранения лога сессий информационного обмена. | Число |
| **Проводить диагностику** | Включает диагностику канала через функцию диагностики. | Логический |
| **Функция диагностики** | Пользовательская процедура с типом **Функция диагностики контура интеграции**. | Ссылка на пользовательскую процедуру |
| **Хранить лог самодиагностики, дней** | Срок хранения лога диагностики. | Число |
| **Лимит ошибочной отправки** | Количество попыток отправки сообщения, после которого сообщение считается остановленным по лимиту ошибок. | Число |

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

### Бизнес-объекты канала

На вкладке **Бизнес-объекты** указывается перечень бизнес-объектов Global ERP, которые участвуют в обмене по каналу. Для экспорта этот список определяет, какие объекты подписываются на отправку при изменении данных. Для импорта он помогает связать канал с классами, которые обрабатываются в рамках обмена.

| Поле | Описание | Тип данных |
|---|---|---|
| **Класс-шапка бизнес-объекта** | Системное имя и наименование основного бизнес-объекта. | Ссылка на список бизнес-объектов |
| **Условия фильтрации** | SQL-условие, которое ограничивает объекты для обмена. Условие добавляется после оператора `WHERE`, основная таблица имеет алиас `t`. | Текст |
| **Условия фильтрации post-data** | Условие фильтрации объектов при подписании на канал с учетом новых и старых значений атрибутов. | Текст |
| **Очередность экспорта** | Порядок экспорта объектов в рамках сессии. Объекты с меньшим номером обрабатываются раньше. | Число |

В составе бизнес-объекта перечисляются классы Global ERP, которые входят в бизнес-объект и участвуют в обмене. Для каждого класса можно указать атрибуты, изменение которых приводит к подписанию объекта на экспорт.

| Поле | Описание | Тип данных |
|---|---|---|
| **Класс** | Системное имя и наименование класса. | Ссылка на класс |
| **Наименование** | Наименование атрибута. | Текст |
| **Логируется** | Если признак установлен, изменение атрибута приводит к подписанию объекта на канал. | Логический |
| **Сохранять старое значение** | Если признак установлен, система сохраняет старое значение атрибута для фильтрации объектов при подписании. | Логический |

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

### Пример параметров импорта через каталог

Параметры канала могут храниться в JSON. Такой формат используется для передачи системных имен методов, признаков включения импорта и экспорта, файлового хранилища и ограничений на объем обработки. Ниже приведен пример JSON-параметров для загрузки данных из каталога, доступного серверу, и обработки данных стандартным методом XML-схем.

```json
{
  "sMetaSchema": "10",
  "sProcessIncomingMessageMethod": "Rpl_ProcessIncomingMessagePkg.processIncomingMessageByBts_Schema",
  "sGetMessageForImport": "Rpl_IntXmlImportApiPkg.createIntXmlInByFilesInFolder",
  "sMainClassMnemoCode": "Bs_Person",
  "sFileStorage": "impFrom1C",
  "sFolderPath": "Bs_Person",
  "nMaxObjectToImportCount": "1000",
  "bExport": "0",
  "bImport": "1"
}
```

| Параметр | Описание |
|---|---|
| `sMetaSchema` | Метасхема, которая используется для обработки данных. |
| `sProcessIncomingMessageMethod` | Метод обработки входящих данных. |
| `sGetMessageForImport` | Метод получения данных для импорта. |
| `sMainClassMnemoCode` | Системное имя класса-шапки бизнес-объекта, который обрабатывается в канале. |
| `sFileStorage` | Системное имя файлового хранилища Global ERP. |
| `sFolderPath` | Путь хранения данных внутри файлового хранилища. |
| `nMaxObjectToImportCount` | Количество объектов, которые обрабатываются в рамках одной сессии. |
| `bExport` | Признак включения экспорта на канале. |
| `bImport` | Признак включения импорта на канале. |

Если канал должен не только принимать данные, но и отправлять ответ во внешнюю систему, используется метод обработки `Rpl_ProcessIncomingMessagePkg.processIncomingMessageAndCreateAnswer`, а параметр `bExport` устанавливается в значение `1`.

Для отправки ответов дополнительно указываются параметры отправки, например:

| Параметр | Описание |
|---|---|
| `sSendMessageMethod` | Метод отправки сообщения, например `Rpl_SendWebRequestPkg().sendPackageRequest`. |
| `sWebAddress` | Адрес web-сервиса внешней системы. |
| `sWebUser` | Пользователь для авторизации, если она требуется. |
| `sWebPassword` | Пароль пользователя для авторизации, если она требуется. |
| `nPackageCount` | Количество сообщений в пакете отправки. |

## Менеджер заданий

Менеджер заданий используется для автоматического запуска интеграционных процедур по расписанию. В рамках интеграции через него выполняются задания импорта, экспорта и подписания измененных объектов на контур. Если соответствующее задание не включено, обмен не запускается автоматически, даже если канал интеграции и XML-схемы настроены.

Путь: `Интеграция и репликация > Менеджер заданий`.

Для интеграционного обмена могут использоваться следующие задания:

- **Агент XML-Snapshot** — подписывает измененные пользователями объекты на каналы интеграции при сохранении изменений;
- **Экспорт** — формирует файлы или сообщения с измененными объектами и передает их во внешнюю систему;
- **Импорт** — получает файлы или сообщения, запускает их разбор и запись данных в базу данных.

Для запуска канала интеграции по расписанию выберите `pgagent`, найдите задание по имени канала, проверьте настройки и включите задание операцией **Включить выделенные задания**. История выполнения выбранного задания отображается на вкладке **Журнал**.

```{note}
Менеджер заданий подключается и настраивается для конкретной базы данных. Если менеджер заданий недоступен или задание не запускается по расписанию, необходимо обратиться к администратору инфраструктуры.
```
Подробное описание создания заданий, настройки расписаний и работы с журналом приведено в разделе [Менеджер заданий](https://help.globalerp.ru/books/User_guide_system/SNAPSHOT/html/0020_3.%20%D0%9C%D0%B5%D0%BD%D0%B5%D0%B4%D0%B6%D0%B5%D1%80%20%D0%B7%D0%B0%D0%B4%D0%B0%D0%BD%D0%B8%D0%B9.html#).

## Web-сервисы и сервисные учетные записи

Web-сервисы используются, когда внешняя система обращается к Global ERP напрямую или когда Global ERP отправляет сообщения во внешнюю систему по HTTP. В таких сценариях канал информационного обмена дополняется параметрами адреса, пользователя, пароля и метода отправки или обработки сообщения. Адреса в примерах приведены как шаблоны настройки и заменяются на адреса конкретного стенда.

### Формат URL для загрузки сообщений

Web-сервисы для приема сообщений преднастроены. Адрес для помещения сообщений в контур обмена формируется по имени сервера, имени базы данных и системному имени контура.

```text
http://test.gs.local/TESTDB/app/sys/rest/ss/pkg/Rpl_RequestHandlerPkg/sendMessage?circuitName=Test
```

В примере:

- `test.gs.local` — адрес сервера Global ERP;
- `TESTDB` — имя базы данных;
- `Rpl_RequestHandlerPkg` — пакет, в котором находится обработчик запроса;
- `sendMessage` — метод помещения сообщения в контур обмена;
- `Test` — системное имя контура.

Адрес для принудительного запуска контура интеграции формируется аналогично.

```text
http://test.gs.local/TESTDB/app/sys/rest/ss/pkg/Rpl_RequestHandlerPkg/schedule?circuitName=Test
```

Если внешняя система должна получать ответы от Global ERP при импорте, в параметрах интеграции указывается адрес web-сервиса внешней системы.

```text
http://uloportal.gs.local:8080/app/sys/rest/ss/pkg/Rpl_RequestHandlerPkg/sendMessage
```

```{attention}
Регистр подстановочных значений в URL должен совпадать с ожидаемыми значениями.
```

### Авторизация

Для использования сервисов передаются пользователь и пароль пользователя Global ERP. Учетные данные могут передаваться в параметрах канала или в заголовках web-сервиса, в зависимости от конкретного сценария интеграции.

Для интеграционных сценариев рекомендуется использовать выделенные сервисные учетные записи. Такой пользователь применяется при обращении внешних систем к web-сервисам Global ERP и при отправке сообщений из Global ERP во внешние системы.

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

### Параметры сервисной учетной записи

В параметрах канала могут использоваться следующие настройки:

| Параметр | Описание |
|---|---|
| `sWebUser` | Пользователь, под которым выполняется обращение к web-сервису. |
| `sWebPassword` | Пароль пользователя. |
| `sWebAddress` | Адрес web-сервиса внешней системы или Global ERP. |
| `sSendMessageMethod` | Метод отправки сообщения. |

## Перенос настроек интеграции

Готовые схемы обработки данных можно перенести в другую систему в формате JSON или средствами [менеджера конфигурации](https://help.globalerp.ru/books/GlobalUserGuideSystemWide/SNAPSHOT/html/service/0100_%D0%BC%D0%B5%D0%BD%D0%B5%D0%B4%D0%B6%D0%B5%D1%80_%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D0%B8.html). Перенос используется, когда нужно повторно использовать настроенные схемы загрузки или выгрузки без ручного создания всей иерархии, например при переносе настроек между тестовой и промышленной средой.

### Выгрузка схемы в JSON

Для формирования JSON-файла:

1. Откройте приложение **Интеграция и репликация**.
2. Перейдите в меню **Настройки**.
3. Откройте список схем загрузки или выгрузки XML-данных.
4. Выберите нужную схему.
5. На панели инструментов или в контекстном меню выберите **Дополнительные операции > Создать JSON файл**.

![](img/rpl_create_json_from_toolbar.jpg)

В JSON-файл можно выгрузить одну схему или группу схем, объединенных в иерархию. Если нужно перенести всю иерархию, выберите головную схему.

### Загрузка схемы из JSON

После создания JSON-файла перенесите его в доступную директорию целевой системы. Для создания схемы на основе JSON-файла:

1. Откройте приложение **Интеграция и репликация** в целевой системе.
2. Перейдите в список схем загрузки или выгрузки XML-данных.
3. На панели инструментов или в контекстном меню выберите **Дополнительные операции > Заполнить из JSON**.
4. Выберите способ загрузки:
   - **Как корневую запись** — если схема должна быть создана как новая верхнеуровневая схема;
   - **Под текущую запись** — если схема должна быть создана как дочерняя для выбранной схемы.

![](img/rpl_fill_from_json_toolbar.jpg)