Connecting with a new IoT platform

Administrators can use the IoT Connector wizard in the Administration Work Center to configure a connection to a new IoT platform, specify how to import data from IoT sensors, and map the data that is imported from devices to asset and location meters.

Adding an IoT Service

About this task

The first step in the IoT Connector wizard is to add the new service.

Procedure

  1. In the Administration Work Center, from the side menu, click Integration and select the IoT Connector tab.
  2. Select the IoT Connection Service subtab.
  3. On the Select an IoT Service page of the wizard, click Add service.
  4. Enter the required information in the following fields:
    Option Description
    IoT Service Name for the IoT service that you create.
    Description Brief description of the IoT service.
    End Point Name Name of the endpoint that you create for the service.
  5. Click Add.
  6. Select the service that you added and click Next.

Configuring the IoT Service

About this task

To configure the IoT service, add the endpoint details that are needed for your connection.

Procedure

  1. On the Configure the IoT Service page, provide details for connecting to your IoT platform.
    1. In the Headers field, ensure that you specify the appropriate values for the API key and token, as shown in the following example: 
      x-api-key:<your IoT api key>.x-api-token:<your IoT api token>

      Replace the entire bracketed string, including the brackets, with the appropriate API key and token.

    2. In the URL field, ensure that you specify the appropriate values for your domain and tenant ID, as shown in the following example: 
      https://api-<ctx:environmentname>.connected products.internetofthings.ibmcloud.com/api/datalake/v1/<ctx:TenantName>

      Replace the entire bracketed string, including the brackets, with your domain and tenant ID.

  2. Click Test connection to ensure that the connection is successful.
  3. Click Next.

Configuring Endpoint Properties

About this task

The next step is to configure the endpoint properties for requesting data from your IoT platform.

Procedure

On the Configure End Point Properties page, enter endpoints for requesting data. Review the information for the endpoints to ensure their accuracy and click Next.

Registering Device Types

About this task

After you configure endpoints, you can register the device types for your platform.

Procedure

The Register Device Types page lists the device types that are not registered as assets or location. To register a device type, select one or more device types, click Register as asset or Register as location, and click Next.

If you have large number of device types, you can use the search feature to find the appropriate device type.

Mapping Data Schemas

About this task

The Map Data Schemas page lists all device types that are registered with the Maximo product. The next step is to map device types to asset or location meters.

Procedure

  1. On the Map Data Schemas page, select the device type that you want to map to a meter and click the edit icon.
  2. On the Schema tab, select the option to enter a device type or retrieve a sample device message for the selected device type.
    Option Description
    Enter manually Choose this option to enter a sample message for a device type manually. You must supply the JSON message for the device type that is selected in the IoT platform, in its original format.
    Detect from a connected device Choose this option to retrieve a sample JSON message with device type properties from your platform.
  3. Optional: If you chose to detect the properties from a connected device, complete the following steps.
    1. Specify whether to enter a specific device ID or to retrieve device type properties from the first available sample message that is returned for the device type.
      Table 1. How to retrieve properties
      Field Description
      From first available Choose this option to select the device type properties from the first sample message that is returned for the device type.
      From device ID Choose this option to enter a specific device ID.
    2. Optional: If you chose to specify a device ID, enter the ID.
    3. Click Get now.
  4. Save your changes.
  5. Select the Device Type Mappings tab.
  6. Click Add mapping.
  7. Click Select meter.
  8. In the Select Meter window, select the appropriate meter and click Done.
  9. In the IoT Device Type Property field, select the property that you want to map to the meter.
  10. In the Data Collection section, select whether to collect all readings or aggregated data.
    Table 2. How to collect data
    Field Description
    Aggregated Choose this option to collect aggregated data.
    All readings Choose this option to collect all readings.
  11. If you selected Aggregated, complete the following steps:
    1. Select the option that you want to use to choose an aggregation type.
      Table 3. How to select an aggregation option
      Field Description
      Enter manually You must supply the JSON message for the device type from the aggregation API, in the exact format that is used in your IoT platform.
      Detect from a connected device Choose this option to retrieve a sample JSON message for the device type from the IoT platform aggregation API.
    2. If you selected the Detect from a connected device radio button, select the option that you want to use to retrieve a JSON message for the device type.
      Table 4. How to retrieve a JSON message for the device type
      Field Description
      From first available Choose this option to select a JSON message from the first sample message that the IoT platform aggregation API returns for the device type.
      From device ID Choose this option to enter a JSON message for a specific device type. Note that this option is available only if your endpoint request specifies a value for the attr:-deviceid- variable.
    3. Optional: If you chose to specify a device ID, enter the ID.
    4. Click Get now.
    5. Save your changes.
    6. To specify how to collect aggregated data, in the Value field, select the type of aggregation that you want for the collection.
    7. In the Time Period field, specify the reporting period for the aggregated data.
  12. In the Data Synchronization section, complete the following steps to configure the cron task that schedules data synchronization:
    1. In the Cron Task Instance Name field, select an existing cron task instance for data synchronization or add a new cron task instance.
    2. Optional: If you add a new cron task instance, in the Cron Task Instance Name field, enter a name.
    3. Optional: If you add a new cron task, in the Schedule field select the schedule for running the cron task.
    4. Click Cron Task Instance Active to activate the cron task.
  13. Click Done.

What to do next

After you map device types to asset or location meters, associate the devices with specific assets or locations.