Managing Triggers

Once triggers are registered, you can use the following features to manage them.

Deleting Triggers

The following is a sample code for deleting a trigger.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers/{TRIGGER_ID}"

Set the access token of the thing or thing owner. Also please replace the placeholder {THING_ID} and {TRIGGER_ID} with the ID of the target thing and trigger, respectively.

If the trigger is successfully deleted, Thing Interaction Framework will return a 204 response.

Enabling and Disabling Triggers

Disabling

You can disable a trigger. Once disabled, the trigger becomes inactive and will not fire the command even if the specified condition is met.

The following is an example of disabling an active trigger.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers/{TRIGGER_ID}/disable"

Set the access token of the thing or thing owner. Also please replace the placeholder {THING_ID} and {TRIGGER_ID} with the ID of the target thing and trigger, respectively.

If the trigger is successfully disabled, Thing Interaction Framework will return a 204 response.

Enabling

You can enable an inactive trigger. Once enabled, the trigger becomes active again and will fire the command when the specified condition is met.

The following is an example of enabling an inactive trigger.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers/{TRIGGER_ID}/enable"

Set the access token of the thing or thing owner. Also please replace the placeholder {THING_ID} and {TRIGGER_ID} with the ID of the target thing and trigger, respectively.

If the trigger is successfully enabled, Thing Interaction Framework will return a 204 response.

Updating Triggers

The following is an example of updating the trigger for executing a command.

curl -v -X PATCH \
  -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/{TRIGGER_ID}" \
  -d '{
    "triggersWhat": "COMMAND",
    "predicate": {
      "eventSource": "STATES",
      "condition": {
        "type": "eq",
        "field": "power",
        "value": true
      },
      "triggersWhen": "CONDITION_FALSE_TO_TRUE"
    },
    "title": "Modified test title",
    "description": "Modified test description",
    "metadata": {
      "color": "red",
      "hex": "#333"
    }
  }'

Set the access token of the thing or thing owner. Also replace the placeholder {THING_ID} and {TRIGGER_ID} with the ID of the target thing and trigger, respectively.

If the trigger is successfully updated, Thing Interaction Framework will return a 204 response.

You can update the trigger for executing server code in the same way.

Getting a Trigger

You can get an existing trigger and check its state as follows:

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers/{TRIGGER_ID}"

Set the access token of the thing or thing owner. Also replace the placeholder {THING_ID} and {TRIGGER_ID} with the ID of the target thing and trigger, respectively.

The trigger is returned as a 200 response as follows:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggersWhat": "COMMAND",
  "triggerID":"{TRIGGER_ID}",
  "predicate":{
    "eventSource":"STATES",
    "condition":{"field":"power", "type":"eq", "value":true},
    "triggersWhen":"CONDITION_CHANGED"
  },
  "command":{
    "schema":"SmartLight",
    "schemaVersion":1,
    "actions":[
      {"setLightColor": {"lightColor": "333"}}
    ],
    "issuer":"user:{USER_ID}",
    "target":"thing:{THIHG_ID}"
  },
  "title":"Test title",
  "description":"Test description",
  "disabled":false,
  "metadata":{
    "color":"red",
    "hex":"#333"
  }
}

By checking the disabled field, you can check if the trigger is currently active or inactive.

Getting a List of Triggers

You can get a list of all triggers registered in Thing Interaction Framework.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers"

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

You will get the list of triggers as a 200 response.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggers": [
    {
      "triggersWhat": "COMMAND",
      "triggerID": "{TRIGGER_ID}",
      "predicate": {
        "eventSource": "STATES",
        "condition": {"type": "eq", "field": "power", "value": true},
        "triggersWhen": "CONDITION_CHANGED"
      },
      "command": {
        "schema": "SmartLight",
        "schemaVersion": 1,
        "actions": [
          {"setLightColor": {"lightColor": "333"}}
        ],
        "target": "thing:th.350948a00022-2d68-5e11-232a-001e9c52",
        "issuer": "user:d3d808a00022-2e0a-5e11-132a-00e8a0d9 "
      },
      "title": "Modified test title",
      "description": "Modified test description",
      "disabled": false,
      "metadata": {
        "color": "red",
        "hex": "#333"
      }
    },
    {
      "triggersWhat": "COMMAND",
      "triggerID": "{TRIGGER_ID}",

      ... the trigger detail follows ...
    }
  ]
}

You can find an array of triggers in the triggers field.

The list contains triggers for both commands and server code.

Pagination

If there exist many triggers registered, Thing Interaction Framework may not be able to return all triggers at once. In such a situation, the Framework will return a portion of the triggers with a nextPaginationKey as follows:

First, you will execute the GET command without any "paginationKey".

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers"

If there are many triggers and Thing Interaction Framework cannot return all of them at once, it will return a "nextPaginationKey" together with a portion of the triggers in the response as follows:

    ... an array of triggers ...

    }
  ],
  "nextPaginationKey":"XXXYYY"
}

By specifying this pagination key in the query parameter paginationKey, you can get the next set of triggers.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-Kii-AppID: {APP_ID}" \
  -H "X-Kii-AppKey: {APP_KEY}" \
  "https://api-jp.kii.com/thing-if/apps/{APP_ID}/targets/thing:{THING_ID}/triggers?paginationKey=XXXYYY?bestEffortLimit=100"

Please set the value of the "nextPaginationKey" as is; the value does not have any special meaning (i.e., you cannot directly specify any page number with the key).

As shown in the above example, you can also specify the bestEffortLimit to limit the number of triggers to be returned.

If you get another nextPaginationKey in the response, you can use it to get the next set of triggers. If no nextPaginationKey is set in the response, it means that you've received all triggers.