Upgrading the eMessage Connector from v.1.2.7 to v.1.3.1/v.1.3.2
Upgrade instructions for the eMessage Connector to upgrade it from v.1.2.7 to v.1.3.1 or to v.1.3.2 are exactly the same. This topic combines the two upgrades, using the notation v.1.3.1/v.1.3.2 for the new version of the eMessage Connector. The sections listed below provide the procedures. Starting with "Best Practices for Upgrading", click each section title to display its content and again to hide it:
Best Practices for Upgrading
Upgrading the eMessage Connector involves installing a new instance of the Connector. Upgrading the Connector also means importing the new versions of the extensions in your ThingWorx Axeda Compatibility Package into your ThingWorx Platform. Before you begin the upgrade, here are some best practices to follow:
• Before upgrading the eMessage Connector and extensions, you need to export any entities from ThingWorx Platform that were created for use with the Connector. If you plan to upgrade the ThingWorx Platform, do that next.
• Copy any site-specific configuration values from the existing installation configuration to the new installation configuration file. Do not just copy over the existing emessage.conf file.
• After importing the Axeda Compatibility Extension into ThingWorx Platform, import your exported entities and re-run the permissions services, as explained in Setting Up Permissions and Visibility for the eMessage Connector. The required permissions are not automatically re-applied when importing your exported entities because the entities are installed as new entities, not as upgraded entities, when you are using this method of upgrading the platform.
• As needed, create any new security entities that you may need. For assistance, refer to Create Security Entities in ThingWorx for a Connector and for Remote Access.
• As a security best practice, convert any JKS keystores to PKCS #12 keystores. For assistance, refer to Converting JKS Keystores to PKCS Keystores.
Upgrading the Extensions
To upgrade the extensions using the versions provided in the Axeda Compatibility Package that contains eMessage Connector v.1.3.1/v.1.3.2 involves these steps:
1. In the running ThingWorx Platform:
a. Import the Remote Access Extension v.1.3.0 using the Import/Export menu. This extension should import without error but will indicate that you need to restart the platform for changes to take effect. Do not restart yet.
b. Import the Axeda Compatibility Extension v.3.0.45 using the Import/Export menu. This extension should import without error but will indicate that you need to restart the platform for changes to take effect.
 | The Connection Services Extension (CSE), ThingWorx Utilities Core Extension, and ThingWorx Utilities SCM extension did not change between Axeda Compatibility Package (ACP) versions 1.3.1 and v.1.4.0/v.1.4.1. If you did not upgrade the platform or you did an in-place upgrade, you do not need to import them again. If you did a fresh install of the platform, you do need to import them. As for the other extensions, use the Import/Export menu to import them. |
2. Restart the ThingWorx Platform.
Once the ThingWorx Platform has restarted, you are ready to install the eMessage Connector, v.1.3.1/v.1.3.2.
Rerun the Permissions Services
Some permissions have changed between ACP v.1.3.1 and ACP v.1.4.0/v.1.4.1. To ensure the proper permissions are applied after upgrading the extensions, follow these steps:
1. In ThingWorx Composer, navigate to the eMessageServices Thing.
2. Execute the GrantEMessageConnectorPermissions service, specifying the user group and organization previously used for the eMessage Connector. For example, specify the user group and organization used for the initial setup of the Connector.
Upgrading the eMessage Connector to v.1.3.1/v.1.3.2
If you also upgraded the ThingWorx Platform, make sure that you have imported your entities back into the platform before you start the Connector upgrade.
If you are upgrading only the Connector, make sure that you imported the new versions of the Axeda Compatibility Extension and Remote Access Extension and restarted the platform before you begin the upgrade.
Follow these steps to install v.1.3.1/v.1.3.2 of the eMessage Connector:
| | When referring to the distribution zip files, emessage-connector-1.3.x.zip refers to both emessage-connector-1.3.1.zip and emessage-connector-1.3.2.zip |
1. From the directory where you extracted the ACP distribution bundle, extract the emessage-1.3.x.zip file to an appropriate location. This extraction creates an emessage-connector-1.3.x folder in that location.
2. If necessary, back up any site-specific or modified configuration files from your current eMessage Connector. For example, back up your customized emessage.conf file.
3. Copy the custom settings from your existing configuration file into the configuration file for the new eMessage Connector v.1.3.1/v.1.3.2. Do not copy an old configuration file over a new one. Instead, re-apply the same changes to the new configuration file.
4. It is strongly recommended that you encrypt the new configuration file. For details, refer to Setting Up an Encrypted Configuration File for an eMessage Connector.
5. If anything about your eMessage Connector installation has changed, such as the location of your Connector configuration file or Connector binary files, update the EMESSAGE_OPTS environment variable or your service definition to reflect those changes. Refer to Setting Environment Variables for an eMessage Connector for details.
6. Run the permission scripts that accompany the new eMessage Connector. Refer to Setting Up Permissions and Visibility for the eMessage Connector for details. Since the entities for the Connector are imported back into the ThingWorx Platform as new entities, you must run these scripts to ensure proper operation of the new eMessage Connector.
 | If this new Connector is on a new machine, whether or not you have to shut down the old Connector before you begin the upgrade depends entirely on your network configuration. For example, do you have a load balancer? Will the new Connector use the same host or IP address as the old one? Consider your network setup in terms of whether you can run the old and new Connectors simultaneously. If not, shut down the old Connector first. If you have multiple Connectors running behind a load balancer, bring up the new one, add it to the load balancer, and then shut down the old one. If the new Connector is using the same host or IP address as the old one, shut the old one down first. |
Take the following steps in the order appropriate to your network setup:
◦ Shut down your old eMessage Connector.
◦ Start the new eMessage Connector. Refer to Starting the eMessage Connector and Running a Quick Test for details.
The eMessage Connector should come online and connect with your ThingWorx Platform.
8. Repeat Steps 1 through 7 for all the eMessage Connectors you are upgrading.
Verifying the Installation
To verify that the eMessage Connector is configured and running as expected, run the smoke test on the eMessage Connector, as described in the section, Running the Smoke Test.