Auto Execution with Triggers
By using the trigger feature, you can automatically execute a command or server code when a predefined execution condition is met.
The table below shows the supported combinations of execution conditions and actions:
Command | Server code | |
---|---|---|
One-time schedule | Yes | - |
Recurring schedule | Yes | - |
State condition | Yes | Yes |
See the related topics in the development guides for Android, iOS, JavaScript, and REST API for more details on the implementation.
Trigger execution conditions
You can use the following three conditions for the trigger execution condition.
One-time schedule
This condition will fire the trigger just once at the designated time.
Recurring schedule
This condition will fire the trigger on the scheduled interval.
State condition
This condition will fire the trigger based on the latest field values of the thing state.
The state condition is defined by the following two conditions.
Comparison conditions
You can set a condition to compare the value with the latest field value of the state. More specifically, you can set the condition to check if the field value is equal to, greater than, or less than the specified value. You can also set the condition to check if the field value is within the specified range of values. Multiple conditions can be concatenated with And and Or.
For example, you can set a condition like "When the room temperature is greater than or equal to 30 degrees" if the thing state contains the "room temperature" field.
Execution conditions
You can specify how to associate the comparison condition and the actual trigger execution. The following associations are available:
- Execute the trigger when the comparison condition is TRUE.
- Execute the trigger when the comparison condition was FALSE and becomes TRUE.
- Execute the trigger when the comparison condition changes.
For example, you will want to use the second association ("the comparison condition was FALSE and becomes TRUE") if you want to turn the air conditioner's power on when the room temperature goes over 30 degrees. If you use the first association ("the comparison condition is TRUE"), the command for turning the power on will be executed every time the thing state is updated as long as the room temperature is over 30 degrees.
If you want to set the association like "when the comparison condition is FALSE" and "when the condition was TRUE and becomes FALSE", consider reverting the comparison condition. You can also use
Equals(Clause, false)
.
Trigger execution
The command or server code set in the trigger is executed when the trigger condition is satisfied.
However, the trigger execution might be delayed when numerous triggers are attempted to execute at the same time because Kii Cloud processes triggers on a best-efforts basis.
Executing commands
A new instance of the command to execute is created by referring the command set in the trigger as a template.
Each command instance has a command ID. A unique command ID is assigned every time the command is executed. If the trigger execution condition is met multiple times, the command will be executed multiple times, and they will have different command IDs. When you get a list of commands via the mobile application API, the number of commands you will get is equal to the number of times the trigger is executed.
When the command is executed, the command result will be registered on Thing Interaction Framework per the command ID. The user who registered the trigger will receive a push notification of the command ID as with the case that the user directly executes a command.
The template of the command set in the trigger includes all action parameters. When a command instance is generated and executed, these parameters will be copied.
Execution flow of a command with a one-time schedule
By setting a trigger, you can auto-execute a command when the designated time arrives. The result of the command execution can be browsed from a mobile app by using the command listing and command result browsing features.
1. Registering triggers from the mobile app
A user registers a trigger from the mobile app. A trigger defines a command and the execution time. The command is executed when the designated time arrives.
You can register multiple triggers.
2. Auto-executing a command
If the condition of a trigger is met, Thing Interaction Framework automatically sends the corresponding command to the thing.
Just like the regular command execution, the command result will be stored in Thing Interaction Framework as the command is executed via the trigger. You can get a list of executed commands and check the command result from the mobile application.
Execution flow of a command with a state condition
By setting a trigger, you can auto-execute a command based on the state condition. The result of the command execution can be browsed from a mobile app by using the command listing and command result browsing features.
1. Registering triggers from the mobile app
A user registers a trigger from the mobile application. A trigger defines a command and associated condition. The command is executed when the designated condition is met.
You can register multiple triggers.
2. Updating state from the thing
The thing periodically updates its state by uploading its data, such as the sensor data.
3. Comparing the state
When the state is updated, Thing Interaction Framework checks all registered triggers to confirm if their conditions are met.
4. Auto-executing a command
If the condition of a trigger is met, Thing Interaction Framework automatically sends the corresponding command to the thing.
The thing that updates the state information and the thing that receives the command can be different. For example, if you manage a thermometer and an air conditioner as separate things, you can register a trigger to "turn on the air conditioner when the thermometer rises to a certain temperature". Note that the owner of the thing that updates the state information and the thing that receives the command must be the same.
Executing server code
To run server code with a trigger, you need to set the following parameters in the trigger.
Endpoint name and parameters
Set the endpoint name and parameters. The information is used when calling the JavaScript function of the server code.
Access token of the executor
Set the access token of the user who is going to execute the server code. The specified access token will be used when running the server code.
Note that the server code does not accept an access token fo a thing. Please use the access token of the thing owner or use the app admin token set in the server code.
AppID of the target application
You can execute the server code in the application other than the one in which you set the trigger. In this case, specify the AppID of the target application.
Execution flow of server code with a state condition
By setting a trigger, you can auto-execute server code as the state condition changes. The result of the server code execution (e.g., returned value from the endpoint and error) can be browsed from a mobile app.
You need to set the server code to execute before you set the trigger. See Server Extension to learn about the server code features and how to set in on the server.
1. Registering triggers from the mobile app
A user registers a trigger from the mobile app. A trigger defines the server code information (i.e., the endpoint name and parameters) and associated condition. The server code is executed when the designated condition is met.
You can register multiple triggers.
2. Updating state from the thing
The thing periodically updates its state by uploading its data, such as the sensor data.
3. Comparing the state
When the state is updated, Thing Interaction Framework checks all registered triggers to confirm if their conditions are met.
4. Auto-executing server code
If the condition of a trigger is met, Thing Interaction Framework automatically executes the server code.
Thing Interaction Framework saves the returned value from the server code and error (if any) when the server code execution is done.
5. Getting the execution result of the server code
Get the server code execution result on the mobile app if needed. The server code is executed every time the condition in the trigger is met; you can get multiple execution results.
Trigger management
You can execute the following features for managing triggers from the mobile app.
- Registering a trigger
- Deleting a trigger
- Enabling a trigger (make them active for execution)
- Disabling a trigger (make them inactive)
- Updating a trigger
- Getting a trigger
- Getting a list of registered triggers
For more details on the features, read the Thing-IF SDK development guides.