Upgrading XML files for version 1.11-JX or later

How to upgrade

As explained in PCP-396, versions 1.11-JX or later will refuse to import files exported by earlier versions of the plugin. The reason is preventing possible errors as the meaning of references to users within the XML files are different, due to the change introduced by PCP-396. XML files exported by older versions reference users internally by their key, but XML configuracion files exported by version 1.11-JX or later, reference users internally by their username.

If necessary, a XML file generated by earlier versions can be upgraded automatically to work with version 1.11-JX or later, just follow these steps:

  1. Download this XSLT file

2. Process the older XML configuration file with this XSLT. The result will be an XML configuration file valid for version 1.11-JX or later. This can be done with any XSLT processor. For example, with open source SAXON-HE XSLT processor by Saxonica Limited, you would run this command line:

java -cp saxon9he.jar net.sf.saxon.Transform original-file.xml UpgradeXMLConfigFilesToV_1-11.xslt > upgraded-file.xml

Some notes on the upgrade process

The upgrade process does two things:

  • It adds a version attribute to the root element in the XML file, which is used by Project Configurator to identify the file as generated by version 1.11-JX or later of the plugin.
  • Wherever it finds a reference to a user, it will try to lookup in the user section of the XML file a user with that key and obtain its username. The reference will be replaced by the username. If a user with that key cannot be found in the user section of the XML file, the reference will be left unchanged and a warning will be issued:
WARNING: Cannot find name for user with key XXXX. Its key will be left unchanged

This situation will happen if the original XML file was exported with the option to avoid the export of some or all users. In these cases, the upgrade process might leave some references to user keys that do not coincide with the corresponding user name, so it might be a safer alternative to repeat the export with the new version of the plugin, instead of upgrading the old XML file.