mvnForum Administration Documentation

Cord Thomas

Software Architect
Lupine Information Systems

20 January 2005

Revision History
Revision v0.420 January 2005cat
Updated for new features in RC4.
Revision v0.320 April 2004cat
Updated for new features in RC3.
Revision v0.216 Jan 2004cat
Updated for new features in RC2. Refactor documentation to be more in line with forum structure.
Revision v0.18 June 2003cat
Prepared documentation for RC1 with installation and user instructions.

Table of Contents

  1. Foreword
  2. 1. Administration
    1. General
      1. Test System Configuration
      2. Configure mvnForum
      3. Email Templates
      4. Build Searching Index
    2. Overview
    3. Forum Management
      1. Category
      2. Forum
      3. Assign Group to Forum
      4. Assign Member to Forum
    4. Groups
      1. Default Groups
      2. Group Management
    5. Users
      1. Default Users
      2. User Management
      3. Rank Management
    6. Permissions
      1. Combined Permissions
      2. Individual Permissions

Foreword

The Administration Guide provides an introduction to setting up your first online forum and the proper use of the forum administration tools. If you do not see what you are looking for here, take a look at the FAQ section, carefully compiled for your edification.

Chapter 1. Administration

General

To perform general forum administration tasks, such as testing the configuration of the forum installation or building the search index, visit the Miscellaneous tasks page.

Test System Configuration

To test the database, mail support, indexing support and image processing support, click the Test System Configuration link on the Miscellaneous page or on the Admin Control Panel page. The following system parameters are tested. Below are a brief explanation on the significance of each and where to look to correct the problem.

  • Support JNDI - required for the Java Application Server to locate the forum framework classes. If this is missing then most likely the forum is not installed properly.

  • Java SQL Ext - the standard Java SQL extensions provide standard connection pool via the javax.sql.DataSource

  • Java Activation Framework - required for JavaMail to send email

  • Java Mail - the Java Mail extension is used to process SMTP messages sent from the administrator and by the Forum Watch system

  • Jakarta BeanUtils - required for common upload to upload avatar images

  • Jakarta Common Logging - the Java Common Logging interface is a common interface for logging messages and used by mvnForum as the template for logging events and errors - this interface can be extended to provide custom logging solutions

  • Jakarta Common Codec - not sure

  • Jakarta Common Collection - supports collection operator utilities

  • Jakarta Common Digester - not sure

  • Jakarta Common Lang - not sure

  • Jakarta Regular Expressions - regular expressions are used to support the Search functionality

  • Jakarta Lucene - a complete content indexing and searching interface that supports the forum thread search capabilities

  • Dom4j - an XML document object model parser for java

  • Image Processing - used to support the avatar icons and captcha images

Configure mvnForum

New to mvnForum is the ability to configure the application setup using the online configuration interface. The minimal setup must be completed first. Once the forum is running and you can access the Admin Control Panel, you can configure the remaining forum setup from the control panel. The minimal setup steps to get mvnForum running are presented in the installation.

The configuration menu, accessed from the Admin Control Panel, has the following main parts: backing up the configuration file; core forum configuration, which reflects the parameters found in mvnforum.xml; factory configuration for identifying the implementations of the major forum user authentication and http request processing; interface configuration for global standard user interface settings; and the core server configurations which reflect the parameters found in mvncore.xml

Changes to the configuration information are not immediately put into place. As a matter of fact, most application parameters would not be noticed until the Servlet container is restarted. mvnForum provides a reload feature to force the application to reread the forum configuration. To force mvnForum to reread the configuration information, click the Reload all Changes link on the Admin's configuration menu. mvnForum will restart after reading all the parameters in the mvnforum.xml configuration file; namely the majority of user-experience features.

This section defines the purpose of the individual configuration parameters

Backup Configuration File

  • Before making changes to the forum configuration, make a backup of the two configuration files. From the admin's forum configuration page, click the Backup Configuration File link to execute a backup of the configuration file.

  • To recover to the saved version, you must stop the Servlet container, copy the backup of the configuration files over the current files, and restart the Servlet container.

mvnForum Core Configuration

  • mvnforum_home - [absolute network path] - MVNFORUM_HOME is a folder that cannot be accessed from the web, you could create a folder mvnForumHome in your WEB-INF and set MVNFORUM_HOME to point to this folder. Please note that the example is for the Windows system, for the *nux system, it look like this: MVNFORUM_HOME = /home/tomcat/mvnForumHome

  • webmaster_email - [String - valid email address] email address for webmaster

  • logo_url - [String - a complete http url] - the url the logo points to

  • supported_locales - [String - any valid locale] a semicoma-separated list of locales supported by the site. This is for internationalization/localization support.

  • default_locale_name - [String - one of the valid list of supported_locales] - the default locale for the forum

  • default_guest_name - [String] - set default name of a virtual Guest user. IMPORTANT: It will be overridden with the data from the database, if it exists (for the Guest user)

  • disable_passwordless_auth - [true/false] - this release supports realm/customized authentication, if you would like to use this feature, then uncomment and set DISABLE_PASSWORDLESS_AUTH = false

  • require_activation - [true/false] - forum members can be created (or seeded) by the forum administrator(s) or through self registration. For self-registering forum members, you can require that they activate their accounts through an email exchange. This was recently introduced to many forums to prevent bots (automated agents) from creating forum accounts. Through the email activation, there is a human step involved in registering for forums (though there is the chance that people will enhance their bots with the ability to collect mail information and respond accordingly).

  • enable_login_info_in_cookie - [true/false] - enable tracking of login information through browser cookies

  • enable_login_info_in_session - [true/false] - enable tracking of login information through Servlet sessions

  • enable_login_info_in_realm - [true/false] - use application realm-specific authentication

  • enable_login_info_in_customization - [true/false] - ??

  • enable_new_member - [true/false] - enable self-registration

  • enable_new_post - [true/false] - enable creating new posts - this is a default for the entire forum

  • enable_rss - [true/false] - enable RSS feeds. If false, RSS feeds will not be supplied

  • enable_watch - [true/false] - enable thread/post watches

  • enable_attachment - [true/false] - enable file attachments to threads/posts

  • enable_avatar - [true/false] - enable member avatars

  • enable_emoticon - [true/false] - enable using emoticons

  • enable_moderation - [true/false] - enable forum moderation

mvnForum Factory Configuration

  • member_implementation - the implementation class providing forum member management

  • onlineuser_implementation -

  • authenticator_implementation -

  • requestprocessor_implementation -

mvnForum Interface Configuration

  • max_attachment_size -

  • max_favorite_thread -

  • max_edit_days -

  • max_attach_days -

  • max_delete_days -

  • rows_per_page -

  • rows_per_rss -

  • hot_topic_threshold -

  • max_posts_per_hour -

  • max_members_per_hour -

  • enable_backup_on_server -

  • max_import_size -

mvnForum Server Configuration

  • use_datasource -

  • database_type -

  • driver_class_name -

  • database_url -

  • database_user -

  • database_password -

  • max_connection -

  • max_time_to_wait -

  • minutes_between_refresh -

  • datasource_name -

  • blocked_ip -

  • mail_server -

  • default_mail_from -

  • username -

  • password -

  • port -

  • blocked_ip -

  • context_path -forum -

  • server_path -

  • server_hour_offset -

  • blocked_user_agent -

Email Templates

Email templates are used to send standard emails to new members (for account activation), password recovery requests, and for users who have active forum watches (requesting notification of updates to discussion topics they are interested in).

Using standard keyword substitution, you can create standard templates by accessing the email template editor from the Miscellaneous tasks in the Admin section. Using the predefined keywords presented at the top of the template editor, change one of 3 templates.

After making changes to a template, be sure to commit the changes by clicking Save Template. Selecting from the list of templates to access another template will not commit the changes you have just made.

Build Searching Index

mvnForum provides a comprehensive set of search features that enable the user to find posts by author, post topic, and date. The search features are supported by Jakarta's Lucene project. Lucene builds an index configured by mvnForum which speeds user's searches of the forum content. To rebuild the index, click on the Rebuild Searching Index.

Overview

To get started with mvnForum, you should understand these basic issues.

Getting started with forum administration

  • The hierarchy of the forums is categories to forums to threads (or posts). Threads belong to a single forum and forums belong to a single category.

  • Guests can access forum threads for reading and searching only

  • Access to forums is restricted based on group and user permissions.

  • Given that, here is a typical setup process for creating a new forum

    • Create a new Group, called newGroup

    • Set the global group permissions for the group so members of the group can login, and perform other tasks

    • Create a new User, called newGroupUser

    • Set the newGroupUser as the owner of the group, newGroup (this also adds the user newGroupUser as a member of this group)

    • Create a new category for the forum, called newCategory

    • Create a new forum, newForum, in the newCategory category

    • Set the forum-specific group permissions of the newGroup so they can moderate the forum

    Following these actions, you will have a new forum and a user that belongs to a group that can access and moderate all threads in the new forum. mvnForum has a very granular approach to managing forums and group/user permissions to the forums.

Forum Management

mvnForum follows a typical structure for grouping discussions into common interests. To manage these groups of discussions, an administrator can create, edit and delete forum categories and forums using the Forum Management control panel. Accessed from the forums administration control panel, the forum management interface shows the list of current categories and forums. Use the links provided to manage forum categories and forums.

Category

Forum categories are top-level groups of forums. An administrator can create categories, add and remove forums from a category and remove categories. Also, once categories have been added to the list, administrators can change the order of the categories and add and remove forums within the categories. For forum management, see the Forum section.

  • Add Category - click on the Add new Category link near the top of the page to load the category creation screen. A category has a name and a description. Use a short enough description to give forum users a concise understanding of the types of forums they will expect to find in the category.

  • Edit Category - click on the edit icon (Edit icon) on the right side of the row of the forum you want to edit to navigate to the category edit screen. Change the description of the category or the category sort order.

  • Delete Category - Because of the danger of removing categories, the web interface only allows deleting empty categories. To delete a category, first delete all the forums.

Forum

Forums are groups of topics sharing a common thread or subject. The forum is the common meeting place for people to share ideas and ask questions on topics where they can expect to receive answers from people sharing interests and knowledge on the topics in the forum. To administer the list of forums supported by your site, navigate to the Forum Management interface accessed in the administrator control panel.

  • Add Forum - click on the Add Forum link in the Add Forum column of the Forum Category you want to add the forum to. To add a forum, the category must first exist. If you have not added a category, visit the c help.

    Adding a new forum

    • Forum Category - a forum belongs to a category - select the forum category from the list

    • Forum name - must be unique within a category. Currently, the name can be up to 250 characters long. It is suggested you keep name shorter for better display results and avoid special characters that might not be rendered by various browsers.

    • Description - optionally provide a description for the forum. This description can provide people clues about the forum topic if the name is not clear enough.

    • Forum Order - the order the forum appears in the list of forums within the forum category.

    • Forum status - sets the forum's status to either normal, disabled, locked, or closed. These status mean:

      Forum Status

      • Normal -

      • Disabled -

      • Locked -

      • Closed -

    • Forum Type - sets the forum's type to either normal or private. These types mean:

      Forum Type

      • Normal - The forum is open to all registered forum users

      • Private - The forum is open only to those members given access by the forum owner(s). To give members access to a private forum, do this //TODO - working with private forums

    • Moderation Mode - sets the forum's moderation mode to either normal or one of a list of moderated forums. Moderation is explained in moderation documentation in the user section. These types mean:

      Moderation Mode

      • System Default - the default configured for the entire site can be one of the following.

      • No Moderation - non of the content in the forum is moderated

      • Thread and Post Moderation - both threads and posts can be moderated; when a thread is moderated its posts are also moderated

      • Only Thread Moderation- only moderate threads, once a thread is approved, all posts within it are automatically accepted

      • Only Post Moderation - only moderate posts, any thread can be started; posts within the thread are moderated

  • Edit Forum - click on the edit icon Edit icon) on the right side of the row of the forum you want to edit to navigate to the category edit screen. The forums are children of the categories they belong to and can be differentiated because they have the icon to the left of their names while categories are on the left margin.

    Changes you can make to a forum

    • Change the category the forum belongs to by selecting another category from the list

    • Update the name and description of the forum

    • Update the sort order of the forum. This moves the forum's location within the list of forums in a category.

    • Enable a forum. By default all new forums are enabled, but you may want to temporarily disable a forum. Uncheck the box to disable the forum.

  • Group Permissions - The most common way to define access permissions to forums, group permissions define the authority groups of members have to various actions in the forums. To set group permissions to a forum, click on the icon under the Group Permissions field for the forum row. This opens the 'Assign Group to Forum <Forum Name>' form. See Assign Group to Forum for more on this.

  • Member Permissions - The most granular approach to defining access permissions to forums. Typically you would implement group permissions, except when assigning group moderators. To grant or revoke member permissions, click on the icon under the Member Permissions field for the forum row. This opens the 'Assign Member to Forum'. See Assign Member to Forum for more on this.

Assign Group to Forum

This form is used to assign groups to the forum, review the current group's permissions and current group's permissions. To assign group permissions to a forum, select a group from the list of available groups and click Choose Group button. From here you will access the Edit Forum-Specific Group Permissions form to add and remove forum permissions for the group. There are combined and individual permissions.

Assign Member to Forum

This form is used to assign members to a forum, review the current member's permissions and current user's permissions. To assign member permissions to a forum, enter either the member's name or memberid (unique numeric key) in the form and click the Choose Member button. From here you will access the Edit Forum-Specific Member Permissions form to add and remove forum permissions for the member. There are combined and individual permissions.

Groups

Access to forums is managed through a combination of group and user permissions. A group is a role definition that provides access to a collection of forum user and administration actions. Users are assigned to groups to provide them access to these actions. Rather than manage individual group permissions, it is easier to manage permissions for a group and then assign users to one or more groups.

Default Groups

mvnForum installs with 5 predefined groups that provide the following action access. For more information on specific permission definitions, see Combined Permissions and Individual Permissions

  • Guest - by default all users are guests. Guests can search and read forum threads. To gain further access to the forums, a guest must register and become a member.

  • Member - a member is a registered forum user. To become a member, a guest must create an account, provide a valid email address and activate their account. Members can create new discussion threads and edit their own threads.

  • Admin - administrators can manage all aspects of mvnForum, including managing the forum categories and forums, manage user accounts, and group permissions. At installation, mvnForum has a single account, admin, which belongs to the admin group.

  • Forum Admin - forum administrators can administer forums, including creating new forums. They cannot manage group or user accounts or permissions.

  • Forum Moderator - forum moderators are forum members that have the additional ability to monitor one or more forums. Forum moderation includes managing the posts submitted to that forum.

Group Management

The default groups installed with mvnForum are typically sufficient for most people to provide access rights and restrictions to the forum areas and actions. Some forum administrators may want to provide a more granular environment in which certain groups of people are limited to specific forums, forum moderators can only moderate certain forums (to provide both moderated and unmoderated forums), and certain users can only add or edit posts in certain forums.

The default group management screen shows the existing list of groups, the owner, member count and links to edit the group and delete the group for each group. You cannot delete the guest or member groups as they are required groups for the forum. From the group management screen, you can click the Add new group link or click any of the group name links to modify the groups.

  • Add new Group - if the list of default groups is insufficient, you can add your own group. You might want to add a group, such as ThisForumModerators that has forum moderator permissions on a select list of forums.

    Adding a new group

    • Group name - group names can be 250 characters long and must be unique within the entire mvnForum

    • Description - optionally provide a description for the group.

    • Group owner name - the name of the forum owner; must be the name of an existing mvnForum member. You can leave this blank if you have not yet created the member who will own this group and update it later. If you enter the name of a member incorrectly and the member name does not exist, the group owner will also be left blank.

  • Edit Global Group Permissions - Every group has global and forum-specific permissions. Global permissions apply to all the forums in the site. Setting global group permissions is the most encompassing way to set forum permissions as it applies to all groups, users and forums.

    Editing Global Group Permissions

  • Edit Forum-Specific Group Permissions - A group can be granted permissions to individual forums. To manage a group's forum access rights, select the group from the Group Management console and select the Edit Forum-Specific Group Permissions. Select the forum to add or remove rights from and click the Choose Forum button.

    Editing Forum-Specific Group Permissions

  • Change Group Option - not implemented yet - ??

  • Change Group Owner - To change a group owner, click this link and enter the new group owner's name. This must be a valid existing forum account id

  • Add Member to Group - To add a new forum member to a group, click this link, enter the list of new member ids and set their privileges. This is done for each group. To add new moderators, enter only the member ids of the people you want to be moderators; do the same for admins. Members added to a group that are not already registered with the forum are not added but no warning is issued.

  • List Members in this Group - Lists the members of a group, identifying whether they are the owner of the owner of the group, what their group privileges are and a link to remove each member from group.

  • Delete this Group - To delete an administrative group, click this button. mvnForum will ask for a confirmation before deleting the group. Note that deleting a group will not delete its members or delete any threads/posts the members have posted. Deleting a group will likely affect the permissions the members have as the permissions the group they belonged to will be lost.

Users

Users are forum members, either preregistered by forum managers or registered by visitors to the forum. User management involves adding, removing and editing users as well as managing user ranks. Additional, very useful features provided by mvnForum are the ability to see users and their permissions; send mail to all non-activated members; and remove stale, non-activated users from the forum database.

Default Users

mvnForum installs with 1 predefined user, the admin user. The admin user, installed with a password of the same name has access to all forum functions. The admin user can then create additional users and groups. The admin user can also grant permissions to users in the various forums. For more information on specific permission definitions, see Combined Permissions and Individual Permissions

  • Guest - by default all users are guests. Guests can search and read forum threads. To gain further access to the forums, a guest must register and become a member.

  • Member - a member is a registered forum user. To become a member, a guest must create an account, provide a valid email address and activate their account. Members can create new discussion threads and edit their own threads.

  • Admin - administrators can manage all aspects of mvnForum, including managing the forum categories and forums, manage user accounts, and group permissions. At installation, mvnForum has a single account, admin, which belongs to the admin group.

  • Forum Admin - forum administrators can administer forums, including creating new forums. They cannot manage group or user accounts or permissions.

  • Forum Moderator - forum moderators are forum members that have the additional ability to monitor one or more forums. Forum moderation includes managing the posts submitted to that forum. For more on moderation, see moderation documentation in the user section.

User Management

After successfully installing mvnForum, the first thing you will want to do is add at least 1 new user. For guidance on how to add users, change user permissions, and assign them to groups, read the following.

  • Add Group - if the list of default groups is insufficient, you can add your own group. You might want to add a group, such as ThisForumModerators that has forum moderator permissions on a select list of forums.

    Adding a new group

    • Group name - group names can be 250 characters long and must be unique within the entire mvnForum

    • Description - optionally provide a description for the group.

    • Group owner name - the name of the forum owner; must be the name of an existing mvnForum member. You can leave this blank if you have not yet created the member who will own this group and update it later. If you enter the name of a member incorrectly and the member name does not exist, the group owner will also be left blank.

  • Edit Global Group Permissions - if the list of default groups is insufficient, you can add your own group. You might want to add a group, such as ThisForumModerators that has forum moderator permissions on a select list of forums.

    Editing Global Group Permissions

  • Edit Forum-Specific Group Permissions - A user can be granted permissions to individual forums. To manage a group's forum access rights, select the group from the Group Management console and select the Edit Forum-Specific Group Permissions. Select the forum to add or remove rights from and click the Choose Forum button.

    Editing Forum-Specific Group Permissions

Rank Management

Ranks are a catchy way to categorize forum users based on the amount of their participation. Use the rank management to set the participation thresholds for how many forum posts a user must participate in to achieve a new ranking.

By default, mvnForum installs with 4 ranks, Stranger (less than 20 posts), Newbie (less than 50 posts), Member (less than 100 posts), and Advanced Member (more than 100 posts). You can edit these thresholds and add new ones.

  • Edit Rank - Change the minimum number of posts or the title of the ranking.

  • Add new Rank - Enter a minimum number of posts and the rank title to create a new ranking.

Permissions

With release candidate 2 (RC2), mvnForum introduced a very granular permissions system for granting access to and restricting access from all aspects of the forum environment. Permissions are granted to groups and users based on sets of restriction rules (combined permissions) and individual permissions for specific functions such as deleting forums and adding post threads.

By default, new accounts are not granted any permissions except for those permissions provided by the group they belong to. Permissions are determined by combining the most permissive permission restrictions of a user's group and their individual permissions. Therefore, a user who belongs to the forum moderator group that has permissions to moderate the forum called 'thisForum' but does not have individual permission to moderate that forum will have permission to moderate the forum because of their participation in the group.

In addition to the combination of the user and group permissions, mvnForum provides the ability to manage permissions for the entire forum site, global permissions, and for individual forums, forum permissions.

The following sections describe the two classes of permissions, combined permissions and individual permissions.

Combined Permissions

As the name implies, combined permissions are group logical sets of permissions into more easily managed categories. The following describes the permission combinations and the individual permissions they group. Depending on whether you are managing group global permissions, group forum permissions, user global permissions, or user forum permissions, the exact result of setting the permissions will differ.

  • Forum Admin

  • Forum Moderator

  • Limited User

  • Normal User

  • Power User

Individual Permissions

The individual permissions provide access restriction to nearly every action a user could take in mvnForum. To limit a user's ability to perform any of the actions listed, you must set both their user and group permission to No.

  • Edit Forum - edit forum name, description and owner

  • Delete Forum - delete the forum from the category

  • Read Post - read a post/thread within the site/forum

  • Add Thread - add a thread (first post) to any or specific forum

  • Add Post - add a post to a thread to any or specific forum

  • Edit Post - edit an existing post in any or a specific forum

  • Delete Post - delete a post in any or a specific forum

  • Add Poll - add a new poll

  • Edit Poll - edit an existing poll

  • Delete Poll - delete a poll

  • Add Attachment - add an attachment to a thread/post

  • Get Attachment - get/download an attachment from a thread

mvnForum documentation created using docbook.