Instrukcja importu struktury organizacyjnej

Poniższa instrukcja opisuje strukturę pliku importu (np. CSV/Excel) służącego do wgrywania lub aktualizacji struktury organizacyjnej w systemie. Każdy wiersz w pliku reprezentuje pojedynczy węzeł w hierarchii (np. firma, region, mikrorynek, konkretny sklep/stacja).

1. Identyfikacja węzła i hierarchia

Kolumny w tej sekcji odpowiadają za umieszczenie węzła w drzewie organizacji oraz nadanie mu odpowiedniej nazwy.

Nazwa kolumny	Wymaganie	Opis i zasady wypełniania
id	Wymagane	Zewnętrzny identyfikator węzła (External ID). Unikalny klucz dla każdego elementu struktury.
new_id	Opcjonalne	Służy do aktualizacji obecnego identyfikatora zewnętrznego. Jeśli podasz tu wartość, po imporcie identyfikator id zostanie zastąpiony przez new_id.
parent_id	Wymagane*	Identyfikator rodzica (węzła wyżej w hierarchii). Uwaga: W przypadku aktualizacji ID rodzica przy użyciu new_id, musi się tu znaleźć to nowe ID. *Może pozostać puste tylko dla głównego węzła organizacji (Root/Centrala).
level_name	Wymagane	Nazwa poziomu struktury, na którym znajduje się węzeł. Np. Centrala, Region, Mikrorynek, Sklep, Stacja.
name	Wymagane	Właściwa nazwa danego węzła, np. Region Zachód, Sklep Warszawa-Centrum.

2. Przypisywanie menedżerów

System pozwala na przypisanie wielu menedżerów do jednego węzła. Kolumny dotyczące menedżerów używają prefiksu managers:[NUMER]:, gdzie numer oznacza liczbę porządkową menedżera (1, 2, 3, itd.).

Ważne: Każdy zdefiniowany menedżer musi mieć wypełnione przynajmniej kolumny id oraz email.

Format kolumny (np. dla menedżera nr 1)	Wymaganie	Opis
managers:1:id	Wymagane	Zewnętrzny identyfikator menedżera (External ID). Wskazówka: W przypadku braku unikalnych ID menedżerów z innych systemów, jako ID można podać ich adres e-mail (najlepsza praktyka) lub ostatecznie kombinację imienia i nazwiska (np. jan.kowalski).
managers:1:email	Wymagane	Adres e-mail menedżera.
managers:1:first_name	Opcjonalne	Imię menedżera.
managers:1:last_name	Opcjonalne	Nazwisko menedżera.
managers:1:attr:[nazwa_atrybutu]	Opcjonalne	Dowolne dodatkowe atrybuty przypisane do konkretnego menedżera. Np. kolumna managers:1:attr:country_code z wartością PL.

Aby dodać drugiego menedżera, dodaj kolejne kolumny z odpowiednim prefiksem, np. managers:2:id, managers:2:email, itd.

3. Lokalizacja geograficzna

Te kolumny służą do określania dokładnych współrzędnych geograficznych. Zazwyczaj wypełnia się je tylko dla węzłów końcowych (tzw. liści), takich jak konkretny sklep lub stacja benzynowa.

Nazwa kolumny	Opis
location:lat	Szerokość geograficzna (np. 52.2297).
location:lng	Długość geograficzna (np. 21.0122).

4. Dane adresowe

Sekcja adresu węzła. Zawiera standardowe składowe adresu oraz elastyczny prefiks dla pól niestandardowych.

Nazwa kolumny	Opis
address:country_code	Kod kraju (np. PL, DE).
address:city	Miasto.
address:postal_code	Kod pocztowy.
address:street	Ulica.
address:building_number	Numer budynku / lokalu.
address:formatted	Pełny, sformatowany adres jako jeden ciąg znaków (np. jeśli adres nie jest rozbity na oddzielne pola jak ulica czy miasto).
address:extra:[nazwa]	Dodatkowe pola adresowe niewymienione wyżej. Przykłady: address:extra:county (powiat), address:extra:voivodeship (województwo).

5. Dodatkowe atrybuty węzła

Możesz rozszerzyć informacje o węźle o dowolne parametry niestandardowe, używając prefiksu attr:.

Nazwa kolumny	Opis
attr:[nazwa_atrybutu]	Definiuje unikalny atrybut dla jednostki/węzła.

Przykłady:

• attr:has_toilet (np. wartość true lub false)
• attr:ownership_model (np. wartość franczyza)