Managing Triggers

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

Deleting a Trigger
Enabling and Disabling a Trigger
Getting a Trigger
Updating a Trigger
Getting a List of Triggers

In any case, you need to get api, a ThingIFAPI instance, that is initialized by the steps described in Initialize Thing-IF SDK prior to executing the features.

Deleting a Trigger

The following is a sample code for deleting a trigger.

const triggerID = trigger.triggerID;

// Delete a trigger.
api.deleteTrigger(triggerID).then((triggerID: string) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = trigger.triggerID;

// Delete a trigger.
api.deleteTrigger(triggerID).then(
  function(triggerID) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

You need to have a triggerID to delete the trigger. You can get the triggerID from the triggerID property of the Trigger class.

You can get trigger, a Trigger instance, when you register a trigger or when you get a list of triggers.

The trigger ID will be returned when the trigger is successfully deleted.

Enabling and Disabling a Trigger

You can enable or disable a trigger that is registered on the server. The disabled trigger will not be executed even if its condition is met.

The following sample code shows how to disable a trigger.

const triggerID = trigger.triggerID;

// Disable a trigger.
api.enableTrigger(triggerID, false).then((trigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = trigger.triggerID;

// Disable a trigger.
api.enableTrigger(triggerID, false).then(
  function(trigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

In this example, we are disabling the trigger by setting the second argument of enableTrigger to false. If you want to enable the trigger, set it to true.

You need to have the triggerID to enable/disable the trigger. You can get the triggerID from the triggerID property of the Trigger.

You can get trigger, a Trigger instance, when you register a trigger or when you get a list of triggers.

Getting a Trigger

You can get an existing trigger.

The following sample code shows how to get a trigger.

const triggerID = "_trigger_id_";

// Get a trigger to update.
api.getTrigger(triggerID).then((trigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

var triggerID = "_trigger_id_";

// Get a trigger to update.
api.getTrigger(triggerID).then(
  function(trigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

When the method successfully completes, the obtained trigger is stored in the argument trigger.

You need to have a triggerID to get a trigger. You can get the triggerID from the triggerID property.

You can get trigger, a Trigger instance, also when you register a trigger or when you get a list of triggers.

Updating a Trigger

You can update a registered trigger with a new process to execute, execution condition, and so on.

The following sample code shows how to update the trigger registered in the example in Registering Advanced Triggers.

The original trigger turns on the air conditioner when the thermometer device goes over 30 degrees Celsius. This sample code updates the execution condition to "when the thermometer device goes over 28 degrees Celsius" and the trigger description correspondingly.

// Get a trigger to update.
let triggerOrg: ThingIF.Trigger;
// triggerOrg = ...

// Create a command from the existing trigger.
const commandOrg = triggerOrg.command;
const command = new ThingIF.TriggerCommandObject(
                  commandOrg.schema, commandOrg.schemaVersion, commandOrg.actions,
                  commandOrg.targetID, commandOrg.issuerID,
                  commandOrg.title, commandOrg.description, commandOrg.metadata);

// Create a new predicate.
const condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 28));
const predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);

// Set a new description.
const description = "Power on when the temperature goes over 28 deg C";

// Create a new trigger request.
const triggerRequest = new ThingIF.PatchCommandTriggerRequest(command, predicate, triggerOrg.triggerTitle, description, triggerOrg.metadata);

// Patch the existing trigger.
api.patchCommandTrigger(triggerOrg.triggerID, triggerRequest).then((updatedTrigger: ThingIF.Trigger) => {
  // Do something.
}).catch((error: ThingIF.ThingIFError) => {
  // Handle the error.
});

// Get a trigger to update.
var triggerOrg;
// triggerOrg = ...

// Create a command from the existing trigger.
var commandOrg = triggerOrg.command;
var command = new ThingIF.TriggerCommandObject(
                  commandOrg.schema, commandOrg.schemaVersion, commandOrg.actions,
                  commandOrg.targetID, commandOrg.issuerID,
                  commandOrg.title, commandOrg.description, commandOrg.metadata);

// Create a new predicate.
var condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 28));
var predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);

// Set a new description.
var description = "Power on when the temperature goes over 28 deg C";

// Create a new trigger request.
var triggerRequest = new ThingIF.PatchCommandTriggerRequest(command, predicate, triggerOrg.triggerTitle, description, triggerOrg.metadata);

// Patch the existing trigger.
api.patchCommandTrigger(triggerOrg.triggerID, triggerRequest).then(
  function(updatedTrigger) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
  }
);

The general process of updating a trigger consists of the following three steps: getting the trigger to update, separately updating the trigger components, TriggerCommandObject (command), StatePredicate (execution condition), and the trigger details, and calling patchCommandTrigger with those components as arguments. New trigger components such as a new command and trigger details are created by copying the original trigger definition and overwriting the parts which need update.

The following processes are executed in the code:

Get the trigger to update in triggerOrg. You can get a Trigger instance when you register a trigger or when you get a list of triggers.
Create a new command to update the trigger with a TriggerCommandObject. This sample code creates an instance without any changes in the original command and updates the trigger. If you need to change any parts of the command, specify new values in the parameters of the constructor. See Registering Advanced Triggers to learn how to specify the parameters.
Create a new execution condition as a StatePredicate. See Trigger Execution Conditions to learn how to specify the execution condition.
Create new trigger details to update the trigger with a PatchCommandTriggerRequest. Specify new values in the third and subsequent arguments. Specify the trigger details stored in triggerOrg for unchanged parameters. This sample code updates the description only.
Update the trigger registered with api, a ThingIFAPI instance which represents the thermometer device, by calling the patchCommandTrigger method with the PatchCommandTriggerRequest.
When the method successfully completes, the updated trigger will be stored in updatedTrigger.

You can update the trigger definition with the patchCommandTrigger method by specifying either or both of a TriggerCommandObject and StatePredicate. If you set a null value in any element, the null element will not be updated. You will get the same result if you set a null value in the first argument of the PatchCommandTriggerRequest in the above sample code because the TriggerCommandObject is not updated. Each field of the trigger details (title, description, and metadata in JSON format) will be updated only when a new value is specified. Otherwise, the field remains unchanged.

If you set a null value in the targetID of the TriggerCommandObject, the thing with which you register the trigger will be set as the thing that executes the command. Pay attention if the original trigger has been registered with a different thing (thermometer device) than the thing (air conditioner) which executes the command as in the above example.

If you need to update a trigger which executes server code, create new endpoint information as a ServerCode and execute the patchServerCodeTrigger method. See Server Code Triggers and the JSDoc to learn how to specify the endpoint information.

Getting a List of Triggers

You can get a list of all triggers that are registered on the server.

If there are many registered triggers, you can use the pagination. If there are 30 registered triggers, for example, you can get ten triggers per page. In this case, you can get all triggers by parsing three pages, ten triggers at a time.

The following is the sample code.

const callback = (error: Error, results: ThingIF.QueryResult<ThingIF.Trigger>)=> {
  if (error) {
    // Handle the error.
    return;
  }

  // Do something with each trigger.
  for (const trigger of results.results) {
    const triggerCommand = trigger.command;
    const triggerPredicate = trigger.predicate;
  }

  // If the next page exists
  if (results.paginationKey) {
    // Get the next page of the list.
    api.listTriggers(new ThingIF.ListQueryOptions(null, results.paginationKey), callback);
  }
};

// Get a list of triggers.
api.listTriggers(new ThingIF.ListQueryOptions(10), callback);

var callback = function(error, results) {
  if (error) {
    // Handle the error.
    return;
  }

  // Do something with each trigger.
  for (var i = 0; i < results.results.length; i++) {
    var trigger = results.results[i];
    var triggerCommand = trigger.command;
    var triggerPredicate = trigger.predicate;
  }

  // If the next page exists
  if (results.paginationKey) {
    // Get the next page of the list.
    api.listTriggers(new ThingIF.ListQueryOptions(null, results.paginationKey), callback);
  }
};

// Get a list of triggers.
api.listTriggers(new ThingIF.ListQueryOptions(10), callback);

As shown in the sample code, you can get a list of triggers with the listTriggers method. The sample code uses a callback because you need to create a recursive loop structure to get all triggers, though this method supports promises. See the implementation example in Querying KiiObjects to learn how to create a loop with promises.

The second argument of the ListQueryOptions specified in the listTriggers method indicates the current page. Specifying the ListQueryOptions without the pagination key returns the first page. results.paginationKey returns the next pagination key when a list of triggers is retrieved with the callback of the listTriggers method. Get subsequent commands by specifying the next pagination key. When all triggers are retrieved, the value of results.pagenationKey in the callback becomes undefined.

The first argument of the ListQueryOptions is the number of triggers to be retrieved on one page. If you do not specify the argument or set a null value, the value configured on the server side will be automatically used. Triggers are retrieved on a best effort basis and you might not be able to get the specified number of triggers. The triggers which are not retrieved on a page will be retrieved on a next page.

triggers in the callback contains a list of retrieved triggers. You can get the command and the conditions in the trigger.