Skip navigation

Jive Release Blog

2 Posts authored by: austen.rustrum Employee

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:

 

pluginError.GIF

 

Questions?

 

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

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:

 

environment_view.png

 

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:

 

environment_edit.png

 

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

 

environment_to_case.png

 

 

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!

Filter Blog

By date: By tag: