Release and Upgrade Information for Ensemble 2012.1

New Management Portal User Interface

The user interface for the Ensemble Management Portal is completely new in this release; therefore, any procedures you are using or have documented most likely must change. Each page of the new portal has help information to guide you.

See Managing Ensemble for details.

Business Rule Conversion

The upgrade procedures to this release automatically convert existing rules. Old rule names (with a .rul extension) allowed for characters that are not supported in class names. In this case, the rule definition includes an alias that is used to invoke the rule. Old rules are automatically converted on upgrade or import and the changes should not affect your applications. However, if you rely on details of the old implementation, you may encounter issues.

Due to the more limited structure of the old rules, some converted rules end up with a structure that may not be the most straightforward or recommended way of developing rules in the new editor, but they will still work as before.

For HL7 routing rules, the rule editor no longer exposes the Schema DocType, which represents the message structure. This is now inferred from the message type. The message structure continues to be exposed for rules that you import from earlier versions.

Changes in Rule Log Structure

As part of the changes to the implementation of business rules and routing rules, this release changes the structure of the rule log. The previous rule log is still available in the Ens.Rule.RuleLogOpens in a new tab class (SQL table Ens_Rule.RuleLog). The new rule log is stored in Ens.Rule.LogOpens in a new tab (SQL table Ens_Rule.Log).

The business rule conversion described in the previous section now records slightly different information in the rule log, in addition to using a different storage structure. If you have written your own queries or reports based on the contents of the rule log, you must update your queries to ensure that they continue to retrieve the correct information and that they continue to perform optimally.

The Rule Log page only shows entries in the new rule log. Ensemble does, however, provide a legacy page, Ensemble, Legacy Rule Log, so you can see the rule log entries from an earlier version:

http://localhost:57772/csp/ensemble/EnsPortal.LegacyRuleLog.zen

You cannot navigate to this legacy page from the Management Portal menus; you must enter the above URI, replacing 57772 with the web server port of your Ensemble instance. The EnsPortal.LegacyRuleLogOpens in a new tab page is subject to the same security restrictions as the EnsPortal.RuleLogOpens in a new tab page.

Ensemble purges the legacy log in the usual way; all old entries should remain for only a small number of weeks depending on your retention policy.

New Dashboard Development Tool

Existing dashboards are not operational starting with this release, but existing business metrics are still valid. You cannot directly convert dashboards from previous releases to this release. Instead, you must create a dashboard in the DeepSee User Portal using your existing business metric as the data source to implement each new dashboard. If you require this type of update, contact the InterSystems WRCOpens in a new tab for guidance.

See the chapter “Creating Dashboards” in Configuring Ensemble Productions to get started.

New Security Model for Management Portal

If you are upgrading an instance of Ensemble, the upgrade process adds new roles to Ensemble users based on their previous roles. Review these roles after an upgrade to verify the converted access and to further restrict access as needed.

One exception is that users in previous versions who held the %Service_Login resource were able to start or stop productions from the command line, even if they did not have permission to access the Management Portal. After an Ensemble upgrade, these users will not be able to stop or start productions. To allow them to do so, you must give them a role, such as %Ens_Operator, that holds the required resource. Users who could start or stop productions from the Ensemble Management Portal in earlier releases are not affected by this tightening in security checks.

For more information, see “Controlling Access to Management Portal Functions” in Managing Ensemble.

Changes to Workflow User Interface

As of this release, the separate Workflow Management Portal is gone. Instead, Ensemble now provides two user interfaces, intended for different sets of users:

• The Management Portal provides pages that implementers and supervisors can use to manage workflow roles, users, and tasks. To access them, from the Ensemble menu, click Manage and then click Workflow.

  These pages are similar in most ways to the Workflow Management Portal, except that they no longer provide options for users to manage their tasks.

• The DeepSee User Portal is a stand-alone user interface intended for end users. It displays dashboards (both Ensemble and DeepSee dashboards). For workflow users, it includes the Workflow Inbox. Via the Workflow Inbox, users can display the task form associated with a task and manage that task in the same way as in previous releases.

Updated Selectivity and Extent Size of the Message Warehouse

Ensemble uses the extent size and selectivity (the number or percentage of records that match any value) property parameters in any table to optimize SQL queries. Setting these correctly for Ens.MessageHeaderOpens in a new tab is important for good response times when using the Ensemble message browser. You can set these values by running the Tune Table facility against this class.

The Ensemble upgrade procedure, however, overwrites this information with the default values. This release improves the default values to represent a typical large site, which should give good performance for most installations. The following shows the default ExtentSize and Selectivity values for the Ens.MessageHeaderOpens in a new tab class in this Ensemble release:

<ExtentSize>20000000</ExtentSize>
<IdLocation>^Ens.MessageHeaderD</IdLocation>
<IndexLocation>^Ens.MessageHeaderI</IndexLocation>
<Property name="MessageBodyClassName">
<Selectivity>10%</Selectivity>
</Property>
<Property name="MessageBodyId">
<Selectivity>0.0001%</Selectivity>
</Property>
<Property name="Priority">
<Selectivity>20%</Selectivity>
</Property>
<Property name="SessionId">
<Selectivity>20</Selectivity>
</Property>
<Property name="SourceConfigName">
<Selectivity>5%</Selectivity>
</Property>
<Property name="Status">
<Selectivity>11%</Selectivity>
</Property>
<Property name="TargetConfigName">
<Selectivity>5%</Selectivity>
</Property>
<Property name="TimeCreated">
<Selectivity>5</Selectivity>
</Property>
<Property name="TimeProcessed">
<Selectivity>5</Selectivity>
</Property>

If you have a large message warehouse and have either run Tune Table or have set these values manually, you should either verify that the 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 new values should improve the performance of queries in the Message Viewer.

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. The ExtentSize and Selectivity values are listed near 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.

For details on using Tune Table from the System, SQL, Schemas, Tables page of the Management Portal, see “ExtentSize, Selectivity, and BlockCount” in the chapter “Optimizing Tables” in the Caché SQL Optimization Guide.

Updated Saved Message Searches

In Ensemble, saved message filters or saved searches allow you to give a name to frequently used combinations of criteria in the message viewer. The storage of these filters has changed and during an upgrade the message filters are automatically converted to the new format and no action is required. However, if you want to export filters from an earlier release to 2012.1 you must run a manual conversion.

First, export the global ^CSPX.EnsMsgFilterFormD from the earlier version and import it into your Ensemble 2012.2 instance.

Then either convert a single saved search with the following command:

Do ##class(EnsPortal.MsgFilter.SavedSearch).ConvertCSPXSearch("mysearch")

Or, convert all saved searches with the following command:

Do ##CLASS(EnsPortal.MsgFilter.SavedSearch).ConvertAllCSPXSearches()

Removed CSPX Files from Distribution

Ensemble no longer ships CSPX files as part of the distribution. The inclusion of these files would give people the ability to bypass the granular security of the new user interface by accessing the old user interface. If you previously used these files, contact the InterSystems WRCOpens in a new tab for help in upgrading your Ensemble environment.

Updated Search Table Validation

An update to the consistency checking, storage definition, and upgrade procedure for search tables resolves a long-standing issue with upgrades losing search table metadata. Ensemble now stores search table metadata locally in each namespace.

To avoid rebuilding your custom search tables after an upgrade, perform an additional step (step 4 of the Upgrading Ensemble procedure) before upgrading to ensure that Ensemble correctly retains search table metadata.

Search table metadata is located in the default global database for each Ensemble namespace; therefore, a change to a search table class does not update metadata in all namespaces to which the class is mapped. You must compile a mapped search table class in all target namespaces to ensure that the metadata local to each namespace is up to date.

If you have not developed any custom search tables, you do not need to take any action. If you complete the upgrade without performing the additional pre-upgrade step and then determine you do have custom search tables, values in the search tables may be incorrect. You can correct this by rebuilding the search tables. For each search table, perform the following:

  Set sc=##class(EnsLib.HL7.SearchTable).BuildIndex()

See the EnsLib.HL7.SearchTableOpens in a new tab entry in the Class Reference for details.

New DTL Classes Created with REPORTERRORS Parameter Set to True

Previous to this release, all DTL data transformation classes inherited from Ens.DataTransformDTLOpens in a new tab had the REPORTERRORS parameter set to False. Beginning with this release, any DTL classes you create with the Data Transform wizards in the Management Portal or Studio override this value to True with the following declaration:

Parameter REPORTERRORS = 1;

This setting causes Ensemble to log any errors it encounters in executing the transform as Warnings in the Event Log and to return a composite status code containing all errors as its return value.

However, to maintain compatibility for existing DTL data transformation classes, the default setting in the abstract class did not change. The Ens.DataTransformDTLOpens in a new tab class still declares:

Parameter REPORTERRORS = 0;

This setting causes Ensemble to silently log errors as trace messages with category xform.

You can review your transformations to see if updating the value of this parameter makes sense in your application.

Updated Legal Character Checking in Configuration Names

The [ character is now disallowed in production configuration names. Productions containing configuration items with names that contain this character no longer compile successfully. As described in the CheckForIllegalCharacters() method of the Ens.Config.ItemOpens in a new tab entry of the Class Reference. This character is restricted because it could interfere with the ArchiveItems property setting syntax of the Message Bank operation (Ens.Enterprise.MsgBankOperationOpens in a new tab) class.

Change in Inactivity Timeout Behavior

The behavior of the InactivityTimeout setting now sends an alert in addition to marking a component as Inactive when no activity has occurred within the inactivity timeout of a configuration item. In addition, the setting is included in the Settings property of the Ens.Config.ItemOpens in a new tab class to permit the use of Default Settings to populate this value.

The original InactivityTimeout property of the Ens.Config.ItemOpens in a new tab class and the XML attribute of the same name is transparently transferred to the new location, so previous code directly accessing this value should see no change in behavior, but the structure of the XML produced in the production XData is slightly different.

Removed Host Monitor from User Interface

Previous releases of Ensemble provided a Host Monitor page in the Ensemble Management Portal. The new Management Portal user interface does not contain this specific page, but does contain the following pages available from the Monitor menu in the Ensemble portion of the portal for monitoring your Ensemble productions:

• System Monitor

• Production Monitor

• Queues

• Jobs

See the Monitoring Ensemble book for details.

Improved Notification for Stopping a Running Production

In the new Management Portal user interface, you stop a production from the Ensemble, Production Configuration page. You can only stop a production if it is open for configuration and it is running. You receive an informational message if you try to stop a production that is not running or try to start a production and another production is already running in the namespace. You must open the running production in the Production Configuration page before you can stop it.

In previous Ensemble versions, if one production was running and you were configuring a different production, when you clicked Stop Production on the configuration page, Ensemble would stop the running production regardless if it was open for configuring. This could lead to a user inadvertently stopping the wrong production.

You can view the running productions on the right hand side of the Management Portal menu navigation pages and click View details to open the selected production in the Production Configuration page.

Change in $$$EnsSystemError Behavior

In previous releases, the $$$EnsSystemError macro logged all exceptions it trapped in Ensemble to the %ETN utility. This release has updated this behavior; it makes the logging optional and turned off by default.

The logging is now controlled by the ^Ens.Debug("LogETN") global. This global is undefined by default, so %ETN logging does not occur. You can set the global at any time to a nonzero value to enable %ETN logging. The purpose of this change is to avoid consuming excessive database space when repetitive errors occur in an Ensemble production. Allowing it to be enabled by setting a global means it can be turned on at any time to collect deeper information when a problem is occurring.

If you have used the $$$EnsSystemError macro to log exceptions to %ETN in your application, you must set the ^Ens.Debug("LogETN") global for your application error logging to continue.