Getting Started with Google Apps Script

If you have never opened Apps Script and want to run one of the OpenRights avails converters, this tutorial is the prerequisite. It takes about fifteen minutes. No prior JavaScript experience needed — you are pasting a prewritten script and learning how to run it safely.

What Apps Script actually is

Apps Script is a JavaScript runtime that lives inside your Google account. Any Google Sheet can have a script attached to it; the script can read and write cells, call Google APIs like Drive or Gmail, and hit external URLs. It runs in Google’s sandbox, so there is no file to install and nothing to configure on your machine.

Two things to know up front:

1. Scripts are bound to a specific Sheet by default. When you add a script through Extensions → Apps Script, the script only has access to that one workbook. This is usually what you want.
2. Scripts need explicit permission for each Google API they touch. The first time a script runs, Google asks you to authorize it. For personal scripts you wrote yourself (or copied from somewhere trusted), this prompt includes a scary-looking “unverified app” warning. That warning is about Google’s developer-verification program, not your script’s safety.

Step 1: Open the Apps Script editor

Create a new Google Sheet, or open an existing one. From the menu, choose Extensions → Apps Script. A new tab opens with a blank editor and one default file called Code.gs. The .gs extension is just “Google Script” — it is plain JavaScript.

By default the starter code looks like:

function myFunction() {
}

Step 2: Paste your first function

Replace that with a function that writes something to the current sheet:

function writeHello() {
  const sheet = SpreadsheetApp.getActiveSheet();
  sheet.getRange("A1").setValue("Hello from Apps Script");
}

Hit Save (floppy icon or Ctrl+S). Give the project a name when prompted — OpenRights Scratch is fine for learning.

Step 3: Run and authorize

At the top of the editor, select writeHello from the function dropdown and click Run.

The first run triggers the authorization flow:

1. Google asks which account to authorize with — pick the account that owns the Sheet.
2. A consent screen appears listing the permissions your script wants. For writeHello, that is “See, edit, create, and delete your spreadsheets in Google Drive.”
3. If you built the script yourself (or pasted it from a trusted source), you will see an unverified warning. Click Advanced, then Go to (project name) (unverified). This is expected for personal scripts — Google’s verification program is for apps distributed to third parties, not for scripts you run on your own sheets.
4. Click Allow.

Check the spreadsheet tab. Cell A1 should read “Hello from Apps Script”.

Step 4: Add the OAuth scopes your script needs

For simple read/write Sheet scripts, Apps Script figures out the permissions automatically. But for scripts that do more — export an .xlsx to Drive, call an external URL — you need to declare scopes explicitly in the project manifest.

To edit the manifest:

1. Click the gear icon (Project Settings) in the left sidebar.
2. Check Show “appsscript.json” manifest file in editor.
3. Open appsscript.json from the file list on the left.

For the OpenRights avails converter, the manifest needs these scopes:

{
  "timeZone": "America/New_York",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/script.external_request"
  ],
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

What each scope actually does:

• spreadsheets — read and write cells in the attached sheet.
• drive — needed to export the workbook as .xlsx (Google’s Drive export endpoint is the underlying mechanism).
• script.external_request — needed if the script calls UrlFetchApp.fetch. The Drive export uses this because it hits a Google API URL.

Save the manifest. The next time you run the script, Google will ask for the new permissions.

Step 5: Bind a custom menu to the sheet

Running scripts from the editor is fine when you are developing. For everyday use, add a custom menu to the spreadsheet itself. Add this to your script:

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("OpenRights")
    .addItem("Say hello", "writeHello")
    .addToUi();
}

onOpen is a reserved function name — Apps Script runs it automatically when the spreadsheet opens. Reload the Sheet tab and you should see an OpenRights menu appear next to Help. Click it, then Say hello, and the cell updates without touching the editor.

Next step

You are set up. Now run the OpenRights converters:

• Convert Avails to EMA with Google Apps Script — single-output EMA Movies or TV.
• Convert Generic Avails to Per-Platform Sheets — EMA Movies, EMA TV, Amazon PVD, Google Play, and Apple iTunes in one run.