Sample SOAP Packet

Here is an example packet sent from DataGate when push to web service is enabled:

POST /test HTTP/1.1
Host: www.example.com:80
Content-Type: text/xml; charset=utf-8
Content-Length: xxx
SOAPAction: "http://www.datalinksystemsinc.com/datagate1/AssetEventNotification"
Connection: close

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Header>
 <DataGateHeader xmlns="http://www.datalinksystemsinc.com/datagate1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.datalinksystemsinc.com/datagate1 http://www.datalinksystemsinc.com/datagate1.xsd" Company="Datalink Systems, Inc." AppVersion="6.8.9" AppName="DataGate Plus" Version="1.0" Pwd="test" UserID="test"/>
</soap:Header>
<soap:Body>
 <AssetEventNotification xmlns="http://www.datalinksystemsinc.com/datagate1">
  <Events>
   <AssetEvent objectID="6517927010000-7">
    <AssetDescription>Mobius</AssetDescription>
    <AssetID>0.0.1</AssetID>
    <RXTime>2020-08-26T21:31:41Z</RXTime>
    <GMTTime>2020-08-26T21:31:41Z</GMTTime>
    <Network>7</Network>
    <Priority>normal</Priority>
  <GPS>
   <Valid>false</Valid>
   <Latitude>34.18937</Latitude>
   <Longitude>-103.595</Longitude>
  </GPS>
    <Telemetry>
   <Speed units="mph">35</Speed>
   <Heading>285</Heading>
     <DigitalIO>
      <IGN>low</IGN>
      <Input1>low</Input1>
      <Output1>low</Output1>
     </DigitalIO>
    </Telemetry>
    <Event>
     <Number>3000</Number>
     <Description>Version 1</Description>
    </Event>
   </AssetEvent>
  </Events>
  <TransID>651792756</TransID>
 </AssetEventNotification>
</soap:Body>
</soap:Envelope>

The following example shows an XML polling request sent to DataGate, and its responses. Each request must include a SOAP header with DataGateRequestHeader element. Responses will contain a DataGateResponseHeader element.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<DataGateRequestHeader xmlns="http://www.datalinksystemsinc.com/Version_1.0" 
 User="user" Password="pass"/>
</soap:Header>
<soap:Body>
<GetAssetList xmlns="http://www.datalinksystemsinc.com/Version_1.0"/>
</soap:Body>
</soap:Envelope>

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<DataGateResponseHeader xmlns="http://www.datalinksystemsinc.com/Version_1.0" Company="Datalink Systems, Inc." AppVer="6.1.10" AppName="DataGate" Version="1.0" Sequence="19" Instance="123"/>
</soap:Header>
<soap:Body>
<GetAssetListResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
 <Assets>
  <Asset>
   <AssetID>1</AssetID>
   <Name>Example</Name>
   <Sequence>1</Sequence>
  </Asset>
...
 </Assets>
</GetAssetListResponse>
</soap:Body>
</soap:Envelope>

The following examples show the SOAP body elements used in requests and responses.

Use the Ping method to check server operation:

<Ping xmlns="http://www.datalinksystemsinc.com/Version_1.0"/>
<PingResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
  <State>OK</State>
</PingResponse>

GetMethods returns a list of supported methods:

<GetMethods xmlns="http://www.datalinksystemsinc.com/Version_1.0"/>
<GetMethodsResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
 <Methods>
<string>Ping</string>
<string>GetMethods</string>
<string>GetAssetList</string>
<string>GetRecentPositions</string>
<string>GetInbox</string>
<string>GetSent</string>
<string>DeleteMessages</string>
<string>GetOutbox</string>
<string>DeleteOutboxMessage</string>
<string>SendMessage</string>
 </Methods>
</GetMethodsResponse>

Use GetAssetList to obtain information on all supported assets:

 <GetAssetList xmlns="http://www.datalinksystemsinc.com/Version_1.0"/>
 <GetAssetListResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
 <Assets>
 <Asset>
 <AssetID>123</AssetID>
 <Name>Example</Name>
 <RadioID>U00001</RadioID>
 <Sequence>19</Sequence>
 <Network>Kenwood</Network>
 <LastReportTime>2016-07-14T13:55:02Z</LastReportTime>
</Asset>
...
</Assets>"
</GetAssetListResponse>

GetRecentPositions returns positions from all assets that have sent something since the Sequence value provided. It is expected that a client will use the Sequence and Instance values returned by the server (in the DataGateMsgHeader element) the last time this method was called. If the Sequence value is not entered, or Instance does not match the server’s current Instance value, all assets with positions will be returned:

<GetRecentPositions xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<Sequence>10</Sequence>
<Instance>123></Instance>
</GetRecentPositions>
<GetRecentPositionsResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<Positions>
<Position>
 <AssetID>123</AssetID>
 <Name>Example</Name>
 <Time>2016-06-10T01:30:48Z</Time>
 <Speed_MPH>0</Speed_MPH>
 <Heading>260</Heading>
 <Latitude>39.12345</Latitude>
 <Longitude>-100.42314</Longitude>
 <Valid>true</Valid>
 <Network>Kenwood</Network>
</Position>
...
</Positions>
</GetRecentPositionsResponse>

Use GetInbox to return all available messages received from assets. Provide a HistoryID value to limit the response to messages with higher HistoryID values. It is expected that the client will use the highest HistoryID value obtained in any previous call to this method:

<GetInbox xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<HistoryID>12345</HistoryID>
</GetInbox>

<GetInboxResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<InboxMessages>
<InboxMessage>
 <AssetID>123</AssetID>
 <Name>Example</Name>
 <Time>2016-05-01T23:59:49Z</Time>
 <HistoryID>12346</HistoryID>
 <Text>Message text</Text>
 <MessageID>123</MessageID>
 <Priority>High/Low</Priority>
</InboxMessage>
...
</InboxMessages>
</GetInboxResponse>

Use GetSent to return all available messages send to assets. Provide a HistoryID value to limit the response to messages with higher HistoryID values. It is expected that the client will use the highest HistoryID value obtained in any previous call to this method:

<GetSent xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<HistoryID>12345</HistoryID>
</GetSent>

<GetSentResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<SentMessages>
<SentMessage>
 <AssetID>123</AssetID>
 <Name>Example</Name>
 <Time>2016-05-02T21:39:42Z</Time>
 <HistoryID>12347</HistoryID>
 <Text>Sent Message</Text>
 <MessageID>100</MessageID>
</SentMessage>
...
</SentMessages>
</GetSentResponse>

The DeleteMessages method will delete all messages from the inbox and sent items with a HistoryID equal to or less than the provided value. It is expected that the client will delete messages periodically. The server will automatically delete older messages when the queue gets too long:

<DeleteMessages xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<HistoryID>12345</HistoryID>
</DeleteMessages>

<DeleteMessagesResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<State>OK</State>
</DeleteMessagesResponse>

Use the GetOutbox method to return a list of messages waiting to be sent to assets. The State element indicates whether the message is being sent or has failed. Once messages have been successfully sent, they will be moved to the sent messages list:

<GetOutbox xmlns="http://www.datalinksystemsinc.com/Version_1.0"/>

<GetOutboxResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<OutboxMessages>
<OutboxMessage>
 <AssetID>123</AssetID>
 <Name>Example</Name>
 <OutboxID>17</OutboxID>
 <MessageID>999</MessageID>
 <State>Sending.../Send Failed</State>
 <Text>Message to asset</Text>
</OutboxMessage>
  ...
</OutboxMessages>
</GetOutboxResponse>

The DeleteOutboxMessage method removes a message from the outbox, using the OutboxID to identify the message. Include the server’s Instance value, as this is required to uniquely identify each item in the outbox:

<DeleteOutboxMessage xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<OutboxID>17</OutboxID>
<Instance>12345</Instance>
</DeleteOutboxMessage>

<DeleteOutboxMessageResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<State>OK</State>
</DeleteOutboxMessageResponse>

Use the SendMessage method to queue a message to an asset. The AssetID value identifies the destination asset, while the Text value contains the message itself. Note that messages will be rejected if they are too long. The response will contain a State value, indicating whether the packet has been sent or is queued for delivery. Queued packets will appear in the outbox, and can be identified using the returned OutboxID value.

The optional Priority and MaxAge values are available from DataGate version 6.8.16. Priority tells DataGate how often to attempt delivery of this message to the asset. Priority 1 messages are tried one time only (using the last known network for this device). Priority 2 messages are tried once per network used by the device. Priority 3 messages (the default if value not provided) are tried three times per network before failure. Priority 4 messages are tried three times per network, and then retried with an increasing delay. Use MaxAge to limit how long a message will stay queued for delivery (in seconds, with a default of 86400).

<SendMessage xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<AssetID>123</AssetID>
<MessageID>1000</MessageID>
<Priority>3</Priority>
<MaxAge>86400</MaxAge>
<Text>Message</Text>
</SendMessage>

<SendMessageResponse xmlns="http://www.datalinksystemsinc.com/Version_1.0">
<State>Sent/Accepted</State>
<OutboxID>17</OutboxID>
</SendMessageResponse>

If any requests are unrecognised or contain invalid values, the server will return a SOAP fault similar to the following:

 HTTP/1.1 500 Internal Server Error
 ...
 <?xml version="1.0" encoding="utf-8"?>
 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
 <soap:Header>
  <DataGateHeader xmlns="http://www.datalinksystemsinc.com/Version_1.0"
   Company="Datalink Systems, Inc." AppVer="6.1.10" AppName="DataGate" Version="1.0"
   Sequence="1" Instance="521883026"/>
 </soap:Header>
 <soap:Body>
  <soap:Fault>
   <faultcode>Client</faultcode>
   <faultstring>Invalid user ID or password</faultstring>
  </soap:Fault>
 </soap:Body>
 </soap:Envelope>