Installation Managenent

The Installation Management is targeted to plugin developers, which have to modify JIRA's resources or add resources in JIRA's directories, for different environments or for different JIRA releases.

Two features are provided :

  • Item Deployment to install a new file in the JIRA folders
  • Item Update to modify a file in the JIRA folders
These features are possible through a new ModuleDescriptor : InstallableItemsModuleDescriptor.

InstallableItemsModuleDescriptor Integration

To allow a such integration, Minyaa Core provides an extension of ModuleDescriptorFactory of JIRA. It is done by the MinyaaModuleDescriptorFactoryExtender.

Without a Plugin dependency mechanism, normally provided by JIRA 4.0, to be usable in a new plugin, a similar extension has to be done.

Proceed as follow :

  • Create a new ModuleDescriptorFactoryExtender :

    package com.atlassian.jira.plugin;
/**
 * @FQCN com.company.jira.plugin.MyPluginModuleDescriptorFactoryExtender
 */
public class MyPluginModuleDescriptorFactoryExtender extends MinyaaModuleDescriptorFactoryExtender {
}


  • Declare it in the top of atlassian-plugin.xml :

    <component key="MyPluginModuleDescriptorFactoryExtender" name="MyPluginModuleDescriptorFactoryExtender" class="com.atlassian.jira.plugin.MyPluginModuleDescriptorFactoryExtender" />


  • At this step, you are able to implement a InstallableItemsModuleDescriptor in your plugin.

    <installable-items key="moduleKey" name="moduleName" class="com.atlassian.jira.plugin.configuration.installer.PluginItemXXXXXXX">
	<description key="moduleDescription">List of Files to install into the current JIRA instance.</description>
	<resource type="velocity" name="view" location="secure/admin/plugins/installer/ViewXXXXXXItems.vm" />
	<resource type="i18n" name="i18n" location="com.atlassian.jira.plugin.installer.PluginItemInstaller" />
	<items>
		<condition class="com.atlassian.jira.plugin.webfragment.conditions.AnyCondition" />
		<items ...>
			<item  ... />
		</items>
	</items>
</installable-items>


  • PluginItemXXXXXXX (inplementation of com.atlassian.jira.plugin.configuration.installer.PluginItemInstaller), ViewXXXXXXItems.vm and items will depend on the type of Installation : Deployment or Update !

Items and Item Descriptors

The XML format for items and item is as follow : 
<items>
	<condition class="com.atlassian.jira.plugin.webfragment.conditions.AnyCondition" />
	<items >
		<items srcLocation="edit-webapp/" destLocation="../../" >
			<item location="relativePath/file.jsp" />
			<item location="relativePath/file.xml" />
			<items >
				<condition class="com.atlassian.jira.plugin.webfragment.conditions.AnyCondition" />
				<item location="relativePath/conditionedFile.xml" />
			</items>
		</items>
		<items srcLocation="edit-webapp/" destLocation="../../" >
			<condition class="com.atlassian.jira.plugin.webfragment.conditions.AnyCondition" />
			<item location="relativePath/conditionedFile.xml" />
		</items>
		<items destLocation="../../" >
			<condition class="com.atlassian.jira.plugin.webfragment.conditions.JiraBuildCondition">
				<param name="jiraMinBuild">3.13.3</param>
			</condition>
			<item replacementProperties="install/replacement.minyaa.core.properties" />
		</items>
	</items>
</items>


  • Each <Items> node contains n <Item> nodes,
  • Only one <condition> is defined per <Items> node, and is applicable to all <Item> nodes,
  • srcLocation is the path to consider in the classpath, normally a path in the jar file of the plugin,
  • destLocation is the destination root folder where files have to be copied. It is a path relative to the WEB-INF/classes folder.
  • srcLocation and destLocation may be overridden in <Item> nodes,
  • location is the path to append to srcLocation and destLocation to build source Path and destination Path.
  • replacementProperties is the path to the Properties File for Replacement.
  • Item Deployment supports srcLocation, destLocation and location,
  • Item Update supports destLocation and replacementProperties

Replacement Properties File Format

This Format may be described as follow ... 
# List of ReplacementSet keys (comma separated) 
replacementSets=<set1>[,<set2>]

# 1st Set 
<set1>.filePath=<Relative File Path needing Replacement>
<set1>.<tokenSet1>=<tokenSet1>[,<tokenSet2>]
<set1>.<tokenSet1>.if.not.exist=<searchedToken blocking the replacement if found>
<set1>.<tokenSet1>.if.exist=<searchedToken required to allow the replacement>
<set1>.<tokenSet1>.token=<tokenToReplace>
<set1>.<tokenSet1>.value=<replacingValue>


Item Deployment

In case of deployment, the PluginItemXXXXXXX will have to be assumed by PluginItemDeployer and ViewXXXXXXItems.vm by ViewInstallableItems.vm

The declaration will be similar to : 
<installable-items key="myDeploymentKey" name="My Deployment" class="com.atlassian.jira.plugin.configuration.installer.PluginItemDeployer">
	<description key="myDeployment.description">List of Files to install into the current JIRA instance.</description>
	<resource type="velocity" name="view" location="secure/admin/plugins/installer/ViewInstallableItems.vm" />
	<resource type="i18n" name="i18n" location="com.atlassian.jira.plugin.installer.PluginItemInstaller" />
	<items>
		<condition class="com.atlassian.jira.plugin.webfragment.conditions.EnterpriseJiraLicenseCondition" />
		<items srcLocation="edit-webapp/" destLocation="../../">
			<item location="includes/panels/project/plugin.schemes.jsp" />
			<item location="template/standard/usergroupsselect.jsp" />
			<item location="template/standard/usergroupsselectnoheaders.jsp" />
		</items>
	</items>
</installable-items>
The XML format for items and item is as follow :
  • srcLocation is the path to consider in the classpath, normally a path in the jar file of the plugin,
  • destLocation is the destination root folder where files have to be copied. It is a path relative to the WEB-INF/classes folder.
  • location is the path to append to srcLocation and destLocation to build Source Path and Destination Path.
In above sample, the file edit-webapp/includes/panels/project/plugin.schemes.jsp will be copied to atlassian-jira/WEB-INF/classes/../../includes/panels/project/plugin.schemes.jsp.

Item Update

In case of Update, the PluginItemXXXXXXX will have to be assumed by PluginItemUpdater and ViewXXXXXXItems.vm by ViewReplacableItems.vm

The declaration will similar as folow : 
<installable-items key="modifiedFiles" name="Modified Files" class="com.atlassian.jira.plugin.configuration.installer.PluginItemUpdater">
	<description key="modifiedFiles.description">List of Files to modify/overwrite into the current JIRA instance.</description>
	<resource type="velocity" name="view" location="secure/admin/plugins/installer/ViewReplacableItems.vm" />
	<resource type="i18n" name="i18n" location="com.atlassian.jira.plugin.installer.PluginItemInstaller" />
	<items destLocation="../../">
		<condition class="com.atlassian.jira.plugin.webfragment.conditions.JiraBuildCondition">
			<param name="jiraMinBuild">3.13.3</param>
		</condition>
		<item replacementProperties="install/replacement.minyaa.core.properties" />
	</items>
	<items >
		<condition class="com.atlassian.jira.plugin.webfragment.conditions.EnterpriseJiraLicenseCondition" />
		<items srcLocation="edit-webapp/" destLocation="../../" >
			<item location="includes/panels/extendedobjectconfiguration_form.jsp" />
		</items>
		<items srcLocation="edit-webapp/WEB-INF/classes/" destLocation="" >
			<item location="entitydefs/entitymodel.minyaa.time.xml" />
		</items>
	</items>
</installable-items>
The XML format for items and item is as follow :
  • srcLocation is the path to consider in the classpath, normally a path in the jar file of the plugin,
  • destLocation is the destination root folder where files have to be copied. It is a path relative to the WEB-INF/classes folder.
  • location is the path to append to srcLocation and destLocation to build Source Path and Destination Path.
In above sample, the file edit-webapp/includes/panels/project/plugin.schemes.jsp will be copied to atlassian-jira/WEB-INF/classes/../../includes/panels/project/plugin.schemes.jsp.