Writing a Plugin Upgrade Task to Migrate User Data to New User Keys
With Confluence 5.2, we are introducing schema and API changes necessary to support the ability to change usernames. To make that possible, users will have a new, unique, permanent key as well as the already-existing, unique, changeable username. See Renamable Users in Confluence 5.2.
This page tells you how to create an upgrade task for your plugin, to migrate existing user data from older versions of Confluence, on upgrade to Confluence 5.2 and later.
Using SAL as a framework for your upgrade task
SAL (the Atlassian Shared Access Layer) provides a plugin upgrade manager that listens for the 'Framework started' event and looks for plugin upgrade tasks to run. As a plugin developer, you can provide a plugin upgrade task component, and SAL will guarantee that the upgrade task is run on Confluence startup.
Step 1. Check prerequisites
Your plugin needs to use version 2 of the Atlassian Plugin Framework. Check that you have the
plugins-version="2" attribute in
Step 2. Add dependencies on SAL and the Confluence User Compatibility Library
Your plugin project needs access to the SAL API and Confluence User Compatibility library. Add the following dependencies to the plugin's
Step 3. Write the upgrade task
Write a class that implements the
interface provided by SAL. Here is an example implementation:
Step 4. Register the upgrade task in your plugin
Add the upgrade task as a component in the plugin:
The PluginUpgradeManager in SAL will automatically scan for components that implement the
PluginUpgradeTask interface. Please note that they have to be declared as
Step 5. Repackage and deploy
Repackage the plugin, deploy it to the instance of Confluence that you want to upgrade and restart the Confluence instance. The plugin upgrade task should be executed when Confluence starts up.