# Integracja z systemem SBO - Adama

Funkcjonalność pozwala na importowanie zleceń na podstawie pliku Excel.

## Interfejs

Dodane zostało nowe uprawnienie pozwalające importować zlecenia z pliku Excel i zostało nadane dla użytkowników z rolą administrator. Włączenie roli powoduje pojawienie się przycisku "Import" w zakładce "+Zaplanuj":

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/import_button.png>)

Kliknięcie przenosi użytkownika do nowej strony, gdzie może przełączać widoki pomiędzy podstronami "Import zleceń" oraz "Historia importowanych zleceń":

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/new_site_with_import_and_history_button.png>)

### Podstrona "Import zleceń"

Po przejściu do widoku importu zleceń jest możliwość zaimportowania danych zleceń z pliku Excel. Po kliknięciu przycisku "Importuj" zostaną utworzone zlecenia, dla których pozycje w pliku Excel miały prawidłowe wartości.

Pojawi się także informacja o ilości poprawnie zaimportowanych pozycji z wypisanymi unikalnymi numerami ID (UNIQUE\_ID).

Dodatkowo w przypadku wystąpienia błędów walidacyjnych pojawi się tabela z wypisanymi pozycjami, dla których pojawiły się konflikty. Do każdej pozycji będą podane podstawowe dane:

- Unique ID,
- Numer SBO,
- Numer kontrahenta,
- Nazwa kontrahenta,
- Opis (W opisie podane będą pola, w których są niepoprawne wartości - walidacje).

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/import_from_Excel_file_site.png>)

### Podstrona "Historia importowanych zleceń"

Użytkownik będzie miał dostęp także do historii importowanych plików. Po przejściu do podstrony "Import zleceń" jest możliwość przełączania się na widok Historii importowanych zleceń.

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/history_of_import.png>)

W kolumnie "Importowany plik" będzie możliwość pobrania pliku, który służył do importu. Po kliknięciu w kolumnie "Szczegóły" na ikonę użytkownik zostanie przeniesiony do strony z listą pozycji z pliku Excel.

Pozycje będą ujęte w tabeli i będą zawierać wszystkie dane z pliku Excel. Dodatkowo w kolumnie Zlecenia będzie lista id utworzonych zleceń na podstawie danej pozycji. Każdy numer będzie linkiem do konkretnego zlecenia.

W przypadku, gdy z danej pozycji nie zostały utworzone zlecenia w kolumnie "Zlecenia" pojawi się komunikat walidacyjny.

Poniżej przykładowa tabela z listą pozycji:

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/list_of_position_from_excel_file.png>)

## Założenia

1. Importowane będą tylko zlecenia do zakładki Transporty i Kontenery.
2. Importowane zlecenia będą miały tylko i wyłącznie jedno miejsce załadunkowe.
3. Importowane zlecenia będą miały załadunek tylko i wyłącznie w magazynie S7.
4. Importowane zlecenia będą miały tylko i wyłącznie jedno miejsce rozładunkowe z adresem z importowanego pliku.

## Opis pól z pliku Excel

Obsługujemy następujące pola z pliku Excel: - Unique ID,

- SBO number,
- Customer number,
- Delivery Name,
- Street,
- City,
- Postal code,
- Country,
- Indeks,
- Item Description,
- Qty to deliver,
- Qty in the container,
- Transport units,
- Product unit,
- Estimated time of arrival,
- Estimated time of departure,
- Type of car,
- ADR,
- Import customs clearance,
- Export customs clearance,
- Check-in address.

#### Unique ID

Unikalny numer używany do jednoznacznego określenia danego zamówienia. Jest on obowiązkowy i widoczny w tabeli zamówień.

#### SBO number

Numer zamówienia z systemu SBO. Numer ten nie jest unikalny i może występować w kilku zamówieniach. Jest to pole obowiązkowe i widoczne w tabeli zamówień w kolumnie Numer SBO.

#### Customer number

Numer kontrahenta. Pole obowiązkowe. Służy do identyfikacji kontrahenta. Przy imporcie numer ten będzie porównywany z numerem kontrahenta, który jest przypisany w platformie Logintegra. Pole to jest obowiązkowe i ponadto musi istnieć dokładnie jeden kontrahent o podanym numerze na platfomie, by zamówienie zostało utworzone.

#### Delivery Name

Adresat. Pole obowiązkowe. Nazwa danego adresu, który jest przypisany do klienta. Wartość z tego pola jest wyświetlana w polu formularza zlecenia "Adresat" w danych adresowych na rozładunku.

#### Street

Ulica. Pole obowiązkowe w przypadku braku danego Adresata. W przypadku braku adresu w platformie Logintegra pole będzie służyć do utworzenia nowego adresu kontrahenta na platformie Logintegra.

#### City

Miasto. Pole obowiązkowe. W przypadku braku adresu w platformie Logintegra pole będzie służyć do utworzenia nowego adresu kontrahenta na platformie Logintegra.

#### Postal Code

Kod pocztowy. Pole obowiązkowe. W przypadku braku adresu w platformie Logintegra pole będzie służyć do utworzenia nowego adresu kontrahenta na platformie Logintegra.

#### Country

Kraj. Pole obowiązkowe. W przypadku braku adresu w platformie Logintegra pole będzie służyć do utworzenia nowego adresu kontrahenta na platformie Logintegra.

#### Indeks

Indeks produktu. Pole obowiązkowe. Służy do identyfikacji produktu, który znajduje się już w platformie. Za pomocą tej wartości do zlecenia będzie dodawany automatycznie indeks, który znajduje się w zakładce Produkty. W przypadku braku takiego indeksu na platformie zostanie stworzony nowy produkt w platformie Logintegra na podstawie danych z pól (Indeks, Item Description, Product unit).

#### Item Description

Pełna nazwa produktu. Pole obowiązkowe w przypadku braku danego produktu na platformie. Pole to będzie brane pod uwagę tylko w przypadku braku produktu o danym indeksie (pole "Indeks") do utworzenia nowego produktu na platformie Logintegra.

#### Qty to deliver

Całkowita ilość jednostek produktu w zamówieniu. Pole obowiązkowe. Wartość podana w tym polu jest wykorzystywana do obliczania ilości zleceń.

#### Qty in the container

Maksymalna ilość jednostek danego produktu, jaka może być przewieziona jednym zleceniem. Pole obowiązkowe. Wartość potrzebna do wyliczenia ilości zleceń.

#### Transport units

Jednostki transportowe. Pole obowiązkowe. Wartość w tym polu informuje o ilości zleceń na platformie, jakie powinny być utworzone z danego zamówienia.

#### Product unit

Jednostka ilości produktu. Pole obowiązkowe w przypadku braku danego produktu na platformie. Pole to będzie brane pod uwagę tylko w przypadku braku produktu o danym indeksie (pole "Indeks") do utworzenia nowego produktu na platformie Logintegra. Dopuszczalne wartości to:

- kg,
- liters,
- pieces.

#### Estimated time of arrival

Data dostawy (rozładunku). Pole obowiązkowe. Na podstawie tej daty określana jest domyślna data dostawy na rozładunku.

#### Estimated time of departure

Dzień, w którym ma się odbyć załadunek w magazynie. Pole obowiązkowe. Na podstawie tej daty ustawiany jest domyślnie zakres czasu na załadunek w magazynie. Zakres czasu będzie od godziny 00:00 danego dnia do godziny 00:00 dnia kolejnego (pełne 24h).

#### Type of car

Rodzaj samochodu. Pole obowiązkowe. Na podstawie tej wartości określany jest rodzaj samochodu. Dopuszczalne wartości:

- Container 20',
- Container 40',
- Tilt,
- Tank,
- Isotank,
- Izotherm/Freezer.

Dodatkowo to pole określa też typ transportu. Na podstawie wartości w tym polu określany jest typ zlecenia w platformie Logintegra. W przypadku wartości: Container 20’ lub Container 40’ zlecenia będą importowane do typu Kontenery. W przypadku wartości: Tilt, Tank, Isotank, Izotherm/Freezer są utworzone jako typ Transport.

#### ADR

ADR. Pole obowiązkowe. Na podstawie tej wartości wybierana jest wartość pola wyboru w formularzu zlecenia o nazwie: ADR. Dopuszczalne wartości:

- YES,
- NO,
- LQ.

#### Import customs clearance

Odprawa celna import. Pole nieobowiązkowe. Na podstawie tej wartości jest oznaczana wartość w polu formularza zlecenia "Odprawa celna import". Dopuszczalne wartości:

- YES,
- NO.

#### Export customs clearance

Odprawa celna eksport. Pole nieobowiązkowe. Na podstawie tej wartości jest oznaczana wartość w polu formularza zlecenia "Odprawa celna eksport". Dopuszczalne wartości:

- YES,
- NO.

#### Check-in address

Adres odprawy celnej. Pole nieobowiązkowe. Wartość podana w tym polu zapisuje się w polu "Uwagi" w formularzu zlecenia.

## Mapowanie danych z pliku Excel do platformy Logintegra

#### Dodanie nowego produktu na platformie Logintegra

W przypadku, gdy zostanie przesłany wraz z pozycją numer indeksu, którego nie ma jeszcze na platformie Logintegra to zostanie dodany nowy produkt. Poniżej mapowanie pól z pliku Excel do utworzenia nowego produktu.

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/mapping_new_product.png>)

#### Stworzenie zlecenia na platformie Logintegra

W przypadku poprawnych danych na platformie tworzonych jest tyle transportów, by wykorzystać całkowitą ilość indeksów. Poniżej mapowanie pól w formularzu transportu.

![](<https://docs.logintegra.com/apollo-backend/pl/static/adama-api/adama_SBO_integration/mapping_new_transport.png>)

## Utworzenie nowego zlecenia

Zlecenie będzie tworzone na podstawie danych z pliku Excel. Mapowanie danych przedstawione jest powyżej na screenie.

Zlecenia, które pochodzą z importu będą miały dodatkowy status: Zaimportowane. Dopiero po zatwierdzeniu tego statusu zlecenie przejdzie do etapu "Nowy" i będzie mogło być dalej procesowane.

Na podstawie jednej pozycji z pliku Excel może zostać utworzonych kilka zleceń. O ilości utworzonych zleceń i ilościach indeksów w tych zleceniach decydują wartości w polach:

- Qty to deliver,
- Qty in the container,
- Transport units.

Pole "Qty to deliver" określa całkowitą ilość indeksów. Pole "Qty in the container" określa maksymalną ilość indeksów jakie zmieszczą się w danym środku transportu. Pole "Transport units" wskazuje ile zleceń powinno zostać utworzonych.

###### Przykład

Dane z pozycji:

| Qty to deliver | Qty in the container | Transport units |
| --- | --- | --- |
| 210 000 | 20 000 | 11 |

W takim przypadku tworzymy 11 transportów. Na początku tworzymy zlecenia z pełnym obłożeniem (maksymalną ilością jaką można załadować na dany typ transportu). Zatem powstanie 10 zleceń, w których będzie po 20 000 szt danego indeksu. W ostatnim 11 zleceniu powinno być tyle sztuk indeksu, ile zostało. Zatem 11 zlecenie będzie miało 10 000 szt indeksu.

## Walidacje

Pola obowiązkowe:

- Unique ID,
- SBO number,
- Customer number,
- Delivery Name
- Indeks,
- Qty to deliver,
- Qty in the container,
- Transport units,
- Estimated time of arrival,
- Estimated time of departure,
- Type of car,
- ADR.

Pola warunkowo obowiązkowe:

- Street (gdy nie istnieje w platformie Adresat "Delivery Name"),
- City (gdy nie istnieje w platformie Adresat "Delivery Name"),
- Postal code (gdy nie istnieje w platformie Adresat "Delivery Name"),
- Country (gdy nie istnieje w platformie Adresat "Delivery Name"),
- Item Description (gdy nie istnieje na platformie produkt o indeksie "Indeks"),
- Product unit (gdy nie istnieje na platformie produkt o indeksie "Indeks").

Pola nieobowiązkowe:

- Import customs clearance,
- Export customs clearance,
- Check-in address.

Komunikaty walidacyjne:

| Walidacja | Komunikat |
| --- | --- |
| Brak obowiązkowych wartości w polach X, Y. | Proszę podać wartości w polach "X", "Y". |
| Wartość w polu Z zawiera inne znaki niż cyfry. Dotyczy pól: Unique ID, SBO number, Customer number, Qty to deliver, Qty in the container, Transport units. | Wartość w polu "Z" musi się składać z samych cyfr. |
| Wartość w polu Product unit jest inna niż jedna z dopuszczalnych wartości: kg, liters, pieces. | Dopuszczalne wartości w polu "Product unit" to kg, liters, pieces. |
| Wartość w polu Type of car jest inna niż jedna z dopuszczalnych wartości: Container 20', Container 40', Tilt, Tank, Isotank, Izotherm/Freezer. | Dopuszczalne wartości w polu "Type of car" to Container 20', Container 40', Tilt, Tank, Isotank, Izotherm/Freezer. |
| Wartość w polu ADR jest inna niż jedna z dopuszczalnych wartości: YES, NO, LQ. | Dopuszczalne wartości w polu "Product unit" to YES, NO, LQ. |
| Wartosć w polu Import customs clearance jest inna niż jedna z dopuszczalnych wartości: YES, NO. | Dopuszczalne wartości w polu "Import customs clearance" to YES, NO. |
| Wartosć w polu Export customs clearance jest inna niż jedna z dopuszczalnych wartości: YES, NO. | Dopuszczalne wartości w polu "Export customs clearance" to YES, NO. |
| Wartość w polu "Qty in the container" jest większa od "Qty to deliver". | Wartość w polu "Qty to deliver" musi być większa od wartości w polu "Qty in the container". |

## Dodatkowe zmiany, jakie należy wykonać na platformie

1. Pole ilość w formularzu dodawania nowego indeksu nie będzie obowiązkowe.
2. Pole ilość palet w formularzu zlecenia będzie polem obowiązkowym.
3. Usuwamy z formularza typu Transport pola:

- Opakowania,
- Osoba kontaktowa,
- Produkt,
- Objętość,
- nr WZ.

## Ponowne przesłanie pozycji (edycja)

Z racji, że z jednej pozycji tworzy się nawet kilkadziesiąt transportów, to proponujemy, by nie było możliwości edycji pozycji, z której poprawnie utworzono zlecenia.

Oczywiście w przypadku jeżeli przesłana pozycja nie przeszła walidacji i nie zostały utworzone zlecenia, ponowne przesłanie poprawnych już wartości powinno utworzyć zlecenie.

## Problemy integracji jednostronnej za pomocą pliku Excel

1. Dane z pliku Excel jest ciężko walidować. Zazwyczaj w takim pliku jest dużo transportów. Problem pojawia się jak np. połowa nie spełnia założonych walidacji. Użytkownik później poprawia plik i przesyła również te transporty, które były już utworzone. Z doświadczenia zdarzają się takie sytuacje, że mamy ustalenia co do konkretnych pól a po dłuższym czasie pojawiają się różne kombinacje wartości w polach, których miało nie być.
2. Poziom skomplikowania dodanych walidacji bardzo rośnie z czasem i jest bardzo ciężki do zrozumienia przez użytkownika, który nie uczestniczył w projektowaniu i zmianach funkcjonalności.
3. Przy takim rozwiązaniu jest spore obciążenie supportu. Użytkownik po zaimportowaniu danych widzi listę nieprawidłowości i prosi support o wskazanie dlaczego dane transporty się nie utworzyły.
4. Nie jest to rozwojowe rozwiązanie.

## Inne możliwości integracji

A) Tabela pośrednicząca,

B) Webeservice,

C) REST API.
