Google Apps Script

Managing Triggers Programmatically

The Script Service in Google Apps Script enables you to manage triggers programmatically. For example, when users execute scripts from a Spreadsheet menu, the script can programmatically create a trigger. By using the Script Service to programmatically create triggers, end-users no longer need to go into the Script Editor to create triggers themselves.

Each trigger object has four properties.

  1. Unique ID: Each trigger has a unique ID. This ID is unique for each and every trigger that belongs to the user. You can fetch this property using Trigger.getUniqueId().
  2. Event Type: This describes the type of event on which the trigger executes. You can retrieve this property using Trigger.getEventType(). There are a number of event types as described in the enum ScriptApp.EventType. For example, an EventType could be CLOCK, meaning it is a time-based trigger, or ON_OPEN, meaning it is a trigger that is executed when a Spreadsheet is opened.
  3. Handler Function: The handler function is the function that will be called when the trigger is executed. You can fetch this property using Trigger.getHandlerFunction().
  4. Trigger Source: A trigger is executed when an event occurs that the trigger is listening to. Each trigger is associated with an EventType as well as a source. The source for a trigger can be fetched using Trigger.getTriggerSource(), and its value is represented by an enum in ScriptApp.TriggerSource.

Creating Triggers

To create new triggers, create a TriggerBuilder and specify the handler function using ScriptApp.newTrigger(). After you create a TriggerBuilder, you can specify the source of the trigger events. For example, your trigger events could be time-based or based on Spreadsheet events. Once you have selected the source, configure your trigger with the trigger-specific settings. For example, for Spreadsheet triggers, you can configure the type of event that the trigger will listen to, such as onEdit.

Below are examples that demonstrate how to create various time-driven and Spreadsheet triggers.

// Create a time-driven trigger
function createTimeTrigger() {
  // trigger every 6 hours
  var everySixHours = ScriptApp.newTrigger("runCommand")
      .timeBased()
      .everyHours(6)
      .create();

  // One-time execution only
  // Use JavaScript Date of 5/17/2012
  var date = new Date(2012, 5, 17);
  var oneTimeOnly = ScriptApp.newTrigger("runCommand")
      .timeBased()
      .at(date)
      .create();

  // Once a week at 06:00
  var onceAWeek = ScriptApp.newTrigger("runCommand")
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(6)
      .create();

  // Each trigger has a unique ID
  Logger.log("Unique ID of Trigger: " + everySixHours.getUniqueId());
}

function createSpreadsheetTrigger() {
  // Get spreadsheet key
  var spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
  var ssId = spreadsheet.getId();

  // Create onEdit trigger using the Spreadsheet
  var onEditTrigger = ScriptApp.newTrigger("runCommand")
      .forSpreadsheet(spreadsheet)
      .onEdit()
      .create();

  // Create onEdit trigger using sheet ID
  var onEditTrigger = ScriptApp.newTrigger("runCommand")
      .forSpreadsheet(ssId)
      .onEdit()
      .create();
}

Modifying and Deleting Triggers

The only way to programmatically modify an existing trigger is to delete it and then create a new one. To delete a trigger, you need to first get a reference to the trigger object you want to delete. Then call ScriptApp.deleteTrigger(), passing in the trigger object you want to delete. The sample below demonstrates how you can delete a trigger with a given unique trigger ID.

// Delete a trigger with the given unique ID
function deleteTrigger(triggerId) {
  // Locate a trigger by unique ID
  var allTriggers = ScriptApp.getProjectTriggers();
  // Loop over all triggers
  for (var i = 0; i < allTriggers.length; i++) {
    if (allTriggers[i].getUniqueId() == triggerId) {
      // Found the trigger and now delete it
      ScriptApp.deleteTrigger(allTriggers[i]);
      break;
    }
  }
}

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.