This document introduces content syndication of Jive Forums data via RSS.

What is RSS?

RSS (Really Simple Syndication or Rich Site Summary) is an XML data format for publishing content from a new-like site. A news-like site is a site that publishes unique items of information - essentially, it is content that can be split into specific parts. In the world of forums those parts can be forums, topics and messages.

For more background, please see the more info section.

Changes in Jive Forums 5.x.

There have been several minor changes in the RSS feeds going from Jive Forums 4.x to Jive Forums 5.x.

RSS versions

There are several versions of the RSS specification out there - Jive Forums publishes RSS in RSS 2.0 format. If you must publish in a different version, it's easy enough to tweak the RSS output slightly. Remember, RSS is XML so it's always possible to reformat the XML generated by Jive Forums via an XSL transformation or some other method.

Jive Forums does implement a few RSS 2.0 specific tags. These include 'pubDate' and 'ttl' which allow newsreaders to more intelligently query your RSS feeds for updates.

RSS Pre-Requirements in Jive Forums

It is necessary to set the 'jiveURL' property - this tells Jive Forums the public web path to your installation. It's necessary for the RSS feeds because part of the generated RSS is a link back to your installation and the full URL needs to be constructed. Often, the value of this can be set to "http://www.mysite.com/forums" for example.

To set this value, login to the admin tool and click on the "Global Settings" tab then click on "Email Settings" in the left sidebar. Look under the "SMTP Settings" and you'll see this property. This is also a good thing to set if you're using email watches because emails sent to your users must contain the full URL of your installation.

Getting RSS data from Jive Forums

By default, RSS feeds are disabled. To enable them, login to the Jive Forums Admin tool (as a system administrator user). Click on the "Skin Settings" tab then click on "Features" in the left sidebar. You should see the option for "Content Syndication (RSS feeds)" - change the option to "Enabled" and click "Save Settings". To test your RSS feeds, call one of the RSS JSP pages. These are included in the default skin and will be referenced off the context where you installed Jive Forums. So, if you installed Jive Forums in a webapp called "jive" mapped to /jive, then try the following URL: http://www.yoursite.com/jive/rss/rssforums.jspa. If you see a bunch of text or XML, then things are working correctly.

There are several RSS feeds currently available from your Jive Forums installation - forum data, popular forum data, topic data, popular topic data, announcements, community statistics, and message data. The example URL above pulls forum data while the following URL pulls topic data: http://www.yoursite.com/jive/rss/rssthreads.jspa. Again, if you hit that URL and see a bunch of text or XML, then everything is working correctly.

The following table describes the available data sources (forum, topic and message datasources), the parameters each takes, and how you can affect output given different parameter values.

JSP RSS page Parameters Parameter Description
ALL username STRING - The username to authenticate with (default is anonymous login).
ALL password STRING - The user's password.
ALL numItems INTEGER - The number of items to show in the feed.
 
rss/rssforums.jspa forumIDs LONG - a comma-seperated list of one or many forum IDs.
categoryIDs LONG - a comma-seperated list of one or many category IDs.
 
rss/rssthreads.jspa forumID LONG - the ID of the forum that contains the topics we're interested in.
categoryID LONG - the ID of the category that contains the topics we're interested in.
Full BOOLEAN - indicates whether or not the message body of the topic's root message should be printed.
 
rss/rsspopularthreads.jsp forumID LONG - the ID of the forum that contains the topics we're interested in.
categoryID LONG - the ID of the category that contains the topics we're interested in.
Full BOOLEAN - indicates whether or not the message body of the topic's root message should be printed.
 
rss/rssmessages.jsp threadID LONG - the ID of the thread that contains the messages we're interested in.
forumID LONG - the ID of the forum that contains the messages we're interested in.
categoryID LONG - the ID of the category that contains the messages we're interested in.
Full BOOLEAN - indicates whether or not the full message body should be printed.
 
rss/rssannounce.jsp forumID LONG - the ID of the forum that contains the announcements we're interested in.
categoryID LONG - the ID of the category that contains the announcements we're interested in.
Full BOOLEAN - indicates whether or not the full announcement body should be printed.
start DATE - indicates the starting date to check for announcements (default format is MM/dd/yyyy). You can override the date format by specifying a Jive property of "rss.rssannouncements.dateformat". Typically, start and end dates for announcements should not be specified since that could include expired announcements.
end DATE - indicates the ending date to check for announcements (default format is MM/dd/yyyy). You can override the date format by specifying a Jive property of "rss.rssannouncements.dateformat". Typically, start and end dates for announcements should not be specified since that could include expired announcements.
 
rss/rsscommunitystats.jsp forumID LONG - the ID of the forum that contains the statistics we're interested in.
categoryID LONG - the ID of the category that contains the statistics we're interested in.
userID LONG - the ID of the user whose message count we're interested in. If this parameter is present, the returned message count will only include messages posted by the specified user.
countUsers BOOLEAN - indicates whether the user count should be included. False by default.

Notice that with each feed page you can pass in a username and password. By default, RSS will retrieved with the same forum permissions that an anonymous user has but using a username and password you can specify a user to authenticate with.

The following table contains examples of the above JSP pages and parameters in action.

URL Description
rss/rssforums.jspa Returns a list and description of all forums in the system.
rss/rssforums.jspa?categoryIDs=3,5,19 Returns a list and description of all forums in the categories 3, 5 and 19.
rss/rssforums.jspa?forumIDs=2,3,4 Returns a list and description of specified forums.
rss/rssforums.jspa?forumIDs=2&username=foo&password=bar Returns a description of just forum 2 and uses the read privileges of the "foo" user.
rss/rssthreads.jspa Returns nothing - at the very least, you must specify a forumID or a categoryID.
rss/rssthreads.jspa?forumID=3 Returns a list of topics from the forum 3.
rss/rssthreads.jspa?categoryID=3&Full=true Returns a list of topics from the category with the ID of 3. The body of the root message of every topic is also printed.
rss/rsspopularthreads.jspa?Full=true Returns a list of system wide popular topics. The body of the root message of every topic is also printed.
rss/rssmessages.jspa?categoryID=5&messageCount=20&username=foo&password=bar&Full=true Returns the latest 20 messages in the category with the ID of 5 and uses the read privileges of the "foo" user. The body of the root message of every topic is also printed.
rss/rssannounce.jspa?forumID=3 Returns a list announcements in forum 3.
rss/rssannounce.jspa?forumID=3&start=08/02/2004 Returns a list announcements in forum 3 since August 2, 2004.
rss/rsscommunitystats.jspa?categoryID=2 Returns statistics for category 2. This will include the total number threads, forums, subcategories, and messages (including those in subcategories.)

Sample output and element description

Given the URL: /rss/rssforums.jspa?forumIDs=2,3 you might see:

<?xml version="1.0" encoding="ISO-8859-1"?>
<rss version="2.0" xmlns:jf="http://www.jivesoftware.com/xmlns/jiveforums/rss">
<channel>
    <title>Jive Forums RSS Feed</title>
    <link>http://yoursite.com/jive</link>
    <description>List of forums</description>
    <language>en</language>
    <generator>Jive Forums Silver 4.0.0 RC (www.jivesoftware.com)</generator>
    <pubDate>Thu, 07 Oct 2004 16:43:38 -0700</pubDate>
    <item>
        <title>Feature Discussion</title>
        <link>http://demo.jivesoftware.com/jive/forum.jspa?forumID=2</link>
        <description>Voice your ideas for Jive. You must be a registered user to post in this forum.</description>
        <jf:creationDate>Sun, 03 Sep 2000 03:30:46 -0700</jf:creationDate>
        <jf:modificationDate>Mon, 27 Sep 2004 16:48:23 -0700</jf:modificationDate>
        <jf:threadCount>564</jf:threadCount>
        <jf:messageCount>2138</jf:messageCount>
        <jf:dateToText>Sep 27, 2004 4:48 PM</jf:dateToText>
    </item>
    <item>
        <title>For Developers</title>
        <link>http://demo.jivesoftware.com/jive/forum.jspa?forumID=3</link>
        <description>Post questions relating to programming with the Jive API, custom integrations or other technical questions.</description>
        <jf:creationDate>Sun, 03 Sep 2000 03:31:06 -0700</jf:creationDate>
        <jf:modificationDate>Wed, 14 Jul 2004 06:04:11 -0700</jf:modificationDate>
        <jf:threadCount>604</jf:threadCount>
        <jf:messageCount>2477</jf:messageCount>
        <jf:dateToText>Jul 14, 2004 6:04 AM</jf:dateToText>
    </item>
</channel>
</rss>

Along the same lines for topics, if you entered: /rss/rssthreads.jspa?forumID=2&numItems=2 you'd get:

<?xml version="1.0" encoding="ISO-8859-1"?>
<rss version="2.0" xmlns:jf="http://www.jivesoftware.com/xmlns/jiveforums/rss">
<channel>
    <title>Jive Forums RSS Feed</title>
    <link>http://yoursite.com/jive</link>
    <description>Most recent forum messages</description>
    <language>en</language>
    <generator>Jive Forums Silver 4.0.0 RC (www.jivesoftware.com)</generator>
    <pubDate>Thu, 07 Oct 2004 16:48:18 -0700</pubDate>
    <item>
        <title>Re: Unable to load database driver 'oracle.jdbc.driver.classes12.jar' -</title>
        <link>http://demo.jivesoftware.com/jive/thread.jspa?messageID=87086&tstart=0#87086</link>
        <description><![CDATA[Say what? <img border="0" src="images/emoticons/happy.gif" alt=":)">]]></description>
        <jf:creationDate>Mon, 27 Sep 2004 16:40:09 -0700</jf:creationDate>
        <jf:modificationDate>Mon, 27 Sep 2004 16:40:09 -0700</jf:modificationDate>
        <jf:author>bill</jf:author>
        <jf:replyCount>0</jf:replyCount>
    </item>
    <item>
        <title>Re: Unable to load database driver 'oracle.jdbc.driver.classes12.jar' -</title>
        <link>http://demo.jivesoftware.com/jive/thread.jspa?messageID=87083&tstart=0#87083</link>
        <description><![CDATA[thanks ... can we spell ouzo?]]></description>
        <jf:creationDate>Mon, 27 Sep 2004 16:27:09 -0700</jf:creationDate>
        <jf:modificationDate>Mon, 27 Sep 2004 16:27:09 -0700</jf:modificationDate>
        <jf:author>barry</jf:author>
        <jf:replyCount>1</jf:replyCount>
    </item>
</channel>
</rss>

One quick thing to notice: the link to your site is computed correctly. The RSS JSP computes your site URL based on the value you specify for it (usually, this is set during the setup process). To see what value is being used, open the admin tool, click the "Global Settings" tab, then click the "Email Settings" link in the left sidebar. From there, you should see a field labelled "URL to your installation". The value of that should be something like: http://www.mysite.com/jive (no trailing "/").

The following table details the non-standard RSS XML elements returned (these are Jive Forums specific elements):

Element Description
jf:creationDate The creation date of the item. The date format isn't always the same - it is Java locale specific. This is because it's intended to be human readable, not computer readable. The date formatter is created like so: DateFormat.getDateTimeInstance(DateFormat.MEDIUM, DateFormat.SHORT);
jf:modificationDate The modification date of the item - same as creation date for formatting.
jf:dateToText The relative date in a very human-readable format.
jf:threadCount The number of topics in the given forum (forum feeds only).
jf:messageCount The number of messages in the given forum (forum and topic feeds only).
jf:replyCount The number of replies (topic and message feeds only).
jf:body The full body of the root message in the given topic (topic feeds only).
jf:author The username of the author who created the topic or nothing if the topic was posted anonymously.
jf:date A short, easily readable date string specifying the creation or modification date of an item.

Displaying RSS (or, actually doing something with this stuff)

An RSS feed is great but worthless unless humans can read it in a human-readable format. There are a lot of RSS aggregators out there - since the RSS produced is valid an RSS-compliant reader will be able to parse it and display it to a user. However, a more powerful use of this is to use an XSL transform to print the content as HTML and include it in a webpage. Doing this allows you to syndicate the forum content to other parts of your site - even outside of the Jive Forums webapp!

We recommend using some standard and open-source JSP tag libraries to do an XSL transform on the RSS feed inside of another JSP page. The JSTL tag libraries do the XSL transform and another tag library caches the output for a specified amount of time. It's wise to do XSL transforms inside of a cache tag since they're usually computationally expensive and take a while to do.

Follow the steps below to starting doing cached XSL transform of your RSS data.

  1. Download the OpenSymphony OSCache library and install it in your webapp.

  2. If your servlet container does not include the JSTL tag libraries, download and install them in your webapp.

  3. Assuming you have the above tag libraries installed, you can insert the following code in your JSP page:
    <%@ taglib uri="http://www.opensymphony.com/oscache" prefix="cache" %>
    <%@ taglib uri="http://java.sun.com/jstl/xml" prefix="x" %>
    <%@ taglib uri="http://java.sun.com/jstl/core" prefix="c" %>
    
    ...
    <table>
    <%-- cache output for 3 mins (180 sec) --%>
    <cache:cache time="180">
    
        <%-- Link to your RSS feed here --%>
        <c:import var="forumsxsl" url="/xsl/forums.xsl" />
        <c:import var="forumsxml" url="http://www.yoursite.com/jive/rss/rssforums.jspa?categoryIDs=1,2,3"/>
        <x:transform xml="${forumsxml}"  xslt="${forumsxsl}" />
    
    </cache:cache>
    </table>
    
    The contents of the file /xsl/forums.xsl would resemble the following:
        <?xml version="1.0" ?>
           <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    
               <xsl:template match="/">
                   <xsl:apply-templates/>
               </xsl:template>
    
               <%-- Template for all "item" matches --%>
               <xsl:template match="item">
                   <tr valign="top">
                       <td width="1%" class="bullet">&#149;</td>
                       <td width="99%" class="news-item">
                           <b>
                           <%-- Create the link to the forum --%>
                           <a class="forum-link">
                               <xsl:attribute name="href">
                                   <xsl:value-of select="link"/>
                               </xsl:attribute>
                               <xsl:value-of select="title"/>
                           </a>
                           </b>
                           <br />
                           <%-- Show the date it was last updated --%>
                           Last Post: <xsl:value-of select="jf:dateToText" />
                       </td>
                   </tr>
               </xsl:template>
    
               <xsl:template match="text()"/>
    
           </xsl:stylesheet>
    

    So what's going on here? We're creating a TABLE of items, each item is an HTML TR row. Notice in the transform we can pick and choose the elements we want to use from the RSS. Here we're only using the link to the forum, the forum name and the date it was last updated.

  4. Experiment with your own XSL transformations!

More information on RSS

There are many articles and a large amount of information about RSS on the web. Here are just a few links: