Click here to see your recently viewed pages and most viewed pages.
Hide
Apps Script

Class ScriptApp

ScriptApp

Access and manipulate script publishing and triggers. This class allows users to create script triggers and control publishing the script as a service.

Properties

PropertyTypeDescription
AuthModeAuthModeAn enumeration that identifies which categories of authorized services Apps Script is able to execute through a triggered function.
AuthorizationStatusAuthorizationStatusAn enumeration denoting the authorization status of a script.
EventTypeEventTypeAn enumeration denoting the type of triggered event.
InstallationSourceInstallationSourceAn enumeration that indicates how the script came to be installed as an add-on for the current user.
TriggerSourceTriggerSourceAn enumeration denoting the source of the event that causes the trigger to fire.
WeekDayWeekdayAn enumeration representing the days of the week.

Methods

MethodReturn typeBrief description
deleteTrigger(trigger)voidRemoves the given trigger so it will no longer run.
getAuthorizationInfo(authMode)AuthorizationInfoGets an object used to determine whether the user needs to authorize this script to use one or more services, and to provide the URL for an authorization dialog.
getInstallationSource()InstallationSourceReturns an enum value that indicates how the script came to be installed as an add-on for the current user (for example, whether the user installed it personally through the Chrome Web Store, or whether a domain administrator installed it for all users).
getOAuthToken()StringGets the OAuth 2.0 access token for the current user.
getProjectKey()StringGets the project key of the current script.
getProjectTriggers()Trigger[]Gets all installable triggers associated with the current project.
getService()ServiceGets an object used to control publishing the script as a web app.
getUserTriggers(document)Trigger[]Gets all installable triggers owned by this user in the given document.
getUserTriggers(form)Trigger[]Gets all installable triggers owned by this user in the given form.
getUserTriggers(spreadsheet)Trigger[]Gets all installable triggers owned by this user in the given spreadsheet.
invalidateAuth()voidInvalidates the authorization this user has to execute the current script.
newStateToken()StateTokenBuilderCreates a builder for a state token that can be used in a callback API (like an OAuth flow).
newTrigger(functionName)TriggerBuilderBegins the process of creating an installable trigger that, when fired, will call a given function.

Detailed documentation

deleteTrigger(trigger)

Removes the given trigger so it will no longer run.


 // Deletes all triggers in the current project.
 var triggers = ScriptApp.getProjectTriggers();
 for (var i = 0; i < triggers.length; i++) {
   ScriptApp.deleteTrigger(triggers[i]);
 }
 

Parameters

NameTypeDescription
triggerTriggerthe trigger to delete

getAuthorizationInfo(authMode)

Gets an object used to determine whether the user needs to authorize this script to use one or more services, and to provide the URL for an authorization dialog. If the script is published as an add-on that uses installable triggers, this information can be used to control access to sections of code for which the user lacks the necessary authorization. Alternately, the add-on can ask the user to open the URL for the authorization dialog to resolve the problem.

 

 var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
 status = authInfo.getAuthorizationStatus();
 url = authInfo.getAuthorizationUrl();
 

Parameters

NameTypeDescription
authModeAuthModethe authorization mode for which authorization information is requested; in almost all cases, the value for authMode should be ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), since no other authorization mode requires that users grant authorization

Return

AuthorizationInfo — an object that can provide information about the user's authorization status


getInstallationSource()

Returns an enum value that indicates how the script came to be installed as an add-on for the current user (for example, whether the user installed it personally through the Chrome Web Store, or whether a domain administrator installed it for all users).

Return

InstallationSource


getOAuthToken()

Gets the OAuth 2.0 access token for the current user. If the script's OAuth scopes are sufficient to authorize another Google API that normally requires its own OAuth flow (like Google Picker), scripts can bypass the second authorization prompt by passing this token instead. However, not all Google OAuth scopes are available in Apps Script. The token expires after a time (a few minutes at minimum); scripts should handle authorization failures and call this method to obtain a fresh token when needed.

Return

String — a string representation of the OAuth 2.0 token


getProjectKey()

Gets the project key of the current script. The project key is a unique identifier for scripts and used to compose the callback URL used in conjunction with newStateToken().

When called in a library, this will return the project key of the outer-most script being executed.

Return

String — the project key of the current script


getProjectTriggers()

Gets all installable triggers associated with the current project.


 Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');
 

Return

Trigger[] — an array of triggers associated with this project


getService()

Gets an object used to control publishing the script as a web app.


 // Get the URL of the published web app.
 var url = ScriptApp.getService().getUrl();
 

Return

Service — an object used to observe and control publishing the script as a web app


getUserTriggers(document)

Gets all installable triggers owned by this user in the given document.


 var doc = DocumentApp.getActiveDocument();
 var triggers = ScriptApp.getUserTriggers(doc);
 // Log the handler function for the first trigger in the array.
 Logger.log(triggers[0].getHandlerFunction());
 

Parameters

NameTypeDescription
documentDocumenta Google Docs file that may contain installable triggers

Return

Trigger[] — an array of triggers owned by this user in the given document


getUserTriggers(form)

Gets all installable triggers owned by this user in the given form.


 var form = FormApp.getActiveForm();
 var triggers = ScriptApp.getUserTriggers(form);
 // Log the trigger source for the first trigger in the array.
 Logger.log(triggers[0].getTriggerSource());
 

Parameters

NameTypeDescription
formForma Google Forms file that may contain installable triggers

Return

Trigger[] — an array of triggers owned by this user in the given form


getUserTriggers(spreadsheet)

Gets all installable triggers owned by this user in the given spreadsheet.


 var ss = SpreadsheetApp.getActiveSpreadsheet();
 var triggers = ScriptApp.getUserTriggers(ss);
 // Log the event type for the first trigger in the array.
 Logger.log(triggers[0].getEventType());
 

Parameters

NameTypeDescription
spreadsheetSpreadsheeta Google Sheets file that may contain installable triggers

Return

Trigger[] — an array of triggers owned by this user in the given spreadsheet


invalidateAuth()

Invalidates the authorization this user has to execute the current script. Used to invalidate any permissions for the current script. This is especially useful for functions tagged as one-shot authorization. Since one-shot authorization functions can only be called the first run after the script has acquired authorization, if you wish to perform an action afterwards, you will have to revoke any authorization the script had, so the user can see the authorization dialog again.


 ScriptApp.invalidateAuth();
 

newStateToken()

Creates a builder for a state token that can be used in a callback API (like an OAuth flow).


 // Generate a callback URL, given the name of a callback function. The script does not need to
 // be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
 function getCallbackURL(callbackFunction) {
   // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
   var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
   var urlSuffix = '/usercallback?state=';
   var stateToken = ScriptApp.newStateToken()
       .withMethod(callbackFunction)
       .withTimeout(120)
       .createToken();
   return scriptUrl + urlSuffix + stateToken;
 }
 

In most OAuth2 flows, the state token is passed to the authorization endpoint directly (not as part of the callback URL), and the authorization endpoint then passes it as part of the callback URL.

For example:

  • The script redirects the user to OAuth2 authorize URL: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • The user clicks authorize, and the OAuth2 authorization page redirects the user back to https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • The above redirect (back to http://script.google.com/...), causes the browser request to /usercallback, which invokes the method specified by StateTokenBuilder.withMethod(method).

Return

StateTokenBuilder — an object used to continue the state-token-building process


newTrigger(functionName)

Begins the process of creating an installable trigger that, when fired, will call a given function.


 // Creates an edit trigger for a spreadsheet identified by ID.
 ScriptApp.newTrigger('myFunction')
     .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
     .onEdit()
     .create();
 

Parameters

NameTypeDescription
functionNameStringthe function to call when the trigger fires

Return

TriggerBuilder — an object used to continue the trigger-building process

Deprecated methods