Confluence 3.5 Upgrade Notes

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

On this page:

Upgrade Notes

Autowatch Turned On by Default

This release includes the new 'autowatch' feature, as described in the release notes. With autowatch turned on, you will receive an email notification each time someone edits or comments on a page that you added or updated.

Note that autowatch is enabled by default for all new and existing users on upgrade. We recommend that you let all Confluence users know that autowatch will be turned on for their usernames when you upgrade to Confluence 3.5. People can turn autowatch off by editing the email settings in their user profile.

New Profile Pictures

This release brings a fresh set of profile pictures. After you have upgraded to Confluence 3.5, the old set will no longer be available for selection. Users who have already chosen one of the old pictures will keep that picture. If they later choose a new picture or upload their own picture, they will not be able to go back to the old picture again.

Team Labels (Now Called 'Space Categories') May Need Tidying Up

In Confluence 3.5, we have changed the term 'team labels' to the more descriptive term 'space categories'. These are keywords that you can apply to spaces, in order to group logically-related spaces.

Confluence 3.5 also introduces a new space directory that displays a list of spaces and offers them grouped by space category.

If your Confluence site has a number of team labels (now called space categories) already applied to the spaces, you may want to tidy up the categories to optimize your space directory.

New Support Tools Plugin

As mentioned in the release notes, the Atlassian Support Tools plugin is now shipped with Confluence. If you installed the earlier version of the plugin, you will need to uninstall it before upgrading Confluence.

Changes to User Management in Confluence

The way Confluence stores, accesses and manages users and groups is completely different in Confluence 3.5. You will notice many improvements, as described in the release notes. When you upgrade to Confluence 3.5, the upgrade process will automatically migrate your data by doing the following:

  • Copying the configuration data from the existing OSUser or Atlassian User XML files into the Confluence database.
  • Migrating your user and group data into the new database tables. It will not destroy the old data. The old tables remain in the database.
  • Migrating internal and external user preferences. So if an LDAP user has logged in to Confluence before, all the same preferences will be there on next login after upgrade.

The sections below describe the upgrade considerations for each supported configuration type.

For Customers with Internally Managed Users

If your Confluence installation currently manages its users and groups in the Confluence database then there are no actions required on upgrade. This applies to Confluence sites that are not connected to Crowd, JIRA, LDAP or a custom directory for user management.

For Customers using LDAP for User Management

If your Confluence currently uses the standard method of connecting to an LDAP server for authentication and user management then the upgrade process will migrate the configuration.

To ensure that the upgrade process can migrate your configuration, please follow the Confluence upgrade guide. In particular, make sure that you:

  • Copy the following files from your old Confluence installation to your new Confluence installation:

    <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml
    <Installation-Directory>/confluence/WEB-INF/classes/osuser.xml
    

Please follow these steps after the upgrade is complete:

  • Ensure that the LDAP connection is correctly configured. 
  • Ensure that the directory order is set to match your environment and requirements. 
  • Enable nested groups, if required in your organization. To understand the performance ramifications of this.
  • Note that people will need to wait until the automatic synchronization task has copied their user and group information from the LDAP directory to the internal cache before they can log in. The synchronization task will start automatically in the background when the directory is configured. If someone tries to log in to Confluence before the synchronization task has finished, the user authentication will fail. 

If you are using a legacy LDAP configuration (such as OSUser with LDAP authentication only), you'll need to reconfigure your LDAP support as covered on Connecting to an LDAP Directory and Connecting to an Internal Directory with LDAP Authentication. In case you encounter an issue, please refer to Upgrade to Confluence 3.5 with OSUser LDAP authentication fails for more details.

For Customers Using JIRA for User Management

If you are already using JIRA to manage your Confluence users, via the JDBC connection to the JIRA database, you must upgrade Confluence to version 3.5 before upgrading JIRA to version 4.3.

JIRA 4.3 has a significantly different database schema and exposes a new REST interface, which Confluence will depend on for continued JIRA user management. If you upgrade to JIRA 4.3 before upgrading to Confluence 3.5, your Confluence users will no longer be able to log in once you upgrade to Confluence 3.5.

Confluence 3.5 does not ship with an OSUser migrator, and it will not recognize the OSUser definition in your atlassian-user.xml file. When upgrading Confluence:

  1. Do not copy the modified atlassian-user.xml and osuser.xml to your Confluence 3.5 installation directory.
  2. Ensure that previous Confluence's server.xml file is copied to your Confluence 3.5 installation directory, in order to retain the JIRA datasource.
  3. Upgrade to Confluence 3.5.

Please follow these steps after the upgrade is complete:

  • Log in to Confluence 3.5.x using the administration username and password you used prior to configuring JIRA user management in Confluence. (Confluence is not yet configured to point to JIRA, so your JIRA credentials will not work.)
    • If you cannot remember or do not have a password which allows you to log in, reset the administrator's password in the database and restart Confluence to log in.
  • Ensure that the JIRA connection is correctly configured:
    • If you plan to connect to JIRA 4.2 or earlier, set up the 'Legacy JIRA Database Connector'. 
    • When you upgrade to JIRA 4.3 or later, set up the new JIRA server connection. 
  • Ensure that the directory order is set to match your environment and requirements. 

For Customers Using Crowd for User Management and SSO

If you are using Confluence with Atlassian Crowd for user management and SSO:

  • You will need to upgrade to Crowd 2.1 or later, before upgrading to Confluence 3.5. Earlier versions of Crowd are not compatible with Confluence 3.5. Confluence 3.4 and earlier will work with Crowd 2.1.
  • Copy the following files from your old Confluence installation to your new Confluence installation:

    <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml
    
  • You no longer need to copy the Crowd integration JAR files into Confluence's WEB-INF/lib/ directory.
  • If you are using com.atlassian.crowd.integration.seraph.v22.ConfluenceAuthenticator for SSO (defined in $CONFLUENCE$/WEB-INF/classes/seraph-config.xml), please use the newer version instead: com.atlassian.confluence.user.ConfluenceCrowdSSOAuthenticator. Specifically, change this:

    <authenticator class="com.atlassian.crowd.integration.seraph.v22.ConfluenceAuthenticator"/>
    

    to this

    <authenticator class="com.atlassian.confluence.user.ConfluenceCrowdSSOAuthenticator"/>
    
  • After the upgrade, you may notice a difference when first connecting Confluence to Crowd: People will need to wait until a synchronization task has copied their user and group information from Crowd to the internal cache before they can log in. If someone tries to log in to Confluence before the synchronization task has finished, the user authentication will fail.
  • Ensure that the directory order is set to match your environment and requirements.

For Customers Using Custom Authenticators

Custom authenticators, as defined in seraph-config.xml, are not affected and should work in the same way as in earlier versions of Confluence.

For Customers Using Custom Directory Connectors

Custom directory types are not possible and not supported in Confluence 3.5 and later. If you have custom providers defined in OSUser or in Atlassian-User, thus defining your own storage for users and groups, the upgrade procedure will prevent you from starting Confluence.

Please see if one of the following solutions will work for you:

  • If you have written a custom provider to support an LDAP schema not natively supported by Confluence 3.4 or earlier, you may no longer need your custom directory connector. Please check the supported LDAP schemas to see if you can use the new LDAP connectors supplied with Confluence 3.5.
  • If you have written a custom provider to support nested groups, you can now use the new directory connectors supplied with Confluence 3.5. 
  • If you have written a custom provider to connect to your own database, please consider loading the data into Confluence via the database instead. You will then need to flush the relevant caches in the application.

If you need to keep the custom directory connection, please consider whether Atlassian Crowd meets your requirements. 

Confluence 3.5 includes the Unified Applications Link (UAL) plugin which manages trust relationships. Authentication for trust relationships, such as Trusted Apps and OAuth, is now configured via Application Links in your administration console. When you first navigate to the Application Links screen, you will be prompted to upgrade your existing Trusted Apps and OAuth trust relationships to application links.

For instructions on how to upgrade your links, see Upgrading an Application Link.

Please note, there is a known issue with the upgrade dialog. This will affect you if you have set up two different types of authentication (e.g. Trusted Apps and OAuth) to the same remote server. The upgrade message displayed on your Application Links screen will prompt you to upgrade two application links. However, you actually only need to have one application link with two authentication types configured, i.e. upgrade one application link and then configure the missing authentication type on that upgraded link.

Upgrade Task Will Reindex Confluence Automatically

We have upgraded the Confluence search engine from Lucene 2.2.0 to 2.9.3. As a result, a reindex is highly recommended when you upgrade. The search will continue to work after upgrade even without a reindex, but you will see exceptions in the logs and reduced capabilities.

When you upgrade to Confluence 3.5, an upgrade task will run automatically to rebuild the index. During the rebuild task, the upgrade process will require three times the size of the index on disk in order to perform the upgrade task. This space will be freed up when the upgrade process has finished.

If you would prefer to rebuild your index later, you can pass the following argument to Confluence when starting up after the upgrade:

-Dconfluence.skip.reindex=true

The initial startup will show an error message from ConfluenceSearcherInitialisation in the logs, because the warming query is run before the upgrade task. This is not a problem.

Changes to Recognized System Properties

We have removed the following system property: confluence.import.use-legacy-importer. Specifying this property will no longer have any effect in Confluence. 

Connections to MySQL Databases

If your Confluence installation is connected to a MySQL database, please ensure that this database uses the 'READ-COMMITTED' transaction isolation level. MySQL's default transaction isolation mode:

  • will cause issues with missing LDAP and other remote directory user permissions.
  • is no longer supported in Confluence 3.5.

See the last step of the MySQL server installation procedure for details.

Deprecation of Functionality

This section provides advanced warnings of features in Confluence 3.5 that will be deprecated in Confluence 4.0 (a future release of Confluence).

Converting a Global Space to a Personal Space

Confluence 4.0 will no longer support the ability to convert a global space to a personal space. Our research has shown that this feature is used very little. Hence, we have decided to remove this feature as part of our ongoing mission to simplify Confluence where possible. 

The 'Mail Page' Feature

In Confluence 4.0, the 'Mail Page' plugin will no longer be bundled with Confluence. This means that the 'Mail Page' feature for e-mailing a page will not be available in Confluence (out of the box) and the Share button will be the recommended method for e-mailing pages to others.

Notes about Supported Platforms and Libraries

End of Support for PostgreSQL 8.1, Firefox 3.0

As previously announced, from this release onwards we no longer offer support for:

  • PostgreSQL 8.1.
  • Firefox 3.0.

Please see End of Support Announcements for Confluence.

Advance Notice of End of Support for MySQL 5.0, Firefox 3.5, Safari 4, Internet Explorer 7

We are planning to end support for the following database and browsers in Confluence 4.0:

  • MySQL 5.0.
  • Firefox 3.5.
  • Safari 4.
  • Internet Explorer 7 (IE7).

Please see End of Support Announcements for Confluence.

Added Support for Safari 5

We now offer support for:

  • Safari 5 in Confluence 3.5.

Lucene Upgraded – Some Methods Now Deprecated

This section is of interest to plugin developers. As stated above, we have upgraded the Confluence search engine from Lucene 2.2.0 to 2.9.3. A number of Lucene methods are now deprecated. These methods will be listed when you compile your plugin. We recommend that you consult the Lucene documentation and replace these methods as soon as possible. They will no longer be available when Confluence upgrades to Lucene 3. This further upgrade is not yet scheduled, but we plan to do it sometime.

Scriptaculous and Prototype JavaScript Libraries Removed

jQuery is the supported JavaScript library for plugin developers.

We first announced the deprecation of other JavaScript libraries with Confluence 2.8. Please note that we have now removed the following libraries from Confluence:

  • Prototype
  • Scriptaculous

X11 Dependencies/Libraries No Longer Required

X11 dependencies/libraries on Unix-/Linux-based operating systems are no longer required by Confluence 3.5 or later. Hence, these libraries do not need to be installed for your Confluence 3.5 upgrade or when installing a new instance of Confluence 3.5 or later.

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 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.4.x, then please read the Upgrade Notes Overviewand the Upgrade Notes for each version of Confluence listed on that page. (There are hyperlinks to each one.) Also:
    • 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 Other 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 Answers.
  • 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.

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.

  • Appfire's Upgrade Assistant for Confluence (UAC) is a commercial plugin that simplifies the upgrade process into an easy-to-use wizard.
RELATED TOPICS

Confluence 3.5 Release Notes

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport