IoT for Insurance API Examples#

The IoT4I API Examples provides examples of using the API of the IBM Bluemix IoT for Insurance service. The examples show how to register users, create devices, create shields and generate events using the REST API from a Node.JS environment.

Overview

The sample demonstrates the expected flow of the IoT for Insurance

1. Create a user
2. Create a device associated to the user
3. Create a new shield
4. Associate the shield with the user
5. Simulate an event for the device

Requirements

To use this sample, you need:

• IBM Bluemix account. Sign up for Bluemix, or use an existing account.
• At least 2GB of memory available in your Bluemix organisation to provision the IoT for Insurance service and its dependencies

IoT for Insurance Architecture

To better understand this example and the IoT for Insurance API this section contains a brief overview of its architecture.

Component	Description
API	The entry point of the service. It allows developers to register devices, create users and monitor the behavior.
Action Engine	Sends email and mobile notifications for events generated by the Shield Engine
Aggregator	Periodically aggregates the data for display purposes in the Insurance Dashboard
Insurance Dashboard	Provides visualization for the data
Shield Engine	Rule Engine. Reads data from the IoT platform, runs the rules on it and if needed generates events for the Action Engine
Transformer	provides cloud to cloud communication capabilities. Device data for registered devices is read from Wink and delivered into IoT platform

Run on Bluemix

1. Create an IoT4Insurance on Bluemix
2. Rename the service to iot4Insurance
3. Use the button below to Deploy the examples on Bluemix via IBM Bluemix DevOps services

Run locally

Preparing to run

1. If you do not already have a Bluemix account, sign up here
2. If you have not already, download node.js and install it on your local machine.
3. If you have not already, download Git and install it on your local machine.
4. Clone the app to your local environment from your terminal using the following command:

git clone https://github.com/IBM-Bluemix/iot4i-api-examples-nodejs.git

5. cd into this newly created directory
6. Install the required npm and bower packages using the following command

npm install

7. Create an IoT for Insurance service on Bluemix
8. Use the Deploy button from the service console to deploy all the required application parts and depending services. This may take a few minutes. If you don't see the Deploy button, make sure your organization has at least 2GB of memory available.
9. Update the credentials in config.js with the data available in the IoT4I Service Credentials page on Bluemix. The URI of the API looks like https://iot4insurance-api-<uuid>.mybluemix.net/ If running in a different region than US the URL will contain the region's name too.
   NOTE: when copying the URI of the API in config.js make sure it does not contain a trailing /
   NOTE: the aggregator URL listed in config.js is optional. The URL is not available in the Service Credentials and can be obtained from the Bluemix page of the aggregator application created by IoT4 for Insurance.

End to end flow

By following the steps below you can exercise all the critical paths in the system, from creating a user to generating hazards for that user. The flow can be repeated as many times as needed, skipping or repeating steps as needed.

1. Create a user. If successfull the application will print the details of the newly created record:

Syntax: node createUser.js <username>
Example: node createUser.js user1

2. Create a shield.If succesfull the application will print the details of the newly created record.

Syntax: node createShield.js <shieldUUID>
Example: node createShield.js 10

3. Attach the shield code to your newly created shield. The command will use the source code from the resources/shieldCode.js file. Important If you modify the shield code you MUST also modify bl/hazard.js such that the simulated sensor event will have the payload expected by your shield.

Syntax: node createShieldCode.js <shieldUUID>
Example: node createShieldCode.js 10

4. Associate the newly created shield with the user.

Syntax: node createUserShieldAssociation.js <username> <shieldUUID>
Example: node createUserShieldAssociation.js user1 10

5. Generate a hazard event for your user. This simulates a message sent by the sensors installed in the user's home. The message is routed through the IoT Platform service and is processed by the Shield created and registered for the user.

Syntax: node simulateHazard.js <username>
Example: node simulateHazard.js user1

6. Open the Insurance Dashboard and search for the newly created user.

Shield, shield code and shield associations

An IoT4I shield is comprised of:

• the metadata: the shield name, description, icon name
• the shield code: the JavaScript code that is executed in the shield Engine. The shield code also has a metadata section that connects it to the shield
• one or more associations to IoT4I users

The elements of the shield are connected together through the shieldUUID. The shieldUUID MUST be a number in string format ( ex: "100") in the shield metadata, shield code metadata and shield association. The shieldUUID MUST be a number (100) in the jsCode. The UUID used MUST be the same in the shield, shield code and shield association.

Shield

{
  "UUID": "100",
  "name": "Wally Humidity Shield",
  "type": "Home",
  "description": "Detects potential water leaks using the humidity sensors",
  "image": "waterShield",
  "canBeDisabled": false,
  "hazardDetectionOnCloud": true,
  "actions": [
    "pushios",
    "email"
  ],
  "potentialClaimAmount": "10",
  "shieldParameters": []
};

Shield Code

{
  "shieldUUID": "100",
  "type": "shield",
  "code": "<jscode>"
}

Shield Code JavaScript

{
  (function() {
  	var shieldUuid = 100;
  	var shieldName = 'wallyHumidityShield2';
  	var hazardUuid = 'Humidity';
  	var hazardTitle = 'A potential water leak (2) was detected by the humidity sensor.';
  	var delay = 20000;

    ...
  })
}

Shield Association

{
  "shieldUUID": "100",
  "username": "[email protected]",
  "hazardDetectionOnCloud": true
}

Monitoring and debugging the IoT4I flow

As the Shield Engine runs shields on incoming sensor events it wil generate new payloads for those events that pass the shield conditions. You can observe these events by monitoring the device commands on the IoTP instance associated with the IoT4I system.

npm run listener

Before you do can run this tool you MUST configure it to connect to the IoT Platform instance used by IoT4I. For that need to copy the IoTF connection information from the Bluemix "Runtime" tab ofr Action Engine, API or Transformer into tools/local-vcap.json. The data will look like:

{
  "services": {
       "iotf-service": [
        {
            "credentials": {
                "iotCredentialsIdentifier": "...",
                "mqtt_host": "xyxyxy.messaging.internetofthings.ibmcloud.com",
                "mqtt_u_port": 1883,
                "mqtt_s_port": 8883,
                "http_host": "xyxyxy.internetofthings.ibmcloud.com",
                "org": "xyxyxy",
                "apiKey": "xyxyxy",
                "apiToken": "xyxyxy"
            },
            "syslog_drain_url": null,
            "label": "iotf-service",
            "provider": null,
            "plan": "iotf-service-standard",
            "name": "iotf-service_xyxyxy",
            "tags": [
                "internet_of_things",
                "Internet of Things",
                "ibm_created",
                "ibm_dedicated_public",
                "lite"
            ]
        }
    ]
  }
}

The hazard events generated by the Shield Engine look like:

{
  payload: 'The service door has been opened.',
  ids: '[email protected]',
  category: 'HAZARD_CATEGORY',
  type: 'hazard',
  shieldUUID: '9',
  hazardUUID: 'contact-shield_1489415824226',
  timestamp: '2017-03-13T15:37:04.179+0100',
  hazardEventId: '[email protected]'
}

Code Structure

The primary purpose of this demo is to document the usage of the IoT for Insurance API. You can use the access methods (createUser, createDevice) and the helper functions (csrfRequest) as starting points for your integration.

File	Description
config.js	Contains the connection URI and credentials. This must be updated to match your IoT4I Deployment
createDevice.js	Shows how to create a device.
createHistoricalData.js	Shows how to use the historian service API to generate historical data.
createPromotion.js	Shows how to use create promotions visible to end users in the mobile application.
createShield.js	Shows how to add a shield in the system.
createShieldCode.js	Shows how to associate JavaScript code to a shield.
createUser.js	Shows how to register a new user in the system.
createUserShieldAssociation.js	Shows how to associate a shield to a user.
csrfRequests.js	Helper functions for adding the CSRF tokens to the POST/PUT requests.
readShield.js	Shows how to read shield information.
readUser.js	Shows how to read user information.
readUserShieldAssociation.js	Shows how to read user and shield associations.
simulateHazard.js	Helper tool for simulating device events in the absence of actual sensors.

For more information on the notion of shield please see the IoT for Insurance Documentation

Contribution

We are more than happy to accept external contributions to this project, be it in the form of issues and pull requests. If you find a bug, please report it via the issues section or even better, fork the project and submit a pull request with your fix! Pull requests will be evaluated on an individual basis based on value add to the sample application.

License

This sample code is licensed under Apache 2.0. See the license file for more information.