Technical Guide Reference Guide Frequently Asked Questions Tutorials
Show menu

Release 4.3 Namespace Migration Notes

Release 4.3 Migration Notes

As part of modernizing our code we are moving parts of the agent code and associated resources from old namespaces to new namespaces in release 4.3. This has a direct impact on the backward compatibility of interface bundles.

For this reason, ConnectPlaza customers need to migrate their interfaces to the new namespace. Most of the time this will only mean that interfaces have to be rebuilt via the ConnectPlaza Constructor. This document describes the necessary actions to take.

What actions, if any, should a ConnectPlaza customer take?

Before discussing any necessary steps a customer should take, we need to give a quick overview of where ConnectPlaza stores interfaces and bundles:

  1. When creating a new interface or loading an old interface in ConnectPlaza Constructor, Constructor stores and retrieves information from the Constructor database. This database contains all the information that goes into interfaces such as the configuration of individual components and flows as well as additional resources such as JS scripts, Java bean definitions and JARs.
  2. When you bundle an interface in Constructor and create a release or snapshot version, the resulting bundle goes to the interface bundle store. This interface bundle contains all the configuration and resources that were in the interface at the time of bundling.
  3. Once a bundle is present in the interface bundle store, it is visible in Deploy and ready to be deployed to an agent.
  4. Deploying a bundle means sending it to a ConnectAgent. The deployed bundles are stored in the adapters directory of the agent. Bundles can reference resources outside of the bundle itself. A common location for shared custom Java code is the jars/endorsed directory. Of course, due to the flexible nature of interfaces any resources on the agent host system can be referenced.

We will now go over each of these resources and resource locations in order to outline what changes in the 4.3 release.

Impact on an existing agent with installed interface bundles

To make the inconvenience as small as possible and to avoid breaking interface bundles after the update, the 4.3 agent will automatically migrate already installed interface bundles when the agent is restarted or when bundles (made prior to the 4.3 release) are deployed in an already running agent. This prevents customers from experiencing problems with their installed interface bundles. This migration process converts installed interface bundles and stores them in the new format in the adapter folder of your agent. The migration will therefore only happen once.

The following resources in a bundle are automatically migrated:

  • Configuration generated by Constructor, i.e. component, flow and interface configuration.
  • JS scripts
  • XML files
  • Bundled JAR files with the limitation that if such a JAR file contains other embedded JAR files, these embedded JARs are not migrated

Every interface bundle that is automatically migrated will write a migration report which will also contain information about what the client should do to make this interface 4.3 compliant. These reports can be found under the Agent Updates tab in the ConnectPlaza Deploy front end.

Bundles that are present in the interface bundle store are not automatically migrated. However, if a customer deploys an old bundle (i.e. build before version 4.3) to a 4.3 agent, it will trigger the above outlined automatic migration process and should work automatically.

The automatic migration process does not apply to bundles created after the 4.3 release. These include a tag that excludes them from the automatic migration process. New interfaces or updated interfaces built via ConnectPlaza Constructor 4.3 must conform to the new migrated source code. What this means will be explained further on. 

Custom jar files in the jars/endorsed directory will be automatically migrated. A backup of the original jar file will exist in this directory if a jar file is migrated. Customers are strongly advised to rebuild their custom jars in the endorsed directory with the new 4.3 dependencies from ConnectAgent.

Resources referenced by bundles that are either not in the bundles themselves or not in the jars/endorsed directory are not automatically migrated.

Impact on the interface configuration in the Constructor database

Certain resources in the Constructor Database are automatically migrated at the 4.3 release. This means that if a customer opens an interface after the 4.3 release, some of its configuration might have changed. The following sections outline which resources are migrated and which might require manual intervention.

Component Configuration

The migration only affects how component configuration is stored in bundles and not existing configuration in Constructor. This means that no further action is required.

One possible exception, is when a component directly references an old opdion agent property. These properties are not automatically migrated and should be manually renamed.

Scripts

If an interface includes JS scripts, these will be automatically migrated at the 4.3 release. This means that if an old script contains a relevant reference to com.opdion.myesb this will be replaced with com.connectplaza.

Note that new scripts should no longer use classes from the com.opdion.myesb package but should use packages from com.connectplaza.

For example:

var cmFact= Java.type("com.opdion.myesb.eaf.pojo.impl.ConnectMessageFactoryImpl");

must be changed to:

var cmFact= Java.type("com.connectplaza.eaf.pojo.impl.ConnectMessageFactoryImpl");

Sometimes predefined properties or headers are used in scripts like opdion.logging.message_correlation_id. These predefined properties were also renamed and should be renamed in scripts accordingly.

Bean definitions

If an interface includes bean definitions, these will be automatically migrated at the 4.3 release. This means that if an old bean definition contains a relevant reference to com.opdion.myesb this will be replaced with com.connectplaza.

Custom JARS

Custom JARs in the Constructor database are not automatically migrated. 

If the JAR is dependent on ConnectPlaza libraries, customers should update their source code by linking with the new 4.3 ConnectAgent dependencies. After building a new version of the library replace the resource in your interface, rebuild the interface via ConnectPlaza Constructor and deploy.

Note that updating the source code involves updating the ConnectPlaza dependencies in the POM file of the project. An IDE, such as Eclipse or IntelliJ, can help remove the old imports and replace them with the new ones.

Other resources

All other resources that can be bundled with an interface such as WSDL files, XSD files, and other types of files, are automatically migrated. Note that preliminary scans of the Constructor database have shown that none of these types of files need to be migrated, i.e. they do not contain old ConnectPlaza namespaces.

Impact on the interface bundle store

None of the bundles in the interface bundle store are automatically migrated. However, if an old bundle is deployed to a 4.3 agent, this bundle will then be automatically migrated according to the process outlined above. Note that this does not affect the version of the bundle in the bundle store, this process is purely on the ConnectAgent side.

FAQ

What should you do if an interface bundle does not work after update 4.3?

The first thing you should try is to rebuild the interface in Constructor and then re-deploy the new bundle to the agent.

If the problem persists, or if you are not able to rebuild the interface in Constructor, send a mail to support@connectplaza.com and include the following files (replace <interface-name> with the name of the interface that caused the error):

  1. The report created during the automatic migration process located in the <agent install directory>/.data/update/reports directory and named <interface-name>.txt.
  2. The following log files: wrapper-updater.log, connectplaza-agent.log and <interface-name>.log. Note that these log files are located in the <agent install directory>/logs directory.

Can you deploy a newly made (after 4.3 release ) bundle to an older agent?

No, this is not possible. The namespace migration is incompatible with older agents. If you want to run a newly build bundle, you will have to update your agent to 4.3.

Can you deploy an old (before 4.3 release) bundle to an older agent?

Yes, the bundles in the interface bundle store remain the same.