Трансформация данных AtlasMap

AtlasMap - инструмент для удобного преобразования данных в рамках интеграционной платформы Entaxy ION.

Интерфейс AtlasMap

  • Entaxy Transformation:

    atlasmap export
    • Import a catalog (.adm): Импортировать каталог (формат .adm).

    • Open a catalog from Entaxy registry (.adm): Открыть каталог из реестра схем Entaxy (формат .adm).

    • Export the current mappings and support files into a catalog (.adm): Экспортировать текущий маппинг и вспомогательные файлы в каталог (формат .adm).

    • Save the current mappings and support files into Entaxy registry (.adm): Сохранить текущий маппинг и вспомогательные файлы в реестр схем Entaxy (формат .adm).

    • Reset all mappings and clear all imported documents: Сбросить все маппинги и очистить данные импортированных документов.

      atlasmap headermenu
      1. Show Column Mapper: Показать маппинг в виде двух столбцов.

      2. Show Mapping Table: Показать маппинг в виде таблицы.

      3. Show Namespace Table: Показать таблицу пространств имен.

      4. Show/Hide mapping Preview: Показать/скрыть предварительный просмотр маппинга.

      5. Show/Hide types: Показать/скрыть тип полей.

      6. Show/Hide mapped Fields: Показать/скрыть сопоставленные поля.

      7. Show/Hide unmapped Fields: Показать/скрыть не сопоставленные поля.

      8. Add a New mapping: Добавить новое сопоставление.

      9. About AtlasMap: Информация об AtlasMap.

    atlasmap source
  • Source: Поле загрузки и отображения источника данных.

    • Import instance or schema file: Импортировать файл данных или схемы.

    • Open instance or schema file from Entaxy registry: Открыть файл данных или схемы из реестра схем Entaxy.

    • Properties: Используемые свойства.

    • Constants: Используемые константы.

    atlasmap target
  • Target: Поле загрузки и отображения цели данных.

    • Import instance or schema file: Импортировать файл данных или схему.

    • Open instance or schema file from Entaxy registry: Открыть файл данных или схему из реестра схем Entaxy.

    • Properties: Свойства.

Поддерживаемые типы данных

  • XML schema or instance files

  • JSON schema or instance files

Создание маппинга AtlasMap

После выбора входной точки маршрута добавьте маппинг AtlasMap в ваш маршрут. В веб-консоли Entaxy перейдите в раздел 'Entaxy Transformation'. Затем создайте новую конфигурацию AtlasMap или откройте существующую в зависимости от ваших потребностей.

В AtlasMap данные представлены в виде источника (Source) и цели (Target). Источник содержит данные, полученные из вашей входной точки маршрута, а цель указывает, как будут представлены преобразованные данные. Воспользуйтесь графическим интерфейсом AtlasMap для создания маппингов между полями и элементами данных источника и цели.

Для корректного маппинга в AtlasMap важно, чтобы структура данных в формате JSON была однородной в каждом элементе массива.

Например, в следующем примере структура неоднородна, так как один из элементов массива содержит дополнительное поле 'phone':

{
  "employees": [
    {
      "id": 123,
      "address": {
        "city": "Moscow"
      },
      "contact": {
        "name": "Ivan"
      }
    },
    {
      "id": 123,
      "address": {
        "city": "St. Petersburg"
      },
      "contact": {
        "name": "Maria"
      },
      "phone": {
        "number": "123456789"
      }
    }
  ]
}

Следующая однородная структура данных позволит успешно использовать AtlasMap:

{
  "employees": [
    {
      "id": 123,
      "address": {
        "city": "Moscow"
      },
      "contact": {
        "name": "Ivan"
      },
      "phone": {
        "number": "123456789"
      }
    },
    {
      "id": 123,
      "address": {
        "city": "St. Petersburg"
      },
      "contact": {
        "name": "Maria"
      },
      "phone": {
        "number": "123456789"
      }
    }
  ]
}

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

Пример:

<?xml version="1.0" encoding="UTF-8"?>
<Envelope xmlns="http://example.com/schema">
    <Header>
        <RequestID>12345</RequestID>
        <TimeStamp>2024-08-23T10:00:00+03:00</TimeStamp>
    </Header>
    <Body>
        <Order>
            <Item>
                <Quantity>1001</Quantity>
                <ProductID>5</ProductID>
            </Item>
            <Item>
                <ProductID>1002</ProductID>
                <Quantity>3</Quantity>
            </Item>
            <Item>
                <ProductID>1003</ProductID>
                <Quantity>2</Quantity>
            </Item>
        </Order>
        <Shipping>
            <Address>
                <Street>Main St</Street>
                <City>Springfield</City>
            </Address>
            <Address>
                <Street>Elm St</Street>
                <City>Shelbyville</City>
            </Address>
        </Shipping>
    </Body>
</Envelope>

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

  1. Сопоставление полей:

    atlasmap namename

    Установите соответствие между полями и элементами данных источника и цели. Например, сопоставьте поле "name" из источника с полем "name" в цели. Поддерживается объединение нескольких полей в одном поле.

    AtlasMap умеет выполнять следующие виды сопоставлений данных:

    • Один к одному (One to one): Это означает, что вы можете установить соответствие между одним исходным полем и одним целевым полем.

    • Многие к одному (Many to one): Этот вид сопоставления позволяет связать несколько исходных полей с одним целевым полем.
      Вы определяете символ разделителя, который будет вставлен в целевое поле между данными, полученными из разных исходных полей.
      По умолчанию, это пробел.

    • Один ко многим (One to many): В этом случае вы можете установить соответствие между одним исходным полем и несколькими целевыми полями. Вы указываете символ разделителя в исходном поле, и AtlasMap автоматически разбивает значение на части с использованием указанного разделителя, затем присваивает каждую часть выбранным целевым полям.

    • Для каждого (For each): Этот вид сопоставления позволяет итеративно устанавливать соответствие между каждым элементом коллекции данных в исходном поле и соответствующим элементом в целевом поле, которое также представляет собой коллекцию данных. Таким образом, каждый элемент коллекции в исходном поле будет связан с соответствующим элементом в целевом поле.

      Коллекции поддерживают только один вид сопоставления - For each. Одному элементу в исходном поле может быть сопоставлен только один элемент в целевом поле.
  2. Преобразование данных: (Трансформация – значок с молнией).

    atlasmap transform

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

  3. Использование констант и свойств:

    atlasmap constant
    atlasmap property

AtlasMap позволяет определять константы и свойства, которые можно использовать в маппингах.

Добавление маппинга AtlasMap в маршрут

  1. Сохранение конфигурации
    По завершении процесса маппинга и настройки преобразований данных, сохраните конфигурацию AtlasMap в формате .adm. При выборе опции сохранения в реестре схем Entaxy, файл будет сохранен по следующему адресу: schemas:название_файла.adm.

  2. Интеграция в маршрут

    atlasmap pre route

    Для интеграции вашей конфигурации AtlasMap с интеграционным маршрутом используйте следующий XML-тег:

<m:atlasmap resource="entaxy-resource://schemas/atlasmap-mapping.adm"></m:atlasmap>

Примеры использования

Представим, что у нас есть интеграция между 1С и CRM, и нам нужно использовать AtlasMap для преобразования данных между этими двумя системами. Мы будем использовать AtlasMap для преобразования данных между JSON-схемой, представляющей данные из 1С, и XML-схемой, совместимой с CRM.

Пример 1. Интеграция данных пользователя между 1C и CRM: Многие к одному

  1. Определение JSON-схемы

    Начнем с определения JSON-схемы, которая описывает структуру данных. Вот пример JSON-схемы:

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "pattern": "^[0-9]{5}$"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "phone": {
          "type": "string",
          "pattern": "^[0-9]{3}-[0-9]{3}-[0-9]{4}$"
        },
        "address": {
          "type": "string"
        }
      },
      "required": ["customer_id", "name", "email"]
    }

    Эта JSON-схема определяет объект с полями "customer_id", "name", "email", "phone" и "address", где "customer_id" ожидает 5 цифр, "email" должен соответствовать формату электронной почты, "phone" ожидает формат "123-456-7890", и "customer_id", "name" и "email" обязательны для заполнения.

  2. Определение XML-схемы

    Определяем XML-схему для XML-файла, который CRM ожидает для обработки данных.

    <?xml version="1.0" encoding="UTF-8"?>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="customer">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="customer_info" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>

    Эта XML-схема определяет корневой элемент <customer>, который содержит единственный элемент <customer_info> с типом xs:string. Теперь мы можем использовать AtlasMap для сопоставления данных из JSON в одно поле XML <customer_info> и для применения трансформации, чтобы объединить эти данные в одну строку.

  3. Создание Маппинга в AtlasMap

    atlasmap example1

    Теперь, когда у нас есть определенные JSON- и XML-схемы, мы можем использовать AtlasMap для создания маппинга данных между ними.

    • Запустите AtlasMap UI.

    • Настройте источник и цель:

      • Укажите источник данных, используя JSON-схему, представляющую данные из 1С.

      • Укажите целевые данные, используя XML-схему, совместимую с CRM.

    • Определите маппинги:

    • Создайте маппинги между полями источника и цели:

      • JSON customer_id, name, email, phone, и address → XML <customer_info>

        Для объединения значений из нескольких полей JSON в одну строку XML с использованием AtlasMap, вы можете воспользоваться возможностью выбора разделителя и предварительного просмотра результата.
        Вот как это делается:

    • Выбор разделителя:

      В AtlasMap, после того как вы создали маппинг JSON → XML для объединения значений, выберите элемент XML, в который вы хотите вставить объединенное значение (например, <customer_info>).

      В настройках этого маппинга, вы можете найти опцию для выбора разделителя (delimiter). Это поле, где вы указываете, какой разделитель должен быть использован для объединения значений. Например, вы можете выбрать запятую, пробел, точку с запятой или любой другой разделитель, который соответствует вашим потребностям.

    • Предварительный просмотр результата:

      В AtlasMap есть возможность просматривать результат маппинга перед его сохранением (preview).

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

    • Проверьте и сохраните ваш маппинг в реестр схем Entaxy:
      Entaxy Transformation → Save the current mappings and support files into Entaxy registry (.adm).

      atlasmap saveentaxyregistry

      Файл конфигурации будет размещен по адресу - schemas:название_файла.adm

    atlasmap schemas
  4. Определение исходных данных JSON-файл

    order.json

    {
      "customer_id": "66654",
      "name": "Oleg Pavlov",
      "email": "oleg@example.com",
      "phone": "911-456-5490",
      "address": "st. Krasnaya. 43"
    }

    Запустите процесс маппинга, интегрировав .adm в маршрут, и AtlasMap преобразует данные из JSON-формата в XML, соблюдая структуру, определенную в XML-схеме.

Пример 2: Интеграция заказов между 1C и CRM: Один к одному

  1. Определение JSON-схемы

    Начнем с определения JSON-схемы, которая описывает структуру данных. Вот пример JSON-схемы:

    {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string"
        },
        "customer_id": {
          "type": "string"
        },
        "total_amount": {
          "type": "number"
        },
        "order_date": {
          "type": "string",
          "format": "date"
        }
      },
      "required": ["order_id", "customer_id", "total_amount", "order_date"]
    }

    Эта JSON-схема определяет структуру данных, которая описывает JSON-файл. Она включает в себя следующие элементы:

    "order_id" - строка (идентификатор заказа).
    "customer_id" - строка (идентификатор клиента).
    "total_amount" - число (общая сумма заказа).
    "order_date" - строка с форматом даты (дата заказа).

    Кроме того, указаны обязательные поля: "order_id", "customer_id", "total_amount" и "order_date". Это гарантирует, что JSON-файл, используемый в интеграции, будет соответствовать этой структуре данных.

  2. Определение XML-instance

    Определяем XML-instance для XML-файла, который CRM ожидает для обработки данных.

    <?xml version="1.0" encoding="UTF-8"?>
    <order>
      <order_id>order_id</order_id>
      <customer_id>customer_id</customer_id>
      <total_amount>total_amount</total_amount>
      <order_date>order_date</order_date>
    </order>

    В этом XML-instance:
    <order> - корневой элемент, представляющий заказ. <order_id> - элемент, представляющий идентификатор заказа <customer_id> - элемент, представляющий идентификатор клиента <total_amount> - элемент, представляющий общую сумму заказа <order_date> - элемент, представляющий дату заказа.

  3. Создание Маппинга в AtlasMap

    atlasmap example2

    Теперь, когда у нас есть определенные JSON-схема и XML-instance, мы можем использовать AtlasMap для создания маппинга данных между ними.

    • Запустите AtlasMap UI.

    • Настройте источник и цель:

      • Укажите источник данных, используя JSON-схему, представляющую данные из 1С.

      • Укажите целевые данные, используя XML-файл, совместимый с CRM.

    • Определите маппинги:

    • Создайте маппинги между полями источника и цели:

      • JSON order_id → XML <order_id>

      • JSON customer_id → XML <customer_id>

      • JSON total_amount → XML <amount>

      • JSON order_date → XML <date>

    • Проверьте и сохраните ваш маппинг в реестр схем Entaxy:
      Entaxy Transformation → Save the current mappings and support files into Entaxy registry (.adm).

      atlasmap exportregistry

      Файл конфигурации будет размещен по адресу - schemas:название_файла.adm

  4. Определение исходных данных JSON-файл

    order.json

    {
      "customer_id": "123456789",
      "order_date": "2023-11-20",
      "order_id": "ORD2023-00567",
      "total_amount": "500"
    }

    Запустите процесс маппинга, интегрировав .adm в маршрут, и AtlasMap преобразует данные из JSON-формата в XML, соблюдая структуру, определенную в XML-instance.

Условные выражения в AtlasMap

AtlasMap предоставляет поддержку условных выражений, что позволяет логически обрабатывать данные при их отображении. Для этого используются функции IF() и ISEMPTY().

  1. IF(boolean-expression, then, else):
    Функция IF() возвращает одно значение, если логическое выражение (boolean-expression) истинно, и другое значение, если оно ложно. Обязательные аргументы: boolean-expression, then (возвращаемое значение, если true), else (возвращаемое значение, если false).

    Пример использования:

    atlasmap fxexample1

    IF(ISEMPTY(lastName), firstName, lastName + '_' + firstName)
    Если "lastName" пусто, то "customerName" будет равно только "firstName".
    Если "lastName" не пусто, то "customerName" будет равно "lastName_firstName".

    Разделитель, используемый для объединения "lastName" и "firstName" можно изменить. Вместо подчеркивания ('_'), вы можете использовать любой другой символ или даже пустую строку в зависимости от ваших требований. При формировании выражения, учитывайте возможность трансформации значений. Например: IF(ISEMPTY(lastName), firstName, lastName + ',' + UPPERCASE(firstName)) .

    UPPERCASE(value): Функция UPPERCASE() преобразует значение в верхний регистр.

    ISEMPTY(source-field-name): Функция ISEMPTY() возвращает true, если указанное поле (source-field-name) пусто, и false в противном случае.

    Пример использования:

    ISEMPTY(firstName)
    Возвращает true, если "firstName" пусто.
    Возвращает false, если "firstName" содержит значение.

    atlasmap fxexample2

Поддерживаемые операторы

Эти операторы предоставляют инструменты для выполнения различных математических и логических операций при отображении и обработке данных в AtlasMap. Вы можете комбинировать их с условиями и функциями для более сложных манипуляций с данными.

Оператор Описание

+

Сложение числовых значений или конкатенация строковых значений.

-

Вычитание числового значения из другого числового значения.

*

Умножение числовых значений.

\

Деление числовых значений.

&& И (And)

Возвращает true, если и левый, и правый операнды являются true. Каждый операнд должен возвращать логическое значение.

|| Или (Or)

Возвращает true, если левый операнд true, или если правый операнд true, или если оба операнда true. Каждый операнд должен возвращать логическое значение.

! Не (Not)

Логическое отрицание. Возвращает true, если операнд false, и наоборот.

> Больше чем (Greater than)

Возвращает true, если левый числовой операнд больше, чем правый числовой операнд.

< Меньше чем (Less than)

Возвращает true, если левый числовой операнд меньше, чем правый числовой операнд.

== Равно (Equal)

Возвращает true, если левый операнд и правый операнд идентичны.