Updating a plugin – the upgrade.xml file

When updating a plugin, the update process that the uDeploy server goes through is to scan every process that has been created on the server (component and generic) and upgrade any step that is provided by the plugin that you are upgrading.  The upgrade.xml file tells the uDeploy server how to update a step or a property.

update

Included at the bottom is the XSD file that defines the upgrade.xml file.

1.  Update a script – if there are no changes to the plugin.xml file (no API changes) but you simply want to update one of the scripts that are run that implement the logic of a step, no change is required to any of the plugin configuration files.  You can simply reload the plugin zip file and the scripts will be replaced.
Note:  Probably not a good practice to follow.  If you are updating your “official” plugin, update the revision number.

2. Propagating a step to the next version – any time you upgrade a plugin, you must include a <migrate-command> element for every step that you want to include in the new version.

<migrate to-version="7">
    <migrate-command name="Step Name"/>
</migrate>

3.  Deleting a step – if you want to delete a step, then simply don’t include a <migrate-command> element for that step.

4.  Adding a step – you don’t need to do anything in the upgrade.xml file for this new step as there is nothing to upgrade.  The process of applying the new plugin will add the new step.

5.  Rename a step – the <migrate-command> element provides a way to rename a step by including an “old” attribute.

<migrate to-version="7">
    <migrate-command name="New Step Name" old="Old Step Name"/>
</migrate>

6.  Adding a step property – there a few situations here that need to be taken into consideration.

a.  if you are adding a new property that does not have a default value, then obviously your script will have to take that into account.  In this situation, you don’t need to do anything special to the upgrade.xml file as long as you have a <migrate-command> element for the property’s step.  All existing process steps will get the new property but since there is no default value there is no need to migrate any existing properties.   If the new property is required, you will be asked to enter a value when the process is requested.

b.  If you are adding a new property that does have a default value, required or not, then you should add a <migrate-properties> element as follows.  This will insure that the properties of any existing use of the step will get migrated and the default value of the property will get assigned to the new property.  If you don’t include the <migrate-properties> element, the default value will not be applied to the property as no property migration will occur.  This will be a problem if your script assumes a default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
      <migrate-properties>
         <migrate-property name="New Property Name" default="New Property Default Value" />
      </migrate-properties>
   </migrate-command>
</migrate>

7.  Deleting a step property – nothing needs to be done in the upgrade.xml if you are deleting a step property.  The process of upgrading the plugin will remove the property as long as you have a <migrate-command> element to migrate the step.

8.  Renaming a step property – a capability similar to renaming a step exists to rename a step property using the <migrate-properties> element.

<migrate to-version="7">
   <migrate-command name="Step Name">
      <migrate-properties>
         <migrate-property name="New Property Name" old="Old Property Name" />
      </migrate-properties>
   </migrate-command>
</migrate>

9.  Changing a step property’s default value – the <migrate-property> element is also used to change its default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
      <migrate-properties>
         <migrate-property name="Property Name" default="New Default Value" />
      </migrate-properties>
   </migrate-command>
</migrate>

10.  Steps 9 and 10 can be combined if you are both renaming a property and re-defining its default value.

<migrate to-version="7">
   <migrate-command name="Step Name">
      <migrate-properties>
         <migrate-property name="New Property Name" old="Old Property Name" default="New Default Value" />
      </migrate-properties>
   </migrate-command>
</migrate>

update.xsd.docx

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s