Upgrading plug-ins

The upgrade.xml file tells the server how to update a step or a property. The server scans every process that has been created on the server and upgrades the steps that you are upgrading.

To upgrade a plug-in, do the following:

Increment the number of the version attribute of the <identifier> element in plugin.xml.
Create a <migrate> element in upgrade.xml with a to-version attribute that contains the new number.
Place the property and step-type elements that match the updated plugin.xml file within the <migrate> element, as shown in the following example.

Considerations

Use the <migrate-command> element to upgrade steps.

Upgrades to scripts and files for a step do not require changes to the upgrade.xml file. However, updating the version number in the upgrade.xml file is a good practice. For script changes to take affect, load the plug-in again.
Keep a step by including a <migrate-command> element for each step to remain in the plug-in.
```
<migrate to-version="3">
    <migrate-command name="step_name"/>
</migrate>
```
Add a new step does not require changes to the upgrade.xml file. Again, the version number of the plug-in should be updated.
Delete a step by not including a <migrate-command> element for the steps to be removed from the plug-in.

Rename a step by coding both the old and new name of the step using the name and old attributes.

<migrate to-version="3">
    <migrate-command name="new_step_name" old="old_step_name"/>
</migrate>

Use the <migrate-properties> elements to upgrade step properties.

Delete a step property by using the <remove-property> element within the <remove-properties> element for the step with the removed property.

<migrate to-version="3">
    <migrate-command name="step_name" 
        <remove-properties>
          <remove-property name="old_property_name" />
        </remove-properties>
   </migrate-command>
</migrate>

Rename a step property by using the name and old attributes on the <migrate-property> element within the <migrate-properties> element for the step with the changed property.

<migrate to-version="3">
    <migrate-command name="step_name" 
        <migrate-properties>
          <migrate-property name="new_property_name" old="old_property_name />
        </migrate-properties>
   </migrate-command>
</migrate>

Change the default value for a step property by using the default attribute on the <migrate-property> element.

        <migrate-properties>
          <migrate-property name="new_property_name" old="old_property_name default="new_default_value" />
        </migrate-properties>
   </migrate-command>
</migrate>

Example

<?xml version="1.0" encoding="UTF-8"?>
<plugin-upgrade
        xmlns="http://www.&company;.com/UpgradeXMLSchema_v1"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <migrate to-version="3">
    <migrate-command name="Run SQLPlus script">
      <migrate-properties>
        <migrate-property name="sqlFiles" old="sqlFile"/>
      </migrate-properties>
      <remove-properties>
        <remove-property name="jvmProperties"/>
      </remove-properties>
    </migrate-command>
  </migrate>
  <migrate to-version="4">
    <migrate-command name="Run SQLPlus script" />
  </migrate>
  <migrate to-version="5">
    <migrate-command name="Run SQLPlus script" />
  </migrate>
</plugin-upgrade>

You can also make a script-only upgrade, that is, an upgrade that contains changes to the step's associated scripts and files but does not change plugin.xml. This mechanism can be useful for plug-in development and for minor bug-fixes/updates.