Dispatch Application Programming Interface

Transcription

1 Intrductin Fleet Managers need t be able t dispatch drivers and their vehicles t a variety f lcatins: jbs, deliveries, service lcatins, etc. Cntig CONNECT prvides a way t track vehicle lcatins, and cmmunicate with drivers wirelessly via a Garmin Persnal Navigatin Device (PND) cnnected t a Cntig 6100 r 6150 GPS tracking beacn installed in a vehicle. The beacn prvides the functin f a wireless mdem and GPS lcatin device, while the Garmin PND prvides a graphical display unit and messaging terminal fr the driver in additin t it s functin as a navigatin device. Fleet Managers typically use dispatching applicatins that are tailred specifically t their business. In such cases, it is cnvenient t allw Fleet Managers t cntinue t use the applicatin with which they are mst familiar. In this case, Cntig s Data Exchange (DEX) (API) with Dispatch is designed t prvide develpers with a methd t exchange infrmatin asynchrnusly between their sftware and the invehicle equipment. This dcument prvides a design verview f the dispatch functins and methds available t develpers.

2 Table f Cntents INTRODUCTION 1 TABLE OF CONTENTS 2 GLOSSARY OF TERMS 4 OVERVIEW 5 COMMUNICATION 7 API DEFINITION OUTBOUND 9 SendJbByAddressTVehicle 9 SendJbByCrdinatesTVehicle 10 SendMessage 12 SendCannedMessage 13 SendMessageWithCannedRespnse 14 DeleteCannedMessage 16 RefreshCannedMessage 17 SendCannedRespnse 18 DetectPND 19 DeleteVehicleJb 20 DeleteAllJbs 20 DeleteAllMessages 21 ChangeJbPririty 22 RequestDriverID 24 2 f 2

3 SendDriverID 25 SendDriverStatus 26 DeleteDriverStatus 27 RequestJbStatus 28 RequestETA 30 EnableAutArrival 30 RequestDriverMessage 31 RequestDataSince 33 DetectVehiclePresence 41 API DEFINITION - INBOUND 43 JbStatusChangeNtificatin 43 MessageRespnseNtificatin 43 MessageNtificatin 44 RequestETANtificatin 44 RequestDriverIDNtificatin 46 RequestVehicleNtificatin 47 3 f 3

4 Glssary f Terms API Beacn An in-vehicle device featuring a GPS receiver, GPRS wireless data mdem, external GPS and GPRS antenna and electrical wiring harness fr pwer, grund, inputs and utputs. CannedMessage Messages that are prvisined t the PND remtely and stred fr future use by the driver when cmpsing a message n the PND. Up t 120 Canned Messages f 49 characters in length are supprted. CannedRespnse Messages that are sent as multiple chice respnses with an utbund message t the driver. Allws driver t pick frm list f desired respnses, reducing keystrkes. Up t 50 CannedRespnse messages f 49 characters are permitted fr a single utbund message t the PND DEX Data Exchange Driver ID A string f alphanumeric characters entered int the PND interface t identify a specific driver. May als be remtely set prgrammatically Driver Status An alphanumeric string that may be selected by a driver n the PND t indicate status (e.g. Off Duty, At Jb, On Duty, Driving etc. List f Driver Status values may be defined prgrammatically and pushed t the PND ESN Electrnic Serial Number GPRS General Packet Radi Service A data cmmunicatins system supprted n GSM netwrks GPS Glbal Psitining System GSM Glbal System fr Mbile a wireless vice and data netwrk Jb A message sent t a PND cnsisting f a destinatin, a message bdy, and a pririty 4 f 4

5 PND Persnal Navigatin Device (e.g. Garmin Satellite Navigatin device) REST Representatinal State Transfer Overview The Cntig DEX API prvides a methd t securely exchange infrmatin frm the Cntig CONNECT system fr a given fleet f vehicles via an asynchrnus REST interface. The DEX interface allws develpers t send and retrieve data in an XML-based frmat. The basic DEX API is dcumented [here]. The Dispatch enhancements t the DEX API, as prpsed in this dcument, prvide a methd t submit wellfrmed data t a vehicle r driver asynchrnusly via a REST interface using a new XML frmat, and receive acknwledgements r data in respnse als in XML frmat. This data may cnsist f jbs (destinatins), messages (i.e. mail), r cmmand messages sent t a PND. The API is designed t functin asynchrnusly as it must handle situatins in which the beacn ges ut f wireless cverage (such as when a vehicle is parked in an undergrund garage), and the PND is discnnected (such as when the driver remves the PND frm the dashbard and stres ut f sight fr security reasns). The API als prvides the develper with a methd t register fr ntificatins f certain supprted messages that may be received frm the PND. When a supprted message is received frm the PND n the Cntig CONNECT server, the API will send a ntificatin message t the develper s applicatin with: Vehicle ID Driver ID (if applicable) Jb r message ID Event timestamp The develper s applicatin may then submit a request t retrieve utstanding events, respnses, r inbund messages frm the API fr a given vehicle, driver, jb and/r message r fr all messages. Fr the API t be functinal, sme precnditins must be met, including: A Cntig beacn and PND are installed in ne r mre vehicles. Beacn is prvisined in the Cntig CONNECT system, and is enabled fr Dispatch. Vehicle recrds are prvisined in the Cntig CONNECT system. User accunts are established in the Cntig CONNECT system at least ne defined with DEX access. A and User Accunt Credentials are prvided t the develper t access the vehicle-specific infrmatin fr given fleet vehicles and t submit messages t PNDs in thse vehicles. 5 f 5

6 Once these precnditins are in place, the DEX API may be accessed. The DEX API enhancements fr Dispatch allw fr the fllwing new functins: Register fr Ntificatins Send Jb t PND (by address r by Lat/Lng crdinates) Send utbund Message thrugh t PND Send / update list f canned messages t device Send Message with CannedRespnses t PND Detect presence r absence f PND Detect presence f Vehicle (beacn) n netwrk Delete selected Jbs Delete all Jbs Delete all Messages Change Pririty f Jbs Request Driver ID Send Driver ID (ver-ride Driver ID n PND) Send / update list f Driver Status ptins Set Aut Arrival Request Jb Status Request Jb Estimated Time f Arrival (ETA) Messages that may be received frm the PND include: Jb status updates: Jb received n PND (pending) Jb read n PND (acknwledged) Driver navigating t jb (en-rute) Jb marked as cmpleted n PND (dne) Jb deleted n PND Messages (mail) Message received n PND Message read Message respnse frm PND: Reply t a specific message with an OK, Yes r N respnse Reply t a specific message with a CannedRespnse Reply t a specific message with a CannedMessage Reply t a specific message with free-frm text New inbund message frm PND (unslicited) Driver ID (lgin) Driver Status change 6 f 6

7 Cmmunicatin The fllwing figures prvide a high-level verview f sample cmmunicatins between yur client applicatin and the PND. Figure 1: Sample f registering fr ntificatins Figure 2: Sample f sending a message t the PND 7 f 7

8 Figure 3: Sample f an inbund message cming frm the PND Figure 4: Sample f a Jb Status Change n the PND Figure 5: Sample f requesting all inbund messages/ntificatins etc 8 f 8

9 API Definitin Outbund SendJbByAddressTVehicle Sends a jb t PND using an address. POST dept/{deptid}/v/{vehicleid}/dispatch/jb Permissin Vehicle id XML cntaining: Jb id Address message assciated with this jb (Optinal) Jb Pririty - rder in the Jb queue Sample: <jb_by_address> <jb_id>55</jb_id> <address> <street>795 Farrw Street</street> <city>cquitlam</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v3j 7V4</zip_cde> </address> <descriptin>pick up the package</descriptin> <pririty>1</pririty> </jb_by_address> 9 f 9

10 Respnse Field Result Cntains the result f the request Success true if the request was queued prperly false therwise Failure Reasn (ptinal) A failure reasn culd be that the address is incrrect. Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs Address nt fund SendJbByCrdinatesTVehicle Sends jb t PND using latitude and lngitude. POST dept/{deptid}/v/{vehicleid}/dispatch/jb Permissin Vehicle id XML Cntaining: Jb id 10 f 10

11 Latitude Lngitude message assciated with this jb (Optinal) Jb Pririty - rder in the Jb queue Sample: <jb_by_crds> <jb_id>55</jb_id> <lat> </lat> <ln> </ln> <descriptin>pick up the package</descriptin> <pririty>1</pririty> </jb_by_crds> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs Address nt fund 11 f 11

12 SendMessage Sends a simple message t the PND POST dept/{deptid}/v/{vehicleid}/dispatch/message Permissin Vehicle id XML Cntaining: Message Id Text Message Sample: <message> <msg_id>5</msg_id> <text>please make sure t fill-up n the way back.</text> </message> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> Errrs </result> 12 f 12

13 SendCannedMessage Creates a canned message fr the PND. POST dept/{deptid}/v/{vehicleid}/dispatch/canned_message Permissin Vehicle id XML Cntaining: Message Id Text message Sample: <message> <msg_id>5</msg_id> <text>stuck in traffic</text> </message> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> 13 f 13

14 Errrs SendMessageWithCannedRespnse Sends a message with an assciated canned respnse t the PND. POST dept/{deptid}/v/{vehicleid}/dispatch/message/canned_respnse Permissin Vehicle id XML Cntaining: Message Id Text message Canned Respnse ID List the list f respnse id (see SendCannedRespnse); nte: minimum value is 4 Sample: <message> <msg_id>5</msg_id> <text>what s the traffic situatin right nw?</text> <canned_respnse_list> <respnse>4</respnse> <respnse>6</respnse> <respnse>9</respnse> </canned_respnse_list> </message> Respnse Field result Cntains the result f the request success true if the request was queued prperly false therwise 14 f 14

15 Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 15 f 15

16 DeleteCannedMessage Deletes a canned message DELETE dept/{deptid}/v/{vehicleid}/dispatch/canned_message Permissin Vehicle id XML cntaining: Message id Sample: <canned_message> <msg_id>5</msg_id> </canned_message> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 16 f 16

17 RefreshCannedMessage Replaces an existing canned message fr the PND. PUT dept/{deptid}/v/{vehicleid}/dispatch/canned_message Permissin Vehicle id XML Cntaining: Message Id Text message Sample: <canned_message> <msg_id>5</msg_id> <text>stuck in traffic in majr rad</text> </canned_message> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> 17 f 17

18 Errrs SendCannedRespnse Sends canned respnse t the vehicle. POST dept/{deptid}/v/{vehicleid}/dispatch/canned_respnse Permissin Vehicle Id XML Cntaining: Canned Respnse id NOTE: minimum value is 4 Canned Respnse Sample: <canned_respnse> <respnse_id>4</respnse_id> <text>zer</text> </canned_respnse> Respnse Field Result Cntains the result f the request Success true if the request was queued prperly false therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> 18 f 18

19 </result> Errrs DetectPND Detects presence f PND cnnected t the device. GET dept/{deptid}/v/{vehicleid}/dispatch/pnd/cnnectin Permissin Vehicle id Respnse Field Cnnectin Cntains the Cnnected flag Cnnected True if a PND is cnnected False if the PND is nt cnnected Sample Respnse <?xml versin='1.0' encding='utf-8'?> <cnnectin xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <cnnected>true</cnnected> </cnnectin> Errrs 19 f 19

20 DeleteVehicleJb Deletes a jb in vehicle DELETE dept/{deptid}/v/{vehicleid}/dispatch/jb/{id} Permissin Vehicle id Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs DeleteAllJbs Deletes all jbs DELETE dept/{deptid}/v/{vehicleid}/dispatch/jb 20 f 20

21 Permissin Vehicle id Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs DeleteAllMessages Deletes all messages n the PND. DELETE dept/{deptid}/v/{vehicleid}/dispatch/message Permissin Vehicle id Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise 21 f 21

22 false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs ChangeJbPririty Changes the jb s pririty. PUT dept/{deptid}/v/{vehicleid}/dispatch/jb/{id} Permissin Vehicle id XML cntaining: New pririty number Sample: <pririty>5</pririty> 22 f 22

23 Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 23 f 23

24 RequestDriverID Request the driver ID. Nte that the respnse will be delivered asynchrnusly by the Cntig server via RequestDriverIDNtificatin (see belw). POST dept/{deptid}/v/{vehicleid}/dispatch/driver/getid Permissin Vehicle ID Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 24 f 24

25 SendDriverID Send the driver ID POST dept/{deptid}/v/{vehicleid}/dispatch/driver/id Permissin Vehicle ID XML cntaining: Driver ID t send Sample: <driver> <driver_id>5</driver_id> </driver> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 25 f 25

26 SendDriverStatus Send a list f canned driver status types that the driver may select frm when specifying his status (such as Driving, On Duty (Nt Driving) Sleeper Berth, Off Duty, etc). POST dept/{deptid}/v/{vehicleid}/dispatch/driver/status Permissin Vehicle ID XML cntaining: Status Id Text status id Sample: <driver_status_list> <driver_status> <status_id>5</status_id> <text>driving</text> </driver_status> <driver_status> <status_id>6</status_id> <text>on Duty (Nt Driving)</text> </driver_status> </driver_status_list> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise 26 f 26

27 false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs DeleteDriverStatus Deletes ne r mre driver status messages. DELETE dept/{deptid}/v/{vehicleid}/dispatch/driver/status/{statusid} Permissin Vehicle ID Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> 27 f 27

28 <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs RequestJbStatus Requests the current status f a particular jb. GET dept/{deptid}/v/{vehicleid}/dispatch/jb/<jb_id> Permissin Vehicle id Jb id Respnse Field Cntains: jb id pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm driver id jb status (culd be ne f: pending, ack, enrute, dne, deleted_by_driver) Jbs with status (ptinal; will nly appear if the jb 28 f 28

29 status is enrute ) ETA in secnds jb pririty starts with 1 GPS-related infrmatin is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Sample Respnse <?xml versin='1.0' encding='utf-8'?> <jb xmlns:xsi=" xsi:schemalcatin=" <jb_id>120</jb_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <driver_id>je</driver_id> <jb_status>enrute</jb_status> <eta>1850</eta> <pririty>1</pririty> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>795 Farrw Street</street> <city>cquitlam</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v3j 7V4</zip_cde> </address> <speed>50</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> 29 f 29

30 </jb> Errrs RequestETA Get the ETA f the current jb. Nte that the respnse will be delivered asynchrnusly via the RequestETANtificatin (see belw). POST dept/{deptid}/v/{vehicleid}/dispatch/pnd/eta Permissin Vehicle id Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs EnableAutArrival Enables the aut-arrival feature n the PND. 30 f 30

31 POST dept/{deptid}/v/{vehicleid}/pnd/autarrival Permissin Vehicle id If set t 1, then aut-arrival is turned n. If set t 0, then aut-arrival is turned ff. Sample: <autarrival>1</autarrival> Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs RequestDriverMessage Requests the message which the driver sent in respnse t the dispatcher message. This wrks with the MessageNtificatin Inbund methd mentined belw. GET dept/{deptid}/v/{vehicleid}/dispatch/message/<id> 31 f 31

32 Permissin Vehicle id Message id Respnse Field Cntains: pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm (ptinal) dispatcher msg id if this message is a respnse t a dispatcher message Driver message message GPS-related infrmatin is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Sample Respnse <?xml versin='1.0' encding='utf-8'?> <driver_message xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> 32 f 32

33 <pnd_esn> </pnd_esn> <beacn> </beacn> <dispatcher_msg_id>17</dispatcher_msg_id> <msg>yes</ msg> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </driver_message> Errrs RequestDataSince Requests a list f jb and message data fr a particular vehicle since a particular date. This is useful in the case f the custmer s server ging dwn. POST dept/{deptid}/v/{vehicleid}/dispatch Permissin Vehicle id XML cntaining: Cutff timestamp in epch frmat Sample: <cutff> <ts> </ts> </cutff> 33 f 33

34 Respnse Field Changes Cntains a list f changes since last time Cntains: jb id pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm driver id jb status (culd be ne f: pending, ack, enrute, dne, deleted_by_driver) (ptinal; will nly appear if the jb Jbs with status status is enrute ) ETA in secnds jb pririty starts with 1 GPS-related infrmatin is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Cntains: pnd esn the ESN f the Garmin PND 34 f 34

35 where this jb status was sent frm beacn the beacn where this jb status was sent frm msg id msg status (culd be ne f: pen, read, deleted) GPS-related infrmatin is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Cntains: message id pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm (ptinal) dispatcher msg id if this message is a respnse t a dispatcher message Driver messages message 35 f 35

36 GPS-related infrmatin is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Cntains: driver id pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm GPS-related infrmatin Driver Id Messages is GPS valid latitude and lngitude address speed in km/hr GPS timestamp in epch frmat Beacn timestamp in epch frmat Cntains: 36 f 36

37 Messages Cnnectin status - nline r ffline pnd esn the ESN f the Garmin PND where this jb status was sent frm beacn the beacn where this jb status was sent frm Beacn timestamp in epch frmat Sample Respnse <?xml versin='1.0' encding='utf-8'?> <data xmlns:xsi=" xsi:schemalcatin= dispatch.xsd"> <jbs> <jb> <jb_id>120</jb_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <driver_id>je</driver_id> <jb_status>enrute</jb_status> <eta>1850</eta> <pririty>1</pririty> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>795 Farrw Street</street> <city>cquitlam</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v3j7v4</zip_cde> </address> <speed>50</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </jb> <jb> <jb_id>120</jb_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <driver_id>je</driver_id> 37 f 37

38 <jb_status>dne</jb_status> <pririty>1</pririty> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9269 Mrningside Ln</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4r3</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </jb> <jb> <jb_id>122</jb_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <driver_id>je</driver_id> <jb_status>enrute</jb_status> <eta>1200</eta> <pririty>1</pririty> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>30</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </jb> <jb> <jb_id>121</jb_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <driver_id>je</driver_id> <jb_status>pending</jb_status> <pririty>2</pririty> <gps_related_inf> 38 f 38

39 <is_valid>false</is_valid> <lat> </lat> <ln> </ln> <address> <street>338 Macdnald Ave</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5c4n4</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </jb> </jbs> <dispatcher_messages> <dispatcher_message> <pnd_esn> </pnd_esn> <beacn> </beacn> <dispatcher_msg_id>17</dispatcher_msg_id> <dispatcher_msg_status>read</dispatcher_msg_status> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </dispatcher_message> </dispatcher_messages> <driver_messages> <driver_message> <msg_id>5</msg_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <dispatcher_msg_id>17</dispatcher_msg_id> <msg>yes</msg> 39 f 39

40 <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </driver_message> <driver_message> <msg_id>6</msg_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <msg>i picked-up an extra package frm Je.</msg> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </driver_message> </driver_messages> <driver_id_messages> <request_driver_id> <driver_id>jhn de</driver_id> <pnd_esn> </pnd_esn> <beacn> </beacn> <gps_related_inf> <is_valid>true</is_valid> <lat> </lat> <ln> </ln> <address> 40 f 40

41 <street>9897 Gaglardi Way</street> <city>burnaby</city> <state>bc</state> <cuntry>ca</cuntry> <zip_cde>v5a4n7</zip_cde> </address> <speed>0</speed> <gps_ts> </gps_ts> </gps_related_inf> <ts> </ts> </request_driver_id> </driver_id_messages> <vehicle_presence_messages> < detect_vehicle_presence > <cnnectin_status>ffline</cnnectin_status> <pnd_esn> </pnd_esn> <beacn> </beacn> <ts> </ts> </detect_vehicle_presence> < detect_vehicle_presence > <cnnectin_status>nline</cnnectin_status> <pnd_esn> </pnd_esn> <beacn> </beacn> <ts> </ts> </detect_vehicle_presence> </vehicle_presence_messages> </data> Errrs DetectVehiclePresence Use this methd t get ntified when a vehicle s beacn is nline r ffline. (See RequestVehicleNtificatin belw) POST dept/{deptid}/v/{vehicleid}/dispatch/nline Permissin 41 f 41

42 Vehicle ID Respnse Field result Cntains the result f the request success true if the request was queued prperly false - therwise Sample Respnse <?xml versin='1.0' encding='utf-8'?> <result xmlns:xsi=" xsi:schemalcatin="dispatch.xsd"> <inf>success</inf> </result> Errrs 42 f 42

43 API Definitin - Inbund JbStatusChangeNtificatin When Cntig gets a jb-status-change message frm the PND, Cntig will invke the custmer s REST server t ntify the custmer f the change. If the custmer s REST server is dwn, Cntig will nt attempt t retry. Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDataSince methd t query the changes. POST dispatch/ v/<vehicleid >/ntificatin/jb Permissin Jb id. Here s a sample: <jb> <id>4</id> </jb> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes MessageRespnseNtificatin When Cntig gets a message respnse frm the driver, Cntig will invke the custmer s REST server t ntify the custmer f the driver s respnse t the custmer s riginal message. If the custmer s REST server is dwn, Cntig will nt attempt t retry. Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDriver methd t query the message. POST dispatch/v/<vehicleid>/ntificatin/message Permissin Message id. Here s a sample: <message>

44 <id>5</id> </message> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes MessageNtificatin When Cntig gets a new message frm the driver, Cntig will invke the custmer s REST server t ntify the custmer f this new driver message. If the custmer s REST server is dwn, Cntig will nt attempt t retry. Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDataSince methd t query the changes. POST dispatch/v/<vehicleid>/ntificatin/drivermessage Permissin Message id. Here s a sample: <drivermessage> <id>4</id> </drivermessage> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes RequestETANtificatin (See RequestETA abve) When Cntig gets a jb s ETA inf, Cntig will invke the custmer s REST server t ntify the custmer that there has been a ETA change fr this particular jb. The custmer will then need t query Cntig s server t retrieve the ETA fr this jb via RequestDataSince (see abve). If the custmer s REST server is dwn, Cntig will nt attempt t retry. 44 f 44

45 Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDataSince methd t query the changes. POST dispatch/v/<vehicleid>/ntificatin/requesteta Permissin Jb id. Here s a sample: <request_eta> <jb_id>4</jb_id> </request_eta> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes 45 f 45

46 RequestDriverIDNtificatin (See RequestDriverID abve) When Cntig gets a jb s driver-id inf, Cntig will invke the custmer s REST server t ntify the custmer f this driver id. If the custmer s REST server is dwn, Cntig will nt attempt t retry. Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDataSince methd t query the changes. POST dispatch/v/<vehicleid>/ntificatin/requestdriverid Permissin XML cntaining: Driver id Vehicle ESN PND ESN Here s a sample: <request_driver_id> <driver_id>75</driver_id> <vehicle_esn> </vehicle_esn> <pnd_esn>21343</pnd_esn> </request_driver_id> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes 46 f 46

47 RequestVehicleNtificatin (See DetectVehiclePresence abve) When a vehicle cnnects t the Cntig server r is detected t be ver 1 hur withut any message, Cntig will invke the custmer s REST server t ntify the custmer f this state. If the custmer s REST server is dwn, Cntig will nt attempt t retry. Cntig will, hwever, keep track f which ntificatins have nt been sent s that the custmer can use the RequestDataSince methd t query the changes. POST dispatch/v/<vehicleid>/ntificatin/detectvehiclepresence Permissin XML cntaining: nline r ffline Driver id Vehicle ESN PND ESN Here s a sample: <detect_vehicle_presence> <cnnectin_status>nline</cnnectin_status> <driver_id>75</driver_id> <vehicle_esn> </vehicle_esn> <pnd_esn>21343</pnd_esn>a </detect_vehicle_presence> Respnse Standard HTTP respnse cdes Errrs Standard HTTP errr cdes 47 f 47