Шаблон элемента обмена

<< Click to Display Table of Contents >>

Navigation:  Механизм обмена данными > Настройка обмена данными в Венд-Аналитике > Элементы обмена >

Шаблон элемента обмена

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

 

 

Фактически шаблон элемента копирует XML-представление этого элемента с некоторыми исключениями:

значения XML-узлов, ограниченные символами #, содержат специальные SQL-выражения вместо значений реквизитов элемента;

значения некоторых узлов и атрибутов могут быть ограничены символами «!» (маркированы);

в шаблоне могут присутствовать узлы специального назначения _HIDDEN_,  _TABLE_, _PARENT_FIELD_, _FILTER_, _IDENTIFICATION_, отсутствующие в XML-представлении элемента.  

SQL-выражения

SQL-выражения содержат алгоритм формирования значения узла при выгрузке данных и способ интерпретации фактического значения соответствующего узла при загрузке данных. Значение XML-узла является SQL-выражением, если оно ограничено символом «#».

 

Выражение может содержать два SQL-предложения, разделенные символом #, либо одно SQL-предложение. В первом случае выражение слева от # используется при выгрузке данных; выражение справа от # используется при загрузке данных. Во втором случае одно и то же выражение используется как при выгрузке, так и при загрузке данных.

SQL-предложение для выгрузки данных

В качестве SQL-предложения для выгрузки данных могут использоваться:

имя ключевого поля таблицы элемента с префиксом «@» (например, @id). В узел, содержащий такое предложение, помещается идентификатор элемента, сформированный в соответствии с шаблоном идентификаторов;

имя поля, ссылающегося на ключевое поле любой таблицы, с префиксом «@» (например, @currency_id). При этом в узел помещается идентификатор того элемента, на который ссылается поле таблицы. Идентификатор формируется в соответствии с шаблоном идентификаторов;

произвольное SQL-предложение (возвращающее единственное значение), включаемое в запрос вида

 Select <SQL-предложение> From <ИМЯ ТАБЛИЦЫ> Main Where <КЛЮЧЕВОЕ ПОЛЕ> = <ЗНАЧЕНИЕ>.

 

Пример узла, содержащего SQL-предложение для выгрузки данных:

<DeletionMark># case when isDeleted = 0 then 'false' else 'true' end ##</DeletionMark>

 

SQL-предложение для загрузки данных

В качестве SQL-предложений для загрузки данных могут использоваться:

имя ключевого поля таблицы элемента с префиксом «@» (например, @id);

имя поля, ссылающегося на ключевое поле любой таблицы, с префиксом «@» (например, @currency_id);

имя поля таблицы (например, name);

присваивание вида <имя поля> = <SQL-предложение>.

 

Для доступа к фактическому значению узла в SQL-предложении может использоваться символ «?». В табличной части шаблона в SQL-предложении может использоваться строка «^parent_id» для доступа к внутреннему идентификатору записи родительской таблицы.

 

Пример узла, содержащего SQL-предложение для загрузки данных:

<DeletionMark>## isDeleted = case when ? = 'false' then 0 else 1 end #</DeletionMark>

 

Маркеры

Если имена корневых XML-узлов элементов разного типа совпадают, необходимо ввести дополнительные признаки, позволяющие отфильтровывать узлы, не соответствующие данному элементу обмена. Данную функцию выполняют маркеры.

 

Маркерами называются узлы и атрибуты шаблона элемента обмена, значения которых ограничены символами «!». Маркеры никак не влияют на выгрузку данных (при выгрузке ограничивающие символы «!» отбрасываются) и используются только при загрузке данных для идентификации узлов, подлежащих загрузке.

 

 

На приведенном рисунке маркер, используемый в шаблоне элемента обмена «Контрагенты: Юридический адрес», обведен красным цветом.

 

Узлы _FILTER_

В некоторых случаях необходимо загружать лишь элементы, удовлетворяющие определенному критерию. Например, в Венд-Аналитику должны загружаться документы с определённой даты. Для этого используется узел _FILTER_, добавляемый в шаблон шапки документа или справочника:

 

<DocumentObject.ПлатежноеПоручениеИсходящее>

 <Ref>#@id#</Ref>

 <_FILTER_>"[Date]".compareTo("2013-08-01T00:00:00") >= 0 </_FILTER_>

 <Date>#docDt#</Date>

 ...

</DocumentObject.ПлатежноеПоручениеИсходящее>

 

Текст узла _FILTER_ представляет собой скрипт на языке Java, возвращающий выражение логического типа ("истина" или "ложь"). Для ссылки на значения узлов загружаемого элемента используется конструкция вида [имя_узла]. Загружаются только те элементы, для которых скрипт возвращает значение "истина". В приведённом выше примере фильтр блокирует загрузку в Венд-Аналитику исходящих платёжных поручений с датой, предшествующей 01.08.2013.

Узлы _HIDDEN_

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

XML-узлы табличной части

При включении в шаблон элемента обмена табличной части документа или справочника следует указать значения трех специальных узлов:

_TABLE_: имя таблицы, содержащей строки табличной части;

_PARENT_FIELD_: имя поля в табличной части, ссылающееся на ключевое поле шапки документа или элемента справочника;

_FILTER_: SQL-выражение для фильтрации строк таблицы, содержащей строки табличной части. Если фильтровать строки табличной части при выгрузке данных не требуется, данный узел может отсутствовать в шаблоне.

 

Ниже указан примерный вид шаблона табличной части элемента обмена «Поступление товаров».

<Товары>

 <Row>

         <_TABLE_>tbDocEntranceDetail</_TABLE_>

         <_PARENT_FIELD_>docEntrance_id</_PARENT_FIELD_>

         <_FILTER_>price > 0</_FILTER_>

         <Номенклатура>#@NOMENCLATURE_ID#</Номенклатура>

         <Количество>#QUANTITY#</Количество>

         <Сумма>#AMOUNT#</Сумма>

 </Row>

</Товары>

Отождествление элементов

Если первый обмен данными происходит в момент, когда обе системы уже содержат элементы, подлежащие синхронизации, возникает проблема отождествления элементов. Предположим, что Венд-Аналитика содержит клиентов Иванов и Петров, а внешняя система содержит клиентов Петров и Сидоров. Обе системы должны «знать» о том, что загружаемый клиент Петров не является новым и уже существует в данной системе.

 

Для решения данной проблемы определяются поля элемента, совпадение значений которых означает тождественность двух элементов. Далее наименования узлов элемента обмена, содержащих выбранные поля, помещаются в узел _IDENTIFICATION_ (наименования узлов разделяются запятыми).  

 

<CatalogObject.Контрагенты>

     <_IDENTIFICATION_>Description,Parent</_IDENTIFICATION_>

 <Ref>#@id#</Ref>

 <Parent>#@parent_id#</Parent>

 <Description>#name#</Description>

</CatalogObject.Контрагенты>

 

В приведенном примере для отождествления клиентов выбраны поля name и parent_id. Клиенты будут признаны тождественными только в том случае, если они имеют одинаковое наименование и расположены в одной и той же папке.

 

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

 

<CatalogObject.Контрагенты>

     <_IDENTIFICATION_>Description,Parent</_IDENTIFICATION_>

     <_IDENTIFICATION_>ИНН</_IDENTIFICATION_>

 <Ref>#@id#</Ref>

 <Parent>#@parent_id#</Parent>

 <Description>#name#</Description>

 <ИНН>#inn#</ИНН>

</CatalogObject.Контрагенты>

 

В представленном выше примере клиенты будут признаны тождественными в любом из следующих случаев:

клиенты имеют одинаковое наименование и расположены в одной и той же папке;

ИНН клиентов совпадает.

 

Для того, чтобы сработал механизм отождествления, следует сначала выгрузить данные из внешней системы в файл, загрузить файл в Венд-Аналитику, и лишь затем выгружать данные из Венд-Аналитики.