Get Mobile Scanning Messages

Authorization Requirements

The credentials supplied with this method call (as specified in the accompanying WS-Security header) must be authorized to the following application(s) and their associated role-based permissions.
Required Application Licenses

In-Cab Scanning
Remote Integration

The user must also have been granted the In-Cab Scanning capability 'Can dequeue scanned documents' on the Customer portal.

Calling Interface

GetMessagesResponse getMessages (GetMessagesRequest messages) throws WSException

messages: The GetMessagesRequest encapsulates the information required to lookup Scanning generated scan data. Please note that only a maximum of 2 messages can be returned for a request.
returns GetMessagesResponse
- Messages are returned with higher priority message first, unless FromKey is used, in which case they are returned oldest message first.

GetMessagesRequest

Element	XSD Type	Description	Required
ReadState	OutgoingReadStatesType (string)	Needed to tell what Message state to use: Unread, Read, Delivered, or Failed for this lookup. If it is not provided, will return messages of any state. This can be used along with FromKey to traverse through all Unread messages sequentially. See usage of OutgoingReadStatesTypefor more information.	No
Routing	RoutingType	Contains the information about how the message was routed.	Yes
FromKey	string	Provide a way to return messages received after this message	No
StartDate	dateTime	Optional beginning time boundary	No
EndDate	dateTime	Optional ending time boundary (inclusive)	No
AutoAck	boolean	If all the messages return should be marked as acknowledged at the time they are read.	Yes
MaxMessages	int	Maximum number of messages to return (if none specified will return all). For Scanning set this to 1 or 2 maximum.	Yes
MessageAck	AckType	Tells the platform to ack/nack a previously read platform message. Allows the customer to add specific information if needed (see above)	No

Sample XML Requests

Only the SOAP body is shown. To see a sample SOAP Envelope and Header, click here.

This sample asks for a maximum of 2 Unread messages for MyTruck123 and it also tells the system to automatically mark all return messages as Read.

<soapenv:Body>

<ns:GetMessagesRequest>

<ReadState>Unread</ReadState>

<Routing>

<Source>

<Type>Vehicle</Type>

<CustomerAssignedId>MyTruck123</CustomerAssignedId>

</Source>

<Service>

<Primary>

<Id>SCAN</Id>

</Primary>

</Service>

</Routing>

<AutoAck>true</AutoAck>

<MaxMessages>2</MaxMessages>

</ns:GetMessagesRequest>

</soapenv:Body>

This sample asks for a maximum of 2 Read messages, between two dates. AutoAck is set to false, since messages have already been Read.

<soapenv:Body>

<ns:GetMessagesRequest>

<ReadState>Read</ReadState>

<Routing>

<Service>

<Primary>

<Id>SCAN</Id>

</Primary>

</Service>

</Routing>

<StartDate>2013-05-16T17:15:20.000Z</StartDate>

<EndDate>2013-05-16T17:15:25.000Z</EndDate>

<AutoAck>false</AutoAck>

<MaxMessages>2</MaxMessages>

</ns:GetMessagesRequest>

</soapenv:Body>

Asks for 2 messages starting for a specific Key it also tells the system to automatically mark all return messages as Read.

<soapenv:Body>

<ns:GetMessagesRequest>

<ReadState>Read</ReadState>

<Routing>

<Service>

<Primary>

<Id>SCAN</Id>

</Primary>

</Service>

</Routing>

<FromKey>9FF13A62-CD79-42C5-BB3B-CD003B8A4A31</FromKey>

<AutoAck>true</AutoAck>

<MaxMessages>2</MaxMessages>

</ns:GetMessagesRequest>

</soapenv:Body>

GetMessageResponseType

Element	Type	Description	Required
Message	MessageType	List of Messages. Empty if none are found.	Yes

Element

Type

Description

Required

Message

MessageType

List of Messages. Empty if none are found.

Yes

MessageType

Element	Type	Description	Required
Id	IdType	Contains the unique keys for this message for both customer and platform	Yes
Routing	RoutingType	Contains the information about how the message was routed	Yes
Payload	PayloadType	Container for actual payload in the message	Yes
AuditHistory	OutgoingAuditHistoryType	Any additional information about the creation and changes to the message	Yes
Created	dateTime	Message creation time	No

Sample XML Response

Audit History shows the various ways the message was delivered and the state changes it went through.

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

<SOAP-ENV:Body>

<msgEip:GetMessagesResponse xsi:schemaLocation="http://msg.data.eip.omnitracs.com/1.0 C:/views/integration/vordel-routing/latest/vordel-helper/vordel-external-api/src/main/resources/EIPMessage1.0.xsd" xmlns:msgEip="http://msg.data.eip.omnitracs.com/1.0" xmlns:baseEip="http://base.data.eip.omnitracs.com/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Message>

<Id>

<Key>9FF13A62-CD79-42C5-BB3B-CD003B8A4A31</Key>

<CorrelationId>8369a2b2-b668-4688-910f-1819f9aa1018</CorrelationId>

</Id>

<Routing>

<Source>

<Type>Vehicle</Type>

<SystemAssignedId>105304409</SystemAssignedId>

<CustomerAssignedId>0105304409</CustomerAssignedId>

</Source>

<Service>

<Primary>

<Id>SCAN</Id>

</Primary>

</Service>

</Routing>

<Payload>

<Length>82474</Length>

<Filename>105304409_2013-05-16_17-14-58.zip</Filename>

<Type>Binary</Type>

<Binary>abcdef</Binary>

</Payload>

<PayloadContext>

<UOMType>Omnitracs</UOMType>

</PayloadContext>

<MetaData Name="UNITADDRESS" Value="105304409"/>

<MetaData Name="DRIVERCOMMENT" Value="test1203r"/>

<MetaData Name="DOCTYPENAME" Value="Standard_200_11XX"/>

<MetaData Name="DRIVERNAME" Value="Unspecified"/>

<MetaData Name="SCANTIME" Value="2013-05-16T17:14:58"/>

<MetaData Name="BATCHID" Value="9a913727bc254d078f8b6e289b40823f"/>

<MetaData Name="TRAILERNUMBER" Value="1234"/>

<MetaData Name="DOCTYPEID" Value="0"/>

<MetaData Name="UNITACCOUNT" Value="66537472"/>

<MetaData Name="LOADNUMBER" Value="iuhf65"/>

<MetaData Name="CONFIRMATIONID" Value="970"/>

<Created>2013-05-16T17:15:21.762Z</Created>

<AuditHistory>

<Audit>

<Key>164DA626-D5DC-4BDE-BC8B-59AAFFD78EF7</Key>

<Date>2013-05-16T17:15:22.945Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Inforouter</Delivery>

<State>Processed</State>

</Distribution>

</Audit>

<Audit>

<Key>164DA626-D5DC-4BDE-BC8B-59AAFFD78EF7</Key>

<Date>2013-05-16T17:15:22.444Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Inforouter</Delivery>

<State>Received</State>

</Distribution>

</Audit>

<Audit>

<Key>164DA626-D5DC-4BDE-BC8B-59AAFFD78EF7</Key>

<Date>2013-05-16T17:15:22.346Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Inforouter</Delivery>

<State>Sent</State>

</Distribution>

</Audit>

<Audit>

<Key>5F77AF75-809F-42EA-BDB5-D960DC813C40</Key>

<Date>2013-05-16T17:15:22.716Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Ftp</Delivery>

<State>Processed</State>

</Distribution>

</Audit>

<Audit>

<Key>5F77AF75-809F-42EA-BDB5-D960DC813C40</Key>

<Date>2013-05-16T17:15:22.527Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Ftp</Delivery>

<State>Received</State>

</Distribution>

</Audit>

<Audit>

<Key>5F77AF75-809F-42EA-BDB5-D960DC813C40</Key>

<Date>2013-05-16T17:15:22.391Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Ftp</Delivery>

<State>Sent</State>

</Distribution>

</Audit>

<Audit>

<Key>D12DCE8F-D1AD-462D-809A-DAD711154C37</Key>

<Date>2013-05-16T17:15:22.359Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Dequeue</Delivery>

<State>Pending</State>

</Distribution>

</Audit>

<Audit>

<Key>D12DCE8F-D1AD-462D-809A-DAD711154C37</Key>

<Date>2013-05-16T17:15:22.311Z</Date>

<Who>Route</Who>

<Distribution>

<Delivery>Dequeue</Delivery>

<State>Sent</State>

</Distribution>

</Audit>

</AuditHistory>

</Message>

</msgEip:GetMessagesResponse>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Exceptions

0000 - There was a problem with the request, either the XML was invalid, or no soap operation was found.

0001 - Too many web service calls too quickly. Make the request later.

0002 - An Internal Error Occurred when trying to process the request. Please try again later.

0003 - Authentication Failed. Check the user credentials

0004 - Not Authorized (No Authorized Apps found)

0005 - WSSE Header Block missing or invalid

0006 - WSSE Header Username token is missing or invalid

1000 - No Data Found. Was not able to locate a required resource

1001 - Invalid Input, Something missing or incorrect in the request. Exception will indicate what the problem was.

1002 - Internal Error, some unknown error occurred. Retry later or call customer service.

1003 - Not authorized. Not authorized to use this service. Check the User Roles on the customer portal