Working with Clearspace Feeds

Like many web sites and applications, Clearspace provides the ability for people to get a digest of its content through a feed. By subscribing to a feed and using a feed reader (also known as an aggregator), people can discover what has been changed in Clearspace without having to visit the application just to find out. Feeds provide data about Clearspace content in a format that a feed reader can use.

People can view a list of the feeds related to the page they're on by clicking the View RSS feeds link the in Actions box.

This will display a list of the feeds available (such as for the "Wellness" space here):

They can also click an icon in their browser's address bar.

When they select one, they'll be able to view the content that would currently be associated with the feed.

Enabling Feeds

Feeds are enabled by default in Clearspace (for use internally) and Clearspace X (for use externally). However, in the internal version basic authentication is required by default. Using the admin console, you can turn feeds on or off, specify which format should be available, and specify whether users (via their feed readers) should be required to send a user name and password with feed requests (use basic authentication). In the console, go to System > Settings > Feeds.

Note: In order for people to use the links available in feeds, you'll need to be sure you've set the jiveURL property. This tells Clearspace the public web path to your installation. This is necessary to support links to Clearspace from content listed in the feed reader. You typically set the jiveURL when you're setting up Clearspace. After setting up, you can set or change the URL in the admin console by setting the jiveURL system property at System > Management > System Properties.

Feeds Available in Clearspace

Clearspace offers feeds in three formats: RSS (Really Simple Syndication) (versions 1.0 and 2.0), Atom 1.0, and JSON (Javascript Object Notation). Each of these carries the feed data in a different way. You can retrieve feed results by using the URLs listed here.

Where noted, these URLs support the following variable parts:

• tag_name — The tag that's been applied to the blog post. In the user interface, tags are listed at the bottom of the post.
• user_name — The user's login name.
• communityid — You can find this number at the end of the URL after you click View RSS Feeds in the All Content page. In the admin console, the ID number is shown at Space/Communities > Settings > Space/Community Settings.
• document_id — A unique identifier for a wiki document. You'll find the ID at the end of the URL when you're viewing a Clearspace document.
• post_id — A unique identifier for a blog post.
• blog_name – A blog's name. For a user blog, this is typically the user's name.
• search_string — For feeds based on searches, this is the URL search parameter created when the user searches.
  Here's an example with the typical full set of search parameters included. In this case, the search term is "macro".

  q=macro&resultTypes=BLOG_POST&resultTypes=DOCUMENT&resultTypes=MESSAGE&resultTypes=COMMUNITY
      &peopleEnabled=true&dateRange=all&communityID=2000&numResults=15&rankBy=10001

  The example search string includes the following parameters:

  • resultTypes — The kinds of content to search.
  • peopleEnabled — Whether to search people's profiles.
  • dateRange — When the content was added. Acceptable values are: yesterday, last7days, last30days, last90days, thisyear, and lastyear.
  • communityID — The ID number for the space/community.
  • numResults — The number of results to display.
  • rankBy — How results should be sorted. Acceptable values are: 10001 (by relevance), 107 (by rating), 6 (by subject), and 9 (by date).

You can also include the following parameters in your feed URL:

• full — Whether to include the full content in the results. Include full=false as a parameter when you want to return just a summary in feed results.
• numItems — The number of results to return. For example, you could include numItems=25 to return 25 results. The default is 10.

In addition, if your Clearspace instance requires basic authentication (a user name and password), you might need to prepend the feed URL with the username and password parameters. Here's an example:

https://<username>:<password>@<domain>/community/feeds/documents

If you don't want to enable basic authentication but still need to send a user name and password, you can use the following form (note that this is less secure):

https://<domain>/community/feeds/documents?username=<username>&password=<password>

System Wide

Per Space

Feed URLs for a particular space/community are similar to the system-wide feed URLs above. The difference is the space-specific feed URLs are appended with the community ID number. You can find this number at the end of the URL after you click View RSS Feeds in the All Content page. In the admin console, the ID number is shown at Space/Communities > Settings > Space/Community Settings.

Per Blog

Per Document

Feed URLs for documents include the document ID. You'll find the ID at the end of the URL when you're viewing a Clearspace document.

Per Person