Oct 9, 2014

Integrating Salesforce to the Carvoyant API

The Internet of Things. IoT. The connected world. A paradigm shift known by many different names. While how exactly it will look may be unclear, it is quite clear that the technological world as we know it is undergoing a rapid and dynamic change. Pick a vertical, and we see the evolution. For instance, consider transportation, or more specifically cars. We've come a long way from the horseless carriages of yore; every modern car has a computer in it that controls it's oprations called the Electronic Control Module (ECM). Not only does this control many of the car's functions, but it also digitizes these actions. While the ECM is specific to a particular manufacturer or vehicle, there is an interface called the 'On Board Diagnostic' (OBD) connector that serves as a universal gateway to the digitized data of a car's inner workings.

Taking advantage of this interface are devices such as Carvoyant's connector, which plugs in to the OBD device and collects your car's data for your use through their API. This allows you to retrieve details such as your cars movements and position, fuel usage, maintenance needs, and much more. For companies whose businesses revolve around many or a fleet of cars, the prospect of accessing their data on-demand and/or near real-time can be very attractive.

 Setting up Carvoyant

1. Refer to Carvoyant's getting started and documentation here: http://confluence.carvoyant.com/display/PUBDEV/Getting+Started

2. Go to http://developer.carvoyant.com and register for a user account.

3. You will fill out some information for the application you create. The "Register Callback URL" field is very important -- this must be the page on which your web app performing the OAuth2 authentication is located and process the authorization code to exchange for the access token.

4. Now that you have an account, we need some data. go to https://sandbox-driver.carvoyant.com/ . Here you must register for a driver account (different from the user account you set up earlier).

5. Create a few cars. Either use your own cars' VIN numbers or search the web for some of your favorite cars and use those. Don't tell them I sent you.

6. Now let's make some trip data. Go to https://sandbox-simulator.carvoyant.com/ and login once again using your driver account. Click on two points on the map and a series of waypoints will be created between them. You can add more color to your data with the properties to the left, such as fuel usage and engine temperature.

7. That's it! We now have some data that we can use in Salesforce once we perform our integration.

 Salesforce Development

 The API uses the standard server side OAuth2 authorization flow. This involves passing an application key and client secret to the API, getting back an authorization code, and exchanging this code for a token from the API. Authentication is complete and this token is then stored and used for subsequent callouts to the API.

 Let's do a simple callout to the API to get our vehicles and their positions. We will then store them as records in Salesforce and map their position on a Visualforce page with Google Maps. This is what we will end up with (or something similar for the data you create):

The code below consists of a few components. We performed our authentication and saved our token and credentials in a custom setting. The class "CarvoyantIntegration" builds our HTTP request for us by using the results from authentication, the target API endpoint (https://sandbox-api.carvoyant.com/sandbox/api), and the resource/HTTP method passed in from our loadVehicles method. We deserialize the response from the Carvoyant API using the Vehicles/Vehicle inner classes, and thereby have the properties of the vehicle for our use later in the processVehicles method, where we take their values and create records in Salesforce.

 The class below contains a getter that merely fetches the vehicle data created from our callouts for use in our visualforce page.

We will use some of the properties in our table of vehicle information, and use the last waypoint latitude/longitude to map the last known location of the vehicles. The page has code for displaying vehicle record information as well as creating markers for the vehicles we queried for inthe controller above. Check out http://blog.crmscience.com/2014/09/lab-coat-lesson-google-maps-api.html for more detailed information about the Google Maps Javascript API.

What's next? Maybe you want to go in the direction of getting data for your vehicles when there is a change. You can use Carvoyant's subscription service and the Salesforce Streaming API as they have described here to do that http://confluence.carvoyant.com/display/PUBDEV/Force.com Perhaps you want to send emails when something goes wrong with a car, or better yet perform some preventative actions when a car hits certain threshold data points during their usage, such as mileage and engine temperatures. Or maybe you want to be able to know when certain cars enter certain areas you demarcate known as Geofences.

While we are only beginning our journey into the connected world, steps like these will prove to be instrumental in guiding that course and our expectations of it. Do we want cars to communicate with eachother? Perhaps leading to more efficient routing and a final end to traffic jams? Can we optimize our infrastructure through analysis of this data? Will this sort of thing help us keep an eye out on our autonomous cars? Control them even? There is a plethora of ideas in this realm that are waiting to be implemented. And what's next... you decide.