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:
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 organisation 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.
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 'Dashboard' link has been removed from the header. To go to the Confluence dashboard, click the site logo.
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 are now known as 'site spaces'. The functionality of spaces has not changed. Macros that use the @global parameter are unchanged.
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.
The 'Default Space Content' option has been removed from the Administrator Console. New site templates are available for customising 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.
The welcome message that appears in the top left of your Confluence dashboard can now be customised 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.
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 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.
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 customising 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 |
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.
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.
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?
http://my.confluence.com/display/MYSPACE, they will go to the space home page.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.
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.
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:
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.
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.
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.
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.
Confluence no longer supports Google Gears for drag-and-drop.
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.
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.
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:
The upgrade to Confluence 5 results in a reindex of all the users' personal information once the upgrade has complete. Installations with a large user base (> 10,000) may experience some delays in indexing of new content immediately after the upgrade. This may result in searching and update streams being out of date for a short period of time immediately after the upgrade. |