The following release notes are available in the \Docs subdirectory of your Ensemble 4.0.1 installation:

• Late-breaking information about Ensemble 4.0.1: \relnotes\ensemble\readme.1st
• Release notes for Ensemble 4.0.1: \relnotes\ensemble\relnotes.htm (this document)
• Description of Ensemble 4.0 new features, prior to any maintenance kits: \Ensemble\ReleaseNotesEnsemble.pdf

This document provides a list of the changes between Ensemble 4.0 and this maintenance kit, Ensemble 4.0.1. Topics include:

• General Announcements
• Upgrade Instructions
• InterSystems News, Alerts, and Advisories
• Online Documentation
• Description of a Change Report
• Change Reports for This Maintenance Kit

Ensemble 4.0.1 is based on Caché 5.2.3. The changes described in this document do not include changes in the underlying Caché. For these changes, see the Caché release notes, which are available in the \Docs subdirectory of your Ensemble 4.0.1 installation as follows:

• Late-breaking information about Caché 5.2.3: \relnotes\cache\readme.1st
• Release notes for the Caché 5.2.3 maintenance kit: \relnotes\cache\relnotes.htm
• Release notes for the previous Caché maintenance kits 5.2.1 and 5.2.2: \relnotes\cache\prenotes.htm
• Description of Caché 5.2 new features, prior to any maintenance kits: \GRN2.pdf
• Description of Caché 5.1 new features: \GRN1.pdf
• Description of Caché 5.0 new features: \GIC.pdf

The Ensemble 4.0 Release Notes state that new 4.0 features are not localized; this is no longer the case. The Ensemble 4.0.1 user interface is localized in Japanese and is localizable in other languages. The exception is the Ensemble Management Portal HL7 Manager user interface, which is not yet localized or localizable.

The Ensemble 4.0 Release Notes (\Docs\Ensemble\ReleaseNotesEnsemble.pdf) provide instructions for upgrading to Ensemble 4.0.1.

Since Ensemble 4.0.1 is based on Caché 5.2.3, anyone upgrading from Ensemble 3.0 or 3.1 will need a new license key, just as when upgrading from Caché 5.0 to 5.1 or 5.2.

Each started job in Ensemble 4.0 consumes one license unit; therefore, be sure to install a license key with sufficient capacity for the number of background jobs required by your production. If you have questions or encounter any problems in this regard, please contact the InterSystems Worldwide Response Center.

When you upgrade to Ensemble 4.0.1, the Ensemble 4.0 Release Notes instruct you to export the entire contents of every Ensemble namespace, upgrade Ensemble, then reimport everything into new namespace(s). These instructions do work, and they are the safest technique.

However, you may find it more convenient to upgrade Ensemble from 3.1 to 4.0.1 as follows:

1. Perform a full backup of your system.
2. Disable incoming services to make sure no more message come in.
3. As soon as processing is done shut down the production.
4. Disable auto-start of the production.
5. Stop Ensemble and perform the Upgrade installation to Ensemble 4.0.1.
6. For every Ensemble enabled namespace except ENSLIB and ENSDEMO, perform the following steps. From the Terminal prompt:

   ZN "namespace"
   DO ##class(%EnsembleMgr).UpgradeNamespace(namespace, 1)
   DO ##class(%EnsembleMgr). EnableNamespace(namespace, 1)
   DO $system.OBJ.CompileAll()

   In these instructions, namespace represents the namespace name.

7. Start your production.

From time to time, InterSystems publishes items of immediate importance to users of our software. These include alerts, mission critical issues, important updates, fixes, and release announcements.

The most current list can be obtained from the InterSystems Website.

Users should check this list periodically to obtain the latest information on issues that may have an effect on the operation of their site.

As a convenience to our users, InterSystems provides online access to documentation for recent product versions at the InterSystems Website. From the home page choose the Caché tab, and on the Downloads menu, select Documentation and Help Updates or follow this link.

To help you assess the impact of this maintenance kit on your applications, the remaining topics in this document describe each modification in detail. The format for this description is a Change Report.

Each Change Report provides a table with the following information:

• Likelihood: The probability that a user on the affected platform will encounter this issue.
• Risk: An assessment of how likely this change is to introduce additional issues into the application environment.
• Ad Hoc: Whether this change has previously been deployed in an ad hoc release and successfully used by customers in production.
• Enhancement: Whether this change provides new features or capabilities for the product.

In Caché 5.2, the class path to CacheDB.jar had changed. We now have versions for Java 1.4 and 1.5.

Previously, when upgrading systems from Ensemble 3.1 to Ensemble 4.0, some users encountered the problem that application code would not compile or execute in upgraded Ensemble namespaces. This problem has been fixed. Also see MC585.

After selecting a message element in the message trace, if you clicked on the Contents link in the message detail pane, y ou'd be prompted to log in again.This problem has now been fixed.

Two occurences of launchPopupWindow() did not pass CSPCHD to the child window and thus went to the CSP login page instead of the desired page. This problem has now been fixed.

Ensemble performs an initialization sequence upon the first Ensemble startup after an installation or upgrade. As of this maintenance kit, Ensemble now loads into the ENSLIB namespace all of the messages found in \Mgr\Locale under the Ensemble installation directory. All Ensemble namespaces now have a mapping of ^CacheMsg and ^CacheMsgName into the ENSLIB namespace.

Previously, the methods that start and stop productions failed to properly convert character formats for characters displayed in confirmation messages for the Japanese locale. This problem is now fixed.

Studio's file dialog was adding a duplicate suffix for these file document types: *.RUL, *.DTL and *.BPL. The duplicate suffix prevents the file from being opened. The same problem did not happen with *.HL7 or regular types (classes, routines, pages). The problem has now been fixed.

Ensemble now supports parameter passing in Ens.ManagerQuery:GetSqlResultSet

Problems were encountered with failover on Ensemble clusters. These were addressed as follows: When $$$SystemName is defined as $zu(110), i.e. the machine's name, it causes problems in a cluster failover situation. Since Ensemble running under ECP is not fully supported at this time, we can assume there is only a single machine running Ensemble at any given time. Thus, we can simply define the $$$SystemName as a constant. That alsos make the cluster failover work properly.

Ensemble now sets MAXLEN="" for the variable %MasterPendingResponses.

Previously, TRUNCATE was set to 1 (that is, true) as part of a class dictionary upgrade. However, this only caused problems in many situations in which properties are truncated. Property parameters no longer have TRUNCATE=1. See TAP228.

Ens.Director:StopProduction() did not work because the timeout value of -1 (the default) was broken. This change fixes the bug. It also changes the timeout default value from -1 to 10 to be in line with the other default timeout values.

Previously, when the Ensemble scheduler was used to start and stop productions, productions sometimes did not start up or shut down cleanly, or sometimes entered a suspended state rather than shutting down. A problem was identified that Ensemble sometimes did not correctly identify the last event’s timestamp relative to the current time. This problem has been fixed.

Previously, if the user tried to start or stop a production that, for some reason, could not be started or stopped, the Ensemble Management Portal sometimes froze until the user closed the browser or a CSP timeout occurred. This problem has been fixed.

When the primary request of a business process is of high priority (from a synchronous call), then all the outgoing asynchronous calls that require responses will have their priority raised to high. The new enchanced behavior is that the raising of the priority will happen only until the response of the original synchronous message is sent back. After the response is sent back, Ensemble does not raise the priority of the asynchronous messages, because these messages are no longer blocking the original synchronous message.

Previously, when upgrading systems from Ensemble 3.1 to Ensemble 4.0, some users encountered the problem that application code would not compile or execute in upgraded Ensemble namespaces. This problem has been fixed. Also see DMC334.

This change adds an enumerated column for production status to the results from the ProductionStatus query.

EnsLib.Workflow.TaskResponse.FindLeastBusyUser was passing the parameter pUserName to EnsLib.Workflow.Engine.FindLeastBusyUser by value when it should pass it by reference. It has been changed to pass by reference and now works.

In one code path, the GetShadowInstance method was erroneously returning its error instead of passing it as an output argument. This problem has been fixed. This change also adds support for getting an instance with default class settings rather than with configured settings from a production. Finally, this change supports the fix provided by TAP215.

A customer tried to use the RawContents property to write out to a file the contents of a >32k HL7 message. This is not an intended or documented use of this property. This change adds warning comments to the source code to discourage such usage.

Code based on form variable values was being executed even when there was no DocClass form variable. This change comments out the code that should not execute.

Schedule strings were being truncated at 50 chars. This change makes these strigns unlimited in length. See MC567.

A duplicate set of error messages for XPath caused problems with conflicting message IDs. These problems have been fixed.

This change adds an optional third argument to the argument lists of BusinessService.ProcessInput() and OnProcessInput(). This addresses the annoying problem that a SOAP service calling ProcessInput() from each of its WebMethods had no easy way to tell from inside OnProcessInput() which of the methods it was called from. Using the classname of the pInput object has been our advice, but that runs into trouble when multiple methods use the same Request type, or none at all. The pHint value can be used to pass through the method name, making it easier for the OnProcessInput() implementation to switch its behavior, or use indirection to call through to the proper sub-method.

Previously, the IBO (iWay Business Object) error response parser did not support “closed” tags such as <Name/>. This problem has been fixed.

This change updates the Counted String Tree (CST) transport support for easy Ensemble-to-Ensemble service calls.

An ill-behaved outbound HL7 TCP client can hold the socket open but never read anything from it and never respond. In this case, the Ensemble retry loop can keep retrying the send until the system TCP output buffer fills up and as a result the job hangs. Interface engineers can find the hung job, kill it, and then re-start the interface using UpdateProduction. This is enough to jolt the remote system back to life, but it also jettisons the current message held by the dead job.

This change provides an enhancement that can both automatically jolt the remote machine by dropping the socket and re-connecting, and help prevent this buffer overflow problem and resulting hung job. The new ReconnectRetry setting is an integer. After this number of retries, the Ensemble TCP outbound adapter drops the connection and attempts to re-connect. If the problem persists, it will wait this many retries and then drop the connection again, and so on, until the FailureTimeout limit is reached, if ever.

The default value is 5. That means customers who upgrade will automatically experience this new behavior. To experience the old behavior they should set this new setting to 0.

TCP InboundAdpaters should use the CallInterval as the timeout for their initial Read from the socket. They were using the ReadTimeout property instead. This change also adds a timeout argument to the Read() method to provide finer control to authors of TextLine business operations and business processes.

Previously, users sometimes encountered an UNDEFINED error during SOAP service initialization. This problem has been fixed.

The CallWizard was not setting the value of the Async keyword correctly. Also the Studio inspector did not reflect the state of the new <call> activity. These problems have been fixed.

This change adds the following helpful changes for users designing custom HL7 schemas:

• Segment descriptions appear in the hover text for each segment in a message structure.
• Helpful descriptions can be found in the data for the base class, so the code that retrieves descriptions now looks all the way through to the base schema.

Previously, Ensemble would not properly show the contents of an HL7 message with a custom schema. The message appeared and was correctly divided into segments, but was all black in the display due to a failure in the underlying code. This problem has been fixed.

This change fixes a problem in the EDI/HL7 Manager which, when present, ran as follows:

1. In the EDI/HL7 Manager, go to the message viewer
2. Open up any valid HL7 message from a flat file
3. Select the radio button for "Production:Business Service" and fill out a valid entry
4. Click the View Message button again
5. An error page displays.

This change and TAP214 fix the problem and add significant enhancements, including a dropdown list of all classes and configured Services that consume the relevant virtual document type, in this case HL7.

This change removes the "None" advice from Credentials setting comments, adds a new Setting ResponseTimeout for EnsLib.SOAP.OutboundAdapter, adds recovery code for ! mode in TCP adapters, and makes some cosmetic changes.

This change fixes the parsing of the "std" boolean flag in schemaXML to accept values 0 and "false" to indicate false. Previously this flag only accepted "" for false.

Miscellaneous changes were required to update the HL7 version 3 demonstration package so that <COMMAND> errors did not result when it was run. These changes included regenerating the SOAP proxies and accommodating changes in the way that OnPreHTTP is now handled for CSP pages

In the Ensemble portal, EDI/HL7 Manager, Message Viewer, the Schema Category / Version field did not appear to contain the provided categories 2.1, 2.2, etc., whereas these could be seen in the Schema Structures page.

This issue appeared when the user dropped down the category/version list when there was no VDoc object currently loaded in the page. The problem was previously overlooked because a user does not usually look at that list until there is a document to apply it to. The problem has been fixed.

A duplicate set of error messages for X12 caused problems with conflicting message IDs. These problems have been fixed.

Previously, users experienced problems cloning an HL7 message. These problems caused segments to be missing from the cloned HL7 message. MSH was the most commonly missing segment. As of this maintenance kit, a cloned HL7 message no longer has missing segments.

Previously, there were several problems with the Ensemble sample productions for HL7. These problems occurred only on machines set to the Spanish locale. The problems included:

• The production cannot process files from the inbound directory.
• An entry in the Event Log page mentions the file is being processed, but it is never actually processed.
• No error is reported in the Event Log.
• The process starts consuming lots of CPU.
• The Home page freezes (see MC575).
• The production cannot be stopped.
• CleanProduction() does not solve the problem.
• It takes a lot of time to stop Ensemble and there are errors.
• It is necessary to restart Windows.

As of this maintenance kit, the problems are now fixed.

Previously, when DTL transformation classes were defined or referenced but not compiled, a subsequent error ocurred when the user tried to display the Ensemble Management Portal, HL7/EDI Document Viewer page. This problem has been fixed.

A problem was caused by our removal of TRUNCATE=1 from all property parameters (see MC567). If a Rule Log property value was too long, instead of truncating it failed validation. In addition, the code path that returned the validation error from %Save() had typos in it, previously undiscovered, resulting in an UNDEFINED error. This change fixes the typos, restores TRUNCATE=1 in the RuleLog class, and adjustst the MAXLEN values of the properties of RuleLog so as to permit more detailed logging.

Previously, HL7 messages with more than 32K characters were not supported. As of this maintenance kit, there are new methods in the Segment and Message classes that allow querying for the full size of >32K segments and storing and retrieving the data in them.

When copying a Message Structure definition from a standard category to a custom schema category, all the segments in the structure string generally have no type because they implicitly refer to segment definitions within the same standard category. However, in the context of the custom schema category they are unresolved, and this causes the DTL editor among other things to not recognize them.

This change makes such implicit references automatically resolve to definitions in the base schema category if they exist there, and to give errors if they don't. This change also improves the error reporting capabilities of the schema importer.

Both port numbers are now 22222.

Fixed some problems in reporting errors when the Java Gateway startup fails.

The Caché pipe device (Open mode "Q") chokes if there is more than one set of quotes in a command. Due to this Caché restriction, we cannot support spaces in the class path and in the JAVA_HOME setting for the Java Gateway. If spaces are used at all, it must be in one or the other, not both. For example if you enter:

"C:\Program Files\Java\javasdk1.5_07\bin\java.exe" -classpath "C:\Program Files\foo\bar.jar" ...

The system returns the error message:

"C:\Program " is not a valid command, batch file ... etc

However, if you do not quote the class path part of the command, the command works.

For further notes on the pipe device see DMC314.

The Java Gateway import wizard had the default timeout of 60 seconds and thus would timeout before the Java Gateway import could finish, in most cases. This change fixes the problem by changing the default timeout to 24 hours.

The pipe device does not like quoted pathnames (see DMC311). Usually, pathnames get quoted because they contain spaces. However, it turns out there is a function called $ZU(147) that attempts to mitigate this by converting a regular filename to an old-style 8.3 filename. So, if there is no short name available, or you are on UNIX, then if the filename contains spaces Ensemble quotes it using $ZU(147).

We have recently changed Java so that we have a 1.4 version and a 1.5 version of CacheDB.jar. Previously there was no way to specify this. Now, a drop list has been added to the Java Gateway service to allow you to specify what version of CacheDB.jar you wish to use.

The timeout for the production start/stop in the Ensemble management portal was way too low; at 60 seconds it would timeout the CSP page while Ens.Director was still stopping the production. The timeout has been increased sufficiently to prevent this from happening.

A comprehensive change has been made to the underlying code that supports localization of text in the Ensemble Management Portal. As of this maintenance kit, most of the portal pages now use the new mechanism rather than the old. This change has enabled several of the other changes noted in this document.

On the Ensemble Home page, below the activity table, there is a new link that you can click to "Return to System Management Portal".

Fixed an error that prevented the Round function from working in rules.

In the previous release there were installation script issues that prevented the upgrade from Ensemble 3.1 to Ensemble 4.0 on Unix Platforms. These problems have been fixed.

When using a remote server that is VMS from the Studio, there were some problems opening BPLs due to issues with the (separate) web server. This change fixes the problem that copy was not working in the Result window.

When using a remote server that is VMS from the Studio, there were some problems opening BPLs due to issues with the (separate) web server. This change fixes the problem that if no web server is specified the Studio simply failed to open the BPL, with no error message.

In the previous version, several of the text strings in the Ensemble Management Portal, Event Log page required localization. This problem has been fixed.

This change provides support for the overall localization of this maintenance kit.

Kitting on all platforms is changed to pick up allmessages_<lang>.xml from kit/common/release/localized/$product, where $product can be cache or ensemble.