There are an amazing variety of projects with vast bodies of work that are distilled down into a single file. Things like a podcast with guests from all over the world, a comprehensive blueprint for a downtown skyscraper, or a feature film made by a movie studio all have a central file that ties everything together.
There can be quite a broad range of users that need to collaborate with others on the same file. But how can you ensure that important files stay up to date and serve as the single source of truth? Enter file locking*. Let’s explore what value file locking can add to your Dropbox app.
* Note that file locking features are only available for Dropbox Business users.
File locking in Dropbox
File locking provides a way for collaborative users to prevent any unwanted edits to particular files. The feature “locks” the file in place so it doesn’t get moved, deleted, changed, or updated by another person or application.
File locking is designed to work with apps that use a file check in/check out flow. Only the file locker will have the ability to edit and unlock the file (although team admins can override the lock). Only files in shared folders can be locked.
Key behaviors of the file locking feature:
- Prevent modifications to locked file
- Locked file can be viewed and downloaded
- Users can see whom holds the file lock
- Admins can override locks by their team
As a quick prerequisite, let’s create a shared file structure. Create a shared folder named “file-lock-article” in your root directory and place a text file named “test-doc.txt” inside. The final path should be “/file-lock-article/test-doc.txt”.
Create a second doc in the same directory — “/file-lock-article/another-doc.txt”.
File locking with the User API
We’ll be using two new file locking endpoints:
We recommend having Dropbox open in the browser so you can manually lock or unlock files as needed when working with the sample scripts. Seeing the file locking feature in the Dropbox user interface may also help understand API behavior.
- Create a user access token
- Create a new Dropbox app from your app console
- Select ‘Dropbox API’Select ‘Full Dropbox’
- Provide name and click ‘Create app’From the Settings page, select the button to generate access token
- Save access token to be used in following examples
Locking files as a user
The /files/lock_file_batch endpoint accepts a list called entries with each entry referencing a specific file with the path parameter, which can be a file path or a file id.
Go ahead and lock the test-doc.txt and another-doc.txt files we created earlier:
curl -X POST \
https://api.dropboxapi.com/2/files/lock_file_batch \
-H 'Authorization: Bearer <user_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"entries": [
{
"path": "/file-lock-article/test-doc.txt"
},
{
"path": "id:7AObMBEU53AAAAAAAAAASw"
},
{
"path": "/throw-an-error"
}
]
}'The response includes the result for each entry submitted:
{
"entries": [
{
".tag": "success",
"metadata": // file metadata,
"lock": // file lock info
},
{
".tag": "success",
"metadata": // file metadata,
"lock": // file lock info
},
{
".tag": "failure",
"failure": // error message
}
]
}Getting file lock info as a user
If a file is locked, then the file’s metadata will return an additional property, file_lock_info, that contains information about the lock. Endpoints that return file metadata such as /files/get_metadata or /files/list_folder will also return file_lock_info for files that are locked.
Use a /files/list_folder call to look at the file lock information for the two files we just locked:
curl -X POST \
https://api.dropboxapi.com/2/files/list_folder \
-H 'Authorization: Bearer <user_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"path": "/file-lock-article"
}'Your locked .txt files will contain file lock information:
"file_lock_info": {
"is_lockholder": false,
"lockholder_name": "Taylor K",
"lockholder_account_id": "dbid:AAB9bIvxKmEflS5houxLa198BIEaS_iYZI",
"created": "2019-12-19T18:03:37Z",
"is_locked": true
}
Unlocking files as a user
The /files/unlock_file_batch will unlock files at a specified path or file id. Locked files can only be unlocked by the lock holder (or a team admin if you’re using a Business account).
Unlock the files from our example:
curl -X POST \
https://api.dropboxapi.com/2/files/unlock_file_batch \
-H 'Authorization: Bearer <user_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"entries": [
{
"path": "/file-lock-article/test-doc.txt"
},
{
"path": "id:7AObMBUU53AAAAAAAAAARA"
}
]
}'You’ll see a success message upon file unlock.
Administering file locks with the Business API
In this section you’ll need to use a team member file access token for and the Dropbox-API-Select-Admin header. If the concept of a team-linked Dropbox app is new to you (or you need a refresher), then this article may be helpful: Manage team sharing in your Dropbox App.
Imagine you’re building a security app that scans a team’s Dropbox files for policy compliance and moves them to a quarantine zone if a problem is found. As your app parses the folder hierarchy, locked and unlocked files alike can be downloaded and scanned. However, once a problem file is identified, locked files have to be unlocked before they can be moved to quarantine.
Make sure that the test-doc.txt file we created earlier is locked and located inside a shared folder nested in your team member folder. This will be the “non-compliant file” for our example.
Discovering file locks
As your security app parses your team’s files and makes /files/list_folder or /files/get_metadata calls, it examines the metadata for each file. Only locked files will include a file_lock_info property with important information about the file lock.
Let's check our test-doc.txt file:
curl -X POST \
https://api.dropboxapi.com/2/files/get_metadata \
-H 'Authorization: Bearer <team_file_access_token>' \
-H 'Content-Type: application/json' \
-H 'Dropbox-API-Select-Admin: dbmid:AAAIrHhxSNGhQ0QD4hZ85lYRDSEhQdovJTg' \
-d '{
"path": "/file-lock-article/test-doc.txt"
}'Yikes! Pretend your security app discovered a file (test-doc.txt) that doesn’t comply with company policy. The file’s lock must be removed before the file can be moved to quarantine.
Administer a file unlock as an admin
In Dropbox, a team’s admin is able to unlock files from the Admin Console. Similarly, a call to the /files/unlock_file_batch endpoint with the Dropbox-API-Select-Admin header set to an admin’s team_member_id unlocks the file as a team admin.
Unlock a file as an admin:
curl -X POST \
https://api.dropboxapi.com/2/files/unlock_file_batch \
-H 'Authorization: Bearer <team_file_access_token>' \
-H 'Content-Type: application/json' \
-H 'Dropbox-API-Select-Admin: dbid:AADuXdtqA88UpveXxu7rcTSo64ADcrWnBMk' \
-d '{
"entries": [
{
"path": "/file-lock-article/test-doc.txt"
}
]
}'Now the locked file is unlocked and can be moved to the quarantine folder (or otherwise handled how you defined in your app). Hooray!
File locks in team-linked apps
Some key takeaways for building file locking into your team apps:
- When building file locking into team-linked Dropbox apps, you’ll need to use a team file access token and either the Dropbox-API-Select-User or Dropbox-API-Select-Admin header.
- The most straightforward way to determine whether a file is locked is checking whether a file’s metadata includes a file_lock_info property.
- File locking endpoints will accept file paths and file ids.
Building file locking into your Dropbox App
For some applications, the introduction of file locking exposes powerful new use cases and workflows. For other classes of apps, file locking means they’ll need to add some additional logic for interacting with locked files (like our security app example). This article covered the behavior of file locking at a high level and how to build file locking into your app with both the Dropbox User API and the Dropbox Business API.
If you have any questions about file locking 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
