Blog Posts From Jivespace Community Blog Tagged With plugin

Simplifying plugin upgrades

communities@jivesoftware.com — Tue, 25 Aug 2009 15:24:08 GMT

Attention, Developers!

Have you ever wondered how you can run an upgrade task in a plugin to do something like add an extra column to a table or a new index to boost performance? You know, those one-time tasks that need to be applied consistently across all your environments? One of the powerful (yet often overlooked) features in Jive SBS 3.0 is the ability to run upgrade tasks in a plugin. These tasks are run once and can do anything from modifying a database to creating new files and folders.

The Past...

Prior to SBS, developers relied on a number of techniques to perform upgrade tasks, including:

Checking for the presence of a system property and, if not present, firing off a background thread to perform the upgrade task from the plugin class' init() method
(downside: someone deletes the system property and your upgrade task gets run again, clustering introduces risk that your upgrade will be run more than once, more work than necessary)
Writing a SQL script that could be run by the DBA on each environment prior to the plugin upgrade
(downside: may require special permission to run scripts, especially in hosted environment; not cross-platform compatible; multiple steps in deployment process may easily be forgotten)
Overlaying the core application to include upgrade tasks with core application upgrade tasks to take advantage of native process for handling upgrades
(downside: must be merged with every release, requires multiple deployment artifacts, risky)

...And Now?

I hoped you would ask! Here's what you need to do:

Step 1

If you don't already have it, add the following two items to your plugin.xml:

<plugin>
     <!--...omitted for clarity...-->
     <databaseKey>pluginName</databaseKey>
     <databaseVersion>1000001</databaseVersion>
     <!--...omitted for clarity...-->
</plugin>

Now when the plugin is installed, it will create a record in the jiveVersion database table with the appropriate values for name and version.

Step 2

Create a new file "upgrade.xml" at the root of your plugin. This new file will live alongside your spring.xml, struts.xml, etc., and contains the list of upgrade tasks that will be run. Each upgrade task is given a version. If the version of your upgrade task is greater than the value in the jiveVersion table for your plugin, your task will be run. Once the upgrade is complete, the version in the database will be the same as the highest upgrade task version. Here's an example upgrade.xml taken from our Supportal:

<upgrade-config>
    <upgrades>
        <upgrade order="1">
            <name>supportal</name>
            <tasks>
                 <!-- 3.2.0 -->
                <task version="32000001"
                    className="com.jivesoftware.community.upgrade.tasks.AddEnvironmentsTask"/>
                <task version="32000002"
                    className="com.jivesoftware.community.upgrade.tasks.EnvironmentPermissionsTask"/>

                <!-- 3.2.1 -->
                <task version="32100001"
                    className="com.jivesoftware.community.upgrade.tasks.DeleteDuplicateEnvironmentFieldValuesTask"/>

                <!-- 3.2.2 -->
                <task version="32200001"
                    className="com.jivesoftware.community.upgrade.tasks.RemoveWebServerRequirementFromEnvironmentsTask"/>

                <!-- 3.2.3 -->
                <task version="32300001"
                    className="com.jivesoftware.community.upgrade.tasks.UpdateEnvironmentFieldOptionsTask1"/>
            </tasks>
        </upgrade>
    </upgrades>
</upgrade-config>

Once you have added your task, make sure to update the databaseVersion in your plugin.xml to the same value as your highest upgrade task!

Step 3

Create your upgrade task class. In the example below we're calling out to an XML file that contains the new schema details. More on that in a sec. Here's the source code:

package com.jivesoftware.community.upgrade.tasks;
 
...imports omitted
 
public class RemoveWebServerRequirementFromEnvironmentsTask implements UpgradeTask {
 
    private static final String SQL = "RemoveWebServerRequirementFromEnvironmentsTask";
 
    public String getName() {
        return "Remove requirement for filling out web server from environment template fields";
    }
 
    public String getDescription() {
        return "Task to mark environment template fields for web server as non-required.";
    }
 
    public String getEstimatedRunTime() {
        return "1 second";
    }
 
    public String getInstructions() {
        return "To run manually, copy the SQL from the RemoveWebServerRequirementFromEnvironmentsTask.xml and run directly against your DB.";
    }
 
    public boolean isBackgroundTask() {
        return false;
    }
 
    public void doTask() throws Exception {
       UpgradeUtils.executeSQLGenFile(SQL, getClass());
    }
 
}

Step 4 (almost there!)

The last thing you need to do (assuming you are updating your DB, of course) is to create the XML file that will be read when UpgradeUtils.executeSQLGenFile(SQL, getClass()) is called. To do this create an XML file in the same path of your class with the same name as your class, only ending with the .xml extension. Following the example above, this could look like the following:

<schema name="Environment Schema">

    <sql description="Update default data for environments."><![CDATA[
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 40;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 59;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 78;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 97;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 116;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 135;
        update supenvtemplfield set isRequired = 0 where envtemplfieldid = 154;
        ]]>
    </sql>

</schema>

The <sql> element lets you execute arbitrary DML or DDL statements against your DB. You can also use the <alter> tag to change an existing table:

    <alter table="jiveBlog" type="add" description="Add Container Type and ID to JiveBlog">
        <column name="containerType" type="int" nullable="false" default="-2"
                description="The type of the container to which the blog belongs"/>
        <column name="containerID" type="bigint" nullable="false" default="17"
                description="The ID of the container to which the blog belongs."/>
        <index type="normal" name="jiveBlg_ctID_idx" column="containerID, containerType"/>
    </alter>

Additionally, you can define new tables using the same syntax as you would in your schema.xml:

    <table name="environmentTemplate" description="Customer environment template">
        <column name="templateID" type="bigint" nullable="false" description="Environment template ID."/>
        <column name="name" type="varchar" size="255" nullable="false" unicode="true"
                        description="The display name of the template (shows in environment template selection)."/>
        <column name="description" type="text" nullable="true" index_none="true" unicode="true"
                description="Tells admins the purpose of this template"/>
        <column name="status" type="int" nullable="false"
                description="The published status of the environment template."/>

        <index type="primary" name="envTempl_pk" column="templateID"/>
        <index type="normal" name="envTempl_templID_st_idx" column="templateID,status"/>
    </table>

What happens if my upgrade runs into problems?

It is important to note that plugin upgrades are run in the background during plugin initialization, so you won't see the upgrade screen similar to what is shown when you upgrade SBS. However, any errors that occur during the plugin installation will be reported to you in the admin console under System > Plugins. Here's what you can expect to see:

Questions?

Leave a comment for me here, or shoot a message to @austrum on Twitter!

Support Design Introduction

communities@jivesoftware.com — Thu, 20 Nov 2008 21:47:06 GMT

Supportal

This is the first in a series of upcoming blog posts where we will delve into the details behind our Supportal. As most of our customers are already aware, the Supportal is Jive's Clearspace customization that transforms generic communities into personal communities where Jive collaborates directly with our customers via cases, documents, and projects.

This first post will provide the high-level overview, overriding design goals, business goals, and additional benefits to the Supportal. Future posts will delve into the business decision details, and the architecture.

The Name

People often ask how the name Supportal came to be. When it comes to overall creativity, I am horrible. In this project's infancy, I used Customer Portal, Customer Support Portal, Support Portal, and many other terms as names. Will French, Jive's Senior Support Engineer, and now the Supportal Development Lead, abbreviated Support Portal, to Supportal (likely making fun of me talking too fast), and the name stuck. It also gets rid of that stigma around the word "portal" as well!

Reasons for the Supportal

The Supportal was created to resolve's Support's own business pains. Prior to identifying the business pains however, we set 3 main overriding goals for the project:

Simplicity: The goal of the supportal is to solve business pain. Too many other support sites are tough to use and hard to navigate. Creating a case needs to be as simple and easy as possible. We continue this philosophy on upcoming features, ensuring that additional features add benefit without causing pain.
Accessibility: Customers weren't getting the information they needed, and people within Jive were not seeing the information they needed. The solution needed to include as many people as possible, while still being private so that only Jive and the customer can see the information.
Usability: Jive prides itself on this, and this is something that's always on our list. Making the Supportal as usable as possible is also a guiding factor we focused on during the first iteration and continue to improve upon.

With the overriding goals set, we identified the following business goals:

Create a solution where customers can go to create all their cases, regardless of severity
Replace email with an online system as the mode of communication
Recreate survey information. Associate the survey to the case.
Integrate Discussions (only community) with cases to provide customers with a single location to get their answer.
Provide customers the ability to create public cases, allowing others (outside Jive support) to read, contribute, and resolve, while ensuring that Jive Support will answer your issue.
Provide the same functionality (email) for customers who refuse to use the new system.
Remove manual customer and contract validation process

Solution

With the business goals identified, we realized that we had to integrate with our online community. Clearspace provided communities (security for each customer), email notification, reply by email, discussions, and a means to replace email as the primary mode of communication. 80% of the work was done for us. The missing parts were:

Auto-creation of customer communities via account, customer, and contract information in Salesforce
Validating customer ability to create cases upon user login
Adding meta data into customer community discussions, allowing them to become cases.
Customizing customer communities to show cases instead of discussions.
Synchronizing the cases (specifically the meta data) with Salesforce.
Paging for Severity 1 cases
Surveys
Creating cases via email

The following blog posts are going to delve into these sections providing more information behind each business goal, and how we customized Clearspace to solve the goal.

Additional Benefits

As with many solutions, we quickly realized that the Supportal can be used for more than just customer cases. The first additional use case for the Supportal was identified when our professional services team started using Clearspace's project functionality within the Secure Communities. This was exactly what Clearspace Projects were intended for, and the Supportal solved our PS department's communication requirements perfectily with no additional customizations.

We also have experienced a slight decrease in overall cases due to the increased visibility of the cases. Managers will frequently apply a community watch so that they receive emails whenever anyone creates a case in their community. We have had managers reply to a case telling us to disregard the case due to it being something they need to solve internally. We have also had managers follow up with their team directly when issues are stagnating, allowing us to resolve issues quicker.

Finally, the public case feature is being used for about 7% of all of our cases. Not a huge number, but definitely significant, and each additional case that is made public results in additional information in our community for others to see and use. This stat is without us pushing the feature at all.

More Widget Development in Clearspace 2.0

communities@jivesoftware.com — Thu, 05 Jun 2008 15:45:45 GMT

Learn all about how to write new widgets for Clearspace 2.0 from Aaron Johnson, Engineering Manager at Jive.

You can also download the Quicktime version (Caution: file is ~285MB), or you can watch a larger version online, which will improve readability of embedded screenshots (recommended).

The entire presentation is also attached below as a PDF file.

You can also watch an earlier video about developing widgets for Clearspace 2.0

New Widget: Community Navigation

communities@jivesoftware.com — Mon, 19 May 2008 15:57:57 GMT

Samee from SourceN just published a new widget that can be used to add an expandable tree view of communities to any customized space. The Community Navigation Widget was created at the request of another community member, Eric Tufts who wanted to replicate the functionality of the browse drop-down menu embedded in a space.

Please try it out and provide feedback in the comments area of the plugin.

Don't forget that we have many more plugins and widgets available for download on the Plugins page.

New Plugin: Feed your Blog

communities@jivesoftware.com — Mon, 28 Apr 2008 23:36:29 GMT

Have you ever wanted to display your external (public) corporate blog inside the internal Clearspace instance used by your employees? Would you like to display content from your personal blog within your Clearspace instance?

The Feed Your Blog plugin gives you the ability to do both of the above and more. This plugin allows your Clearspace instance to periodically poll an RSS or Atom feed and have it post any new entries that it finds to a blog that you specify.

You can get this plugin and other plugins by visiting our plugin page. You can also view the source code of our plugins by browsing our svn repository.

Want to Display a Calendar in Clearspace?

communities@jivesoftware.com — Fri, 18 Apr 2008 16:41:03 GMT

We've had requests for Calendar functionality in Clearspace, but so far, we haven't had an easy way to add a Calendar. Now, with Jive's recent Jotlet.net acquisition, we have a way for people to add calendars to Clearspace customized space pages with the Jotlet.net Calendar Plugin!

This simple Jotlet.net Calendar Widget is a plugin that contains a widget that lets you show and edit any or all of your Jotlet.net calendars on your Clearspace community, homepage, or project pages.

Or if you just want to see how Adam Wulf created this widget, you can find the source code in our svn repository. You can also find the Jotlet.net Calendar widget and more plugins for Clearspace in Plugin Downloads

New Plugin: Member Map

communities@jivesoftware.com — Wed, 26 Mar 2008 16:49:43 GMT

Jim Tremlett just released, Member Map, a new plugin for Clearspace based on Google Maps.

The Member Map plugin builds on the Google Map plugin developed by Jay Allen. The plugin displays the location of members of a community based on their addresses. The plugin employs Google's Map API for both the display of the map as well as the geocoding of addresses. As such, the address may be as general as a zip code or state, or as specific as a full address including street address.

Want to Create Fancy Charts in Clearspace?

communities@jivesoftware.com — Tue, 12 Feb 2008 00:56:33 GMT

Appfire has just released the FlashCharts Plugin for Clearspace. The Appfire FlashCharts Plugin introduces "data visualization" to Clearspace through stunning XML-based Flash charts and graphs. 20 different flavors of animated charts are individually controlled through 'macro parameters' and a set of associated 'xml data structures' required by each chart type.

You can get all of the details about the FlashCharts plugin and download other cool Clearspace plugins on Jivespace.

Easy Way to Embed Presentations or Other Media in Clearspace

communities@jivesoftware.com — Thu, 10 Jan 2008 18:59:14 GMT

If you are looking for an easy way to display slide shows in Clearspace, we have a SlideShare Macro plugin that lets anyone display a slide show presentation in documents, blog posts, and threads.

You can use this plugin to display SlideShare presentations, but it also provides a simple example code to illustrate how you can use a plugin to display media from other online sources in Clearspace as embedded content. You can learn more about the plugin or just download the code from svn.

A quick example:

Interested in Embedding Videos in Clearspace?

communities@jivesoftware.com — Wed, 19 Dec 2007 19:39:04 GMT

If you want to easily embed videos in your Clearspace blog posts, documents, and discussions, we have two plugins that might be useful.

The YouTube macro lets you embed videos from YouTube, which is great for smaller videos. For longer videos (more than the 10 minute YouTube limit), we have a blip.tv plugin.

All of the videos on Jivespace use the blip.tv plugin. Here's an example in action:

Download or learn more about these plugins from Jivespace or visit our svn server to download the source and see how we did it!

If you are interested in writing your own plugin or macro for Clearspace, you can find plenty of information in our documentation space.

Add Shiny New Features to Clearspace with a Simple Macro

communities@jivesoftware.com — Tue, 13 Nov 2007 22:15:47 GMT

Want to add a shiny new feature to your Clearspace community? It just might be easier than you think! A macro can be used for anything from embedding videos to displaying Jira Issues to adding bling

A macro class that extends com.jivesoftware.community.renderer.BaseMacro. This class will implement the methods that Clearspace calls to get the String value for display in the user interface where the user has inserted your macro.
Macros are technically plugins, so yours will include a plugin.xml file that describes the plugin to Clearspace, including which Java class is your macro class.

to your text. They are also an easy way to get started if you want to add some custom functionality to your Clearspace community.

The basics

For simple macros, you'll really need just two pieces of code:

The process

Set up your testing environment and project hierarchy.
Create your plugin.xml file, which tells Clearspace what's in the plugin -- in short, what Clearspace features you're extending -- and where to find code and other supporting files your plugin needs
Create a plugin class with the logic to tell Clearspace what to do when the user uses your macro.
Build, deploy, and test your macro.

Sounds pretty easy. If you still aren't sure, you can start with these documents and tutorials:

The specified document was not found.
The specified document was not found.
The specified document was not found.

And as always, you can post any questions here in Jivespace if you get into any trouble.

What's your craziest idea for a macro?

Clearfox: Firefox Plugin for Clearspace

communities@jivesoftware.com — Wed, 03 Oct 2007 04:48:01 GMT

Learn more from Aaron Johnson about creating Firefox plugins that access Clearspace information using the Clearfox plugin as an example.

or download the Quicktime version (caution: 144MB file)