Import API: Rules for positions synchronization

Since synchronized or new positions are a list, and the final view of the positions is a tree, the Tangl platform uses a mechanism of automatic recognition of parent and child positions and building them into a tree.

Basic properties of the position

Each position has several properties that are important when importing or synchronizing:

• Guid (optional) - unique position identifier.
• Code ( required) - full code of the position. As a general rule, it consists of several modules. For example: А.01.12-003
• Name (optional) - position name.

Additional properties of the position

In addition to the basic properties, a position has additional properties that usually need to be written or updated:

• Price (optional) - unit rate of the position.
• Unit (optional) - the unit of position measurement from those present in the Tangl Value service in the global settings.

Organizing positions when importing into an empty directory

When importing into an empty catalog, all positions have the status of new. The only property by which they can be organized into a tree is the Position Code.

When importing Tangl itself arranges the position codes into modules and on this basis determines their hierarchy. The following rules apply:

• Module delimiters can be represented by any characters.
• The order of the positions in the list does not matter, as their hierarchy and final order is determined by their codes.
• If the list contains an position with a second-level code (e.g. 12.20) but no parent position with a first-level code (e.g. 12), the child position will not be imported, but will be ignored because the system will not find a parent for it in the hierarchy .
• Empty rows or rows with missing codes or names are ignored.

Example of a list of imported positions:

┌─────────┬────────────┐
│Код      │ Имя        │
├─────────┼────────────┤
│01       | ST         │ //✔ New
│02       | AR         │ //✔ New
│         │            │ //✖ Blank line. Ignored
│01.10    │ Walls      │ //✔ New child. Parent: 01
│01.20    │ Slabs      │ //✔ New child. Parent: 01
│04.10    │ Pipes      │ //✖ New child. Parent: 04. Ignored
└─────────┴────────────┘

The result of the import in the catalog:

01 ST
 └─ 01.10 Walls
 └─ 01.20 Slabs
02 AR

Organizing positions when importing into a non-empty directory

When importing into a catalog that already has existing positions, the imported positions can have the status of new or updated.

If the imported position is missing in the directory, the rules above plus additional rules apply to it:

• The system will search for the parent not only in the imported list of positions, but also in the catalog to which the import is performed.
• If an position with a certain code, name or Guid is already present in the reference book, it will not be searched for a parent, because the position does not require organization in the tree.

An example of a catalog to which the import is performed:

01 ST
 └─ 01.10 Walls
02 AR
04 MEP

Example of a list of imported positions:

┌─────────┬────────────┐
│Код      │ Имя        │
├─────────┼────────────┤
│02       | AR         │ //✔ Existing. Updated
│         │            │ //✖ Blank line. Ignored
│01.10    │ Walls 200  │ //✔ Existing child. Parent 01 is found in the catalog. Updated
│01.20    │ Slabs      │ //✔ New child. Parent 01 found in the catalog
│04.10    │ Pipes      │ //✔ New child. Parent 01 found in the catalog
└─────────┴────────────┘

The result of the import in the catalog:

01 ST
 └─ 01.10 Walls 200
 └─ 01.20 Slabs
02 AR
04 MEP
 └─ 04.10 Pipes

Search for existing positions in the catalog when importing

When importing, the system tries to find the imported position in the catalog to decide whether it is new or existing.

The search prioritizes the position properties in the following order:

First the search is performed by the Guid field.

• If there is no Guid field or the position with such Guid is not found, the search is performed by the Code field.
• If the position with such a Code field is not found, the search is performed by the Name field.
• If there is no Name field or the position with such a field is not found, this position is considered a new one.

The following rules also apply:

• If the Code field is missing, the position is skipped.
• If the position has no parent position in the write data or in the existing catalog, the position is skipped.
• If there are no fields to write data, the data is skipped (remains as it was in the catalog or is created empty if the position is new).

Data deletion

Properties for deleting positions:

• Guid (optional) - unique position identifier.
• Code (required) - position code.
• Name (optional) - position name.

When searching for positions for deletion, the selection follows a feature sequence in an order similar to a data write.