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

On this page:

Preparing your team for Confluence 5

Confluence 5.0 introduces a number of significant changes to the user experience: A new way of creating content, a redesigned header, a new sidebar, and other changes to the look and feel of your site. People in your organization will need to be aware of the coming changes, so that they can plan and prepare for them. We have written a guide to help you: Planning for Confluence 5.

In addition, if you are upgrading from Confluence 3.5 or earlier please note that the change to the Confluence editing experience is significant. See the guide to Planning for Confluence 4.

Upgrade notes – user interface and editor

Changes to 'Browse' menu and space administration options

For all spaces using the default theme, the 'Browse' menu has gone. It is replaced by options in the new sidebar. For help on preparing Confluence users for this change, see Planning for Confluence 5.

If your Confluence site includes plugins (add-ons) that add options to the 'Browse' menu:

• The options now belong under 'Space tools' in the sidebar. They will appear there if the plugin author has already updated the plugin for Confluence 5.0.
   
• The options may appear in the help menu (accessible from the Confluence header) after upgrade. This will happen if the plugin author has not yet updated the plugin for Confluence 5.0. See our guidelines for plugin developers: Browse Menu and Space Tools changes in Confluence 5.0.

Changes to the dashboard

The 'Dashboard' link has been removed from the header. To go to the Confluence dashboard, click the site logo.

Renamed macros: Metadata Details and Details Summary

We have renamed the following macros: Metadata Details is now Page Properties. Details Summary is now Page Properties Report. When you upgrade to Confluence 5.0 or later, an upgrade task will automatically rename all existing Metadata Details and Details Summary macros on your Confluence pages. The wiki markup and storage format code for these macros has not changed. 

Global spaces renamed 'site spaces'

Global spaces are now known as 'site spaces'. The functionality of spaces has not changed.  Macros that use the @global parameter are unchanged. 

Upgrade notes – administration

Space logo is now round

As part of the refresh of the Confluence user interface, we have changed the shape of the space logo.Existing logos may be affected, and may not look good in the new round format.

We have added a simple way for space administrators to crop and update logos, directly from the space sidebar. Go to a page in the space and choose 'Configure sidebar'. Then choose the edit icon  next to the space name. For step-by-step instructions, see Changing a Space's Logo.

Default space content now managed in global templates

The 'Default Space Content' option has been removed from the Administrator Console. New site templates are available for customizing the homepage content of new site and personal spaces. These site templates are available on the 'Global Templates' screen of the Administration Console. An upgrade task will convert any existing default space content (created using the old wiki markup editor) to the new format. The 'Default Space Content' template will show as 'Edited' with your custom content inside. 

Welcome message now managed in global templates

The welcome message that appears in the top left of your Confluence dashboard can now be customized via a site template, available on the 'Global Templates' screen of the Administration Console. This means you can use the rich text editor to edit the content. An upgrade task will convert your existing welcome message (created using the old wiki markup editor) to the new format. The default welcome message template will show as 'Edited' with your custom content inside.

New getting-started guide on dashboard

By default, the Confluence dashboard now displays a quick-start guide for administrators, under the site welcome message on the left. This section of the dashboard is visible to Confluence administrators and system administrators only. It is not configurable via the web interface, but you can update or remove it by editing the site layout as described in Customising the Getting Started Guide on the Dashboard.

Confluence administrator permission now sufficient to configure application links

Confluence 5.0 includes version 3.10.6 of Application Links. Note that people with 'Confluence Administrator' permissions can now configure application links. For example, they can link Confluence to JIRA. Previously, you needed 'System Administrator' permissions to perform this function. Confluence administrators will be able to add, modify and remove application links and project links. However, Confluence administrators can configure only OAuth authentication for application links.

Custom themes, layouts and CSS will probably break

To achieve the new look and feel of Confluence 5.0, we have made major changes to the CSS and layouts of the Confluence pages. If your Confluence site or any spaces use a custom theme or custom CSS, they will probably no longer work after the upgrade.

If you are using the Confluence default theme or the Confluence Documentation theme, no action is required.

If you are using the Easy Reader theme, your site and affected spaces will be moved to the Confluence default theme. See below.

If you are using a third-party theme, please use the plugin manager in your Confluence Administration Console to check if there is a new version of the theme that is compatible with Confluence 5.0. See Checking app compatibility with application updates.

If you have applied a custom theme, we recommend that you revert to the Confluence default theme before upgrading to Confluence 5.0. See how to apply a theme to a site or to a space.

If you have applied custom CSS, you will need to update the CSS after the upgrade. See our guide to styling Confluence with CSS. Confluence 5.0 introduces many new CSS rules to the application as well as heavily modifying existing CSS. You will need to update your CSS to reflect these changes. In order for your CSS to continue working you will need to ensure that any new rules added to Confluence are appropriately overridden in your CSS. Additionally you will probably want to go through your CSS and remove any overrides that are no longer required.

If you have applied custom decorators or layouts, you will need to update them after the upgrade. See our guide to customizing your site and space layouts. Confluence 5.0 introduces many new markup patterns. If you do not have some or all of these patterns in place, you may find that your custom decorator does not look the way it is supposed to. The best way to update your decorator is to compare it to the decorators used in Confluence 5.0 and adapt yours to follow the same patterns.

These URLs may be useful, if your CSS breaks to the extent that you cannot access the options via the Confluence UI:

• Choosing a theme for the entire site:
  

  http://MY.CONFLUENCE.COM/admin/choosetheme.action

• Editing the CSS for the entire site:
  

  http://MY.CONFLUENCE.COM/admin/editstylesheet.action

• Editing the custom HTML for the entire site:
  

  http://MY.CONFLUENCE.COM/admin/editcustomhtml.action

• Choosing a theme for a space:

  http://MY.CONFLUENCE.COM/spaces/choosetheme.action?key=SPACEKEY

• Editing the CSS for a space:

  http://MY.CONFLUENCE.COM/spaces/editstylesheet.action?key=SPACEKEY

Upgrade notes - functionality removed or replaced

Easy Reader theme is no longer available

Confluence 5.0 and later releases do not include the Easy Reader theme. We are moving towards a single Confluence theme that presents a simplified default experience. At the same time, we want to make it easy for add-on developers to extend Confluence with custom themes. Our analysis has shown that very few Confluence sites use the Easy Reader theme.

If your Confluence site currently uses the Easy Reader theme, the site and the spaces that use the theme will be automatically transferred to the default theme when you upgrade to Confluence 5.0.

Advance warning of plans to merge Documentation theme with the default theme

This is an advance notice that we plan to merge the functionality of the Confluence Documentation theme with the Confluence default theme. We do not yet have a specific date for this plan, and we are interested in your feedback. The new default theme, to be introduced in Confluence 5.0, includes a sidebar with contextual navigation. Our plan for a later release is to include all the features of the Documentation theme into the default theme, and then remove the Documentation theme from Confluence.

If you are interested in this change and would like to give us feedback, please add a comment on this blog post: Advance warning of plans to merge Documentation theme with the default theme. We are especially interested to know which features of the Documentation theme you use and value the most.

Destination of links to top level of space is no longer configurable

We have removed a little-used option from the Confluence site configuration. Up to now, Confluence had an option called 'View Space Goes to Browse Space'. The option determined what happened when people clicked a link that pointed to the root of a space. For example: http://my.confluence.com/display/MYSPACE

If the option was set, Confluence would direct people to the 'Browse Space' view instead of the space home page. Now this option has gone, and Confluence will always direct people to the home page of the space when they click such a link.

How does this affect you?

• You do not need to do anything.
• The 'View Space Goes to Browse Space' configuration no longer applies to any spaces, even if you had previously selected this option.
• When people click a link that ends in the space key, like http://my.confluence.com/display/MYSPACE, they will go to the space home page.

Office Connector configuration restricted to system administrators

Configuration of the Office Connector was previously available to both Confluence administrators and system administrators. In Confluence 5.0 and later, this action is now available to system administrators only. See Global Permissions Overview.

Permission for page-level exports no longer configurable

Previous versions of Confluence offered a configurable permission in the space administration interface, to control who can export pages to PDF and Microsoft Word. In Confluence 5.0 and later, this permission is no longer configurable. People who have permission to view the page will also be able to export the page to PDF and Word.

Note that this affects page exports only. The space export permission is still present and configurable.

Direct access to labels view no longer available via menus

In earlier versions of Confluence, people could get to the labels view by choosing 'Browse' > 'Labels'. Now that the 'Browse' menu has gone from the default theme, this option is no longer available.

To find the labels view:

• Where you see a label on a page, blog post or attachment, choose the label to go to the labels view. (Any page or blog post that has labels will have them listed together in a block at the bottom of the page.)
• You will also see labels in the 'Attachments' view or in a listing of attachments provided by the Attachments macro.

Alternatively, visit the following URL:

<MY.CONFLUENCE.SITE>/labels/listlabels-alphaview.action?key=MYSPACEKEY. 

For example: https://confluence.atlassian.com/labels/listlabels-alphaview.action?key=DOC

Note: The Documentation theme retains the 'Browse' menu in Confluence 5.0, and thus the 'Browse > Labels' option is still accessible.

Ability to add space labels no longer available

In order to simplify the use of labels in spaces, we have removed the ability to add space labels. Existing space labels will remain, but you will be unable to add new space labels to your spaces. Space categories are not affected by this change. 

JavaScript configuration option

We have removed an option from the general configuration section of the Administration Console that allowed for JavaScript to be served in the footer instead of the header. JavaScript will now always be served in the header.

Upgrade notes – integration and supported platforms

Team Calendars 3.1 or later required

If you are using the Team Calendars add-on for Confluence, you will need to upgrade to Team Calendars 3.1 or later. Earlier versions of this add-on will not work with the new design in Confluence 5.0.

End of support for Google Gears

Confluence no longer supports Google Gears for drag-and-drop.

End of support for Java 6

As previously announced, from this release onwards we no longer offer support for Java 6 (JRE and JDK 1.6). Please see End of Support Announcements for Confluence.

End of support for Tomcat 5.5

As previously announced, from this release onwards we no longer offer support for Tomcat 5.5.x. Please see End of Support Announcements for Confluence.

Upgrade procedure

Note: Upgrade to a test environment first. Test your upgrades in your test environment before rolling them 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 and other important directories 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 4.3, read the  release notes and upgrade guides for all releases between your version and the latest version.
   In particular:
   • Read the Confluence 3.5 Upgrade Notes.
   • If you are upgrading from 2.1 or earlier, read the 2.2 release notes too.
   • If your site contains links to a file system (for example [\\\C:\Foo\Bar\foobarpreso.ppt] these may break when upgrading to Confluence 5.0.  We recommend that you upgrade directly to Confluence 5.0.3. Refer to  CONF-23575 - Getting issue details... STATUS  for more details.
3. Download the latest version of Confluence.
4. Follow the instructions in the Upgrade Guide.
5. "Create" option not activated on some sites: If the global default language of your Confluence site is not English, you will need to install a patch in the form of a plugin. For more information, please refer to this article in our knowledge base: Nothing Happens when Users Click on The "Create" Button.
   
   

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 help you.