Clearspace Administrators' Guide

This is a guide for administering Clearspace, a team collaboration application. This guide describes the kinds of things users can do with Clearspace and it provides information on how you can manage it.

Note: This guide assumes you've already installed Clearspace, so it does not describe installation procedures. Please refer to the Clearspace Installation Guide.

This guide is divided into the following sections:

Before You Get Started — Assumptions, recommendations, and tools.

Setting Up Clearspace — Overview of the setup tool.

Clearspace Basics — Background on Clearspace concepts and features.

Administrators' Reference — Brief descriptions of the admin console user interface.

Before You Get Started

Be sure to check out the README.html included at the root of the Clearspace distribution. That document includes basic instructions for getting started (from installing Java to starting your application server to running Clearspace), known issues, and a link to the license agreement.

For the most part, this guide assumes you've already installed Clearspace. That process includes:

1. Copying the Clearspace distribution to the server you'll be using. You'll find the distribution at the Jive Software web site (www.jivesoftware.com).
2. Deciding what database technology you'll be using with Clearspace. Data about users, content, and the means for organizing them is stored in a database that you specify while using the Clearspace setup tool. You should use a separate database for a production deployment, but the Clearspace distribution includes an embedded database you can use for evaluation purposes. See the Clearspace Installation Guide for more information.
3. Deciding what application server technology you'll be using. The standalone distribution of Clearspace includes an application server. If you use your own, be sure to see the instructions specific to setting up Clearspace on some of the most popular application servers in Clearspace Installation Guide.
4. Deploying Clearspace using the database and application server decisions you made in the preceding steps. This process is finished when you complete the setup tool that is displayed when you launch Clearspace for the first time. The setup tool is designed to be easy to use, but you'll find an overview of it in this guide under Setting Up Clearspace.

Get acquainted with Clearspace

Clearspace is designed to be simple to use, but offers a lot for users to do with it. You'll probably find that it's easier to administer your Clearspace installation if you're familiar with the concepts it's based on (such as content sharing and collaboration) and the technologies it incorporates (including wiki documents, blogs, discussions, and so on). The Clearspace Basics section of this guide introduces these concepts, suggesting administrative best practices and tasks along the way.

Administration Console

You can use the Clearspace Admin Console to manage system settings, permissions, content (documents, discussions, and blogs), and users. The Clearspace Basics section of this guide offers many tips along the way for modifying these settings, while the Administration Console Reference describes each of the console's pages, including what you can do there.

To view the console, make sure Clearspace is running, then go to a URL of the following form:

http://<hostname>:<portnumber>/<context>/admin

By default, using the built-in application server, this URL is: 

http://localhost:8080/clearspace/admin

Setting Up Clearspace

The first time you navigate to a page in the administration console, you'll be prompted to set up Clearspace using the setup tool. This tool assumes that you've either already set up a database for use with Clearspace, or that you're going to use the embedded database. This section briefly describes the setup tool.

Note: After you've completed the setup tool, you'll be prompted to start the administration console. Enter the user name and password you specified in the setup tool's Admin Account page.

The first page of the setup tool prompts you to specify the location of your jiveHome directory:

Note: The setup tool runs only once. If you need to re-run it, open the jiveHome/jive_startup.xml file, find the line  <setup>true</setup>, and change the true value to false. Restart your application server, point your browser at Clearspace using the URL above and rerun the setup tool.

Jive Home Settings — Confirm the location of the jiveHome directory (by default this is at the root of the distribution). The jiveHome directory contains configuration files, logs, data (for the embedded database) and other items that Clearspace needs to run correctly.

License Settings — Enter the license key you purchased (you can retrieve your purchased keys by logging into www.jivesoftware.com) or click continue to accept the evaluation license.

Database Settings — Specify how to connect to the Clearspace database. You can use the embedded database that is included with Clearspace or you can choose an external database. If you choose the standard database connection or JNDI datasource, you'll be prompted for required settings after you click Continue. See the Clearspace Installation Guide for information on supported databases and connection values to use.

Note: The embedded database isn't recommended for production use.

User System — Specify the system Clearspace should use for user and group data. For the Default option, the setup tool will use the user and group database tables from the Clearspace database. For the LDAP option, you'll be prompted to enter information for your LDAP server (such as host, base distinguished name (DN), and so on). For the Custom option, you'll be prompted to give the names of your implementations of interfaces from the Jive Software API (such as com.jivesoftware.base.UserManager) for user system access.

Other Settings — Specify defaults for RSS feeds and email sent via the server. Clearspace can send email when a account is created for a new user, for email notifications, and so on. Specify the "From" name and email address that should be used in these emails, as well as the SMTP host and port that should be used.

Clearspace can also be configured to receive email, such as when a user posts a discussion response via email. To get these emails, Clearspace needs a client account; specify those details here. 

Admin Account — Specify the system administrator's password. Be sure to change the admin email password from the default value, which is "admin".

Quick Links for Getting Started

After you install Clearspace, the Dashboard page will display links through which you can get started adding data about your community. For more information on these links, see the Dashboard Tab topic.

Clearspace Basics

Clearspace combines three Web 2.0 technologies (wiki, blogs, and discussion forums) into one easy-to-use solution for teams to create, store, and find relevant content, communicate within a community and collaborate on projects.

This section introduces you to what users can do with Clearspace by describing the concepts and technologies it supports. Throughout this section, you'll find administrative best practice suggestions and lists of associated administrative tasks. From an administrative perspective, what you do will help users make the most of Clearspace.

You'll find the following included in this section:

• Content — An overview of how Clearspace handles user content.
  • Documents — An introduction to collaborative (wiki) and uploaded documents
  • Blogs — About blogs, a frequent and chronological publication of idea, comments and thoughts.
  • Discussions — How Clearspace handles discussion threads.
• Users and Groups — Introduces user management, including permissions and authentication, moderation, user status, and collaboration.
• Profiles — Introduces user profiles.
• Tags — An overview of tags, a keywording mechanism through which users label and locate content.
• Spaces — About spaces, which provide structure to a community so that content is easier and more intuitive to find.

Content

Clearspace integrates documents, blogs, and discussions as distinct content formats that share editing features. Users create new content from the New menu, as shown here:

As users add content, the differences between a blog, a discussion, and a document become important as guides for choosing the best format. The following gives a brief overview of what characterizes each format.

Each of these formats has its own benefits and common uses. To make authoring them easier, Clearspace provides the following common features to ensure a consistent experience for the users:

• Common editing model. Each of these content formats shares features a resizable editor that supports rich text and plain text (for wiki-style markup) editing, as well as a content preview.
• Support for tagging. When editing content, users can apply tags that will help other users find the content. They can create new tags or choose from a list of tags already associated with the space.
• Support for comments. All three formats allow users to comment on the document's content.

The following illustrations show the toolbars for the rich text and plain text editing modes available for documents, blogs, and discussion posts.

As users incorporate Clearspace into their daily work, you might find that they benefit from basic guidelines on which content format to use for a given goal. Use the best practices guidelines in this document for suggestions.

Note: From a Clearspace perspective, profiles are content also in that they're searchable.

Documents

Best Practices | Tasks

Users can create new documents using the integrated wiki technology or they can attach documents that were authored with other tools, such as Microsoft Word or Adobe Acrobat.

A wiki document is ideal for collaborative authoring. With a wiki document multiple users can easily add, remove, and edit the document's content. This ease of interaction (along with the simple editor) makes the wiki document a great tool for collaborative authoring. (If you're unfamiliar with wikis, you'll find more information at Wikipedia - which is itself a very large wiki.)

The following illustration shows a new wiki document in the rich text editor.

Wiki documents tend not to be written in the first person, as a blog often is. Instead, they're often authored by multiple people with a shared purpose in mind. In addition, whereas blog or discussion posts are likely to be tied to particular point in time — a current question or issue — documents are usually not. Documents evolve with relative permanence.

Some good uses for wiki documents include:

• Collaborative documents (such as proposed product plans), which will have multiple authors.
• Longer-lived documents (such as a schedule of training classes), which provide a place to store information that is likely to be needed for a while.
• Documents to be reviewed (such as documentation), which will require that certain community members review and possibly approve it. Such documents are said to be associated with a workflow.

Clearspace also supports many document types as attachments. For example, a user can create a wiki document as a kind of container, then attach Word documents that should be reviewed by others in the community. The container provides a way to not only describe and expose the Word document, but also to ensure that specific members of the community see it.

Best Practices for Documents

• Educate users about the difference between collaborative (wiki-style) documents, blogs, and discussions.
• Encourage users to use wiki documents for quick or collaborative authoring of searchable content.
• Disallow undesirable content types for attached documents. For example, you might not want to allow certain media types.
• Add an approver who will be prompted to approve all documents in a given space. For example, some departments might want to be careful to ensure that sensitive information doesn't get inadvertently published.

Tasks Related to Documents

• Specify what document types should be allowed in your system. The complete list of document types supported by Clearspace is listed in the administration console. Use the Documents page for this task.
• Specify the directory where documents should be cached. Use the Caches page for this task.
• Edit or delete documents in a space. Use the Document Management page for this task.
• Specify users who should approve all documents authored in a space. Use the Document Settings page for this task.
• Set user permissions for creating, reading, and rating documents. Use the Global Permissions page for this task.
• Import a group of documents into Clearspace. Use the Import Documents page.

Blogs

Best Practices | Tasks

When they want to communicate with the rest of the community about what they're doing or thinking, people usually write a blog post. Similar to a newspaper or magazine column, a blog is a place for periodic posts of a (usually) first-person nature. A blog post is a new installment on the blog. Blog posts tend to be timely, meaning that they're often about the author's current thoughts, or something they've just discovered and want to share. For example, they can be about yesterday's visit to a potential customer

The following illustrates a blog post, along with a reply.

 
Blogs can have multiple authors. In a multi-user blog, multiple people post their own installments sequentially to the same blog. Note that this is different from a wiki document, in which multiple people make changes to shared document content.
You can also aggregate blogs so that blogs associated with multiple spaces are listed in the Blogs list of a single space (while also remaining visible from their parent spaces). Note that this is different from other content types, which aren't visible across spaces.

Note: See the Wikipedia definition of "blog".

Some good uses for blogs include:

• Status reports, which are typically written and updated by a single person.
• Capturing a user's opinion or point of view, similar to a newspaper column or first-person article.
• Capturing status, meeting notes, or news related to a project.
• Sharing information such as links to useful resources on the Web.

Best Practices for Blogs

• Among the tags applied, tag a blog post as personal or professional. This will help users focus on the information they care about most when searching.
• Consider aggregating blogs when blogs from disparate spaces would be useful to display in the Blogs list of a single space.

Tasks Related to Blogs

• Make global settings about blogs, blog comments, trackbacks, and so on. Use the Blog Settings page.
• Change global permissions for blogging. Use the Global Permissions page.
• Create or update a user blog. Use the Personal Blogs page.
• Create or update a space blog. Use the Group Blogs page.
• Aggregate blogs. Use the Blog Settings page.

Discussions

Best Practices | Tasks

Discussions provide a place for users to ask for responses from other community members. Unlike blogs and wikis, discussions tend to have short-term interest (such as when a question is asked and answered) and the initial post tends to be more an invitation than a declaration (as opposed to many blog posts).

The following illustrates a discussion post and a reply.

Some good uses for discussions include:

• An open dialog with other community members, such as for getting feedback on a new benefits program from the Human Resources department.

• A technical question, which is or when the answer would benefit other members of the community.

Best Practices for Discussions

• Encourage users to mark responses as "Helpful" or "Correct". This not only helps other users identify the content they need, but also identifies the responder as someone who might have useful answers.
• Convert discussions into documents in order to repurpose the content. You can save a discussion thread as a wiki document. This is useful when, for example, the thread has captured information that you might want to hang on to for later use.
• Encourage users to tag content.
• Try to moderate discussions lightly. Instead, make the guidelines for discussions available and easily discoverable, then only moderate when a post is out of line or off topic.

Tasks Related to Discussions

• Set the number of abuse reports after which a post is hidden. Use the Discussions page.
• Assign moderator permissions. Use the Admins & Moderators page.
• Enable users to receive an email alert when content in a discussion is added, moved, or removed. Use the Discussion Settings page.
• View a list of threads in a space, along with the number of replies, last modification date, and creating user for each. Use the Discussion Management page.
• Delete a discussion thread. Use the Discussion Management page.
• Set the number of helpful answers allowed for each discussion thread. Use the Discussion Settings page.
• Set whether a new discussion thread should be, by default, marked as a question. Use the Discussion Settings page.
• Enable/disable whether Clearspace should send email alerts. Use the Discussion Settings page.
• Set the amount of time after which an open question will generate an alert sent by email to specified addresses. Use the Discussion Settings page.
• Specify the addresses that should receive email alerts. Use the Discussion Settings page.
• Enable/disable whether discussion threads should be marked as read and specify the number of days after which that should occur. Use the Discussion Settings page.

Profiles

Best Practices | Tasks

In Clearspace, user profiles are like other content in that they can be found on searches. Because of this, information that users give about themselves - including interests and areas of expertise - can be a great source of information for users looking to have a question answered.

Best Practices for Profiles

• Encourage users to add information for their profiles. In particular, information about a user's skills or expertise will help other users identify the best sources of information in the community.

Tasks Related to Profiles

• Define the default format for user profiles. You can use the administration console to customize the fields that are included in user profiles. Use the Profiles page.

Tags

Best Practices | Tasks

Tagging is a way to apply keywords to content. As they do on the Web, users in Clearspace use tags to find content and make content easier to find. Users can apply tags to each of the content formats described in the Content section: documents, discussion posts, and blog posts.

For example, if a strategic planning team co-authors the organization's strategic plan, each contributor would add the tags that best describe the document. One person could associate the tags "strategic_plan" and "focus_areas". Another could associate the tags "strategic_plan", "goals", and "objectives". And a third could associate the tags "long_range_planning" and "company_goals". All terms would be added to the tag list, so any user could click any of the associated tags from either the complete tag list or Popular Tags list to display a list of content that would include the strategic plan document. Other information could also be listed for the selected tag, such as a status report from a team currently working on planning.

The following illustrates how users can add tags to content from a list of "popular tags" that Clearspace develops over time as tags are added. 

Through tags, data and content are collectively categorized by community members. This makes related content more discoverable via logical groupings other than the space/sub-space hierarchy.

Note: See the Wikipedia definition of "tag".

Clearspace makes using tags easier with the following conventions:

• Browsing by tags. Users can find content by viewing a list of the content associated with a particular tag. On the Tags page, users can filter a tag list by space/sub-space, documents, discussions, and blog posts, then click a tag to view a list of the content associated with it.
• Picking from popular tags. When applying tags, users can choose from a list of tags that are popular in the space. Clearspace builds this list from associations that users have already defined by applying tags. As Clearspace identifies popular tags users are applying, users discover what the majority of other users call something, and an "enterprise vocabulary" emerges.
• Grouping tags in tag sets. Users can find content associated any of multiple tags by using tag sets, which are named collections of tags. You can create tag sets using the administration console.
• Displaying tags in tag clouds. Tag clouds are lists of tags that are visually clustered to make finding relevant tags easier. To help users find what they're looking for, a tag cloud uses visual clues such as alphabetical order and font size (tags applied to more content are larger). Clearspace displays tag clouds on the home page for a space or sub-space, on the Tags page (where users browse for content by tags), and on the page displaying a blog post.

Along the way, as users apply tags across the content set, they create a kind of distributed index that is tailor made for the content in spaces.

Best Practices for Tags

Make the following best practice recommendations to the community's users:

• Encourage users to associate tags with content. This adds to the Clearspace search capability to making finding content even easier.
• Encourage users to use existing tags where possible. The Popular Tags list at the bottom of the document editing page lists these for the sub-space in which the document has been created. Users can click tags in the list to add them to the Tags box, where they'll be associated with the content.
• Create tag sets to capture keyword categories. You can also encourage users to suggest tag sets that make sense for them.

Tasks Related to Tags

• Manage tag sets. You can create, edit, and remove tag sets. Use the Tag Set Management Page for this task.
• Edit the cache size for tags. Use the Caches page.

Spaces

Best Practices | Tasks

When you set up spaces, you provide a structure for users to keep content organized. A space is an organizational container for documents, discussions, polls, tags, and announcements. One of the first things you'll likely do when setting up Clearspace is create spaces and sub-spaces in hierarchies that reflect your company's functional areas or interests.

The following shows the Browse menu, from which users can view tags, users, blogs, and the space hierarchy.

 
You'll likely find that you're defining spaces and their sub-spaces in keeping with the areas that users interact in outside of Clearspace. For example, at a high level, spaces could reflect organizational divisions. Sub-spaces are likely to reflect organizational subdivisions, but they could also mirror areas of interest or other more informal boundaries. For example, you might create a top-level Sales space to reflect the sales department, then create sub-spaces such as Channel Sales, Business Development, and Direct Sales. Other criteria by which to define sub-spaces include functional area, project, and topic.

As you define spaces, keep in mind the following: 

• Each space and sub-space can have different sets of permissions, so you can control access and capabilities within a space. You can also expose portions of the space to external partners using Clearspace's powerful and secure permissions system.

Best Practices for Spaces

• When defining spaces and sub-spaces, be sure to that the divisions and hierarchy are intuitive to your users. You might start by looking at how users and teams are organized within your user community. You could also create a suggested space/sub-space hierarchy and get user feedback on it.
• Create a general, high-level hierarchy to start at first. Once your users are involved, they'll refine the categorization using tags. As a general rule, the more spaces and sub-spaces there are, the more information will get siloed and the power of tagging and Tag Groups will not have a chance to display itself.
• Define spaces with the role of tags in mind. Spaces organize content, but over time tags will grow to constitute virtual groups to organize content also. As users apply tags to content, for example, a tag such as "personal" might come to mean "a blog or wiki that isn't connected with the company's business." In other words, this is probably a better way to categorize "personal" posts than a Personal sub-space would be.
• Note that content can't be shared and tagged between discrete spaces --- only within the space in which it's created. Use a Community to group multiple concepts or functional areas; use a tag group to group together discrete concepts within a Community.

Tasks Related to Spaces

• Create spaces and sub-spaces. Use the Management tab for spaces.
• Merge spaces. Use the Merge Spaces page.
• Set admin or moderator permissions for a space or sub-space. Use the Admins & Moderators Page.

Notifications and RSS Feeds

Tasks

Clearspace users can choose to receive email notifications or RSS to stay up to date on changes to content they care about. Each space lists the available RSS feeds.

• With email notifications, the Clearspace system sends an email to the user when a change has been made to the content they've signaled an interest in.
• With RSS feeds, users can receive the change notification by using their favorite RSS feed aggregator. Modern web browsers, such as Internet Explorer 7 and Firefox 2.0, include an RSS aggregation feature.

RSS feeds that allow users to determine what content they receive based on their needs and interests, along with how they receive it --- in their personalized browser page or within the company's main intranet or Web page.

The option to receive email notifications and RSS feeds is available for:

• Spaces and sub-spaces.
• Documents, discussions, and blogs.
• Tags.
• Announcement, polls.

Tasks Related to Notifications and RSS Feeds

• Delete a user's email notifications. Use the User Summary page.
• Edit the template on which notification emails are based. Use the Email Templates page.

Users and Groups

Tasks

Administrative tasks related to users and groups are probably among the most important you'll perform. From managing the membership of user groups to setting who has access to which Clearspace actions to promoting community participation, there are numerous administrative areas that revolve around users. This section describes the kinds of things you can do with related to users.

In this section you'll find:

User Authentication Systems

Permissions

Content Moderation

Status Levels

Workflow and Collaboration

User Authentication Systems

If you have an existing user authentication system and/or an LDAP Directory, integrate these systems with your Clearspace application to offer members log-in convenience and save administrative time managing user permissions.

Single Sign-on (SSO) Integration. Many web sites require visitors to authenticate themselves before they can access site content. By integrating with a Single Sign-on (SSO) system, users log in one time to authenticate and access web site content and the online community. We make the integration process simple, using the Auth Token and Auth Factory libraries.

LDAP/Active Directory Integration. Avoid manual entry of user and permissions data by integrating your existing LDAP user database with your online community membership database. Refer to our Administrator's Guide for more information.

Tasks Related to Users and Groups

• Search for user or group summaries. Use the User Search page.
• Add or remove users and groups. Use links on the Management tab for People.
• Edit settings for a user or group. Use links on the Management tab for People.
• View a user's activity in Clearspace, such as their blog and discussion posts. Use the User Summary page.
• Update the list of default avatars available to users. Use the Avatar Settings page.
• Set the fields to display in user profiles. Use the Profile Configuration page.
• Enable or disable user password resets. Use the Password Reset page.
• Edit settings for user registration, such as emails to welcome new users, the URL at which terms and conditions are described, and so on. Use theRegistration Settings page.

Permissions

Best Practices | Tasks

You specify permissions in the context of managing spaces and sub-spaces. Permissions are scoped to the level of the root space (where global permissions are set) or sub-spaces. Sub-spaces inherit permissions from their parent space, but inherited permissions can be augmented or revoked at the sub-space level.

You might give a user permission to read documents globally, but permission to author new documents only in a particular sub-space (perhaps a sub-space corresponding to the department they work in). For example, in a Marketing Department space all users might have space permissions that allow them to view and post content in the general community, but only those Product Managers with the appropriate permissions may be able to author and approve content, such as brochures and pricing information, that can be accessed by the sales organization.

Clearspace checks permissions when a user accesses content, as follows:

1. The application examines the global user permissions — the permissions the user has within the entire Clearspace instance.
2. The application looks at Group permissions for groups the user belongs to.
3. The application applies content permissions at the following levels:
   • Space --- Permissions for all users when they log into the space and access space content. Add these permissions to users or groups at the space level.
   • Sub-space — Permissions for users in a sub-space. Clearspace checks the user's sub-space permissions to see if they have been modified from the original space-level permissions. If so, when the user accesses content in that space or related sub-spaces, the sub-space permissions override the space permissions. Otherwise, space permissions are inherited by sub-spaces beneath the space.

Understanding User Types

Clearspace ships with two default user types that cannot be deleted: Anyone and Registered Users. Once a user registers, they can be assigned permissions as a User or as part of a Group. This results in four categories of Clearspace users who can receive global permissions: Anyone, Registered, User, and Group.

• An Anyone user is simply anyone who visits the online community. This user type is designed to be associated with a guest or to allow anonymous access. Anyone permissions are a blanket set of permissions for anyone who visits. Think hard about what you want people to be able to do anonymously, but weigh that against the need to engage people to encourage them to participate. (Note that users who merely view content are not counted among the number of users your license provides for.)
• A Registered User is someone who has entered your online community's required registration information. Registered Users permissions are globally assigned permissions you give to anyone who registers. Participants must be registered in order to participate in threaded discussions.
  
  Among registered users, Clearspace provides a way for you to assign permissions according to the following two categories:
  • A User is a registered individual.
  • A Group is a group of registered individuals.

The Spaces > Permissions > Global Permissions page provides the Grant New Permissions tab, where you can grant or revoke permissions for specified users and groups, as shown here:

Best Practices for Permissions

• Rather than assigning permissions on a user by user basis, create user groups and assign permissions to the groups. This will make managing permissions easier.
• Define the user groups you'll need before launching the space. For example, group users according to employee job function or department. User and Group permissions can be assigned on a space or sub-space basis.
• Before adding users (and spaces) to the system, it might be useful to collect information about roles for those users who will have special permissions - such as blog authors, moderators, and so on. As you create spaces and sub-spaces using the admin console, you'll be prompted for this information.

Tasks Related to Permissions

• Set permissions for administrators and moderators. Use the Admins & Moderators Page.
• Set permissions for users or groups to create and interact with content. A list of permissions is displayed in the illustration above. Use the Space Permissions Page or Global Permissions Page (Spaces).

Content Moderation

Best Practices | Tasks

While moderation is typically less of a concern for internal use, Clearspace includes comprehensive auto-moderation features you can use to ward off user abuse or improper posts. This section describes those features and offers some recommendations.

Develop Your Usage Policy. Design a usage policy to ward off abuse or inadvertent posts that are not appropriate for the community. Early warning can make a big difference, and can prevent your members from having a negative experience. Make the consequences for unacceptable behavior clear. Some ideas for possible policy statements to include are:

• No profanity.
• Treat others with respect.
• Stay on topic.

Use filters and interceptors. A filter dynamically formats message content before it posts to the space. In contrast, an interceptor uses specific criteria to accept, modify, or reject an entire incoming message before it enters the space. Filters and interceptors can be applied to discussions, document comments, and blog comments. Because you can't apply interceptors to documents (and to a blog post only when it's first created), make sure you're comfortable with the employees you allow to author those types of content when setting permissions. When you don't want any part of a post or comment with an offending word to enter the space before an action is taken, use an interceptor instead of a filter.

Apply a profanity filter. This filter automatically detects words in the profanity list and replaces them with ***. Use the list of common profanity terms from the Jive site as a starting point, then conduct a team-building exercise to augment this list. The profanity filter is the most commonly used filter; please consider using it.

Encourage employees to report abuse. The Clearspace Report Abuse feature gives your users the ability to help police the community by allowing them to report an offensive post to the moderator. A reported post can automatically be taken out of the thread when the number of users that report the post exceeds an administrator-specified number. The post is put into a moderation queue, and must receive moderator approval before it can be placed back into the thread.

Best Practices for Moderation

• Create usage guidelines and make them well-known to users.
• Enforce usage guidelines quickly and publicly. Other community members are more likely to follow the guidelines if you confirm that they will be enforced.

Tasks Related to Moderation

• Edit settings for banning specific users and IP addresses. Use the Ban Settings Page.
• Turn filters on or off. Use the Filters and Macros Page.
• Install interceptors. Use the Interceptors Page.
• Enable or disable abuse reporting. Use the Discussions Page.

Status Levels

Best Practices | Tasks

To help encourage users to participate in discussions, Clearspace provides a way for users to accrue status level points based on their activity. Having users who contribute valuable (or even entertaining) information in spaces, or on whom other users can rely for expert opinions and support, helps to build Clearspace's usefulness as a tool; the more users participate, the more information that is available for the community as a whole.

Where a user's name is displayed, Clearspace displays a status icon such as corresponding to to the number of points the user has accrued. By default, for example, Clearspace includes the following status levels: master (501-1000 points); junior (101-500 points); newbie (0-100 points). You can configure the levels, along with how many points correspond to an action and what image should be used for the status icon.

You can assign point values to the following user actions:

• Discussion activity, such as posting, responding, providing helpful and correct answers to questions.
• Creating wiki documents.
• Posting to a blog.

Best Practices for Status Levels

• Offer rewards or recognition for users who reach or maintain certain status levels.

Tasks Related to Status Levels

• Configure aspects of user status levels, including the status icon to use, the range of values for the levels, and the number of points to assign for each user action. Use the Status Level Settings page.

Workflow and Collaboration

Some documents will require the collaboration of a particular set of users. For example, a planning document might benefit from the authorship and approval of department members.

For cases such as these, Clearspace users can:

• Create a list of collaborators.
• Assign specific permissions for each user in the list.

• Specify that document editing is "closed," meaning that it is editable only by designated users in the collaborators list.
• Specify that document commenting is "closed," meaning that new comments will not be allowed.

The following illustrates adding users as collaborators on a wiki document. For this document, Gladys is the creator and must also approve the document before it can be published for visibility to the community as a whole. Raoul and Betty are set to be authors, meaning that they can make changes to the document's content, but their approval isn't necessary for publishing.

Administrators' Reference

This portion of the guide describes the admin console user interface.

Administration Console Reference

Dashboard Tab

Use this tab to view recent activity in your Clearspace instance. You might also find the Quick Links at the top of the page handy --- they're shortcuts to the following places in the admin console:

System Tab

Management Tab (System)

System Information Page

Console Location: System > Management > System Information

Displays information about the configuration of the system on which Clearspace is deployed.

License Information Page

Console Location: System > Management > License Information

Displays the amount of the license's capacity is currently being used and expiration status. This page also provides a way to upgrade the license.

System Properties Page

Console Location: System > Management > System Properties

Use this page to view and set system properties. Values for password-sensitive fields are hidden. Long property names and values have extra spaces in them to make sure they wrap correctly. To see the full value, click the edit icon then look at the Property Value field.

Log Viewer Page

Console Location: System > Management > Log Viewer

Use this page to view messages logged by the Clearspace instance. You can filter messages by severity, mark a place in the log, and get or send a copy of the list.

Query Stats Page

Console Location: System > Management > Query Stats

Use this page to enable query statistics to trace all database queries made by the system. This can be useful to debug issues and monitor database performance. Keep in mind, however, that leaving query statistics permanently running will cause performance to degrade slightly.

Scheduled Tasks Page

Console Location: System > Management > Scheduled Tasks

Use this page to view and add tasks that should be executed at times you specify.

In the Class Name box, enter the fully-qualified name of the Java class that implements the task to run. Note that this class must be on the Clearspace classpath. In the Schedule box, enter the time (in Unix cron format) to execute the task. 

Settings Tab (System)

Attachments Page

Console Location: System > Settings > Attachments

Edit attachment policies using the forms below. The enabling/disabling of attachments is permission based. To completely turn off attachments, remove all attachment permissions.

Caches Page

Console Location: System > Settings > Caches

Clearspace relies on its cache to process data efficiently. To keep performance high, it caches data so that pages can be rendered quickly without directly querying the database. Use this panel to:

• Monitor and modify cache settings for each of the categories of cached data that Clearspace uses.
• Use cache tools to warm up the caches, loading them with often-used data.
• Enable/disable short-term query caching, in which cache expirations occur more than once every 5 or 10 seconds.

Discussions Page

Console Location: System > Settings > Discussions

Manage discussion, moderation and abuse settings. Fields marked with an asterisk use a special template language to build dynamic content. For example, you can reference the message object by using the variable.

Documents Page (System)

Console Location: System > Settings > Documents

Lists the settings for system-wide document handling. On this page, you can:

• View the document cache location path.
• Enable or disable document sharing.
• Allow or disallow certain content types for uploading into Clearspace.
• Add support for allowing content types not already listed.

Documents can be disabled and various content types can be disabled.

Email Server Page

Console Location: System > Settings > Email Server

These settings control how email is sent and retrieved. The SMTP tab is for configuring outgoing email, and the Email Monitoring tab is for configuring incoming email.

Email Templates Page

Console Location: System > Settings > Email Templates

Lists the templates that are used for emails automatically sent by the Clearspace system. Click the icon to view and edit template details. Click Add Template to add an additional locale.

Plugins Page

Console Location: System > Settings > Plugins

Use this page to install, restart, disable, or delete plugins.

Search Page

Console Location: System > Settings > Search

Manage search settings using the forms below.

Spell Check Page

Console Location: System > Settings > Spell Check

Use this page to specify the dictionary to use for spell check, and to edit the custom dictionary by adding or removing words. 

Themes Page

Console Location: System > Settings > Themes

Use this page to view, create and delete themes. Themes are installed in the jiveHome/themes directory. The global theme will be used throughout the application as the "base" theme.

Virus Scanner Page

Console Location: System > Settings > Virus Scanner

Use this page to make settings about the virus scanner, including:

• Whether it should be enabled.
• Its URI.
• Email addresses to send notification to.

If the scanned attachment has a virus that can be cleaned, the original attachment is deleted and replaced with a cleaned attachment. If the attachment must be blocked due to an infection, the original attachment is deleted and replaced with a text message. Email notifications are optionally sent if there was a blocked infection.

Web Services

Console Location: System > Settings > Web Services

Use this page to make settings for web services, which provide the ability for external applications to connect to this instance of Clearspace. Note that all users connecting via web services will be also be restricted to the same access rights that they would have accessing and modifying content through the normal web application.

Spaces Tab

Management Tab (Spaces)

Use this page to add and edit sub-spaces to the space selected beneath the Space Summary title.

Document Management Page

Console Location: Spaces > Management > Document Management

Lists the documents contained in the specified space.

Discussion Management Page

Console Location: Spaces > Management > Discussion Management

This page displays discussion threads for the space whose name is displayed under Discussion Management. Click the edit icon to edit the discussion. 

Tag Set Management Page

Console Location: Spaces > Management > Tag Set Management

Tag Sets are a way to organize community content by arranging tags into groups. For example, if you have the tags "display", "19inch", and "21inch", you may want to group these together into a set called "Display". Users will be able to navigate these sets to find their desired content quickly. To create a new tag set, click on the "Create New Tag Set" link.

Merge Spaces Page

Console Location: Spaces > Management > Merge Spaces

This panel allows you to merge the content of one space into another.

Import Documents Page

Console Location: Spaces > Management > Import Documents

Use this form to import all files in a directory as uploaded documents.

Settings Tab (Spaces)

Console Location: Spaces > Management > Settings Tab

Space Settings Page

Console Location: Spaces > Settings > Space Settings

Select check boxes for the types of content that will be allowed in the space.

Note: Creating a new space or sub-space begins on the Management. See the Management Tab (Spaces) topic for information on creating new spaces.

Space Creation Wizard

To reach this wizard, click Spaces > (Space Summary Page) > Create New Sub-Space (button)

Use this wizard to add sub-spaces. The wizard's steps prompt you for space basics (such as space name), level of privacy, types of content allowed, and so on. 

Blog Settings Page (Spaces)

Console Location: Spaces > Settings > Blog Settings

Use this page to aggregate blogs into the space whose name is displayed under Blog Settings. You can aggregate blogs from other spaces into the selected space. That way, the aggregated blogs will be visible from the selected space.  

Discussion Settings Page

Console Location: Spaces > Settings > Discussion Settings

Moderation allows administrators and moderators to screen threads and messages before they are viewable in your community. When moderation is turned on, you must approve or reject each thread or reply. You can see a list of pending messages by clicking on the "Moderation" link to the left.

Question feature settings allow you to set the number of helpful answers per thread and to configure the default question status for threads.

Document Settings Page

Console Location: Spaces > Settings > Document Settings

Lists the users who will approve all documents in this space before they are published. Click the Add Approver button to add approvers to the list. Click the Delete to delete them.

Community Everywhere Page

Console Location: Spaces > Settings > Community Everywhere

Use this page to enable and make settings for the community everywhere feature. With community everywhere, you can display Clearspace discussion thread content in web pages that are external to Clearspace. Users viewing the external page can create discussions and post replies that are added to the discussion in Clearspace. With community everywhere enabled, paste the script in the Code window into the web page that should support creating and/or displaying discussion threads.

To ensure that pages at certain URLs only can host community everywhere script, enter their URL in the Restrict Referrers To box; this can be a comma-separate list of URLs. In the System User box, enter the name of the "user" who will be shown as having begun the discussion.

Click Generate New Key to generate a unique identifier that will be associated with the discussion created from the external page. This unique ID is inserted into the script in the Code box.

Thread Archive Settings Page

Console Location: Spaces > Settings > Thread Archive Settings

Specify whether to archive discussion threads. 

Extended Properties Page

Console Location: Spaces > Settings > Extended Properties

Communities can have an arbitrary number of extended properties which facilitates additional functionality to what the core API provides.

Filters and Macros Page

Console Location: Spaces > Settings > Filters and Macros

Filters and macros both dynamically reformat the contents of messages, announcements and polls. Filters can be applied globally or on a per community or per forum basis. They are similar concepts but filters can apply to the entire block of text and macros operate on a specific part (for example, {macro}will alter text in here{macro}).

Below is a list of all filters and macros in the system. You can enable or disable each filter and macro and edit its settings.

Gateway Settings Page

Console Location: Spaces > Settings > Gateway Settings

Gateways allow you to synchronize threads in your community with an external data source. For example, use the email gateway to mirror the content of a mailing list.

Interceptors Page

Console Location: Spaces > Settings > Interceptors

Interceptors examine messages before they enter the system and can modify or reject them. Use the forms below to install and customize local interceptors.

Permissions Tab (Spaces)

If you don't have a sub-space selected (as when the root space is selected), the Permissions tab will provide a way to view and edit global permissions. To set admins, moderator, and other permissions for a sub-space, select the space before displaying the Permissions tab. To select a sub-space, click the Spaces tab (so that the Space Summary page is displayed), then click the name of the sub-space you want to edit permissions for, then click the Permissions tab.

Admins & Moderators Page

Console Location: Spaces > Permissions > Admins & Moderators

Displays the admin and moderator permissions assigned to Clearspace users. You can edit permissions.

This page will display global permissions if you haven't selected the root space, and space permissions if you have selected a sub-space. To select s sub-space, click the Spaces tab (so that the Space Summary page is displayed), then click the name of the sub-space you want to set permissions for, then click the Permissions tab.

Global Permissions Page (Spaces)

Console Location: Spaces > Permissions > Global Permissions

Displays the global (root space) permissions assigned to users and groups and provides a place to grant new permissions.

This page is only available when you have selected the root space. In other words, to view this page, click the Spaces tab (so that the Space Summary page is displayed), click the Permissions tab, then click Global Permissions.

To apply specific permissions for a user or group not listed here, click the Grant New Permission tab, then select the permissions to grant or revoke and specify the user or group to apply them for.

Space Permissions Page

Console Location: Spaces > Permissions > Space Permissions

Displays the sub-space permissions assigned to users and groups and provides a place to grant new permissions.

This page is only available when you have selected a sub-space below the root space level. In other words, to view this page, click the Spaces tab (so that the Space Summary page is displayed), click the name of the sub-space you want to set permissions for, click the Permissions tab, then click Space Permissions.

To apply specific permissions for a user or group not listed here, click the Grant New Permission tab, then select the permissions to grant or revoke and specify the user or group to apply them for.

Blogs Tab

Management Tab (Blogs)

Personal Blogs Page

Console Location: Blogs > Management > Personal Blogs

Create, edit and delete personal blogs.

Group Blogs Page

Console Location: Blogs > Management > Group Blogs

Create, edit and delete group blogs.

Settings Tab (Blogs)

Blog Settings Page (Blogs)

Console Location: Blogs > Settings > Blog Settings

Manage global blog settings.

Permissions Tab (Blogs)

Global Permissions Page (Blogs)

Console Location: Blogs > Settings > Global Permissions

Grant permission to read and create blogs to groups and individuals.

People Tab

Management Tab (People)

User Summary Page

Console Location: People > Management > User Summary

Use this page to edit settings about user accounts. Click the edit icon to:

• Change the user's password.
• View or delete documents they've authored.
• View or delete their discussion posts or blog posts.
• Change their email notifications.
• View and add system properties about the user.
• Delete the user.

Create Summary Page

Console Location: People > Management > Create User

Create a user here. After you click Create User, the admin console will display a page through which you can edit user properties such as password, email, name and email visibility, and so on. 

Group Summary Page

Console Location: People > Management > Group Summary

View and edit user groups. Click the Edit icon to display a page through which you can edit group properties, such as admin and member list.  

Create Group Page

Console Location: People > Management > Create Group

Create a user group here. After you click Create Group, the admin console will display a page through which you can edit the group admin and member list.

User Search Page

Console Location: People > Management > User Search

Search for a user as a way to easily reach their User Summary page. The IDs for users matching your search term will be displayed in a list from which you can select the user you want.

Settings Tab (People)

Avatar Settings Page

Console Location: People > Settings > Avatar Settings

Use this page to specify how to handle avatars (images representing users).

Ban Settings Page

Console Location: People > Settings > Ban Settings

User Accounts and IP Addresses can be banned using the form below. The different ban levels are Disable Login, Disable Post, Moderate Post. Disable Login will prevent the banned user from logging into their account. Disable Post will prevent the banned user from posting any messages. Moderate Post will mark all messages posted by the banned user for moderation.

Password Reset Page

Console Location: People > Settings > Password Reset

Use this page to make it possible for users to request that their password be reset if they forget it. If enabled, they'll receive an email with a link through which they can reset the password. Use the Email Templates page link to specify a template for the email they receive.

Profile Configuration Page

Console Location: People > Settings > Profile Configuration

Profile fields are the basic building blocks of a users profile. Below are all the profile fields defined in the system. To create a new profile field, click New Field.

Registration Settings Page

Console Location: People > Settings > Registration Settings

Manage the registration experience, such as whether users must type characters from a random image in order to register (human input validation), whether the user will be required to accept terms and conditions, and so on. From here you can also reach console pages where you can set templates for email messages sent in connection with registration.

Status Level Settings Page

Console Location: People > Settings > Status Level Settings

A status level indicates a range of scores for a user. For example, you can designate users with scores of 0-10 be ranked as "Beginners" and users with scores of 400-500 be "Golds". Scores are calculated on users according to a specific algorithm.

Different scenarios can be selected an manipulated for awarding points to users.

Reporting

Reports

Main Page

Console Location: Reporting > Reports > Main

Use the new forum threads, new blog posts and new wiki documents reports to get a sense how 'active' the entire community is.  Each graph represents data from the last seven days.

Use the tag clouds to watch developing trends in the system. An sudden increase in the use of a specific tag may indicate the need for a new community or topic.

The activity tables should be used to gauge hotspots in the system: areas where users are having frequent discussions.

Threads Page

Console Location: Reporting > Reports > Threads

Use the threads graph to monitor the number of threads created over time. A small number of threads created may indicate that users are not aware of the ability to ask questions via the forum or that they are utilizing other methods such as email or instant messaging for group discussion.

Messages Page

Console Location: Reporting > Reports > Messages

Use the messages graph to monitor the number of messages created over time. A small number of messages created may indicate that users are not aware of the ability to ask questions via the forum or that they are utilizing other methods such as email or instant messaging for group discussion.

Blog Posts Page

Console Location: Reporting > Reports > Blog Posts

Use the blog posts graph to monitor the number of blog posts created over time.

Blog Comments Page

Console Location: Reporting > Reports > Blog Comments

Use the blog comments graph to monitor the number of blog comments created over time.

Documents Page (Reporting)

Console Location: Reporting > Reports > Documents

Use the documents graph to monitor the number of documents created over time.

Console Location: Reporting > Reports > Console Location

Document Edits Page

Console Location: Reporting > Reports > Document Edits

Use the document edits graph to monitor the number of document revisions created over time.

Document Comments Page

Console Location: Reporting > Reports > Document Comments

Use the document comments graph to monitor the number of document comments created over time.

Real-Time Tab

Settings Tab (Real-Time)

Overview Page

Console Location: Real-Time > Settings > Overview

This page provides an overview of real-time integration and indicates whether Clearspace is connected for real-time integration. Use the Connection and Presence pages to set up the connection.

With real-time integration and with XMPP presence enabled, the Clearspace user interface will display presence information for Clearspace users — such as whether they're "online" or "away" from an instant message perspective. The user interface will display a link through which a user can easily send an instant message to another user.

Connection Page

Console Location: Real-Time > Settings > Connection

To enable real-time collaboration, enter your Wildfire server name and external component port.

Note that to enable integration with your Wildfire server, you need the Wildfire plugin. You can get the plugin using the Wildfire server admin console or by going to the Wildfire Plugins page at igniterealtime.com.

For enhanced security, you must enter a secret key to connect Clearspace to the Wildfire server. The secret key is stored on the Wildfire server and can be accessed in the Wildfire admin console. In that console, choose the Server tab, and then the External Components page in the Server Settings section.

Presence Page

Console Location: Real-Time > Settings > Presence

Use this page to enable XMPP presence, a feature through which Clearspace users can view presence information about other users (such as whether they're "available" from an instant messaging perspective).

Select the Enable XMPP Presence check box to enable presence cues in the Clearspace user interface.

Select the Use Common Username For XMPP Presence check box to tell Clearspace that it can assume that user names on the Clearspace server can be used to construct user names for communication with the real-time server. In other words, with this box selected, Clearspace will assume that MyCompany user "sam" on Clearspace is "sam@mycompany.com" on the real-time server. This is useful if you're using a common server, such as a single LDAP server, for resolving user names for both real-time and Clearspace.