Organization Structure Import Instructions
The following instructions describe the structure of the import file (e.g., CSV/Excel) used to upload or update the organizational structure in the system. Each row in the file represents a single node in the hierarchy (e.g., company, region, micromarket, specific store/station).
1. Node Identification and Hierarchy
The columns in this section are responsible for placing the node in the organization tree and ensuring its proper naming.
| Column Name | Requirement | Description and Filling Rules |
|---|---|---|
id | Required | External identifier of the node (External ID). Unique key for each element of the structure. |
new_id | Optional | Used to update the current external identifier. If you enter a value here, after import the id identifier will be replaced by new_id. |
parent_id | Required* | Identifier of the parent (node higher in the hierarchy). Note: In case of updating the parent's ID via new_id, the new ID must appear here.*May remain empty only for the main organization node (Root/Headquarters). |
level_name | Required | Name of the structure level where the node is located. E.g., Headquarters, Region, Micromarket, Store, Station. |
name | Required | Actual name of the given node, e.g., Western Region, Store Warsaw-Center. |
2. Assigning Managers
The system allows assigning multiple managers to a single node. The manager columns use the prefix managers:[NUMBER]:, where the number represents the ordinal number of the manager (1, 2, 3, etc.).
Important: Each defined manager must have at least the id and email columns filled out.
| Column Format (e.g., for manager no. 1) | Requirement | Description |
|---|---|---|
managers:1:id | Required | Manager's external identifier (External ID). Tip: If unique manager IDs from other systems are missing, their email address can be provided as ID (best practice) or ultimately a combination of first and last name (e.g., jan.kowalski). |
managers:1:email | Required | Manager's email address. |
managers:1:first_name | Optional | Manager's first name. |
managers:1:last_name | Optional | Manager's last name. |
managers:1:attr:[attribute_name] | Optional | Any additional attributes assigned to a specific manager. E.g., column managers:1:attr:country_code with the value PL. |
To add a second manager, add subsequent columns with the prefix, e.g., managers:2:id, managers:2:email, etc.
3. Geographical Location
These columns are used to specify precise geographic coordinates. They are usually filled only for leaf nodes, such as a specific store or gas station.
| Column Name | Description |
|---|---|
location:lat | Latitude (e.g., 52.2297). |
location:lng | Longitude (e.g., 21.0122). |
4. Address Data
The node address section. Contains standard address components and a flexible prefix for custom fields.
| Column Name | Description |
|---|---|
address:country_code | Country code (e.g., PL, DE). |
address:city | City. |
address:postal_code | Postal code. |
address:street | Street. |
address:building_number | Building / apartment number. |
address:formatted | Full formatted address as a single string (e.g., if not split into street/city). |
address:extra:[name] | Additional address fields not listed above. Examples: address:extra:county (county), address:extra:voivodeship (voivodeship). |
5. Additional Node Attributes
You can extend node information with any custom parameters using the attr: prefix.
| Column Name | Description |
|---|---|
attr:[attribute_name] | Defines a unique attribute for a unit/node. |
Examples:
attr:has_toilet(e.g., valuetrueorfalse)attr:ownership_model(e.g., valuefranchise)