10 Replies Latest reply on Nov 21, 2017 9:50 AM by carlesc RSS
    asinclair-2 Apprentice

    ThingWorx extension versioning requirements?

    After making some modification to restructure an extension, I tried to update the server and got the following ...

    What can and cannot be changed between versions of an extension? Are the rules documented somewhere?

    I checked the Thingworx extension development user guide (TWX 6.6) but there are no details there.

      • Re: ThingWorx extension versioning requirements?
        kmoon Apprentice

        When you upgrade an extension package from one major version to the next major version, you can get that error. To resolve this issue, try these steps below to remove the extension package and reimport.


        1. Export all entities that depend upon the extension in question
        2. Delete all entities that depend upon the extension in question
        3. Remove the extension through the Manage extensions screen under the Import/Export menu option
        4. Import the new extension through the Import/Export menu option Import

          • Re: ThingWorx extension versioning requirements?
            asinclair-2 Apprentice

            Thanks for providing a workaround, Daniel.

            In a production system, however, this procedure would cause an interruption of service, requires coordination between tenants, and incorporates some risk of losing data.


            I need an answer to my original question so I can plan enhancements to my Extensions that avoid the need to restart.

          • Re: ThingWorx extension versioning requirements?
            brue Apprentice



            Starting with ThingWorx 6.6, extensions follow a Semantic Versioning 2.0.0 like set of rules for the packageVersion number of an extension. Basically, extension versions must follow the <major>.<minor>.<patch> format where each section is a numeric value.

            • When the current extension is already installed(For example: MyExtension with a version of 2.5.3)
              • Major version differences are not allowed into the system. Major changes signify a change in an extension that is not backwards compatible. MyExtension:3.0.1 would not be allowed to be installed.
              • Minor version differences are allowed into the system only when the minor version is greater than the minor version that is installed. MyExtension:2.6.1 would be allowed to be installed.
              • Patch version differences are also allowed into the system only when the patch version is greater than the patch version that is installed. MyExtension:2.5.4 would be allowed to be installed.


            Whether you are on a production system or not, it's likely you'll need a restart of ThingWorx to get your new extension's JAR file(s) to replace the existing one(s). What you'll need to do is a "dump and pump" which is a full export and import of your current system into a new system with your new extension installed. If you incorporated a change to your extension that causes your existing entities and data to be incompatible, it's a bit more involved because you now have to transform your export before you import.

              • Re: ThingWorx extension versioning requirements?
                asinclair-2 Apprentice

                This is the kind of info I needed. Thank you, Brian.


                In my case, the old extension was version 1.0.2 and the new one was 1.1.0, which should have been okay according to the rules above. Are the other conditions associated with this error that would be checked during validation?


                I need to better understanding of what changes can cause "your existing entities and data to be incompatible." Some thing are obvious, but I suspect the devil is in the details. This is a "best practices" topic and it would be interesting to hear how people manage this.


                Thanks again.

                • Re: ThingWorx extension versioning requirements?
                  carlesc Heavyweight Champ

                  Hi Brian,


                  About Semantic Versioning, why it's that strict? can we disable the major version upgrade limitation?


                  Imagine a "not professional" developer for an extension which didn't followed the rules: they updated major version without doing significant API changes, crazy developers! You will be forced to do a "dump and pump" process when it isn't needed, and we speak with real world TW production servers that can be an hours process ( imagine a production server with about 100000 things or more... ) which on the other hand could be just a server restart?


                  Well previous case it's not an hypothetical case, the "not professional" developer it's ThingWorx with Mail Extension, and the production server it's our ( which lucky/unlucky for us we are not a 100000 things, but still a "dump and pump" it's not a desired process, as it takes too much and you lose Real Time data). I've looked at API Changes between 2.0 and 3.X and it aren't major at all, everything that we have that works on 2.0 works also on 3.X.


                  What we do now? you can decide this implementation restrictions without training your team on it and also give a clear statement on it, not just a community post when someone asks for it, as you see people doesn't gets it, neither internal people


                  Of course current workaround will be to unzip extension, change metadata information to for instance 3.X to 2.3.X and go on, but for sure professional developers doesn't like it.


                  Best Regards, Carles.