OVDW Web Service Integration Guide

Last updated
Save as PDF

OVDW Web Service Integration Guide.

CAUTION: This interface has been deprecated in the WMC product and is will be removed in the future.

Please refer to current documentation here.

The OVDW message service supports forward messages (mobile destination) and return messages (mobile originated) via SOAP web services. Our partners implement web service clients for both services. This means Forward messaging is a push model and return messages are pull. This document represents OVDW WSDL version as of 10/20/2009. The current WSDL is located on our production servers.
OVDW Web Service Information Covered

WebService Methods
WebService Security
Forward Message Samples
Return Message Samples

OVDW Web Service Methods

OVDW supports the following message invocations

send
getMessages
getDeliveredMessages

The send method delivers a host workflow message to the mobile client.

The getMessages method retrieves responses from the mobile client that have not been delivered. Messages are queued for delivered on the OVDW message gateway until they are retrieved. An upper limit is imposed on the number of messages returned.

The getDeliveredMessages retrieves responses from the mobile client. This call enables the caller to fetch messages that may have already been delivered via getMessages. Caller specifies a date range and date type. An upper limit is imposed on the number of messages returned.

For problems generating the WSDL proxies in .NET, please download the Visual Studio 2008 project with C# example source code from here.

OVDW Web Service Security

Both forward and return message services require Username Token authentication . The WS security header element requires two nested elements, Timestamp and UsernameToken. Any other elements contained in the security element will result in a failure. Here is an example of a valid SOAP message generated from a .NET client.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"

xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<soap:Header>

<wsa:Action></wsa:Action>

<wsa:MessageID>uuid:cf120f55-2726-4193-b943-69a0e6e35257</wsa:MessageID>

<wsa:ReplyTo>

<wsa:Address>[http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous]</wsa:Address>

</wsa:ReplyTo>

<wsa:To>[https://ovdw-int.qualcommapps.com/ovdw-service/services/ovdw]</wsa:To>

<wsse:Security soap:mustUnderstand="1">

<wsu:Timestamp wsu:Id="Timestamp-e6570416-ea52-4005-815d-f5c54626ad42">

<wsu:Created>2008-07-31T17:53:00Z</wsu:Created>

<wsu:Expires>2008-07-31T17:58:00Z</wsu:Expires>

</wsu:Timestamp>

<wsse:UsernameToken

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"

wsu:Id="SecurityToken-e05c0e33-180c-42b2-b5d5-490604009ea5">

<wsse:Username>user</wsse:Username>

<wsse:Password

Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">

password

</wsse:Password>

<wsse:Nonce>8orTSg3lKUnjX1gxCHjPZQ==</wsse:Nonce>

<wsu:Created>2008-07-31T17:53:00Z</wsu:Created>

</wsse:UsernameToken>

</wsse:Security>

</soap:Header>

<soap:Body>

<send xmlns="http://service.web.ovdw.qdc.qualcomm.com/">

<arg0 xmlns="">

<acctno>33344444</acctno>

<data></data>

<seqno>8881</seqno>

<ua>105055349</ua>

</arg0>

</send>

</soap:Body>

</soap:Envelope>

Forward Message Samples

Here are sample XML soap messages for forward messaging. Note: Soap Header information has been omitted for brevity.

Inbound Message - Sent from Dispatch to OVDW Web Service

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:send xmlns:ns2="http://service.web.ovdw.qdc.qualcomm.com/">

<arg0>

<acctno>33344444</acctno>

<data><datum name="msgType" value="clearTripPlan"</datum></data>

<seqno>1000</seqno>

<ua>105055349</ua>

</arg0>

</ns2:send>

</soap:Body>

</soap:Envelope>

Sample Un-encoded Payload - New Trip Plan

The following can be placed in the <data> block and sent to a test unit that is running the reference application for Driver WorkFlow on the MAS.

<data id="D_MOCK_TRIP_PLAN_1">

<datum name="msgType" value="tripPlan" />

<datum name="planId" value="172342345"/>

<data id="D_TRIP_PLAN_1_DEST1">

<datum name="destId" value="1756"/>

<datum name="id" value="2" />

<datum name="destination" value="Long Beach Industries" />

<datum name="address" value="2250 Kettner Drive" />

<datum name="destinationType" value="pickup" />

<datum name="active" value="true" />

<datum name="comments" value="Show pickup icon" />

<datum name="latitude" value="33.961337" />

<datum name="longitude" value="-118.02725" />

<datum name="status" value="new"/>

<data id="D_TRIP_PLAN_1_RULE">

<datum name="subType" value="lbsRule" />

<datum name="arriveDistanceFeet" value="50" />

<datum name="arriveIdleTimeMinutes" value="50" />

<datum name="departDistanceFeet" value="50" />

<datum name="arriveIgnitionOffMandatory" value="true" />

</data>

<data id="D_TRIP_PLAN_1_DEST2">

<datum name="destId" value="1755"/>

<datum name="id" value="11" />

<datum name="destination" value="Flying j- Escondido" />

<datum name="address" value="I-15, Exit 78" />

<datum name="destinationType" value="fuelstop" />

<datum name="comments" value="Show fuel icon" />

<datum name="latitude" value="40.00" />

<datum name="longitude" value="-100.00" />

<data id="D_TRIP_PLAN_2_RULE">

<datum name="subType" value="lbsRule" />

<datum name="arriveDistanceFeet" value="100" />

<datum name="departDistanceFeet" value="100" />

</data>

Sample Un-encoded Payload - Add Destination (Stop) to Trip Plan

The following can be Base64 encoded and placed in the <payload> and send to a test unit that is running the reference application for Driver WorkFlow on the MAS. It will add the stop to the above trip plan. If a trip plan with a different planId is already on the device, and error response return message will be received.

<data id="D_MOCK_TRIP_PLAN_1_ADD">

<datum name="type" value="addStop" />

<datum name="planId" value="172342345"/>

<data id="D_TRIP_PLAN_1_DEST7">

<datum name="destId" value="1795"/>

<datum name="id" value="11.75" />

<datum name="destination" value="New Dest 7 after Dest 5" />

<datum name="address" value="2250 Kettner Drive" />

<datum name="destinationType" value="pickup" />

<datum name="active" value="true" />

<datum name="comments" value="Show pickup icon" />

<datum name="latitude" value="33.961337" />

<datum name="longitude" value="-118.02725" />

<datum name="status" value="new"/>

<data id="D_TRIP_PLAN_1_DEST7_RULE">

<datum name="subType" value="lbsRule" />

<datum name="arriveDistanceFeet" value="50" />

<datum name="arriveIdleTimeMinutes" value="50" />

<datum name="departDistanceFeet" value="50" />

<datum name="arriveIgnitionOffMandatory" value="true" />

</data>

<data/>

Sample Un-encoded Payload - Clear Trip Plan

The following can be Base64 encoded and placed in the <payload> and send to a test unit. It will clear any currently available trip plan from the device.

<data id="D_MOCK_TRIP_PLAN_CLEAR_MSG">

<datum name="type" value="clearTripPlan"/>

</data>

Sample Un-encoded Payload - Clear Pre-Plan

The following can be Base64 encoded and placed in the <payload> and send to a test unit. It will clear any currently available pre-plan from the device.

<data id="D_MOCK_PRE_PLAN_CLEAR_MSG">

<datum name="type" value="clearPrePlan"/>

</data>

Outbound Message

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns1:sendResponse xmlns:ns1="http://service.web.ovdw.qdc.qualcomm.com/">

<return>

<message>okay</message>

</return>

</ns1:sendResponse>

</soap:Body>

</soap:Envelope>

Return Message Samples

Here are sample XML soap messages for return messaging. Note: Soap Header information has been omitted for brevity. See security section for details on the soap header.

Service Request Message - Request Messages From the Web Service

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns2:getMessages xmlns:ns2="http://service.web.ovdw.qdc.qualcomm.com/">

<arg0>30418944</arg0>

</ns2:getMessages>

</soap:Body>

</soap:Envelope>

Service Reponse Message - MCP100 or MCP200 Mobile Message Delivery Confirmation Receipt

NOTE: That <lat> and <lon> values are provided as 1/30th of a second values. To get the number of seconds, divide by 30. To get the number of minutes, divide by 30*60=1800. To get the number of degrees, divide by 30*60*60=108000.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>

<ns1:getMessagesResponse xmlns:ns1="http://service.web.ovdw.qdc.qualcomm.com/">

<return>

<notifications>

<fmc>

<svc_params>

<ua>105055349</ua>

<ident>

<gmn>1080272189</gmn>

<gid>

<source_ ua>

61476864

</source_ua>

<sequence_num>1080272189</sequence_num>

<virtual_channel>100</virtual_channel>

<direction>0</direction>

<priority>2</priority>

<service>2</service>

</gid>

</ident>

<status>9</status>

</svc_params>

<svc_data>

<msg_create>

<pos>

<valid>0</valid>

<pos_type>

0

</pos_type>

<ignition>0</ignition>

<age>0</age>

<speed>0</speed>

<trip_status>0</trip_status>

<direction>0</direction>

<pos_time>1970-01-01T00: 00:00.0Z</pos_time>

<geo>

<lat>0</lat>

<lon>0</lon>

</geo>

</pos>

<time>2008-07-16T21:41:28.0Z</time>

</msg_create>

<msg_transmit>

<pos>

<valid>0</valid>

<pos_type>0</pos_type>

<ignition>0</ignition>

<age>0</age>

<speed>0</speed>

<trip_status>0</trip_status>

<direction>0</direction>

< geo>

<lat>0</lat>

<lon>0</lon>

</geo>

</pos>

<time>1970-01-01T00:00:00.0Z</time>

</msg_transmit>

</svc_data>

</fmc>

</notifications>

<responses>

<seqno>12</seqno>

<status>0</status>

<payload>

<ack>

<status>0</status>

<status_str></status_str>

<svc_params>

<ua>105055349</ua>

<ident>

<gmn>1080272189</gmn>

<gid>

<source_ua>61476864</source_ua>

<sequence_num>1080272189</sequence_num>

<virtual_channel>100</virtual_channel>

<dire ction>

0

</direction>

<priority>2</priority>

<service>2</service>

</gid>

</ident>

</svc_params>

</ack>

</payload>

</responses>

</return>

</ns1:getMessagesResponse>

</soap:Body>

</soap:Envelope>

Service Response Message - Workflow Return Message with Workflow Data

This message is a sample of what is received when a message is delivered with Driver Workflow data contained in the message.

<soap:Body>

<ns1:getMessagesResponse xmlns:ns1="http://service.web.ovdw.qdc.qualcomm.com/">

<return>

<notifications>

<!-- DATA PAYLOAD DECODED HERE

Contents will match the message formats shown in the sample messages -->

<data gmn="2456825218">

<datum value="arrived" name="msgType"/>

<datum value="5654659" name="planId"/>

<datum value="D01" name="destId"/>

<datum value="DAN" name="currentDriver"/>

<datum value="30811.75" name="totalFuel"/>

<datum value="true" name="inMotionUIEnabled"/>

<datum value="34015745" name="trailerID"/>

<datum value="0190020.9" name="lifeToDateDistance"/>

<datum value="158.875" name="parkedIdleFuel"/>

<datum value="false" name="ignition"/>

<datum value="0190020.9 MI" name="lifeToDateDistanceDisplayValue"/>

<datum value="190020.9" name="odometer"/>

<datum value="14.875" name="ptoFuel"/>

</data>

<notification>

<return_msg>

<svc_params>

<ua>105016927</ua>

<virtual_channel>100</virtual_channel>

<ident>

<gmn>2456825218</gmn>

<gid>

<source_ua>105016927</source_ua>

<sequence_num>674775671</sequence_num>

<virtual_channel>100</virtual_channel>

<direction>1</direction>

<priority>2</priority>

<service>2</service>

</gid>

</ident>

</svc_params>

<svc_data>

<msg_create>

<pos>

<valid>1</valid>

<pos_type>

3

</pos_type>

<ignition>2</ignition>

<age>0</age>

<speed>0</speed>

<trip_status>

0

</trip_status>

<direction>9</direction>

<pos_time>2009-06-10T22:48:27.0Z</pos_time>

<geo>

<lat>4289920</lat>

<lon>-9741935</lon>

</geo>

</pos>

<time>2009-06-10T22:48:32.0Z</time>

</msg_create>

<msg_transmit>

<pos>

<valid>1</valid>

<pos_type>3</pos_type>

<ignition>

2

</ignition>

<age>0</age>

<speed>0</speed>

<trip_status>0</trip_status>

<direction>9</direction>

<pos_time>2009-06-10T22:48:37.0Z</pos_time>

<geo>

<lat>4289920</lat>

<lon>-9741935</lon>

</geo>

</pos>

<time>2009-06-10T22:48:42.0Z</time>

</msg_transmit>

<app_payload>

<length>

305

</length>

<binary>

789C8D925F4BC33014C5B <purposely truncated

</binary>

</app_payload>

</svc_data>

</return_msg>

</notification>

</notifications>

</return>

</ns1:getMessagesResponse>

</soap:Body>