Blog Posts From Jivespace Community Blog Tagged With sbs

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!

Giving customers the power to organize open support ticket priority, on the fly!

communities@jivesoftware.com — Thu, 11 Jun 2009 16:43:49 GMT

Out with the old

In the past, when a customer wanted to check on the status of any of their open cases they would log into their secure space overview page and use the Community Open Cases widget. This widget was designed with a very simple goal in mind, just display the open cases with a bit of extra information and an emphasis on Severity 1 issues. This proved useful for quite some time and gave customers a good overview of what was going on with their community from a support perspective.

However, there was one major flaw. Customers had no way of interacting with this information and often found it very difficult to organize this data in a manner that they could use quickly and efficiently. Welcome, open cases widget 2.0!

The new and improved open cases widget

Along with our upgrade of the Supportal to SBS 3.0, I took on the job of updating this widget to provide customers with better control over their open cases. There are two major upgrades that I gave this widget which have enhanced the way people use it:

1. Cases broken down by Severity

Instead of displaying all the open cases in a potentially enormous group, I've broken down the display into 3 distinctive parts. This is especially helpful for customers with more than 10+ open support cases at a time and allows customers to quickly see if they have any Level 1 issues that they need to attend to quickly.

2. New case option available: Priority

To the right of every case status is a set of up and down buttons which control the individual priority of every issue (within their respective severity).

Okay great, so how do I use it?

Step 1: Log in

Log into the Supportal and visit your Company's secure space "Overview" tab

Step 2: Organize open cases

Browse through any open cases and use the "move up/move down" buttons to re-order them. All the moving on the screen will be done in real-time thanks to our good old friend Javascript. You may recognize these buttons from SBS, as they are used to control the location of profile fields on the admin console registration settings page.

Step 3: Don't forget to Save!

As of right now, your cases will be in the order you want on the overview page, but there is one final step. You will need to click the Save Settings button at the bottom right hand corner of the widget. This will take the current ordering of your widget and persist the case priorities to the database.

You will receive a friendly notification at the top of the widget that your Priority changes have been successfully saved, and you are done!

Well that's easy enough, how does it all work?

I'm glad you asked--it's really quite simple.

Displaying the widget

First off, the widget loads up all the non-closed cases within a secure space and puts them into three different Collections (one for each severity):

for (String caseID : caseIDs) {
    try {
        SupportCase supportCase = supportCaseManager.getSupportCase(Long.parseLong(caseID));
        String status = supportCase.getStatus();
        if (status != null && !caseStatusManager.isClosedStatus(status)) {
            String severity = supportCase.getSeverity();
            String priority = supportCase.getPriority();
            supportCase.setPriority(priority != null ? priority : "0");
 
            if(severity.equals("Level 1")) {
                openSev1Cases.add(supportCase);
                Collections.sort(openSev1Cases, new CaseComparator());
            }
            else if(severity.equals("Level 2")) {
                openSev2Cases.add(supportCase);
                Collections.sort(openSev2Cases, new CaseComparator());
            }
            else {
                openSev3Cases.add(supportCase);
                Collections.sort(openSev3Cases, new CaseComparator());
            }
        }
    }
    catch (NotFoundException e) {
        log.error("Could not retreive support case in OpenCasesWidget: " + e.getMessage());
    }
}

(Ideally this will get refactored soon to allow for more or less than 3 severities instead of being hard-coded. But it will work for now.)

The CaseComparator() orders all the currently open cases by their priority in the database. If nothing has yet been set, it will be put in the order that the cases were created.

The fancy effects

The cases are now sent to the template, where they are displayed in their respective severity grouping and automatically hooked into the Javascript functions that allow the up/down buttons to work. When you click on one of the buttons the following Javascript magic happens:

1. References to the required objects on the screen are loaded up using Javascript:

var moveUp = function(e, type) {
    Event.stop(e);
    var ansc = this.up(".case-field");
    if(ansc != undefined) {
        ansc.previous().insert({before: ansc});
        updateHiddenField(ansc, ansc.next());
    }
    updateOrderingAnchors(type);
}

2. A hidden priority field for each case is updated with the new ordering value:

var updateHiddenField = function(element, newElement) {
    var temp = element.select(".case-priority")[0].value;
    element.select(".case-priority")[0].value = newElement.select(".case-priority")[0].value;
    newElement.select(".case-priority")[0].value = temp;
}

3. The ordering of the case above (or below if the down arrow was pressed) will be swapped on screen and the list rebuilt:

var updateOrderingAnchors = function(type) {
    if(type == "1") {
        var elms = $("sev1-case-list-body").select("tr");
    }else if(type == "2") {
        var elms = $("sev2-case-list-body").select("tr");
    }else{
        var elms = $("sev3-case-list-body").select("tr");
    }
    elms.each(function(tr, i) {
        var anchors = tr.select(".field-moveup")[0];
        if (i <= 0) {
            anchors.update("<span class='move-up-disabled'>move up</span>");
        }
        else {
            anchors.update(new Element("a", {"class": "anchor-move-up", href: "#"}).update("move up"));
        }
        anchors = tr.select(".field-movedown")[0];
        if (i == elms.length - 1) {
            anchors.update("<span class='move-down-disabled'>move down</span>");
        }
        else {
            anchors.update(new Element("a", {"class": "anchor-move-down", href: "#"}).update("move down"));
        }
    });
    bindAnchors();
}

4. Now that the ordering is complete, you click the Save Settings button which makes a call to this Javascript to call a DWR method and display the nice notification at the top of the widget:

CasePriorityAction.setPriorities( values, {
    callback:function() {
        $('save-button').enable();
        $('jive-success-box').style.display = "block";
        Effect.Fade($('jive-success-box'),{delay: 3, duration: 5});
    }
});

Saving the data

The final step involves saving this to the database, which is done by the call to the setPriorities DWR method as noted above. This loops through all the cases on the screen and sets the priorities in the database accordingly:

public void setPriorities(List<String> values) {
    try {
        for(String value : values){
            String[] vars = value.split("-");
            SupportCase supportCase = supportCaseManager.getSupportCase(Long.parseLong(vars[1]));
            supportCase.setPriority(vars[2]);
            
            supportCaseManager.updateSupportCase(supportCase);
        }
    }
    catch (NotFoundException e) {
        log.error("Could not retreive case in CasePriorityAction: " + e.getMessage());
    }
}

I hope this information provides you with interesting insight into how our custom development allows us to work smarter and more efficiently with all our customers. We want these new features to enrich your Jive experience!

As always, Jive welcomes any and all feedback about this feature and the Supportal in general. Please comment on this post or start a discussion in our Supportal Feedback space.

Enhancing the customer support experience with the Jive SBS Content Type Framework (CTF)

communities@jivesoftware.com — Thu, 14 May 2009 17:46:35 GMT

Introducing the CTF

When Jive SBS released this March with the newly developed Content Type Framework (CTF), it unlocked a world of limitless possibilities. Perhaps one of the greatest (and most overlooked) features in the Jive SBS 3.0 release, the CTF allows business owners the ability to dream big without taking a big hit to the wallet by providing developers with simple, easy-to-use hooks for creating new content types like events, ideas, forms and more. Customizations that would have previously taken several months or longer can be condensed into far shorter development cycles and can now all be done inside of a plugin. This has the added benefit of reducing long-term cost of ownership, as it ensures developers will be insulated from core product changes, making upgrades and patch release updates a breeze.

Naturally, given all of the benefits of the framework, we couldn't resist taking advantage of it ourselves! In the latest release of the Supportal we introduced a new customer environment tracking feature built on top of the CTF that we hope will shape our customer support experience in the months and years to come.

What is a customer environment?

Simply put, it is a collection of structured data that gives Support details on your setup, e.g., which version of the product you are using, the database you're hooked up to, and special configuration options that you use. When published, they look similar to a document:

Because the environment form is built on top of the CTF, commenting, tagging, search and other extras are all features that essentially come along for free. The editing experience is just like a regular form:

Once an environment has been created, you'll want to use it when creating new cases in the Supportal:

Why should I create an environment?

I'm glad you asked! Well, first off, if you're an Enterprise SaaS customer, we already have you covered, so no need to worry. Jive Support will create an environment document for you with the correct details and name it clearly so you know which one to use when creating new support cases. If you're hosting the software internally, consider these benefits:

Faster Response Times
Once you fill out an environment, we'll never again have to ask you which version you're running on or what Java options you're using! Less back and forth with our Support Engineers means less time spent gathering details and more time on fixing problems and answering questions. Plus, if you have multiple environments that you manage, the environment tracking feature clarifies which one your case pertains to for both your colleagues and our support team.
Transparency
We're all about keeping people in the loop and environment tracking does just that. If your system admin goes on vacation, you won't be struggling to find the information you need to help our Support team resolve the problem. Plus, if a technical person needs to come up to speed on a case you have submitted, all of the details are available in one central place.
Improved Customer Support in the Future
When you associate an environment to your case, you're helping us build a repository of information that enables us to identify areas of collective strength and weakness. Environment tracking opens the door for advanced reporting capabilities that were previously impossible or very difficult at the least. It also allows us to make better decisions about the direction of the product.

Is my data safe?

When you create an environment, it will only be visible within your secure customer space in the Supportal, so only those with access to your secure space will be able to see the information, even if your case is made public. And we're not evil, so we'll never share your data with third parties. Your data is safe with us!

Now, after all this, if you still have concerns about creating an environment to associate with your next case, please let us know why! We're hope you're happy with our constant improvements to our Support tool and invite all feedback, either on this blog post or in our Support Feedback space.

Thanks and enjoy!

Additional Reading

If you're still reading, you must be a developer saying "I'm excited about creating my own custom content type! Where do I start?" For a deeper look at custom content types, start here. After you have browsed through the documentation, download the example memo content type plugin from our public plugins SVN repository:

https://svn.jivesoftware.com/svn/dev/repos/jive/plugins/memo-type-example/trunk/

The memo custom content type is a simple example that demonstrates the power of the Content Type Framework. Check it out and start playing!

Jivespace & Supportal get an upgrade!

communities@jivesoftware.com — Fri, 17 Apr 2009 17:24:20 GMT

Welcome to Jive SBS! We just upgraded our Jivespace community to SBS 3.0.1, and along with it upgraded the Supportal customization, adding a few new features and improvements.

If you see any issues, please post a discussion in our Supportal Feedback space or create a public case there, and we'll get it addressed quickly.

Now, on to the new features:

An updated Open Cases widget allows prioritizing by the customer

We previously allowed you to view your open cases, but sometimes when you have a few open cases it can be helpful to rank them in importance--both for you and your company, but for us as well. Have a look at it here, and it will automatically be in your account's secure space next time you log in!

Account Member Management falls into the hands of the Customer

Prior to this Supportal upgrade, if you wanted to add or remove someone from your secure space, you needed to ask Support to do so. Well, with the upgraded Supportal, you can now put this power into the hands of someone that is currently a part of your account. There is still one manual step, asking Support to appoint one of your users as 'user admin' for your account. Once designated, the user admin can add and remove users, as well as add/remove the admin privilege should that assignment need to change. You can see the link to manage account members on the Group Membership Widget on your secure space overview. Don't see it? Ask Support to add it to your account space today!

First integrated Environment tracking on cases

Are you tired of Support continually asking what version you're running, or similar questions? Well, we're tired of asking it too ! We've now taken the first step to associating Environments to each and every one of your cases. That way, if the version does matter, we can simply take a look at the environment you have associated with the case and dive right into troubleshooting. What's the catch? We are going to need you to keep these as current as possible in order to make this all work smoothly. We are hoping to evolve this to be able to eliminate the Product drop down and solely use Environments in the future. We welcome your feedback and help in shaping this new feature in the Supportal. Please visit our Supportal Feedback space to do this.

Lastly, some new UI when creating a case

As you can see from the screenshot above, we've added some indication of what fields are required when creating a new case, and something you may also not notice is that we have taken away the 'Stage' detail as it was not useful to us.

Again, please let us know if you see any issues, and we hope you enjoy the new Supportal and the overall upgrade to SBS!

More Details on the Jive 3.0 Platform

communities@jivesoftware.com — Sat, 04 Apr 2009 01:00:49 GMT

We got a lot of good feedback from customers when we announced the 3.0 builds and platform changes. As a result, we've added back support for the MySQL and SQLServer databases. I'd like to take a minute to address some of the feedback and explain some of the background for this move.

As background, we've changed the way we package and ship our software. I just published an in-depth look at the benefits of this move - a good read if you're looking to understand more.

The package we've built is available on Linux and Solaris and runs on the following databases: MySQL, Postgres, Oracle, and MS SQLServer. The application itself is available as an installable package and bundles an application server, Java runtime, the app itself, and a set of optimized preconfigurations (example: tuned JVM settings).

Why make this move? A number of reasons. We talk to customers often and the consistent number one priorities are performance, scalability, stability, and the support experience. We get a lot of great feature and improvement ideas but those top priorities are the air customers breathe. Based on that, we try to move the needle in these areas significantly for each release. For example, for the 2.5 release we managed a 40% performance improvement overall. In 3.0 the numbers aren't quite as dramatic but we've added new features and performance has not suffered. As we looked up and down our architecture it became clear that some new thinking was needed.

The application has evolved past the point where it can be distributed as a standalone WAR file (however, to be clear - a WAR does still exist in the bundle). The context in which it runs is vitally important, especially for things like performance but also for features. We need the ability to depend on the environment we run in and there is a lot of variance in server-side Java deployments.

On the support side, we've seen too many misconfigurations in the environment. For example, sometimes we see issues where a customer is unable to change the parameters of the VM either to allocate more heap memory or to change the GC settings - these kinds of things are vitally important to the Jive app. Another big challenge is just access to the right log/debug files - none of this is consistent among appservers. Also, oftentimes the best information is a Java heap dump and we've seen the ability to get that information be a real challenge. In the new package, we've distributed a script that grabs every relevant log file and heap dump and zips it up in a way that can easily be sent to our support team. We feel this will dramatically improve the time-to-resolve issues.

What doesn't change? It's important to note that development, customizations, plugins, themes, etc don't change in at all. For example, how you deploy a plugin is exactly the same. Clustering also works in the same way. This is not an appliance, nor is it a black box. (Note, an appliance is something we'd consider as an option for future deployments - let us know if you have feedback on this approach).

We believe there are a lot of benefits to this approach. Ultimately, this foundation will allow us to develop some very unique features while delivering continued huge performance and scalability gains. We definitely recognize some customers will have problems migrating to this platform and we're more than willing to make it work for you - just let us know.

(One final note: within a week we will announce when the extra database support will be available.)

If you have questions, comment on this post or feel free to drop me a line at bill@jivesoftware.com.