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

Тег <...-data-source> описывает источник данных, вместо ... указывается тип источника.

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

Для всех источников данных при использовании object-searcher, complex-object-searcher, script-object-searcher обязательно должен быть заполнен параметр id-column, иначе поиск объектов выполняться не будет, см. Файл конфигурации импорта. Тег <...-searcher>.

<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.

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

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

  • <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> описывает источник данных из SQL баз данных."

Параметр

  • 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;

    • Переменная 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 файл считывается полностью в память, строится его дерево и только после этого происходит импорт.

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

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

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

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

  • 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.

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

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

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

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

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

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

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

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

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

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

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

    • 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>
  • <root-element> — внутри тега задается корень (DN) иерархии объектов LDAP для импорта. Необходимо указать как минимум один корень. Спецсимволы в названии "=", "\", "," следует экранировать обратным слэшем.

  • <import-tag> — внутри тега задается префикс элементов импорта, по которым будет осуществляться фильтрация. Можно указать несколько раз.

    Пример. Запись каталога:

    • №1 — DN: cn=Иванов Иван,ou=Специалисты 1 линии,dc=Почта
    • №2 — DN: cn=Петров Петр,ou=Специалисты 1 линии,dc=Почта
    • №3 — DN: ou=Специалисты 1 линии, dc=Почта

    Значение import-tag:

    • cn — импортируются записи №1 и №2, т.к. их DN начинается с cn.
    • ou — импортируется запись №3, т.к. ее DN начинается с ou.
    • значение, отличное от ou и cn — игнорируются все записи (№1, №2 и №3).

  • <ignored-postfix> — внутри тега задается список постфиксов, не включаемых при импорте. Указывает полный путь (DN) до иерархии игнорируемых объектов LDAP для импорта. Может быть использован несколько раз для одного или нескольких корней.

    В перечислении недопустимы лишние пробелы до и после запятых.

  • <allowed-postfix> — внутри тега задается список постфиксов, включаемых при импорте. Указывает полный путь (DN) до импортируемой иерархии объектов LDAP для импорта. Состоит из полного пути включая корень.

    Если указан хотя бы один allowed-postfix, все импортируемые объекты, которые не будут ему соответствовать будут отброшены. Имеет приоритет ниже чем ignored-postfix. Можно указать несколько раз для одного или нескольких корней.

  • <filter> — фильтр (критерий) поиска объектов в LDAP.

    Значение по умолчанию:

    (|(&(objectClass=user)(objectCategory=person))(objectClass=organizationalUnit))

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

    <filter><![CDATA[ (|(&(objectClass=user)(objectCategory=person))(objectClass=organizationalUnit))]]></filter>

    Чтобы импортировать другие типы объектов, необходимо добавить соответствующие условия в тег.

    Пример для импорта групп:

    <filter><![CDATA[ (|(&(objectClass=user)(objectCategory=person))(objectClass=organizationalUnit)(objectClass=group))]]></filter>

    При указании тега <filter> не должно быть переносов на новую строку, тег должен быть указан одной строкой.

    Уровни поиска

    При поиске объектов используется тип вложенности SearchControls.ONELEVEL_SCOPE, который ограничивает поиск только на одном уровне под заданным DN.

    Чтобы выполнить поиск по всем уровням дерева, необходимо добавить в тег <filter> дополнительное условие.

    Пример.

    Чтобы импортировать из AD в систему (SMP) объекты определенного типа (например, группы пользователей), которые находятся на любом уровне вложенности (в корне домена или в любой папке OU), то в фильтре нужно указать не только условие фильтрации по нужному типу объекта "objectClass=group", но и добавить условие "ИЛИ objectClass=organizationalUnit":

    <filter><![CDATA[ (|(objectClass=organizationalUnit)(objectClass=group))]]></filter>

    В результате поиск будет произведен по всем отделам (OU) и дойдет до нужных объектов.

    Чтобы при этом не импортировались отделы, найденные фильтром, в конфигурации импорта нужно указать префикс элементов импорта, по которым будет осуществляться фильтрация:

    <import-tag>cn</import-tag>

    В результате будут импортированы все отфильтрованные объекты, DN которых начинается с "CN" и не будут импортированы OU, потому что их DN начинается с "OU". Т.е. будут импортированы все группы пользователей на любом уровне вложенности, начиная с корня домена.

Пример

<ldap-data-source check-user-disabled="true" full-domain="true" import-root="true" domain="">
    <column name="" src-key=""/>       
    <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>

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

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

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

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

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