Jive Developer Blog
5 Posts tagged with the upgrade tag
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!
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!
Hello Jivespace users,
For those of you who are customers and have been using Jive's support solution (the 'Supportal'), please read on to see what changes have happened recently and how they benefit you! I will also touch on what else may have changed and how it could impact your usage (plus how to take care of it!).
If you are not a customer yet, most of this information does not apply, but it does showcase the support solution that Jive has developed and is using.
Jivespace Updated, new version of the Supportal deployed
Jivespace was updated to 2.5.5, and the Supportal plugin, which recently went a 3.5 month development cycle, was deployed last Thursday, the 18th. It was a big upgrade for the Supportal as it went under the knife and was essentially re-engineered from the ground up. It is currently developed by our very own support engineers Scott Hirdes and myself.
New Features
You will no doubt notice a few changes, but just in case you don't see them all, here is a showcase of the new features which impact the customer directly:
1. Auto Close
Cases are now going to be automatically followed up on if they are idle for more than 5 business days. This can be turned off on a per-case basis by simply choosing 'No' on the case details 'Allow this case to be auto closed' option.
2. Public Case Navigation
Have you created a public case yet? If not, please read about it here: http://www.jivesoftware.com/jivespace/docs/DOC-2932 under the section Best Uses for "Allow Case to be Public." And if you have already created a public case, did you notice that it was difficult to get back to your account community after viewing your public case? Well not anymore! If you have created a public case, you can now navigate back to it with the link at the top of the case:
3. Moving towards Account Management
You now have a couple features which let us take the first steps into account management from the Supportal. Group Membership Widget & Support Status tab.
The Group Membership Widget can be added to your account community, and it will then show the contacts from your company who have access to your company's cases. You can ask any support engineer to add this widget to your account community!
The Support Status tab is a way for you to check if you currently have support with us. If there are any problems with this, please contact us!
Those are the new features that impact you as the customer, but there are many more changes to the plugin which benefit our support engineers, and the plugin as a whole!
Change which could affect your day to day usage
We fixed some issues with our account synchronization rules, to more appropriately reflect our underlying account information. If you no longer see an account community that you believe you should have access to, please email accountsupport@jivesoftware.com.
If you see any other issues, please let me know as soon as you can!
Thanks and enjoy!
-
eric.butler@webtrends.com on Supportal 4.1.0 Features: Documentation Search, Support Focus, Sortable Columns
-
Will on Supportal 4.1.0 Features: Documentation Search, Support Focus, Sortable Columns
-
Will on Supportal 4.1.0 Features: Documentation Search, Support Focus, Sortable Columns
-
BlueMenace on Supportal 4.1.0 Features: Documentation Search, Support Focus, Sortable Columns
-
crossman on Supportal 4.1.0 Features: Documentation Search, Support Focus, Sortable Columns