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: When you are onboarding a thing from a mobile application, you will execute the onboarding using the thing owner's access token (See Access token and Thing owner for more details).
• Onboarding by Thing: When you are onboarding a thing from the thing itself, you will execute the onboarding with the basic authentication (you can alternatively use the access token of the thing).

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-jp.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:

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-jp.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-jp.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-jp.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.