Работа с регистрами сведений в КД 3.130.08.2024 14:31

В статье рассматривается один из механизмов при работе с «Конвертацией данных 3.1», а именно — обмен данными регистра сведений в формате Enterprise Data.

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

Особенности формата при работе с регистрами

Для начала заглянем в формат данных XDTO-пакета, поставляемого с БСП.

Первое, что стоит заметить, вы не увидите объектов со словом «Регистр» в названии. Все справочные данные в терминах Enterprise Data считаются справочниками, и их наименования начинаются со слова «Справочник».

Для примера посмотрим объект Справочник.ДокументыФизическихЛиц в 16 версии типового формата.

Настройка формата регистра в XDTO-пакете

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

Структура регистра сведений в XDTO-пакете определяется тремя объектами:

собственно объект регистра сведений, включающий поля фильтров-измерений регистра (включая Период для периодических регистров);
объект набора записей, состоящий из одного поля «Строка»;
объект записи с описанием всех полей регистра (включая Период для периодических регистров).

1. Тип объекта регистра Справочник.ДокументыФизическихЛиц

Правило 1.1

Имя: строго в формате «Справочник.ИмяРегистра».

Базовый тип: указывается Object из пространства имен http://www.1c.ru/SSL/Exchange/Message

Значения остальных свойств отвечают за более тонкую настройку объекта XDTO, и при их установке следует руководствоваться примерами типового формата. Чаще всего меняться значения будут у двух свойств: «Открытый» и «Последовательный». Вот за что они отвечают:

Открытый — признак того, является ли тип объекта XDTO открытым. Данное свойство показывает, может ли экземпляр объекта XDTO содержать дополнительные свойства, не определенные в его типе.

Последовательный — это свойство показывает, содержит ли экземпляр соответствующего объекта XDTO последовательность XDTO. Данный признак имеет значение «Истина», когда порядок следования вложенных элементов XML не может однозначно определяться порядком следования свойств в типе. Последовательность XDTO позволяет задать в явном виде порядок следования элементов, как они будут представлены в документе XML. Для объектов типов, у которых это свойство установлено в «Ложь», порядок следования вложенных элементов соответствует порядку следования свойств.

Правило 1.2

Для созданного объекта регистра добавлены свойства, повторяющие состав измерений регистра, а также свойство Период, если регистр периодический. Имена свойств могут повторять имена измерений, но хорошим тоном будет снабдить их суффиксом Фильтр или Отбор, поскольку именно эту роль они выполняют при обработке набора записей.

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

При настройке фильтров измерений (да и любых вложенных полей свойств объекта XDTO) следует обращать внимание на настройку значений «Минимальное количество» и «Максимальное количество». Они отвечают за контроль обязательности заполнения значения, а также способа заполнения, которое будет рассмотрено при описании следующего объекта формата.

Говоря по-простому, эти два свойства отвечают за то, сколько значений может принимать данное поле. Если минимальное значение установить в 0, то поле будет считаться необязательным для заполнения. Если же оставить значение 1, то при валидации данных XDTO платформа затребует обязательного наличия значения. То есть, хотя бы одно значение это поле принимать должно.

Правило 1.3

Добавить свойство «Строки» (или «Записи») с типом объекта набора записей (см. описание следующего объекта ниже), установить для него минимальное значение 0.

2. Тип объекта набора записей ДокументыФизическихЛицЗаписи

Правило 2.1

Для описания наличия у объекта многострочной части создается новый тип объекта, для которого ничего не указывается, кроме имени. Хотя имя может быть совершенно произвольным, однако рекомендуется брать его из предыдущего типа, для дальнейшего понимания, к чему относится тот или иной тип, и добавить в конце слово «Строки» или «Записи».

Правило 2.2

Добавить свойство »Строка» (строго именно так) с типом объекта строки записи (см. описание следующего объекта ниже), и установить для него минимальное значение 1, а максимальное: −1 (минус один).

Установленные минимальные и максимальные значения для свойства «Записи» основного объекта и свойства «Строка» объекта набора записей крайне важны. Именно при такой последовательности система валидации понимает, что табличная часть в принципе может отсутствовать (минимальное для «Записи» = 0), но если она есть, то хотя бы одна строка в ней должна быть (минимальное для «Строка» = 1). Максимальное значение –1 для свойства «Строка» означает, что оно может принимать коллекцию значений указанного типа. При работе с объектом XDTO в это поле будет передан объект с типом «СписокXDTO».

3. Тип объекта строки записи ДокументыФизическихЛицЗапись

Правило 3.1

Для описания формата отдельной строки регистра, создается еще один тип объекта. Имя также рекомендуется взять из имени основного объекта, добавив в конце слово «Строка» или «Запись».

Правило 3.2

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

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

И еще один немаловажный момент: при указании типов свойств ссылочного типа, следует выбирать из пакета специализированные типы, начинающиеся со слов »КлючевыеСвойства». Именно они указывают на тип «Ссылка» в терминах формата XDTO.

Важные моменты при работе с англоязычными конфигурациями

Если вам посчастливится работать с международными конфигурациями на базе англоязычного кода, то при работе с пакетом XDTO следует помнить следующее:

при описании типа справочного объекта его имя должно строго начинаться со слова «Справочник», за которым следует точка. Именно так, на кириллице;
при описании типа многострочной части »…Записи», его единственное свойство должно строго называться «Строка». Именно так, на кириллице.

Разработка правил обмена в КД 3.1

Теперь рассмотрим процесс разработки правил обмена в «Конвертации данных 3.1» для выгрузки и загрузки записей регистра сведений. Предполагается, что в конфигурации КД уже создана и настроена Конвертация для «Управления торговлей 11.5», загружены сведения о формате Enterpeise Data версии 1.16 и настроены правила обмена для видов документов и физических лиц. Для упрощения демонстрации и выгрузка, и загрузка данных будет разрабатываться для одной конфигурации УТ 11.

Разработка правила выгрузки на стороне Источника

Создание ПКО

Создаем новое правило конвертации объектов и заполняем следующие поля:

Объект конфигурации — РегистрСведений.ДокументыФизическихЛиц;
Объект формата — Справочник.ДокументыФизическихЛиц;
Область применения — Для отправки;
Идентификатор правила — заполняем либо автоматически по кнопке «Заполнить», либо набираем свое наименование.

Сохраняем по кнопке «Записать» и переходим на вкладку «Правила конвертации свойств» для настройки ПКС.

И тут — первая особенность. Все свойства объекта-источника для регистра сведений заполняются без указания свойств источника, и для всех свойств устанавливается флажок «Программная обработка». То есть, всю выгрузку набора записей мы полностью пропишем в коде обработчика.

Самый быстрый и простой способ заполнить все ПКС — воспользоваться кнопкой «Настройка ПКС» для их автоматического создания. В открывшемся списке устанавливаем флажки возле всех свойств формата (кроме общих свойств объекта формата, их мы в рамках примера не рассматриваем), значения в колонке «Свойство конфигурации» оставляем пустыми.

Нажимаем кнопку «Создать правила конвертации свойств» и получаем нужный результат. При этом для ссылочных значений ПКС автоматически заполнены правила конвертации отправки значений.

После этого переходим на вкладку «Обработчики событий» и для обработчика ПриОтправке вставляем следующий код:


// 1
ДанныеXDTO.Вставить("ПериодОтбор",         ДанныеИБ.Отбор.Период.Значение);
ДанныеXDTO.Вставить("ФизическоеЛицоОтбор", ДанныеИБ.Отбор.Физлицо.Значение);
ДанныеXDTO.Вставить("ВидДокументаОтбор",   ДанныеИБ.Отбор.ВидДокумента.Значение);

// 2
ТаблицаЗаписи = Новый ТаблицаЗначений;
ТаблицаЗаписи.Columns.Add("ВидДокумента");
ТаблицаЗаписи.Columns.Add("ДатаВыдачи");
ТаблицаЗаписи.Columns.Add("КемВыдан");
ТаблицаЗаписи.Columns.Add("КодПодразделения");
ТаблицаЗаписи.Columns.Add("Номер");
ТаблицаЗаписи.Columns.Add("Период");
ТаблицаЗаписи.Columns.Add("Представление");
ТаблицаЗаписи.Columns.Add("Серия");
ТаблицаЗаписи.Columns.Add("СрокДействия");
ТаблицаЗаписи.Columns.Add("ФизическоеЛицо");
ТаблицаЗаписи.Columns.Add("ЯвляетсяУдостоверяющимЛичность");

// 3
Для Каждого СтрокаЗаписи Из ДанныеИБ Цикл
	НоваяСтрока = ТаблицаЗаписи.Добавить();
	ЗаполнитьЗначенияСвойств(НоваяСтрока, СтрокаЗаписи);
	НоваяСтрока.ФизическоеЛицо = СтрокаЗаписи.Физлицо;
	НоваяСтрока.ЯвляетсяУдостоверяющимЛичность = СтрокаЗаписи.ЯвляетсяДокументомУдостоверяющимЛичность;
КонецЦикла;

// 4
ДанныеXDTO.Вставить("Записи", ТаблицаЗаписи);

Что делает этот код:

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

Создание ПОД

Теперь осталось создать правило обработки данных для возможности выгрузки зарегистрированных изменений на узле плана обмена для нашего регистра. Сделать это можно либо вручную на вкладке «Правила обработки данных» на форме настройки конвертации, либо на основании созданного ПКО по кнопке «Создать» на его форме.

На этом разработка правил выгрузки завершена, теперь можно выгрузить код модуля менеджера и обновить его в конфигураторе базы Источника.

Разработка правила загрузки на стороне Приемника

На стороне базы Приемника разработка правил загрузки выглядит еще интереснее. Здесь обработка кодом выполняется настолько полно, что даже не нужно ПКО, весь код выполняется в обработчике ПОД и полностью обрабатывает загрузку набора записей.

Создание ПОД

В форме настройки конвертации переходим на вкладку «Правила обработки данных» и создаем новое ПОД. Заполняем поля:

Область применения — Для получения;
Объект выборки — Справочник.ДокументыФизическихЛиц;
Идентификатор правила — нажимаем кнопку «Заполнить», при необходимости корректируем;
Правило конвертации объекта — оставляем пустым.

Переходим на вкладку «Обработчики событий» и для обработчика ПриОбработке вставляем следующий код:

// 1
СвойстваОтбор = ДанныеXDTO;
Если ДанныеXDTO.Свойство("КлючевыеСвойства") Тогда
	СвойстваОтбор = ДанныеXDTO.КлючевыеСвойства;
КонецЕсли;

// 2
ФизическоеЛицоОтбор = Неопределено;
ВидДокументаОтбор = Неопределено;
ПериодОтбор = Неопределено;

СвойстваОтбор.Свойство("ФизическоеЛицоОтбор", ФизическоеЛицоОтбор);
СвойстваОтбор.Свойство("ВидДокументаОтбор", ВидДокументаОтбор);
СвойстваОтбор.Свойство("ПериодОтбор", ПериодОтбор);

// 3
НаборЗаписей = РегистрыСведений.ДокументыФизическихЛиц.СоздатьНаборЗаписей();
НаборЗаписей.ДополнительныеСвойства.Вставить("ОтключитьМеханизмРегистрацииОбъектов", Истина);

// 4
ПравилоКонвертацииФизическиеЛица = ОбменДаннымиXDTOСервер.ПКОПоИмени(
КомпонентыОбмена, "Спр_ФизическиеЛица_Получение");
ПравилоКонвертацииВидыДокументов = ОбменДаннымиXDTOСервер.ПКОПоИмени(
КомпонентыОбмена, "Спр_ВидыДокументовФизическихЛиц_Получение");

Если ЗначениеЗаполнено(ФизическоеЛицоОтбор) Тогда
	ЗначениеОтбора = ОбменДаннымиXDTOСервер.СтруктураОбъектаXDTOВДанныеИБ(
		КомпонентыОбмена, ФизическоеЛицоОтбор,
ПравилоКонвертацииФизическиеЛица, "ПолучитьСсылку");
	НаборЗаписей.Отбор.Физлицо.Установить(ЗначениеОтбора.Ссылка);
КонецЕсли;
Если ЗначениеЗаполнено(ВидДокументаОтбор) Тогда
	ЗначениеОтбора = ОбменДаннымиXDTOСервер.СтруктураОбъектаXDTOВДанныеИБ(
		КомпонентыОбмена, ВидДокументаОтбор,
ПравилоКонвертацииВидыДокументов, "ПолучитьСсылку");
	НаборЗаписей.Отбор.ВидДокумента.Установить(ЗначениеОтбора.Ссылка);
КонецЕсли;
Если ЗначениеЗаполнено(ПериодОтбор) Тогда
	НаборЗаписей.Отбор.Период.Установить(ПериодОтбор);
КонецЕсли;

Если Не ЗначениеЗаполнено(НаборЗаписей.Отбор.Физлицо.Значение) Тогда
	Возврат;
КонецЕсли;

// 5
Если ДанныеXDTO.Свойство("Записи")
	И ЗначениеЗаполнено(ДанныеXDTO.Записи) Тогда
	
	Для Каждого СтрокаЗаписи Из ДанныеXDTO.Записи Цикл
		ЗаписьДокументыФЛ = НаборЗаписей.Добавить();
		
		Если Не ЗначениеЗаполнено(НаборЗаписей.Отбор.Физлицо.Значение) Тогда
			ЗначениеЭлемента = ОбменДаннымиXDTOСервер.СтруктураОбъектаXDTOВДанныеИБ(
				КомпонентыОбмена, СтрокаЗаписи.ФизическоеЛицо,
ПравилоКонвертацииФизическиеЛица, "ПолучитьСсылку");
			ЗаписьДокументыФЛ.Физлицо = ЗначениеЭлемента.Ссылка;
		Иначе
			ЗаписьДокументыФЛ.Физлицо = НаборЗаписей.Отбор.Физлицо.Значение;
		КонецЕсли;
		
		Если Не ЗначениеЗаполнено(НаборЗаписей.Отбор.ВидДокумента.Значение) Тогда
			ЗначениеЭлемента = ОбменДаннымиXDTOСервер.СтруктураОбъектаXDTOВДанныеИБ(
				КомпонентыОбмена, СтрокаЗаписи.ВидДокумента,
ПравилоКонвертацииВидыДокументов, "ПолучитьСсылку");
			ЗаписьДокументыФЛ.ВидДокумента = ЗначениеЭлемента.Ссылка;
		Иначе
			ЗаписьДокументыФЛ.ВидДокумента = НаборЗаписей.Отбор.ВидДокумента.Значение;
		КонецЕсли;
		
		Если Не ЗначениеЗаполнено(НаборЗаписей.Отбор.Период.Значение) Тогда
			ЗаписьДокументыФЛ.Период = СтрокаЗаписи.Период;
		Иначе
			ЗаписьДокументыФЛ.Период = НаборЗаписей.Отбор.Период.Значение;
		КонецЕсли;
		
		ЗаписьДокументыФЛ.ЯвляетсяДокументомУдостоверяющимЛичность =
СтрокаЗаписи.ЯвляетсяУдостоверяющимЛичность;
		ЗаполнитьЗначенияСвойств(ЗаписьДокументыФЛ, СтрокаЗаписи,
"Серия,Номер,ДатаВыдачи,СрокДействия,КемВыдан,КодПодразделения,Представление");
		
	КонецЦикла;
	
КонецЕсли;

// 6
НаборЗаписей.ОбменДанными.Загрузка = Истина;
НаборЗаписей.Записать(Истина);

Что здесь происходит:

Получение свойства отбора из данных XDTO и…
… считывание значения отборов, при их наличии;
Создание нового набора записей, который будет наполняться данными;
Конвертация прочитанных на шаге 2 значений фильтров и установка отборов у набора записей;
Чтение и заполнение записей регистра из данных, полученных от Источника;
Запись результата.

Особенность при работе с расширением формата

Если вы разрабатываете собственный формат обмена в виде расширения типового формата XDTO-пакета, есть риск встречи с неприятным моментом.

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

Для исправления ситуации необходимо внести изменения в типовой модуль ОбменДаннымиXDTOСервер (на момент написания статьи в версии БСП 3.1.10.211 ошибка присутствует):

В процедуре РасширитьСвойстваТаблицыОбъекта () строку:

Если СтрНайти(ПолеИзРасширения.Тип.Имя, КлассКлючевыеСвойства()) > 0 Тогда

Заменить на строку:

Если ПолеИзРасширения.Тип.Имя = КлассКлючевыеСвойства() Тогда

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

Заключение

Эта статья подробно описывает процесс настройки обмена данными регистра сведений в «Конвертации данных 3.1» с использованием формата Enterprise Data и XDTO-пакета. Рассмотрены особенности формата данных, правила создания и настройки объектов XDTO, а также разработка правил обмена на стороне Источника и Приемника. Приведены примеры кода для различных этапов обработки данных, что делает статью практическим руководством для разработчиков, работающих с данными регистров сведений. Соблюдение изложенных правил и рекомендаций поможет избежать распространенных ошибок и успешно настроить обмен данными.