Astus API A ST US COMMUN I CATION P LAT FORM M AY

Transcription

1 Astus API ASTUS COMMUNICATION PLATFORM M AY

2 Available technologies WEB SERVICES DATA EXPORTER PUSH SERVICES PULL SERVICES Get / change any information Export odometers and engine time daily Export any event from devices in real time Import any event from your system in real time 2

3 Information Explications Customer name Registration Please provide the following information to gain access to the platform (See next page) Customer contact Dev company name Dev company contact Project summary Name, phone, Name, phone, Service needed Languages you re using WebServices, DataExporter, PUSH, PULL C#, Java, Javascript, 3

4 Contact Us Create an account Problem using the service New development Any other question 4

5 Astus Web Services GET / CHANGE ANY INFORMATION 5

6 Authentication Service This service validates username and password. It opens a session and returns a token. Use that token in subsequent calls. Static Data Service Use this service to get any configured entity in Astus: vehicles, drivers, locations, territories, Authentication Static Description Astus Web Services (AWS) allow you to get or change any information in Astus, from your system. Information is kept more than 2 years. You can t use AWS in a browser, you must create a custom application. If you don t have access to a dev team, contact us, we might be to help you in your project. Technologies : XML, SOAP and WSDL Report Service Generate any report available in Astus. History Service Get trip events information. (Depricated, please use Report Service) Realtime State Get the latest information available in Astus. Position, speed, accessories, exceptions, availability, custome state, Task Service Get and send new task for users. Command Service Get predefined commands and send them to the modules. Key Service Define/delete reservations for your a vehicle, key and specific time. Report Event State Task Command Key Get the WSDL by adding?wsdl at the end of each links: 6

7 Here s some samples to get you started Download full version with calls to every services C#, Visual Studio 2010 Identification First get a token by calling AuthenticationService.OpenSession and providing your username and password. The token is valid for 60 minutes after your last call. For security purposes, always call CloseSession when your done. Sessions will automatically be closed if no activity is detected. Download small version that calls Trip report C#, Visual Studio 2015 Here s an XML of OpenSession POST HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: " Host: astus.com Content-Length: 424 Expect: 100-continue Connection: Keep-Alive <s:envelope xmlns:s=" <s:body xmlns:xsi=" xmlns:xsd=" <OpenSession xmlns=" <OpenSessionRequest xmlns=" <Username>UUU</Username><Password>PPP</Password> </OpenSessionRequest> </OpenSession> </s:body> </s:envelope> 7

8 Here s an XML sample for GetVehicle POST HTTP/1.1 Content-Type: text/xml; charset=utf-8 SOAPAction: " Host: astus.com Content-Length: 756 Expect: 100-continue Subsequent calls You must pass the token for each subsequent calls. An exception will be thrown if the token is missing. <s:envelope xmlns:s=" <s:body xmlns:xsi=" xmlns:xsd=" <GetVehicles xmlns=" <AuthenticatedRequest xmlns=" <UnsafeToken> <Value>TTT</Value> </UnsafeToken> </AuthenticatedRequest> </GetVehicles> </s:body> </s:envelope> An exception will be thrown if the token is expired. 8

9 Here s a sample var ReportRequest = new ReportRequest(); ReportRequest.UnsafeToken = new ReportService.Token(); ReportRequest.UnsafeToken.Value = Context.Token.Value; Reports You must pass one DATAS (data filter) for each filter per data type. You must define ParameterType according to filter type you re passing. Filtername, ValueType, IsMandatory and HasManyValues are depricated. var VehicleFilter = new ReportFilter(); VehicleFilter.ParameterType = FilterParameterType.Vehicle; if (vehicleids!= null) { VehicleFilter.Values = vehicleids.oftype<object>().toarray(); ReportRequest.Datas = new[] { VehicleFilter }; } ReportRequest.StartDateTime = start; ReportRequest.EndDateTime = end; var Response = this.reportcontract.gettripduration (new GetTripDurationRequest(ReportRequest)); Here s an XML sample <Datas> <DataName>Static</DataName> <ParameterType>Vehicle</ParameterType> <ValueType>Integer</ValueType> <IsMandatory>false</IsMandatory> <HasManyValues>true</HasManyValues> <Values> <anytype d4p1:type="xs:int" xmlns:d4p1=" <anytype d4p1:type="xs:int" xmlns:d4p1=" </Values> </Datas> 9

10 Download a complete sample Here s a sample Java package demo; import java.rmi.remoteexception; Java File/Import in Eclipse and select pom.xml. import com.astus.service._2010._11.*; import com.astus.services._2010._11.*; import com.astus.service._static._2010.*; import com.astus.service._static._2010._11.*; public class DemoGetVehicles { public static void main(string[] argc) { System.out.println("Authentication"); OpenSessionRequest opensessionrequest = new OpenSessionRequest("user@domain.xyz","pwd"); AuthorizationContractProxy authproxy = new AuthorizationContractProxy(); StaticContractProxy statproxy = new StaticContractProxy(); Use Apache CXF to create proxy classes. try { authproxy.setendpoint(" OpenSessionResponse opensessionresponse = authproxy.opensession(opensessionrequest); System.out.println("Token: " + opensessionresponse.gettoken().tostring()); statproxy.setendpoint(" AuthenticatedRequest authenticatedrequest = new AuthenticatedRequest(); authenticatedrequest.setunsafetoken(opensessionresponse.gettoken()); GetVehiclesResponse getvehiclesresponse = statproxy.getvehicles(authenticatedrequest); System.out.println("Vehicles found: " + getvehiclesresponse.getvehicles().length); for (Vehicle vehicle : getvehiclesresponse.getvehicles()) { System.out.println("plate: " + vehicle.getplatenumber() + ", odometer: " + vehicle.getodometer()); } } catch (RemoteException e) { e.printstacktrace(); } } } 10

11 Astus Data Exporter EXPORT ODOMETERS AND ENGINE TIME DAILY 11

12 Available fields Vehicle name In Astus Description ADE is a small application that extracts the odometer and engine time of each vehicle for a customer in a CSV file. You can then import that file in your system. You can install this application on a Windows desktop or server. Simply run it automatically using Windows Task Scheduler. The application relies on Astus Web Services (AWS), so you must enter your username and password in the configuration file. Date Odometer Engine time YYYY-MM-DD the information was received KM / Miles Hours 12

13 Astus Push Services EXPORT ANY EVENT FROM DEVICES IN REAL TIME 13

14 Description Astus Push Services exports events you need when they occur. Our team will create an adaptor for your system. Depending on the project s size and complexity, a one time fee may apply. How it works Each time a qualifiyng event is reported by a device, Astus Push Service will adapt it and send it to your listening server. To create the adaptor, please provide: - Event types you need - Positions, trips, accessories, - Comminucation frequency - Format - XML, CSV, JSON - Protocol - WebServices, RestFull, FTP 14

15 Astus Pull Services IMPORT ANY EVENT FROM YOUR SYSTEM IN REAL TIME 15

16 Description Astus Pull Services imports events from your system. Our team will create an adaptor for your system. Depending on the project s size and complexity, a one time fee may apply. How it works At frequency, Astus Pull Service will get and adapt an event from you server. To create the adaptor, please provide : - Event types you need - Positions, trips, accessories, - Comminucation frequency - Format - XML, CSV, JSON - Protocol - WebServices, RestFull, FTP 16

17 Annexes MORE INFORMATION 17

18 0 LowBattery 4 - BatteryDisconnected X - DeviceConnected (Not implemented yet) X - PositionReceived (Not implemented yet) WHEN Our Push service receives all events generated by a device or a user s action. Anyone of these can serve as a trigger to send information. Here are some of the events that can be used to send information to your system. 1 - KeyRead : Any key read on the reader (including valid ones) 6 - ValidKeyRead : The key has a valid reservation and was approved. 5 - CardHolderState 10 - Reserved : Vehicle is inside a scheduled period, but no valid key has been passed 2 - IgnitionStart 8 - ReservationStart : When a reservation start (the key was accepted and a card holder state is valid) 7 - FirstDrive : When the customer first start moving at the beginning of his reservation (time to remove snow in winter) 9 - ReservationEnd : When all conditions are met to end the reservation (badge out and key card holder state) 3 - IgnitionEnd 11 - Valet : No starter kill 12 - Immobilized : Only master key will start the vehicle 18

19 WHAT The Push service can send any information known by Astus inside one or many messages. Here s a partial list of what can be sent. 19

20 FREQUENCY There are many settings that manage the frequency of push events. Here are some of them. SendFrequency: seconds between each push of information to your remote system. SendFailedFrequency: seconds between each retries when a push fails. FailedToUnrecoverableDuration: duration in seconds a failed event will be retried before to be moved to Unrecoverable. 20

21 Accessories (sensors) Astus API can be use to read accessories state and values. Unfortunately, only AccessoryID is exposed. Use the following table to find the meaning of AccessoryID. 21