Dropbox Integration

Author:Robin Burke, Zijun Liu
Version:June 5th, 2020

1. Introduction

Dropbox Integration is based on the Dropbox API, and enables users to post files and folders to Dropbox locations. The Dropbox API key is password-encrypted and the encrypted key can be included in a public repository (i.e. GitHub).

2. Installation

2.0. QuickStart Guide

pip install dropbox

2.1. Go to Dropbox Official Website

  1. Go to website. https://www.dropbox.com/developers
  2. Click Create apps on the page. See Figure1 below.
Management Tools

Figure1

2.2. Create new app on Dropbox

  1. Choose an API. There are two types of Dropbox API. Dropbox API and Dropbox Business API. For personal, you can choose Dropbox API.
  2. Choose the type of access you need. There are two types of access too. App folder means you can upload your files on selected folder. This is recommended as it provides additional security for your Dropbox folder.
  3. Name your app. Give a name for your Dropbox API app name. i.e. test2. See Figure2 below.
Management Tools

Figure2

2.3. Save your Dropbox API key

  1. After you finish section 2.2. Click the Continue button below. You have successfully created your Dropbox API app.
  2. See Figure3 below. Figure3 is the OAuth 2 section. The Generated access token is space for your Dropbox API. Copy the API key to a text file. Do not store this file in your study directory with data files, etc. that you might want to share with others on GitHub, for example.
Management Tools

Figure3

3. Integrating with librec-auto

3.1. Encrypt your Dropbox API key

  1. As above, your secret key should be stored in a secure location.
  2. To encrypt the key to create a file that can be shared securely, run the script bin/encrypt.py. Include the following arguments:
  • --encrypted This is the file that contains the API key in encrypted form. This will typically be placed in your study directory in a directory called keys.
  • --key This is the cleartext API key that you got from Slack.

The call will look like this:

python bin/encrypt.py --encrypted mystudy/keys/dropbox-api.enc --key non-shared-safe-location/dropbox-api.key

  1. The script will prompt you for a password. You will need this password later to use the encrypted API key.

3.2. Add the script to the configuration file

  1. In order to add Dropbox integration to your study, you will need to add a script element to the post-processing portion of the configuration file. Here is an example:
<script lang="python3" src="system">
     <script-name>dropbox-post.py</script-name>
     <param name="option">file</param>
     <param name="encrypted_key">keys/dropbox-api.enc</param>
     <param name="path">post/cool-graphic.jpg</param>
     <param name="dest">/app-folder-on-dropbox</param>
     <param name="password"/>
</script>

The parameters are as follows:

  • option Either file or folder. The above example is a file example.
  • channel The Slack channel where the message should be posted. Do not include the hashtag.
  • encrypted_key The location of the encrypted API key. This is relative to the study directory where the configuration is located.
  • path The file/folder that will be posted in the designated folder when the script is executed.
  • dest The destination folder on Dropbox where files will be sent.
  • password Do not include the password here. (You’ll notice that the element has no content.) This is a flag indicating that the password will be entered on the command line when librec-auto is run. If you do not include it, you will be prompted for the password when the script is run, but that kind of defeats the purpose of having an automated experimental tool.

To post the contents of a folder to Dropbox, the option element will contain the term folder instead of file. The path argument will then be interpreted as the path to a folder.

3.3. Provide the password when running librec-auto

Use the -k or --key_password on the command line to provide the password to librec-auto. Example:

python -m librec_auto -k my_password_here run

The password can be shared with collaborators via some secure channel. The same password will be used for all scripts containing the empty <password/> element.