Onboarding

To use the Thing-IF feature, you need to register a thing to the Thing Interaction Framework and optionally bind it with a mobile application (more specifically, with a user of the mobile application). This binding process is called Onboarding.

As described in the overview, you can onboard a thing from a mobile application or from the thing itself.

Onboarding by Owner

You can use either the vendorThingID or thingID (please check here for more details).

Onboard with vendorThingID

The following is an example of a thing owner onboarding with the vendorThingID.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithVendorThingIDByOwner+json" \
  "https://api.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "vendorThingID": "{VENDOR_THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "thingType": "{THING_TYPE}",
    "thingProperties": {
      "{PROPERTY_NAME}": "{PROPERTY_VALUE}"
    },
    "owner": "user:{USER_ID}",
    "dataGroupingInterval": "15_MINUTES"
  }'

If you are setting a user as the thing owner, please set the access token of this user. If you are setting a group as the thing owner, please set the access token of this group's member.

The information to be put in the body is as follows:

Field Mandatory? Description
vendorThingID Yes ID assigned by the thing vendor. See here for more information. Any string with alphanumeric, hyphen, underscore and period up to 200 characters is accepted as long as it is unique in the application. This field value cannot be modified later.
thingPassword Yes The password for the thing. Basically, a unique password is assigned to each thing to secure the resources allocated for the thing in Thing Interaction Framework. The password set at the first onboarding becomes active. Specify this password when you are to onboard the thing for the second time and thereafter. You cannot change the password later.
owner Yes The ID of the thing owner. This can be either a user ID or group ID. Please use the prefix "user:" when setting a user ID and "group:" when setting a group ID.
thingType No A type of the thing. Any string with alphanumeric, hyphen, underscore and period up to 100 characters is accepted.
thingProperties No The properties of the thing. You can set both the predefined and custom fields. See Register a Thing for more details.
dataGroupingInterval No The grouping interval for storing state history. The history will not be stored if no grouping interval is specified. The available intervals are 1_MINUTE, 15_MINUTES, 30_MINUTES, 1_HOUR, and 12_HOURS. See this page for the details.

If the thing with the specified vendorThingID does not exist, a new thing will be registered in Thing Interaction Framework with the specified information; otherwise, the information is ignored (i.e., the thing information will not be updated).

The owner registration will always be executed, regardless of if the thing with the specified vendorThingID already exists or not.

If the onboarding is succeeded, Thing Interaction Framework will return a 200 response as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "thingID":"{THING_ID}",
  "accessToken":"{THING_ACCESS_TOKEN}",
  "mqttEndpoint":{
    "installationID":"{INSTALLATION_ID}",
    "host":"{BROKER_HOST}",
    "mqttTopic","{MQTT_TOPIC}",
    "userName":"{USERNAME}",
    "password":"{PASSWORD}",
    "portSSL":{PORT_SSL},
    "portTCP":{PORT_TCP},
    "portWS" : {PORT_WS},
    "portWSS" : {PORT_WSS},
    "ttl":{MQTT_TTL}
  }
}

The response will have the thingID and access token of the thing. It will also contain the MQTT endpoint information that is to be used for establishing a MQTT connection (See here for more details).

Onboard with thingID

The following is an example of a thing owner onboarding with the thingID.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithThingIDByOwner+json" \
  "https://api.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "thingID": "{THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "owner": "user:{USER_ID}"
  }'

The REST call and its response are very similar to that of the previous Onboarding with vendorThingID, with the following differences:

  • The thing with the specified thingID must exist for the successful onboarding.
  • Since the target thing should already exist, you do not need to set the "thingType" and "thingProperties" fields. If you set them, they will be ignored.
  • The Content-Type is "application/vnd.kii.OnboardingWithThingIDByOwner+json".

Onboard by Thing

You can use either the vendorThingID or thingID (please check here for more details).

Onboard with vendorThingID

The following is an example of a thing onboarding with its vendorThingID.

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithVendorThingIDByThing+json" \
  "https://api.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "vendorThingID": "{VENDOR_THING_ID}",
    "thingPassword": "{THING_PASSWORD}",
    "thingType": "{THING_TYPE}",
    "thingProperties": {
      "{PROPERTY_NAME}": "{PROPERTY_VALUE}"
    }
  }'

The REST call and its response are very similar to that of the previous Onboarding with vendorThingID, with the following differences:

  • You will use the basic authentication. Replace {BASE64_ENCODED_APPID_AND_APPKEY} with a Base64-encoded string of concatenated AppID and AppKey with a colon (:) in between the two values. You can also use the access token of the thing.
  • The Content-Type is "application/vnd.kii.OnboardingWithVendorThingIDByThing+json".
  • You should not set the "owner" field.

Onboard with thingID

The following is an example of a thing onboarding with its thingID.

curl -v -X POST \
  -H "Authorization: Basic {BASE64_ENCODED_APPID_AND_APPKEY}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  -H "Content-Type: application/vnd.kii.OnboardingWithThingIDByThing+json" \
  "https://api.kii.com/thing-if/apps/{APP_ID}/onboardings" \
  -d '{
    "thingID": "{THING_ID}",
    "thingPassword": "{THING_PASSWORD}"
  }'

The REST call and its response are very similar to that of the previous Onboarding with vendorThingID, with the following differences:

  • You will use the basic authentication. Replace {BASE64_ENCODED_APPID_AND_APPKEY} with a Base64-encoded string of concatenated AppID and AppKey with a colon (:) in between the two values. You can also use the access token of the thing.
  • The thing with the specified thingID must exist for the successful onboarding.
  • Since the target thing should already exist, you do not need to set the "thingType" and "thingProperties" fields. If you set them, they will be ignored.
  • The Content-Type is "application/vnd.kii.OnboardingWithThingIDByThing+json".
  • You should not set the "owner" field.