Navigation Integration

Last updated
Save as PDF

MCP Maptuit NaviGo Integration

Maptuit Project Overview

Manumit NaviGo is a hybrid navigation solution for MCP customers. Hybrid refers to the fact that the application is distributed between the NaviGo Client (mobile) and the NaviGo Portal (server). Drivers request directions to destinations by entering the address on the Mobile Display Unit (MDU) in the cab.

The Maptuit NaviGo service provides drivers with moving maps, easy to read text, spoken directions, and a simple to use touch screen interface.

Questions (question)

Omnitracs Technical Services Team: developer-support.mail

Engineering Technical Support: 1-800-541-7490

Virtual Channels

260 -- For the conversation between the NaviGo Client and NaviGo Portal

261 -- For the conversation between the NaviGo Daemon and NaviGo Portal

322 -- For dispatch integration from Host to NaviGo Daemon

NaviGo Dispatch Integration Notes and Gotcha's

Dispatch Integration can only be sent to MCP units with NaviGo enabled and the Maps loaded, not I/Mct's.
Ensure that the units are in an account profile that has NaviGo enabled.
Ensure that the units themselves are enabled for Dispatch Integration.
Driver Log In must be enabled for the account.
The XML data that is to be sent to the units can be gotten from the MapTuit NaviGo Deamon API guide. Only the AddDispatch packet is required.
Special characters like & " < > ' must be coded for and converted into an format ( & ' < > " )
No responces are received from the unit in XML format. Only the standard Qtracs PEND, XMIT, RCVD, UNDL, and RJTD status values. Any special handling and notification of messages not being received or rejected by the mobile must be handled by the host. There are no notifications from the mobile if it has issues with the dispatch once the message is delieved to it.
The NaviGo dispatch messages are sent in binary format to channel 322 in the sned message/binary message command.
It is suggested that the messages are sent Sleepy to allow the longest send time.
Once the XML is build, ensure that it is in 64 bit encoder format. Note that the Iseries is in EBCIDIC, so the XML needs to be translacted to ASCII for GZIP to be run against it.
The ASCII file to be GZIP'd needs to be in ASCII in a 64 bit encoded version.
Once the XML is built, then it needs to be GZIP'd to compress it and convert it to binary.
GZIP is a freeware product that you can down load from the web. Version 1.3.12 works for the Navigo application. You can get it from http://gnuwin32.sourceforge.net/packages/gzip.htmor http://www.gzip.org/ . Some versions of Gzip do not pack the data in a format that the mobile unit can unpack properly.
The XML packet you send to the GZIP product should have all the white space removed before GZIP'ing it, if you don't, then the spaces are included as part of the GZIP'd packet, and takes up space on the OV unit when it is unzipped.
The largest GZIP'd record that can be sent at one time is 1454 bytes
The largest XML packet that can be sent at one time is 16K.
If being sent, the Longitude must be sent before the Latitude. Long/Lat is in Degrees seconds format.
Navigo does not do Preplanned dispatches. It only has 1 dispatch on it at a time, although you can append multiple packets to it as long as it's the same dispatch.
We recommend you set the GenerateRoute to No, so that the driver can select the segments that he wants to have routed. Each route segment is sent to MapTuit and back to the unit. This help cut down traffic if not needed.
We recommend that you send the address information for each stop, giving the driver the address information. Send the Long/Lat if you can, as that also saves traffic to MapTuit. MapTuit processes each address, unless the long/lat is sent, and askes the dirver to select the correct stop, if there are multiples.
Contact Info, Telephone, Notes, and Early/Late time windows are just informational, and are probably part of the load assignment macro, and don't need to be sent.
If the XML packet, or the GZIP'd packet exceed the size limits, you need to properly close the XML, omitting stops, and send that one, then create a new packet, omitting the stops you've already sent, using a <Append>Yes</Append> xml code between the AddDispatch and the Dispatch tags.

Below is an example of a XML packet:

<?xml version="1.0" ?>
<NaviGo>
    <AddDispatch>
        <SetActive>Yes</SetActive>
        <GenerateRoute>No</GenerateRoute>
        <Dispatch>
            <Id>003643738</Id>
            <Name>NaviGo & Omnitracs Hardware Delivery</Name>
            <Stop>
                <Id>00</Id>
                <Name>Mobile Devices R Us</Name>
                <Type>PickUp</Type>
                <Coordinate>
                    <Longitude>-71.601003</Longitude>
                    <Latitude>42.543096</Latitude>
                    <StreetName>Main St</StreetName>
                </Coordinate>
                <ContactInfo>
                    <Name>Joe Smith</Name>
                    <Telephone>720-842-4800</Telephone>
                </ContactInfo>
                <Notes>Stop at gate B and call the contact.</Notes>
                <Window>
                    <EarlyTime>2007-02-09 13:00</EarlyTime>
                    <LateTime>2007-02-09 15:15</LateTime>
                </Window>
            </Stop>
            <Stop>
                <Id>01</Id>
                <Name>Tucumcari Flying J</Name>
                <Type>Fuel</Type>
                <CustomerCode>FlyingJ123</CustomerCode>
            </Stop>
            <Stop>
                <Id>299</Id>
                <Name>Harbourfront</Name>
                <Type>Delivery</Type>
                <Address>
                    <Street>1 York Street</Street>
                    <City>Toronto</City>
                    <Region>ON</Region>
                    <Country>CA</Country>
                </Address>
            </Stop>
            <Stop>
                <Id>399</Id>
                <Name>Maptuit Corporation</Name>
                <Type>Delivery</Type>
                <Address>
                    <Street>133 King St E</Street>
                    <City>Toronto</City>
                    <Region>ON</Region>
                    <Country>CA</Country>
                </Address>
                <CustomerCode>Maptuit Corporation Toronto</CustomerCode>
                <Coordinate>
                    <Longitude>-79.37295</Longitude>
                    <Latitude>43.65023</Latitude>
                    <StreetName>King St E</StreetName>
                </Coordinate>
                <ContactInfo>
                    <Telephone>720-842-4800</Telephone>
                </ContactInfo>
                <Notes>Call in advance if arriving outside the window. </Notes>
                <Window>
                    <EarlyTime>2007-02-11 09:00</EarlyTime>
                    <LateTime>2007-02-11 11:30</LateTime>
                </Window>
            </Stop>
        </Dispatch>
    </AddDispatch>
</NaviGo>

Portal Specific Information

https://intinfo.omnitracs.com/display/iWebInt/Send+Binary+Message

sendBinaryMessage

This web service is used to create a forward binary message and queue it for transmission to a list of destinations (addressees). A global message handle is returned. Transactions indicating the disposition of transmitted messages will be available through ESS.

int sendBinaryMessage(String addressees, boolean returnReceipt, int priority, int virtualChannel, byte[] body) throws WSException

addressees

Vehicle or List

comma delimited string containing the addressees (destinations) of the message. The addressees may be vehicles, groups of vehicles, indirect users, indirect groups of users or any combination thereof. A single message may be addressed to up to 20 addressees. If the addressee is indirect, attach the '@" symbol in front of the addressee.

SCACs

SCAC/Vehicle ID's are supported. Valid SCAC/Vehicle ID format is:

SCAC|Vehicle ID - send the message to the specified vehicle

Fleetwide

Possible values - *ALLVEH

Sends a message to all vehicles

returnReceipt a boolean that when set to true indicates that a notification indicating that the message has been read should be returned through ESS.

priority an integer indicating the priority of the forward message.

0	Normal
1	Important
2	Sleepy
3	Sleepy + Important
5	Attention
9	Emergency

virtualChannel an integer indicating the virtual channel over which the message body will be sent. The valid range is 3, and 322 - 999.

body The body of the binary message is a byte array that may contain up to 4,000 elements.

Message Body Form

The body of the binary message is a byte array. The body may consist of XML, text, a comma delimited string or an array of bytes with the underlying meaning of the data at the bit level where each byte does not have to represent a specific character. The sender has the ultimate in flexibility when it comes to what can be sent via the body of the binary message. This message will not be modified in any way by the host and will just be passed along to the mobile.

Please note that the binary message data is defined in the WSDL as XML data type xsd:base64Binary. You will need to employ a base64Binary encoder to translate the ASCII or Unicode binary message being sent. Some platforms have built-in functions to do this. .NET and Java are such examples. Other platforms will require you download and use a library containing the base64Binary encoder. A Google search for your platform with the term "base64 encoder" will likely show several freely available algorithms for encoding base64Binary data. The algorithm is well defined and rather simple to replicate.

Exceptions

002 Required field not specified.
003 Company not authorized for access through integration.
004 User is not authorized.
005 Destination must be specified.
006 Message body cannot be empty.
007 Invalid Return receipt.
008 Invalid priority specified.
009 User is not authorized to send attention messages.
010 User is not authorized to send emergency messages.
011 Invalid virtual channel specified.
012 User is not authorized to send messages to all vehicles.
013 Invalid destination.
014 Destination not found.
015 Wildcard destination cannot be indirect.
016 Only one destination allowed when there is a wildcard destination.
017 Destination is an auxiliary vehicle but QMASS is not turned on.
018 Destination must be a vehicle or indirect to a vehicle.
019 Maximum of 20 destinations may be specified.
020 User is not authorized to send OTA binary messages.
021 Message body exceeds allowable line limit.
022 Failure sending message. A specific reason will be returned to the client for message failure.

Sample sendBinaryMessage Request:

<soap:Body>
    <sendBinaryMessage
        xmlns="http://websvcs.qtracswebws">
        <addressees
            xmlns="">TESTUNIT
        </addressees>
        <returnReceipt
            xmlns="">false
        </returnReceipt>
        <priority
            xmlns="">2
        </priority>
        <virtualChannel
            xmlns="">322
        </virtualChannel>
        <body
            xmlns="">SGVsbG8gV29ybGQh
        </body>
    </sendBinaryMessage>
</soap:Body>

Sample sendBinaryMessage Response:

<soapenv:Body>
    <p861:sendBinaryMessageResponse xmlns 861="http://websvcs.qtracswebws">
        <sendBinaryMessageReturn>37325</sendBinaryMessageReturn>
    </p861:sendBinaryMessageResponse>
</soapenv:Body>

Iseries Specific Information

The GZIP original and GZIP'd files recide on the IFS.
When you create the IFS file that is to contain the XML file, create it with CCSID code 1252, then close it, and reopen it with TEXTDATA code page (we recommend using Scott Klement's freeware for IFS). This will cause the ASCII/EBCDIC conversion for you. The GZIP requires this conversion to work properly.
Refer to the Qtracs/400 Tech. manual for the specifics on creating the message, but below is an example.

CMBLOK DS

CMSNDR 1 10 Inz('NAVIGO')

CMSNDT 11 11 Inz(' ')

CMRCNT 12 13P 0 Inz(0)

CML 14 233 DIM(20)

CMTTTX 234 235P 0 Inz(0)

CMPRIO 236 236 Inz('2')

CMOFPK 237 237 Inz('0')

CMRRCP 238 238 Inz('0')

CMWRAP 239 239 Inz('0')

CMRPLY 240 249 Inz('*DISPATCH')

CMMAC# 250 251P 0 Inz(322)

CMVER# 252 253P 0 Inz(0)

CMLMH 254 263 Inz(' ')

CMRSVD 264 270 Inz(' ')

CMBTIN 271 271 Inz('B')

CMBLEN 272 274P 0

CMBODY 275 4174

DMBLOK DS

DMGMH 1 5P 0

DMBORN 6 12P 0

DMOFPK 13 13

DMSTTS 14 14

DMREAS 15 18

DMRCNT 19 21P 0

C Eval CmBody = %Trim(GZIP_Data)

C Eval CmBlen = %Len(%Trim(CmBody))

C Eval CML(1) = 'TESTUNIT'

* OMCRTMSG - Create & Send Message

C Call 'OMCRTMSG'

C Parm CMBLOK

C Parm DMBLOK

The above example uses an application "NAVIGO" that needs to be defined on your Iseries in Qtracs, and linked to your binary channel 322.

The GZIP_Data is the data retrieved from the IFS GZIP'd file.

The type of message is set to "B" for Binary, and the macro is set to 322 for binary channel 322 which is used for NaviGo Dispatch.

Download Documents -

Add Dispatch: APIAddDispatch.doc

NaviGo Deamon API: CUST_navigoAPI2.pdf

Here are some interesting things about...