Command Triggers

To execute a command automatically, set the template of the command and the condition in the trigger. See the below examples.

Trigger Definition

The trigger definition is set in the body with the following fields:

Fields Mandatory? Description
triggersWhat Yes The target the trigger will execute. Specify "COMMAND" when you want to execute a command.
predicate Yes The execution condition to fire the trigger. See Trigger Execution Conditions for the field usage.
command Yes The command to execute when the execution condition is met. See the below table for the field usage.
title No The title of the trigger (max 50 characters).
description No The description of the trigger (max 200 characters).
metadata No The metadata of the command in a JSONObject format.

command is set with the following fields:

Fields Mandatory? Description
actions Yes An array of actions to be sent in the command. In the example in Sending Command, three actions (turnPower, setPresetTemperature, and setFanSpeed) are set and sent in the command. As shown in the example, you can set the parameter for each action.
issuer Yes The issuer of the command. The issuer must be the owner of the target thing. 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.
schema and
schemaVersion		 Yes The schema name and version. They are useful for detecting the schema version mismatch (See here for more information).
target If the thing that updates the state information and the thing that receives the command are different, specify the thing that receives the command. The owner of these things must be the same.
title The title of the command (max 50 characters).
description The description of the command (max 200 characters).
metadata The metadata of the command in a JSONObject format.

If the trigger is successfully registered in Thing Interaction Framework, the Framework will assign a trigger ID. This trigger ID is returned in a 201 response as follows:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "triggerID": "{TRIGGER_ID}"
}

Registering One-Time Schedule Triggers

See below for an example to register a one-time schedule trigger.

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/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "SCHEDULE_ONCE",
      "scheduleAt": 1483150970386
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #1",
    "description": "Execute the command at the designated time",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

Set the access token of the thing owner. Also, replace the placeholder {THING_ID} with the ID of the target thing.

Registering Recurring Schedule Triggers

See below for an example to register a recurring schedule trigger.

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/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "SCHEDULE",
      "schedule": "0 9 * * *"
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #2",
    "description": "Execute the command on the scheduled interval",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

Set the access token of the thing owner. Also, replace the placeholder {THING_ID} with the ID of the target thing.

See Recurring Schedule to learn how to set the time.

Registering State Condition Triggers

See below for an example to register a trigger with a state condition.

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/json" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "STATES",
      "condition": {"type": "eq", "field": "power", "value": true},
      "triggersWhen": "CONDITION_CHANGED"
    },
    "command": {
      "schema": "SmartLight",
      "schemaVersion": 1,
      "issuer": "user:{USER_ID}",
      "target": "thing:{TARGET_THING_ID}",
      "actions": [
        {"setLightColor": {"lightColor": "333"}}
      ]
    },
    "title": "Example #3",
    "description": "Execute the command when the state condition is met",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

Set the access token of the thing owner. Also, replace the placeholder {THING_ID} with the ID of the target thing.