Versioning and Migration
Each of the base components andimplementations that are included out-of-the-box has a configuration version. Versions are used to keep track of the configuration JSON object, and are necessary to ensure that in the future, custom components can be migrated to new ThingWorx Navigate releases.
Versioning Details
The configuration JSON object contains two keys that track version: baseConfigurationVersion and implementationConfigurationVersion. Note that the keys are hidden in the configuration dialog box in the Mashup Builder, but are part of the configuration returned from the GetConfigurations service.
 |
To identify the configuration versions for a component, execute the following services on the component Thing:
• GetBaseConfigurationVersion, for the version of the base component
• GetImplementationConfigurationVersion, for the version of the implementation
|
Calling the Migrate Service
When creating a custom implementation for a component, you create a Thing Template that extends an existing base component or implementation. Any service in the custom implementation that calls the GetConfigurations service must first call the Migrate service.
The Migrate service has four parameters:
• migrationType– string; the type of migration, currently only supports “Configuration”
• data– JSON; the name of the configuration JSON object
• targeBaseVersion– string; the version of the base component
• targetImplementationVersion– string; the version of the implementation
The following is a sample code calling the Migrate service:
var migratedConfig = me.Migrate(
{
"migrationType":"Configuration",
"data":"configuration",
"targetBaseVersion":"9.0.0",
"targetImplementationVersion":"1.0.0"
}
);
{
"migrationType":"Configuration",
"data":"configuration",
"targetBaseVersion":"9.0.0",
"targetImplementationVersion":"1.0.0"
}
);
The Migrate service compares the value of targetBaseVersion against the value of baseConfiguration from the configuration JSON object and the value of targetImplementationVersion against the value of implementationConfigurationVersion from the configuration JSON object. If the version values do not match, then the Migrate service calls either the MigrateBase service or the MigrateImplementation service, which migrates the configuration JSON object to match the version of the target base or target implementation.
In general, when creating a custom Business Logic Implementation component, you do not need to call the MigrateImplementation service. However, if you create a new version of an existing custom implementation and it uses a different configuration version, then you need to implement MigrateImplementation and GetBaseMigrationVersion.
When creating a custom Base Business Logic component, you must implement the MigrateBase service.