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

Registering state condition triggers

Before you register a trigger, set the target server code. Refer to Server Extension Programming Guide to learn how you can set the server code.

When you are done with setting the server code, set the endpoint you want to execute by the trigger.

The next example is setting a trigger to execute the alertTemperature endpoint of the server code with the parameter {"caller":"trigger"} when the room temperature goes over 30 degrees.

// Specify an end point of server code.
String accessToken = KiiUser.getCurrentUser().getAccessToken();
JSONObject param = new JSONObject("{\"caller\":\"trigger\"}");
ServerCode serverCode = new ServerCode("alertTemperature", accessToken, null, param);

// Create a predicate.
// Execute the server code when the temperature is greater than or equal to 30 deg C.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 30));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger(serverCode, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

In the sample code, we create ServerCode and StatePredicate instances and register a trigger with the postNewTrigger method.

The ServerCode instance is used to set the condition for the server code. We are setting the following parameters in the ServerCode constructor.

• The first argument: the name of the server code endpoint (i.e., the name of JavaScript function) to execute.
• The second argument: the access token to be used for executing the server code. We are setting the access token of the owner user in this example. In the server code, you can use the context.getAccessToken() to get the access token of the caller and execute the server code with the privilege of this caller. When you execute the server code with a trigger, the token specified in the argument will be used as the caller token.
• The third argument: the AppID of the Kii Cloud application that is hosting the server code. If you want to run the server code that is hosted by other application, please specify the AppID of the application here. If the server code is hosted by the same application (i.e., the application specified when you initialize api), you can specify a null value.
• The fourth argument: the parameter to be passed to the endpoint. The parameter is to be set as a JSONObject. You can set a null value if there is no parameter.

The way to initialize the execution condition of the trigger is the same as that of when you initialize a command trigger.

When the trigger is registered, you will get a Trigger instance.

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

You can use the pagination if there are many results. If there are 30 results stored in Thing Interaction Framework, for example, you can get 10 results per request (i.e., 10 results per page) and get all results in three requests.

The following is the sample code:

try {
  String paginationKey = null;

  do {
    // Get a list of server code results.
    Pair<List<TriggeredServerCodeResult>, String> results = api.listTriggeredServerCodeResults(trigger.getTriggerID(), 0, paginationKey);
    List<TriggeredServerCodeResult> serverCodeResults = results.first;

    for (TriggeredServerCodeResult serverCodeResult : serverCodeResults) {
      // Check if the server code succeeded or not and process each result.
      if (serverCodeResult.isSucceeded()) {
        String returnedValue = serverCodeResult.getReturnedValueAsString();
        Date executedAt = new Date(serverCodeResult.getExecutedAt());
      } else {
        String errorMessage = serverCodeResult.getError().getErrorMessage();
        Date executedAt = new Date(serverCodeResult.getExecutedAt());
      }
    }

    // Get the next pagination key.
    paginationKey = results.second;
  } while (paginationKey != null);
} catch (ThingIFException e) {
  // Handle the error.
}

We are getting the results stored in the server with the listTriggeredServerCodeResults method. As shown in the sample code, we need to set the trigger ID of the target trigger instance. This trigger instance has been returned when you register the trigger to Thing Interaction Framework.

The paginationKey represents the current page status. When you execute the listTriggeredServerCodeResults method with a null value, the first page is returned with the next pagination key being set in the second. You can get the next page by setting this value as the pagination key of the next listTriggeredServerCodeResults execution. When all results are obtained, a null value will be returned as the pagination key.

In the second argument of the listTriggeredServerCodeResults method, you can specify the number of results to get (i.e., the size of the page). If you set the number to 0 or below, the server will apply the optimal setting. The size of the page here will be handled in a best-effort manner, so the actual number of results obtained can be smaller than the specified number. The results that could not be retrieved can be obtained on the next page.

The list of results is stored in the results.first. As shown in the sample code, you can check the time when the server code was executed and if the execution was a success. If the execution succeeded, you can get the returned value. If the execution failed, you can get an error message. We are getting the returned value as a string in the sample code. You can, of course, code your application to get the returned value in other formats, like integer and JSON.