Apps Script – How to deploy a library

Apps Script libraries

In this post we’re going to look at how we can connect an Apps Script project to a library file. So, first, why would we want to do that?

1. You want to connect to an external project, which you haven’t written. There’s an example of this in my post on how to create short URLs for pre-filled Google Forms, where my code connects to a library written by Martin Hawksey.
2. You want to connect to a central project, so that any updates are quicker and can be easily controlled. We will look at an example of this in this post.

Sometimes I have situations where I need multiple Google Sheets but the code each one runs is the same. For example, if each Google Sheet needs to be accessed by different people. So, rather than copying the code into each sheet project, then potentially having to update the code by copying and pasting every time there is a change, what we can do is connect those separate sheets to a central script file, then use the version history to keep all of them up-to-date.

So, in this example we have a script in an Apps Script file on my Drive, which will make and send reports to students using data in the spreadsheets. We connect the sheets to that script file by using a library.

Each of the spreadsheets has a class with their emails and marks.

The script then makes a Google Doc report using the data from the spreadsheet, adds a link to the sheet, and also emails a PDF version of it to the students.

In summary, we’re going to look at:

1. Deploying a new library
2. Connecting a Script project to a library
3. Updating the library version
4. Using Development mode

Deploying a new library

First, let’s look at how we set up a new library deployment.

In the Script file where the code lives, click on the Deploy button and “New Deployment”.

Click the “Select type” cog wheel icon.

Select “Library” from the menu.

Type in a description for this version.

It can be anything you want. Plus, it will automatically call this version 1.

Click the Deploy button.

You will see this confirmation screen. You’re going to need the Script ID BUT BEWARE it’s not on this page. A common mistake (and I’ve made this) is to copy the Deployment ID, but this is not what we need to set up the library. Just click Done. To be honest, I don’t know why they don’t include the Script ID on this page too.

Getting the Script ID for the library

The script ID is hiding in the “Project Settings” section which you’ll find in the menu on the left-hand side of the editor. Click on that.

Then click “Copy” in the Script ID section.

Connecting a project to a library

Now open the script project in the file you want to connect to the library. In this example, it’s a Google Sheet with the student marks.

Click on the plus sign next to Libraries.

Under Add a library, paste in the Script ID you just copied.

Then click on the “Look up” button.

If it finds it, then you will see the version and identifier sections appear.

If your code is ready to be used, change “HEAD (Development mode)” to version 1 (or the latest version if you have one later). Then click “Add”.

Go through the usual permission authorization. (See this post if you need help with that).

Then you will see the library appear under libraries. Note, you can connect to more than one library.

Setting up the functions

Now, we’re ready to work with the library. The following steps are in the script editor in the file that is calling the library.

There are a couple of key things you need to do.

1. You need to set up functions to be able to run any of the functions in the library. The function names don’t need to be the same as the ones in the library, but sometimes it can help to know what you’re calling.
2. You use the library name to refer to the library and then after a dot add the name of the function in the library you want to call. the editor will show you what ones are available.

So, for example, the library is in the script file on my Drive called “makeSendReportsLibrary”. I want to run the makeSendReports function in it.

I’ve wrapped all this up in a function called makeSendReports but it could be called something else, it doesn’t have to be the same as the function name in the library.

Running the project

From the script editor in the Google Sheet, I run the makeSendReports function.

This will get the data on the sheet, create a Google Doc report for each student, adding their details and marks to it, add a link to the Docs, then will email a PDF version of that to the student and finally will add the status SENT to the sheet.

The students receive this email with their report.

Making copies of the file

The good thing is that if you set up a master sheet which is connected to the library, if you make a copy of the file, then the copy will also automatically be connected to the library and will be connected to the same version. So, usually I make master file, connect the library, then make copies of that file.

Updating the library version

So, what happens if you want to make any changes to the script? You will need to make those changes in the library and then update the version number in each of the files that is connected to it.

So, for example, let’s update the report script, so that we add an onOpen function to create a menu when the file is opened, so the function can be run from there rather than having to open the script editor.

I would, of course, do this before making copies of the file but it serves as an example of how to update the library version and how to add another function to the project.

1. function onOpen() {
2.  const ui = SpreadsheetApp.getUi();
3.  ui.createMenu('REPORTS')
4.    .addItem('Make and send reports', 'makeSendReports')
5.    .addToUi();
6. }

I’ve added this function to the makeSendReports file in a new script file.

In the script editor of the script file library (makeSendReportsLibrary), click on “Deploy” and “Manage deployments”.

This will show you the current active version. Version 1 in our example.

Click on the Version menu.

Then select “New version”.

Give the new version a description – often some notes on the latest changes. Click on “Deploy”.

You’ll then see the confirmation message.

Then go to the Google Sheet connected to the library (e.g. “2-Class marks and reports CLASS 1”). Click on the library name (e.g. “makeSendReportsLibrary”.

This will show you the current version of the library being used.

Click on the version menu and select the version you want (e.g. 2).

Then click “Save”.

In this example, we’re going to add a menu which is added when the spreadsheet is opened, so we need to set up an onOpen function, so that it is triggered when the file is opened.

Then within that we call the library name followed by a dot and you will see that we now have two functions to choose from, as there are two in the library script file. Select onOpen.

5. function onOpen(){
6.  makeSendReportsLibrary.onOpen();
7. }

This will now run the onOpen function when the file is opened and run the code within it that is in the library script file.

As you can see when we open the file, it’s added the REPORTS menu, which we can run the script from.

Making changes without changing the version number

If you make any changes to the code in the script file library, they won’t be reflected in the files as they will still be looking at a specific version. To reflect the new version you have to change the version number as we saw above.

However, sometimes you want to change the code without having to change the version number. This could be because there is a problem with the code and you’re trialing different things out to see what works, or you want to make some improvements and want to trial it out without having to officially release the next version.

Fortunately, you can do this without changing the version number. First, add the new code in the script file library. As an example, I’ve added a new function called newFunctionAdded. It doesn’t have to be a new function, you can just edit an existing one, but here I want to also show you that this new function will appear as an option in our Google Sheet script.

8. function newFunctionAdded(){
9.   const ss = SpreadsheetApp.getActiveSpreadsheet();
10.}

Next, go to the Google Sheet file and the script editor.

Click on the makeSendReportsLibrary library.

You will see it’s currently on version 2.

Click on the version and select “HEAD (Development mode)”.

Then click Save. This will allow you to access the latest code in that library, even though you haven’t created a specific version number for it yet.

Type in the new function and when you type in the library name as we did before, you will now see that we have access to that new function we created.

9. function newFunction(){
10.  makeSendReportsLibrary.newFunctionAdded();
11.}

This allows you to make multiple edits to the code without having to increase the version number every time, and it also allows you to try the new code out without affecting other files, as you have only changed this particular file.

Once you’re happy with the changes or improvements, then deploy the script again as a new version, and update the files to look for that new version number.

---

You can make a copy of the script file and Google Sheet master file here:

GOOGLE SHEET

REPORT MASTER DOC

FULL CODE – The complete code is stored on GitHub. Copy and paste it into a script file on your Drive.