Visualizing Apps Script dependencies

dependencyForce

If you use a lot of libraries, sometimes things get a bit messy. You delete an old version to clean up and suddenly notice a few days later that things stop working because it's being referenced by some project. Apps Script does not provide any tools to help you track down what's gone wrong. If you are using a development mode, deleting the version that was first referenced in your project will also cause it to fail, even though you are not actually using that version. 

With all that going on, I thought it would be useful to have a way of exploring which libraries are being used by which projects. This is a force directed visualization using d3.js to take the dependency data created by Getting your apps scripts to Github.

GasGit info

This visualization is a webapp that directly accesses the info.json files created for each project by GasGit. So you have to use GasGit to extract and analyze the scripts you want to visualize. You don't have to write them up to gitHub, but you do need to do those first steps - so take a look at  Getting your apps scripts to Github for how to prepare your scripts for visualization. 

Example

I've visualized all my public Apps Script projects and they should be shown in live visualization below, or at this link. It takes a little while to load as it has to read several hundred drive files. It does use caching so sometimes it will be ok.


It uses a similar technique to Node focus explorer without excel which visualizes a web site via its topics. Here's a quick walkthrough of what you're looking at




Each orange node is a separate Apps Script github project repo. The blue nodes are the dependencies (Apps Script libraries needed - both directly and indirectly - by each of those projects). Each orange is connected to its blue dependencies. The bigger the node, the more dependencies/projects are connected.

Focusing in

Clicking on a node will show only that node's connections, so below I can see that my gasGit project needs the libraries shown.

Hovering

Hovering over a node will show the project key as well as the name and version number
and hovering over a link will show details of the connection

Other views

Clicking on a library willl show all the projects it's connected to

and further clicking on any of the connected projects will show which other libraries they are using - and so on.

Development mode

If a library is being referenced in development mode, maybe that's what you intend, but often you leave it turned that way accidentally. Especially if you are using a library that has a reference to another library in development mode. Development mode dependencies are shown in green - so i can see from below that I'm accessing the cDelegateMemory library from quite a few places in development mode.

Looking into that a little more, I discover that I'm accessing that library from 2 libraries that are themselves  production, so that flags up a potential issue. This is the main reason I created this visualization - to find exactly this scenario.

Parameters

The webapp takes 2 optional parameters
  • nocache=1 - don't use cache. Useful if you've just refreshed your extraction folder
  • start=/some/drive/path. Can be used to override the default Extract.to folder  for example if you only want to viz one project
Searching

I didn't bother putting a text search - you can simply use the browser's control/f search to find nodes, and it will highlight them.


Getting started

You can get the code and its dependencies from GitHub. You'll also need GasGit, which you can also get on GitHub (remember that you need to run the doExtraction and doLibraries phases of GasGit to create the files that dependencyForce needs). In both cases the libraries used are described there. You'll also find all the dependency source if you prefer not to use libraries.

I use the Drive json API rather than the native Apps Script services, so you'll also need to set up Oauth2. It's exactly the same process as described in Getting your apps scripts to Github and the doget patterns for this are included in the project sources.

Setting up your environment

You will need to have run GasGit for the projects you want to analyze, and setting up for dependenctForce is similar
  • Enable the drive API in the Advanced Services and the cloud console and get some credentials
  • Do your one off credentials setup by running the code in the onetimesetup module.
  • In the settings module, set extract.to to the Drive folder that is the root for your local git repos. This is the same setting you would have used for Gasgit
  • Publish your app, and it will give you the callback url to add to the cloud console.
That's it-  you should now be able to visualize all your libraries and projects.

For more on drive SDK see Using Drive SDK

You want to learn Google Apps Script?

Learning Apps Script, (and transitioning from VBA) are covered comprehensively in my my book, Going Gas - from VBA to Apps script, available All formats are available now from O'Reilly,Amazon and all good bookshops. You can also read a preview on O'Reilly

If you prefer Video style learning I also have two courses available. also published by O'Reilly.
Google Apps Script for Developers and Google Apps Script for Beginners.



Comments