Data store connector for Cloudant NoSQL DB

Use IBM® Cloudant® NoSQL DB for IBM Cloud to store and access your device data in daily, weekly, or monthly databases set by on your selected bucket interval.

When you use Cloudant NoSQL DB to store device data with IBM Maximo Asset Monitor, three databases are automatically created;

• Current bucket interval database.
• Upcoming interval database.
  When the end of an interval is reached, device data is stored in the bucket database for the new interval and a new database is created for the following interval.
• Configuration database.
  Design documents that you add to the configuration database are copied to new databases as these are created.

Database naming schema

The destination configuration determines how IBM Maximo Asset Monitor manages the databases in your Cloudant NoSQL DB account.

The database naming schema is as follows:{destinationName}_{bucketName}, with {bucketName} determined by your choice of bucketInterval when you configure the Cloudant NoSQL DB destination:

Document schema

Device data is stored in a database either as JSON or as base64 depending on the data type.

JSON

If the data is valid JSON and the format of the device event is set to json, the device data is stored in the following format:

{
  "_id": "78bf4380-3311-11e6-a747-d7b140d1a70a",
  "_rev": "2-d13912b7c089f060a4ba7369fa86e46f",
  "typeId": "t",
  "deviceType": "0",
  "eventType": "json_payload",
  "format": "json",
  "timestamp": "2016-06-15T16:54:41.464+01",
  "data": {
    "a": 22
  }
}

Other data

Device data that is not valid JSON or where the format is not set to json is stored as a base64 encoded strings under the payload field in the following format:

{
  "_id": "80f1ce10-3311-11e6-a747-d7b140d1a70a",
  "_rev": "1-bfcbf1e74389fe4188a9425c0cd2575a",
  "payload": "eHh4eHg=",
  "typeId": "t",
  "deviceType": "0",
  "eventType": "non_json_payload",
  "format": "notjson",
  "timestamp": "2016-06-15T16:54:55.217+01"
}

Configuration

By using the Python SDK, you can set up a Cloudant NoSQL DB binding in just a few lines of code. For more information about how to get your IoT data forwarded to Cloudant NoSQL DB, see the Python SDK documentation for DSC.

You can also use the following code sample to configure two destinations and forwarding rules to ensure that all events and all states are forwarded.

import wiotp.sdk.application

options = wiotp.sdk.application.parseEnvVars()
appClient = wiotp.sdk.application.ApplicationClient(options)

# Configure the binding
serviceBinding = {
  "name": "mycloudant",  "type": "cloudant", 
  "credentials": { 
    "host": "hostname", 
    "port": 443, 
    "username": "username", 
    "password": "password"
  }
}
service = appClient.serviceBindings.create(serviceBinding)
# Set up the connector
connector = self.appClient.dsc.create(name="connector1", serviceId=service.id)
# Set up destinations
connector.destinations.create(name="events", bucketInterval="MONTH")
connector.destinations.create(name="state", bucketInterval="MONTH")
# Set up rules
rule1 = connector.rules.createEventRule(name="allevents", destinationName="events", typeId="*", eventId="*")
rule2 = connector.rules.createStateRule(name="allstate", destinationName="state", logicalInterfaceId="*")

The sections that follow explain in more detail how you can configure the Cloudant NoSQL DB historian feature by using the IBM Maximo Asset Monitor APIs.

Step 1: Set up the service binding

To configure a service binding to Cloudant NoSQL DB, you need the following Cloudant NoSQL DB information:

• username
• password
• host
• port

With this information, you can call the API to create a new Cloudant NoSQL DB service binding.

When the service binding completes, a serviceId is returned. You need this 36 character UUID when you set up the connector instance.

Important: The API requires the additional url field. This field is a composite of the information you collected prior and is constructed this way: https://{username}:{password}@{host}:{port}

Step 2: Set up the connector

To configure the connector, you need the following information:

• The serviceId from the creation of the service binding.
• A name and optional description for the connector
• An optional timezone to override the default conversion of all timestamps to Coordinated Universal Time.

Tip: You can enable the connector or create it in a disabled state to be enabled at a later date.

With this information, you can call the API to create a new Cloudant NoSQL DB connector.

Step 3: Set up the destination

The third step is to set up the destination by configuring a daily, weekly or monthly storage policy and to specify the database naming scheme to use with the Cloudant NoSQL DB account.

You set up the destination by using the API to create a new Cloudant NoSQL DB destination.

Step 4: Set up the forward rule

The final step is to configure the data to be forwarded to Cloudant NoSQL DB destination that you set up in step 3. by using the API to create a new forwarding rule.

Configure the rule to forward either events or state to the destination:

• To forward events.
  1. Set type to event.
  2. Provide a selector by using typeId and deviceId. Devices that are identified by the selector have their events are forwarded.
• To forward state.
  1. Set type to state.
  2. Provide a selector by using logicalInterfaceId. Devices that implement the logical interface have their states forwarded.

IBM developer recipes

The following recipes describe how to use IBM Maximo Asset Monitor and Cloudant NoSQL DB together:

• Query and Process IBM Maximo Asset Monitor Device Data from Cloudant NoSQL DB.
  This recipe shows how to query and do data processing operations on the device data that is stored in Cloudant NoSQL DB.