Notification->GetObservations

Last updated
Save as PDF

GetObservations (Notification function)

The Notification web service includes data about a number of operations, some of which existed elsewhere and were moved here. Examples: unassigned driving and odometer jumps.

XML Request

The GetObservations function takes the following input parameters:

Parameter	Type	Optional	Description
LastObservationID	Int	Yes	Used for successive calls. Next response will include all records after the LastObservationID speicified. (Max records returned is 1000.) If not preesnt or a value of 0 is provided, the StartTime specified will be used
StartTime	dateTime	Yes	Earliest possible time (in GMT) for the first returned observation. Used if the LastObservationID is 0 or not specified
ObservationTypeFilter	List of strings	Yes	A list of strings corresponding to observation types. If omitted, all present observations are returned
ObservationType	string	Yes	A type of observation to be returned. currently supported: UNASSIGNED_DRIVING_STARTED, UNASSIGNED_DRIVING_ENDED and ODOMETER_JUMP

Notes:

One valied value of LastObservationID or StartTime needs to be present in the request.
ObservationType contents are strings and not ENUM values, which makes it easier to add new types.

  
<soapenv:Body>  
      <GetObservationsRequest>  
         <!--Optional:-->  
         <LastObservationID>int</LastObservationID>  
         <!--Optional:-->  
         <StartTime>dateTime</StartTime>  
         <!--Optional:-->  
         <ObservationTypeFilter>  
            <!--Zero or more repetitions:-->  
            <:ObservationType>string</ObservationType>  
         </ObservationTypeFilter>  
      </:GetObservationsRequest>  
   </soapenv:Body>

Note that there may be name-space related prefix with the tags, for example, <GetObservationsRequest> will show as <xyz:GetObservationsRequest>, where xyz is an abbreviation of the name-space.

XML Response

The XML response will have the following parameters

Parameter	Type	Optional	Description
Observation	object	Yes	A squence of observatinos is returned, each contains the following parameters
ObservationID	Long	No	The (unique) ID of the observation
ObservationType	String	No	The type of the observation
StartTime	dateTime	No	The start time of the observation in UTC
EndTime	dateTime	Yes	The end time of the observation in UTC. Certain observations will not have this value set
ServerProcessedTime	dateTime	No	The time that the sever processed the event that created this observation in UTC
Identifier	String	Yes	An indicator of which entity the observation is about. It varies based on the observation type
Attributes	String	Yes	A base64 encoded string that contains an XML structure containing attributes for the observation. The format of the XML varies by observation type

The following table specifies te type of Identifier and presence of EndTime for each supported observation type:

_ObservationType _	Identifier	EndTime present?
UNASSIGNED_DRIVING_STARTED	VehicleID	No
UNASSIGNED_DRIVING_ENDED	VehicleID	No
ODOMETER_JUMP	VehicleID	Yes

Attributes included in the Attributes decoded string, in order, including type and optional. Example: Lattitude (float, Y) means it is a float and optional:

ObservationType	Attribute 1	Attribute 2	Attribute 3	Attribute 4
UNASSIGNED_DRIVING_STARTED	Latitude (float, Y)	Longitude (float, Y)	Odometer (float, Y)	Co-DriverID (string, Y)
UNASSIGNED_DRIVING_ENDED	Latitude (float, Y)	Longitude (float, Y)	Odometer (float, Y)	Co-DriverID (string, Y)
ODOMETER_JUMP	UA (Int, N)	StartOdometer (Float, N)	EndOdometer (Float, N)

  
<SOAP-ENV:Body>  
      <ns3:GetObservationsResponse xmlns:ns2="http://omnitracs.com/hos/web/services/notification-data" xmlns:ns3="http://omnitracs.com/hos/web/services/notification">  
         <ns3:Observation>  
            <ns2:ObservationID>int</ns2:ObservationID>  
            <ns2:ObservationType>string</ns2:ObservationType>  
            <ns2:StartTime>dateTime</ns2:StartTime>  
            <ns2:EndTime>dateTime</ns2:EndTime>  
            <ns2:ServerProcessedTime>dateTime</ns2:ServerProcessedTime>  
            <ns2:Identifier>string</ns2:Identifier>  
            <ns2:Attributes>PE9kb21ldGVySnVtcEF0dHJpYnV0ZXM+PFVBPjEwNTMwNzc4NDwvVUE+PFN0YXJ0T2RvbWV0ZXI+MTI5MDczLjA8L1N0YXJ0T2RvbWV0ZXI+PEVuZE9kb21ldGVyPjEyOTE5MC44PC9FbmRPZG9tZXRlcj48L09kb21ldGVySnVtcEF0dHJpYnV0ZXM+</ns2:Attributes>  
         </ns3:Observation>  
         <ns3:Observation>  
            <ns2:ObservationID>int</ns2:ObservationID>  
            <ns2:ObservationType>string</ns2:ObservationType>  
            <ns2:StartTime>dateTime</ns2:StartTime>  
            <ns2:EndTime>dateTime</ns2:EndTime>  
            <ns2:ServerProcessedTime>dateTime</ns2:ServerProcessedTime>  
            <ns2:Identifier>string</ns2:Identifier>  
  
<ns2:Attributes>PE9kb21ldGVySnVtcEF0dHJpYnV0ZXM+PFVBPjEwNTMwNzc4NDwvVUE+PFN0YXJ0T2RvbWV0ZXI+MTI5MTkwLjg8L1N0YXJ0T2RvbWV0ZXI+PEVuZE9kb21ldGVyPjEyOTQ5MS40PC9FbmRPZG9tZXRlcj48L09kb21ldGVySnVtcEF0dHJpYnV0ZXM+</ns2:Attributes>  
         </ns3:Observation>  
      </ns3:GetObservationsResponse>  
   </SOAP-ENV:Body>

Decoding the base64 encoded value for the UNASSIGNED_DRIVING_STARTED observation would result in an XML like the following example (and similar for the UNASSIGNED_DRIVING_ENDED observation):

  
<UnassignedDrivingStartedAttributes>  
      <Latitude>123.23</Latitude>  
      <Longitude>123.23</Longitude>  
      <Location>5 mi SSE of San Diego, CA</Location>  
      <Odometer>103234.21</Odometer>  
      <Co-DriverID>JSMITH</Co-DriverID>  
</UnassignedDrivingStartedAttributes>

Decoding the base64 encoded value for the ODOMETER_JUMP observation would result in an XML like the following example:

  
<OdometerJumpAttributes>  
      <UA>111400.3</UA>  
      <StartOdometer>111443.2</StartOdometer>  
      <EndOdometer>5 mi SSE of San Diego, CA</EndOdometer>  
</OdometerJumpAttributes>

You can download the XSD for each observation base64 encoded value from the attachments for this page. (Tools -> Attachments)