Infs protokół komunikacyjny Wersja 1.3 Słownik Klient aplikacja zainstalowana na urządzeniu z systemem Android, w posiadaniu kierowcy Serwer aplikacja zainstalowana na infrastrukturze firmy Infis, komunikująca się z klientami Założenia 1. Wymiana informacji odbywa się przy pomocy protokołu XMPP. 2. Komunikaty przesyłane przez system muszą być poprawne brak wymaganych tagów lub niepoprawny format XML powoduje zignorowanie komunikatu. 3. Wszystkie przesyłane komunikaty sterujące wymagają potwierdzeń, zarówno te przesyłane z serwera do końcówki, jak i z końcówki do serwera. Nie dotyczy to jedynie komunikatów potwierdzających. 4. Unikalność identyfikatorów komunikatów jest wymagana w ramach całej komunikacji klienta z serwerem nie może się zdarzyć sytuacja, w której dany klient prześle nowy komunikat o już wykorzystanym identyfikatorze. Analogicznie, serwer nie może wysłać nowego komunikatu o już wykorzystanym identyfikatorze do danego klienta. 5. Klient bądź serwer mogą wysłać powtórnie niezmieniony komunikat, identyfikowany unikalnym identyfikatorem komunikatu. Jeżeli druga strona konwersacji przetworzyła już ten komunikat, musi odesłać potwierdzenie otrzymania, ignorując samą treść komunikatu. 6. Jeżeli strona nie otrzymała potwierdzenia dostarczenia komunikatu, powinna wysłać ten komunikat ponownie, z niezmienionym identyfikatorem komunikatu. 7. Końcówki akceptują komunikaty przesyłane od dowolnego identyfikatora JID, serwer akceptuje komunikaty wysłane do dowolnego identyfikatora JID. 8. Jeśli nie zaznaczono inaczej, pola są typu tekstowego, mogą zawierać dowolne znaki alfabetu UTF-8 i mają długość do 255 znaków. 9. Jeśli nie zaznaczono inaczej, przy zapisie liczb rzeczywistych stosuje się przecinek od oddzielania części ułamkowej. 10. Oprócz komunikatów sterujących, klient obsługuje standardowe rozmowy (chat) znane z protokołu XMPP może je inicjować i odpowiadać na przychodzące rozmowy. Typy komunikatów System obsługuje następujące typy komunikatów: 1. Przesyłane z serwera do klienta: a. Nowe zlecenie b. Edycja istniejącego zlecenia c. Usunięcie zlecenia 1
d. Zakończenie zlecenia i potwierdzenie zakończenia zlecenia 2. Przesyłane z klienta do serwera: a. Akceptacja zlecenia b. Odrzucenie zlecenia c. Zmiana stanu zlecenia 3. Przesyłane w obie strony: a. Potwierdzenie otrzymania komunikatu Opis komunikatów Wszystkie komunikaty sterujące w systemie przesyłane są wewnątrz znacznika <body> </body> wewnątrz typu Message z protokołu XMPP. Każdy komunikat sterujący musi rozpoczynać się ciągiem znaków: <infis_message type= Typ komunikatu jest determinowany na podstawie elementu: type=" " Tylko znane typy komunikatów są przetwarzane. Wymaganym elementem wszystkich komunikatów sterujących jest unikalny identyfikator komunikatu, ma on postać identyfikatora tekstowego (litery, liczby, znaki - i _ ): <msg_id>12345</msg_id> Poszczególne typy komunikatów mają własne, wymagane elementy. Komunikaty przesyłane z serwera do klienta Nowe zlecenie Nowe zlecenie posiada typ order_new i wymaga następujących elementów: <order_id> unikalny identyfikator zlecenia, z jego użyciem będzie wykonywana cała komunikacja dotycząca zlecenia <vehicle_id> nazwa pojazdu obsługującego zlecenie (czyli de facto tego, do którego powinno trafić zlecenie) <trailer_id> nazwa/numer naczepy ("parowanie" naczepy z ciągnikiem) <driver_id> identyfikator kierowcy (nr karty do tacho, id Dallasa) opcja <loads> informacje o załadunku, opisane poniżej <unloads> informacje o rozładunku, opisane poniżej Do tego opcjonalnie komunikat może zawierać informacje: <name> nazwa zlecenia wprowadzana podczas jego generowania <driver_name> nazwisko kierowcy (opcja) <contract> numer umowy (opcjonalnie) <comment> komenatrz tekstowy do zlecenia, długość do 4000 znaków Elementy <loads> i <unloads> składają się z niepustych list, zawierających informacje o miejscu i towarze, który ma zostać w nim załadowany lub rozładowany. Każda z nich zawiera odpowiednio elementy <load> bądź <unload>, opisane następującymi parametrami: <location_no> liczba porządkowa lokalizacji kontrahenta. Nie jest identyfikatorem unikalnym firmy, a numerem porządkowym lokacji, używanym do określenia kolejności 2
odwiedzin punktów zdefiniowanych w zleceniu, oraz ich ewentualnej późniejszej edycji. Element wymagany. <name> nazwa kontrahenta <street> ulica <no> nr domu <app_no> nr mieszkania <city> miasto <zip> kod pocztowy <country> kraj <lat> szer. geogr., opisana jako liczba ze znakiem oznaczająca stopnie zapisane dziesiętnie (DDD.DDDD, <-180.0000; 180.0000> <lon> dł. geogr., opisana jako liczba ze znakiem oznaczająca stopnie zapisane dziesiętnie (DD.DDDD, <-90.0000; 90.0000> <start_time> data/godzina początku załadunku/rozładunku, opisana w formacie yyyy.mm.dd HH:mm z, gdzie yyyy rok, MM miesiąc w roku, dd dzień w miesiącu, HH; godzina, mm minuta, z strefa czasowa. <stop_time> data/godzina początku załadunku/rozładunku, opisana w formacie jak przy start_time <comment> komenatrz tekstowy do lokalizacji, długość do 4000 znaków Każdy element <load> bądź <unload> może zawierać listę <cargos> elementów <cargo>, opisujących ładunek. Poszczególne elementy mogą zawierać następujące elementy: <order_id> numer transakcji/zamówienia, nie ma nic wspólnego z identyfikatorem zlecenia w systemie <cargo_name> nazwa towaru <quantity> ilość, nieujemna liczba rzeczywista <unit> jednostka <total_weight> całkowita waga, liczba rzeczywista oznaczająca kilogramy <temp_control> kontrola temperatury, wartość 1 lub 0 <min_temp> min. dop. temp., liczba rzeczywista oznaczająca stopnie Celsjusza <max_temp> maks. dop. temp., liczba rzeczywista oznaczająca stopnie Celsjusza <comment> komentarz do ładunku, długość do 4000 znaków Edycja istniejącego zlecenia Edycja zlecenia posiada typ order_edit i wymaga elementu: <order_id> numer przesłany wcześniej w komunikacje order_new Edycja może zawierać dowolne elementy, znane z komunikatu order_new. Tylko przesłane w komunikacie order_edit elementy zostają zmienione, w przypadku przesłania list <loads> bądź <unloads> zmieniane są całe listy. Dodatkowo mogą się w treści wiadomości znaleźć polecenia edycji, usuwania bądź dodawania nowych miejsc załadunków i rozładunków, odpowiednio: <loads_edit> lista ładunków, które mają zostać zmienione, identyfikowanych na podstawie liczby porządkowej lokalizacji kontrahenta <location_no>. Zawiera elementy typu <load>, z których tylko przesłane dane zostaną podmienione. <loads_delete> lista ładunków, które mają zostać usunięte. Zawiera elementy <load>, z których tylko wykorzystywany jest jedynie <location_no> 3
<loads_new> lista ładunków, które mają zostać dodane. Zawiera elementy typu <load> Analogiczne komunikaty występują w przypadku typu <unload> Usunięcie zlecenia Usunięcie zlecenia posiada typ order_delete i wymaga elementu: <order_id> numer przesłany wcześniej w komunikacje order_new Po jego przesłaniu klient usuwa dane o zleceniu, jeżeli było ono w trakcie jest ono przerywane. Nie można cofnąć tej czynności. Zakończenie zlecenia i potwierdzenie zakończenia zlecenia Operacja zakończenia zlecenia przez operatora, wyrażenie zgody na zakończenie zlecenia bądź na jego odrzucenie przez kierowcę jest realizowana przy pomocy komunikatu typu order_terminate i wymaga elementów: <order_id> numer przesłany wcześniej w komunikacje order_new <terminate> wartość true/false, która oznacza zgodę lub jej brak na zakończenie zlecenia (jeśli jest to odpowiedź na żądanie klienta) bądź też true, jeśli jest to zakończenie wygenerowane po stronie operatora. Komunikat order_terminate jest wysyłany w trzech sytuacjach: operator chce zakończyć zlecenie (np. zostało ono odwołane przez zleceniodawcę) kierowca odrzucił przesłane mu zlecenie, odpowiedział komunikatem order_deny operator wyraża na to zgodę, bądź nie kierowca zakończył zlecenie, ustawiając odpowiedni status operator wyraża na to zgodę, bądź nie Komunikaty przesyłane z klienta do serwera Akceptacja zlecenia Akceptacja zlecenia posiada typ order_ack i wymaga elementu: <order_id> numer otrzymany wcześniej w komunikacje order_new Odrzucenie zlecenia Odrzucenie zlecenia posiada typ order_deny i wymaga elementów: <order_id> numer otrzymany wcześniej w komunikacje order_new <comment> niepusty komentarz tekstowy, długość do 4000 znaków Zmiana stanu zlecenia Zmiana statusu zlecenia posiada typ order_status i wymaga elementów: <order_id> numer otrzymany wcześniej w komunikacje order_new <status> numer statusu <comment> komentarz tekstowy, do 4000 znaków, wymagany przy niektórych statusach Statusy mają odpowiednio znaczenie: 0 zlecenie nie rozpoczęte nie jest wysyłane jako zmiana statusu, a jedynie ustawiany na telefonie 1 zlecenie w trakcie realizacji 4
2 oczekiwanie na załadunek 3 załadunek 4 oczekiwanie na rozładunek 5 rozładunek 6 przerwa w realizacji zlecenia wymaga przesłania komentarza 7 żądanie zakończenia zlecenia 8 zakończenie zlecenia nie jest wysyłane, jest ustawiane w momencie otrzymania potwierdzenia zakończenia od operatora Komunikaty przesyłane w obie strony Potwierdzenie otrzymania komunikatu Potwierdzenie otrzymania komunikatu posiada typ ack i wymaga następującego elementu: <ack_msg_id>12345</ack_msg_id> - potwierdzenie odebrania komunikatu o danym msg_id o wartości 12345 Przykład komunikacji 1. Operator przesyła nowe zlecenie: <infis_message type="order_new"> <msg_id>12aa1</msg_id> <order_id>12345</order_id> <vehicle_id>wa 54321</vehicle_id> <trailer_id>123</trailer_id> <name>przewóz desek z tartaków Leszka i Jarka do Pana Stefana</name> <loads> <load> <location_no>1</location_no> <name>tartak Leszka</name> <street>marszałkowska</street> <no>100</no> <app_no>1</app_no> <city>warszawa</city> <zip>00-100</zip> <country>polska</country> <lat>21,01234</lat> <lon>52,012345</lon> <start_time>2011.11.11 12:00 GMT</start_time> <stop_time>2011.11.12 12:00 GMT</stop_time> </load> <load> <location_no>2</location_no> <name>tartak Jarka</name> <street>al. Jerozolimskie</street> <no>12</no> <app_no>123</app_no> <city>warszawa</city> <zip>00-432</zip> <country>polska</country> 5
</loads> <unloads> <lat>21,01111</lat> <lon>52,02222</lon> <start_time>2011.11.13 12:00 GMT</start_time> <stop_time>2011.11.14 12:00 GMT</stop_time> <comment>uwaga! Zły pies na posesji!</comment> </load> <unload> <location_no>3</location_no> <name>fabryka mebli Pana Stefana</name> <street>inowłodzka</street> <no>1</no> <app_no></app_no> <city>warszawa</city> <zip>03-140</zip> <country>polska</country> <lat>21,01114</lat> <lon>52,02777</lon> <start_time>2011.11.14 13:00 GMT</start_time> <stop_time>2011.11.14 17:00 GMT</stop_time> <cargos> <cargo> <order_id></order_id> <cargo_name>deski dębowe</cargo_name> <quantity>100</quantity> <unit>szt.</unit> <total_weight>2000</total_weight> <temp_control>1</temp_control> <min_temp>0</min_temp> <max_temp>50</max_temp> <comment>deski podłogowe, bez sęków</comment> </cargo> </cargos> </unload> </unloads> 2. Komunikator potwierdza otrzymanie wiadomości: <infis_message type="ack"> <msg_id>9723dda</msg_id> <ack_msg_id>12aa1</ack_msg_id> 3. Kierowca akceptuje zlecenie: <infis_message type="order_ack"> <msg_id>76abs2</msg_id> <order_id>12345</order_id> 4. Serwer potwierdza otrzymanie akceptacji zlecenia <infis_message type="ack"> <msg_id>986acw1</msg_id> 6
<ack_msg_id>76abs2</ack_msg_id> 5. Kierowca ustawia status JAZDA i rusza w kierunku punktu załadunku: <infis_message type="order_status"> <msg_id>098dj</msg_id> <order_id>12345</order_id> <status>1</status> 6. Serwer potwierdza otrzymanie zmiany statusu <infis_message type="ack"> <msg_id>8009ee</msg_id> <ack_msg_id>098dj</ack_msg_id> 5. Dyspozytor się pomylił i nie wpisał numeru domu dostawy, edytuje więc zlecenie i przesyła poprawki do terminala: <infis_message type="order_edit"> <msg_id>569d</msg_id> <order_id>12345</order_id> <unloads> <unload> <location_no>3</location_no> <name>fabryka mebli Pana Stefana</name> <street>inowłodzka</street> <no>1</no> <app_no>7</app_no> <city>warszawa</city> <zip>03-140</zip> <country>polska</country> <lat>21,01114</lat> <lon>52,02777</lon> <start_time>2011.11.14 13:00 GMT</start_time> <stop_time>2011.11.14 17:00 GMT</stop_time> <cargos> <cargo> <order_id></order_id> <cargo_name>deski dębowe</cargo_name> <quantity>100</quantity> <unit>szt.</unit> <total_weight>2000</total_weight> <temp_control>1</temp_control> <min_temp>0</min_temp> <max_temp>50</max_temp> <comment>deski podłogowe, bez sęków</comment> </cargo> </cargos> </unload> </unloads> 7. Klient potwierdza otrzymanie aktualizacji zamówienia 7
<infis_message type="ack"> <msg_id>822100</msg_id> <ack_msg_id>569d</ack_msg_id> 8
Wersja Autor Opis zmian Data 1.0 Marcin Łępicki Pierwsza wersja dokumentu 18.04.2012 1.1 Marcin Łępicki Wprowadzenie metryki dokumentu. 19.04.2012 Drobne poprawki formatowania. Dodanie w opisie typu komentarza do zlecenia. Dodanie komentarza do lokalizacji. Przywrócenie formatu daty ze strefą czasową. Określenie maksymalnej długości komentarzy przy odrzuceniu i zakończeniu zlecenia. Poprawka błędu przy typie danych załadunku to ilość a nie jednostka jest typu rzeczywistego. Dodanie formatu liczb rzeczywistych w założeniach. 1.2 Marcin Łępicki Uściślenie zachowania przy odebraniu 23.04.2012 zduplikowanego pakietu. Dodanie komunikatów edycji listy załadunków / rozładunków. 1.3 Marcin Łępicki Dodanie komentarza do typu cargo Usunięcie typu order_comment Przeniesienie typu order_terminate jako elementu wysyłanego przez serwer Uściślenie i zmiana zachowania statusów 30.04.2012 9