Файл конфигурации импорта. Общий

В разделе содержится структура файла конфигурации импорта и описание всех тегов.

• <config name="" save-log="" threads-number="" description="" skip-workflow="">

  • <mode></mode>

  • <gui-parameter name="" type="" title=""/>

  • <parameter name=""></parameter>

  • <script-parameter name=""></script-parameter>

  • <class name="" threads-number="" log-column-name="">

    • <mode></mode>

    • <parameter name=""></parameter>

    • <csv-data-source id-column="" file-name="" url-timeout="" with-header="" encoding="" delimiter="">

      • <column name="" src-key=""/>

      </csv-data-source>

    • <cassandra-data-source id-column="">

      • <column name="" src-key=""/>

      • <cassandra-connection host="" keyspace="" user="" password="" ssl="" port=""/>

      • <query></query>

      </cassandra-data-source>

    • <sql-data-source id-column="">

      • <column name="" src-key=""/>

      • <connection-code></connection-code>

      • <query></query>

      • <script></script>

      </sql-data-source>

    • <xls-data-source id-column="" file-name="" url-timeout="" sheet-number="" start-row="">

      • <column name="" src-key=""/>

      </xls-data-source>

    • <xlsx-data-source id-column="" file-name="" url-timeout="" sheet-number="" start-row="">
      • <column name="" src-key=""/>

      </xlsx-data-source>

    • <xml-data-source file-name="" url-timeout="" xpath="" fast-parsing="" readNameSpacesFromDoc="">

      • <column name="" src-key=""/>

      </xml-data-source>

    • <ldap-data-source id-column="" check-user-disabled="" full-domain="" import-root="">

      • <column name="" src-key="" parent="" login=""/>

      • <connection-code></connection-code>

      • <root-element></root-element>

      • <import-tag></import-tag>

      • <ignored-postfix></ignored-postfix>

      • <allowed-postfix></allowed-postfix>

      • <filter></filter>

      </ldap-data-source>

    • <hierarchical-filter parent-column=""/>

    • <column-notempty-filter column=""/>

    • <id-prefix prefix=""/>

    • <script-filter mime-type=""/>

    • <constant-metaclass-resolver metaclass=""/>

    • <by-column-metaclass-resolver metaclass="" case-column="" default-case=""/>

    • <column-metaclass-resolver column="" default-metaclass=""/>

    • <script-metaclass-resolver mime-type=""/>

    • <object-searcher attr="" metaclass=""/>

    • <complex-object-searcher/>

    • <script-object-searcher mime-type="" />

    • <attr name="" column="" not-null="" default-value="">

      • <include-mode></exclude-mode>

      • <exclude-mode></exclude-mode>

      • <ad-image-converter title="" mimeType="" eraseOld=""/>

      • <boolean-converter true-value=""/>

      • <case-list-converter delimiter="" class=""/>

      • <collection-converter delimiter=""/>

      • <complex-object-converter></complex-object-converter>

      • <datetime-converter format=""/>

      • <double-converter/>

      • <file-content-converter titleColumn="" mimeTypeColumn=""/>

      • <hyperlink-converter delimiter=""/>

      • <integer-converter/>

      • <localized-column lang="" column=""/>

      • <object-converter attr="" metaclass="" required="" removed=""/>

      • <script-converter mime-type=""/>

      • <string-converter trim=""/>

      • <time-interval-converter interval=""/>

      </attr>

    • <metaclass-attrs>

      • <metaclass></metaclass>

      • <attr name=""/>

      </metaclass-attrs>

    • <remove-customizer hierarchy-root="" metaclass="" attr=""/>

      • <skip-objects-script></skip-objects-script>

      • <remove-condition-script></remove-condition-script>

      </remove-customizer>

    • <script-customizer>

      • <before-import></before-import>

      • <before-process-item></before-process-item>

      • <before-process></before-process>

      • <after-process></after-process>

      • <after-import></after-import>

      </script-customizer>

    • <timer-customizer attr="" column=""/>

    • <backtimer-customizer attr="" allowance-column="" deadline-column="" deadline-column-format=""/>

    </class>

  </config>

Тег <config> *

Описание

Тег <config> — основной тег конфигурации, в него вложены все остальные теги. В параметрах тега задаются основные параметры импорта.

Параметры

• name — имя конфигурации.

  Используется как ключ для группировки результатов (логов) импорта. Результаты импортов с одинаковыми именами выводятся в одном и том же списке.

  Тип: Строка. Необязательный.

• save-log — управление файлом с логами импорта.

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

  Возможные значения параметра:

  • true — файл с логами импорта сохраняется в системе,
  • false — файл с логами импорта не сохраняется в системе, логи импорта сохраняются только в логах приложения.

  Тип: Логический. Необязательный. По умолчанию: true

• threads-number — количество потоков, которыми будут обрабатываться элементы из внешнего источника. Возможность обработки данных в несколько потоков зависит от технических параметров подключения к базе данных.

  Тип: Целое число. Необязательный. По умолчанию: 1 (один поток)

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

  В многопоточном режиме проходит только сам импорт данных. Операции предобработки и постобработки всегда выполняются в один поток.

  • К предобработке относятся тэги: data-source, hierarchical-filter, column-notempty-filter, id-prefix, metaclass-resolver, script-customizer и before-import в нем.

    Если на этапе предобработки используется тег hierarchical-filter, то весь последующий импорт выполняется также в одном потоке. Это связано с необходимостью последовательного формирования иерархии данных и соблюдения их порядка, что не позволяет распараллеливать вычисления

  • К самому импорту относятся тэги: before-process-item, object-searcher, attr, converter, before-process, сохранение объекта и потом after-process
  • К постобработке относятся тэги: remove-customizer и тэги к нему относящиеся, script-customizer и after-import в нем

• description — описание импорта.

  Используется только в самой конфигурации.

  Тип: Строка. Необязательный.

• skip-workflow — управление выполнением проверок, связанных с жизненным циклом объектов.

  Пример использования: импорт закрытых запросов с переводом их в статус "Закрыт".

  Возможные значения параметра:

  • false — пропускаются проверки, связанные с жизненным циклом объектов.
  • true — проверки выполняются.

  Тип: Логический. Необязательный. По умолчанию: false.

Пример

<config description="Example"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="../../../../../../target/classes/advimport/schema1.xsd"
   save-log="true"
   threads-number="1"
   skip-workflow="false" >
  
</config>

Тег <mode> *

Описание

Тег <mode> указывает режим импорта.

• Вложен в <config> — указывает режим импорта, общий для всех классов.
• Вложен в <class> — указывает режим импорта для класса импортируемых объектов, в котором объявлен тег. Указанный режим переопределяет глобальный режим, объявленный в теге <mode>, вложенном в <config>.

Содержимое тега

Внутри тега задается режим импорта:

• CREATE — только создание объектов.
• UPDATE — только обновление существующих объектов.
• EMPTY — без создания объектов и обновления существующих объектов.

В одной конфигурации импорта можно указывать сразу несколько режимов.

• Если указаны CREATE и UPDATE, то будут создаваться новые объекты и обновляться уже существующие.

• Если указаны EMPTY и/или CREATE и UPDATE, то создание объектов и обновления существующих производиться не будет.

  В режиме EMPTY выполняются только: script-filter, вычисление значений атрибутов, script-customizer, remove-customizer. Режим используется для проверки работоспособности импорта. Условия поиска и условия сопоставления атрибутов выполняются без фактического изменения данных.

Каждый режим прописывается отдельном теге.

Пример

<mode>CREATE</mode>
<mode>UPDATE</mode>
<mode>EMPTY</mode>

Тег <gui-parameter>

Описание

Тег <gui-parameter> позволяет запросить у пользователя дополнительные параметры импорта, которые можно использовать в конфигурации импорта.

Дополнительные параметры импорта запрашиваются при запуске импорта через интерфейс. Значения параметров вводятся пользователем на форме "Запуск импорта".

Запрашивать можно сколько угодно дополнительных параметров, т.е. тегов <gui-parameter> может быть сколько угодно в конфигурации.

Есть возможность запросить два типа параметров: строку и файл. Тип указывается в параметрах тега <gui-parameter>.

Параметры

• name — название параметра в конфигурации.

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

  Тип: Строка. Обязательный.

• type — тип запрашиваемого параметра.

  Возможные значения параметра:

  • String — запрос строкового параметра;
  • FILE — загрузка файла, используется для выбора файла, в котором хранятся объекты для импорта.

  Тип: Строка. Обязательный.

• title — название параметра на форме, которую видит пользователь.

  Тип: Строка. Обязательный.

Пример

<gui-parameter name="paramName" type="STRING" title="Additional parameter"/>
<gui-parameter name="uploadedFile" type="FILE" title="File for import" />

Тег <parameter>

Описание

Тег <parameter> задает некоторую константную величину, которую можно в дальнейшем использовать в конфигурации. В отличие от <gui-parameter> значение не запрашивается у пользователя.

• Вложен в <config> — задает некоторую константную величину, которую можно в дальнейшем использовать в конфигурации.

• Вложен в <class>:

  • задает некоторую константную величину, которую можно в дальнейшем использовать в конфигурации;

  • переопределяет значение параметра, объявленное в теге <parameter>, вложенном в <config>.

    Чтобы переопределить значение параметра, нужно указать у него точно такое же значение параметра name.

Содержимое тега

Внутри тега <parameter> задается значение константы.

Параметры

• name — название параметра в конфигурации.

  По указанному названию можно обратиться к параметру и получить его значение.

  В качестве названия параметра можно указать специальные системные названия.

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

  Имена параметров по умолчанию следующие:

  • metaClass — значение кода метакласса по умолчанию для импортируемых объектов;
  • idHolder — значение по умолчанию для идентификатора объекта во внешней системе;
  • importRootUUID — uuid корневого объекта, в иерархии которого необходима архивация объектов, не участвующих в импорте. Используется в теге <remove-customizer> (значение параметра hierarchy-root).

  Тип: Строка. Обязательный

Пример

<parameter name="defaulTitle">Default title</parameter>
<parameter name="idHolder">idHolder</parameter>
<parameter name="importRootUUID">ou$1234</parameter>

Тег <script-parameter>

Описание

Внутри тега <script-parameter> содержится groovy-скрипт, определяющий значение параметра. Скрипт выполняется во время проведения импорта.

Параметры

• name — название скрипта.

  Тип: Строка. Необязательный

Пример

Параметры, вычисляемые скриптом во время выполнения импорта, определяются в теге <script-parameter>.

Пример 1. Дата, с которой необходимо выгружать трудозатраты

<script-parameter name="dateFrom">
    def cal = Calendar.instance;
    cal.add(Calendar.DAY_OF_YEAR, -30);
return cal.time.format( 'yyyy-MM-dd' );
</script-parameter>

Пример 2. Дата, до которой необходимо выгружать трудозатраты

<script-parameter name="dateTo">
    return new Date().format( 'yyyy-MM-dd' );
</script-parameter>

Тег <class> *

Описание

Тег <class> объявляет описание импортируемых объектов.

В теге <class> можно переопределить режим импорта, глобальные параметры, объявить новые параметры, описать источник, сортировку и фильтрацию, определить класс импортируемых объектов, поиск существующих объектов, создать объекты / обновить значения атрибутов объектов, изменить значения атрибутов с помощью кастомайзеров.

Источников импорта в рамках одной конфигурации может быть сколько угодно, но каждый источник должен быть описан в рамках своего тега <class>, поэтому тегов <class> может быть сколько угодно.

Параметры

• name — название класса импортируемых объектов.

  Тип: Строка. Необязательный

• threads-number — количество потоков, которыми будут обрабатываться элементы из внешнего источника.

  Переопределяет количество потоков, которые были объявлены в аналогичном параметре тега <config>.

  Тип: Целое число. Необязательный

• log-column-name — название колонки, содержимое которой будет выводиться в круглых скобках в сообщениях импорта после "ID=".

  Название колонки ищется среди колонок описания источника, указанного в параметре name.

  Если значение параметра log-column-name не заполнено или указанная колонка отсутствует, то пользовательский текст выводиться не будет.

  Тип: Строка. Необязательный

Пример

<class name="import1" threads-number="1">

</class>

Тег <csv-data-source>

Описание

Тег <csv-data-source> описывает источник данных из CSV-файла.

Параметры

• id-column — имя колонки (атрибута данных) из источника, содержащей уникальный внешний идентификатор объекта.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

• file-name — полное имя файла (полный путь, имя файла, расширение файла), из которого будет производится импорт.

  Обязательно указывать протокол получения файла, например:

  file-name="file:/opt/_imports/cfg_storages.csv"

  Можно указать:

  • файл полученный от пользователя через <gui-parameter>;
  • url до файла.

  Тип: Строка. Обязательный

• url-timeout — таймаут ожидания получения данных из внешнего источника, заданного с помощью URL (в секундах).

  0 подразумевает бесконечное ожидание.

  Тип: Целое число. Необязательный. По умолчанию: значение из настроек соединения по умолчанию

• with-header — управление наличием подписей колонок в импортируемом файле.

  Возможные значения параметра:

  • true — scr-key колонки задает подпись колонки,
  • false — scr-key указывает номер колонки. Нумерация колонок начинается с 0.

  Тип: Логический. Необязательный

• encoding — кодировка символов импортируемого файла.

  Тип: Строка. Необязательный. По умолчанию: cp1251

• delimiter — разделитель колонок.

  Задается только одним символом в кодировке файла источника. Указать в качестве разделителя символ табуляции нельзя.

  Тип: Символ. Необязательный. По умолчанию: ;

  Если поле содержит запятые, переносы строк, двойные кавычки или символ разделителя, то это поле должно быть заключено в двойные кавычки или другой символ, указанный в параметре text-delimiter.

• text-delimiter — символ для цитирования/экранирования. Все, что находится между символами " (двойная кавычка), будет воспринято, как одно значение, даже если внутри будут разделители delimiter.

  Тип: Символ. Необязательный. По умолчанию: "

  В платформе используется com.opencsv.CSVParser. Такая реализация позволяет использовать символ экранирования, по умолчанию обратный слеш \, для экранирования специальных символов, в том числе и символов delimeter и text-delimeter.
  

Вложенный тег

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Если у источника данных есть параметр with-header и его значение true, то src-key — название колонки.

    Тип: Строка. Обязательный

Пример

<csv-data-source file-name="$uploadedFile" url-timeout="40" with-header="true">
    <column name="id" src-key="@id"/>
    <column name="title" src-key="Title"/>
</csv-data-source>

Возможные ошибки

При импорте из csv файла при стандартных настройках может произойти ошибка, если заданы разделители текста:

• delimiter=";" // точка с запятой;
• text-delimiter=""" // двойные кавычки.

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

Если в csv файле есть строка с названием отдела "Отделение "Московское", где используется три двойных кавычки, то это приведет к ошибке импорта.

Ошибку можно исправить двумя способами:

• Преобразовать csv файл так, чтобы строки содержали четное количество двойных кавычек.
• Заменить значение параметра text-delimiter, к примеру, на одинарную кавычку.

Тег <cassandra-data-source>

Описание

Тег <cassandra-data-source> описывает источник данных из NoSQL БД Cassandra.

Параметр

• id-column — имя колонки (атрибута данных) из источника, содержащей уникальный внешний идентификатор объекта.

  Колонки доступны по индексам, первая колонка имеет индекс "0".

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

Вложенные теги

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Тип: Строка. Обязательный

• <cassandra-connection> — параметры подключения к БД Cassandra.

  Параметры:

  • host — IP-адрес подключения.

    Тип: Строка. Обязательный

  • keyspace — пространство ключей.

    Тип: Строка. Обязательный

  • user — логин пользователя.

    Тип: Строка. Обязательный

  • password — пароль пользователя.

    Тип: Строка. Обязательный

  • ssl — требуется ли SSL-сертификат.

    Тип: Логический. Обязательный

  • port — требуется ли SSL-сертификат.

    Тип: Строка. Обязательный. По умолчанию: 9042.

• <query> — внутри тега задается SQL-запрос, в результате которого получаются значения колонок.

Пример

<cassandra-data-source>
   <column name="ou_id" src-key="0"/>
   <column name="title" src-key="1"/>
   <cassandra-connection host="192.168.240.205" keyspace="testkeyspace" user="user" password="user_password" ssl="true" port="9042"/>
   <query>
      select * from ous
   </query>
</cassandra-data-source>

Тег <sql-data-source>

Описание

Тег <sql-data-source> описывает источник данных из реляционных баз данных.

Параметр

• id-column — имя колонки (атрибута данных) из источника, содержащей уникальный внешний идентификатор объекта.

  Колонки доступны по номерам или алиасам.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

Вложенные теги

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Тип: Строка. Обязательный

• <connection-code> — внутри тега указывается код подключения из каталога подключений. Код подключения к источнику SQL определяется при добавлении подключения.

  Некоторые параметры указанного подключения (url (строка подключения); user (имя пользователя); passwd (пароль); domain (домен), driver (класс реализации протокола jdbc)) могут быть переопределены в параметрах тега <sql-data-source>. Каждый параметр подключения представляет собой отдельный атрибут тега <sql-data-source>. Если параметр явно не определен в конфигурации импорта, то он берется из настроек указанного подключения.

• <query> — внутри тега задается SQL-запрос, в результате которого получаются значения колонок.

• <script> — внутри тега задается скрипт, параметризующий SQL-запрос.

  В скрипте доступно:

  • Стандартное api;

  • Переменная parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  • Переменная query(PreparedStatement), в которой содержится параметризованный запрос из тега <query>.

    Чтобы определить параметры (записанные в виде знака вопроса) в SQL-запросе, у переменной query нужно вызвать один или несколько (в зависимости от количества параметров) методов из следующего списка:

    • query.setBoolean(1, boolean);
    • query.setString(1, string);
    • query.setInt(1, int);
    • query.setLong(1, long);
    • query.setDate(1, date);
    • query.setTimestamp(1, timestamp);
    • query.setObject(1, object);
    • query.setBlob(1, blob);
    • query.setClob(1, clob);

    В вышеуказанных методах первый параметр — номер параметра в SQL-запросе(начинается с 1), второй — значение соответствующего типа.

    Не рекомендуется использовать метод query.setObject(1, object), т.к. результат работы метода зависит от JDBC-драйвера, подробнее см. в документации JDBC.

Примеры

Пример 1.

<sql-data-source>
   <column name="id" src-key="@id"/>       
   <connection-code>@код_подключения</connection-code>        
      
   <query>select col1, col2 from table where col1 = ?</query>      
   <script>query.setString(1,'lalala')</script>
</sql-data-source>

Пример 2. Передача параметров в источник импорта SQL

...
<gui-parameter name="param1" type="STRING" title="param1"/>
...
<sql-data-source>
   <column name="id" src-key="@id"/>
   <connection-code>sql1</connection-code>
   <query>select id from table where col1 = ?</query>
   <script>query.setString(1,parameters.get('param1'))</script>
</sql-data-source>

Пример 3. Конвертация значения типа "Строка" в тип:

• boolean (приведено два вида преобразования):

  <gui-parameter name="rvm" type="STRING" title="removed"/>
  query.setBoolean(1,parameters.get('rvm').toBoolean())
  query.setBoolean(1,Boolean.valueOf(parameters.get('rvm')))
  

• date:

  <gui-parameter name="mDate" type="STRING" title="date"/>
  query.setDate(1,new java.sql.Date( utils.formatters.strToDate(parameters.get('mDate')).getTime()))
  

• long:

  <gui-parameter name="prjId" type="STRING" title="prjId"/>
  query.setLong(1,Long.valueOf(parameters.get('prjId')))
  

<xls-data-source>

Описание

Тег <xls-data-source> описывает источник данных из XLS таблицы.

Параметры

• id-column — имя колонки (атрибута данных) в источнике импорта, содержащей уникальные ключи для импортируемых объектов. В источнике импорта id-column должен быть заполнен для всех объектов, иначе возможно дублирование объектов.

  Обязательность заполнения параметра:

  • в режиме UPDATE — наличие параметра id-column в файле конфигурации импорта является обязательным;
  • в режимах CREATE и EMPTY — наличие параметра id-column в файле конфигурации импорта не обязательно.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

• file-name — полное имя файла, из которого будет производится импорт.

  Обязательно указывать протокол получения файла.

  Можно указать:

  • файл полученный от пользователя через <gui-parameter>;
  • url до файла.

  Тип: Строка. Обязательный

• url-timeout — таймаут ожидания получения данных из внешнего источника, заданного с помощью URL (в секундах).

  0 подразумевает бесконечное ожидание.

  Тип: Целое число. Необязательный. По умолчанию: значение из настроек соединения по умолчанию

• sheet-number — номер листа книги, на котором находятся импортируемые данные.

  Тип: Целое число. Необязательный. По умолчанию 0, т.е. при отсутствии sheet-number в конфигурации импорта, берутся все данные из листа с номером 0, (самого первого)

• start-row — номер первой строки, содержащей импортируемые данные.

  Тип: Целое число. Обязательный.

Вложенный тег

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Тип: Строка. Обязательный

Пример

<xls-data-source file-name="http://host/path" url-timeout="30" sheet-number="1" start-row="1">
    <column name="id" src-key="@id"/>
</xls-data-source>

<xlsx-data-source>

Описание

Тег <xlsx-data-source> описывает источник данных из XLSX таблицы.

Параметры

• id-column — имя колонки (атрибута данных) из источника, содержащей уникальный внешний идентификатор объекта.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

• file-name — полное имя файла, из которого будет производится импорт.

  Обязательно указывать протокол получения файла.

  Можно указать:

  • файл полученный от пользователя через <gui-parameter>;
  • url до файла.

  Тип: Строка. Обязательный

• url-timeout — таймаут ожидания получения данных из внешнего источника, заданного с помощью URL (в секундах).

  0 подразумевает бесконечное ожидание.

  Тип: Целое число. Необязательный. По умолчанию: значение из настроек соединения по умолчанию

• sheet-number — номер листа книги, на котором находятся импортируемые данные.

  Тип: Целое число. Необязательный. По умолчанию 0, т.е. при отсутствии sheet-number в конфигурации импорта, берутся все данные из листа с номером 0, (самого первого)

• start-row — номер первой строки, содержащей импортируемые данные.

  Тип: Целое число. Обязательный

Вложенный тег

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Тип: Строка. Обязательный

Пример

<xlsx-data-source file-name="http://host/path" url-timeout="30" sheet-number="1" start-row="1">
    <column name="id" src-key="@id"/>
</xlsx-data-source>

<xml-data-source>

Описание

Тег <xml-data-source> описывает источник данных из XML файла.

Параметры

• id-column — имя атрибута данных из источника, содержащей уникальный внешний идентификатор объекта.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

• file-name — полное имя файла (полный путь, имя файла, расширение файла), из которого будет производится импорт.

  Обязательно указывать протокол получения файла.

  Можно указать:

  • файл полученный от пользователя через <gui-parameter>;
  • url до файла.

  Тип: Строка. Обязательный

• url-timeout — таймаут ожидания получения данных из внешнего источника, заданного с помощью URL (в секундах).

  0 — бесконечное ожидание.

  Тип: Целое число. Необязательный. По умолчанию: значение из настроек соединения по умолчанию

• xpath — xpath путь до импортируемых элементов данных.

  Тип: Строка. Необязательный

• fast-parsing — определяет способ парсинга xml файла.

  Параметр нужно использовать для импорта больших xml файлов со сложной структурой.

  • false (по умолчанию) — xml файл считывается полностью в память, строится его дерево и только после этого происходит импорт.

    Пример записи в логе импорта: (10 июн 2025 18:03:30,949)... [5/5]..., где [5/5] означает, что загружено 5 объектов из 5.

  • true — в память считывается один объект (объектом считается элемент, путь до которого указан в параметре xpath), затем выполняется проверка считанного объекта на валидность структуры xml.

    • Если объект невалидный, то он пропускается с соответствующей записью в логе и считывается следующий объект.
    • Если объект валидный, то происходит импорт считанного объекта и считывается следующий объект. Процедура выполняется, пока не будет достигнут конец файла.

    Если значение threads-number > 1 (параметр тегов <config> и <class>), то сначала собирается число объектов, указанное в этом параметре, а после производится импорт. Параметр не используется, если указан тег <hierarchical-filter> (вложен в тег <class>), выводится сообщение об ошибке: "Тег <hierarchical-filter> не может использоваться при пообъектном импорте данных".

    Пример записи в логе импорта: (10 июн 2025 18:03:30,949)... [5/N]..., где 5 — количество загруженных объектов, а N — количество потоков (threads-number), использованных при импорте.
    Например, при настройке импорта fast-parsing=true и threads-number="1", в логе импорта будет запись вида: (10 июн 2025 18:03:30,949)... [5/1]....

  Тип: Логический. Необязательный.

• readNameSpacesFromDoc — указывает нужно ли читать nameSpaces из файла XML.

  • true — будут взяты как стандартные nameSpaces, так и объявленные в заголовке самого документа XML. Если NameSpace объявлен в теле документа (не в заголовке), то он будет проигнорирован.
  • false — nameSpaces из файла XML игнорируются.

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

  Тип: Логический. Необязательный.

Вложенный тег

• <column> — колонка импортируемых данных. Каждая колонка импортируемых данных описывается в отдельном теге <column>.

  Параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать.

    Тип: Строка. Обязательный

  • src-key — полный xpath путь до элемента.

    В пути должна быть указаны:

    • ось элементов;
    • выражение, определяющее отбираемые элементы;
    • предикаты (дополнительные условия отбора)

    Примеры:

    <xml>
    <container>
       <elem login="iivanov">
          <name>Иванов Иван</name>
          <email internal="true">iivanov@company.ru</email>
       </elem>
       <elem login="ppetrov">
          <name>Петров Петр</name>
          <email internal="true">ppetrov@company.ru</email>
       </elem>
    </container>
    </xml>

    xpath для получения Имя пользователя с login "iivanov":

    xml/container/elem[@login="iivanov"]/name/text()

    xpath для получения значения internal параметра у пользователя с login "ppetrov":

    xml/container/elem[@login="ppetrov"]/email/@internal

    Полное описание xpath смотрите на W3 Xpath Tutorial (ссылка на документацию).

    Тип: Строка. Обязательный

Пример

<xml-data-source file-name="classpath:/ru/naumen/advimport/ou_object_converter.test.xml" xpath="/Items/OU">
   <column name="id" src-key="./@id" />
   <column name="parent" src-key="./Parent/text()" />
   <column name="removed" src-key="./Removed/@value" />
   <column name="removalDate" src-key="./Removed/RemovalDate/text()" />
</xml-data-source>

<ldap-data-source>

Описание

Тег <ldap-data-source> описывает источник данных из LDAP или AD.

Параметры LDAP описываются в атрибутах и вложенных тегах тэга <ldap-data-source>.

Некоторые параметры импорта LDAP также могут быть определены в файле конфигурации импорта в теге <parameter>, как константные величины, используемые в качестве значений по умолчанию, если они не заданы в явном виде, например: <parameter name="ldapDomain"> ( имя домена) и <parameter name="rootDN"> (корневой домен импорта).

Параметры

Параметры full-domain и check-user-disabled относятся к импорту сотрудников из Active Directory или LDAP и не должны использоваться во время импорта других объектов.

• id-column — имя колонки (атрибута данных) из источника, содержащей уникальный внешний идентификатор объекта.

  В дальнейшем по этому идентификатору будет производится поиск объекта, см. <object-searcher> и <hierarchical-filter>.

  Тип: Строка. Необязательный

• check-user-disabled — указывает необходимость пропускать пользователей, которые неактивны в AD.

  Тип: Логический. Обязательный

• domain — значение параметра будет добавлено к логину при формировании соответствующего атрибута (sAMAccountName + @ + доменное имя).

  Тип: Строка. Необязательный

  Особенности формирования логина сотрудника при импорте описаны в разделе Импорт логина сотрудника.

• full-domain — задает правило формирования логина импортируемого пользователя по его DN. Доменное имя может быть частичным или полным в зависимости от значения параметра

  Тип: Логический. Обязательный

• import-root — указывает необходимость импорта объекта на который указывает DN из root-element.

  Тип: Логический. Обязательный

Вложенные теги

• <column> — колонка импортируемых данных, задается соответствие атрибутов LDAP-объекта колонкам импорта.

  Дополнительные параметры:

  • name — название импортируемой колонки данных.

    Название используется при присваивании атрибуту значения и указывает из какой колонки нужно его брать (параметры тега <attr>).

    Тип: Строка. Обязательный

  • src-key — номер колонки в источнике данных.

    Тип: Строка. Обязательный

  • parent — objectGUID родительского объекта.

    Тип: Строка. Необязательный

  • login — логин пользователя, включая доменное имя.

    Тип: Строка. Необязательный

    Особенности формирования логина сотрудника при импорте описаны в разделе Импорт логина сотрудника.

• <connection-code> — внутри тега указывается код подключения. Код подключения к LDAP определяется при добавлении подключения.

  Некоторые параметры указанного подключения (url (строка подключения); user (имя пользователя); passwd (пароль); domain (домен)) могут быть переопределены в параметрах тега <ldap-data-source>. Каждый параметр подключения представляет собой отдельный атрибут тега <ldap-data-source>. Если параметр явно не определен в конфигурации импорта, то он берется из настроек указанного подключения.

  <ldap-data-source id-column="objectGUID" check-user-disabled="false" import-root="false" full-domain="true" user="${ldapUser}" passwd="${ldapPasswd}" url="${ldapUrl}" domain="${ldapDomain}">
  <connection-code>${connectionCode}</connection-code>
  </ldap-data-source>

Особенность импорта дублирующихся объектов

При импорте объектов с одинаковым значением атрибута, указанного в параметре id-column в конфигурационном файле импорта:

• в режиме CREATE — импортируется первый попавший в очередь дублирующийся объект;
• в режиме UPDATE — импортируется последний дублирующийся объект;
• при комбинации режимов CREATE и UPDATE — импортируется последний дублирующийся объект.

Для поиска объектов по нескольким атрибутам в конфигурационном файле импорта можно заполнить тег <complex-object-searcher>.

• Файл конфигурации импорта. Тег <...-searcher>

Режим импорта указывается в конфигурационном файле импорта в теге <mode>.

• Файл конфигурации импорта. Тег <mode>

<hierarchical-filter>

Описание

Тег <hierarchical-filter> определяет необходимость иерархической сортировки импортируемых строк.

Если при импорте одновременно создаются иерархически подчиненные объекты, то при импорте сначала будут обработаны строки содержащие объекты "родители", а затем строки с объектами "потомками". Т.е. гарантируется, что сначала будет проимпортирован объект со значением id-column совпадающим со значением parent-column.

Параметр

• parent-column — название колонки, указывающей на родителя, который считается корнем иерархии, т.е. будет импортироваться первым.

  Тип: Строка. Обязательный

Пример

<hierarchical-filter parent-column="parent"/> 

<column-notempty-filter>

Описание

Тег <column-notempty-filter> указывает фильтр, исключающий из импорта строки с пустым значением указанной колонки в источнике данных.

Параметр

• column — название колонки, в которой надо проверять значение на пустоту.

  Тип: Строка. Обязательный

Пример

<column-notempty-filter column="title"/> 

<id-prefix>

Описание

Тег <id-prefix> позволяет модифицировать значение id-column и parent-column, дописывая к ним в качестве префикса указанное значение. Это позволяет загружать данные из нескольких источников с одинаковыми внешними идентификаторами.

Параметр

• prefix — значение, которое будет подставляться перед внешним идентификатором.

  Тип: Строка. Обязательный

Пример

<id-prefix prefix="prefix-value"/> 

<script-filter>

Описание

Тег <script-filter> указывает фильтр на основе скрипта. С помощью script-filter при импорте выполняется отсеивание ненужных строк данных, соответствующих создаваемым или изменяемым объектам. Обработка выполняется в однопоточном режиме, вне зависимости от значения параметра threads-number в тегах <config> и <class>.

Добавление фильтра может привести к увеличению времени выполнения импорта.

Содержимое тега

Внутри тега задается содержание скрипта, см. Скрипт конфигурации импорта.

Скрипт возвращает:

• true — если строка данных должна участвовать в импорте;
• false — если строку нужно пропустить.

В скрипте доступны контекстные переменные:

• ctx — контекст импорта, получение значений выражений ctx.evaluate(expr);
• item — строка импортируемых данных;

• parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

  Значение параметра внутри скрипта можно получить одним из способов:

  • parameters.<имя_параметра>

  • parameters.get("<имя_параметра>")

Параметр

• mime-type — тип скрипта.

  Тип: Строка. Необязательный. По умолчанию "application/x-groovy".

Примеры

1. В приведенном примере noSkip — имя параметра заданного тегом <parameter>.

<script-filter mime-type="">return item.properties.id != "skip" || "true" == parameters.noSkip</script-filter>

2. В приведенном примере импортируются объекты со значением code = correctCode

<script-filter>
<![CDATA[
if (item.properties.code == "correctCode'') //импортируем объекты со значением code = correctCode
{
return true
}
else
{
return false
}
]]>
</script-filter>

<constant-metaclass-resolver> *

Описание

Тег <constant-metaclass-resolver> задает конкретный метакласс создаваемых объектов. Т.е. все объекты будут созданы с этим метаклассом.

Тег обязателен только для режима CREATE. При обновлении объектов задавать этот параметр не обязательно.

Параметр

• metaclass — метакласс

  Тип: Строка. Обязательный. По умолчанию ${metaClass}.

Пример

<constant-metaclass-resolver metaclass="ou$forTest"/> 

<by-column-metaclass-resolver> *

Описание

Тег <by-column-metaclass-resolver> позволяет определить тип создаваемого объекта по значению колонки импортируемых данных. Т.е. объект будет создан с тем метаклассом, который указан в его колонке.

Тег обязателен только для режима CREATE. При обновлении объектов задавать этот параметр не обязательно.

Параметры

• metaclass — метакласс

  Тип: Строка. Обязательный. По умолчанию ${metaClass}.

• case-column — название колонки, значение которой определяет тип создаваемого объекта.

  Тип: Строка. Обязательный.

• default-case — тип создаваемых значений по умолчанию, если колонка не содержит данных.

  Тип: Строка. Необязательный.

Пример

<by-column-metaclass-resolver metaclass="ou" case-column="caseColumn"/> 

<column-metaclass-resolver> *

Описание

Тег <column-metaclass-resolver> позволяет определить тип создаваемого объекта по значению колонки импортируемых данных.

В отличие от by-column-metaclass-resolver в колонке должен содержаться полный идентификатор метакласса.

Тег обязателен только для режима CREATE. При обновлении объектов задавать этот параметр не обязательно.

Параметры

• column — название колонки, значение которой определяет тип создаваемого объекта.

  Тип: Строка. Обязательный.

• default-metaclass — тип создаваемых значений по умолчанию, если колонка не содержит данных.

  Тип: Строка. Необязательный.

Пример

<column-metaclass-resolver default-metaclass="ou$example" column="сolumn"/> 

<script-metaclass-resolver> *

Описание

Тег <script-metaclass-resolver> позволяет определить тип создаваемого объекта скриптом, на основании входящих данных.

Тег обязателен только для режима CREATE. При обновлении объектов задавать этот параметр не обязательно.

Содержимое тега

Внутри тега задается содержание скрипта.

В скрипте доступны контекстные переменные parameters (параметры импорта), ctx (контекст импорта, получение значений выражений ctx.evaluate(expr)), item (строка импортируемых данных).

Параметр

• mime-type — тип скрипта.

  Тип: Строка. Необязательный. По умолчанию "application/x-groovy".

Пример

<script-metaclass-resolver mime-type="application/x-groovy">
   return item.properties.columnName
</script-metaclass-resolver>

<object-searcher> *

Описание

Тег <object-searcher> задает простое правило поиска объекта по значению атрибута объекта. Объекты ищутся среди объектов с заданным классом /типом.

Используется только для режима UPDATE. При создании объектов задавать этот тег не обязательно.

Параметры

• attr — атрибут, по которому осуществляется поиск объекта.

  Тип: Строка. Обязательный. По умолчанию ${idHolder}

• metaclass — тип объектов, среди которых осуществляется поиск.

  Тип: Строка. Обязательный. По умолчанию ${metaClass}

Пример

<object-searcher attr="idHolder" metaclass="ou$forTest"/>

<complex-object-searcher> *

Описание

Тег <complex-object-searcher> задает последовательность поиска объекта по нескольким атрибутам объекта или поиск по различным классам /типам.

Параметров нет.

Используется только для режима UPDATE. При создании объектов задавать этот тег не обязательно.

Пример

<complex-object-searcher>
    <object-converter attr="idHolder" metaclass="ou$forTest"/>
    <object-converter attr="title" metaclass="ou"/>
    <script-converter>a + b</script-converter>
</complex-object-searcher> 

<script-object-searcher> *

Описание

Тег <script-object-searcher> позволяет находить объект по сложной логике поиска.

Используется только для режима UPDATE. При создании объектов задавать этот тег не обязательно.

Содержимое тега

Внутри тега задается содержание скрипта.

В скрипте доступны контекстные переменные parameters (параметры импорта), ctx (контекст импорта, получение значений выражений ctx.evaluate(expr)), item (строка импортируемых данных).

Параметр

• mime-type — тип скрипта.

  Тип: Строка. Необязательный. По умолчанию "application/x-groovy"

Пример 1

<script-object-searcher mime-type="application/x-groovy">
   a + b
</script-object-searcher> 

Пример 2. Поиск объекта по сложной логике

Пример поиска, происходящего по разным типам, в зависимости от значения type:

<script-object-searcher mime-type="application/x-groovy"> 
<![CDATA[
def mc 
def type = item.properties.type 
   if (type == 'принтер') 
   { 
   mc = 'objectBase$Printer' 
   } 
   if (type == 'монитор') 
   { 
   mc = 'objectBase$Monitor' 
   }   
utils.find(mc, ['serialNumber':item.properties.serialNumber])[0] 
]]> 
</script-object-searcher>

Тег <attr> *

Описание

Тег <attr> описывает присваивание атрибуту объекта значение из колонки источника импорта.

Вложен в <class>.

В конфигурации импорта должен быть хотя бы один тег <attr>

В теге <attr> указывается:

• режим импорта, в котором нужно или не нужно заполнять атрибут;
• преобразователь значения, при необходимости привести значение атрибута из источника к какому-то специальному виду (если преобразователь не указан, то он будет определен на основе метаинформации).

Параметры

• name — код атрибута, в который надо сохранить значение.

  Тип: Строка. Обязательный

• column — название колонки, из которой надо взять данные для присваивания.

  Используется название колонки, которое было присвоено в источнике <...-data-source> (вложенный тег <column>, параметр name).

  Если название колонки не указано, то устанавливается значение из default-value.

  Тип: Строка. Обязательный

  При импорте атрибута "Название" (title) нужно указывать конкретную колонку, в которую сохраняется значение. Возможные колонки: title, title_ru, title_en, title_client

• default-value — значение атрибута, устанавливаемое по умолчанию в случае пустого значения из источника данных.

  Тип: Строка. Необязательный

  Примеры:

  1. Если включен режим Update, следующая строка вернет архивные объекты из архива, если такие объекты присутствуют в источнике импорта:

  <attr name="removed" default-value="false"/>

  2. Импортировать корневой отдел импорта в отдел с заданным UUID, а не в root (Компанию):

  <attr name="parent" column="parent" default-value="ou$3799801"/>

  3. Использования default-value для атрибутов, ссылающихся на объекты, например, parent

  <parameter name="importRootOUIdHolder">\c7\c9\ac\ea\c8\29\2c\4d\af\da\9c\be\48\21\d3\84</parameter>
  <parameter name="ouIdHolder">idHolder</parameter>
  ...
  <attr name="parent" column="parent" default-value="${importRootOUIdHolder}">
     <object-converter attr="${ouIdHolder}" required="false"/>
  </attr>

  <parameter name="obMetaClass">objectBase$SpravAsSBS</parameter>
  ...
  <attr name="infoSystem" default-value="objectBase$2206702" > 
     <object-converter attr="UUID" metaclass="${obMetaClass}" required="true" />
  </attr> 

• not-null — указывает обязательность заполнения значения атрибута.

  Возможные значения параметра:

  • true — атрибуту в обязательном порядке должно быть присвоено не пустое значение. Если значение будет пустое, то объект импортироваться не будет (ошибка импорта).
  • false — значение атрибута может быть пустым.

  Тип: Логический. Обязательный

<include-mode>/<exclude-mode>

Теги <include-mode>/<exclude-mode> используются, чтобы указать необходимость заполнять атрибут только в определенном режиме импорта объекта (CREATE, UPDATE).

Вложены в <attr>.

• <include-mode> — внутри тега задается режим, в котором необходимо заполнять (изменять) атрибут.
• <exclude-mode> — внутри тега задается режим, в котором не требуется заполнять (изменять) атрибут.

Вложенные теги <include-mode>/<exclude-mode> указывать необязательно. Если эти теги не заданы, то по умолчанию значение атрибута будет заполнено во всех режимах импорта, где это возможно.

Пример 1: необходимо заполнить атрибут в режиме импорта CREATE:

<attr name="" column="" default-value="" not-null="true">
<attr name="idHolder" column="id">
   <include-mode>CREATE</include-mode>
</attr>
<attr name="title" column="title" />

Пример 2: не заполнять атрибут в режиме импорта UPDATE:

<attr name="" column="" default-value="" not-null="true">
<attr name="idHolder" column="id">
   <exclude-mode>UPDATE</exclude-mode>
</attr>
<attr name="title" column="title" />

<ad-image-converter>

Тег <ad-image-converter> указывает, что нужно импортировать картинки из AD, используется для преобразования и сравнения картинок.

Вложен в <attr>.

Логика работы

• Если mode = CREATE, то атрибуты заполняются, как обычно.
• Если mode = UPDATE, то если в атрибуте лежал такой же файл — редактирование не происходит.
• Если было пусто, либо файлов больше 1, либо 1, но другой — устанавливается новое значение.
• Если старое значение было не пусто, а новое = null, то старое значение затрется, либо нет — в зависимости от флага eraseOld.

Параметры

• title — название загружаемого файла.

  Тип: Строка. Необязательный. По умолчанию picture

• mimeType — формат хранения (Mime Type) загружаемого файла.

  Тип: Строка. Необязательный. По умолчанию image/jpeg

• eraseOld — определяет, нужно ли удалять старое значение атрибута, если его значение не пусто, а новое значение пусто.

  Возможные значения параметра:

  • true — старое не пустое значение файла удаляется;
  • false — старое не пустое значение файла сохраняется.

  Тип: Логический. Необязательный. По умолчанию false

Пример

<attr name="idHolder" column="id">
   <ad-image-converter title='pic.jpg' mimeType='image/jpeg' eraseOld='true'/>
</attr>

<boolean-converter>

Тег <boolean-converter> преобразует импортируемое значение в логическое значение.

Вложен в <attr>.

Параметр

• true-value — задает значение соответствующее "истине".

  Если значение атрибута не задано, то импортируемые данные считаются true, в случаях если значение true или yes.

  Тип: Строка. Обязательный.

Пример

<attr name="idHolder" column="id">
   <boolean-converter true-value="goodValue" />
</attr>

<case-list-converter>

Тег <case-list-converter> преобразует импортируемое значение в набор типов класса.

Вложен в <attr>.

Параметры

• delimiter — символ, которым отделены объекты.

  Тип: Символ. Обязательный.

• class — класс, среди типов которого производится поиск типов.

  Тип: Строка. Обязательный.

Пример

<attr name="idHolder" column="id">
    <case-list-converter delimiter="," class="ou"/>
</attr>

<collection-converter>

Тег <collection-converter> преобразует коллекцию значений (для атрибутов типа "Набор ссылок на бизнес-объект" и "Набор элементов справочника") — определяет соответствие для каждого объекта во входящих данных и перенаправляет преобразование к конкретному конвертеру.

Вложен в <attr>.

Параметры

• delimiter — символ, которым отделены объекты.

  Тип: Символ. Обязательный

Пример

<attr name="idHolder" column="id">
   <collection-converter delimiter=",">
       <object-converter attr="idHolder" metaclass="ou"/>
       <script-converter></script-converter>
   </collection-converter>
</attr>

<complex-object-converter>

Тег <complex-object-converter> указывает, что нужно преобразовать импортируемое значение в объект. Задает одно или более правил поиска объекта complex-object-converter и выполняет указанные в нем правила последовательно. В порядке определения в xml конвертер переходит к следующему правилу, только если предыдущий вернул null.

Вложен в <attr>.

Пример

<attr name="idHolder" column="id">
    <complex-object-converter>
        <object-converter attr="" metaclass=""/>
        <script-converter>a + b</script-converter>
    </complex-object-converter>
</attr>

<datetime-converter>

Тег <datetime-converter> преобразует импортируемое значение (строку) в дату или дату /время. Используется, если в источнике импорта дата хранится в виде строки с использованием шаблона даты, например, 2022-02-22 12:34:56 (yyyy-MM-dd HH:mm:ss).

Вложен в <attr>.

Если в источнике импорта дата хранится как количество миллисекунд, прошедших с 1 января 1970 года 00:00:00, необходимо использовать преобразование даты с помощью тега Файл конфигурации импорта. Общий.

Если в качестве источника импорта используется AD, дата может храниться в нестандартном формате, подробнее см. Импорт отделов и сотрудников из Active Directory - Особенности загрузки даты из AD.

Параметр

• format — параметр, в котором задается формат даты из источника импорта:

  yyyy-MM-dd (дата);

  yyyy-MM-dd HH:mm:ss (дата/время в 24-часовом формате);

  yyyy-MM-dd hh:mm:ss a (дата/время в 12-часовом формате).

  Тип: Строка. Обязательный.

Пример 1

Дата в источнике импорта:

2022-02-22 12:34:56 (в формате yyyy-MM-dd HH:mm:ss).

Параметр:

<attr name="idHolder" column="id">
    <datetime-converter format="yyyy-MM-dd HH:mm:ss"/>
</attr>

Если в параметре будет указан формат даты, который отличается от формата в источнике импорта, то преобразование завершится с ошибкой, например, если в источнике импорта содержится дата в формате yyyy-MM-dd, а в параметре указан формат yyyy-MM-dd HH:mm:ss.

Пример 2

Конвертор дат с указанием часового пояса time-zone, в котором приходит дата в импортируемых данных.

<attr name="creationDate" column="whenCreated">
    <datetime-converter format="yyyyMMddHHmmss'.0Z'" time-zone="GMT+0:00"/>
</attr>

<double-converter>

Тег <double-converter> преобразует импортируемое значение в вещественное число.

Вложен в <attr>.

Параметров нет.

Пример

<attr name="idHolder" column="id">
    <double-converter/>
</attr>

<file-content-converter>

Тег <file-content-converter> преобразует импортируемое значение в строку.

Вложен в <attr>.

Параметры

• titleColumn — колонка, в которой хранится название файла.

  Тип: Строка. Обязательный.

• mimeTypeColumn — колонка, в которой указывается mimeType файла.

  Тип: Строка. Обязательный.

<hyperlink-converter>

Тег <hyperlink-converter> преобразует импортируемое значение в гиперссылку.

Вложен в <attr>.

Параметр

• delimiter — символ, которым разделены названия ссылки и URL ссылки.

  Тип: Символ. Обязательный.

Пример

<attr name="idHolder" column="id">
    <hyperlink-converter delimiter=";"/>
</attr>

<integer-converter>

Тег <integer-converter> преобразует импортируемое значение в целое число.

Вложен в <attr>.

Параметров нет.

Пример

<attr name="idHolder" column="id">
    <integer-converter />
</attr>

<localized-column>

Тег <localized-column> используется только для системного локализованного атрибута title и указывает в какой язык какое значение нужно сохранить. Если тег указан, а title не локализован, то тег игнорируется.

Также во вложенном теге <column> тега <...-data-source> необходимо указать, откуда брать значения для локализованного атрибута title.

Вложен в <attr>.

Параметры

• lang — язык, в который нужно сохранить значение из источника. Возможные значения: ru, en, client.

  Тип: Строка. Обязательный.

• column — название колонки, из которой надо взять значение.

  Тип: Строка. Обязательный.

Пример

<attr name="title" column="title">
    <localized-column lang="ru" column="title_ru"/>
    <localized-column lang="en" column="title_en"/>
    <localized-column lang="client" column="title_client"/>
</attr>

<object-converter>

Тег <object-converter> преобразует импортируемое значение в объект. Если найдено более одного значения, то возвращает произвольный объект.

Вложен в <attr>.

Параметры

• attr — имя атрибута, по которому производится поиск объекта.

  Тип: Строка. Обязательный. По умолчанию ${idHolder}

• metaclass — код метакласса, среди объектов которого производится поиск.

  Тип: Строка. Обязательный. По умолчанию ${metaclass}

• required — определяет, нужно ли обязательно искать объекты.

  Возможные значения параметра:

  • true — конвертор обязательно должен найти объект, а если объект не нашелся, то сообщать об ошибке и импорт объекта не производить.

    Если конвертируемое значение пусто, то результатом преобразования будет NULL вне зависимости от значения параметра.

    Если значение false и объект не будет найден, то будет возвращен null

  • false — объект может быть не найден.

  Тип: Логический. Обязательный. По умолчанию true

• removed — определяет, нужно ли искать архивные объекты. Если не указан, то ищутся все объекты

  Возможные значения параметра:

  • true — ищет только архивные объекты
  • false — ищет только не архивные объекты.

  Тип: Логический. Необязательный.

Пример

<attr name="idHolder" column="id">
    <object-converter attr="idHolder" metaclass="ou"/>
</attr>

<script-converter>

Тег <script-converter> задает произвольное правило преобразования значения на основе скрипта.

Вложен в <attr>.

Содержимое тега

Внутри тега задается содержание скрипта.

В скрипте доступны контекстные переменные:

• parameters — параметры импорта.
• ctx — значение выражения (параметра), используется как ctx.evaluate("parameter");
• item — строка импортируемых данных;
• value — конвертируемое значение;
• subject — импортируемый объект;

• storage — значение, передаваемое из одного скрипта в другой, в рамках конфигурации импорта.

Доступна только для чтения глобальная переменная subject соответствующая проимпортированному объекту.

Параметр

• mime-type — тип скрипта.

  Тип: Строка. Необязательный. По умолчанию application/x-groovy.

Пример 1

<attr name="idHolder" column="id">
    <script-converter mime-type="application/x-groovy"> a + b </script-converter>
</attr>

Пример 2. Назначение категории в соответствии с группами AD

<script-converter mime-type="application/x-groovy"> 
if(null == value || value.trim().isEmpty()) 
{ 
return utils.get('categoriesUsers',['code':'regular']); 
} 
if(value.contains('CN=_SMP_vip,OU=SMP,OU=Servers,DC=bank,DC=ru')) 
{ 
return utils.get('categoriesUsers',['code':'VIP']); 
} 
return utils.get('categoriesUsers',['code':'regular']); 
</script-converter>

Пример 3

Преобразование даты, которая хранится в источнике импорта как число миллисекунд, прошедших с 1 января 1970 года 00:00:00.

<attr name="discardDate" column="discardDate" >
   <script-converter>
     <![CDATA[
        if (value == null) {
          return null
          }
          return new Date(value)
     ]]>
   </script-converter>

Если количество миллисекунд передано в строке (а не числом), необходимо value указывать следующим образом:

return new Date(value.toInteger())

<string-converter>

Тег <string-converter> преобразует импортируемое значение в строку.

Вложен в <attr>.

Параметры

• trim — определяет, нужно ли удалять пробелы в начале и конце строки.

  Возможные значения параметра:

  • true — пробелы удаляются;
  • false — пробелы сохраняются.

  Тип: Логический. Необязательный.

Пример

<attr name="idHolder" column="id">
    <string-converter trim="true"/>
</attr>

<time-interval-converter>

Тег <time-interval-converter> преобразует импортируемое значение во временной интервал.

Вложен в <attr>.

Параметры

• interval — используемая единица измерения, возможные значения: SECOND, MINUTE, HOUR, DAY, WEEK, CUSTOM.

  CUSTOM — тип интервала в конфигурации импорта, который может читать файлы-источники, содержащие значения типа "[Значение] пробел [Единица измерения]" и создавать объекты в соответствии с указанной цифрой и размерностью. Например, создать объект с интервалом в 1 день, если в импортируемом файле интервал для объекта записан, как "1 DAY".

  Если параметр не заполнен, то единица измерения берется из файла с импортируемыми данными.

  Тип: Строка. Обязательный.

Пример

<attr name="idHolder" column="id">
    <time-interval-converter interval="SECOND"/>
</attr>

Тег <metaclass-attrs>

Описание тега

Тег <metaclass-attrs> — позволяет импортировать значения пользовательских атрибутов, объявленных в конкретном классе/типе. Атрибуты можно группировать по классам и типам.

Вложен в <class>.

Тег <metaclass-attrs> должен располагаться после всех тегов <attr> (в конфигурации импорта должен быть хотя бы один тег <attr>).

Параметров нет.

Вложенные теги

• <metaclass> — могут быть указаны один и более тегов (каждый для своего класса/типа), в которых нужно заполнять атрибуты;

• <attr> — пользовательские атрибуты.

  Параметр:

  • name — код атрибута.

    Тип: Строка. Обязательный

  Пример:

  <metaclass-attrs>
      <metaclass></metaclass>
      <attr name="" />
  </metaclass-attrs>

<remove-customizer>

Описание

Тег <remove-customizer> помещает в архив все объекты, которые не участвуют в импорте и иерархически находятся в объекте с указанным uuid. Обработка выполняется в однопоточном режиме после импорта всех объектов.

Объекты, не участвующие в импорте — объекты системы, которым в рамках текущего импортируемого класса конфигурации не удалось найти соответствия среди объектов в источнике.

Вложен в <class>, располагается после описания импорта значений.

Кастомайзер работает для режимов UPDATE и EMPTY и игнорируется для режима CREATE.

Если тег <remove-customizer> указан, то в архив поместятся объекты системы, удовлетворяющие следующим условиям:

• у них заполнен атрибут, указанный в качестве значения параметра attr (если параметр присутствует);
• тип объектов соответствует метаклассу, указанному в качестве значения параметра metaclass;
• объекты иерархически находятся в объекте, UUID которого задан в качестве значения параметра hierarchy-root;
• объекты, не участвующие в текущем импорте класса конфигурации.

Параметры

• hierarchy-root — UUID объекта, в иерархии которого необходимо произвести архивирование объектов, не участвующих в текущем импорте класса конфигурации. Для архивирования всех объектов указанного типа, не участвующих в текущем импорте, необходимо указать UUID объекта класса "Компания".

  Пример: класс "Сотрудник" (employee) вложен в класс "Отдел" (ou), если указываем hierarchy-root = 'ou$123', то в архив попадают только сотрудники отдела с UUID = 'ou$123', если указываем компанию, то в архив попадают сотрудники всех отделов.

  Если данный параметр не указан, то применяется значение по умолчанию, заданное в теге <parameter> (параметр importRootUUID). Если значение параметра importRootUUID не задано, то синхронизация не будет выполнена.

  Тип: Строка. Необязательный. По умолчанию ${metaClass}.

• metaclass — метакласс объектов для архивации.

  Если данный параметр не указан, то применяется значение по умолчанию , заданное в теге <parameter> (параметр metaClass). Если значение параметра metaClass не задано, то синхронизация не будет выполнена.

  Тип: Строка. Необязательный.

• attr — код атрибута, по значению которого проверяется что объект импортирован, а не создан вручную.

  Если параметр не указан, то в архив помещаются все объекты метакласса, указанного в параметре metaclass, находящиеся в иерархии объекта, UUID которого указан в параметре hierarchy-root и не участвующие в текущем импорте класса конфигурации.

  Если параметр указан, то в архив будут помещены объекты метакласса, указанного в параметре metaclass, находящиеся в иерархии объекта, UUID которого указан в параметре hierarchy-root, у которых значение данного атрибута заполнено.

  Тип: Строка. Необязательный.

Примеры

1. UUID корневого отдела:

   <parameter name="importRootUUID">ou$01</parameter>

2. Метакласс импортируемых отделов:

   <parameter name="metaClass">employee</parameter>

3. В архив попадут объекты метакласса employee, заданного в теге <parameter>, отдела ou$01, заданного в теге <parameter>, у которых атрибут flag был заполнен (не пустой) и которые не участвуют в импорте:

   <remove-customizer attr="flag" />

4. В архив попадут объекты метакласса employee, заданного в теге <parameter>, отдела ou$02, которые не участвовали в импорте:

   <remove-customizer hierarchy-root="ou$02" />

5. В архив попадут объекты метакласса employee$contactPerson, отдела ou$01, заданного в теге <parameter>, которые не участвовали в импорте:

   <remove-customizer metaclass="employee$contactPerson" />

6. В архив попадут объекты метакласса employee$contactPerson, отдела ou$02, заданного в теге <parameter>, у которых атрибут flag был заполнен (не пустой), и которые не участвуют в импорте:

   <remove-customizer attr="flag" hierarchy-root="ou$02" metaclass="employee$contactPerson" />

7. Если включен режим Update, следующая строка вернет архивные объекты из архива, если такие объекты присутствуют в источнике импорта:

   <attr name="removed" default-value="false"/>

8. Если включен режим Update, следующая строка переведет в архив все объекты метакласса ${employeeMetaClass}, находящиеся в ${importRootUUID}, которые не участвовали в импорте:

   <remove-customizer hierarchy-root="${importRootUUID}" metaclass="${employeeMetaClass}" attr="${employeeIdHolder}"/->

Вложенные скриптовые обработчики

Вложенные скриптовые обработчики применяются, если необходимо задать исключение для архивации объектов:

• skip-objects-script — указывает объекты, которые исключаются из архивирования.

  Скрипт выполняется один раз до начала работы remove-customizer.

  Скрипт возвращает список UUID объектов. Результирующий список UUID добавляется к списку UUID, участвующих в импорте и не подлежащих архивации.

  Глобальные переменные:

  • parent — объект, в иерархии которого необходимо произвести архивирование не проимпортированных объектов. Значение по умолчанию ${importRootUUID} или параметр hierarchy-root;
  • ctx — ImportContext: ctx.evaluate(expr) для получения значения выражений или ctx.getLogger().info('text') для логирования;
  • storage — значение, передаваемое из одного скрипта в другой в рамках конфигурации импорта, во всех скриптах кастомайзера;

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  Пример. Исключить все вложенные в объект hierarchy-root объекты:

  <skip-objects-script><![CDATA[
     return utils.find(parameters.metaClass, [ 'parent' : parent ])
   ]]>
  </skip-objects-script>

• remove-condition-script — добавляет дополнительное условие архивации объекта и/или изменяет объект перед архивацией.

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

  Глобальные переменные:

  • subject — объект, подлежащий архивации при работе remove-customizer;
  • ctx — ImportContext: ctx.evaluate(expr) для получения значения выражений или ctx.getLogger().info('text') для логирования;
  • storage — значение, передаваемое из одного скрипта в другой в рамках конфигурации импорта, во всех скриптах кастомайзера;

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  Пример 1. Отменить архивацию объекта, если его название не testTitle:

  <remove-condition-script><![CDATA[
     return subject.title == 'testTitle'
    ]]>
  </remove-condition-script>

  Пример 2. Изменить атрибут в объекте и продолжить архивацию:

  <remove-condition-script><![CDATA[
     utils.edit(subject, ['isEmployeeLocked': true], true);  
     return true
  </remove-condition-script>

  Скрипт должен возвращать логическое значение (Boolean). Если возвращается значение другого типа, процесс архивации будет остановлен.

<script-customizer>

Описание

Тег <script-customizer> позволяет производить преобразования по сложной логике, определенной в скрипте.

Вложен в <class>, располагается после описания импорта значений.

Скриптовая логика обработки указывается во вложенных тегах. Каждый из вложенных тегов соответствует какому-то из этапов импорта, соответственно и скрипт, указанный в теге, будет выполнятся на соответствующем этапе импорта.

Вложенные теги

• <before-import> — содержит скрипт, который вызывается перед импортом объектов.

  В скрипте доступны глобальные переменные:

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

• <before-process-item> — содержит скрипт, который вызывается перед созданием или изменением объекта в системе. Скрипт срабатывает в момент, когда обработана строка, но еще не сформированы значения атрибутов (properties) для создания или редактирования объекта.

  В скрипте доступны глобальные переменные:

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  • item (для чтения /записи) — соответствует строке импортируемых данных;
  • subject (только для чтения) — соответствует проимпортированному объекту.

• <before-process> — содержит скрипт, который вызывается перед созданием или изменением объекта в системе. Скрипт срабатывает в момент, когда обработана строка и сформированы значения атрибутов (properties) для создания или редактирования объекта.

  В скрипте доступны глобальные переменные:

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  • item (только для чтения) — соответствует строке импортируемых данных;
  • subject (только для чтения) — соответствует проимпортированному объекту;
  • properties (только для чтения) — содержит свойства бизнес-процесса — итоговые значения атрибутов, которые будут использоваться в бизнес-процессе.

• <after-process> — содержит скрипт, который вызывается после создания или изменения объекта в системе.

  В скрипте доступны глобальные переменные:

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

  • item (для чтения /записи) — соответствует строке импортируемых данных;
  • subject (только для чтения) — соответствует проимпортированному объекту.

• <after-import> — содержит скрипт, который вызывается после импорта всех объектов.

  В скрипте доступны глобальные переменные:

  • parameters — параметры импорта. Содержит объединенные значения из тегов <gui-parameter>, <parameter> и <script-parameter>.

    Значение параметра внутри скрипта можно получить одним из способов:

    • parameters.<имя_параметра>

    • parameters.get("<имя_параметра>")

Если при импорте создается или обновляется объект, у которого на атрибуты типа "Дата", "Дата/время" настроено действие по событию "Наступление времени атрибута" и даты в значении этих атрибутах указаны в будущем, то такое действие по событию будет запланировано и выполнится корректно в указанное время.
Правило актуально, если атрибуты типа "Дата", "Дата/время" заполняются в теге <after-process> </after-process> .
Если атрибуты типа "Дата", "Дата/время" заполняются в теге <after-import> </after-import>, то действие по событию не запланируется и не будет выполнено.

Скрипты из тегов <before-process> и <after-process> запускаются после каждой строки, вне зависимости от того, создавались(изменялись) объекты или нет.

Пример 1.

<script-customizer>
   <before-import></before-import>
   <before-process-item>a+b</before-process-item>
   <before-process>a+b</before-process>
   <after-process>a+b</after-process>
   <after-import></after-import>
</script-customizer>

Пример 2. Использование значения параметров из тега <gui-parameter> в теге <script-customizer>

<!-- Определение параметра в теге config -->
<gui-parameter name="guiparam" type="STRING" title="Введите параметр"> 

<script-customizer>
   <before-process-item>
      modules.Service.method(parameters.guiparam)
   </before-process-item>
</script-customizer>

<timer-customizer>

Описание

Тег <timer-customizer> позволяет импортировать прямой счетчик времени.

Вложен в <class>, располагается после описания импорта значений.

Параметры

• attr — код атрибута типа Timer.

  Тип: Строка. Обязательный.

• column — название колонки, в которой хранится сколько уже отсчитал счетчик в мс.

  Тип: Строка. Обязательный.

Пример

<timer-customizer attr="totalTimeTimer" column="timer"/>

<backtimer-customizer>

Описание

Тег <backtimer-customizer> позволяет импортировать обратный счетчик времени.

Вложен в <class>, располагается после описания импорта значений.

Параметры

• attr — код атрибута типа BackTimer.

  Тип: Строка. Обязательный.

• allowance-column — название колонки, в которой хранится сколько осталось отсчитать счетчику в мс.

  Тип: Строка. Обязательный.

• deadline-column — название колонки, в которой хранится deadline для данного счетчика в формате deadline-column-format.

  Тип: Строка. Обязательный

• deadline-column-format — формат преобразования даты deadline, например, yyyy-MM-dd HH:mm:ss.

  Тип: Строка. Обязательный.

Пример

<backtimer-customizer
   attr="timeAllowanceTimer"
   allowance-column="backTimer"
   deadline-column="deadlineTime"
   deadline-column-format="dd.MM.yyyy HH:mm:ss"/>