Apps Script task

TheApps Script task lets you run Google Apps Script from your integration. Google Apps Script is a rapid application development platform that makes it fast and easy to create business applications. For more information, seeGoogle Apps Script. This task is useful when you want to run custom scripts or reuse existing scripts in your integration.

• Enable AppsScript API
• Create OAuth 2.0 Client ID
• Set up an authentication profile
• Ensure thatVPC Service Controls isNOT setup for Application Integration in your Google Cloud project.Warning:Cloud Function does not function or stops functioning ifVPC Service Controls is set up for Application Integration in your Google Cloud project.

Enable AppsScript API

You must enable the AppsScript API in your Google Cloud project and your AppsScript user account to use this task. For information about enabling the AppsScript API in your Google Cloud project, seeEnabling an API in a standard Google Cloud project. To enable the API in your user account, clickSettings and setGoogle Apps Script API toOn.

Create OAuth 2.0 client ID

If you have an OAuth 2.0 client ID available, you can skip this step and proceed to Set up an authentication profile.

For information about creating a new OAuth client ID, seeCreate OAuth client ID.

Set up an authentication profile

Application Integration uses the authentication profile to connect to Google Cloud for deploying and running the Apps Script project. To set up an authentication profile, perform the following steps:

Add the Apps Script task

1. In the Google Cloud console, go to theApplication Integration page.

   Go to Application Integration

2. In the navigation menu, clickIntegrations.

   TheIntegrations page appears listing all the integrations available in the Google Cloud project.

3. Select an existing integration or clickCreate integration to create a new one.

   If you are creating a new integration:

   1. Enter a name and description in theCreate Integration pane.
   2. Select a region for the integration.Note: TheRegions dropdown only lists the regions provisioned in your Google Cloud project. To provision a new region, clickEnable Region. SeeEnable new region for more information.
   3. Select a service account for the integration. You can change or update the service account details of an integration any time from theinfoIntegration summary pane in the integration toolbar.Note: The option to select a service account is displayed only if you have enabled integration governance for the selected region.
   4. ClickCreate. The newly created integration opens in theintegration editor.

4. In theintegration editor navigation bar, clickTasks to view the list of available tasks and connectors.
5. Click and place theApps Script element in the integration editor.

Create an authentication profile

1. Click theApps Script element on the designer to view theApps Script task configuration pane.
2. In the task configuration pane of the Apps Script task, click+New authentication profile.
3. In theAuthentication profile dialog, enter a name and description for the profile and set the following properties:
   • Authentication type: SelectOAuth 2.0 authorization code
   • Authentication endpoint: Enterhttps://accounts.google.com/o/oauth2/auth
   • Token endpoint: Enterhttps://oauth2.googleapis.com/token
   • Client ID: Enter the client ID.

     The Client ID is available in your Google Cloud project dashboard underCredentials > OAuth 2.0 Client IDs.

   • Secret: Enter the client secret

     The client secret is available in your Google Cloud project dashboard underCredentials > OAuth 2.0 Client IDs.

   • Scope(s): Enter the following:

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     Note: Multiple scopes can be separated by a single space character (" ").

4. ClickGenerate Access Token and Save.

   You are redirected to an authorization screen. Log in and provide consent to the permissions listed on the screen to generate your access token. If the generation of the access token is successful, your authentication profile is saved, and you can continue to edit your integration.

1. In the task configuration pane, clickConfigure Apps Script Project.

   TheApps Script Configuration dialog appears.

2. You can choose to link to an existing Apps Script project or create a new Apps Script project.

   Configuring an Apps Script project associates the Apps Script project with your integration in Application Integration.

3. Click Save.
4. ClickOpen Apps Script Project.

   In the Apps Script editor, you can see the following files:

   • Run.gs: Contains the executable code. Write your script inside therun function. This function is called when the Apps Script task executes. In your script, you can use the variables defined at the integration level. For information on using the integration variables, seeUsing integration variables.
   • Main.gs: Contains the initialization code to run Apps Script from your integration. Do not edit or modify this file.
   • Test.gs: Contains the executable code for test runs. You can write your script inside thetestRun function totest the script.

   Make sure to deploy the project inWeb apps format. Formore information on the various deployment modes, see Create and manage deployments.

Access integration variables

The Apps Script task uses theAppsScriptTask library, which enables you to use integration variables in your script. TheAppsScriptTask library is automatically imported and is available for use in therun function.

To access an integration variable in your Apps Script, you must pass the variable in the form oftask parameters to the Apps Script task. The task parameters are key-value pairs whereKey is the name of the variable in your AppsScript task and theValue is the corresponding integration variable name. You can add one or more task parameters in theTask Parameters section of the task configuration pane.

For example, if you have an integration variable namedProduct that you want to use in your Apps Script, you can defineKey asProductKey and the value asProduct. In your Apps Script, you can then useAppsScriptTask.getTaskParameter('ProductKey') to read theProduct variable.

• setIntegrationVariable
• getTaskParameter

//WritetoanIntegervariableAppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');

//ReadanintegrationvariableAppsScriptTask.getTaskParameter('EmployeeIDKey');

To view all the functions available in theAppsScriptTask library, hover over theAppsScriptTask menu item in your Apps Script editor, click Moremore_vert> Open in a new tab.

Test your Apps Script

Before publishing your integration, you can test your script using thetestRun function available in theTest.gs file. Write your test code in thetestRun function, using theAppsScriptTaskTest library. This library lets you run assertion-based test cases and is automatically imported for use in thetestRun function.

To view all the functions available in theAppsScriptTaskTest library, hover over theAppsScriptTaskTest menu item in your Apps Script editor, click Moremore_vert> Open in a new tab.

The following sample shows the usage ofAppsScriptTaskTest library functions.

functiontestRun(){//Createanewrequestletreq=AppsScriptTaskTest.createNewTestRequest('myCustomTest');//Addataskparameterthatreferencesanintegrationvariablewiththevalue5AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req,'input','$input$',5);//AddataskparameterthatreferencesanintegrationvariableAppsScriptTaskTest.createReference(req,'output','$output$');//Runthetask(assumingthetaskincrementstheinputby1)andgettheresponseletres=AppsScriptTaskTest.runTest(req,executeScript);//ChecktheresponsefortheexpectedintegrationvariableanditscorrespondingvaluesAppsScriptTaskTest.containsIntegrationVariable(res,'output',true);AppsScriptTaskTest.containsIntegrationVariable(res,'someOtherIntegrtionVariable',false);AppsScriptTaskTest.containsIntegrationVariableWithValue(res,'output',6);}

The following sample shows you how to access JSON and array variables in thetestRun method:

functiontestRun(){//Createanewrequestletreq=AppsScriptTaskTest.createNewTestRequest('json-test');//AddataskparameterthatreferencesaJSONintegrationvariableAppsScriptTaskTest.setIntegrationVariableAndCreateReference(req,"emp","employee",{name:"snape",age:35});//AddataskparameterthatreferencesanarrayintegrationvariableAppsScriptTaskTest.setIntegrationVariableAndCreateReference(req,"arr","array",["A","B","C"]);//Runthetaskandgettheresponse//Assumethattherunmethodincreasestheageoftheemployeeby5andappendsanewelementinthearrayletres=AppsScriptTaskTest.runTest(req,executeScript);//ChecktheresponsefortheexpectedintegrationvariableanditscorrespondingvaluesAppsScriptTaskTest.containsIntegrationVariableWithValue(res,"employee",{name:"snape",age:40});AppsScriptTaskTest.containsIntegrationVariable(res,"array",true);AppsScriptTaskTest.containsIntegrationVariableWithValue(res,"array",["A","B","C","D"]);}

After running the test cases, you can view the assertions in theExecution log. To view the logs, clickExecution log from the menu.

Best practices

We do not recommend using the Apps Script task if you require latency less than 1 to 2 seconds for the task in your integration.

In addition, we recommend coding all your logic in a single Apps Script task, rather than chaining multiple Apps Script tasks, to minimize performance bottlenecks.

For information about the usage limits that apply to theApps Script task, see Usage limits.

Considerations

When including the Apps Script task in your integration design, consider the following system limitations:

• Maximum active deployments for an AppsScript: 50
• Queries per second (QPS) for API executables: 5000/min
• Queries per second (QPS) for Webapp deployments: 5000/min
• Latency for API executables: 1.5s
• Latency for Webapp: 2.5s
• Maximum cumulative size of all the integration variables in an AppsScript: 15 MB

Error handling strategy

An error handling strategy for a task specifies the action to take if the task fails due to atemporary error. For information about how to use an error handling strategy, and to know about the different types of error handling strategies, seeError handling strategies.

SLA exclusions

The Apps Script task has a dependency on theGoogle Apps Script product. Because this dependency is external to the Application Integration, all executions ofactive integrations that fail because of the failure in the Apps Script task, are excluded from theApplication Integration Service Level Agreement (SLA) terms and conditions.

Quotas and limits

For information about quotas and limits, seeQuotas and limits.

What's next

• Learn aboutall tasks and triggers.
• Learn how totest and publish an integration.
• Learn abouterror handling.
• Learn aboutintegration execution logs.