CoPilot Messages Details

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

CoPilot
Remote Integration

The user must also have been granted the CoPilot capability 'Can dequeue CoPilot messages' on the Customer portal.

Calling Interface

GetMessagesResponse getMessages (GetMessagesRequest messages) throws WSException

messages: The GetMessagesRequest encapsulates the information required to lookup CoPilot generated messages. Please note that only a maximum of 50 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 or Read 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.	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 CoPilot set this to a value of 50 or less.	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 50 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>CPLT</Id>

</Primary>

</Service>

</Routing>

<AutoAck>true</AutoAck>

<MaxMessages>50</MaxMessages>

</ns:GetMessagesRequest>

</soapenv:Body>

This sample asks for a maximum of 50 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>CPLT</Id>

</Primary>

</Service>

</Routing>

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

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

<AutoAck>false</AutoAck>

<MaxMessages>50</MaxMessages>

</ns:GetMessagesRequest>

</soapenv:Body>

Asks for 25 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>CPLT</Id>

</Primary>

</Service>

</Routing>

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

<AutoAck>true</AutoAck>

<MaxMessages>25</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

Routing (RoutingType)

Element	Type	Description	Required
Priority	PriorityType	Denotes the level of priority (Emergency = 6, High = 5, Medium = 3, Low = 0) used in the delivery of the message	No
Destination	BaseResourceType	Reference for the recipient of the message (typically this would be Vehicle)	No
Service	ServiceType	Qualifies what service (typically an application) handled this message in the platform	Yes

Element

Type

Description

Required

Priority

PriorityType

Denotes the level of priority (Emergency = 6, High = 5, Medium = 3, Low = 0) used in the delivery of the message

No

Destination

BaseResourceType

Reference for the recipient of the message (typically this would be Vehicle)

No

Service

ServiceType

Qualifies what service (typically an application) handled this message in the platform

Yes

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>CPLT</Id>

</Primary>

</Service>

</Routing>

<Payload>

<Length>82474</Length>

<Type>Binary</Type>

<Binary>abcdef</Binary>

</Payload>

<PayloadContext>

<UOMType>Omnitracs</UOMType>

</PayloadContext>

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

<AuditHistory>

<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