Skip to end of metadata
Go to start of metadata

The latest Community Forums has a wide range of new features and functionality which were developed in accordance with feedback from customers and clients. The new Forums provide a series of customizable columns as well as search, sort and filter options in a more elegant interface. In order to provide these features we've had to dramatically re-design the architecture of Community Forums in 2.0.  We've implemented or re-implemented (with improvements) almost all of the old Forum features, and encourage you to move over to the new Community Forums add-on.

Why Should I Move My Existing Forums to the latest macros?

There are a number of benefits with the latest Forums, amongst the many benefits of the new macros in Forums 2.x are:-

  • Search, Sort and Filter topics - making it easier to find topics you're looking for
  • Custom configurable forum columns - giving you more power to deploy a forum that looks and feels how you want
  • Improved UI - the new forums have had a UI overhaul, bringing more information to your forum and looking at home in Confluence
  • And we've re-implemented a series of features that previously exhibited bugs, such as pagination of forum topics and activity score


This guide will assist you in migrating your existing forums to use the new forum macros to allow you to access these new features.

Automated Upgrade of Forum Macros

You can use the upgrade task in Community Forums 2.1 to quickly and easily migrate all your existing forums to use the latest macros.

To simplify the process of moving your existing forums to the latest forum macros, we've introduced an upgrade task to quickly and easily update all your Forums.

  1. From the Confluence administration console, select the Upgrade Forum link from the left hand panel.
    Upgrade Forums

  2. The Upgrade Forums page explains the migration process, please read this information carefully.
    You can view which forum macros are used using the pre-migration report information under the  "What will be migrated?" section.
    Pre-migration Information

  3. Click "Run Migration Task" to start the migration task

  4. Again, please read the disclaimer. You may wish to create a back-up of your Confluence instance.

  5. If you are happy to upgrade, click "Accept. This will migrate all pages using the old forum macros to use the latest macros.

  6. You migration should have now completed, you can use the post migration report to see the pages that have migrated.


If you have experienced any errors during the migration task, you can migrate the macros that failed to migrate manually using the guide below or contact our support.

Manual Upgrade of Forum Macros

If you prefer to upgrade manually, or if you have encountered difficulties with the automated migration task, you can choose to perform the upgrade manually. This is a simple task per forum that requires replacing the macros found on an existing forum with the new macros provided in Community Forums version 2.0 and above. This guide will walk you through the process. N.B. We realise that each organisation may have configured their forum specifically, this guide provides a general manual upgrade of the macros although users are welcome to customize their migration further. For information on automated migration please see the section on Automated Upgrade of Forum Macro

1. Upgrading the Forum Macro

The new Forum separates the Forum functionality from the column functionality, giving you more freedom to decide what information is displayed and how. We'll cover how you can first add the new Forum macro with the same parameters as your existing Forum, and then each of the forum table separate columns. As this is a manual migration, you will need to note down 4 parameters from inside the forum macro.


  1. Go to your forum and enter edit mode. Select the Forum-macro and click edit. Note down the parameters for the following fields (if any)
    • Root Page
    • Space
    • Recurse
    • Count

  2. Leave macro editor mode and add a new {forum} macro to the page.

  3. You will now have a new forum macro that will be used later to add columns to

  4. Select the new forum macro and click "Edit"

  5. Update the parameters with the notes you made from the previous old macro. Note: You only need to do this if they are different
    1. Root Page
    2. Space
    3. Recurse
    4. Count -> Topics displayed per page

  6. Save this {Forum} macro configurations

  7. You have now added the basic forum configuration and can now add the column macros in the next step.

2. Upgrading the Forum Summary Macro

Now that you've added the main forum macro, you can add the column macros to the forum macro. This is a simple process of adding 4 column macros to the Forum Macro.

  1. In edit mode, add a {Forum Topic Status Column} to the Forum macro.

  2. Add the {Forum Topic Title Column} to the Forum Macro
  3. Add the {Forum Topic Author Column} to the Forum Macro
  4. Add the {Forum Topic Number of Replies Column} Macro to the Forum Macro
  5. Add the {Forum Topic Number of Views Column} Macro to the Forum Macro
  6. Add the {Forum Topic Last Activity Date Column}

    Default Forum Columns

  7. This provides the basic Forum 2.0 configuration. You can add further column macros and configure these as you wish. For further information on which columns are available and their parameters please see our macro guide.
  8. Save the forum and check you are happy with the configuration.

3. Removing the Add Topic Macro and the Old Forum Macro

  1. The Add Topic Macro is no longer required and does not work with the new Forum macros. The new Forum automatically provides an Add Topic button and shares the same configuration as the rest of your forum, simplifying setup and use of the Forum. Please remove the Add Topic macro from your Forum in edit mode
  2. If you are happy with the configuration of your forum from from step 2, you can remove the old forum macro from the page and save your page. Your new forum is complete.

If you wish to configure your forum further, you can add further macros or configure your Forum macro/ topic column macros to create the perfect forum that meets your organization's specific needs. For further information, please see our macro guide. Once you are happy with your configuration, please remove the old forum macro and save the page.


Top of Page

  • No labels