Easy Forums

User’s Guide

1. User’s Guide
2. Features
3. Getting Started
   1. Upgrading from an earlier version of the plugin
4. Highlights of this plugin
   1. In-Built Content Protection
   2. Forum and Topic Access Control
5. Configuration Settings
6. Creating Content
   1. Creating Forums
   2. Creating Topics
7. Roles and Permissions
   1. Reference Table of Allowable Actions for Easy Forum Users by Role
8. Converting an existing Forum into an Easy Forums
9. Mobile Device Support

Features

• The Forum administrators can set permissions for which users can view the forums and topics within the space.
• The Forum administrators can set permissions for which users can reply/comment on topics within the space.
• Administrators and Moderators can modify Page Restrictions to further customize which users can View and Edit either Forms or Topics.
• Moderators are used to control and monitor the Forums. They have permission to edit and delete all posts, as well as Confluence administrators.
• Topics, within a forum, can be created by any user, however, if required each forum can be configured using Page Restrictions to restrict this to specific users.
• Forums can be sorted by most popular posts, status, author, last post or alphabetical.
• A list of top contributors for each forum is shown.
• Administrators and moderators can select which forums are shown on the Forum Summary page, allowing for forums (and topics) to be Active, Read-Only or Hidden.
• All users can subscribe to topics and be notified via email.

Getting Started

Easy Forums is designed to be contained in a new Confluence space. This plugin makes it simple to get started, just follow these easy steps.

1. As the forum administrator, use the ‘Create space’ link in the Space menu to get started.
2. From the list of space templates, select ‘Easy Forums’
3. Give the Forum a name, that will easily be identified in your organization as a discussion area, click the Create button

Do Not combine other third-party plugin features that manipulate Pages with the Easy Forums Space. This may have undesirable behaviours and may not be supported by the vendor.

You will now have the Forum Summary page as the home page of the new space. As an administrator, you can edit the Welcome message and even add other macros to this home page, but it should not be needed.

You will also notice that forum moderators are required, simply go to Confluence User management, go to Groups, find the easyforums-moderators group, and add a few volunteers who will want to help moderate the forums.

That is it, the rest is up to the moderators and users to provide valuable discussions and posts.

Upgrading from an earlier version of the plugin

Version 3.0

If you are upgrading to version 3.0 and you previously used the ‘Topic Creators’ parameter in the Forum Macro, then you need to migrate this functionality into Page Restrictions.

The ‘Topic Creators’ parameter is now deprecated, and the Forum Add and Edit capabilities is controlled by built-in Confluence Space and Page permissions. This allows for both the Moderators and Administrators control over Users’ visibility as well as providing more flexibility and control, than using the single group previously implemented.

To migrate this functionality, please follow these steps.

1. Identify each Forum page that uses the macro parameter ‘Topic Creators’
2. Edit the Forum Page and in the macro placeholder, you will see the group name currently configured displayed (you do not need to edit the Macro to see the name).
3. Click on Page Restrictions (can be down in Edit mode or View mode of the Forum Page), and then add the configured group from the parameter to the ‘Editing Restrictions’ and hit apply.

Further restrictions to both Edit and View can be applied at this point. Moderators and Administrators can now further restrict Users from seeing entire Forums and Topics if required using the built-in Confluence Permissions and Restrictions.

Version 2.0

If you are upgrading to version 2.0, there are a few things you will want to do in your current forum space. Edit the Forum Summary page (space home page), and remove all of the built-in Confluence macros. Leave only the Forum Summary Page macro, and I would suggest also leaving the Welcome message, feel free to change this message for your users.

For each Forum, again you will want to remove all the built-in confluence macros, leaving only the Forum Page macro.

Highlights of this plugin

In-Built Content Protection

This plugin uses built-in confluence restrictions plus extra security to restrict content in the forums from tampering.

The following restrictions apply and can be setup by the administrators if needed.

• The entire space containing the forums can be restricted to selected users using the built-in Space permissions of Confluence. Here the admins can control who can view the forums, create pages (topics) and also create comments (posts). This is common across all forums in the space.
• The Forum Summary page (the space home page) can only be edited by confluence administrators and moderators.
• Each Forum page also can only be edited by confluence administrators and moderators.
• Each forum can also be configured by the administrators and moderators, to further restrict the set of users that can create Topics within the forum. This is done by modifying the Edit View restrictions of the Forum page.
• Each Topic page can only be edited by the author, administrator or moderators. Anyone can add comments to a topic if they fulfill the space permissions and page restrictions of the Topic and Forum for creating comments.

Forum and Topic Access Control

The status of a Forum and Topic can be changed. The administrator and moderators can change the state of both Forums and Topics by clicking on the Status link in the Summary or Forum tables.

If the status of a Forum is changed, this is applied to all the Topics in the Forum. Individual Topics can be changed as well, but will only affect that single page/thread.

The status choices are:

• Active: Authorized users can create content and reply to topics
• Read Only: Users can no longer create new posts, the forum or topic can only be read
• Hidden: Remove the Forum or Topic from the Table, preventing visibility from all users

In order to fully ensure that Hidden Forums or Topics are in fact kept hidden, the plugin by default disables the following built-in confluence features to restrict users from accessing hidden pages.

• The Sidebar with the navigation tree is hidden (Configurable)
• The View in Hierarchy link is hidden
• The Pages link in the breadcrumbs is hidden

Configuration Settings

There are global settings available to customize and control behaviors of this App, for details refer to Configuration.

Creating Content

Creating Forums

Forums can only be created by administrators and moderators. To do this, simply click on the Create New Forum button on the Forum Summary page.

This will create a new Confluence page using a built-in template.

The only thing that is needed for this page is a Title, you do not need to modify the content of this page, however, you may like to setup restrictions for Users who can View and Edit Forum content using Page Restrictions of the Forum.

Save the page and the Forum is active and ready for users.

Creating Topics

Any users with permission can create topics, they will do this by clicking the Create New Topic button on the Forum page. This will start a discussion thread and any users can comment and like other comments in the thread.

Roles and Permissions

EasyForums has 3 Roles; Administrators, Moderators and Users.

• Administrators are all the built-in Confluence Administrators, and these are given all the same privileges as Forum Moderators.
• Moderators are Confluence users, in a specified EasyForums-Moderators group that have full Edit privileges over all Forums and Topics, so that they can moderate all content in the Forums.
• Users are the people that can add Topics and Posts to the Forums.

EasyForums makes use of the standard Confluence Space and Page permissions. Administrators will need to set up the EasyForums space permissions to allow your user base access to the space as you would any other Confluence spaces.

To further restrict individual Forums and Topics, use the built-in Page Restrictions to further restrict Users and Groups from either Viewing or Editing Forums or Topics.

Any Edit or Viewing Restrictions configured on any of the Forum Pages will be applied to every Topic within the Forum.

Also, you can provide Restrictions on individual Topics within a Forum, if you need this level of control. Simply setup Page Restrictions on the Topic.

Post (aka Comment) permissions will adhere to the Permissions and Restrictions of the Topic page. Please remember, however, the 3 Roles defined above do not override the built-in Confluence Permissions and Restrictions, these must be setup accordingly to provide the correct behavior for the 3 roles.

To assist with this setup, please refer to the Reference Table below.

Reference Table of Allowable Actions for Easy Forum Users by Role

The following table shows what functionality each Role in EasyForums is allowed to perform, as well as the required permissions that need to be setup in the Space.

The Administrator role is one of either a System Administrator, Confluence Administrator or Space Administrator.

The Moderator role is assigned to users via the global Configuration.

All Roles must have Space View permissions, just like any other Space, in addition to the required Permissions below.

* This is available only if Page restrictions allow, and these can be setup differently for each Forum and Topic as needed, please refer to Roles and Permissions above. The Owner of Topics and Posts also has permission to Edit their own Topic/Post.

Converting an existing Forum into an Easy Forums

So you may have trialed another plugin, or you have a temporary set of pages setup with existing discussions. Well, you can convert these into Easy Forums compatible pages.

Easy Forums should be located in its own space to take advantage of space restrictions and to be able to hide forums and topics, however all other functionality will work in any existing space as long as the page hierarchy is setup correctly.

This plugin uses a 3 tier hierarchy.

• Forum Summary Page
  • Forum Page
    • Topic Page
    • Topic Page
    • .
    • .
  • Forum Page
    • Topic Page
    • Topic Page
    • .
    • .

The Forum Summary page should be at the top, or parent of the Space or area within confluence. Simply add the Forum Summary Page macro to this page and add any other Welcome message for your users.

Then for each Forum, ensure that they are children pages of the Forum Summary Page. You can use the built-in Move command (harder) or use the ‘View in Hierarchy‘ (easier) to relocate the pages.

Once the Forum pages are in the right place, ie. children of the Forum Summary page, you need to do the following changes

• Edit each Forum page, add the Forum Page macro.
• Add the following label to the page ‘easyforums-forum‘

Now, you will need to do the same thing for each topic page within the forum, if not already there, they need to be children of the corresponding Forum. Then for each Topic page, make these changes:

• Edit each Topic page, and at the bottom of the existing content, add the Topic Page macro
• Add the following label to the page ‘easyforums-topic‘

The basic structure is now done and users will see the list of forums and topics on the parent pages. At this stage, some of the statistics have not been collected and will take time for the data to become available. Do not worry, it will come as users edit content within the forums.

Mobile Device Support

The Easy Forums have been designed to render on mobile devices when accessing Confluence from these devices.

However, in order for this to work correctly, utilizing correct CSS styling, Confluence is missing a critical header component that must be manually added to the global page layout.

To do this, go to the ‘Confluence Administration’ area, then select ‘Custom HTML’ under the Look and Feel category.

Then click the ‘Edit’ button, and in the top section, add the following

At end of the HEAD

<meta name='viewport' content='width=device-width; initial-scale=1.0;'>

Press ‘Save’.

The Forum pages should now render nicely on Mobile devices.