Overview
Dropbox is a cloud-based file storage platform that allow you to store, share, and access files from anywhere. This connector utilizes Dropbox’s API to interact with its endpoints, providing efficient file management and collaboration capabilities within your Bizagi processes.
The Dropbox connector for Bizagi is available for download at Bizagi Connectors Xchange. With this connector, you can integrate Dropbox features like file upload, download, and listing directories directly into your workflows. For more information on this connector’s capabilities, visit the Xchange platform.
|
This connector was developed using the API information provided by Dropbox. Bizagi and its subsidiaries do not guarantee the content or are responsible for errors resulting from the use of Dropbox's API services. Bizagi and its subsidiaries are not liable for any loss, cost, or damage caused by the use of Dropbox's API. |
Before you start
To test and use this connector, you will need:
1.Bizagi Studio installed.
2.The connector installed, either through the Connectors Xchange or via manual installation as outlined in the Installing and managing connectors article.
3.A Dropbox account with a registered app in the Dropbox Developer Console, ensuring access to the Storage Service API.
Setting up a Dropbox account
1.Open your browser and go to Dropbox website. Then, click the Find your plan link.
2.Select the plan that best suits your needs and budget. Dropbox offers a 30-day trial or Try for free options, each with a detailed description of the plan.
|
While not required, we strongly recommended to choose either the Business – For teams or Business Plus – For companies plan. |
Click the Try for free button for your chosen plan.
3.Enter your email address and click the Continue button.
|
We do not recommend selecting Continue with Google or Continue with Apple due to authentication incompatibility with Bizagi. |
4.Fill in all required fields, read the terms and conditions, and click Agree and sign up.
5.In the trial initiation window that appears, confirm that the correct plan is selected to start the trial. Enter a team name in the Team name field, check the terms and privacy policy checkbox, and click the Start free trial button to begin your 30-day trial.
6.Dropbox will now prompt you to verify your email. Check your inbox for the verification email and click the Verify your email button.
7.Dropbox will prompt you to select a range corresponding to the number of employees in your company. Choose the appropriate option, and the Skip button will be enabled at the bottom of the screen. Click Skip.
Make sure to skip all subsequent steps until you reach your main Dropbox workspace. After completing these actions, you will find two default folders: one with your name and another with your team name.
Configuring a Dropbox application
1.Navigate to the Dropbox Developer Console and click the Create app button.
2.Configure your app with the following settings:
•Choose an API: Select Scoped access.
•Chose the type of access you need: Select Full Dropbox – Access to all files and folder's in a user's Dropbox.
•Name your app: Enter a name for your app.
Check the Dropbox API Terms and Conditions checkbox, and click Create app.
3.Once the app is created, you will see four tabs. Under the Settings tab, note the App key and App secret (the latter is hidden for security reasons). Click Show to reveal the App secret and copy both values into a notepad or text file for easy access. You will need these values when configuring the connector in Bizagi.
4.In the OAuth 2 section, add the necessary Redirect URIs. For development environments, use https://build.bizagi.com/redirectOauth2.html.
Click Add to save the URI. Once added, the URI should appear listed in the Redirect URIs section.
5.Navigate to the Permissions tab and enable the following permissions for the app:
•Account Info: account_info.read, account_info.write
•Files and folders: files.content.read, files.content.write, files.metadata.read, files.metadata.write
After configuring the permissions, click Submit to finalize. A message stating Permissions change successful will confirm that everything is set up correctly.
Configuring the connector
To configure the connector, particularly its authentication parameters, follow the steps outlined in the Connectors Configuration section of the Installing and managing connectors article.
For this configuration, use the following authentication parameters:
•Authentication method: OAuth 2 Authentication
•OAuth2 flow: Authorization Code Grant
•client_id: The Dropbox App key obtained earlier under the app's Settings tab.
•client_secret: The Dropbox App secret obtained earlier under the app's Settings tab.
•auth_url: This URL can be found in the official Dropbox API documentation under the Authorization section. The URL is: https://www.dropbox.com/oauth2/authorize.
•token_url: This URL can also be found in the official Dropbox API documentation under the Authorization section. The URL is: https://api.dropboxapi.com/oauth2/token.
•scope: Scopes correspond to the permissions set in the Permissions tab when configuring the Dropbox application. Enter the scopes separated by spaces, as follows: account_info.read account_info.write email files.content.read files.content.write files.metadata.read files.metadata.write openid profile
•token_access_type: When setting up the OAuth flow, add token_access_type=offline as a parameter in your authorization URL to receive a refresh token in the access token payload. This will allow the access token to be automatically renewed upon expiration using the refresh token. To add a new parameter, click the + button.
When you click the Authorize button, a login pop-up window will appear. Enter the credentials for the Dropbox account you created.
The application may request a verification code sent to the account's registered email. If this happens, check your inbox for the 6-digit code. If a connection has already been established, you will not need to re-enter credentials.
Log in with the service credentials in the pop-up window. If the process is successful, the window will close, and a green box with a success message will appear.
Using the connector
This connector includes a set of actions that allow you to utilize Dropbox services and leverage their capabilities.
For general guidance on configuring a connector, refer to the Using connectors article.
When using this connector, be aware of the following details for the available actions.
Available actions
List folder
This action returns the contents of a folder.
To configure its inputs, consider the following descriptions:
•include_deleted (boolean): If true, the results will include entries for files and folders that have been deleted. The default value is false.
•limit (UInt32, min=1, max=2000): The maximum number of results to return per request.
|
This is an approximate number, and in some cases, slightly more entries may be returned. This field is optional. |
•path (String): A unique identifier for the file.
•recursive (boolean): If true, the folder listing operation will be applied recursively to all subfolders, and the response will include content from all subfolders.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•entries (object): A collection of resources.
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date when the resource was last modified by the client.
•server_modified (date): The date when the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
•cursor (String, min_length=1): Pass the cursor to listfoldercontinue to see what has changed in the folder since your last query.
•has_more (boolean): If true, there are more entries available. Pass the cursor to listfoldercontinue to retrieve the rest.
Copy
This action copies a file or folder to a different location within Dropbox.
To configure its inputs, consider the following descriptions:
•from_path (String): The user's Dropbox path for the file or folder to copy.
•to_path (String): The target path in the user's Dropbox for the file or folder.
•allow_shared_folder (boolean): This has no effect, and its default value is false.
•autorename (boolean): If there is a conflict, Dropbox will attempt to automatically rename the file to avoid the conflict. The default value is false.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date when the resource was last modified by the client.
•server_modified (date): The date when the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Create folder
This action creates a folder at a specified path.
To configure its inputs, consider the following descriptions:
•path (String): The user's Dropbox path where the folder will be created.
•autorename (boolean): If there is a conflict, Dropbox will attempt to automatically rename the folder to avoid the conflict. The default value is false.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
Delete
This action deletes the file or folder at a specified path.
To configure its inputs, consider the following descriptions:
•path (String): The user's Dropbox path for the file or folder to delete.
•parent_rev (String): Perform the deletion only if the provided “rev” matches the latest “rev” of the existing file. This field does not support folder deletions.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date the resource was last modified by the client.
•server_modified (date): The date the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Download file
This action downloads a file from the user's Dropbox.
To configure its inputs, consider the following descriptions:
•path (String): The path of the file to download.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•file (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date the resource was last modified by the client.
•server_modified (date): The date the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Download folder (zip)
Downloads a folder as a zip file from the user’s Dropbox.
To configure its inputs, consider the following descriptions:
•path (String): The path of the folder to download.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•metadata (object): Metadata of the folder.
•id (String, min_length=1): A unique identifier for the folder.
•name (String): The last component of the path (including extension). This never contains a “/”.
•path_lower (String): The full path in lowercase in the user’s Dropbox. This always begins with a “/”. This field will be null if the file or folder is not mounted. This field is optional.
•path_display (String): The display path of the resource.
•zipName (String): The name of the zip file.
•zipFile (String): The content of the zip file in base64.
Get Metadata
This action returns metadata for a file or folder.
|
Root folder metadata is not supported. |
To configure its inputs, consider the following descriptions:
•path (String): The path of a file or folder in Dropbox.
•include_deleted (boolean): If true, DeletedMetadata will be returned for deleted files or folders. Otherwise, LookupError.not_found will be returned. The default value is false.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date the resource was last modified by the client.
•server_modified (date): The date the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Move
This action moves a file or folder to a different location within the user’s Dropbox.
To configure its inputs, consider the following descriptions:
•allow_ownership_transfer (boolean): Allow the move operation even if it results in a transfer of ownership of the content. This does not apply to copies. The default value is false.
•autorename (boolean): If there is a conflict, Dropbox will attempt to automatically rename the file to avoid the conflict. The default value is false.
•from_path (String): The user's Dropbox path for the file or folder to move.
•to_path (String): The destination path in the user's Dropbox.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date the resource was last modified by the client.
•server_modified (date): The date the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Upload
This action creates a new file with the content provided in the request.
|
Do not use this action to upload a file larger than 150 MiB. Instead, start an upload session with /upload_session/start. |
To configure its inputs, consider the following descriptions:
•path (String): The path in the user’s Dropbox where the file will be saved.
•autorename (boolean): If a conflict is detected, Dropbox will attempt to automatically rename the file to avoid the conflict. The default value is false.
•mute (boolean): Normally, users receive notifications about file modifications in their Dropbox account via client software. If true, this tells clients not to notify the user about this modification.
•contents (String): The content of the file.
To configure the outputs and begin testing, map the output object to the corresponding entity in Bizagi, making sure to properly map the entity's attributes.
To configure its outputs, consider the following descriptions:
•id (String): The resource identifier.
•tag (String): An internal label for the response.
•name (String): The name of the resource.
•path_lower (String): The resource's path in lowercase.
•path_display (String): The display path of the resource.
•client_modified (date): The date the resource was last modified by the client.
•server_modified (date): The date the resource was last modified by the server.
•rev (String): A unique identifier for the current version of the resource.
•size (int): The size of the resource in bytes.
•content_hash (String): The resource's content hash.
•sharing_info (object): Shared information for the resource.
Troubleshooting
Issue 1: Authentication error
Verify the authentication credentials and ensure all parameters are correct. Additionally, make sure the Redirect URI is registered in the Dropbox API application.
|
If re-authentication is needed through the Management Console Web (MCW), the Redirect URI parameter must be updated, as it differs from other platforms. Use the value displayed in the MCW screen when registering it on the Dropbox platform. |
Issue 2: Error 401 when running the connector
Re-authenticate through either Studio or the MCW.
Last Updated 9/26/2024 3:41:39 PM