How to move Google Workspace users to another OU with GAM

GAM7 moves one user, or everyone in an organizational unit, with a single command. Here is each form, the preview to run first, how to leave suspended accounts where they are, and how long the new settings take to apply.

Organizational units are how Google Workspace decides which rules apply to whom: which apps are on, what a Chromebook allows, whether files can be shared outside the district. Moving a user is moving them from one set of rules to another. In a school it happens in bulk every summer and one person at a time all year.

The short answer

For one person, check where they are now:

gam info user alice@example.org

Then move them:

gam update user alice@example.org ou "/Staff/High School"

For everyone in an organizational unit, say a grade moving up, list who is there first:

gam print users limittoou "/Students/Grade 8" issuspended false

Then move them all:

gam update ou "/Students/Grade 9" move ou_ns "/Students/Grade 8"

Read that one right to left: take the users in /Students/Grade 8 and move them into /Students/Grade 9.

Those two commands select the same people, and it is worth knowing why they do. Google's own user query for an organizational unit also returns the users in every unit underneath it; GAM then narrows the result to the one you named. Measured on a live domain with two users in an organizational unit and one in a child beneath it, Google returned three and the command printed two. The ou selector in the move behaves the same way and left the child's user alone. When you do want everything underneath, that is what ou_and_children is for.

Leave the suspended accounts where they are

The ou_ns in that command matters. GAM offers several ways to select the users in an organizational unit, and the documentation lists them plainly: ou is "All users", ou_ns is "Non-suspended users", and ou_susp is "Suspended users". (GAM wiki: Collections of Users)

In a rollover you almost always want ou_ns. A student who withdrew in March is suspended, and dragging that account into next year's grade makes it look like a current student in every report you run. Leave suspended accounts behind and deal with them on purpose.

The same list also has ou_and_children and its variants, which include every organizational unit underneath as well. Use them only when you mean it: moving /Students and all its children into one place flattens a structure somebody built carefully.

Quote the path, and know where GAM splits

Put quotes around any organizational unit path with a space in it. The commands above use the singular forms, where that is all it takes. The plural forms, orgs and ous, are different: GAM splits their argument on spaces, and the documentation's own fix is to wrap the path in single quotes inside the double ones, as in gam info orgs "'/Foo Bar'". (GAM wiki: Organizational Units)

When the new settings take effect

The move itself is quick. The settings that come with the new organizational unit follow on Google's schedule: "Changes can take up to 24 hours but typically happen more quickly." (Change service settings for different users) Do not judge a move by how a Chromebook behaves in the first ten minutes. The directory itself can also take a little while to show the change everywhere; how long directory changes take covers that separately.

Sources

In ORINEX Workspace, Move OU works on one user or a whole selection, with an organizational unit tree to choose the destination from, and when a bulk move finishes it opens the destination so you can check the result. What ORINEX Workspace does.