Tips and Tricks to using GAM to Manage Student G-Suite Accounts

GAM is a command line tool that allows administrators to manage many aspects of their G Suite Account. GAM requires G Suite Education. G Suite Legacy Free Edition has limited API support and not all GAM commands work. Some GAM functions require domain administrative privileges.

First, I have to say that GAM is a very powerful tool. You can accomplish many things with it in a rather short period of time. It takes a little time to get set up and configured, but once you have that done, you can do a lot of good or a lot of damage very quickly. It will not prompt you with “are you sure?”. It will just do EXACTLY what you told it to do. Trust me when I tell you, test everything on a single user first, then when you are sure that you got exactly the results that you wanted, expand it to a few more users to be sure. Then and only then should you consider running the full list of tasks that need to be accomplished.

You can find this amazing tool at https://github.com/jay0lee/GAM/wiki.

You will also want to get this incredible resource for using GAM and keep this handy. It really helps you to understand the full power of this tool and to begin to harness some of it for yourself. To learn more visit https://gamcheatsheet.com/.

We’ll start with some simple commands for a single user to get things started. If you want to simply remove the alias test.user@sps-k12.com from an existing Gmail account you can use the following command for this task.

“gam delete alias test.user@sps-k12.com”

If you were changing the domain name for a user from sps-k12.com to demo.sps-k12.com, you could use the following command to perform the task.

“gam update user test.user@sps-k12.com email test.user@demo.sps-k12.com”

This will change the google username to the @demo.sps-k12.com domain so that the user must log in with this username when accessing Google resources. It will also take the original @sps-k12.com email address and add that as an alias on the account so that email addressed to the old domain name will still be delivered to this user.

Would you like to automate provisioning for your district?

In a previous blog post, we mentioned using GAM to clean up accounts that passed your retention policy requirement and should be removed from your system. To remove a single account, you would use the following command.

“gam delete user test.user@demo.sps-k12.com”

Now, to step this up a bit, we need a larger list of users so that we can feed a list into these commands and process them for many users at a time. I prefer to use the Google Admin Console to get my list.

Login to your Google Admin Console and navigate to users. Make sure that you select “Users from all organizational units” and then click on the icon to download users.

I prefer to select then “All user info columns and currently selected columns (leave the default setting to select all 31 columns) and then choose your format.

I personally prefer “Comma-separated values (.csv)”.

Then choose “Download”. Then Google will prepare the file for you, and you must select “Download CSV” to get your file.

Now you can use this to create a list of the users that need to be modified. You can bring this file into Microsoft Excel and turn it into a table.

You could sort on the column labeled “Org Unit Path [Required]” to get a list of all the user in a particular organizational unit if you wanted to delete all of these users.

NOTE: This may not be the most practical example because now Google allows you to multi-select and delete users from an OU. They didn’t always allow that. However, if you have many pages of users to delete, this will allow you to simplify the process.

Once you have reduced the rows to be just the users that you want to perform the operation on, you can delete all other columns in the spreadsheet except for “Email Address [Required]”. Then save this file as userlist.csv and save it into the same folder where you installed the GAM tool.

You will need to remove the column header so that you only have a simple list of email addresses each on their own line in a text file. My file looks like this:

aaliyah.andrews@sps-k12.com
abigail.baldwin@sps-k12.com
ahrianna.bagley@sps-k12.com
aissata.bah@sps-k12.com
alakee.badaru@sps-k12.com

For the sake of this demonstration, I’m going to assume that you installed GAM into C:\GAM on a Microsoft Windows machine. Now to introduce the “For In Do Loop” command. To execute the delete command for these 5 users that are contained in a text file named C:\GAM\userlist.txt we would do the following:

Open a command prompt, change the current directory to C:\GAM and type the following:

“for /F %f in (c:\gam\userlist.txt) do gam delete user %f”

Now to explain what is going on here. The /F parameter says that the input will be a FILE. The filename is then specified within the parenthesis. The first %f says that this is the variable that we will use to substitute the contents of the file specified later within our command. You can choose any letter that you want, but you must realize that the letter is case-sensitive, so if you specify lower-case f, then, later on, you must also use a lower-case f.

Everything that comes after the word “do” is the command that will be executed repeatedly and each line of the file specified will be substituted in the place where the last %f is placed. The variable doesn’t need to be last. It can be placed anywhere that is appropriate in the command. The feedback that would return on the screen would be:

gam delete user aaliyah.andrews@sps-k12.com
gam delete user abigail.baldwin@sps-k12.com
gam delete user ahrianna.bagley@sps-k12.com
gam delete user aissata.bah@sps-k12.com
gam delete user alakee.badaru@sps-k12.com

GAM will automatically put a 5-second delay between each command so that this process will take approximately 20 seconds for these 5 users. You may need to consider this if you are planning to delete 5,000 users it could take you approximately 6.94 hours to complete full list of users.

There is one more point of clarification with the “for in do loop” command. The syntax that was used in the example is if you type the command and execute it interactively. It is slightly different if you want to embed this command inside a batch file or cmd file to execute as a scheduled task or something like that. The command is almost identical, but %f needs to be changed to %%f in both cases. The new command would look like this”

“for /F %%f in (c:\gam\userlist.txt) do gam delete user %%f”

Lastly, I’d like to show slightly more advanced command that could be used on all of your users if you were switching from one domain name to another as your standard for all users. For this example, we want to edit our userlist.txt file and do a search and replace @sps-k12.com with nothing so that it is removed completely from all users. The result should be a simple list of usernames list this:

aaliyah.andrews
abigail.baldwin
ahrianna.bagley
aissata.bah
alakee.badaru

Now, to change all of these users default email from @sps-k12.com to @demo.sps-k12.com we would use the following command.

“for /F %f in (c:\gam\userlist.txt) do gam update user %f@sps-k12.com email %f@demo.sps-k12.com”

This shows that not only can you put %f anywhere in the command, but you can use it multiple times to put the same value into the command in multiple places.

I hope that you have found this useful, but please be very careful when using these commands.

You may also want to check out our blog post: How to Manage Google OU Exceptions.