gas-tools

This is a set of tools to help develop Google Apps Script projects. It supports development of GAS code on a local system (using your favourite editor and version control system), transfer of the code to and from GAS project files on Google Drive, and (soon) local testing of GAS code.

The tools run under node-js and use npm package management.

Much of the original work was done in the project from which this was forked, node-google-apps-script by Dan Thareja [email protected] and Matt Condon [email protected].

Quickstart

1. Get Google Drive Credentials

You can do this one of two ways:

1. Add Drive permissions to the default Developer Console Project that is created for each Apps Script project
2. Use an independent Developer Console Project and enable the Drive API

1.1 Default Apps Script Developer Console Project

1. Access the automatically created apps script Developer Console Project by
2. Resources > Developers Console Project
3. Click on the blue link at the top (project-name - api-project-##########) to access the correct Developer Console Project
4. Enable the Google Drive API
5. Click APIs & auth in the left nav and then select APIs
6. Search for Drive and select the Google Drive API listing.
7. Click Enable API
8. Acquire Google Drive Client Secret Credentials
9. In the Credentials section, select Add credentials and choose OAuth 2.0 client ID
10. In the menu that appears, choose Other for the Application type.
11. Give it any name you like and click Create.
12. Finally, download your credentials using the Download as JSON button to the right. * Save these credentials to a location of your choosing; ~/Downloads is fine.
13. You may close the Developer Console window.

1.2 Independent Developer Console Project

1. Create a new Dev Console Project
2. Use this link to create the project. It will auto-activate the Google Drive API. * If you have multiple Google Accounts, append &authuser=1 to the end of the url to choose which account to login with. Note that authuser is zero-indexed.
3. Make sure Create a New Project is selected and hit Continue.
4. Once the project has been created, click Go to Credentials.
5. Acquire Google Drive Client Secret Credentials
6. Select Add credentials, choose the OAuth 2.0 client ID type
7. Click Configure Consent Screen.
8. Select your email address from the dropdown and assign your add-on a Project Name. * This can always be changed later.
9. Save your Consent Screen
10. In the menu that appears, choose Other for the Application type.
11. Give it any name you like and click Create.
12. Finally, download your credentials using the Download as JSON button to the right. * Save these credentials to a location of your choosing; ~/Downloads is fine.
13. You may close the Developer Console window. * To return to this project later, select Resources > Developer Console Project while editing your script. Then click the link at the top of the dialog to open the Developer Console with this project selected.

2. Authenticate the Tools

This process will set up Google Drive authentication to allow uploading and importing of the Apps Script project.

1. Run gas auth path/to/client_secret_abcd.json

• i.e. gas auth ~/Downloads/client_secret_1234567890-abcd.apps.googleusercontent.com.json

1. Follow the directions by clicking on the link generated by the script.
2. After you're successfully authenticated, feel free to delete the client_secret.json credentials file.

You can pass the option --no-launch-browser to generate a url that will give you a code to paste back into the console. This is useful if you're using ssh to develop.

3. Initialize your project

This proces will create gas-tools.json and a sub-directory where all Apps Script project files will be downloaded to. You can either use an existing project or create a new one.

3.1 An existing Apps Script project

1. Navigate to your Apps Script project from Google Drive (must be a standalone script)
2. Get your project ID from the address bar, located after /d/ and before /edit.

• For example, '//script.google.com/a/google.com/d/abc123-xyz098/edit?usp=drive_web'

1. Navigate to a directory where your Apps Script project will live
2. Run gas init <fileId> within your project directory.

• For example, gas init abc123-xyz098

3.2 A new Apps Script project

1. Head to https://script.google.com and create a new blank project.
2. Save the mostly empty project and give it a name.

• Saving is important; the project is not in your Google Drive until it is saved.

1. Get your project ID from the address bar, located after /d/ and before /edit.

• For example, '//script.google.com/a/google.com/d/abc123-xyz098/edit?usp=drive_web'

1. Navigate to a directory where your Apps Script project will live
2. Run gas init <fileId> within your project directory.

• For example, gas init abc123-xyz098

4. Develop locally

Start scripting and enjoy total freedom of your local dev environment and source control options! Create script files with a .gs or .js extension and html files with a .html extension

5. Upload New Files

Run gas upload from within your project directory. You should then be able to reload your Apps Script project in the browser and see the changes.

Usage

gas auth

  Usage: gas auth [options] <path/to/client/secret.json>

  Authorize gas to use the Google Drive API

  Options:

    -b, --no-launch-browser  Do not use a local webserver to capture oauth code
                              and instead require copy/paste of key returned in
                              the browser after authorization completes.
    -p, --port [port]        Port to use for webserver

Performs the authentication flow described in the quickstart above.

gas init

  Usage: gas init|clone <fileId> [options]

  Initialize project locally. The external Apps Script project must exist.

  Options:
    -s, --subdir [subdir]
    -o, --overwrite

Creates gas-tools.json, which contains information about your Apps Script project and downloads all project files into a subdirectory (default: src/)

gas upload

  Usage: gas upload|push

  Upload back to Google Drive. Run from root of project directory

Upload the project to Google Drive. Sources files from ./src or the configured subdirectory.

Development

Ensure that both before and after you make any changes that all the tests run by npm test pass.

If you want to use a development version of the command line tool in other projects, you can run npm link from the root directory of the repo to symlink to your local copy. If you already have another version installed, you can uninstall it first with npm uninstall -g *package_name*

Please submit any bugs to the Issues page. Pull Requests also welcome.

Testing

The test suite is still under construction, but consists of unit tests and functional tests. There are gulp targets to find and run the various kinds of tests, and the tests themselves use the tape framework.

Unit Tests

Unit tests are in *.jt files anywhere in the repo (excepting directories and files that either start with a dot or are ignored by .gitignore). The build system will find these and execute them individually by running node on them.

These tests should run without any special setup.

Functional Tests

Functional tests are under the t/ subdirectory. While these can load and run JavaScript code just like the unit tests do, they typically go beyond this to run command-line programs, create and check files, access Google Drive via the REST API, and the like.

To run them you will need to authenticate yourself to use the Google Drive API using the gas auth subcommand.

Limitations

The upload/download tools allow you to nest files in folders, but the Apps Script platform expects a flat file structure. Because of this, no files can have the same name, even if they are in separate directories. One file will overwrite the other, making debugging difficult.

Your add-on must be developed as a standalone script and tested within Doc or Sheet. This means that it cannot use certain functions of bound scripts, namely installable triggers. While testing within a Doc, you have access to the "Special methods" mentioned in the docs, though. If you followed the quickstart above, you should be set up correctly.

Common Issues

The Google Drive API frequently returns a 400 error without a helpful error message. Common causes for this are:

• javascript formatting errors
  • The server-side javascript code (.js or .gs) is validated upon upload.
  • If there is a syntax error, the upload will fail.
• The project does not exist yet.
  • Verify that the project exists in your Google Drive folder.
  • If you have been added to an existing project, verify that the owner has shared the file with you with the "can edit" permission.
• Missing server-side libraries
  • verify that any required Libraries (frequently Underscore or OAuth2) have been added to the Apps Script project
• Authentication error
  • Verify that ~/.gapps exists and has 4 values: client_id, client_secret, redirect_uri, and refresh_token`
  • To reset authentication, 'rm ~/.gapps' and then perform the authentication steps in part #2 of the quickstart again.

References

The following documentation and articles may be useful in giving background on this tool, similar tools, and how they can be used.

• Google Apps Script Documentation
• Matt Hessinger, Advanced development process with apps