2.9. Data Import

Note:

The Data Import feature is only available with the additional package dfx-import installed. Import can be used to create or update records. Using this feature, you can transfer data from Excel and XML files into:

• Document types
• User dictionaries
• System dictionaries

To perform a data import, complete the following steps:

1. Create an import template. In the template, you can configure the mapping between parts of the file and the platform attributes into which you want to transfer the data.
2. Run the import.

2.9.1. Create an Import Template

You can create a template for importing data from the following file types:

• Excel file — files with the .xls or .xlsx extension, containing no more than one sheet.
• XML file — a file with the .xml extension.

2.9.1.1. Template for Importing Data from an Excel File

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Data Import 2 shortcut group, then select the Import Templates 3 shortcut.

3. In the toolbar, select Create 4.

4. Fill in the fields 1 using the hints in the table below, then in the toolbar select Save.

Field	Description
Code*	Unique code of the import template. The code must be unique. The code must be short (typically up to 10 characters). Use only Latin letters and digits. Example: "inv2025" — for importing invoices, "employees" — for importing an employee list, "prod_list" — for importing products.
Name*	Enter the template name as it will appear in the platform interface. The name can contain any characters and be written in any language. Make the name descriptive so its purpose is clear. Example: "Invoice Import 2025", "Employee Directory", "Product Catalog".
Description	Optional field where you can describe the template's purpose and usage details in full. Example: "Template for monthly product list updates from 1C", "Import of new employees from the HR department file"
Object type*	Select one of the following object types into which data will be imported. Document type User dictionary System dictionary
Object*	After selecting the object type, select the specific object (document type, user dictionary, or system dictionary) into which data will be imported.
Binding settings*	Binding settings are the most important part of the configuration, where you define the mapping between the columns of your Excel file and the attributes in the system. Enable the toggles for the attributes into which you want to import data from the Excel file. ℹ️ Note: Import is not supported for the following attribute types: Multiple Reference HTML Content Table attributes — for these attribute types, you can import data directly through the document or task form. Some attributes contain nested attributes, where each nested attribute has its own toggle. Enable at least one nested attribute toggle. In the Message field, enter the attribute names that must exactly match the column names in the Excel file. Example: Excel column name "Product Name" = attribute name "Product Name" in the system. ℹ️ Note: When working with an attribute that contains nested attributes (for example, a dictionary), you must: Enable the main (root) attribute. In the Message field for this root attribute, enter only a dot "." Enable the toggle for one or more nested attributes. In the Message field of the enabled nested attributes, enter the column name from the Excel file. Enable the Key attribute toggle for the required attributes. The Key attribute toggle marks the fields by which the system will compare data from Excel against existing records in the system. How import with a single key attribute works: The system compares the value in the Excel cell against the values of this attribute across all existing records in the system: If a record is found where the attribute value matches → the system will update the other fields of that record with the Excel data If no record with that attribute value is found → the system will create a new record with all the data from Excel How import with multiple key attributes works: The system searches for records by the values of all key attributes: If a record is found where the value of at least one key attribute matches → the system will update that record with the Excel data If no record is found with those key attribute values → the system will create a new record ℹ️ Note: You must mark at least one attribute as a key attribute. Choose as key attributes those whose values are not repeated across different records in the system. Example: a dictionary record code — its value is unique for each record. Do not use system fields (Document number, Registration number, Registration date) for creating new documents via import. However, you can use them as key fields when updating existing documents. Attributes of type Boolean and Hyperlink cannot be key attributes.

Note:

Fields marked with * are required.

When importing Boolean attribute values, enter "Yes" in the Excel file if the toggle should be enabled, or leave the cell empty if the toggle should be disabled.

2.9.1.2. Template for Importing Data from an XML File

Field	Description
Code*	Unique code of the import template. The code must be unique. The code must be short (typically up to 10 characters). Use only Latin letters and digits. Example: "inv2025" — for importing invoices, "employees" — for importing an employee list, "prod_list" — for importing products.
Name*	Enter the template name as it will appear in the platform interface. The name can contain any characters and be written in any language. Make the name descriptive so its purpose is clear. Example: "Invoice Import 2025", "Employee Directory", "Product Catalog".
Description	Optional field where you can describe the template's purpose and usage details in full. Example: "Template for monthly product list updates from 1C", "Import of new employees from the HR department file"
Object type*	Select one of the following object types into which data will be imported. Document type User dictionary System dictionary
Object*	After selecting the object type, select the specific object (document type, user dictionary, or system dictionary) into which data will be imported.
Binding settings*	Binding settings* are the most important part of the configuration, where you define the mapping between the attributes of the XML file and the attributes in the system. Enable the toggles for the platform attributes into which you want to import data from the XML file. ℹ️ Note: Import is not supported for the following attribute types: Multiple Reference HTML Content Table attributes — for these attribute types, you can import data directly through the document or task form. Some attributes contain nested attributes, where each nested attribute has its own toggle. Enable at least one nested attribute toggle. In the Message field, enter the full path to the container value or container attribute value. Examples: Container value — the full path is written as a chain of XML element names separated by dots. Each name in the chain is the tag name you need to traverse to reach the required element. Container attribute value — the full attribute path is written as a chain of XML element names separated by dots, with the attribute name appended at the end after the @ symbol. ℹ️ Note: When working with an attribute that contains nested attributes (for example, a dictionary), you must: Enable the main (root) attribute. In the Message field for this root attribute, enter only a dot "." Enable the toggle for one or more nested attributes. In the Message field of the enabled nested attributes, enter the full path to the container value or container attribute value. Enable the Key attribute toggle for the required attributes. The Key attribute toggle marks the fields by which the system will compare data from Excel against existing records in the system. How import with a single key attribute works: The system compares the value in the Excel cell against the values of this attribute across all existing records in the system: If a record is found where the attribute value matches → the system will update the other fields of that record with the Excel data If no record with that attribute value is found → the system will create a new record with all the data from Excel How import with multiple key attributes works: The system searches for records by the values of all key attributes: If a record is found where the value of at least one key attribute matches → the system will update that record with the Excel data If no record is found with those key attribute values → the system will create a new record ℹ️ Note: You must mark at least one attribute as a key attribute. Choose as key attributes those whose values are not repeated across different records in the system. Example: a dictionary record code — its value is unique for each record. Do not use system fields (Document number, Registration number, Registration date) for creating new documents via import. However, you can use them as key fields when updating existing documents. Attributes of type Boolean and Hyperlink cannot be key attributes.

Note:

Fields marked with * are required.

2.9.2. Run the Import

You can run the import using one of the following methods:

Method 1: Via the system "Import" shortcut.
available to users with the admin role

1. In the navigation panel, select the Documents 1 workspace.

2. Select the Data Import 2 shortcut.

3. In the Template 1 field, select the required data import template.

4. In the File content field, select + 2 to upload the file from which you want to import data.

5. Select the Import 3 button.

After the import starts, the system checks for all columns defined in the import template and displays a data preview. To cancel the import, select the Discard changes button.

Method 2: Via a user shortcut
available to all users

Via a user shortcut of the Documents or User Dictionaries type. This method is available to all users who have been granted access to the shortcut by its creator.

1. Create a shortcut.

2. When creating the shortcut, in the Type 1 field, select Documents or User Dictionaries.

3. In the toolbar, select the Save 2 icon.

4. In the top right corner of the dictionary, select the 1 icon, then select Data Import 2.

5. In the Template 1 field, select the required data import template.

6. In the File content field, select + 2 to upload the file from which you want to import data.

7. Select the Import 3 button.

After the import starts, the system checks for all columns defined in the import template and displays a data preview. To cancel the import, select the Discard changes button.

2.9.3. Configure Attachment and QES Import

The platform allows you to import attached files and their QES (qualified electronic signatures) into file attributes of documents. To do this, complete the following steps:

1. Create a data import template. When creating the template, in the Binding settings field, enable the file attribute 1 into which you want to import attachments.
2. In the Message field 2, enter the required attribute name.
3. In the Signatures 3 field, select one of the following options:

---

• None — Import files without a QES, in .txt, .doc, .docx, .png, .pdf, .xls, or .xlsx format.

---

• In separate files — the main file and QES are imported separately. The signature file must have the same name as the main file with the ".p7s" extension appended at the end.

  Example:
  Main file: Act.docx
  QES file: Act.docx.p7s

  Note:

  If you need to import multiple QES signatures for a single attachment, add sequential signature numbers to the signature file names.

  Example:
  Main file: Act.docx
  First QES file: Act.docx.1.p7s
  Second QES file: Act.docx.2.p7s
  Third QES file: Act.docx.3.p7s

---

• In a container — the file and QES are combined into a single container. The container name must include the full file name with the .p7s extension.

  Example: ActOfCompletedWorks.docx.p7s

---

• In separate files or in a container — both of the above options are supported.

---

4. Optional: In the File extension field, you can select the file extensions available for import. For example, if you select .pdf, all files in the .zip archive with a different extension will be ignored by the platform during import.

2.9.4. Run Attachment and QES Import

You can import not only data from a file, but also additional attachments you want to add to the document — these can be regular files or files with signatures. You can import them from your Excel or XML file directly into the file attributes of your document.

To run the import of document attachments and their signatures, complete the following steps:

1. Complete all the steps described in the previous section Configure Attachment and QES Import.

2. Open the Data Import window. You can do this using one of the following methods, depending on the role of the user performing the import:
   2.1. Via the system "Import" shortcut. This method is available only to users with the admin role.
   2.2. Via a user shortcut of the Documents or User Dictionaries type. This method is available to all users who have been granted access to the shortcut by its creator.

3. In the Data Import window, in the Template field, select the import template you created in the first step of this guide.

4. In the File content field, select the + icon to add the Excel or XML file that contains the attachment file names.

   Note:

   Regarding attachment names in the Excel or XML file:

   • If there is one attachment and it will be imported into a Document image or File attribute type, enter the full file name with extension in the Excel or XML file.

     Example: ActOfCompletedWorks.docx.

   • If there are multiple attachments and they will be imported into a Document attachments or File collection attribute type, enter the names of the folders containing the files in the Excel or XML file.

     Example: "Attachment 1", "Attachment 2".

5. In the Attachments field, select the + icon to add a .zip archive containing one or more attachments.

   • If there is only one attachment, the file must be placed in a .zip archive. It will be imported into a Document image or File attribute type, depending on the settings you configured in the first step of this guide.

   • If there are multiple attachments, each attachment file must be placed in a separate folder together with its signatures. All these attachment folders must then be grouped into a single .zip archive. Multiple attachments will be imported into Document attachments or File collection attribute types, depending on the settings you configured in the first step of this guide.

   * The format and number of files depends on the value of the "Signatures" field you selected when creating the import template.

6. Select the Next button.

After the import starts, the system checks for all columns defined in the import template and displays a data preview. To cancel the import, select the Discard changes button.

2.9.5. Import Data into Table Attributes

If you want to import data into table-type attributes, this cannot be configured at the document type, user dictionary, or system dictionary level. However, you can import data into a table attribute of the Table/Collection custom attribute type directly on the form of a specific document or task. Make sure that Detailed table settings and Detailed form settings are enabled and configured in your Table/Collection attribute.

1. Open the relevant workspace depending on the entity type:
   1.1. To import data into a document form, select the Documents 1 workspace, then select the Documents 2 shortcut.

   1.2. To import data into a task form, select the Tasks 1 workspace, then select the All Tasks 2 shortcut.

2. Select the task or document whose table attribute you want to import data into.

3. Find the table attribute on the form into which you want to import data.

   Note:

   For this import type, you can only use a custom attribute of the Table/Collection type.

   Note:

   Your attribute may have a different name — what matters is that it was created with the Table/Collection type.

4. On the attribute, select the 1 icon, then select Import 2.

5. Select the .xls or .xlsx file on your device from which you want to import data into the attribute. Also make sure your table in the file meets the following requirements:

   Note:

   Before importing data into a table attribute, prepare the table in the Excel file according to these requirements:

   1. The first row of the table A must be empty.
   2. The first column of the table B must be empty.

   These empty row and column are used by the platform as technical offsets and are not imported into the attribute data.

6. In the toolbar, select Save 3.

2.9.6. Grant Access to Import

By default, import can be performed by users with the Developer and Data manager roles.

To grant import access to users with other roles:

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Data Import 2 shortcut group, then select the Import Templates 3 shortcut.

3. Open the import template 4 to which you want to grant access.

4. Select one of the available methods:

Method 1: Using the button on the top panel

a. On the top panel of the form, select the Permissions button.

Method 2: Through the settings menu

a. To open the settings menu, select the icon in the top right corner of the form 1.

b. From the expanded menu, select Permissions 2.

5. In the toolbar, select the + icon.

6. In the Subject 1 field, select one of the following options:

   • Organizational units — select this option to grant access to one of the following entity types: our organizations, departments, positions, or executor groups.
   • Administration subjects — select this option to grant access to one of the following entity types: user groups, roles, or users.

7. In the desired entity field 2, add the specific unit to which you want to grant access.

8. In the toolbar, select Save 3.

2.9.7. View Import History

You can view the status and details of a completed import in two ways:

• By import template — view the import history for a specific import template.
• All imports — view the history of all imports regardless of the template. By default, import records are sorted by execution date.

2.9.7.1. Import History by Template

You can view the import history for a specific import template.

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Data Import 2 shortcut group, then select the Import Templates 3 shortcut.

3. Right-click the required import template 4.

4. Select Details 1, then Import Log 2.

The Import Log window will appear at the bottom of the screen, where you can view the status of imports performed using the selected template.

2.9.7.2. All Imports History

You can view the status and details of all imports performed on the platform.

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Data Import 2 shortcut group, then select the Import Log 3 shortcut.

3. Select the record 4 whose details you need.

4. To view the import details for each attribute, go to the Data tab.

2.9.8. Bulk Import from Folder

Note:

The Bulk Import from Folder feature is only available with the additional package dfx-mass-file-import installed.

The Bulk Import from Folder feature allows you to import a large number of files stored in a folder on the server into the platform. This is useful when your documents come from scanners, external systems, or services that place files into a predefined folder.

Note:

During import, the platform processes all files in the selected directory, except those located in nested subfolders.

2.9.8.1. Import Files from a Folder

Note:

The folder must be on the server. It is typically connected by a system administrator using a file manager (for example, WinSCP or Total Commander).

1. Create a custom Text attribute.
   In the following steps, the name of the import folder will be stored in this attribute's value. Name it, for example, "Bulk import folder name" and set the Code field to "Mass_folder_name".

2. Create a custom File Collection attribute.
   At the end of this guide, the imported files will be stored in this attribute's value. Name it, for example, "Imported files collection" and set the Code field to "Imported_files".

3. Open or create a document type.
   When creating it, go to the Constructor tab to add and configure the relevant attributes:

   1. Add the custom Text attribute (the one you created in step 1 of this guide) to the document type form.

   2. Add the custom File Collection attribute (the one you created in step 2 of this guide) to the form.

4. Create a document based on the document type you created in the previous step. When creating it, do the following:

   1. On the form, select the custom Text attribute and enter the name of the server folder from which you want to import files as its value.

5. In the navigation panel, select the Studio 1 workspace.

6. Select the Data Import 2 shortcut group, then select the Bulk Import from Folder 3 shortcut.

7. In the toolbar, select Import files 4.

8. In the Path to the directory with files on the server field, enter the path to the folder relative to the server.

9. In the Search attribute code field, enter the code of the attribute whose value contains the folder name (step 4, point i. of this guide).

10. In the "File Collection" attribute code field, enter the code of the attribute you added to the document form in step 3, point ii. of this guide.

11. Select the Do not import duplicates checkbox if you want the system to check imported files for duplicates by name and size.

12. Select the Validate "File Collection" attribute restrictions checkbox. The system will then apply the format and size validation you configured when creating the attribute.

13. Select Import.

After this, all contents of the server folder (that meet the criteria you specified) will be imported into the "File Collection" attribute value.

2.9.8.2. View the Bulk Import Status

1. In the navigation panel, select the Studio 1 workspace.

2. Select the Data Import 2 shortcut group, then select the Bulk Import from Folder 3 shortcut.

3. In the grid, you can view the import status A, the start and end dates of the import B, and the number of imported files C.

4. If errors occurred during import, you can view their count in the Errors A column, and download a detailed error report from the Action B column.

   The error report consists of two sections: Errors A and Processed B.

   • The Errors section lists the folder name that was checked during import, as well as the reason why the file import from that folder was not completed.

   • The Processed section lists the document ID and the name of the file that was successfully imported into the File Collection attribute defined in the import settings form.