Configure the Apps Script task

You're viewing Apigee X documentation.
View Apigee Edge documentation.

The Apps 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, see Google Apps Script. This task is useful when you want to run custom scripts or reuse existing scripts in your integration.

Before you begin

Before using the Apps Script task, make sure you complete the following steps:

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, see Enabling an API in a standard GCP project. To enable the API in your user account, click Settings and set Google Apps Script API to On.

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.

To create an OAuth 2.0 Client ID:

  1. In the Cloud Console, go to APIs & Services > Credentials.
  2. Click + CREATE CREDENTIALS.
  3. Select OAuth client ID from the list of available options.
  4. On the Create OAuth client ID page, select Web Application from the drop-down list in the Appication type field.
  5. (Optional) Enter a Name for your OAuth 2.0 client to identify the client in the Cloud console.
  6. Click + ADD URI to add an Authorized redirect URI in the following format:
    https://apigee.google.com/organizations/GCP_PROJECT_ID/integrations/callback
  7. Click CREATE.

Set up an authentication profile

Apigee 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:

  1. Go to the Apigee UI and sign in.
  2. Select your organization using the dropdown menu in the upper left corner of the UI.
  3. Click Develop > Integrations.
  4. Search for or select the integration to edit from the Integrations list and click to open the integration designer.
  5. Select Add a task/trigger > Tasks to view the list of available tasks.
  6. Drag the Apps Script element to the integration designer.
  7. Click the Apps Script element on the designer to view the Apps Script task configuration pane.
  8. In the task configuration pane of the Apps Script task, click +New authentication profile.
  9. In the Authentication profile dialog, enter a name and description for the profile and set the following properties:
    • Authentication type: Select OAuth 2.0 authorization code
    • Authentication endpoint: Enter https://accounts.google.com/o/oauth2/auth
    • Token endpoint: Enter https://oauth2.googleapis.com/token
    • Client ID: Enter the client ID.

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

    • Secret: Enter the client secret

      The client secret is available in your Google Cloud project dashboard under Credentials > 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 (" ").

  10. Click Generate 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.

Configuration

To configure an Apps Script project in the Apps Script task, perform the following steps:

  1. In the task configuration pane, click Configure Apps Script Project.
  2. In the Apps Script Configuration dialog, you can choose to link to an existing Apps Script project or create a new Apps Script project.

    This associates the Apps Script project with your integration.

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

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

    • Run.gs: Contains the executable code. Write your script inside the run 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, see Using 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 the testRun function to test the script.

    Make sure to deploy the project in Web apps format. For more information on the various deployment modes, see Create and manage deployments.

Use integration variables

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

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

For example, if you have an integration variable named Product that you want to use in your Apps Script, you can define Key as ProductKey and the value as Product. In your Apps Script, you can then use AppsScriptTask.get('ProductKey') to read the Product variable.

The AppsScriptTask library provides the following methods to access integration variables:

  • set: Sets the value to a variable
  • get: Gets the value of a variable

The following sample script shows the usage of set and get functions.

// Read an integration variable
AppsScriptTask.getTaskParameter('EmployeeIDKey');

// Write to an Integer variable
AppsScriptTask.setIntegrationVariable('EmployeeIDKey',456');

To view all the functions available in the AppsScriptTask library, hover over the AppsScriptTask menu item in your Apps Script editor, click the vertical dots, and select Open in a new tab.

Test your Apps Script

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

To view all the functions available in the AppsScriptTaskTest library, hover over the AppsScriptTaskTest menu item in your Apps Script editor,click the vertical dots, and select Open in a new tab.

The following sample shows the usage of AppsScriptTaskTest library functions.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.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 the testRun method:

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);


  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.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 the Execution log. To view the logs, click Execution log from the menu.

Retry on failure

You can configure various retry strategies to handle errors in a task. The retry strategies allow you to specify how to rerun the task in case of an error. For more information, see Error handling strategies.

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.

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