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

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. If your Confluence license is already associated with a Confluence Server ID (that is, most customers running recent versions of Confluence), follow procedure b below. If my.atlassian.com prompts you to enter a Server ID before upgrading your license, follow procedure a:
   
   
   1. Procedure for associating a Confluence license with your Confluence Server ID:
      
      
      1. If you have not already upgraded your Confluence installation to version 3.1, go to your Confluence installation's License Details page to access the Server ID associated with your Confluence license. Make a note of this Server ID.
      2. If you have already upgraded your Confluence installation to version 3.1 and cannot access your Confluence installation's License Details page, open the confluence.cfg.xml file (located inside the Confluence Data Directory) in a text editor and make a note of your Confluence installation's Server ID from the confluence.setup.server.id property in this file.
      3. If you cannot access the Server ID in your Confluence installation using either of the two methods above, then please contact our customer support team for further assistance. This issue may occur when upgrading from a very old version of Confluence.
      4. Follow the remaining prompts on my.atlassian.com to enter your Server ID and then upgrade your Confluence license.
   2. Procedure for upgrading a Confluence license associated with a Server ID:
      
      
      1. Select the appropriate Confluence license to expand its details.
      2. 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 Upgrade Function
         
         
         
         Screenshot 2: Upgraded License Key Note
         
         
      3. Copy the new license from the text box above this message to your clipboard.
4. 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
   
   
5. On the 'Update Confluence License' page, paste your new license details into the 'License' field.
6. Enter the Confluence administrator account's username and password details and click the 'Save' button.
   
   Screenshot: Update Confluence License Page
   
   
7. If your license update 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 customized 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 immediately work for you.

To resolve these issues, you will need to re-implement your custom layouts or reset these custom layouts back to the Confluence default settings.

Other Issues:

The following other issues may occur prior to resolving these issues:

• 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 customizations that had been implemented, other user interface problems or problems with Confluence's functionality may be found.

Re-implementing custom layouts:

To re-implement your custom layouts, please refer to Upgrading Customized Site and Space Layouts for details on retrieving the customizations 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. 

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 customizations. 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 customizations 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 Seraph authenticators are supported for problems which are not related to user management or authentication.
• 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

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 and database.  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.

Checking for Known Issues and Troubleshooting the Confluence Upgrade

After you have completed the steps required to upgrade your Confluence installation, check all the items on the Confluence post-upgrade checklist to ensure that everything works as expected. If something is not working correctly, please check for known Confluence issues and try troubleshooting your upgrade as described below:

• Check for known issues. Sometimes we find out about a problem with the latest version of Confluence after we have released the software. In such cases we publish information about the known issues in the Confluence Knowledge Base.
• Check for answers from the community. Other users may have encountered the same issue. You can check for answers from the community at Atlassian Community.
• Did you encounter a problem during the Confluence upgrade? Please refer to the guide to troubleshooting upgrades in the Confluence Knowledge Base.

• If you encounter a problem during the upgrade and cannot solve it, please create a support ticket and one of our support engineers will assist you through the process.

Useful Plugins

Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on add-on support.

• Unable to render {include} The included page could not be found.

RELATED TOPICS

Confluence 3.1 Release Notes