This page last changed on Dec 08, 2009 by mryall.

Below are some important notes on upgrading to Confluence 3.1. For details of the new features and improvements in this release, please read the Confluence 3.1 Release Notes.

On this page:

Upgrade Notes

New License Key Requirements for Confluence 3.1

In order to continue using Confluence, you must upgrade your Confluence license to Atlassian's new license key format.

We have undertaken this change to enhance and improve the support we provide our customers. Bear in mind that this license upgrade will not incur any additional costs and does not change Confluence's functionality in any way.

Upgrading an Existing Confluence License for Confluence 3.1 Compatibility

This procedure can only be performed by Confluence Administrators.

To upgrade your existing license to the new license key format, which will be required for continued use of Confluence 3.1:

  1. Visit the license upgrade area in your account at my.atlassian.com.

  2. Enter your Atlassian account details (email address and password) to access and manage your Atlassian product licenses.

  3. Select the appropriate Confluence license to expand its details.

  4. In the 'info' note below your license on the right-hand side of the page, click the 'update your license key' link (as shown in screenshot 1 below). Once this is done, the note changes to that shown in screenshot 2 below.

    Screenshot 1: License Key Update Function



    Screenshot 2: Updated License Key Note



  5. Copy the new license from the text box above this message to your clipboard.

  6. Ensure your upgraded Confluence installation has been started, enter your Confluence site's URL into a web browser and on the Confluence license upgrade screen, click the 'page' link in the 'Description' field to begin updating Confluence with your upgraded Confluence license to open the 'Update Confluence License' page.

    Screenshot: Confluence License Upgrade Screen



  7. On the 'Update Confluence License' page, paste your new license details into the 'License' field.

  8. Enter your the username and password details associated with your license and click the 'Save' button.

    Screenshot: Update Confluence License Page



  9. If your license upgrade was successful, you will be prompted to restart Confluence.

    Screenshot: Successful Confluence License Update Screen

Custom layouts must be re-implemented after upgrading Confluence

If you have customised your Main Layout on either the space or the global level, or if you have a custom theme plugin, the new Link to this Page, Page Restrictions and 'Move Page' dialog box features in Confluence 3.1 will not work immediately for you.

Other Issues:

If you do not re-implement your custom layouts after upgrading to Confluence 3.1, the following may occur:

  • The Atlassian Confluence footer may appear fixed on the page and obscure content that extends below the length of the web page.
  • Some pages may not render at all.

Depending on the version of Confluence you upgraded from and the customisations that had been implemented, other user interface problems or problems with Confluence's functionality may be found.

To re-implement your custom layouts, please refer to Upgrading Custom Layouts for details on retrieving the customisations made to your layouts and re-implementing them into your upgraded version of Confluence.

Customers running Confluence on Weblogic are required to specify the prefer-web-inf-classes element in the weblogic.xml file prior to upgrading Confluence

If you are a customer running Confluence on Weblogic, then before upgrading to Confluence 3.1, you must ensure that the prefer-web-ing-classes element in the weblogic.xml file has been specified with the content value of true. For more information, please refer to Installing Confluence EAR-WAR on Weblogic.

To do this:

  1. Ensure that Confluence and Weblogic have been stopped.
  2. Open the weblogic.xml file in a text editor. (This file is located in the <confluence install directory>\confluence\WEB-INF directory.)
  3. Ensure that <prefer-web-inf-classes>true</prefer-web-inf-classes> has been added as a child element of the <container-descriptor> element, such that your <container-descriptor> element looks something like:
    <container-descriptor>
       <prefer-web-inf-classes>true</prefer-web-inf-classes>
    </container-descriptor>
    

    Your particular weblogic.xml may have other child elements of the <container-descriptor> element, so leave these intact.

  4. Save any changes made to the weblogic.xml file.
  5. Follow the upgrade procedure.

The Drag-and-Drop feature disables the ability to drag and drop links or text in Firefox 3.0

Some browsers like Firefox and Safari allow Confluence users to create links easily by dragging and dropping hyperlinks from other web pages directly into the rich text editor window. This browser-specific feature also allows the rearrangement of text when editing Confluence wiki page content, by highlighting text and dragging and dropping it elsewhere.

However, the Confluence 3.1 Drag-and-Drop feature is not compatible with these link creation and text rearrangement features of Firefox 3.0 and setting up Confluence's Drag-and-drop feature will disable these Firefox 3.0 features.

To allow the Confluence 3.1 Drag-and-Drop feature to work together with these link creation and text rearrangement features of Firefox, upgrade your Firefox browser to version 3.5.

Clarification of supported user management configurations in Confluence

In Confluence 3.1, Atlassian is clarifying our support for user management configurations and code-level customisations. This is being done so that we can deliver significant improvements in our user management performance and configuration in a future release.

Confluence is fully supported with the following configurations provided and documented by Atlassian:

  • Built-in user management with Atlassian-User Hibernate managers ("default user management")
  • Built-in user management, with OSUser LDAP authentication (deprecated since 2.7, moving to Atlassian-User LDAP is recommended)
  • External user management with read-only JIRA JDBC providers ("JIRA delegated user management")
  • External user management with Atlassian-User LDAP providers ("standard LDAP user management")
  • External user management with Atlassian Crowd.

Unfortunately, we cannot offer complete support for code-level customisations in our user management system. The following caveats apply to customers who are using extensions to our user management systems:

  • Custom implementations of Atlassian-User managers are supported for problems which are not related to user management.
  • Custom implementations of OSUser providers are not supported with Confluence. The OSUser APIs required for implementing custom providers were deprecated in Confluence 2.7, so customers with custom OSUser implementations will need to migrate their code to the Atlassian-User API to have support for their Confluence instance.

Advance warning: In Confluence 3.2, Atlassian will be removing functionality required for custom OSUser providers. From this point, custom OSUser providers will not work correctly with Confluence 3.2, so we recommend porting any custom OSUser providers to the Atlassian-User interfaces as part of your Confluence upgrade process.

Upgrade Procedure

Upgrade a test environment first

As always, please test your upgrades in your test environment before rolling into production.

If you are already running a version of Confluence, please follow these instructions to upgrade to the latest version:

  1. Before you upgrade, we strongly recommend that you back up your Confluence Home Directory and database. See the documentation on backing up your Confluence site. If you are using an external database, perform a database backup.

  2. If your version of Confluence is earlier than 3.0.x, then please read the Upgrade Notes Overview and the Upgrade Notes for each version of Confluence listed on that page. (There are hyperlinks to each one.) Furthermore:
    • If you are upgrading from 2.1 or earlier, please read the 2.2 release notes.
    • If you are upgrading from 2.2 or earlier, you will need to upgrade to Confluence 2.7.x first, confirm the upgrade was successful, then upgrade again from version 2.7.x to the latest. For more details, please refer to CONF-11767.

  3. Download the latest version of Confluence.

  4. Follow the instructions in the Upgrade Guide.

  5. If you encounter a problem during the upgrade, please create a support ticket and one of our support engineers will assist you through the process.
RELATED TOPICS

Confluence 3.1 Release Notes


Document generated by Confluence on Dec 10, 2009 18:41