Manage groups and collaborations

Guides CLI CLI sample scripts Manage groups and collaborations
Edit this page

Manage groups and collaborations

Script structure

This script uses Box CLI to create or update groups, add users to them, and finally to create collaborations between groups and folders. The script consists of two parts described in detail in the sections below. You can run them both or use the optional flags to decide which part to run.

Create or update groups

  1. The script uses the .csv file you specify for the UserGroupAdditionPath parameter. The file lists group names and user emails. When creating the file, you can use the same group name for several users, and assign one user to several groups. For example:

    GroupNameUserEmail
    Group1ManagedUser1@test.com
    Group1ManagedUser2@test.com
    Group2ManagedUser3@test.com
    Group3ManagedUser1@test.com
  2. If the group doesn't exist, the script creates it. If it does exist, the script can update the entries based on the provided data.

Create or update collaborations

  1. The script uses the .csv file you specify for the CollaborationsCreationPath parameter. The file lists group names, folder IDs, and collaboration roles.

  2. For each row, the script checks if a group exists and if it's not already added as a collaborator to the corresponding folder. For example:

    GroupNameFolderIdCollaborationRole
    Group11111111editor
    Group21111111viewer_uploader
    Group22222222viewer
    Group31111111viewer_uploader
  3. If both of these conditions are met, the script assigns the group to a folder using the role defined in the CollaborationRole column. Also, if a group already exists, but the CollaborationRole changed, the script will update it if you pass the -UpdateExistingCollabs flag when running the script.

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.

Box CLI

To use the script, you will need the Box CLI installed and configured. You can get this done by going through our quick start guide. The user you use to login with should be the main Box admin or co-admin.

Configure the script

  1. Clone the boxcli GitHub repository and cd into this example's folder or download the files from examples directory.

    git clone https://github.com/box/boxcli.git boxcli
    cd boxcli/examples/Mass\ Groups\ \&\ Collaborations\ Update/
    
  2. Set the path to the .csv file with the list of groups and user emails.

    $UserGroupAdditionPath = "./User_Group_Addition.csv"
    
    • UserEmail is the primary email address for the user in Box.
    • GroupName is the name of the group.
  3. Set your own path to the .csv file with the list groups and user emails.

    $CollaborationsCreationPath = "./Collaborations_Creation.csv"
    
    • GroupName is name of the group the script will add as a collaborator to the folder.
    • FolderId is the folder ID the collaborator will be added to.
    • CollaborationRole is the name of the role used when creating a collaboration.

    You can configure the available roles by setting the AvailableCollaborationRoles parameter:

    $AvailableCollaborationRoles = @("editor", "viewer", "previewer", "uploader", "previewer_uploader", "viewer_uploader", "co-owner")
    

Run the script

  1. Run the Powershell command.

    pwsh
    
  2. Run the script.

    ./Mass_Groups_Collabs_Update.ps1
    

Optional flags

You can use flags to run run or skip specific parts of the script.

  • If a group already is set as a collaborator for a specific folder but with a role other than defined in the .csv file, the script will inform you about it. It will not make any changes to an existing collaboration. If you want to update an existing collaboration with role defined in .csv file, set an additional -UpdateExistingCollabs flag when running the script.

    Mass_Groups_Collabs_Update.ps1 -UpdateExistingCollabs
    
  • To update groups without creating collaborations, add the -SkipCollabsCreation boolean flag when running the script:

    Mass_Groups_Collabs_Update.ps1 -SkipCollabsCreation
    
  • To create collaborations without any group updates, add the -SkipGroupsUpdate boolean flag when running the script:

    Mass_Groups_Collabs_Update.ps1 -SkipGroupsUpdate
    

Logging

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

  • Mass_Groups_Collabs_Update_all.txt that contains all log entries
  • Mass_Groups_Collabs_Update_errors.txt that contains only errors.