Skip to main content

Upgrading from Ensemble 2007.1 or Later

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.

FeedbackOpens in a new tab