If you're a system administrator, use this guide to set up and configure Clearspace using the admin console. This guide includes information about console features that are only available to system administrators.

Some Clearspace administration features are covered in more detail in other documentation, while others are available to space administrators and user/group administrators as well as to system administrators. For information on those features, look to the following:

Document	System Admin	Space Admin	User/Group Admin
Managing Spaces
Managing Permissions
Managing Users and Groups
LDAP and Active Directory Guide
Fine-Tuning Clearspace Performance
Clearspace Clustering Information
Clearspace Theming Guide
Clearspace Upgrade and Migration Guide
Using Community Everywhere
Localizing Clearspace
Recommended Environments for Clearspace Deployments

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

Fine-Tuning Clearspace Performance— Once you get Clearspace up and running, you'll need this to get the best performance from the start. This guide is included with the Clearspace documentation.

Before You Get Started

Be sure to check out the README.html included with the documentation. There you'll find 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. If you're looking for information on installing, see the Clearspace Installation Guide.

Administration Console

You can use the Clearspace Admin Console to manage system settings, permissions, content (documents, discussions, and blogs), and people. This guide describes those things that only a system administrator can do in the admin console.

You can start the admin console from the command line. If you used the installer program to install Clearspace, you can also display the console by using the Clearspace service manager (the installer installs Clearspace as a Windows service).

• To view the console from the command line, 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

• To view the console from the service manager, click the Clearspace icon in the Start menu, desktop, or task bar, then Launch 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 evaluation database. This section briefly describes the setup tool.

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— The first page of the setup tool prompts you to specify the location of your jiveHome directory. 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 evaluation 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 evaluation 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. Here's an example of a standard connection configuration:

See the Clearspace Installation Guide for information on supported databases and connection values to use.

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

User Settings— 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). Be sure to see Clearspace LDAP and Active Directory Guide for details on setting up an LDAP or Active Directory connection.

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.

Jive Service Cloud— Choose whether to enable your Clearspace instance's connection with the Jive service cloud. In this version, cloud features include document sharing. In the Service Name box, simply enter the name you would like to have represent your Clearspace instance in the cloud. This is the name that people using the cloud will see (note that people using the cloud might have access to content from Clearspace instances other than yours). One choice might be the name your instance's root space will use.

Usage Statistics— Choose whether to allow Clearspace to send usage statistics back to Jive Software. For more information see Sending Usage Statistics.

Other Settings— Specify defaults for RSS feeds and email sent and received by Clearspace. 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. 

You'll be able to change these settings later via the admin console.

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

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.

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.

Getting Basic System Information

You can get basic, system-wide information about the deployment context for Clearspace from the admin console. Use this information when requesting support.

Root Space

You can change the name and description for the root space.

Admin Console: System > Settings > Space

Deployment Environment

You'll find information about the environment into which Clearspace is deployed in the admin console. This information includes the Java environment (JVM version and Java system properties), operating system, uptime, and user, group, and authorization managers in use. It also includes information about the data source.

Admin Console: System > Management > System Information

Deployment License

The admin console lists the license type, capacity, current usage (how many of your allowed capacity is being used), number of cluster members, and license creation and expiration dates.

Admin Console: System > Management > License Information

Locale

You can use the admin console to set the locale, time zone, and character set for the Clearspace instance.

Admin Console: System > Management > Locale

Getting Data Into Clearspace

With a fresh Clearspace instance, you can import data from another Jive Software application or migrate data from a database that's serving another Clearspace instance. Note that you can only import or migrate to an empty Clearspace database.

Importing from another Jive Software Application. If you have data from another Jive Software application -- including Integrated, Knowledge Base, or Forums -- you can import that data into Clearspace.

Note: Clearspace version 2.0 doesn't support importing directly from another Jive application. You should first import into a 1.x version of Clearspace (preferably the latest), then the new Clearspace instance to version 2.

If you're considering migrating, be sure to read Migrating from Other Jive Products in the Clearspace Upgrade and Migration Guide.

Admin Console: System > Import/Export > Import Content

Migrating from another database technology. Clearspace provides a migration tool through which you can copy data from one database management system (DBMS) to another. The destination system you're copying into must be empty before you use the tool or migration will fail.

If you're considering migrating, be sure to read Migrating from One DBMS to Another in the Clearspace Upgrade and Migration Guide.

Admin Console: System > Import/Export > Database Migration

Connecting to User Authentication Systems

Clearspace includes a database for storing data about people and groups you add. But you can use another system instead, including LDAP, Active Directory, or a custom system. You choose a user data system when you're setting up Clearspace with its setup tool; you can't specify or configure a system in the admin console.

You'll find a full guide for connecting to a user data system in the Clearspace LDAP and Active Directory Guide.

For information on viewing user and group account information, be sure to see Managing Users and Groups.

You can also set up Clearspace to synchronize data between the Clearspace database and your external user database. On the User Data Synchronization Settings page, you can enable synchronization and set how synchronization is done. This feature helps you ensure that the local Clearspace database only contains data related to users who are in your external (LDAP or Active Directory, for example) database. For example, you can disable the Clearspace account of a person whom your external database shows as no longer enabled.

Admin Console: People > Settings > User Data Synchronization Settings

Connecting to the Jive Service Cloud

Jive Software provides a service through which you can add features to Clearspace by connecting your Clearspace instance to a service provider hosted by Jive. Hosted services are ideal for sharing information with people who aren't among people using Clearspace.

You can connect to the service cloud when you're setting up Clearspace using the setup tool, or afterward in the admin console. When you create a connection, give a description that will identify your Clearspace instance to people using the cloud, such as your company name or the name of your instance as it is known to internal users.

Admin Console: System > Management > Service Cloud

Document Sharing

Enable document sharing to provide people using Clearspace with a link through which they can share a document with people outside Clearspace. With the service enabled, people will be able to invite guests by email. Clearspace will present shared documents through a URL to the service, where guests will be able to create an account and view or comment the document.

The document also supports email notifications when there are changes to the document's content or its comments (you currently can't edit the template for notifications sent by the cloud).

Configuring Clearspace Email

Clearspace can send email for notifications, welcome messages, and so on. It can also receive messages, such as for creating a discussion post from an email sent to Clearspace. For sent messages, tou can tailor the form of automatic emails by editing the email templates that are provided for each of these emails.

Note: You can also set up a connection between Clearspace and an email server so that actual email content is synchronized with and displayed as content in a space. For more information see Synchronizing Content with Email or Newsgroups.

Connecting to Email Servers

Clearspace uses an SMTP email server for sending messages such as content update notifications, task reminders, registration confirmations, and so on. It uses a POP3 or IMAP server for receiving messages, such as for creating a discussion post from an email sent to Clearspace.

With configuration settings for your email servers in hand (host name, port, login credentials, and so on), you can set up and test a connection to the servers from the Clearspace admin console. After you change server settings you'll need to restart the application server in order for them to take effect.

Admin Console: System > Settings > Email Server

Managing Email Templates

Clearspace includes about 25 templates to shape the content of emails it sends to people in response to certain events. For each of these, you can edit template content, change template locale, and add new templates for use in other locales.

The templates cover a wide range of actions in Clearspace. Some of these are very common, such as watch notifications sent when content is changed or added (for blogs, documents, spaces, and so on) or when someone requests a reset of their password. Others are sent for actions or events that are more rare, such as when Clearspace detects a virus in an uploaded file. You'll find a complete template list in the Clearspace admin console.

Note: You configure other specific aspects of Clearspace email in other parts of the admin console. For example, you set whether moderation email should be sent at all on the Discussions settings pages (see Configuring Discussions Options).

When you're editing templates, you use the syntax of FreeMarker, the technology used to render most of the Clearspace user interface. Also, each template supports a specific set of tokens to hold the place of email content that will vary from message to message. For example, the notification email sent to those watching a document includes tokens for the document that's being watched, the person subscribed for notification, and the URL of the document they're watching. In the template text you refer to tokens in the FreeMaker way: ${document}, ${user}, ${docURL}, and so on. Here's an example designed to tell the receiving user that a document they're watching has been updated:

${SkinUtils.getDisplayName(user)}, The document "${document.subject}",
    was updated ${JiveGlobals.formatDate(document.modificationDate)} <#if
    versionAuthor?exists>by
    ${SkinUtils.getDisplayName(versionAuthor)}.</#if> To view the document, visit:
    ${docURL}

This template gets the name of the subscribing person and addresses them, then gives the document title, updated date and URL. If the person who updated the document is still in the system, then their name is given also.

Note that the token syntax requires the dollar sign and curly braces; parentheses and square brackets, for example, won't work here. When you're editing a template, the admin console will display the tokens you can use in it.

Admin Console: System > Settings > Email Templates

Enabling Integration with Openfire

By integrating Clearspace with your Openfire instance, you can create a connection in which IM presence information is visible in Clearspace. In other words, with Clearspace and Openfire aware of each other, a person "Available" via IM will appear so in Clearspace. To integrate the two, you'll need Clearspace version 2.0 or higher and Openfire version 3.5.0 or higher. Also, if you want Openfire to use Clearspace as its source of user data, you must have enabled REST-style web services in Clearspace (for more information, see Setting Access for Web Service Clients).

Configuring this connection requires that you make specific settings to both Openfire and Clearspace.

In the Openfire setup tool, on the Profile Settings page, select Clearspace Integration to use as the user and group system to use. On the Profile Settings: Clearspace Integration page, enter the location where Openfire can find Clearspace via REST web services and the shared secret they'll both use. (If you get through the setup tool and decide to change this setting later, you can make the change in the Openfire admin console on the Server > Server Settings > Profile Settings page.)

On the Real Time - Connection Settings page, enter the URL at which Openfire can reach your Clearspace instance. In the Shared Secret box, enter the shared secret that you entered when configuring Openfire. Click Save Shared Secret to create the connection.

Admin Console: Real-Time > Settings > Connection

Getting Information About Performance

Clearspace provides tools through which you can keep track of the application's performance and usage. You can even easily connect your Clearspace instance to a web analytics application to get more detailed usage statistics.

You'll find a thorough guide to getting the best performance out of your Clearspace instance in Fine-Tuning Clearspace Performance.

Adjusting Application Caches

Clearspace caches data in order to reduce the number of trips the application makes to its database. The caches greatly improve performance by letting people get things done in the application more quickly. You can adjust the sizes of these caches so that they're best tailored for your instance's needs.

You'll probably do most of your cache adjustment during the first few months of your deployment, then less frequently as use of Clearspace grows. For more information on improving performance, including adjusting caches, be sure to see Fine-Tuning Clearspace Performance.

Admin Console: System > Settings > Caches

Examining Database Queries

You can view the query expressions Clearspace uses as it interacts with its database. This is handy when you're troubleshooting or looking for ways to improve Clearspace performance. For example, you might use it to look for long-running queries or queries that are running too often.

When you turn this feature on, the admin console displays the query expressions executed (without the actual values used), the number of times a query is executed, the time in milliseconds it took to execute a query, and the average time the query took.

Keep in mind that turning this feature on and leaving it on will slow Clearspace's performance. It's best to use it only while you're collecting performance information.

Admin Console: System > Management > Query Stats

Getting Application Logs

Clearspace logs messages with application information, warning, and errors. When you want to collect information to troubleshoot or enhance application performance, you can view the log messages in the admin console. (You can also log information about databse queries, as described in Examining Database Queries.)

The Log Viewer page displays the log content and gives the file system location where you'll find the log files themselves. You can specify the name for each log file by editing the file <jiveHome>/jive_startup.xml. Here's an example with the default log file names (if you change values in this file, you'll need to restart Clearspace for the changes to take effect):

<jive>
    <!-- ...other properties... -->
    <log>
        <filename>
            <info>jive.info.log</info>
            <debug>jive.debug.log</debug>
            <warn>jive.warn.log</warn>
            <error>jive.error.log</error>
        </filename>
    </log>
    <!-- ...other properties... -->
</jive>

Note that logs in the console aren't the same as as messages logged by your application server. See you app server's documentation to locate its logs.

Admin Console: System > Management > Log Viewer

Auditing Administrative Tasks

Clearspace logs actions you and others take through the admin console. You might find these logs useful when you're tracking down the cause of an error or misconfiguration in the system.

Each log entry includes the time the action was taken, the person whose action resulted in the entry, and the part of Clearspace code that executed to carry out the action.

Admin Console: System > Management > Audit Log Viewer

Tracking Usage Graphically

Clearspace provides charts that illustrates how people are using the application. You can check these reports periodically to get a high-level sense of how content is being used, such as whether discussion posts are replied to, questions answered, and so on.

Admin Console: Reporting > Reporting

Integrating Web Analytics

You can connect Clearspace with a web analytics application such as Google Analytics or WebTrends. When you have an account with a web analytics provider, then add their script via the admin console, the script is automatically inserted by Clearspace at the bottom of Clearspace pages. The script isn't typically displayed to people, nor are the analytics results displayed in the admin console (you get them from your analytics provider).

Here's are two examples of what you might enter in the admin console:

<script src="www.google-analytics.com—urchin.js
        <http://www.google-analytics.com/urchin.js>"
        type="text/javascript"> </script>

or

<script type="text/javascript"> _uacct =
        "AB-123456-1"; urchinTracker(); </script>

Admin Console: Reporting > Settings > Third-Party Integration

Sending Usage Statistics

You can choose to have Clearspace send usage statistics back to Jive Software. The Clearspace Usage Statistics Service periodically collects information about the installation environment and overall activity of your Clearspace instance. This information is offered anonymously; your identity is not included. Jive Software uses the information to make Clearspace even better by analyzing the installation platforms and product features used most often by our customers. The following lists describe what (and how often) information is collected. (Jive Software is committed to maintaining your trust and confidence. Thanks for your help!)

At start-up and once per week the following data is collected:

• Hardware vendor
• Clearspace version
• Operating system vendor and version
• Java Virtual Machine vendor and version
• Application server vendor and version
• Country database version
• User manager class
• Group manager class
• Authentication manager class
• Database vendor and version
• JDBC driver vendor and version
• Time zone
• Anonymous instance ID

Additionally, once a day the daily total counts are collected for the following:

• Messages
• Discussions
• Registered and active users
• Blog posts
• Questions
• Wiki documents

Managing Access

You can manage people's access to Clearspace features through the admin console. A few of these features (described below) are available to system administrators only. But the important work of granting permission for specific user and administrator tasks is available to both system and space administrators. For information about granting permissions, see Managing Permissions.

Configuring User Registration and Login

You can configure how people first get involved in Clearspace. This is especially important if your Clearspace instance provides a collaboration venue for people who sign up on their own (as with many instances of Clearspace Community). You can determine whether (and how) they can sign up on their own, whether you send them a welcome message (and what the message contains), whether they can request a reset of their password, and so on.

Admin Console: People > Settings > Password Reset

Admin Console: People > Settings > Registration Settings

Banning People

You can block a person's access to Clearspace. For example, if someone becomes abusive in their messages (or moderating their content is too time-consuming), you might want to ensure that they can't post any more. You can ban them through their login credentials or their IP address. (If you want to ban them using their IP address, you'll need to enable IP address tracking; the admin console has more information.)

Admin Console: People > Settings > Ban Settings

Configuring Content Handling

Clearspace integrates documents, blogs, and discussions as distinct content formats that people can edit in a common way.

Configuring Document Options

People can create new text documents (with word processor-style formatting) or they can attach documents of other types, including PDF files, Word documents, and spreadsheets.

There are two sets of configuration settings for documents: system-wide settings and space settings.

• System-wide settings (described in this guide) are available for system administrators. They include size of uploaded documents and content types that are allowed for uploading.
• Space settings are available for system administrators and space administrators. Provide a place for an administrator to designate people to approve documents published in the space.

The system-wide settings are described in this document; space settings are described in Managing Spaces, which is intended for space administrators.

Best Practices for Document Options

Use the system-wide settings to configure documents globally based on how you expect people to use documents.

• You might want to disable uploaded documents if you want to ensure that users can create only text documents using the editor in Clearspace. (Note that the content of uploaded documents is searched just as are documents people write in Clearspace.)
• If you enable uploaded documents, you can disallow content types that you don't want stored in the system. People won't be able to upload content of types that you disallow.

Admin Console: System > Settings > Documents

Configuring Discussion Options

Through discussions people ask for feedback from others. 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 many blog posts tend to be).

There are two sets of configuration settings for discussions: system-wide settings and space settings.

• System-wide settings (described in this guide) are available for system administrators. They include abuse reporting, moderation email, read tracking, and threading.
• Space settings are available for system administrators and space administrators. These are settings that those using a particular space might want to have tailor for the space's needs. The settings relate to messages as questions, answers as helpful, moderation level, and email alerts.

The system-wide settings are described in this document; space settings are described in Managing Spaces, which is intended for space administrators.

Best Practices for Discussion Options

Use the system-wide discussion settings to configure discussions globally based on how you expect people to use Clearspace discussions.

• If you're anticipating that people might post abusive messages (such as in an external community), enable the report abuse feature. This causes a "Report Abuse" link to appear in the Actions list for discussions. When someone clicks the link, they'll be able to select an abuse category and enter notes describing their reason for reporting. A single user won't be able to report abuse more than once for a given message. The abuse report will be visible to someone designated to moderate the space containing the discussion.
• With the report abuse feature on, you can specify that the message is hidden from people after a certain number of them report abuse for it.
• Set new threads as questions if you expect people to use Clearspace largely to post requests for information. Threads that aren't questions might be calling other people's attention to something or soliciting feedback (where there isn't an particular answer sought).
• If you're seeing slower performance, try disabling read tracking and turning the thread mode default to "flat." Both of these features can tax performance on some configurations. (Note that users will still be able to set thread mode to either flat or threaded in their preferences.)

Admin Console: System > Settings > Discussions

Managing Blogs

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. (See the Wikipedia definition of "blog".)

As you're managing blogs, keep in mind that the author of a blog also has the ability to edit the blog's settings. They do this on the blog's Blog Management page, reached from the Clearspace Your Stuff menu. In fact, a blog author can do more things with their blog that an administrator can do from the admin console.

Here's a summary of administrative things related to blogs. All of these are available to a blog's author; those in bold are things you can do in the admin console, too:

• Write, view, edit, and delete posts.
• Write, view, edit, and delete comments.
• Approve or delete trackbacks.
• Edit options such as the blog's friendly name, its URL within Clearspace, its description.
• Add or remove blog authors.
• Specify whether people must authenticate in order to comment.
• Approve comments before they're visible.
• Turn feeds from the blog on or off, as well as set what is included in the feed.
• Import content from another blog into a Clearspace blog. A blog author can import from Movable Type, WordPress, and other technologies listed on the Blog Management page.

In addition, you can use the admin console to add and remove authors for a particular blog. You can also set permissions for a blog as well as for blogs globally. See Managing Permissions for information about managing blog permissions.

Best Practices for Blogs

• You can use the Comments page to edit, view, or delete comments to blogs, such as when moderating. Note that the blog's author can also take these actions with comments through the blog management page.
• You can't edit the post for a blog, but you can delete it on the Personal Blogs or Group Blogs page. Deleting a post is one way to remove offensive content.

• You can have content from multiple blogs appear on in a single space by aggregating those blogs into the space. See Managing Spaces for more information.

Admin Console: Blogs > Management and Blogs > Settings

Configuring Private Message Options

You can enable private messages, a feature through which people can send each other messages that aren't visible to everyone else in the way that discussions are. A person receives and reads a private message through the Private Messages tab on their profile.

In the admin console, you can turn the feature and its notifications on or off as well as set a limit on the number of messages allowed per person.

Admin Console: System > Settings > Private Messages

Configuring Support for Images and Attachments

People can insert images and attach files to their documents, blog posts, and discussion messages. Using the admin console, you can configure Clearspace support for images and other attachments.

The distinction between images and attachments is important. People can attach to content any file you allow by using the Browse button at the bottom of the content editing page. Attached files will show up as links at bottom of published content, so that others can click to view the attachment. Note that when someone attaches an image, a preview of the image shows with its link. People can also insert images by using the insert image button on the editing page toolbar. Inserted images will be displayed in the content itself, but won't show up as links at the bottom of the page.

In the admin console, the Attachments page is for configuring the attachment feature; the Images page is for configuring the "insert image" feature. It's a good idea to tailor these settings to best fit your situation. Here are a few suggestions.

• Adjust the cache. Clearspace provides two cache types: file system and in-memory. Use the Images and Attachments pages in the admin console to adjust the file system cache. For example, you might want to increase the cache size if images or other attachments are filling the file system area you're caching to (typically <jiveHome>/images or <jiveHome>/attachments). Note that changing the filesystem cache size on the the Images page makes the same change to the same setting on the Attachments page, and vice versa. You can make in-memory cache changes (for images) on the System > Settings > Caches page. This is a much more short-lived cache that has a larger impact on performance. See Fine-Tuning Clearspace Performance for more on adjusting in-memory caches.
• Manage image and attachment quantity and size. Pay attention to whether larger or more numerous images and attachments make Clearspace slower. If you find that many people are attaching many larger files (and that this is making the application slower), then you might want to create limits by adjusting the size and quantity settings.
• Disallow support for certain content types. You might find that some content file types aren't needed (or are in fact unwanted). You can prevent some kinds of files from being uploaded to Clearspace by "disallowing" them, specifying their MIME content type. If you change these settings, be sure to change it on both the Image and Attachments pages.
• Adjust how images are rendered. You can set guidelines for how Clearspace displays images in content. For example, Clearspace will display attached images as a thumbnail (a smaller version of the image) if the image itself is larger than the size you specify on the Images page.

Note that some of the settings are interrelated. For example, if you want people to be able to attach more images to a document than they are currently allowed to, you'll need to make two changes: increase Maximum number of images per object of the Images page and increase Max number of attachments per document on the Attachments page.

Admin Console: System > Settings > Attachments

Admin Console: System > Settings > Images

Configuring Spell Check

Clearspace checks spelling as people create and edit content. You can tailor this feature to your needs by setting specifying dictionaries that are specific to your locale or technical needs. You can also add words not in the main dictionary to the custom dictionary used by your Clearspace instance; that way, words commonly used where you are won't be marked as misspelled.

Admin Console: System > Settings > Spell Check

Configuring Search

Clearspace provides search access to content it contains (including information about people) as well as access to external search engines that support OpenSearch. You can use the admin console to configure and optimize these for use across your Clearspace instance.

Main Search

Support for searching internal content and user profiles is provided by the Lucene open source search engine. Lucene works by periodically creating an index of content, then searching against the index. As a result, search results are affected by, say, how often the index is updated.

Note: Clearspace includes Search Tips documentation that people can use to make the most of their searches. You can reach the tips from a search page.

Things to keep in mind as you manage the main search:

• The indexes for content and for user information are separate from each other. That means that you can enable searching for content and user information separately (you can turn user searching off, for example). It also means that you can update the indexes separately at need, which can be more practical than updating everything at once when you need to.
• Having Clearspace regularly update the search indexes is very handy; rebuilding an index (via the Index Tasks tab) can be very time-consuming. You should only manually rebuild if you really have to; reasons for doing so are listed in the admin console.
• When you choose to log search queries, the log information is written to the database supporting your Clearspace instance. You can retrieve this information by querying the jiveSearch and jiveSearchCriteria tables. For example, a query can return the query terms used, how many results were returned, the ID for the user who did the search, and so on.
• You can improve searches for people using your Clearspace instance by tailoring the stop words and synonym lists to best suit your needs. For example, if you realize that people will search using slang common to your industry, you could add synonyms that associate a commonly used term with slang alternatives. A software industry example could be "programmer,developer,engineer".
• Try to settle on your list of stop words early, before you've got a lot of content. When you change the list, you need to rebuild the search index; that can take quite a while when you've got a lot of content in the database.
• You can set whether blog and document comments should be found when searching by setting system properties. Use the following system properties (in the admin console at System > Management > System Properties):

  Property	Description	Values
  blog.searchComments.enabled	Toggles whether or not comments to blog posts are returned in search results.	true (default) to enable return of comments on search; false to disable it.
  document.searchComments.enabled	Toggles whether or not comments to documents are returned in search results.	true (default) to enable return of comments on search; false to disable it.

Admin Console: System > Settings > Search

OpenSearch

You can make some external search engines available to people using Clearspace. If a search engine supports OpenSearch, you can add support for it to Clearspace so that the search engine will be used (in addition to the internal search engine) when people search for content. Examples of OpenSearch engines include Technorati and Wikipedia, not to mention Clearspace instances (such as Jivespace).

Engines that support OpenSearch provide a descriptor XML file and usually publish the file at a public URL. The descriptor tells OpenSearch clients (such as Clearspace) what they need to know to query the search engine.

There are two ways you can add OpenSearch engines in the admin console at System > Settings > OpenSearch Engines:

• Enter a descriptor URL, then click Add Engine from Descriptor URL. Clearspace will visit the URL to retrieve the descriptor XML file, then retrieve the needed information from the file.
  
  

  If Clearspace gets the information it needs, that's all there is to it. However, you might get prompted for more information, such as login credentials if the engine is secure. Note that you can edit engine properties later.

  

• Click Add Engine from Form, then fill out the form to include the required information. The information asked for here is what would be included in the descriptor XML file. This is the same information you can edit for an engine, as described below.

  

 

As you edit the engine's properties, keep in mind the following:

• The icon URL is a URL to an icon representing the search engine. Clearspace will display this in its UI.
• Clearspace uses the search URL to send the user's query.
• The search result content type is the content type, such as application/rss+xml or text/html, that the search engine's results will be returned in. If this is a type that Clearspace can parse, such as application/rss+xml, the results will be displayed in the UI; if not, Clearspace will display a link through which the user can separately search the engine's site itself.
• The query test term can be anything you like to test queries.
• You might need to enter a username and password if the search engine requires login credentials.
• The Enabled check box is selected by default, meaning that user searches will query the engine. Clear the box to make the search engine unavailable to people.

Admin Console: System > Settings > OpenSearch Engines

Managing Feeds

People can choose to receive feeds (RSS 1 or 2, Atom) to stay up to date on changes to content they care about. You can configure aspects of these feeds such as which feed technology is used, whether basic authentication is required, and so on.

Admin Console: System > Settings > Feeds

Filtering and Formatting Content

Filters and macros both dynamically reformat the contents of messages, announcements and polls. Filters can be applied globally. 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}).

This console page lists the filters and macros installed for your instance. At the bottom of the page you can install others.

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 your profanity list and replaces them with ***. The profanity filter is the most commonly used filter; please consider using it. You use the filter by adding the words you want filtered out, then turning on the filter. On the Filters and Macros page, scroll to the profanity filter and click its Settings link. On the filter settings page, enter the list of words you want filtered out of your content. Be sure to select check boxes for the parts of the content you want filtered, then click Save Properties. Back on the Filters and Macros page, click the profanity filter's On button to turn it on.

Admin Console: Spaces > Settings > Interceptors

Admin Console: Spaces > Settings > Filters and Macros

Configuring User Appearance Options and Presence

Enabling Personalized Homepages

People can personalize the Clearspace home page using widgets. Widgets are designed to provide a custom view of content (and not necessarily content in Clearspace). If for some reason you want to disable the ability for people to make personalized homepages, you can do so on the Profile and Homepage page.

Admin Console: People > Settings > Profile and Homepage

Defining Profile Templates

In Clearspace, user profiles are like other content in that they can be found on searches. Because of this, information that people give about themselves — including interests and areas of expertise — can be a great source of information for people looking to have a question answered. A person's profile can include biographical and professional information, along with links to content they've contributed.

You can customize the profile template, providing the fields that people will fill in with profile information. Clearspace includes several commonly used fields, but you can add your own as well.

Admin Console: People > Settings > Profile and Homepage

Configuring Organizational Relationships

You can use Clearspace to create or merely display organizational relationships between people using it. Using the admin console, you can define whether organization graphs are displayed and how peers, managers and direct reports are labeled. For example, you might want to change the labels if relationships aren't technical manager/direct report, but something more unique to your organization.

You can also set whether managers and direct reports can change relationships they're in. For example, you could set it so that managers can assign direct reports for themselves.

If the approval process is enabled, changes to relationships by people using Clearspace are sent for approval to people whose user names are in the Notified Users box.

Admin Console: People > Settings > Organizational Relationship Settings

Configuring Organizational Relationships

You can use Clearspace to create or merely display organizational relationships between people using it. Using the admin console, you can define whether organization graphs are displayed and how peers, managers and direct reports are labeled. For example, you might want to change the labels if relationships aren't technical manager/direct report, but something more unique to your organization.

You can also set whether managers and direct reports can change relationships they're in. For example, you could set it so that managers can assign direct reports for themselves.

If the approval process is enabled, changes to relationships by people using Clearspace are sent for approval to people whose user names are in the Notified Users box.

Admin Console: People > Settings > Organizational Relationship Settings

Configuring Status Levels

Creative status level goals are a great way to encourage people to get involved. People accrue status by earning points as they create and respond to content in Clearspace. Over time, people develop a reputation for reliability and authority in their favorite areas. The more people participate, the more information that is available for the community as a whole.

You can set how many points are awarded for a given scenario (an action in Clearspace). You can also define the status levels themselves, setting the point range that the status level represents.

Where a person's name is displayed, Clearspace displays a status icon such as corresponding to the number of points the person 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.

Clearspace provides more than 50 status images, but if you want to add your own you can. To do that, put the GIF files into a <jiveHome>/resources/images/status directory. Use the same naming scheme as the existing images: statusicon-<number-in-sequence>.gif. You might want to start your numbering at some higher level to avoid problems if Clearspace upgrades include more images. For example, to add five new images (where included images currently end at number 52), you could add images called statusicon-100.gif, statusicon-101.gif, statusicon-102.gif, statusicon-103.gif, and statusicon-104.gif.

Here are a few suggestions for making the most of status levels:

• Set the number of points per scenario based on the kinds of activity you want to reward in Clearspace. For example, if you want to provide a context in which questions are usually answered, award more points for correct and helpful question responses.
• Define status levels that people will be enthusiastic about -- make it fun. For example, you could think of it as a kind of game. Is the highest level a "Ninja"? A "Genius"? "Indiana Jones" or "Nobel Candidate"? Devise a list of levels that goes well with the culture of people using Clearspace.

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

Admin Console: People > Settings > Status Level Settings

Avatar Settings

Enable user-uploaded avatars as one of the ways to let people personalize their experience on Clearspace. You can simply enable avatars, in which case administrators will be able to define (even upload) the avatars people can choose from. But you might find that people get more out of Clearspace by uploading their own avatar images.

With avatars enabled, users will get a "change avatar" link in the Actions list of their profile page. Depending on how you've set up the feature, users will be able to select from an existing set of avatar images or upload their own.

Admin Console: People > Settings > Avatar Setting

Setting Access for Web Service Clients

Clearspace exposes much of its functionality as web services. Through a web service client, other applications can interact with Clearspace. In order for this to happen, you'll need to first enable one or more of the web service styles that Clearspace suports. These include SOAP, REST, and XML-RPC. The style you choose will depend on your design goals and the client's needs.

You have several options as to what you'll allow and require for clients attempting to access your instance via web services. You can allow any client to have access or restrict access to clients that authenticate with credentials found in your user database.

Note: You'll need to enable REST web services to set up communication between Clearspace and your Openfire server instance if you have one.

Admin Console: System > Settings > Web Services

Synchronizing Content with Email or Newsgroups

You can create gateways through which Clearspace will synchronize data between a space and an email, newsgroup, or Mbox data source.

When you create a gateway, you specify the data source to synchronize with, along with the space to synchronize. In other words, each gateway is a one-to-one mapping between a space and the data source. You can either create a gateway that's automatically used for synchronizing or you can synchronize data in either direction at need. Gateway settings are scoped to specific spaces.

You can also choose to use a 24-hour buffer for importing. That means that, at the time of import, the gateway pulls in all data that has come in since the last import, plus all those that came in within the 24-hour period before the last import. For example, if an email has already been imported, it won't be imported again, but any emails that came in late and were missed the last time the gateway ran will be imported. This redundancy helps ensure that you get those emails that were held up at the server for some reason and did not get delivered in a timely manner. 

To use a gateway for automatic importing or exporting, you add the gateway, then specify the time interval for importing and/or exporting. To use a gateway for one-time or at-need synchronization, you use the Import Once or Export Once tab.

Admin Console: Spaces > Settings > Gateway Settings

Managing Customizations

Plugins, themes, and other extensions are ways to add and enhance Clearspace features.

Adding and Editing Themes

With themes, you can customize the way Clearspace looks, adding your own logo and brand information. You can even change the composition of Clearspage pages, rearranging them, adding and removing features.

For information on developing themes, see the Clearspace Theming Guide.

Admin Console: System > Settings > Themes

Adding and Removing Plugins

If your Clearspace instance has any plugins installed, you can view a list of them on the Installed Plugins page. If you don't have any yet, Jive Software offers a few you can get started with. The Add Plugin page lists plugins that are available free from Jive Software. It also provides a place to add plugins for which you have a JAR file. The best (and probably easiest) way to install a plugin, however, is to simply copy its JAR file into your <jiveHome>/plugins directory. Clearspace will automatically deploy the plugin code within a few seconds.

Admin Console: System > Plugins > Installed Plugins

Admin Console: System > Plugins > Add Plugin

Adding and Removing Widgets

Clearspace comes with around 30 widgets to use on customized home pages, space overview pages, and elsewhere. If you don't want certain widgets to show up where people can customize page layouts, you can remove them using the admin console. You can also add new widgets. At the bottom of the page, under Add a new widget, enter the fully-qualified class name of the class for the widget you're adding, then click Add Widget. The JAR containing the widget you're adding must be on the Clearspace classpath.

Admin Console: System > Settings > Widgets

Fine-Tuning with System Properties

System properties are name/value pairs that configure particular aspects of Clearspace. Many of these are tied to other settings in the admin console, so that changing the value in the console will change the value of the corresponding system property. Generally speaking, you should leave system properties unchanged unless you're asked to change it by Jive's support team. You might also change a system property value if the change is part of a larger effort to customize Clearspace.

Note: Names and values for system properties and extended properties are case sensitive.

Admin Console: System > Management > System Properties