Developer s Guide. Trimble SOAP Web Services

Transcription

1 Developer s Guide Trimble SOAP Web Services

2 SOAPWebSrvDG-Oct October Copyright 2017, Trimble Inc. All rights reserved. Trimble and the Globe & Triangle logo are trademarks of Trimble Inc. registered in the United States Patent and Trademark Office and other countries. TrimWeb and TrimView are trademarks of Trimble Inc. GeoManager is a service mark of Trimble Inc. All other trademarks are the property of their respective owners. Trimble reserves the right to make changes at any time, in order to improve the reliability, function or design of its devices, products or services and to supply the best devices, products and services possible. Trimble devices, products and services are protected under one or more of the following U.S. Patents: 5,477,228; 5,694,594; 5,959,577; 5,990,827; 6,459,988; 6,529,159; 6,552,682; 6,594,576; 6,664,922; 6,578,005; 5,963,911; 6,862,524; 6,795,017; 6,882,313; 6,867,733; 6,832,140; 6,922,566 and numerous other patents and patents pending in jurisdictions worldwide. Trimble does not represent that the devices, products or services shown or described herein are free from patent infringement or from any other third party right. Trimble assumes no obligation to correct any errors contained herein or to advise any user of liability for the accuracy or correctness of any engineering software support or assistance provided to a user. The Trimble devices, products and services are dependent on the coverage and calling areas of wireless networks owned and operated by third parties. Coverage and calling areas are approximate and may not cover significant portions of the United States. Actual coverage and operation of the devices, products and services depend on a variety of factors, including without limitation: system availability and capacity; system and equipment upgrades, repairs, maintenance, modifications and relocation; user equipment; terrain; signal strength; structural conditions; weather and atmospheric conditions; availability of power; governmental regulations; suspected fraudulent activities; acts of God and other conditions beyond the reasonable control of Trimble. Trimble will not be responsible for limits in coverage or performance degradation due to any such conditions. The user acknowledges that coverage and calling areas may be interrupted, halted or curtailed or the quality of the transmission may be diminished at any time. The devices, products and services are dependent upon the availability of the Internet, which is owned and operated by and accessed through third parties. Trimble assumes no responsibility for improper storage of data or information, or delivery of messages. The user assumes the entire risk in downloading or otherwise accessing any data, information, files or other materials obtained from the Trimble web site, even if the user has paid for or otherwise been provided virus protection services from Trimble. The Trimble devices, products and services and any modifications, alterations, additions or changes to the devices, products or services are not fault tolerant and are not designed, manufactured or intended for use in life support, emergency, mission-critical or other ultrahazardous activities ( High Risk Activities ). Trimble specifically disclaims any express or implied warranty of fitness for such High Risk Activities. Use of a Trimble device, product or services in any application without the written consent of Trimble is prohibited. All customer information is governed by the Trimble Privacy Policy located on the Trimble web site Notice of Rights. All rights reserved. No part of this manual may be reproduced or transmitted in any form by any means electronically, mechanically, by photocopying, via recording or otherwise without the prior written permission of Trimble Inc. For information on getting permission for reprints, contact Corporate Communications at Trimble Inc. Notice of Liability. The information in this manual is distributed on an As Is basis, without warranty, and was current at the time of publication. While precautions have been taken in the preparation of the manual, Trimble will not have any liability to any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly by the instructions contained in this manual or by the software or hardware products described in it. Privacy and Use. This product is intended to monitor and make available information concerning the vehicle s activities. It is the customer s sole responsibility to ensure that its use complies with any applicable laws and regulations. It is the customer s responsibility to develop and communicate policies concerning use of the application prior to implementing the product. Customers are urged to consult with their own legal counsel in connection with the particular use to which the customer puts the product and the potential implications from that use. ii

3 TRIMBLE SOAP WEB SERVICES Developer s Guide Contents Chapter 1: Introduction 1 Overview... 2 Web service syntax... 2 Web service classification... 3 About this guide... 3 Target audience... 3 Chapter contents... 4 Document conventions... 5 Chapter 2: Client Integration 7 Generating client code... 8 Manually invoking a secured web service from.net... 8 Chapter 3: Vehicle Service 11 URL Operations getvehiclelocation Request: GetVehicleLocation Response: GetVehicleLocation getclosestvehicles Request: GetClosestVehicles Response: GetClosestVehicles getdriverlocation Request: GetDriverLocation Response: GetDriverLocation getemployeedeviceassociations Request: GetEmployeeDeviceAssociationRequest Response: GetEmployeeDeviceAssociationResponse SOAP Faults Example Example getassociationsbyemployeeid Request: GetAssociationsByEmployeeIdRequest Response: GetEmployeeDeviceAssociationResponse SOAP Faults Example Example getassociationsbydevicelabel Request: GetAssociationsByDeviceLabelRequest Response: GetEmployeeDeviceAssociationResponse SOAP Faults Example Example getassociationsbyeffectivedate Request: GetAssociationsByEffectiveDateRequest iii

4 CONTENTS Response: GetEmployeeDeviceAssociationResponse SOAP Faults Example Example createdeviceshiftdefinition Request: CreateDeviceShiftDefinitionRequest Response: CreateDeviceShiftDefinitionResponse SOAP Faults Example Example Example Chapter 4: Landmark Service 55 URL Operations createlandmarks Request: CreateLandmarks Response CreateLandmarks editlandmarks Request: EditLandmarks Response EditLandmarks deletelandmarks Request: DeleteLandmarks Response DeleteLandmarks closestlandmarks Request: GetClosestLandmarks Response: GetClosestLandmarks getlandmarktypes Request: GetLandmarkTypes Response: GetLandmarkTypes getlandmarks Request: GetLandmarks Response: GetLandmarks Chapter 5: Employee Service 83 URL Operations createemployeeshiftdefinition Request: CreateEmployeeShiftDefinitionRequest Response: CreateEmployeeShiftDefinitionResponse SOAP Faults Example Example Example Appendix A: Authentication Error Message 93 Invalid user name or password Missing user name iv

5 TRIMBLE SOAP WEB SERVICES Developer s Guide Appendix B: Security Header Details 95 Appendix C: List of Status and Error Messages 97 Landmark Service Vehicle Service Employee Service General RBAC messages General authorization and subscription messages Appendix D: SOAP Fault Message 103 Appendix E: Call Frequency Defaults 105 Appendix F: Landmark Types 107 Appendix G: Web Service URLs 109 v

6 vi CONTENTS

7 TRIMBLE SOAP WEB SERVICES Developer s Guide Introduction 1 Welcome to the Trimble SOAP Web Services Developer s Guide. This document describes the Trimble SOAP Web Services, which make the services offered by GeoManager available through a standard HTTPS SOAP message interface. 1

8 INTRODUCTION Overview Overview The Cloud Service Architecture (CSA) enables the services that are offered by GeoManager to be made available through web services that are packaged for proxy access, aided by crossapplication configurations and data exchange. Applications can use the Trimble SOAP Web Services via a standard HTTPS SOAP message interface. This HTTPS interface is SSL-based to ensure that requests and responses are delivered in a highly secure manner. In order to safely and securely communicate with the web services, GeoManager user names and passwords must be used. Prior to issuing the SOAP message requests, web service operation authentication and authorization must be performed. If an invalid GeoManager user name is used to access a web service operation, the following XML-formatted error will be returned: <soapenv:reason> <soapenv:text xml:lang="en-us">the security token could not be authenticated or authorized; nested exception is: javax.security.auth.callback.unsupportedcallbackexception: Invalid user or password provided. a</soapenv:text> </soapenv:reason> Note: See Authentication Error Message on page 93, and List of Status and Error Messages on page 97, for a complete list of the response status codes that can be returned from web service operation calls. Note: The Trimble SOAP Web Services support the SOAP 1.2 message protocol, and WSDL version 1.1 is used to describe them. All SOAP request messages should contain the security header details. See Security Header Details on page 95. Web service syntax The URL for the web service endpoints will be of this form (where <service> is the name of one of the Trimble SOAP Web Services): See Web Service URLs on page 109 for the list of URLs for the Trimble SOAP Web Services. Service responses are returned in SOAP XML message format. Your application should use an XML parser to transform the response data into the desired format. 2

9 TRIMBLE SOAP WEB SERVICES Developer s Guide Note: The web service call syntax and parameters are case-sensitive. The web service operations raise some validation and run time errors in the form of SOAP fault messages. These messages contain a message code, along with the error message itself: <faultdetail> <messagecode>vehicle_20011</messagecode> <message>not able to resolve the Address. Invalid Address.</message> </faultdetail> Note: See SOAP Fault Message on page 103 for more details about SOAP Fault messages. Refer to List of Status and Error Messages on page 97 for a complete list of message codes and messages. Web service classification Each web service is classified according to the type of GeoManager entity that it operates upon: Vehicle Service This service retrieves automatic vehicle location information from the database. Landmark Service This service creates, maintains and deletes the landmark information that is held in the database. Employee Service This service creates employee shift definitions in the database. About this guide This guide contains reference information for the Trimble SOAP Web Services and their operations. Target audience This guide is aimed at developers who want to create client applications that use the Trimble SOAP Web Services. 3

10 INTRODUCTION About this guide Chapter contents Chapter 1: Introduction This chapter provides a brief overview of the Trimble SOAP Web Services. Chapter 2: Client Integration This chapter provides information that will aid you to write programs that use the web services. Chapter 3: Vehicle Service This chapter describes the Vehicle Service. It provides detailed reference information for each of the service s operations. Chapter 4: Landmark Service This chapter describes the Landmark Service. It provides detailed reference information for each of the service s operations. Chapter 5: Employee Service This chapter describes the Employee Service. It provides detailed reference information for each of the service s operations. Appendix A: Authentication Error Message This appendix contains details of the SOAP faults that may be raised by the web services in the event of authentication errors. Appendix B: Security Header Details This appendix contains details of the security credentials that must be present in the SOAP header of requests that are sent to the web services. Appendix C: List of Status and Error Messages This appendix contains details of the statuses, and associated messages, that are returned by many of the web service operations. Appendix D: SOAP Fault Message This appendix contains an example of the SOAP Fault message format that several of the web service operations can return. Appendix E: Call Frequency Defaults This appendix describes the limitations on how often users can send requests to the web services. Appendix F: Landmark Types This appendix lists the types of landmark that are defined within GeoManager, along with their associated numbers and colors. 4

11 TRIMBLE SOAP WEB SERVICES Developer s Guide Appendix G: Web Service URLs This appendix lists the URLs for each of the Trimble SOAP Web Services. Document conventions This guide uses the following conventions: Commands and buttons For easy recognition, User Interface (UI) features appear in bold type. For example: On the File menu, click New. Keyboard shortcuts Delete means the Delete key, or the Del key on your numeric keypad. Enter means the Enter, Return, or CR key, depending on which of these keys appears on your keyboard. Key combinations CTRL+KEY, SHIFT+KEY, and ALT+KEY are examples of key combinations. Hold down the first key in the combination and, at the same time, press the second key in the combination (designated above as KEY). For example: CTRL+C means hold the Control key down and press the letter C on your keyboard (CTRL+C is the Windows Copy command). Monospaced font indicates file paths and names, lines of code, commands, and data that you enter using your keyboard. For example: Type ls -a Monospaced, italicized font indicates variable data that you must replace with data appropriate to your current settings, environment, or task. For example, in the following URL, you would replace webserver: 5

12 6 INTRODUCTION About this guide

13 TRIMBLE SOAP WEB SERVICES Developer s Guide Client Integration 2 This chapter provides information that will help you to write programs that use the web services. 7

14 CLIENT INTEGRATION Generating client code Generating client code 1 Download the web service s WSDL file: Where <service> is the name of the web service that you want to use. See Web Service URLs on page 109 for a list of URLs for the Trimble SOAP Web Services. 2 Use one of these development environments to generate the client code: Eclipse NetBeans.Net Framework 3 Add GeoManager credentials and action parameters to the client code. See Security Header Details on page Set the request parameter values in the client code. For example, for the Landmark Service s getvehiclelocation operation the request parameters are a list of vehicle names. 5 Run the client code. The program parses the XML response message. Manually invoking a secured web service from.net 1 Download and install Web Services Enhancements (WSE) 3.0 for Microsoft.NET. At the time of writing, it can be found at this URL: By default, WSE will be installed in this location: C:\Program Files\Microsoft WSE\ 2 Use the program C:\Program Files\Microsoft WSE\v3.0\Tools\WseWsdl3.exe to generate a proxy file for the web service. For example, for the Landmark Service: WseWsdl3.exe type:webclient A file named LandmarkService.cs will be created. This is the proxy for the service. 3 Change the LandmarkService class so that it derives from Microsoft.Web.Services3.WebServicesClientProtocol 4 Write a.net client program to invoke the desired web service operations on the generated proxy. 5 In the client code, add the following lines to set the SOAP Header security credentials, before invoking the actual web service operation: LandmarkServiceSoap12 landmarkserviceproxy = new LandmarkServiceSoap12(); 8

15 TRIMBLE SOAP WEB SERVICES Developer s Guide UsernameToken ut = new UsernameToken("atroadsoftware", "atroadsoftware", PasswordOption.SendPlainText); landmarkserviceproxy.requestsoapcontext.security.tokens.add(ut);... //method invocation... 6 To compile the client and the proxy files successfully, the namespaces Microsoft.Web.Services3.Design and Microsoft.Web.Services3.Security.Tokens should be imported with the reference of Microsoft.Web.Services3.dll. 9

16 10 CLIENT INTEGRATION Manually invoking a secured web service from.net

17 TRIMBLE SOAP WEB SERVICES Developer s Guide Vehicle Service 3 This chapter describes the Vehicle Service. It provides detailed reference information for each of the service s operations. 11

18 VEHICLE SERVICE URL URL The Vehicle Service is available at this URL: Operations Name getvehiclelocation getclosestvehicles getdriverlocation getemployeedeviceassociations getassociationsbyemployeeid getassociationsbydevicelabel getassociationsbyeffectivedate createdeviceshiftdefinition Description Gets the last reported location data for a particular vehicle. Gets a list of the closest vehicles to a particular latitude and longitude, address or landmark. Gets the last reported location data for a particular driver. Returns the associations between the specified employee and mobile device that were, are, or will be effective on a particular date. Returns a list of device associations that were, are, or will be effective on a particular date, for the specified employees. Returns a list of employee associations that were, are, or will be effective on a particular date, for the specified devices. Returns the employee-device associations that were, are, or will be in effect on the specified date. Creates or updates one or more pairs of working hours, for one or more mobile devices. getvehiclelocation This operation allows an application to request the last reported location data for a particular vehicle. Vehicle location information is as accurate as the data transfer interval that has been set up for your account. If your account has been set up so that location information is transmitted from vehicles to Trimble every 15, 10, 5, or 2 minutes, then the information will be available to your application in 15, 10, 5, or 2-minute increments. 12

19 TRIMBLE SOAP WEB SERVICES Developer s Guide Note: The web service operation call syntax and parameters are case-sensitive. Request: GetVehicleLocation Parameter Datatype Value vehiclename string The labels of the mobile devices that belong to the vehicles for which you want to obtain location data. Device labels are available via the Administration tab in GeoManager. Each device label is customer-defined, and is associated with the serial number of a particular Trimble device. A maximum 100 device labels are allowed. Response: GetVehicleLocation Data Fields Datatype Value address string The house or building number and street name. crossstreet string The cross street name for the address. city string The city name for the address. region1 string Either: The state code or name for the address (if states are applicable to the country); or: The county name for the address (if counties are applicable to the country). region2 string The county name for the address (if counties are applicable to the country). zipcode string The ZIP Code for the address. country string The country name for the address. countrycode string The country code for the address. landmarkname string The customer-defined name of the landmark that is associated with the address (if this is available within your account). 13

20 VEHICLE SERVICE Operations Data Fields Datatype Value loceventtime datetime The date, time and time zone (as per your Trimble account s setup) when the vehicle s location was observed. This will be specified in the time zone for which the device has been set up. eventtime datetime The date, time and time zone when the vehicle s location was observed (in GMT). statusdetail/ statusmessage string Indicates whether or not the vehicle is moving. If it is moving, its speed and direction should be available. If the vehicle is stationary, a stationary time should be available. direction string The direction in which the vehicle is moving. speed int The vehicle s speed, in kilometers per hour. stopduration int The number of minutes during which the vehicle was in a parked state. nonreportingstatus enum The mobile device s reporting status. This is available when the vehicle is in a moving state, and will be either: WITHIN_LIMIT; or: NOT_WITHIN_LIMIT Latitude, Longitude float The latitude and longitude of the vehicle s location (in fractional degrees, with 6 decimal digits of accuracy). requestidentifier string This element is available when the current location of a particular vehicle could not be fetched from the Trimble database. It contains the mobile device label for the vehicle whose current location details could not be retrieved. statuscode,statusmessage string This indicates whether or not the request was successfully processed. The application must check this status before proceeding. See Security Header Details on page 95. Note: Due to geographic location issues, not all address fields may be available. 14

21 TRIMBLE SOAP WEB SERVICES Developer s Guide Here is an example of a GetVehicleLocationRequest SOAP message: <soap:envelope xmlns:soap=" xmlns:v1=" <soap:header xmlns:wsa=" <wsse:security xmlns:wsse=" soap:mustunderstand="1"> <wsse:usernametoken xmlns:wsu=" wsu:id="usernametoken-1"> <wsse:username>atroadsoftware</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> <wsa:action>urn:getvehiclelocation</wsa:action> </soap:header> <soap:body> <v1:getvehiclelocationrequest> <!--1 to 100 repetitions:--> <v1:vehiclename>9f111111</v1:vehiclename> <v1:vehiclename>9f000099</v1:vehiclename> <v1:vehiclename>cf000099</v1:vehiclename> </v1:getvehiclelocationrequest> </soap:body> </soap:envelope> Here is the response: <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:wsa=" <wsa:messageid>urn:uuid:c4bf3d fd </wsa:messageid> <wsa:action> getvehiclelocationresponse</wsa:action> <wsa:relatesto>urn:uuid:c4bf3d fd </wsa:relatesto> </soapenv:header> <soapenv:body> <ns5:getvehiclelocationresponse xmlns:ns5=" vehicle/v1" xmlns=" xmlns:ns2=" xmlns:ns4=" trimble.com/mrm/datatypes/vehicle/v1" xmlns:ns3=" coretypes/responsestatus/v1"> <ns5:vehiclelocationdetail> <ns4:vehiclename>9f000099</ns4:vehiclename> <ns4:location> <ns4:address> <ns2:address/> <ns2:city/> <ns2:region1>ab</ns2:region1> <ns2:zipcode>t0p</ns2:zipcode> <ns2:region2>alberta</ns2:region2> <ns2:country>canada</ns2:country> <ns2:countrycode>ca</ns2:countrycode> <ns2:coordinate> <ns2:latitude> </ns2:latitude> <ns2:longitude> </ns2:longitude> </ns2:coordinate> 15

22 VEHICLE SERVICE Operations <ns2:crossstreet/> </ns4:address> <ns4:landmark> <ns2:landmarkname/> </ns4:landmark> </ns4:location> <ns4:localeventtime> t08:55: :30</ns4:localeventtime> <ns4:eventtime> t05:25:23.000z</ns4:eventtime> <ns4:statusdetail> <ns4:statusmessage>moving</ns4:statusmessage> <ns4:direction>n</ns4:direction> <ns4:speed>14</ns4:speed> <ns4:stopduration>0</ns4:stopduration> <ns4:nonreportingstatus>within_limit</ns4:nonreportingstatus> </ns4:statusdetail> </ns5:vehiclelocationdetail> <ns5:vehiclelocationdetail> <ns4:vehiclename>9f111111</ns4:vehiclename> <ns4:location> <ns4:address> <ns2:address>6988 W CAMP WISDOM RD</ns2:address> <ns2:city>dallas</ns2:city> <ns2:region1>tx</ns2:region1> <ns2:zipcode>75236</ns2:zipcode> <ns2:region2>dallas</ns2:region2> <ns2:country>united States</ns2:country> <ns2:countrycode>us</ns2:countrycode> <ns2:coordinate> <ns2:latitude> </ns2:latitude> <ns2:longitude> </ns2:longitude> </ns2:coordinate> <ns2:crossstreet/> </ns4:address> <ns4:landmark> <ns2:landmarkname/> </ns4:landmark> </ns4:location> <ns4:localeventtime> t23:20: :00</ns4:localeventtime> <ns4:eventtime> t19:20:00.000z</ns4:eventtime> <ns4:statusdetail> <ns4:statusmessage>moving</ns4:statusmessage> <ns4:direction>n</ns4:direction> <ns4:speed>90</ns4:speed> <ns4:stopduration>0</ns4:stopduration> <ns4:nonreportingstatus>within_limit</ns4:nonreportingstatus> </ns4:statusdetail> </ns5:vehiclelocationdetail> <ns5:responsedetail> <ns3:requestidentifier>cf000099</ns3:requestidentifier> <ns3:statuscode>vehicle_20005</ns3:statuscode> <ns3:statusmessage>invalid vehicle label</ns3:statusmessage> </ns5:responsedetail> </ns5:getvehiclelocationresponse> </soapenv:body> </soapenv:envelope> 16

23 TRIMBLE SOAP WEB SERVICES Developer s Guide getclosestvehicles This operation allows an application to get a list of the closest vehicles to a particular latitude and longitude, address or landmark. The list of vehicles that is returned is sorted by distance from the vehicle to the latitude and longitude coordinates, address or landmark. The getclosestvehicles operation will perform a forward geocoding process to convert the supplied address fields to latitude and longitude coordinates. If this process is successful, the returned list of vehicles is sorted according to the distance of each vehicle from the addresses' latitudes and longitudes. To get a list of the closest vehicles to a landmark, the landmark must currently exist in the GeoManager database. If the landmark is successfully located, the returned list is sorted by distance from the vehicle to the landmark's latitude and longitude. Request: GetClosestVehicles Parameter Datatype Value landmarkid int The landmark must currently exist in the GeoManager landmark database. If the landmark is successfully located, the returned list is sorted by distance from the vehicle to the landmark's latitude and longitude. latitude float The latitude, in decimal degrees (to a maximum of six decimal places). For example: longitude float The longitude, in decimal degrees (to a maximum of six decimal places). For example: address string The house or building number and street name. for example: 420 South Irena Ave city string The city name for the address. region1 string Either: The state code or name for the address (if states are applicable to the country); or: The county name for the address (if counties are applicable to the country). region2 string The county name for the address (if counties are applicable to the country). zipcode string The ZIP Code for the address. country string The country name for the address. 17

24 VEHICLE SERVICE Operations Parameter Datatype Value countrycode string The country code for the address. range int The search radius within which to search for vehicles. The default value is 10 kilometers, and the maximum value is 200 kilometers. maxcount int This parameter controls the maximum number of vehicles that will be returned by this operation. The default value is 10, and the maximum value is 25. The order of precedence in which the request parameters are taken is: Landmark ID Latitude and longitude coordinates Address Response: GetClosestVehicles Data Fields Datatype Value vehiclelabel string The customer-defined label of the mobile device that belongs to the vehicle. distance float The distance, in kilometers, from the location specified by the latitude and longitude fields. latitude float The latitude, in decimal degrees (to a maximum of six decimal places). For example: longitude float The longitude, in decimal degrees (to a maximum of six decimal places). For example: address string The house or building number and street name. for example: 420 South Irena Ave city string The city name for the address. crossstreet string The cross street name for the address. region1 string Either: The state code or name for the address (if states are applicable to the country); or: The county name for the address (if counties are applicable to the country). 18

25 TRIMBLE SOAP WEB SERVICES Developer s Guide Data Fields Datatype Value region2 string The county name for the address (if counties are applicable to the country). zipcode string The ZIP Code for the address. country string The country name for the address. countrycode string The country code for the address. Here is an example of a GetClosestVehiclesRequest SOAP message: <soap:envelope xmlns:soap=" xmlns:v1=" trimble.com/mrm/servicetypes/vehicle/v1" xmlns:v11=" coretypes/geolocation/v1"> <soap:header/> <soap:body> <v1:getclosestvehiclesrequest> <v11:landmarkid>?</v11:landmarkid> <v1:address> <v11:address>?</v11:address> <v11:city>?</v11:city> <v11:region1>?</v11:region1> <v11:zipcode>?</v11:zipcode> <v11:region2>?</v11:region2> <v11:country>?</v11:country> <v11:countrycode>?</v11:countrycode> <v11:coordinate> <v11:latitude> </v11:latitude> <v11:longitude> </v11:longitude> <v11:altitude>?</v11:altitude> <v11:accuracy>?</v11:accuracy> </v11:coordinate> </v1:address> <v1:range>10</v1:range> <v1:maxcount>10</v1:maxcount> </v1:getclosestvehiclesrequest> </soap:body> </soap:envelope> 19

26 VEHICLE SERVICE Operations Here is the response: <soapenv:envelope xmlns:soapenv=" <soapenv:body> <ns4:getclosestvehiclesresponse xmlns=" geolocation/v1" xmlns:ns2=" xmlns:ns3=" xmlns:ns4=" servicetypes/vehicle/v1"> <ns4:closestvehicledetail> <ns3:vehiclelabel>fe001005dd</ns3:vehiclelabel> <ns3:address> <address>holland PARK ROUNDABOUT</address> <city>shepherds BUSH, GREATER LONDON</city> <region1>england</region1> <zipcode>w12 8</zipCode> <region2>london</region2> <country>gb</country> <coordinate> <latitude> </latitude> <longitude> </longitude> </coordinate> <crossstreet/> </ns3:address> <ns3:distance>0</ns3:distance> </ns4:closestvehicledetail> <ns4:closestvehicledetail> <ns3:vehiclelabel>fe001007ff</ns3:vehiclelabel> <ns3:address> <address>holland PARK ROUNDABOUT</address> <city>shepherds BUSH, GREATER LONDON</city> <region1>england</region1> <zipcode>w12 8</zipCode> <region2>london</region2> <country>gb</country> <coordinate> <latitude> </latitude> <longitude> </longitude> </coordinate> <crossstreet/> </ns3:address> <ns3:distance>0</ns3:distance> </ns4:closestvehicledetail> <ns4:closestvehicledetail> <ns3:vehiclelabel>fe001004murli</ns3:vehiclelabel> <ns3:address> <address>6 MITRE WAY</address> <city>ladbroke GROVE, GREATER LONDON</city> <region1>england</region1> <zipcode>w10 6</zipCode> <region2>london</region2> <country>gb</country> <coordinate> <latitude> </latitude> <longitude> </longitude> </coordinate> <crossstreet/> </ns3:address> 20

27 TRIMBLE SOAP WEB SERVICES Developer s Guide <ns3:distance>2.4</ns3:distance> </ns4:closestvehicledetail> <ns4:closestvehicledetail> <ns3:vehiclelabel>fe001006ee</ns3:vehiclelabel> <ns3:address> <address>6 MITRE WAY</address> <city>ladbroke GROVE, GREATER LONDON</city> <region1>england</region1> <zipcode>w10 6</zipCode> <region2>london</region2> <country>gb</country> <coordinate> <latitude> </latitude> <longitude> </longitude> </coordinate> <crossstreet/> </ns3:address> <ns3:distance>2.4</ns3:distance> </ns4:closestvehicledetail> <ns4:closestvehicledetail> <ns3:vehiclelabel>fe001002mm</ns3:vehiclelabel> <ns3:address> <address>353 EDGWARE ROAD</address> <city>st JOHNS WOOD, GREATER LONDON</city> <region1>england</region1> <zipcode>w2 1</zipCode> <region2>london</region2> <country>gb</country> <coordinate> <latitude>51.522</latitude> <longitude>-0.173</longitude> </coordinate> <crossstreet/> </ns3:address> <ns3:distance>3.6</ns3:distance> </ns4:closestvehicledetail> </ns4:getclosestvehiclesresponse> </soapenv:body> </soapenv:envelope> getdriverlocation This operation allows an application to request the last reported location data for a particular driver, and its request and response structures are similar to the getvehiclelocation operation. In order to use this operation, the specified driver must be associated with a vehicle. 21

28 VEHICLE SERVICE Operations Request: GetDriverLocation Parameter Datatype Value employeeid string The ID of the employee whose last reported location data is required. Employee id is named in the Employee/Driver Administration Link on the web account. Employee IDs can be seen in GeoManager by selecting the Administration tab and clicking View/Create/Edit Employee Details. A maximum of100 employee IDs are allowed. Response: GetDriverLocation Data Fields Datatype Value address string The house or building number and street name. crossstreet string The cross street for the address. city string The city name for the address. region1 string Either: The state code or name for the address (if states are applicable to the country); or: The county name for the address (if counties are applicable to the country). region2 string The county name for the address (if counties are applicable to the country). zipcode string The ZIP Code for the address. country string The country name for the address. countrycode string The country code for the address. landmarkname string The customer-defined name of the landmark that is associated with the address (if this is available within your account). loceventtime datetime The date, time and time zone (as per your Trimble account s setup) when the vehicle s location was observed. This will be specified in the time zone for which the device has been set up. eventtime datetime The date, time and time zone when the vehicle s location was observed (in GMT). 22

29 TRIMBLE SOAP WEB SERVICES Developer s Guide Data Fields Datatype Value statusdetail/ statusmessage string Indicates whether or not the vehicle is moving. If it is moving, its speed and direction should be available. If the vehicle is stationary, a stationary time should be available. direction string The direction in which the vehicle is moving. speed int The vehicle s speed, in kilometers per hour. stopduration int The number of minutes during which the vehicle was in a parked state. nonreportingstatus enum The mobile device s reporting status. This is available when the vehicle is in a moving state, and will be either: WITHIN_LIMIT; or: NOT_WITHIN_LIMIT Latitude, Longitude float The latitude and longitude of the vehicle s location (in fractional degrees, with 6 decimal digits of accuracy). requestidentifier string This element is available when the current location of a particular employee could not be fetched from the Trimble database. It contains the ID of the employee whose current location details could not be retrieved. statuscode,statusm essage string This indicates whether or not the request was successfully processed. The application must check this status before proceeding. See List of Status and Error Messages on page 97. Here is an example of a GetDriverLocationRequest SOAP message: <soap:envelope xmlns:soap=" xmlns:v1=" trimble.com/mrm/servicetypes/vehicle/v1"> <soap:header xmlns:wsa=" <wsse:security xmlns:wsse=" soap:mustunderstand="1"> <wsse:usernametoken xmlns:wsu=" wsu:id="usernametoken-1"> <wsse:username>atroadsoftware</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> <wsa:action>urn:getdriverlocation</wsa:action> </soap:header> <soap:body> <v1:getdriverlocationrequest> 23

30 VEHICLE SERVICE Operations <!--1 to 100 repetitions:--> <v1:employeeid>34343</v1:employeeid> <v1:employeeid>a34343</v1:employeeid> </v1:getdriverlocationrequest> </soap:body> </soap:envelope> Here is the response: <soapenv:envelope xmlns:soapenv=" <soapenv:header xmlns:wsa=" <wsa:messageid>urn:uuid:c4bf3d fd </wsa:messageid> <wsa:action> getdriverlocationresponse</wsa:action> <wsa:relatesto>urn:uuid:c4bf3d fd </wsa:relatesto> </soapenv:header> <soapenv:body> <ns5:getdriverlocationresponse xmlns:ns5=" v1" xmlns=" xmlns:ns2=" xmlns:ns4=" trimble.com/mrm/datatypes/vehicle/v1" xmlns:ns3=" coretypes/responsestatus/v1"> <ns5:employeelocation> <ns4:employeeid>34343</ns4:employeeid> <ns4:employeefirstname>john</ns4:employeefirstname> <ns4:employeelastname>williams</ns4:employeelastname> <ns4:vehiclelocation> <ns4:vehiclename>9f000066(greyhound)</ns4:vehiclename> <ns4:location> <ns4:address> <ns2:address>2974 GRASSINA ST</ns2:address> <ns2:city>san JOSE</ns2:city> <ns2:region1>ca</ns2:region1> <ns2:zipcode>95136</ns2:zipcode> <ns2:region2>santa CLARA</ns2:region2> <ns2:country>united States</ns2:country> <ns2:countrycode>us</ns2:countrycode> <ns2:coordinate> <ns2:latitude> </ns2:latitude> <ns2:longitude> </ns2:longitude> </ns2:coordinate> <ns2:crossstreet>adeline AVE</ns2:crossStreet> </ns4:address> <ns4:landmark> <ns2:landmarkname/> </ns4:landmark> </ns4:location> <ns4:localeventtime> t21:09: :30</ns4:localeventtime> <ns4:eventtime> t17:39:00.000z</ns4:eventtime> <ns4:statusdetail> <ns4:statusmessage>parked</ns4:statusmessage> <ns4:direction/> <ns4:speed/> <ns4:stopduration>210</ns4:stopduration> </ns4:statusdetail> </ns4:vehiclelocation> </ns5:employeelocation> <ns5:responsedetail> 24

31 TRIMBLE SOAP WEB SERVICES Developer s Guide <ns3:requestidentifier>a34343</ns3:requestidentifier> <ns3:statuscode>vehicle_20008</ns3:statuscode> <ns3:statusmessage>not a valid Employee ID or Device Association not found.</ ns3:statusmessage> </ns5:responsedetail> </ns5:getdriverlocationresponse> </soapenv:body> </soapenv:envelope> getemployeedeviceassociations Returns the associations between the specified active employee and mobile device that were, are, or will be effective on the specified date. The employee ID and device label that are passed in the request are checked to see whether they contain invalid characters. In order to be valid, the employee ID and device label must match this regular expression: ^[a-za-z0-9][a-za-z0-9- _\']+$ If the account for the user whose credentials are specified in the request s SOAP header has the organizational hierarchy functionality enabled, then the operation will only return the relevant associations between active employees and mobile devices that belong to the user s organizational unit. If the organizational hierarchy functionality is not enabled for the user s account, then the operation will return the relevant associations between all the active employees and mobile devices in the user s account. For each employee-device association that is successfully retrieved, the response will contain an employeedeviceassociations element that has the association s details. If there are any problems with the employee ID, device label or effective date that are sent in the request, then the response will contain an errorresponselist element for each of the errors. For details of the specific errors that can occur, see the description of the statuscode field in Response: GetEmployeeDeviceAssociationResponse on page 26. Note: Additional SOAP faults relating to the execution of the HTTP request may be raised by this operation. See SOAP Faults on page

32 VEHICLE SERVICE Operations Request: GetEmployeeDeviceAssociationRequest Parameter Datatype Value employeeid string The ID of the employee for which the employee-device associations are required. Employee IDs can be seen in GeoManager by selecting the Administration tab and clicking View/Create/Edit Employee Details. devicelabel string The customer-defined label for the mobile device for which the employee-device associations are required. Device labels can be seen by selecting the Device Management tab in GeoManager. effectivedate date The date for which you would like to see the employeedevice associations that were, are, or will be in effect. Response: GetEmployeeDeviceAssociationResponse Data Fields Datatype Value totalrecords int Not applicable for this operation. lastmodifiedtime datetime Not applicable for this operation. devicelabel string The customer-defined label for the mobile device with which the employee is associated. serialnumber string The serial number that was given to the mobile device by its manufacturer. employeeid string The ID of the employee with which the device is associated. effectivedate datetime The date and time upon which the employee-device association came, or will come, into effect. lastname string The employee s last name. firstname string The employee s first name. validuntil datetime The date and time that the employee-device association ended, or ends. If no expiry date exists for the association then this element will be empty, and its xsi:nil attribute will have the value true. requestidentifier string Not applicable for this operation. responseidentifier string Not applicable for this operation. 26

33 TRIMBLE SOAP WEB SERVICES Developer s Guide Data Fields Datatype Value statuscode string The error code for the problem that occurred. This field is present in the errorresponselist element that the response will contain in the event of an error. Possible error codes that this operation could return are: VEHICLE_20031 The specified device label consisted of invalid characters. The device label must match this regular expression: ^[a-za-z0-9][a-za-z0-9- _\']+$ VEHICLE_30002 The specified employee ID consisted of invalid characters. The employee ID must match this regular expression: ^[a-za-z0-9][a-za-z0-9- _\']+$ VEHICLE_20032 Either: The specified mobile device doesn t exist in the user s account; or: The organizational hierarchy functionality is enabled for the user s account, and the specified mobile device does not belong to the user s organizational unit. EMPLOYEE_20032 Either: The specified employee ID doesn t exist in the user s account; or: The organizational hierarchy functionality is enabled for the user s account, and the specified employee does not belong to the user s organizational unit. statusmessage string A message that describes the problem that occurred. This field is present in the errorresponselist element that the response will contain in the event of an error. The message depends upon the status code that is returned. For a list of the messages that are associated with the status codes, see List of Status and Error Messages on page

34 VEHICLE SERVICE Operations SOAP Faults In addition to the SOAP faults that are common to many of the web service operations (see Authentication Error Message on page 93), SOAP faults that contain the following details may also be raised specifically by this operation. Invalid user name A SOAP fault that contains the following details will be returned if the account for the user whose credentials are specified in the request s SOAP header has not had the Vehicle Web Service function group (and the Get Employee Device Association function within that group) enabled in GeoManager: <faultdetail> <messagecode>vehicle_20004</messagecode> <message>invalid user name</message> </faultdetail> Example 1 Here is an example of a GetEmployeeDeviceAssociationRequest message: <soap:envelope xmlns:soap=" xmlns:v1=" trimble.com/mrm/servicetypes/vehicle/v1"> <soap:header xmlns:wsa=" <wsse:security soap:mustunderstand="1" xmlns:wsse=" 2004/01/oasis wss-wssecurity-secext-1.0.xsd"> <wsse:usernametoken wsu:id="usernametoken-1" xmlns:wsu=" wss/2004/01/oasis wss-wssecurity-utility-1.0.xsd"> <wsse:username>benuser1</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> <wsa:action>urn:getemployeedeviceassociations</wsa:action> </soap:header> <soap:body> <v1:getemployeedeviceassociationrequest> <v1:employeeid>3014</v1:employeeid> <v1:devicelabel>dd349254</v1:devicelabel> <v1:effectivedate> </v1:effectivedate> </v1:getemployeedeviceassociationrequest> </soap:body> </soap:envelope> Here is the GetEmployeeDeviceAssociationResponse message that is returned: <S:Envelope xmlns:s=" <S:Header xmlns:wsa=" <wsa:messageid>urn:uuid:288aa8d1f23309c64c </wsa:messageid> <wsa:action> getemployeedeviceassociationsresponse</wsa:action> <wsa:relatesto>urn:uuid:288aa8d1f23309c64c </wsa:relatesto> </S:Header> <S:Body> <ns5:getemployeedeviceassociationresponse xmlns:ns5=" servicetypes/vehicle/v1" xmlns:ns2=" 28

35 TRIMBLE SOAP WEB SERVICES Developer s Guide businessextension/v1" xmlns=" xmlns:ns4=" xmlns:ns3=" datatypes/coretypes/responsestatus/v1" xmlns:ns6=" coretypes/shiftdefinition/v1"> <ns5:employeedeviceassociations> <ns5:devicelabel>dd349254</ns5:devicelabel> <ns5:serialnumber>dd349254</ns5:serialnumber> <ns5:employeeid>3014</ns5:employeeid> <ns5:effectivedate> t01:39:09.000</ns5:effectivedate> <ns5:lastname>newemp3</ns5:lastname> <ns5:firstname>newemp3</ns5:firstname> <ns5:validuntil xsi:nil="true" xmlns:xsi=" </ns5:employeedeviceassociations> </ns5:getemployeedeviceassociationresponse> </S:Body> </S:Envelope> Example 2 Here is an example of a request that contains an invalid employee ID: <soap:envelope xmlns:soap=" xmlns:v1=" trimble.com/mrm/servicetypes/vehicle/v1"> <soap:header xmlns:wsa=" <wsse:security soap:mustunderstand="1" xmlns:wsse=" 2004/01/oasis wss-wssecurity-secext-1.0.xsd"> <wsse:usernametoken wsu:id="usernametoken-1" xmlns:wsu=" wss/2004/01/oasis wss-wssecurity-utility-1.0.xsd"> <wsse:username>benuser1</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> <wsa:action>urn:getemployeedeviceassociations</wsa:action> </soap:header> <soap:body> <v1:getemployeedeviceassociationrequest> <v1:employeeid>9999</v1:employeeid> <v1:devicelabel>dd349254</v1:devicelabel> <v1:effectivedate> </v1:effectivedate> </v1:getemployeedeviceassociationrequest> </soap:body> </soap:envelope> Here is the response that is returned: <S:Envelope xmlns:s=" <S:Header xmlns:wsa=" <wsa:messageid>urn:uuid:e4e3f2a0e2926ee39c </wsa:messageid> <wsa:action> getemployeedeviceassociationsresponse</wsa:action> <wsa:relatesto>urn:uuid:e4e3f2a0e2926ee39c </wsa:relatesto> </S:Header> <S:Body> <ns5:getemployeedeviceassociationresponse xmlns:ns5=" servicetypes/vehicle/v1" xmlns:ns2=" businessextension/v1" xmlns=" 29

36 VEHICLE SERVICE Operations xmlns:ns4=" xmlns:ns3=" datatypes/coretypes/responsestatus/v1" xmlns:ns6=" coretypes/shiftdefinition/v1"> <ns5:errorresponselist> <ns3:responseidentifier>dd349254</ns3:responseidentifier> <ns3:statuscode>employee_20032</ns3:statuscode> <ns3:statusmessage>employee does not belong to the user</ns3:statusmessage> </ns5:errorresponselist> </ns5:getemployeedeviceassociationresponse> </S:Body> </S:Envelope> getassociationsbyemployeeid Returns a list of device associations that were, are, or will be effective on a particular date, for up to 25 specified employees. The employee IDs that were passed in the request are checked to see whether they contain invalid characters. In order to be valid, the employee IDs must match this regular expression: ^[a-za-z0-9][a-za-z0-9- _\']+$ If the account for the user whose credentials are specified in the request s SOAP header has the organizational hierarchy functionality enabled, then the operation will only return the device associations for employees that belong to the user s organizational unit. For each employee-device association that is successfully retrieved, the response will contain an employeedeviceassociations element that has the association s details. If there are problems with any of the employee IDs or the effective date that are sent in the request, then the service will carry on processing the rest of the request, and the response will contain an errorresponselist element for each of the errors that was encountered. For details of the specific errors that can occur, see the description of the statuscode field in Response: GetEmployeeDeviceAssociationResponse on page 26. Note: Additional SOAP faults relating to the execution of the HTTP request may be raised by this operation. See SOAP Faults on page