Перейти к основному содержанию
`Ctrl`+`K`

# Настройка экспорта и импорта

Раздел описывает настройку обмена данными по 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-тега:

    <Документ>
      <Наименование>Система вентиляции</Наименование>
      <ПозицииДокумента>
        <Позиция НомерПозиции="1"/>
        <Позиция НомерПозиции="2"/>
        <Позиция НомерПозиции="3"/>
        <Позиция НомерПозиции="4"/>
      </ПозицииДокумента>
    </Документ>

Если в XML-файле формируются пустые значения с `xsi:nil="true"`, в корневой тег должен быть добавлен атрибут `xmlns:xsi` со значением `http://www.w3.org/2001/XMLSchema-instance`.

    <ЭлементНоменклатуры 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: корневая схема обрабатывает основной тег, дочерние схемы — вложенные теги и коллекции.

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

Интерфейс настройки схем загрузки разделен на несколько областей:

- левая область содержит дерево схем, которое соответствует вложенности тегов в XML-файле;

- правая верхняя область содержит версии выбранной схемы;

- правая нижняя область содержит параметры схемы и правила обработки атрибутов.

### Основные поля схемы загрузки

Поле | Описание
--- | ---
Код | Уникальный код схемы. Обязателен для заполнения.
Наименование | Наименование схемы.
Основной класс | Класс, в который загружаются данные по схеме.
Метод загрузки | Метод обработки схемы. Для корневой схемы используется `load`, для дочерней схемы-коллекции — `byParent`. Значение `select` для схем загрузки не используется.
Примечание | Описание схемы.
Тег рекурсивен | Признак, который используется, если внутри тега содержится тег с таким же именем и при загрузке нужно сформировать дерево.
Предок на два уровня выше | Используется, если предок для создаваемой записи расположен на два уровня выше в иерархии схем.
Запрос потомков | SQL-запрос, который возвращает список `id` записей для дочернего тега. Используется как альтернатива стандартному методу `byParent`, если нужный класс не является прямой коллекцией текущего.

Пример рекурсивной структуры для загрузки иерархии групп ТМЦ:

    <Группа>
      <Ссылка>aa6666fb-f31f-11e4-825f-448a5bc9fffa</Ссылка>
      <Наименование>Материалы</Наименование>
      <Код>00000000796</Код>
      <Группа>
        <Ссылка>5ea96b2a-7a45-11e6-80c8-000c2914ea2f</Ссылка>
        <Наименование>ПРОКАТ ЧЕРНЫХ МЕТАЛЛОВ</Наименование>
        <Код>00000010251</Код>
        <Группа>
          <Ссылка>18bebff9-7a45-11e6-80c8-000c2914ea2f</Ссылка>
          <Наименование>Сталь сортовая</Наименование>
          <Код>00000010248</Код>
        </Группа>
      </Группа>
    </Группа>

### Настройка версии XML-схемы

В версии XML-схемы указываются параметры XML-структуры, которая используется при загрузке.

Поле | Описание
--- | ---
№ | Порядковый номер. Заполняется автоматически.
Наименование | Наименование версии.
Обобщающий XML-тег | Тег, который объединяет несколько одинаковых тегов. Можно указать полный путь через `/`.
XML-тег | Тег, который соответствует позиции основного класса схемы. Можно указать полный путь через `/`.

### Настройка атрибутов загрузки

Атрибуты задают правила чтения значений из 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-запроса:

    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. В поле Значение/Функция укажите системное имя файлового хранилища, в которое нужно загружать файлы.

Примечание

Системное имя файлового хранилища можно посмотреть в интерфейсе `Настройка системы > Сущности > Файловые хранилища`.

Чтобы при загрузке для файла формировалось имя, в настройках атрибутов добавьте позицию с именем атрибута `FileName` и снимите признак Активность для этой позиции.

### Нестандартные случаи загрузки

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

#### Формирование иерархии групп при загрузке ТМЦ

Для формирования групп при загрузке позиции справочника настройте отдельную схему для группы ТМЦ и установите признак Тег рекурсивен.

В функции постобработки добавьте скрипт, который привяжет корневую группу из XML-файла к нужной группе справочника ТМЦ.

    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()`.

Метод возвращает идентификатор последнего загруженного объекта. Для групп это идентификатор самой нижнеуровневой группы, который можно использовать в постобработке.

    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` выполните настройку типов объекта для соответствующего класса в интерфейсе настройки типов объектов.

### Порядок настройки импорта данных

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

Для настройки импорта:

1. Создайте внешнюю систему: `Интеграция и репликация > Настройки > Внешние системы`.

2. Создайте и настройте метасхему интеграции. Обычно для одной внешней системы создается одна метасхема.

3. Создайте XML-схемы, по которым будут разбираться входящие данные.

4. Настройте правила интеграции в канале информационного обмена.

5. В менеджере заданий настройте расписание и включите задание, которое было создано в поле Агент при создании канала обмена.