Server Code Triggers

To execute server code automatically, set the information about the server code and the condition in the trigger.

When the server code execution is finished, you can get the execution result (i.e., the returned value and error).

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 "SERVER_CODE" when you want to execute server code.
predicate Yes The execution condition to fire the trigger. See Trigger Execution Conditions for the field usage.
serverCode Yes The server code to execute when the execution condition is met. Refer to Server code definition 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.

Server code definition

Set the following information under the serverCode field.

Fields Mandatory? Description
endpoint Yes The name of the server code endpoint to execute.
parameters No The parameter to be passed to the endpoint.
tartgetAppID No The AppID of the application where the server code is set. Set if the server code and the trigger are set in the different applications.
executorAccessToken No The "caller" access token used for executing the server code. This is required if you set the taregetAppID field.

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 state condition triggers

See below for an example to register a trigger that executes server code automatically.

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": "SERVER_CODE",
    "predicate": {
      "eventSource": "STATES",
      "condition": {"type": "eq", "field": "power", "value": true},
      "triggersWhen": "CONDITION_CHANGED"
    },
    "serverCode" : {
      "endpoint" : "saveColor",
      "parameters" : {
        "brightness" : 100,
        "color" : "#FFF"
      },
      "executorAccessToken" : "_kuslkq71LdiHcR0Ez91uIT2N-fUBRst3vMnWE3Ge8o"
    },
    "title": "Example #2",
    "description": "Execute the server code 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.

Getting execution results of server code

After setting a trigger, the specified server code will be executed every time when the designated state condition is satisfied. The results are stored in Thing Interaction Framework, and you can check these results via the REST API.

The following is a sample of getting the execution result.

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}/results/server-code"

Set the access token of the thing or thing owner. Also replace the placeholder {THING_ID} with the ID of the target thing. The {TRIGGER_ID} should be replaced with the triggerID that was returned when you register the trigger.

You will get the server code execution result as a 200 response.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "triggerServerCodeResults" : [ {
    "succeeded" : true,
    "returnedValue" : "1456801769894",
    "executedAt" : 1456801769904
  }, {
    "succeeded" : true,
    "returnedValue" : "1456801784981",
    "executedAt" : 1456801784987
  }, {
    "succeeded" : false,
    "executedAt" : 1456802646413,
    "error" : {
      "errorMessage" : "Error found while executing the developer-defined code",
      "details" : {
        "errorCode" : "RUNTIME_ERROR",
        "message" : "Error in Server Code"
      }
    }
  } ],
  "nextPaginationKey" : "200/1"
}

The succeeded tells you if the server code execution was successful. If the execution was successful, you will be able to get the code execution time in UNIX time (msec) and the returned value. If the execution was failed, you will be able to get the code execution time and the error detail.

Like when you get a list of triggers, you can limit the number of results to get in one request and use the pagination by setting the parameters "bestEffortLimit" and "paginationKey". The next example shows how you can set these parameters in the GET command. Refer to Getting a List of Triggers for details.

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}/results/server-code?paginationKey=XXXYYY&bestEffortLimit=100"