When deciding to upgrade to the current release of Ensemble you may want to review the new features and enhancements as well as any compatibility issues of this and any intervening releases since you last installed Ensemble. The following chapters in the Ensemble Release Notes
contain such information:
Ensemble runs on top of Caché. This means that, in addition to changes in Ensemble, the new Ensemble release includes a large number of changes in the underlying Caché technologies as outlined in the following table.
|IF you are upgrading from ...
||THEN the underlying changes resemble ...
|Ensemble 2017.1 to Ensemble 2017.2
||Caché 2017.1 to Caché 2017.2
|Ensemble 2016.2 to Ensemble 2017.2
||Caché 2016.2 to Caché 2017.2
|Ensemble 2016.1 to Ensemble 2017.2
||Caché 2016.1 to Caché 2017.2
|Ensemble 2015.2 to Ensemble 2017.2
||Caché 2015.2 to Caché 2017.2
|Ensemble 2015.1 to Ensemble 2017.2
||Caché 2015.1 to Caché 2017.2
|Ensemble 2015.1 to Ensemble 2017.2
||Caché 2015.1 to Caché 2017.2
|Ensemble 2014.1 to Ensemble 2017.2
||Caché 2014.1 to Caché 2017.2
|Ensemble 2013.1 to Ensemble 2017.2
||Caché 2013.1 to Caché 2017.2
|Ensemble 2012.2 to Ensemble 2017.2
||Caché 2012.2 to Caché 2017.2
|Ensemble 2012.1 to Ensemble 2017.2
||Caché 2012.1 to Caché 2017.2
|Ensemble 2010.2 to Ensemble 2017.2
||Caché 2010.2 to Caché 2017.2
|Ensemble 2010.1 to Ensemble 2017.2
||Caché 2010.1 to Caché 2017.2
|Ensemble 2009.1 to Ensemble 2017.2
||Caché 2009.1 to Caché 2017.2
|Ensemble 2008.2 to Ensemble 2017.2
||Caché 2008.2 to Caché 2017.2
|Ensemble 2008.1 to Ensemble 2017.2
||Caché 2008.1 to Caché 2017.2
|Ensemble 2007.1 to Ensemble 2017.2
||Caché 2007.1 to Caché 2017.2
|Ensemble 4.0.1 to Ensemble 2017.2
||Caché 5.2.3 to Caché 2017.2
|Ensemble 4.0 to Ensemble 2017.2
||Caché 5.2.1 to Caché 2017.2
If you are upgrading from Ensemble 2008.2 or an earlier version, you cannot upgrade directly to Ensemble 2017.2, but must first upgrade to an intermediate version. For details, see Supported Upgrade Paths
in the Caché Installation Guide
There was no 2011.1 release of Ensemble.
Beginning with Ensemble 2007.1, Ensemble runs on top of the same numbered version of Caché.
Ensemble Upgrade Paths
Before running an upgrade installation, review the information referenced in this chapter to determine if there are any tasks to complete before upgrading. The following upgrade paths to this release of Ensemble are supported:
The following upgrade paths to this release of Ensemble require additional steps in the upgrade procedure:
If you have an Ensemble version prior to 4.0, or if you have been using a field test version of Ensemble and you want to upgrade it to the most recent Ensemble product, contact the InterSystems Worldwide Response Center
(WRC) for guidance.
Upgrading from Ensemble 2007.1 or Later
If you are upgrading from Ensemble 2007.1 or later to this release of Ensemble, in addition to deleting the files outlined in the Caché upgrade documentation, the upgrade procedure deletes the following Ensemble files:
Any user files in the ENSDEMO
Any user files in the packages normally reserved for Ensemble (CSPX
, or EnsLib
If you have customized any files in these namespaces or added new files to these namespaces, you should preserve them before upgrading. To preserve such files, export them before proceeding with the upgrade. You may import them to any namespace after the upgrade is complete.
You cannot upgrade an Ensemble instance that has a running production; in fact, the upgrade procedure shuts down Ensemble if it is running. It is best to stop any running productions and then cleanly shut down Ensemble before you begin the upgrade installation.
If you have removed the mappings, but not disabled Ensemble, upgrading Ensemble re-creates the mappings. For more information on this topic contact the InterSystems Worldwide Response Center
To upgrade an existing Ensemble installation to this release of Ensemble:
Stop all running productions.
Perform exports to preserve files that are deleted on upgrade.
If you use custom search tables
and are upgrading from Ensemble 2010.2 or earlier, run the following command from a terminal in the ENSLIB
the upgrade to prepare the existing metadata for relocation:
ENSLIB>Merge ^%SYS("Ensemble","Upgrade","SearchTable","Data") = ^Ens.Config.SearchTablePropD
Ensemble automatically recompiles all search table classes during the upgrade process, so do not Kill the global nor import the contents after the upgrade. The upgrade process ensures that Ensemble correctly retains search table metadata after the upgrade. It also ensures that the converted data is consistent, so InterSystems strongly recommends that you thoroughly test your upgrade process so that you can address any issues in the original metadata prior to the actual upgrade.
If you have a large message warehouse and have either run Tune Table or have set the extent size and selectivity values manually, you should either verify that the new default values match your existing system or run Tune Table after the upgrade. If you have not run Tune Table or manually set the Selectivity
value, the default values are likely to be an improvement on your performance.
If you have taken action to optimize access to this table, take the following actions to ensure that the system performs well after the upgrade:
If your values are significantly different than the new defaults, then after upgrading, either run Tune Table or use Studio or the Management Portal to manually update the ExtentSize
values to describe your system.
You can run Tune Table against a running system as long as you select the Keep class up to date
Each chapter provides special instructions for upgrades.
If you exported custom schemas or any other production components or classes from a previous Ensemble installation, import them using Studio or the Management Portal. Be sure to import each item into the same namespace from which you exported it.
After upgrading Ensemble, you must recompile all objects that you have defined. One way to do this is to recompile all objects in namespaces that contain your custom code. To recompile all objects in a namespace, open a Terminal window and issue the following commands:
This method both upgrades and then compiles the class dictionaries in the specified namespace.
You could also use the $SYSTEM.OBJ.CompileAllNamespaces()
method to recompile all namespaces, but you should not do this when upgrading a HealthShare installation. You should not recompile a namespace used for HealthShare.
It is important to compile classes and schemas before
compiling the DTL or BPL that uses them. In a complex application, you might have other dependencies to consider as well.
The recommendation to use $SYSTEM.OBJ.CompileAll()
assumes that all information about dependencies between items being compiled is entirely contained within the declarations of the items themselves. You can establish such information by including compiler keywords such as DependsOn
. Alternatively, you can create routines to compile the code so that dependencies unavailable to the compiler are accounted for, especially in relation to schemas and domain-specific languages.
The Ensemble upgrade process reports important information regarding upgrades into a log file. After upgrading, review the contents of the ensinstall.log
file in the \mgr
subdirectory of your Ensemble instance to review the results of your upgrade.
Regenerate proxy classes if you previously generated them using the Java Gateway or one of the Caché language bindings, by following the instructions in the appropriate guides:
In some previous releases, in order to automatically start productions or execute code on production start, you inserted this code in the Caché user startup routine ^%ZSTART
. This code should now belongs in other locations; consequently, remove all Ensemble-related code from the user startup routine ^%ZSTART
. Use the following replacement mechanisms:
Identify any code that you want to run for a production when it is started. Override the OnStart()
callback method in the production class and place that code into this method.
Identify any code that is designed to act on specific business hosts upon production startup. Override the OnProductionStart()
callback method in the corresponding business service, business process, or business operation class and place that code into this method.
Upgrading from Ensemble 4.0 or 4.0.1
Upgrading from Ensemble 4.0 or 4.0.1 to the current release of Ensemble uses the same procedure as upgrading from later versions of Ensemble, but with some additional considerations. These are:
The upgrade procedure deletes any HL7 custom schema definitions (*.HL7
To preserve such files, export them before proceeding with the upgrade. You may import them to any namespace after the upgrade is complete.
For each Ensemble-enabled namespace, run these commands from your Terminal session:
These commands are required for the ENSDEMO
namespaces, and for any user-defined Ensemble-enabled namespaces.
Upgrading Ensemble Mirror Members
Any upgrade involving a mirror includes two kinds of changes:
Changes that should occur on all mirror members, such as replacement of library code in CACHELIB
Changes that affect the mirrored data and should occur only once (on the primary failover member) because database access is read-only on the backup mirror members.
The Ensemble upgrade code is sensitive to this distinction and may need to make both kinds of changes during the course of an upgrade. It is important to note that the Ensemble upgrade code performs upgrades to Ensemble-enabled namespaces on a namespace-by-namespace basis, and checks whether each namespace contains mirrored data. If a namespace contains any
mirrored data, then the only once
steps only occur for that namespace when the upgrade code is running on the primary failover member. As such, it is crucial that the data Ensemble uses to determine whether a namespace has been upgraded is shared across the mirror.
The following sections describe the details of the data as well as the important issues and procedures necessary to upgrade the Ensemble instances in a mirror configuration:
Important Mirror Global Data
The most important location for upgrade data which need to be shared is the ^Ens.Mirror
global located in each namespace that contains any mirrored data. The ^Ens.Mirror
global is used to determine which upgrade steps need to occur for that namespace. As such, you must
ensure that each namespace containing mirrored data includes this global in the mirrored database(s). More specifically, for each namespace which contains mirrored data, you must map the ^Ens.Mirror
global in that namespace to a mirrored database so both members of the mirror can determine whether only once
steps in the upgrade process for that namespace are complete.
You should also map the ^Ens.AutoStart
global to a mirrored database for each namespace containing mirrored data. The ^Ens.AutoStart
global specifies the name of the Ensemble production to start automatically after startup and, generally, it makes sense to have such an auto-start be identical across mirror members.
It may be simpler to illustrate what is meant by the above two directives using an example. Assume a given Ensemble namespace makes use of two user databases: DATA1
. (The namespace also includes mappings to ENSLIB
, but that is handled by Ensemble.) Assume DATA2
is a mirrored database, but DATA1
is not mirrored. In this situation, you must explicitly map both ^Ens.AutoStart
to the mirrored DATA2
database so the contents of the globals are visible to both members of the mirror.
Before the upgrade commences, disable the auto-start of productions for namespaces containing mirrored data on both instances. If, as recommended, the ^Ens.AutoStart
global is mirrored across the two instances for a given namespace, then you only need to perform this step on the primary mirror member; otherwise, perform this step on both failover members. This is in keeping with the standard Ensemble upgrade procedure and prevents any productions from being started during the upgrade.
Use the following commands to identify if the two important globals are mapped correctly for a given NAMESPACE
In this case, do not use the system-wide configuration startup setting EnsembleAutoStart
to turn off auto-start, because this is in the CPF file and is not mirrored. Instead, disable auto-start for each namespace, one at a time.
Ensemble upgrades may require data to be moved to the %SYS
namespace during the upgrade. Perform the steps on both nodes to ensure that both nodes are in a position to run all the upgrade steps if needed.
You should also be cognizant of other data or code that needs to be present on both machines, and whether any user application changes also need to occur.
Performing the Mirror Upgrade