When you’re running a business, it can feel like everything is constantly changing. Among the many areas to maintain is how your people find the information they need. With growth and unavoidable turnover, it’s a challenge to ensure everyone has the correct access to team data. Dropbox Business streamlines this process, seamlessly allowing new team members to interact with protected files and resources.
Everyone having the correct access to team Dropbox files is critical to your business running smoothly, but manually adding new members who are joining and removing those who are leaving can be tedious and error-prone. This process is called User Provisioning. Luckily, with the Dropbox Business API, this doesn’t have to be the case.
This article will show you how to automate the process of members joining or leaving your team and how to safely manage their data when they leave. Sample code uses the Dropbox Python SDK.
Why Automate User Lifecycle Management?
Automating user management makes mistakes less likely as your team changes. Manually adding a member, for example, has the possibility of user error when typing the new employee’s email address. When this happens, it might take days before you realize the new employee never got the access they needed. If the process of adding an employee was automated, a script could pull the employee’s email address from a master list, ensuring no typos occur and nobody is accidentally given access to your team’s data.
Making scripts to manage user accounts also alleviates the burden of remembering the specific configurations your company prefers for those processes. For example, if your company policy is for an employee to have their account files wiped upon leaving, you can configure the script once, so you don’t have to change it later. Plus, when you integrate your scripts with existing HR or IT tools, you can add the right groups for each employee role, alongside your other on-boarding tasks.
It’s not just a matter of saving time, though these benefits compound as your team grows. You can build workflows to keep your team data secure and to help you ensure compliance with GDPR, LGPD, and other laws and standards. Former employees can be removed promptly (to enforce compliance) and new team members can quickly begin to contribute.
So, with the benefits clearly evident, let’s look at how exactly the process can be automated.
Adding New Employees to Dropbox
Adding employees to your Dropbox Business team can be done using the API. There are a number of popular language SDKs available, but these examples will use the Dropbox Python SDK. The Dropbox SDKs make it easier to use the Dropbox API, but you can also use the API directly if you want. The only other thing you’ll need is a team member management access token from your app, which can be created from the App Console of the Dropbox developer portal. We describe this step in the beginning of our recent article “Manage team sharing in your Dropbox app”.
The first step with any Dropbox Python script is to import the Dropbox library and make a connection using your access token:
import dropbox
token = '<your_team_member_management_access_token>'
dbx_team = dropbox.DropboxTeam(token)You can now create a script to add employees to your team. For this example, a new employee, Amy Smith, has joined your company. You want to add her to your Dropbox Business team. To do so, use the dropbox.team.MemberAddArg() function to set the parameters of the user, and then use the team_members_add() function to add her to your team with the parameters:
email = 'amy.smith@example.com'
first_name = 'Amy'
last_name = 'Smith'
member = dropbox.team.MemberAddArg(
member_email=email,
member_given_name=first_name,
member_surname=last_name,
send_welcome_email=True)
dbx_team.team_members_add([member])If the user does not have a Dropbox account, they’ll receive an email inviting them to create one. For this example, we chose to set send_welcome_email=True, which is already the default value if unspecified. But sometimes you might want to set it to False, and do what we call “silent invitations”. Silent invitations can be used, for example, in situations where Single Sign-On (SSO) is enabled, and members need to login using an existing authentication solution. In this case, the IT department might want to instruct people on how to join new team instead of sending the default Dropbox invitation email.
If they do have an existing account with the email address that got invited, they’ll be asked whether they would like to join the team and bring their personal files to a private folder in their team account or decline the invitation.
Note: Dropbox Advanced and Enterprise teams can be configured with Invite Enforcement, in which case the invited user with a corporate e-mail address will either have to accept the invitation and join the team, or change their e-mail address to a personal one. |
This process can be used to handle a list of employees by simply using a for loop to iterate through the list and updating the email , first_name, and last_name parameters.
For example, let’s say you had employee information in a list like this:
Accounts
>>>
[['Amy', 'Smith', 'amy@email.com'],
['Bob', 'Johnson', 'bob@email.com']]Iterating through each contact with a for loop would look like this:
for account in Accounts:
email = Accounts[account][2]
first_name = Accounts[account][0]
last_name = Accounts[account][1]
member = dropbox.team.MemberAddArg(
member_email=email,
member_given_name=first_name,
member_surname=last_name,
send_welcome_email=True
)
dbx_team.team_members_add([member])This general process can be easily customized to fit the unique way your company stores its employee information. Customize it to fit your workflow, and make adding employees to your Dropbox Business team a breeze.
Handling an Employee Status Change
Employees sometimes have to leave and if they do, you need to be prepared to manage their accounts. If a team member is permanently leaving, you’ll want to remove them from your Dropbox Business team.
To begin that process, you’ll use the dropbox.team.UserSelectorArg() function to select the user. The user can be identified with either their email, Team Member ID or their external ID. The External ID is optional but frequently used by Identity Management Systems that integrate with Dropbox.
For our example, we’ll select them using their email:
user = dropbox.team.UserSelectorArg.email('amy@email.com')
With the employee selected, we’ll use the team_members_remove() function to remove their account from the team:
dbx_team.team_members_remove(user,
wipe_data=True,
transfer_dest_id=None,
transfer_admin_id=None,
keep_account=False) Your answers to the three questions below will determine the correct configuration of parameters:
- Do you want to delete the account, or convert it to a Basic account?
- If you would like to let them keep their personal files and their Dropbox account, set keep_account to True. An example of when you would prefer to convert instead of delete is when you invited someone for a temporary project. They brought their own Dropbox account, but now the project is over and they need to bring their files with them.
- Do you want to transfer the files to another account?
- This ensures none of the files are lost or inaccessible to your team. If so, you’ll want to specify the other account with transfer_dest_id. You’ll also have to set transfer_admin_id to identify which administrator is to handle any errors that happen during the process. If you don’t want to transfer the files, both can be left as None. The files will still reside in your team for you to take action later. You can use the /members/move_former_member_files endpoint for that.
- And finally, would you like to wipe the account’s data from the user's connected devices?
- If so, make sure wipe_data is set to True. Keep in mind that if you choose to downgrade the account to a Basic account (with keep_account=True), you won’t be able to wipe their files.
The Dropbox API Explorer can be a useful tool in identifying the correct configuration of parameters when removing a team member.
So, putting it all together, let’s look at an example of an employee whose account data is being wiped from the linked devices and their data is not being transferred at the moment:
user = dropbox.team.UserSelectorArg.email('amy@example.com')
dbx_team.team_members_remove(user, wipe_data=True, transfer_dest_id=None, transfer_admin_id=None, keep_account=False)You can batch remove employee accounts similar to the previous section using a for loop to iterate and select their email addresses.
If an employee’s account is accidentally removed, you have seven days to recover it. This can be done through the web interface or via the API using the team_members_recover() function:
user = dropbox.team.UserSelectorArg.email('amy@email.com')
dbx_team.team_members_recover(user)If you downgraded the user to a Basic account, you can’t re-add them using the team_members_recover method. You'll need to re-invite them to the team like a new employee.
Since accounts can only be recovered for seven days after their removal, removing an account isn’t an effective way of handling situations when an employee is only temporarily leaving, such as for parental leave.
In these instances, suspending the account is a more apt course of action, as doing so allows you to easily reactivate it when they rejoin the team. As a matter of fact, suspending instead of deleting is usually the best practice, usually employed by the user provisioning tools that integrate with Dropbox. You can find a list of these solutions in our Identity and Access Management partners page.
The process is similar to removing team accounts, as you again use UserSelectorArg to select the user. However, this time you use the team_members_suspend function instead.
For example, if Amy takes a leave of absence, you can temporarily suspend her from your team account:
user = dropbox.team.UserSelectorArg.email('amy@email.com')
dbx_team.team_members_suspend(user, wipe_data=True)The only parameter to decide here is wipe_data. Setting it to True will delete all the user’s data on their linked devices. This can also be useful if someone’s laptop or phone was missing and that device had sensitive files on it.
When Amy returns, you can reactivate her account with the team_members_unsuspend() function:
box.team.UserSelectorArg.email('amy@email.com')
dbx_team.team_members_unsuspend(user)The ability to suspend and remove user accounts ensures that you have full control over the makeup of your Dropbox Business team.
Using the Dropbox API to Improve your User Lifecycle Management
With the Dropbox Business API—and an assist from a few Python scripts—you’ll be automating user lifecycle management, giving your company more time and security. Long gone are the days of employees waiting for the IT department to manually grant them access to the files they need; now, a simple script can give them that access before they even step through the door.
This article covered some of the User Lifecycle Management capabilities available in the Dropbox Business API such as adding a team member, removing a team member, suspending a team member, and provided guidance around best practices. But this is just the beginning. The Dropbox API can help you with many other tasks such as managing groups, granting administrative permissions, setting secondary e-mail addresses, and setting member space limits. Please take the time to look at the Dropbox Business API Documentation and see what else you can automate with it.
If you have any questions about User Lifecycle Management or need help building with the Dropbox API, you can contact us here or post on our developer forum.
Build with Dropbox today at www.dropbox.com/developers
