Box Developer Documentation

Join BoxWorks 2024 to discover what's possible with content and AI!

Register now!

Update user zones

Update user zones

This script provisions users to a specific data residency zone within a Multizone Box tenant. It performs the following steps:

  1. It uses admin or co-admin login email address to find the associated enterprise and the zone policy assigned to this enterprise. An assigned zone policy is inherited by all users unless specified otherwise. It is sometimes called the default zone.
  2. It performs zone assignment based on an input .csv file containing user email addresses and zone mappings.

Usually, you use the script once to do the initial provisioning of user zones, but you can also use it for subsequent runs to make zone assignment updates.

If you would like to use Admin Console for zone assignment, see this guide. For more information about Box Zones, see the official website.

Prerequisites

Windows

Install the latest version of dotnet core.

MacOS & Linux

Install PowerShell. Run the pwsh command to test the installation.

pwsh

Depending on the directory you are running the command in, the output may differ. For example:

PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>

If you encounter issues make sure you installed both dotnet core and PowerShell.

Set up application with JWT authentication

To use the script, you will need the Box CLI with JWT authentication installed and configured.

When creating the app, use the Configuration tab to configure the following settings:

  • In App Access Level, select App + Enterprise Access.
  • In Application Scopes > Administrative Actions, select Manage Enterprise Properties, Manage Users.
  • In Advanced Features, select Generate user access tokens.

Adjust admin settings

Make sure Box Admin or Co-Admin has at least Manage Users privileges. To check this setting:

  1. Go Users & Groups section in the Admin Console.
  2. Click the user account you want to verify.
  3. Go to Edit User Access permissions section to grant the administrative privileges for users and groups.

Prepare the .csv file

The .csv file must have two columns with the following headers: Email and Region.

  • Email contains the primary email address of a Box user.

  • Region contains the user-friendly name for the zone to which the script will assign the user. This name is provided by the ZonesTable that is a hash table used to define zones. The keys are the zone's user-friendly names, and the corresponding value is the global ID of the zone.

    $ZonesTable = @{
        US = "100001"             #US
        GermanyIreland = "100002" #Germany/Ireland with in region uploads/downloads/previews
        Australia = "100003"      #Australia
        Japan = "100004"          #Japan with in region uploads/downloads/previews
        Canada = "100005"         #Canada
        JapanSingapore = "100007" #Japan/Singapore with in region uploads/downloads/previews
        UKGermany = "100008"      #UK/Germany
        UK = "100009"             #UK with in region uploads/downloads/previews
        France = "100012"         #France
    }
    

Consult the Box Consulting or Customer Success manager to get the IDs corresponding to the zones enabled in a specific enterprise.

A sample input .csv file containing emails and zone names is provided with this script. Its content looks as follows:

EmailRegion
betty@company.comUS
roger@company.comFrance
sally@company.comJapanSingapore

Configure the script

Set the UserZonesUpdatePath to point to your .csv file.

$UserZonesUpdatePath = "./your_file_name.csv"

Update the adminEmail to the admin or co-admin login email address of the account the script will use to make zone assignments. If you don't specify this value, the script will prompt you for it.

$adminEmail = "john@box.com"

Run the script

Run the Powershell command.

pwsh

Run the script.

./Mass_Update_User_Zones.ps1

Optional flags

To run the script in a simulation mode, add the simulate boolean flag.

./Mass_Update_User_Zones.ps1 -DryRun

Logging

Logs are stored in a logs folder located in the main folder. You have access to these log files:

  • Mass_Update_User_Zones_all.txt that contains all log entries.
  • Mass_Update_User_Zones_errors.txt that contains only errors.