Importing Extensions
An extension is a zip archive consisting of extension files and a metadata file. To install the contents of an extension into ThingWorx, you need to import the zip file. You can import multiple extensions at the same time by packaging all of the extension zip files together into one zip folder.
Enabling Extension Import
Extension import is disabled by default for all users, but can be enabled by configuring the platform-settings.json file:
1. Open the platform-settings.json file. By default, the file is located in the ThingworxPlatform folder.
2. Add or update the following ExtensionPackageImportPolicy parameters to true to allow extensions to be imported. See section below for best practices on configuration.
All parameters are false by default. Reference platform-settings.json for more information on each parameter.
"ExtensionPackageImportPolicy": {
"importEnabled": false,
"allowJarResources": false,
"allowJavascriptResources": false,
"allowCSSResources": false,
"allowJSONResources": false,
"allowWebAppResources": false,
"allowEntities": false,
"allowExtensibleEntities": false
3. Save and close the platform-settings.json file.
Best Practices for Controlling Extension Import
Take an iterative approach when configuring the parameters in the ExtensionPackageImportPolicy to enable the minimal number of parameters to control extension imports. All parameters are false by default.
1. Set the importEnabled parameter to true and import your extension.
2. If the import fails, set the allowEntities parameter to true and import your extension.
3. If the import fails, set the allowExtensibleEntites parameter to true and import your extension.
4. If the import fails, set the applicable allow<Content>Resources parameter(s) (for example, allowJarResources). Resources are specified in the extension's metadata.xml file.
5. After successful import, change all the parameters back to false.
6. Restart the platform to disable any extensions from being imported.
Importing an Extension
To import an extension, follow the steps below:
1. From Composer, click Import/Export > Import.
2. From the Import Option drop-down list, select Extension.
3. Browse your local directory to select an extension zip file, and then click Open.
4. Click Validate, and then click Import.
5. Click Close to close the Import dialog box.
The imported extension files are displayed on the dashboard.
Versioning Extensions
Using the dependsOn attribute of the ExtensionPackage element, you can specify comma-separated name-version pairs for extensions. The format is name:major release number.minor release number.patch number (for example, ExtensionA:1.0.0), which is used in dependency checking.
Upgrading Java-backed Extensions
When you attempt to upgrade a Java-backed extension by importing a new version, an information message displays, stating that you must restart the platform. When this occurs, the extension zip file is placed in a queue: /ThingworxStorage/extensions/upgradequeue. After you restart the Apache Tomcat server, ThingWorx will try to import the extension zip files in the queue. If a queued extension import fails, you must restart the server again to revert to the previous version of the extension. After ThingWorx attempts to import queued extensions, the queue is cleared, even if a queued extension import fails.
You do not have to restart after each import of a Java-backed extension. Multiple extensions can be queued for import and then will be imported in the appropriate order based on their dependencies after a single restart. See the Extension Development Guide for more information on setting up dependencies.
Non-Java extensions will typically import without requiring any restarts. However, there are exceptions with the following scenarios:
If a non-Java extension is part of a zip of zip files that contains a Java extension that is being upgraded, the entire zip of zips will be queued and imported after restart.
If a non-Java extension is being imported (for initial install or upgrade) and it depends on an extension that is queued for upgrade, the non-Java extension will also be queued.
Common Extension Import Result Messages
The following information messages and warnings are common during extension imports:
Info: Extension <extension-name> is queued for installation on the next server restart because it contains JAR files, and an older version of this extension is already installed.
Anytime you import an extension with a JAR in it, you will get this message stating that you need to restart the server to complete the import.
Warning: Extension <extension-name> skipped because it is already installed.
Warning: Extension Package <extension-name> may be trying to change the template of the following Entities: <entity: entity-name>
ThingWorx does not support changing the base Thing Template of an entity. This warning occurs during extension imports when the reported Thing Template cannot be inspected to determine if its base Thing Template has been changed or not.
After Restarting the Platform
After restarting, check the application logs to ensure the queued extensions are imported successfully. You should see the following in the application log for each queued extension being imported:
Starting entity import of /ThingworxStorage/extensions/XSS_Test/metadata.xml
The following message will be displayed if the queued import(s) completed successfully:
*** Import completed successfully
The following errors will be displayed if there were issues:
Error occurred while installing Extensions from upgrade queue
If issues caused the queued import to fail, restart the system again to revert back to the previous extension versions.
Analyzing Extension Import Failure Messages
If your extension import fails, you will receive messages in the Application Log that generically state that the “extension import failed” and references the Error Log for more details. In the ErrorLog.log file, at the end of the error message that occurred for your import failure, the reason why the extension package you imported failed is stated. Examples for failure are import disabled, jar import not allowed, and so on. Use this error to help you adjust the appropriate configuration settings to successfully install your extension.
Log Message
Verify Parameter Configuration in ExtensionPackageImportPolicy
ExtensionPackage upload attempted while import disabled
"importEnabled": true
ExtensionPackage<XYZ> upload attempted while allow jars is disabled
"allowJarResources": true
ExtensionPackage<XYZ> upload attempted while allow Javascript is disabled
"allowJavascriptResources": true
ExtensionPackage<XYZ> upload attempted while allow CSS is disabled
"allowCSSResources": true
ExtensionPackage<XYZ> upload attempted while allow JSON is disabled
"allowJSONResources": true
ExtensionPackage<XYZ> upload attempted while allow WebApp is disabled
"allowWebAppResources": true
ExtensionPackage<XYZ> upload attempted while allow entities is disabled
"allowEntities": true
ExtensionPackage<XYZ> upload attempted while allow extensible entities is disabled
"allowExtensibleEntities": true
Was this helpful?