Skip to main content

Upgrading Ensemble

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. See the following for this information:

If you are using the InterSystems Mirroring technology with Ensemble, see the “Upgrading an Ensemble Mirror” section for additional specific instructions.

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.2 to Ensemble 2018.1 Caché 2017.2 to Caché 2018.1
Ensemble 2017.1 to Ensemble 2018.1 Caché 2017.1 to Caché 2018.1
Ensemble 2016.2 to Ensemble 2018.1 Caché 2016.2 to Caché 2018.1
Ensemble 2016.1 to Ensemble 2018.1 Caché 2016.1 to Caché 2018.1
Ensemble 2015.2 to Ensemble 2018.1 Caché 2015.2 to Caché 2018.1
Ensemble 2015.1 to Ensemble 2018.1 Caché 2015.1 to Caché 2018.1
Ensemble 2015.1 to Ensemble 2018.1 Caché 2015.1 to Caché 2018.1
Ensemble 2014.1 to Ensemble 2018.1 Caché 2014.1 to Caché 2018.1
Ensemble 2013.1 to Ensemble 2018.1 Caché 2013.1 to Caché 2018.1
Ensemble 2012.2 to Ensemble 2018.1 Caché 2012.2 to Caché 2018.1
Ensemble 2012.1 to Ensemble 2018.1 Caché 2012.1 to Caché 2018.1
Ensemble 2010.2 to Ensemble 2018.1 Caché 2010.2 to Caché 2018.1
Ensemble 2010.1 to Ensemble 2018.1 Caché 2010.1 to Caché 2018.1
Ensemble 2009.1 to Ensemble 2018.1 Caché 2009.1 to Caché 2018.1
Ensemble 2008.2 to Ensemble 2018.1 Caché 2008.2 to Caché 2018.1
Ensemble 2008.1 to Ensemble 2018.1 Caché 2008.1 to Caché 2018.1
Ensemble 2007.1 to Ensemble 2018.1 Caché 2007.1 to Caché 2018.1
Ensemble 4.0.1 to Ensemble 2018.1 Caché 5.2.3 to Caché 2018.1
Ensemble 4.0 to Ensemble 2018.1 Caché 5.2.1 to Caché 2018.1

If you are upgrading from Ensemble 2008.2 or an earlier version, you cannot upgrade directly to Ensemble 2018.1, 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.

The Caché Release Notes and Upgrade Checklist book in the Caché documentation is helpful when you are upgrading from previous Ensemble versions.

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:

  • Ensemble 2017.1

  • Ensemble 2016.2

  • Ensemble 2016.1

  • Ensemble 2015.2

  • Ensemble 2015.1

  • Ensemble 2014.1

  • Ensemble 2013.1

  • Ensemble 2012.2

  • Ensemble 2012.1

  • Ensemble 2010.2

  • Ensemble 2010.1

  • Ensemble 2009.1

  • Ensemble 2008.2

  • Ensemble 2008.1

  • Ensemble 2007.1

To upgrade to this release of Ensemble, follow the instructions in Upgrading from Ensemble 2007.1 or Later.

The following upgrade paths to this release of Ensemble require additional steps in the upgrade procedure:

  • Ensemble 4.0.1

  • Ensemble 4.0

Additionally follow the instructions in Upgrading from Ensemble 4.0 or 4.0.1.

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 CenterOpens in a new tab (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 namespace

  • Any user files in the packages normally reserved for Ensemble (CSPX, Demo, Ens, 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.


In some environments, you need to create namespaces in Ensemble and then remove the Ensemble mappings from the namespace. You should only do this if you understand the impact of removing these mappings. If you have removed these mappings, you must also disable Ensemble for the namespace. You can create a new namespace that is disabled for Ensemble by clearing the Make this an Ensemble namespace check box when creating the namespace. For more information, see “Create a Namespace on an Ensemble Instance” in the Caché System Administration Guide. If you have already created a namespace and have removed the Ensemble mappings, you can disable Ensemble in the namespace by opening a Terminal window and issuing the following command:

Do ##class(%Library.EnsembleMgr).DisableNamespace("namespace",1)

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 CenterOpens in a new tab.

To upgrade an existing Ensemble installation to this release of Ensemble:

  1. Stop all running productions.

  2. Disable the production auto-start option for all productions in all namespaces. See “Managing Production Auto-Start” in Managing Ensemble.

  3. Perform exports to preserve files that are deleted on upgrade.

  4. 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 namespace before the upgrade to prepare the existing metadata for relocation:

    ENSLIB>Merge ^%SYS("Ensemble","Upgrade","SearchTable","Data") = ^Ens.Config.SearchTablePropD

    Ensemble checks this location during upgrade and adds any of the existing metadata into namespaces where the originating search table classes exist. This occurs before any compilation of search tables in the namespace. For details, see “Updated Search Table Validation” in the chapter “Upgrade Compatibility Issues” in the Ensemble Release Notes.

    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.

  5. 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:

    1. Record the ExtentSize and Selectivity values of your current system. One way to do this is to open the Ens.MessageHeaderOpens in a new tab class in Studio. ExtentSize and Selectivity are listed at the end of the class definition in the code window.

    2. 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 and Selectivity 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 check box.

    For details on using Tune Table, see “ExtentSize, Selectivity, and BlockCount” in the chapter “Optimizing Tables” in the Caché SQL Optimization Guide.

  6. Prepare for an upgrade to Ensemble as described in “Upgrading Caché” in the Caché Installation Guide.

  7. Install Ensemble using the instructions in the appropriate platform-specific chapter of the Caché Installation Guide:

    Each chapter provides special instructions for upgrades.

  8. 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.

  9. 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:

     ZN "namespace"
     DO $system.OBJ.CompileAll("u")

    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 and CompileAfter. 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.

  10. 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.

  11. 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:

  12. 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:

    • To automatically start productions, use the Ensemble production auto-start options instead of your custom code. For details, see “Managing Production Auto-Start” in Managing Ensemble.

    • 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.

    For information on these callback methods, see “Less Common Tasks” in Developing Ensemble Productions.

  13. Re-enable the production auto-start options, as desired. See “Managing Production Auto-Start” in Managing Ensemble.

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:

     ZN "nextEnsembleNamespace"
     DO ##class(Ens.MessageHeader).%PurgeIndices()
     DO ##class(Ens.MessageHeader).%BuildIndices()
     DO ##class(EnsLib.HL7.Message).%PurgeIndices()
     DO ##class(EnsLib.HL7.Message).%BuildIndices()
     DO ##class(EnsLib.HL7.Message).%BuildIndices(($LB("Extent")))

    These commands are required for the ENSDEMO and ENSEMBLE namespaces, and for any user-defined Ensemble-enabled namespaces.

Upgrading Ensemble Mirror Members

This section documents the steps to follow to upgrade an Ensemble mirror configuration. You should be familiar with standard Caché upgrade procedures. For general information on running Ensemble on a mirror, see “Ensemble Considerations for Mirroring” in the Caché High Availability Guide and for upgrade procedures, see “Minimum Downtime Upgrade with Mirroring” in the Caché Installation Guide for details.

Any upgrade involving a mirror includes two kinds of changes:

  1. Changes that should occur on all mirror members, such as replacement of library code in CACHELIB and ENSLIB.

  2. 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 and DATA2. (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 and ^Ens.Mirror 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:

  Write ##class(SYS.Database).%OpenId($P(##class(%SYS.Namespace).GetGlobalDest
  Write ##class(SYS.Database).%OpenId($P(##class(%SYS.Namespace).GetGlobalDest


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.

Mirror Considerations

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

Minimum Downtime Upgrade with Mirroring” in the Caché Installation Guide describes the different types of mirror upgrades. If you are doing a major version upgrade and have Ensemble namespaces with mirrored data, you must choose one of the procedures that includes mirrored database changes.

FeedbackOpens in a new tab