Managing Triggers

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

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.

let triggerID = trigger.triggerID

// Delete a trigger.
api.deleteTrigger(triggerID) { (triggerID: string!, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

You need to have a triggerID to delete the trigger. You can get the triggerID from trigger's triggerID.

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.

let triggerID = trigger.triggerID

// Disable a trigger.
api.enableTrigger(triggerID, enable: false) { (trigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

In this example, we are disabling the trigger by setting the enabled parameter of the enableTrigger to false. If you want to enable the trigger, please set the enabled to true instead.

You need to have the triggerID to enable/disable the trigger. You can get the triggerID from trigger's triggerID.

You can get trigger, a Trigger instance, 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.
var triggerOrg: Trigger
// triggerOrg = ...

// Create a command form from the existing trigger.
let form = TriggeredCommandForm(command: triggerOrg.command!);

// Create a new predicate.
let condition = Condition(clause:RangeClause(field: "currentTemperature", lowerLimitInt: 28, lowerIncluded: true))
let predicate = StatePredicate(condition: condition, triggersWhen: TriggersWhen.CONDITION_FALSE_TO_TRUE)

// Set a new description.
let options = TriggerOptions(triggerDescription: "Power on when the temperature goes over 28 deg C")

// Patch the existing trigger.
let triggerID = triggerOrg.triggerID
api.patchTrigger(triggerID, form: form, predicate: predicate, options: options) { (updatedTrigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

The general process of updating a trigger consists of the following three steps: getting the trigger to update, separately updating the trigger components, TriggeredCommandForm (command) or ServerCode (server code), StatePredicate (execution condition), and TriggerOptions (trigger details), and calling patchTrigger 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 it or when you get a list of triggers.

  • Create a TriggeredCommandForm from the command in triggerOrg.command. Though this sample code passes the data in triggerOrg.command to patchTrigger without any changes, if you need to change any parts of the command, specify new values in the parameters of the initializer and create a TriggeredCommandForm. See Registering Advanced Triggers to learn how to specify the command definition.

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

  • Create a new execution condition as a StatePredicate. See Trigger Execution Conditions to learn how to specify the execution condition.

  • Create a TriggerOptions from triggerOrg with the new triggerDescription. See Registering Advanced Triggers to learn how to specify the trigger details.

  • Update the trigger registered with api, a ThingIFAPI instance which represents the thermometer device, by calling the patchTrigger method with the triggerID and created TriggeredCommandForm, StatePredicate, and TriggerOptions specified.

  • When the method successfully completes, the updated trigger will be stored in the callback's updatedTrigger.

You can update the trigger definition with the patchTrigger method by specifying either or both of a TriggeredCommandForm and StatePredicate. If you omit any element, the omitted element will not be updated. For example, you will get the same result if you omit the TriggeredCommandForm in the above sample code. Each field of the TriggerOptions will be updated only when a new value is specified. Otherwise, the field remains unchanged.

If you set a nil value in the targetID of the TriggeredCommandForm, 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.

Getting a Trigger

You can get an existing trigger.

The following sample code shows how to get a trigger.

let triggerID = "_trigger_id_"

// Get a trigger.
api.getTrigger(triggerID) { (trigger: Trigger?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
}

When the method successfully completes, the obtained trigger is stored in the callback's trigger.

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

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

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.

// Get a list of triggers.
api.listTriggers(nil, paginationKey: nil) { (triggers: [Trigger]?, paginationKey: String?, error :ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }

  // Do something with each trigger.
  for trigger in triggers! {
    let triggerCommand = trigger.command
    let triggerPredicate = trigger.predicate
  }

  // If the next page exists
  if paginationKey != nil {
    // Get the next page of the list.
    api.listTriggers(nil, paginationKey: paginationKey) { (triggers: [Trigger]?, paginationKey: String?, error :ThingIFError?) -> Void in
      if error != nil {
        // Handle the error.
        return
      }

      // Do something with each trigger.
    }
  }
}

As shown in the sample code, you can get a list of triggers with the listTriggers method.

The paginationKey represents the current page status. When you execute the listTriggers method with a nil value, the first page is returned with the next pagination key being set in the callback's pageneationKey. You can get the next page by setting this value as the pagination key of the next listTriggers execution. When all triggers are obtained, a nil value will be returned as the callback's pageneationKey.

The first argument of the listTriggers denotes the number of triggers to get (i.e., the size of a page). If you set a nil value, the server will apply the optimal setting. The size of the page set here will be handled in a best-effort manner, so the actual number of triggers obtained can be smaller than the specified number. The triggers that could not be retrieved can be obtained on the next page.

The list of triggers is stored in the callback's triggers. You can get the command and the conditions in the trigger.