The Fleet Management Starter Application for the IBM® IoT Connected Vehicle Insights SaaS offering demonstrates how quickly you can build an app on IBM Cloud to manage and monitor a fleet of vehicles in real time.
The Fleet Management Starter Application uses the IBM IoT Connected Vehicle Insights SaaS offering together with IBM Cloud services to provide a sample solution for fleet operation management and personnel. By using the application, you can easily track and view the following information:
- Availability of a fleet of cars on a map
- Location of vehicles
- Overall health of the entire fleet
- Health diagnostics and conditions of a specific vehicle in the fleet
- Condition of vehicles by order of severity or risk
- Event history for the entire fleet
- Event history for a specific vehicle in the fleet
The Fleet Management Starter Application uses the following IBM Cloud services:
To deploy and use the Fleet Management Starter Application, you need an instance of IBM IoT Connected Vehicle Insights that is deployed and running on either IBM SaaS.
Deploy the Fleet Management Starter Application on IBM Cloud either automatically or manually, as outlined in the following instructions.
To automatically deploy the Fleet Management Starter Application on IBM Cloud, click 
The automatic deployment option creates an instance of the app and the required IBM Cloud services, and also binds the services to the starter app automatically. After the automated deployment, complete the following steps to configure the app to manually to connect to your IBM IoT Connected Vehicle Insights SaaS service.
- Open the IBM Cloud dashboard in your browser.
- To stop the app, click ACTIONS > Stop App.
Next: Go to Connecting to IBM IoT Connected Vehicle Insights service.
To manually deploy the Fleet Management Starter Application on IBM Cloud, complete all of the following steps:
- Log in to IBM Cloud. If you do not have an existing IBM Cloud account, click Register and follow the instructions to create an account.
- Download and install the Cloud-foundry CLI tool.
- Clone the Fleet Management Starter Application to your local environment by using the following console command:
git clone https://github.com/ibm-watson-iot/iota-starter-server-fm-saas.git
- Change to the directory that you created.
- Edit the
manifest.ymlfile and change the values of<name>and<host>to something unique.<host>must be same withpostUrlin gateway.properties.
applications:
:
host: iota-starter-server-fleetmanagement
name: iota-starter-server-fleetmanagement
memory: 512M
path: .
instances: 1
:
Note: The host value is used to generate your application URL, which is in the following syntax:
<host>.mybluemix.net.
- Install the NPM package by using the following command. The installer observes the dependencies that are specified in your
package.jsonfile.
$ cd ./webclient
$ npm install
- Convert TypeScript to JavaScript:
$ npm run tsc
$ npm run gulp
$ cd ..
- By using the command line tool, connect to IBM Cloud and log in when prompted:
$ cf api https://api.ng.bluemix.net
$ cf login
- Create an instance of the Cloudant NoSQL DB service in IBM Cloud:
$ cf create-service cloudantNoSQLDB Lite FleetCloudantDB
- Push the starter app to IBM Cloud by using the following command:
$ cf push --no-start
Important: When you run the push command, you must include the --no-start option as you must complete further steps manually before you start the app.
Result: Your very own instance of the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application is now deployed on IBM Cloud.
To run the Fleet Management Starter Application with your IBM IoT Connected Vehicle Insights instance, the following two custom plugins must be deployed to your IBM IoT Connected Vehicle Insights instance. The source code of the plugins is contained in plugins folder under the Fleet Management Starter Application repository.
| Plugin | Component | Description |
|---|---|---|
| HttpActionNotifyClient | Vehicle Data Hub (VDH) | A VDH plugin that accepts sendCarProbe requests from simulated vehicles and POSTs affected events and notified messages to the Fleet Management Starter Application. |
| FleetAlert | Agent | A rule plugin that calculates fuel level from fuel tank capacity of a vehicle and remaining fuel in received probe. A fuel alert rule estimates the value to generate a fuel warning to be notified to the Fleet Management Starter Application. |
To build and deploy the plugins, complete the following steps:
- The IBM IoT Connected Vehicle Insights Plugin Deployment Tool must be installed on your IBM IoT Connected Vehicle Insights SaaS instance. Contact the system administrator for your IBM IoT Connected Vehicle Insights SaaS service to make a request to install it.
- The IBM IoT Connected Vehicle Insights Plugin Development Tool must be installed on your eclipse IDE, as outlined in the IBM IoT Connected Vehicle Insights Plug-In Programmer's Guide. To get access to the guide and the tool, contact your IBM IoT Connected Vehicle Insights system administrator.
- The Fleet Management Starter Application Git repository must be downloaded on your local environment. If you need to download the repository, you can clone it by using the following console command:
git clone https://github.com/ibm-watson-iot/iota-starter-server-fm-saas.git
- Launch the eclipse that contains IBM IoT Connected Vehicle Insights Plugin Development Tool.
- Open Git perspective (Window > Perspective > Open Perspective > Other...).
- From the Git Repositories view, click Add an existing local Git repository. Alternatively, you can also clone the repository by selecting Clone a Git repository.
- Specify a directory that contains the Fleet Management Starter Application Git repository.
- Select the Fleet Management Starter Application Git repository and click Finish.
- Right click the added repository on Git Repositories view and select Import Projects....
- Select Import existing Eclipse projects and click Next.
- Select
FleetAlertandHttpActionNotifyClientand click Finish.
- Open Java perspective (WIndow > Perspective > Open Perspective > Other...) in your eclipse.
- Right click the
HttpActionNotifyClientproject in Package Explorer view and select Export.... - Select Java > JAR file and click Next.
- Input a file name in the JAR file field and click Finish.
- In the same manner, export the
FleetAlertproject as a JAR file.
- Download a copy of the
gateway.propertiesfile that you deployed on the VDH server by using IBM IoT Connected Vehicle Insights Plugin Deploy Tool. - Open the
gateway.propertiesfile with a text editor. - Increment
client.numin thegateway.propertiesfile. - Insert the following two lines before the DefaultHTTPClient client definition.
client.client1=com.ibm.mobility.sample.http.HttpActionNotifyClient client.client1.protocol=http - Renumber all the existing client definition keys so that they do not conflict with each other, for example:
client.client2=com.ibm.mobility.autodrive.client.def.DefaultHTTPClient client.client2.protocol=http client.client2.agent=SM_API - Insert the following client unique properties:
HttpActionNotifyClient.postUrl=https://<your-iota-starter-fleetmanagement>.mybluemix.net HttpActionNotifyClient.postUser=starter HttpActionNotifyClient.postPassword=Starter4Iot- For
postUrl, replace the example URL with your Fleet Management app URL. - If you modified the default
postUserandpostPasswordcredentials, replace the values that are specified in the properties file. - Save the changes and close the editor.
- For
A fragment of the gateway.properties file exists under conf folder of the HttpActionNotifyClient project. You can copy contents from the file.
- Deploy exported
HttpActionNotifyClientjar and updated gateway.properties to a VDH server using IBM IoT Connected Vehicle Insights Plugin Deploy Tool. - Deploy export the
FleetAlertjar to an Agent server. - Restart IBM IoT Connected Vehicle Insights components using IBM IoT Connected Vehicle Insights Plugin Deploy Tool as needed.
After deploying the app on IBM Cloud, you must configure the app to connect to your IBM IoT Connected Vehicle Insights SaaS service instance.
{: #config_endpoints} To connect to your IBM IoT Connected Vehicle Insights service instance, the starter app reads the REST API endpoints and credentials from an environment variable on IBM Cloud. Configure the environment variables as follows:
- Open the IBM Cloud dashboard in your browser.
- Open the IBM IoT Connected Vehicle Insights service.
- Select Runtime tab at the left navigation bar.
- Click Environment variables.
- Add the following environment variable:
USER_PROVIDED_VCAP_SERVICES = <endpoint definition in JSON format>
Define the endpoints in the following JSON format. Note that you must remove any line breaks that are at the end of each line to set to the environment value on IBM Cloud.
{
"iotforautomotive": [
{
"credentials": {
"api": <IBM IoT Connected Vehicle Insights endpoint>,
"username": <user name>,
"password": <passsword>,
"maximo": {
"orgid": <organization for IBM IoT Connected Vehicle Insights>
"classificationid": <classification for Vehicle Data>
"username": <user name for Maximo API >,
"password": <passsword for Maximo API >
}
}
}
]
}
To obtain the correct values, contact your system administrator.
| Key | Description of Value |
|---|---|
| api | A URL to call the REST API for IBM IoT Connected Vehicle Insights, which must end with a forward slash character (/) |
| username | User name for accessing the Vehicle Data Hub (VDH) and other IBM IoT Connected Vehicle Insights endpoints |
| password | Password for accessing the VDH and other IBM IoT Connected Vehicle Insights endpoints |
| maximo/orgid | IBM IoT Connected Vehicle Insights Organization specified in IBM Maximo Asset Management |
| maximo/classificationid | Classification for vehicle data defined in Maximo Asset Management |
| maximo/username | User name for accessing the Maximo Asset Management API |
| maximo/password | Password for accessing the Maximo Asset Management API |
The IBM Secure Gateway service provides secure connectivity and establishes a tunnel between your IBM Cloud organization and the remote location that you want to connect to. Before you use the Secure Gateway service, contact your IBM IoT Connected Vehicle Insights system administrator. For more information, see Secure Gateway.
To secure the app, authentication is enabled by default for the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application. The default user credentials are as follows:
| User name | Password |
|---|---|
| starter | Starter4Iot |
-
To change the user name or password that is used by the app, edit the values that are specified for the
APP_USERand theAPP_PASSWORDenvironment variables. -
To remove authentication, set both the
APP_USERandAPP_PASSWORDenvironment variables to 'none'.
- To start the Fleet Management Starter Application, open the IBM Cloud dashboard and start the app.
Congratulations! You are now ready to use your own instance of the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application. To connect to the app, enter the following URL in your browser:
http://<host>.mybluemix.net in your browser.
The starter app also provides a mobile app to connect to an OBDII dongle plugged in to your car. The mobile app sends data from an OBDII dongle to the Fleet Management Starter Application through the Watson IoT Platform service and you can see the data in the app. Complete the steps below to enable this optional feature.
- Open the IBM Cloud dashboard in your browser.
- Open the IBM IoT Connected Vehicle Insights service.
- Select Connections tab at the left navigation bar.
- Click Connect New.
- Select IBM Watson IoT Platform service, and then click Create to bind the service.
When you start the OBDII Fleet Management App for the first time, your device is automatically registered to the Watson IoT Platform service with the default device type, which is OBDII. Create a device type for your device by completing the following steps:
- Open the Watson IoT Platform dashboard on IBM Cloud.
- Click Device.
- Click Device Types.
- Click +Create Type.
- Click Create device type.
- In the Name field, enter 'OBDII'.
- Leave the other fields as default and click Next at the bottom right until a device type is created.
To build and install the OBDII Fleet Management App on an Android phone, see the following repository.
- For Android phone : IBM IoT Connected Vehicle Insights - OBDII Fleet Management App for Android.
- For iOS phone : IBM IoT Connected Vehicle Insights - OBDII Fleet Management App for iOS.
After deploying the Fleet Management Starter Application, start OBDII Fleet Management App on your phone.
When you start the OBDII Fleet Management App for the first time, your device is registered automatically to the IoT Platform service that you have specified in the mobile app, and a corresponding vehicle is created automatically when you connect your device to the IoT Platform.
Now that your device is connected to the Watson IoT Platform, go to the Map or Car Status page in the app and see the status.
If you no longer need a device, go to the Watson IoT Platform dashboard and delete your device manually. After you delete a device, update the vehicles in the IBM IoT Connected Vehicle Insights service, as follows:
- Open the Fleet Management Starter Application on your browser.
- On the left navigation bar, click Vehicle.
- On the top right side of the page, click Sync with IoT Platform.
A vehicle corresponding to deleted device must be removed from a table. Also, if you have added a device to the Watson IoT Platform manually, the vehicle is added to the table.
To report a defect with the IBM IoT Connected Vehicle Insights - Fleet Management Starter Application, go to the Issues section section.
To debug problems, check the IBM Cloud app logs. To view the logs, run the following command from the Cloud Foundry CLI:
$ cf logs <application-name> --recent
For more information about how to troubleshoot your application, see the Troubleshooting section in the IBM Cloud documentation.
The IBM IoT Connected Vehicle Insights - Fleet Management Starter Application includes code to track deployments to IBM Cloud and other Cloud Foundry platforms.
For each instance that you deploy, the following information is sent to a Deployment Tracker service on each deployment:
- Node.js package version
- Node.js repository URL
- Application Name (
application_name) - Application GUID (
application_id) - Application instance index number (
instance_index) - Space ID (
space_id) or OS username - Application Version (
application_version) - Application URIs (
application_uris) - Cloud Foundry API (
cf_api) - Labels of bound services
- Number of instances for each bound service and associated plan information
- Metadata in the repository.yaml file
This data is collected from the package.json and repository.yaml file in the sample application and the VCAP_APPLICATION and VCAP_SERVICES environment variables in IBM Cloud and other Cloud Foundry platforms. This data is used by IBM to track metrics around deployments of sample applications to IBM Cloud to measure the usefulness of our examples, so that we can continuously improve the content we offer to you. Only deployments of sample applications that include code to ping the Deployment Tracker service will be tracked.
You can disable the Deployment Tracker service by removing require("metrics-tracker-client").track(); from the beginning of the app.js server file.
Thank you for using our IBM® IoT Connected Vehicle Insights SaaS service and starter apps. As well as providing samples to help you get started, we'd like to know what you and your users think about our service offering.
The IBM IoT Connected Vehicle Insights Fleet Management starter application sample also includes the Medallia Net Promoter Score (NPS) widget code, which you can choose to deploy with the apps that you develop to integrate with the service.
The NPS widget provides a mechanism for you and your app users to rate your overall experience with the IBM IoT Connected Vehicle Insights service and to provide specific feedback comments to help us to continually improve the quality of the service offering and to increase your satisfaction. When you build an application by using our sample code, the NPS widget is automatically included in your app and provides the following user interface for providing feedback to IBM:
When you or your app users rate the IBM IoT Connected Vehicle Insights service by completing the survey in the NPS widget, the rating score, feedback comments, and customer ID are automatically submitted back to IBM.
By default, when you build an app by using the Fleet Management starter app sample code that is in this repository, the NPS widget is enabled. If you would like to remove the NPS widget from the user interface of your apps, complete the following steps:
- In this repository. go to the
/webclientfolder. - Edit both the
index.htmlandindex-prod.htmlfiles and remove all of the code from<!-- NPS Widget BEGIN -->to<!-- NPS Widget END -->. - Save your changes.
The IBM NPS widget is produced in partnership with Medallia. For information about the widget and the data that it collects, see Privacy Policy - Medallia.