NEW! Box CLI automation template to manage Slack integration folder mappings
At the beginning of June, Box Platform launched a new brand API to manage mapping folders in Box to channels in Slack, and also recently launched a new scripts for admins and developers to complete repetitive tasks using the Box CLI. Today, we are releasing a new automation template script using the integrations mappings for Slack API.
As described in the first post, when Box as the Content Layer for Slack is enabled, Box folders are created for each channel, and files are uploaded to those folders. Channel members become editing collaborators of the created folder, and content is easily accessible via bookmark in the channel.
Let’s jump into the tutorial.
Prerequisites
Before following along, the below should be completed.
- Have access to an enterprise Box account that has Admin or Co-admin permissions
- Install and configure the Box CLI using OAuth with the above account
- Confirm Box for Slack is installed in the Slack workspaces or orgs
- Confirm Box as the Content Layer for Slack is enabled
Note, that for Slack-side channel validation, the Integration Mappings API is calling the Slack API.
Download script
The next step is to download the script to your local machine. Do so by cloning the CLI GitHub repo or directly downloading the file from the /examples directory. You can run the below in a terminal window.
git clone https://github.com/box/boxcli.git
cd boxcli/examples/Integration\ Mappings/Install Powershell
You can skip this step if you already have Powershell. If you have never used Powershell on your machine, you can get access to it by following the below instructions.
For Windows:
- Install the latest version of dotnet core
For MacOS/Linux:
- Install PowerShell
To confirm Powershell and the script are downloaded correctly, you can run the following command in the terminal window you used earlier to clone the CLI script.
pwshYou should see something like this.
Integration Mappings % pwsh
PowerShell 7.3.4
PS /Users/USERNAME/boxcli/examples/Integration Mappings>Now we are ready to run the script!
This script can do one of three things:
- CREATE new Box folder to Slack Channel mappings
- EXTRACT a list of all the current mappings
- UPDATE existing Box folder to Slack Channel mappings
CREATE new Slack folder integration mappings
When using Box as the content layer for Slack, a folder is not created or collaborated until a user uploads the first piece of content in a channel. As such, the CREATE option exists in case you wish to create (a) new channel(s) and map (an) existing(or new) Box folder(s) all at one time.
The script will fail if you try to create a mapping on (a) folder(s) that already have/has one created. If you wish to update an existing mappings, use the UPDATE option instead.
Create a new Slack channel(s)
After you create the new channel(s), make sure to collaborate in any users you wish to. Make note of the channel id(s) in the URL bar.
Select Box Folder ID(s)
The Box folder(s) selected can be (an) existing team folder(s) with lots of content or one(s) that is/are brand new. Make note of the folder ID(s) in the URL bar.
The other requirement is that the Box as Content Layer for Slack service account must be added as a co-owner or owner of the folder(s) in order to manage collaborations and uploads.
If you don’t know what the service account email address is, continue to the next steps to try running the script. You will see an error similar to this in the error log file if the service account is not an owner or co-owner.
You can then collaborate the automation user email address into the folder(s) and try running the script with the CREATE option again.
Update the csv file
Open the script folder in a code or csv editor of choice. There, you will find a file named mappings_example.csv. Using this file, or a copy, input as many rows as you would like, making sure to include the Box folder ID, Slack channel ID, and Slack Org ID. Save the file.
You should know the Slack Org ID from the Box as Content Layer for Slack setup steps. If you need a quick way to find it later, in the Admin console, under Apps, scroll down to the list of apps. Search for Slack and click the configure button.
In the popup window, scroll down until you see the org id in the text box.
Run CREATE
Back in the terminal, you can run the following command to create new mappings. The mapping path variable is customizable — meaning you are allowed to use whatever file name you wish.
If you don’t input an action it will ask you to specify one.
If you don’t input a mapping path, it will default to using ./mapping.csv.
./Integration-mappings.ps1 -Action CREATE -MappingPath ./mappings_example.csvSee success message
If everything was successful, you will see a message similar to the below. The … are used below to represent the json response object.
Starting Process
Creating new mappings
Output [
{...}
]
All bulk input entries processed successfully.Now, the next time a user uploads a file in the respective Slack channel a link to that channel’s Box folder mapped will automatically appear.
EXTRACT all Slack folder integration mappings
Running the script using the EXTRACT option will save a file called mapping.csv in the script home directory. You can change the file name and path if you wish as shown in the example below.
It is recommended to run the EXTRACT option before the UPDATE option, as this will create the csv input file format required for the UPDATE option.
The script will fail if you try to run the extract option and haven’t set up the Slack integration via the steps in the pre-requisites
Run EXTRACT
In the terminal, you can run the following command to extract all the current mappings. The mapping path variable is customizable — meaning you are allowed to use whatever file name you wish.
./Integration-mappings.ps1 -Action EXTRACT -MappingPath ./mapping_sheet.csvIf you don’t input an action it will ask you to specify one.
If you don’t input a mapping path, it will default to using ./mapping.csv.
Check for csv file
If the script ran successfully, you will see a new file in the script folder named what you input for the mapping path variable. The script automatically readjusts the column names and columns selected to be what is required for the update action option.
If you wanted to check the output, you could verify the Box Folder ID opened for a specific Slack channel ID and see that they match the csv.
The update action does not retrieve all columns. It only outputs the mapping columns needed for updating.
Starting Process
Extracting current mappings
Pulling current mappings
Importing csv
Renaming columns
Saving new csv file to edit
Extraction Output written to /Users/USERNAME/Desktop/boxcli/examples/Integration Mappings/mapping_new.csvUPDATE Slack folder integration mapping
Running the script using the UPDATE option will use a file called mapping.csv in the script home directory. You can change the file name and path if you wish as shown in the example below.
It is recommended to run the EXTRACT option before the UPDATE option, as this will create the csv input file format required for the UPDATE option.
Select Box Folder ID(s)
The Box folder(s) selected can be (an) existing team folder(s) with lots of content or one(s) that is/are brand new. Make note of the folder ID(s) in the URL bar.
The requirement that the Box as Content Layer for Slack service account must be added as a co-owner or owner of the folder(s) in order to manage collaborations and uploads is still valid. If you need a refresher on the steps for this, scroll back up!
Update the csv file
Remove any rows in the csv that you do not wish to update. If for some reason you accidentally leave one in as it was output, don’t panic. It will not change anything.
When updating, you should only update the new Box folder ID(s). You should not change the row ID or partner (channel) id column data.
Save the file.
Run UPDATE
In the terminal, you can run the following command to update all the mappings input in the csv. The mapping path variable is customizable — meaning you are allowed to use whatever file name you wish. But if you are using the one output from the EXTRACT action, make sure to use whatever you input for the mapping path variable in that command.
./Integration-mappings.ps1 -Action UPDATE -MappingPath ./mapping_new.csvIf you don’t input an action it will ask you to specify one.
If you don’t input a mapping path, it will default to using ./mapping.csv.
See success message
If everything was successful, you will see a message similar to the below. The … are used below to represent the json response object.
Starting Process
Updating mappings
Output [
{...}
]
All bulk input entries processed successfully.Now, the next time a user uploads a new file in the respective Slack channel the link to that channel’s Box folder will automatically update.
Logging
Logs are stored in a logs folder located in the main script folder. You have access to these log files:
Integration-mappings_all.txtthat contains all log entries.Integration-mappings_errors.txtthat contains only errors.
Other important information
The Box as Content Layer for Slack service account must be added as a co-owner or owner of the folder in order to manage collaborations and uploads.
This script does not migrate any content from a previously mapped folder to the new one. Due to potential large size of a previously mapped folder, it is advised to migrate data separately, or simply move the previously mapped folder into the new folder.
This script will maintain permissions, meaning that if a user is in a Slack channel and a piece of content is shared, they will get access to the new folder.
Resources
Integration Mappings Guides
We hope you enjoyed this blog on the Box Integration Mappings for Slack API. Feel free to reach out to us on the developer forum for support.
