# Настройка экспорта и импорта Раздел описывает настройку обмена данными по XML-схемам: регистрацию объектов для экспорта, формирование исходящих XML-файлов, разбор входящих XML-файлов, загрузку прикрепленных файлов и отдельные нестандартные сценарии импорта. Перед настройкой экспорта и импорта должны быть созданы внешняя система, метасхемы и канал информационного обмена. ## Настройка экспорта Экспорт используется для передачи данных из Global ERP во внешнюю систему. Экспорт настраивается через канал информационного обмена, бизнес-объекты канала, правила подписания измененных объектов и XML-схемы выгрузки. В результате настройки система определяет, какие объекты нужно отобрать, в каком порядке их обработать и какую XML-структуру сформировать для внешней системы. ### Регистрация изменившихся объектов Автоматическая регистрация изменившихся объектов настраивается на вкладке **Бизнес-объекты** в карточке канала информационного обмена. Эта настройка определяет, какие объекты должны попадать в экспорт при изменении данных, и позволяет ограничить выгрузку только значимыми для внешней системы изменениями. Для настройки регистрации изменившихся объектов: 1. На вкладке **Бизнес-объекты** в столбце **Класс-шапка бизнес-объекта** укажите классы бизнес-объектов, по которым нужно отслеживать изменения. 2. В столбце **Условие фильтрации** задайте SQL-условие, которое ограничивает записи для экспорта в рамках канала. Условие добавляется после оператора `WHERE`. 3. Если выгружается несколько бизнес-объектов, в столбце **Очередность экспорта** укажите порядок обработки. Объект с меньшим номером выгружается раньше. 4. На вкладке **Состав** добавьте классы, входящие в бизнес-объект: основной класс и необходимые коллекции. 5. На вкладке **Атрибуты** отметьте в столбце **Логируется** атрибуты, изменение которых должно подписывать объект на экспорт. ### Схемы выгрузки XML-файлов Схемы выгрузки описывают, как данные объектов Global ERP преобразуются в XML-файл. В схеме задается основной класс, метод выгрузки, версии XML-схемы и правила формирования тегов или атрибутов XML. Путь: `Интеграция и репликация > Настройки > Схемы выгрузки`. Для настройки схемы выгрузки: 1. Откройте список схем выгрузки. 2. Создайте новую схему и заполните ее основные поля. 3. В правой верхней области создайте версию XML-схемы. 4. Для версии задайте перечень атрибутов, которые нужно выгружать в XML-файл. 5. Для каждого выгружаемого атрибута задайте правило формирования значения. 6. Если в файл нужно выгрузить составной бизнес-объект, создайте дочернюю схему. Связь объектов разных классов определяется связью, заданной в бизнес-объекте. ### Основные поля схемы выгрузки Основные поля схемы определяют класс, из которого берутся данные, и способ получения дочерних объектов. Для корневой схемы обычно используется метод `load`, а для вложенных схем — методы, которые связывают дочерние данные с родительским объектом. | Поле | Описание | |---|---| | **Код** | Уникальный код схемы. Обязателен для заполнения. | | **Наименование** | Наименование схемы. | | **Основной класс** | Класс, из которого выгружаются данные по схеме. | | **Метод загрузки** | Метод обработки схемы. Для корневой схемы используется `load`; для дочерней схемы-коллекции — `byParent`; для дочерней схемы, которая не является прямой коллекцией предка, — `select`. | | **Примечание** | Описание схемы. | | **Условие** | SQL-условие для ограничения данных текущей схемы. Условие добавляется в блок `WHERE`; атрибуты основного класса указываются с алиасом `t`, например `t.id`. | | **Запрос потомков** | SQL-запрос, который возвращает список `id` объектов дочерней схемы. Используется для метода `select`. | Для корневой схемы ограничение данных выполняется не через поле **Условие** в схеме, а через **Условие фильтрации** бизнес-объекта в настройке канала. ### Настройка версии XML-схемы В версии XML-схемы указываются параметры XML-структуры, которая будет сформирована при выгрузке. Версия позволяет поддерживать несколько вариантов структуры для одной схемы и выбирать нужный вариант через метасхему. | Поле | Описание | |---|---| | **№** | Порядковый номер. Заполняется автоматически. | | **Наименование** | Наименование версии. | | **Обобщающий XML-тег** | Тег, который объединяет несколько однотипных записей, например позиции документа. | | **XML-тег** | Тег, который соответствует позиции основного класса схемы. Значения атрибутов могут быть помещены внутрь этого тега как дочерние теги или как атрибуты XML-тега. | Пример обобщающего XML-тега: ```xml <Документ> <Наименование>Система вентиляции <ПозицииДокумента> <Позиция НомерПозиции="1"/> <Позиция НомерПозиции="2"/> <Позиция НомерПозиции="3"/> <Позиция НомерПозиции="4"/> ``` Если в XML-файле формируются пустые значения с `xsi:nil="true"`, в корневой тег должен быть добавлен атрибут `xmlns:xsi` со значением `http://www.w3.org/2001/XMLSchema-instance`. ```xml <ЭлементНоменклатуры xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <КлючевыеСвойства> <Ссылка>76501/60 <НаименованиеПолное>Шайба 40Х13 ГОСТ 5632-72 24.4x13 ГОСТ 13465-77 <КодВПрограмме>01992134024 <КодТНВЭД xsi:nil="true"/> <ТипТМЦ xsi:nil="true"/> <ВидВедомости xsi:nil="true"/> ``` ### Настройка атрибутов выгрузки Атрибуты настраиваются в детализации версии XML-схемы. Каждая строка определяет, какой тег или атрибут XML будет создан и откуда система возьмет его значение. За счет разных источников можно выгружать прямые атрибуты объекта, значения связанных объектов, константы, результаты SQL-запросов, JEXL-выражений и прикрепленные файлы. | Поле | Описание | |---|---| | **№** | Порядок добавления тегов в XML. | | **XML-тег** | Имя тега или атрибута XML. | | **Тип тега** | Способ записи значения: **Нода**, **Атрибут** или **Рутовая нода**. Значение **Рутовая нода** в базовом сценарии не используется. | | **Источник** | Источник значения: атрибут класса, атрибут ссылочного класса, константа, функция, SQL-текст, SQL-текст XML, JEXL-текст или файл `Btk_File`. | | **Имя атрибута** | Системное имя атрибута основного класса. | | **Имя атрибута ссылочного класса** | Системное имя атрибута ссылочного класса. | | **Формат** | Шаблон форматирования значения. Для атрибутов типа `Date` формат обязателен, например `dd.MM.yyyy`. | | **Значение/Функция** | Константа или функция, которая используется для получения значения. | | **SQL-текст** | SQL-запрос, который возвращает одно текстовое значение. | | **Активность** | Признак активности правила. | | **Использовать формат Истина/Ложь** | Позволяет выгружать логические значения как `true` или `false`. | | **Внешняя система для GUID** | Внешняя система, идентификатор которой используется для GUID. Если настройка указана и в атрибуте XML-схемы, и в метасхеме, приоритет имеет настройка атрибута XML-схемы. | Для источника **Константа** можно использовать специальные значения: | Значение | Описание | |---|---| | `ClassID` | Возвращает значение поля **Идентификатор версии** из метасхемы для данной XML-схемы. | | `SysDate` | Возвращает текущие дату и время. | | `oursystemname` | Возвращает имя системы Global ERP из справочника внешних систем. | Для выгрузки прикрепленных файлов используется источник **Файл btk**. В поле **Имя атрибута** указывается ссылка на файл в объекте. Если файл прикреплен через промежуточную коллекцию, например `Btk_FileAttach`, выгрузка настраивается через соответствующий дочерний класс. ### Порядок настройки экспорта данных Для настройки экспорта через файлы: 1. Создайте внешнюю систему: `Интеграция и репликация > Настройки > Внешние системы`. 2. Создайте и настройте метасхему интеграции, в которой указан перечень бизнес-объектов для экспорта. 3. Для каждого выгружаемого бизнес-объекта настройте схему выгрузки. 4. Настройте правила интеграции в канале информационного обмена. 5. В менеджере заданий настройте расписание и включите задание, которое было создано в поле **Агент** при создании канала обмена. 6. Для ручного подписания объектов на экспорт выполните скрипт `Rpl_IntXmlSnapshotAgentApi.run()` через интерфейс `Сервис > Инструменты > Выполнить JEXL-скрипт`. ## Настройка импорта Импорт используется для загрузки данных из внешней системы в Global ERP. Через механизм импорта можно выполнять регулярный обмен, перенос нормативно-справочной информации, загрузку начальных данных и обработку входящих XML-файлов. Состав загружаемых данных, правила сопоставления, порядок обработки и источник данных определяются каналом информационного обмена, метасхемами и схемами загрузки. При настройке импорта важно заранее определить ключи поиска записей: по ним система решает, нужно обновить существующий объект или создать новый. ### Схемы загрузки XML-файлов Схемы загрузки описывают, как система разбирает XML-файл и записывает данные в объекты Global ERP. Иерархия схем должна соответствовать структуре XML: корневая схема обрабатывает основной тег, дочерние схемы — вложенные теги и коллекции. Путь: `Интеграция и репликация > Настройки > Схемы загрузки`. ![](img/rpl_import_xml_schemas.jpg) Интерфейс настройки схем загрузки разделен на несколько областей: - левая область содержит дерево схем, которое соответствует вложенности тегов в XML-файле; - правая верхняя область содержит версии выбранной схемы; - правая нижняя область содержит параметры схемы и правила обработки атрибутов. ### Основные поля схемы загрузки | Поле | Описание | |---|---| | **Код** | Уникальный код схемы. Обязателен для заполнения. | | **Наименование** | Наименование схемы. | | **Основной класс** | Класс, в который загружаются данные по схеме. | | **Метод загрузки** | Метод обработки схемы. Для корневой схемы используется `load`, для дочерней схемы-коллекции — `byParent`. Значение `select` для схем загрузки не используется. | | **Примечание** | Описание схемы. | | **Тег рекурсивен** | Признак, который используется, если внутри тега содержится тег с таким же именем и при загрузке нужно сформировать дерево. | | **Предок на два уровня выше** | Используется, если предок для создаваемой записи расположен на два уровня выше в иерархии схем. | | **Запрос потомков** | SQL-запрос, который возвращает список `id` записей для дочернего тега. Используется как альтернатива стандартному методу `byParent`, если нужный класс не является прямой коллекцией текущего. | Пример рекурсивной структуры для загрузки иерархии групп ТМЦ: ```xml <Группа> <Ссылка>aa6666fb-f31f-11e4-825f-448a5bc9fffa <Наименование>Материалы <Код>00000000796 <Группа> <Ссылка>5ea96b2a-7a45-11e6-80c8-000c2914ea2f <Наименование>ПРОКАТ ЧЕРНЫХ МЕТАЛЛОВ <Код>00000010251 <Группа> <Ссылка>18bebff9-7a45-11e6-80c8-000c2914ea2f <Наименование>Сталь сортовая <Код>00000010248 ``` ![](img/rpl_import_parent_two_levels.jpg) ### Настройка версии XML-схемы В версии XML-схемы указываются параметры XML-структуры, которая используется при загрузке. | Поле | Описание | |---|---| | **№** | Порядковый номер. Заполняется автоматически. | | **Наименование** | Наименование версии. | | **Обобщающий XML-тег** | Тег, который объединяет несколько одинаковых тегов. Можно указать полный путь через `/`. | | **XML-тег** | Тег, который соответствует позиции основного класса схемы. Можно указать полный путь через `/`. | ![](img/rpl_import_summary_tag_example.jpg) ### Настройка атрибутов загрузки Атрибуты задают правила чтения значений из XML-файла и записи этих значений в атрибуты классов Global ERP. В этой настройке определяется не только источник значения, но и поведение при поиске, отсутствии значения или ошибке сопоставления. | Поле | Описание | |---|---| | **№** | Порядок загрузки атрибутов. Важен, если значения уже загруженных атрибутов используются в SQL-запросах для получения других значений. | | **XML-тег** | Имя тега или атрибута тега, значение которого нужно загрузить. Атрибут тега указывается через `@`, например `Реквизиты@код`. | | **Тип тега** | При загрузке XML-файлов не используется. | | **Источник** | Источник значения: атрибут класса, атрибут ссылочного класса, константа, функция, SQL-текст, SQL-текст XML, JEXL-текст или файл `Btk_File`. | | **Имя атрибута** | Системное имя загружаемого атрибута. | | **Формат** | Формат даты для атрибутов типа `Date`, например `dd.MM.yyyy`. Поле обязательно для дат. | | **Значение/Функция** | Константа или функция, если выбран соответствующий источник. | | **SQL/JEXL-текст** | SQL-запрос или JEXL-выражение для получения значения. SQL-запрос должен возвращать одно текстовое значение. | | **XML-схема** | Другая схема загрузки, если значение нужно получить через отдельную схему. | | **Активность** | Признак применения правила. | | **Для поиска** | Признак, который включает атрибут в ключ поиска записи. Если запись найдена, она обновляется; если не найдена, создается новая. | | **Использовать формат Истина/Ложь** | Для сценариев обмена с 1С позволяет использовать значения `Ложь` и `Истина` вместо `0` и `1`. | | **Требуется заполнение** | Если признак установлен и в теге нет значения, новая позиция класса не создается. | | **Обязателен** | Если признак установлен, при отсутствии значения в теге возникает ошибка. | | **Ошибка, если не найдено значение при заполненном теге** | Если в теге есть значение, но SQL-текст, функция или XML-схема не вернули результат, возникает ошибка. | | **Внешняя система для GUID** | Внешняя система, к которой относится внешний идентификатор. | В SQL-запросах можно использовать параметры: - `:t` — значение текущего XML-тега; - `:sCode` — значение другого загруженного атрибута текущей схемы, где `sCode` заменяется на системное имя атрибута; - `:super$sCode` — значение атрибута из основного класса вышестоящей схемы. Пример SQL-запроса: ```sql select case when cast(:bNotActive as varchar) = '1' then :t || '/' || :id else :t end ``` Для источника **JEXL-текст** доступны переменные `id`, `currentStringValue`, `currentXmlNode` и `idMetaSchema`. Итоговое значение должно быть приведено к типу `String`, например `toString(id)`. ### Загрузка прикрепленных файлов При импорте можно загружать не только значения атрибутов, но и файлы, связанные с объектом. Для этого в схеме загрузки используется источник **Файл btk**, а файл сохраняется в указанное файловое хранилище. Для загрузки файлов в **Прикрепленные файлы**: 1. Под схемой загрузки объекта, к которому должны прикрепляться файлы, создайте дочернюю схему с методом загрузки `byParent`. 2. В поле **Основной класс** укажите класс-развязку между `Btk_File` и основным классом вышестоящей схемы. Например, можно использовать `Btk_AttachItem` или `Qj_QuestionFile`. 3. В версии схемы добавьте атрибут и выберите источник **Файл btk**. 4. В поле **Значение/Функция** укажите системное имя файлового хранилища, в которое нужно загружать файлы. ```{note} Системное имя файлового хранилища можно посмотреть в интерфейсе `Настройка системы > Сущности > Файловые хранилища`. ``` ![](img/rpl_file_storage.jpg) Чтобы при загрузке для файла формировалось имя, в настройках атрибутов добавьте позицию с именем атрибута `FileName` и снимите признак **Активность** для этой позиции. ### Нестандартные случаи загрузки В некоторых сценариях стандартного сопоставления тегов XML с атрибутами класса недостаточно. Тогда используются дополнительные признаки схемы, постобработка или вызов API-методов, которые формируют связанные данные после основной загрузки. #### Формирование иерархии групп при загрузке ТМЦ Для формирования групп при загрузке позиции справочника настройте отдельную схему для группы ТМЦ и установите признак **Тег рекурсивен**. В функции постобработки добавьте скрипт, который привяжет корневую группу из XML-файла к нужной группе справочника ТМЦ. ```scala var rop = Btk_GroupApi.loadByGid(gidObject.toString()); var jrop = new("ru.bitec.app.gtk.jexl.session.JexlRop", rop); if (jrop.idParentGroup == null) Btk_GroupApi.setidParentGroup(rop, 3503L); ``` В схеме загрузки ТМЦ добавьте скрипт, который вызывает метод `Bts_XmlSchemaVerApi.parseStringXMLReturnLastObjId(spXml: String, idpHeadClass: Long, idpMetaSchema: Long)`. Параметры метода: - `spXml` — XML для разбора по схеме загрузки; - `idpHeadClass` — идентификатор основного класса, по которому создаются записи. При загрузке групп это идентификатор класса `Btk_Group`; - `idpMetaSchema` — идентификатор метасхемы. В параметр передается `dMetaSchema.get()`. Метод возвращает идентификатор последнего загруженного объекта. Для групп это идентификатор самой нижнеуровневой группы, который можно использовать в постобработке. ```scala var idgroup = Bts_XmlSchemaVerApi.parseStringXMLReturnLastObjId(sXml.toString(), 501L, idMetaSchema.get()); var rop = s_GoodsApi.loadByGid(gidObject.toString()); Btk_ObjectGroupApi.register(rop, idgroup, 0B, 1B); commit(); ``` #### Загрузка типа объекта для ТМЦ Некоторые классы требуют дополнительной настройки расширения типов. Для класса `Bs_Goods` настройка используется при загрузке атрибута `idObjectType`. Для корректной загрузки `idObjectType` выполните настройку типов объекта для соответствующего класса в интерфейсе настройки типов объектов. ![](img/rpl_goods_type_extensions.jpg) ### Порядок настройки импорта данных После настройки схем загрузки и канала выполните тестовую загрузку на небольшом наборе данных. Это позволяет проверить ключи поиска, обязательные поля, преобразование типов и обработку ошибок до включения регулярного расписания. Для настройки импорта: 1. Создайте внешнюю систему: `Интеграция и репликация > Настройки > Внешние системы`. 2. Создайте и настройте метасхему интеграции. Обычно для одной внешней системы создается одна метасхема. 3. Создайте XML-схемы, по которым будут разбираться входящие данные. 4. Настройте правила интеграции в канале информационного обмена. 5. В менеджере заданий настройте расписание и включите задание, которое было создано в поле **Агент** при создании канала обмена.