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

Property	Type	Description
`AuthMode`	`AuthMode`	An enumeration that identifies which categories of authorized services Apps Script is able to execute through a triggered function.
`AuthorizationStatus`	`AuthorizationStatus`	An enumeration denoting the authorization status of a script.
`EventType`	`EventType`	An enumeration denoting the type of triggered event.
`InstallationSource`	`InstallationSource`	An enumeration denoting how the script was installed to the user as an add-on.
`TriggerSource`	`TriggerSource`	An enumeration denoting the source of the event that causes the trigger to fire.
`WeekDay`	`Weekday`	An enumeration representing the days of the week.

Methods

Method	Return type	Brief description
`deleteTrigger(trigger)`	`void`	Removes the given trigger so it no longer runs.
`getAuthorizationInfo(authMode)`	`AuthorizationInfo`	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.
`getIdentityToken()`	`String`	Gets an OpenID Connect identity token for the effective user, if the `openid` scope has been granted.
`getInstallationSource()`	`InstallationSource`	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).
`getOAuthToken()`	`String`	Gets the OAuth 2.0 access token for the effective user.
`getProjectTriggers()`	`Trigger[]`	Gets all installable triggers associated with the current project and current user.
`getScriptId()`	`String`	Gets the script project's unique ID.
`getService()`	`Service`	Gets 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, for this script or add-on only.
`getUserTriggers(form)`	`Trigger[]`	Gets all installable triggers owned by this user in the given form, for this script or add-on only.
`getUserTriggers(spreadsheet)`	`Trigger[]`	Gets all installable triggers owned by this user in the given spreadsheet, for this script or add-on only.
`invalidateAuth()`	`void`	Invalidates the authorization the effective user has to execute the current script.
`newStateToken()`	`StateTokenBuilder`	Creates a builder for a state token that can be used in a callback API (like an OAuth flow).
`newTrigger(functionName)`	`TriggerBuilder`	Begins the process of creating an installable trigger that, when fired, calls a given function.

Deprecated methods

Method	Return type	Brief description
~~`getProjectKey()`~~	`String`	Gets the project key of the current script.
~~`getScriptTriggers()`~~	`Trigger[]`	Gets all installable triggers associated with the current project and current user.

Detailed documentation

`deleteTrigger(trigger)`

Removes the given trigger so it no longer runs.

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

Parameters

Name	Type	Description
`trigger`	`Trigger`	The trigger to delete.

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

`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

Name	Type	Description
`authMode`	`AuthMode`	the 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

`getIdentityToken()`

Gets an OpenID Connect identity token for the effective user, if the openid scope has been granted. This scope is not included by default, and you must add it as an explicit scope in the manifest file to request it. Include the scopes https://www.googleapis.com/auth/userinfo.email or https://www.googleapis.com/auth/userinfo.profile to return additional user information in the token.

The returned ID token is an encoded JSON Web Token (JWT) , and it must be decoded to extract information from it. The following examples shows how to decode the token and extract the effective user's Google profile ID.

 var 
  
 idToken 
  
 = 
  
 ScriptApp 
 . 
 getIdentityToken 
 (); 
 var 
  
 body 
  
 = 
  
 idToken 
 . 
 split 
 ( 
 '.' 
 )[ 
 1 
 ]; 
 var 
  
 decoded 
  
 = 
  
 Utilities 
 . 
 newBlob 
 ( 
 Utilities 
 . 
 base64Decode 
 ( 
 body 
 )) 
 . 
 getDataAsString 
 (); 
 var 
  
 payload 
  
 = 
  
 JSON 
 . 
 parse 
 ( 
 decoded 
 ); 
 var 
  
 profileId 
  
 = 
  
 payload 
 . 
 sub 
 ; 
 Logger 
 . 
 log 
 ( 
 'Profile ID: ' 
  
 + 
  
 profileId 
 );

See the OpenID Connect documentation for the full list of fields (claims) returned.

Return

String — The identity token if available; otherwise null .

`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 — The source of installation.

`getOAuthToken()`

Gets the OAuth 2.0 access token for the effective 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. 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.

The token returned by this method only includes scopes that the script currently needs. Scopes that were previously authorized but are no longer used by the script are not included in the returned token. If additional OAuth scopes are needed beyond what the script itself requires, they can be specified in the script's manifest file.

Return

String — A string representation of the OAuth 2.0 token.

`getProjectTriggers()`

Gets all installable triggers associated with the current project and current user.

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

Return

Trigger[] — An array of the current user's triggers associated with this project.

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

`getScriptId()`

Gets the script project's unique ID. This is the preferred method to get the unique identifier for the script project as opposed to ~~getProjectKey()~~ . This ID can be used in all places where project key was previously provided.

Return

String — The script project's ID.

`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, for this script or add-on only. This method cannot be used to see the triggers attached to other scripts.

 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

Name	Type	Description
`document`	`Document`	A Google Docs file that may contain installable triggers.

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

`getUserTriggers(form)`

Gets all installable triggers owned by this user in the given form, for this script or add-on only. This method cannot be used to see the triggers attached to other scripts.

 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

Name	Type	Description
`form`	`Form`	A Google Forms file that may contain installable triggers.

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

`getUserTriggers(spreadsheet)`

Gets all installable triggers owned by this user in the given spreadsheet, for this script or add-on only. This method cannot be used to see the triggers attached to other scripts.

 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

Name	Type	Description
`spreadsheet`	`Spreadsheet`	A Google Sheets file that may contain installable triggers.

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

`invalidateAuth()`

Invalidates the authorization the effective 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 must revoke any authorization the script had, so the user can see the authorization dialog again.

ScriptApp.invalidateAuth();

Throws

Error — when invalidation fails

`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, calls a given function.

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

Parameters

Name	Type	Description
`functionName`	`String`	The function to call when the trigger fires. You can use functions from included libraries, such as `Library.libFunction1` .

Return

TriggerBuilder — An object used to continue the trigger-building process.

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp

Deprecated methods

`getProjectKey()`

Deprecated.use getScriptId() instead.

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 returns the project key of the outer-most script being executed.

Return

String — The project key of the current script.

`getScriptTriggers()`

Deprecated.This function is deprecated and should not be used in new scripts.

Gets all installable triggers associated with the current project and current user.

Logger.log('Current script has ' + ScriptApp.getScriptTriggers().length + ' triggers.');

Return

Trigger[] — An array of the current user's triggers associated with this project.

Authorization

Scripts that use this method require authorization with one or more of the following scopes :

https://www.googleapis.com/auth/script.scriptapp