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 application

To use the script, you will need a Box application with OAuth 2.0 authentication. If you don't have one, go to your Developer Console, and follow the guide Setup with OAuth 2.0.

Configure the script

  1. Clone the boxcli GitHub repository or download the files from examples directory.

    git clone https://github.com/box/boxcli.git
    
  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. Change the directory to the folder containing the script. In this example, it is the Mass Groups & Collaborations Update folder.

    rvb@lab:~/box-cli/examples/Mass Groups & Collaborations Update$ pwsh PowerShell 7.2.4
    Copyright (c) Microsoft Corporation.
    https://aka.ms/powershell
    Type 'help' to get help.
    PS /home/rvb/box-cli/examples/Mass Groups & Collaborations Update>
    
  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.