Box.net APIv1 migration: Difference between revisions

Latest revision as of 15:30, 17 October 2014

Note: This page contains information for site administrators only.

Box API v2

Box.net API v1, which Moodle uses to interact with the Box repository and Box portfolio, expired 14 December 2013. It was replaced by Box API v2. Three important consequences of the new API are:

The Moodle site must use HTTPS in order to access Box.
Box plugins must be configured with a Box client ID and secret.
For Box repository users it will no longer be possible to create a shortcut/alias to a file stored in Box. Existing aliases will need to be converted to file copies by running the Box.net-alias-to-copy-conversion tool.

Obtaining a Box client ID and secret

Go to https://app.box.com and create an account or log in
Go to https://app.box.com/developers/services and click the link 'Create new application'
Enter an application name and click the 'Content API' button
Once the application is created, click the 'Edit this application' button
On the Edit a Box Application page, scroll down to the section 'OAuth2 parameters' and make a note of the client ID and secret

The client ID and secret can then be used to configure the Box repository and Box portfolio.

Box repository configuration

Go to Administration > Site administration > Plugins > Repositories > Manage Repositories
Reactivate the Box.net repository by selecting 'Enabled and visible' in the dropdown menu
Configure the repository plugin by entering the Box client ID and secret. Make sure you don't include any white space in the text boxes!
Save changes

Box portfolio configuration

Go to Administration > Site administration > Plugins > Portfolios > Manage Portfolios
Reactivate the Box.net portfolio by selecting 'Enabled and visible' in the dropdown menu
Configure the portfolio plugin by entering the Box client ID and secret
Save changes

The Box-alias-to-copy-conversion tool

IMPORTANT: The Box-alias-to-copy-conversion tool must be used before 14 December 2013 to avoid data loss!

Administrators are advised to run the Box-alias-to-copy-conversion tool immediately after upgrading their site. It may be run

Either from within Moodle:

Ensure that the Box repository has been configured according to the instructions above
Go to Administration > Site administration > Modules > Repositories > Manage repositories and click the settings link for Box
Click the link to run the tool

Or via a CLI script, found at /repository/boxnet/cli/migrationv1.php.

Please be aware that this tool could take several hours to run depending on the number of aliases and their size.

Note: After running the tool, the Box settings page will still display the message 'It appears that you were using Box with the API version 1, have you run the migration tool to convert the old references?' Please just ignore it. ;-)

@@ Line 1: / Line 1: @@
-{{Installing Moodle}}
+{{Repositories}}
-As of the 14th of December 2013, the API that Moodle uses to interact with the [[Box.net repository]] and [[Box.net portfolio]] is reaching its end of life. Box.net now recommends using their API version 2. There are a few implications related to the migration to their new API:
+''Note: This page contains information for site administrators only.''
-==After upgrade to 2.6==
+==Box API v2==
-===Repository===
+Box.net API v1, which Moodle uses to interact with the [[Box repository]] and [[Box portfolio]], expired 14 December 2013. It was  replaced by Box API v2. Three important consequences of the new API are:
-After the upgrade, and without doing anything, all the files that were referenced from Box.net will still be accessible until the 14th of December. But it will not be possible to import new files until you configure the repository for the API version 2.
+# The Moodle site must use HTTPS in order to access Box.
+# Box plugins must be configured with a Box client ID and secret.
+# For Box repository users it will no longer be possible to create a shortcut/alias to a file stored in Box. ''Existing aliases will need to be converted to file copies by running the Box.net-alias-to-copy-conversion tool.''
-To configure, do the following:
+==Obtaining a Box client ID and secret==
-* Get the ''client ID'' and ''secret'' from your App at [https://app.box.com/developers/services Box.net]
+# Go to https://app.box.com and create an account or log in
-* Navigate to the repository settings: Administration block > Site administration > Plugins > Repositories > Manage instances
+# Go to https://app.box.com/developers/services and click the link 'Create new application'
-* In the dropdown of Box.net, select ''Enable and visible''
+# Enter an application name and click the 'Content API' button
-* Then click ''Settings''
+# Once the application is created, click the 'Edit this application' button
-* Enter the ''client ID'' and ''secret''
+# On the Edit a Box Application page, scroll down to the section 'OAuth2 parameters' and make a note of the client ID and secret
-===Portfolio===
+The client ID and secret can then be used to configure the Box repository and Box portfolio.
-You just need to configure the portfolio settings for the API version 2.
+==Box repository configuration==
-To configure, do the following:
+# Go to ''Administration > Site administration > Plugins > Repositories > Manage Repositories''
+# Reactivate the Box.net repository by selecting 'Enabled and visible' in the dropdown menu
+# Configure the repository plugin by entering the Box client ID and secret. Make sure you don't include any white space in the text boxes!
+# Save changes
-* Get the ''client ID'' and ''secret'' from your App at [https://app.box.com/developers/services Box.net]
+==Box portfolio configuration==
-* Navigate to the repository settings: Administration block > Site administration > Plugins > Portfolios > Box.net
-* Enter the ''client ID'' and ''secret''
-==Requirement for HTTPS==
+# Go to ''Administration > Site administration > Plugins > Portfolios > Manage Portfolios''
+# Reactivate the Box.net portfolio by selecting 'Enabled and visible' in the dropdown menu
+# Configure the portfolio plugin by entering the Box client ID and secret
+# Save changes
-Compared to the version 1, the API version 2 requires your website to use HTTPS for the authentication process.
+==The Box-alias-to-copy-conversion tool==
-==End of alias/shortcuts==
+<p class="note">'''IMPORTANT''': The Box-alias-to-copy-conversion tool must be used before 14 December 2013 to avoid data loss!</p>
-With the initial version of the API, we could use a direct link to a file as a reference in Moodle. But after the migration it is not possible any more, the repository will not support references any more.
+Administrators are advised to run the Box-alias-to-copy-conversion tool immediately after upgrading their site. It may be run
-==/!\ To be done before the 14th of December 2013==
+Either from within Moodle:
-We have provided a tool that will convert all the references you had in Moodle to real files (true copies). You can run this tool using either of the following:
+# Ensure that the Box repository has been configured according to the instructions above
+# Go to ''Administration > Site administration > Modules > Repositories > Manage repositories'' and click the settings link for Box
+# Click the link to run the tool
-* The Web interface, found at http://yoursite/repository/boxnet/migrationv1.php
+Or via a CLI script, found at /repository/boxnet/cli/migrationv1.php.
-* The CLI script, found at /repository/boxnet/cli/migrationv1.php
-''Please be aware that this tool could take several hours to run depending on the number of references and their size.''
+''Please be aware that this tool could take several hours to run depending on the number of aliases and their size.''
+Note: After running the tool, the Box settings page will still display the message 'It appears that you were using Box with the API version 1, have you run the migration tool to convert the old references?' Please just ignore it. ;-)
 [[Category:Site administration]]
+[[Category:Portfolios]]

Documentation