Working with information registers in KD 3.1

The article examines one of the mechanisms when working with Data Conversion 3.1, namely, the exchange of register data in Enterprise Data format.

When discussing data exchange using KD 3, information registers are often ignored, with the focus being on reference books and documents. This article aims to fill this gap. Along the way, we will touch on some of the nuances of working with the XDTO package.

Features of the format when working with registers

First, let's look at the data format of the XDTO package supplied with the BSP.

The first thing to notice is that you won't see any objects with the word “Register” in their name. All reference data in Enterprise Data terms is considered reference booksand their names begin with the word “Directory”.

Let's look at the object as an example Directory.Documents.Individuals in version 16 of the standard format.

Setting the register format in the XDTO package

Let's take a closer look at the structure of the data format for the information register. You can use these same principles when developing your own types.

The structure of the information register in the XDTO package is defined by three objects:

  1. the actual object of the information register, including the fields of the register's filter-dimensions (including the Period for periodic registers);

  2. a recordset object consisting of a single String field;

  3. a record object describing all register fields (including Period for periodic registers).

1. Register object type Directory.DocumentsPersons

Rule 1.1

Name: strictly in the format “Directory.RegistryName”.

Basic type: is indicated Object from namespace http://www.1c.ru/SSL/Exchange/Message

The values ​​of the remaining properties are responsible for fine-tuning the XDTO object, and when setting them, you should follow the examples of the typical format. The values ​​of two properties will change most often: “Open” and “Sequential”. Here's what they are responsible for:

Open — an indicator of whether the XDTO object type is open. This property indicates whether an instance of an XDTO object can contain additional properties not defined in its type.

Consistent — This property indicates whether the instance of the corresponding XDTO object contains an XDTO sequence. This flag is True when the order of nested XML elements cannot be uniquely determined by the order of properties in the type. The XDTO sequence allows you to explicitly specify the order of elements as they will be presented in the XML document. For objects of types for which this property is set to False, the order of nested elements corresponds to the order of properties.

Rule 1.2

For the created register object, properties have been added that repeat the composition of the register dimensions, as well as the Period property if the register is periodic. The names of the properties can repeat the names of the dimensions, but it would be good practice to provide them with a suffix Filter or Selectionsince that is the role they play when processing a set of records.

The order in which these properties are listed, unlike the configuration object, is not of great importance here.

When setting up dimension filters (and any nested fields of XDTO object properties), you should pay attention to setting the “Minimum Quantity” and “Maximum Quantity” values. They are responsible for controlling the mandatory nature of filling in the value, as well as the filling method, which will be discussed when describing the next format object.

In simple terms, these two properties are responsible for the fact that how many values can accept this field. If the minimum value is set to 0, the field will be considered optional. If you leave the value 1, then when validating XDTO data, the platform will require the mandatory presence of a value. That is, this field must accept at least one value.

Rule 1.3

Add a property “Rows” (or “Records”) with a recordset object type (see the description of the next object below), set its minimum value to 0.

2. Recordset object type DocumentsIndividualsRecords

Rule 2.1

To describe whether an object has a multi-line part, a new object type is created for which nothing is specified except the name. Although the name can be completely arbitrary, it is recommended to take it from the previous type, for further understanding of what this or that type refers to, and add the word “Lines” or “Records” at the end.

Rule 2.2

Add property «Line” (strictly so) with the record string object type (see the description of the next object below), and set its minimum value to 1, and its maximum to -1 (minus one).

The minimum and maximum values ​​set for the Record property of the main object and the Row property of the recordset object are extremely important. This is the sequence that allows the validation system to understand that the table section may be absent in principle (minimum for Record = 0), but if it is present, it must contain at least one row (minimum for Row = 1). The maximum value of –1 for the Row property means that it can accept a collection of values ​​of the specified type. When working with an XDTO object, an object of the XDTOList type will be passed to this field.

3. Object type of the record line DocumentsIndividualsRecord

Rule 3.1

To describe the format of a single register line, another object type is created. It is also recommended to take the name from the main object name, adding the word “Line” or “Record” at the end.

Rule 3.2

The record object is filled with properties according to the register structure, including all measurements and period (for periodic information registers).

When specifying minimum and maximum values ​​for dimension fields, you should repeat the same values ​​that were specified for the filters on the root object.

And one more important point: when specifying the types of reference type properties, you should select specialized types from the package that begin with the words “Key Features” They are the ones that indicate the “Link” type in terms of the XDTO format.

Important points when working with English-language configurations

If you are lucky enough to work with international configurations based on English code, then when working with the XDTO package, you should keep the following in mind:

  • when describing a reference object type, its name must strictly begin with the word “Reference”, followed by a period. That's right, in Cyrillic;

  • when describing the multi-line part type “…Records”, its only property must be strictly named “Line”. That's right, in Cyrillic.

Development of exchange rules in KD 3.1

Now let's look at the process of developing exchange rules in “Data Conversion 3.1” for uploading and downloading records of the information register. It is assumed that in the configuration of the CD, Conversion for “Trade Management 11.5” has already been created and configured, information about the Enterprise Data version 1.16 format has been loaded, and exchange rules for document types and individuals have been configured. To simplify the demonstration, both uploading and downloading data will be developed for one configuration of UT 11.

Developing a download rule on the Source side

Creation of PKO

Create a new object conversion rule and fill in the following fields:

  • Configuration object — Register of Information. Documents of Individuals;

  • Format object — Directory.DocumentsofIndividuals;

  • Scope of application — For sending;

  • Rule ID – fill in either automatically using the “Fill” button, or type in your own name.

We save by clicking the “Save” button and go to the “Property Conversion Rules” tab to configure the PKS.

And here is the first peculiarity. All properties of the source object for the information register are filled without specifying the source properties, and the “Program processing” flag is set for all properties. That is, we will completely write the entire unloading of the record set in the handler code.

The fastest and easiest way to fill in all the PKS is to use the “PKS Setup” button to create them automatically. In the list that opens, check the boxes next to all the format properties (except for the general properties of the format object, which we will not consider in this example), and leave the values ​​in the “Configuration Property” column empty.

We press the button “Create property conversion rules” and get the desired result. At the same time, the conversion rules for sending values ​​are automatically filled in for the reference values ​​of the PKS.

After that, go to the “Event Handlers” tab and for the handler WhenSending insert the following code:


// 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.Вставить("Записи", ТаблицаЗаписи);

What this code does:

  1. transfer of selected measurement data from the transferred set of records to the unloading;

  2. creation of a table of values ​​for a multi-line part that repeats the structure of the data format;

  3. filling a table with data from a set of records;

  4. transferring the table of records to the dump.

Creation of POD

Now it remains to create a data processing rule to be able to unload registered changes on the exchange plan node for our register. This can be done either manually on the “Data Processing Rules” tab on the conversion setup form, or based on the created PKO by clicking the “Create” button on its form.

This completes the development of the unloading rules, now you can unload the manager module code and update it in the Source database configurator.

Developing a loading rule on the Receiver side

On the Receiver base side, the development of loading rules looks even more interesting. Here, the code processing is performed so completely that even the PKO is not needed, all the code is executed in the POD handler and completely handles the loading of the record set.

Creation of POD

In the conversion settings form, go to the “Data processing rules” tab and create a new POD. Fill in the fields:

  • Scope of application — To receive;

  • Sample object — Directory.DocumentsofIndividuals;

  • Rule ID — click the “Fill” button and make adjustments if necessary;

  • Object Conversion Rule — leave blank.

Go to the “Event Handlers” tab and insert the following code for the OnProcessing handler:

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

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

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

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

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

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

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

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

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

What's going on here:

  1. Getting the selection property from XDTO data and…

  2. …reading the value of selections, if any;

  3. Create a new recordset that will be populated with data;

  4. Converting the filter values ​​read in step 2 and setting the selections for the record set;

  5. Reading and filling register records from data received from the Source;

  6. Recording the result.

Peculiarity when working with format extension

If you develop your own exchange format as an extension of the standard XDTO package format, there is a risk of encountering an unpleasant moment.

If a custom information register object is added to the format extension and its properties include reference type values, then when unloading from the Source database according to such rules, an execution error will occur indicating a format error.

To correct the situation, it is necessary to make changes to the standard module. Data ExchangeXDTOServer (at the time of writing the article, the error is present in BSP version 3.1.10.211):

In the procedure ExpandObjectTableProperties() line:

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

Replace with line:

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

The reason for the error is that the reference values ​​have a format object type that starts with a keyword Key Featuresand is also called service group of properties when positioning by “link” in terms of format. When encountering this phrase as part of a type name, the system attempts to go into the folder to read nested properties that do not actually exist.

Conclusion

This article describes in detail the process of setting up the exchange of register data in “Data Conversion 3.1” using the Enterprise Data format and the XDTO package. It covers the features of the data format, the rules for creating and setting up XDTO objects, and the development of exchange rules on the Source and Receiver sides. Code examples are provided for various stages of data processing, making the article a practical guide for developers working with register data. Following the rules and recommendations outlined will help you avoid common mistakes and successfully set up data exchange.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *