Ensemble Release Notes
Upgrade Compatibility Issues
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Before upgrading Ensemble, first review the product changes in this release that could affect the operation of your existing system. The following sections list the compatibility issues for this and previous releases of Ensemble. In addition to the issues in this release, be sure to also review the issues for each intervening release since you last installed Ensemble:

The following releases did not include compatibility issues specific to Ensemble; therefore, you need only review the Caché documentation:
Compatibility Issues for Upgrades to Ensemble 2017.1 (This Release)
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Business Process Lock Changes
In this release we have improved handling locks in business processes that are coded to allow multiple asynchronous responses. In previous releases, if a part of the business process exceeded the system lock timeout, the asynchronous response could be discarded. In this release, instead of discarding the response, Ensemble requeues the response to the business process.
XML VDoc Handling of Missing Values Changes
In previous releases, transformations could insert an empty string value in the target where the property in the source was missing. In this release the value in the target is missing and not the empty string. If your transformation relies on the missing value in the target, you can explicitly set the target property to an empty string.
XML VDoc Child of Repeating Parent Changes
In previous releases, if the XSD schema defined a repeating parent that contained a repeating child and there was only a single child element in the XML document, the VDoc could define the child as a member of the repeating parent. This prevents you from accessing any child element other than the first. In this release, XML VDoc correctly parses the repeating element. If you have written code to explicitly handle the previous structure, you should modify your code to handle the corrected structure.
Ensemble Java Gateway Defaults to JDK 1.8
In previous versions, the Ensemble Java Gateway defaulted to JDK 1.7, but in this release it defaults to JDK 1.8. If you need to continue using JDK 1.7, specify that version in the Java Gateway settings.
Ensemble DotNet and Java Gateways Support Validated Connections
In this release, you can start the Ensemble Java and DotNet gateways and require passphrases. There are also changes to specifying the address for the gateway and starting the gateway for use by another system. See Java and Gateway Changes in the Caché Recent Upgrade Checklists for details.
Search Tables Now Handle Vertical Bars
In previous releases, Ensemble did not allow a vertical bar (|) in any of values indexed by a search table, because double and single vertical bars both interfered with Ensemble internals.
In this release, this limitation has been removed, and any vertical bar is replaced by a plus sign when the data is indexed. Recompile any search table classes to enable them to index new data correctly. Note that this has no effect on the existing contents of the search tables. Also, search for a plus sign rather than a vertical bar, when you use the search table. For example, to search for a message that contains my|string, use my+string.
Compatibility Issues for Upgrades to Ensemble 2016.2
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Production Status Hover Tip May Be Stale
The Production Configuration page checks the status of the production and tests if any component needs updating. These checks temporarily lock the production’s runtime data. In this release, we have improved efficiency by minimizing the locks. A consequence of this change is that the hover text indicating that a production needs updating may be out of date and not reflect the current state. If you select the Update button, the data is refreshed and the update uses the current data.
IsEnsembleNamespace Method Returns Information About Specified Namespace
In this release, the ##class(%Library.EnsembleMgr).IsEnsembleNamespace() method takes a parameter and returns whether the specified namespace is enabled for Ensemble. In previous releases, this method always returned the status of the current namespace. If you have code that specifies a parameter, in previous releases, it would have ignored the parameter and returned the status of the current namespace. In this release, it returns the status of the specified namespace. If no parameter is specified, the behavior is unchanged; the method returns the status of the current namespace.
Note:
If the user does not have access to the specified namespace, this method always returns 0.
Efficiency Improvements Changed VDoc XSD Schema Structure
This release improves the efficiency of storing XSD by eliminating unneeded data. This can also substantially reduce the amount of data that needs to be journaled. These internal structures should only be accessed by InterSystems internal code. If you have written code that directly accesses these structures, you should modify it to use the public APIs.
Note:
If a large schema is re-imported, it is possible that large journal records will be produced as the unnecessary schema data is removed.
Ensemble Editors Now Respect Source Control Readonly Property
Although the Ensemble editors, such as the DTL and BPL editors, supported source control systems, they did not prevent you from editing files that were not checked out in the source control system. Although Ensemble would allow you to edit the file, you would not be able to check in your changes. In this release, if source control is enabled for a definition, Ensemble will only allow you to edit the file if you have checked it out and the source control system provides write access.
To make the document editable, check it out and then refresh the page. If you wish to edit a definition that is not checked out, change the name by doing a save as. In the Record Mapper and Complex Record Mapper, you can accomplish this by modifying the RecordMap or Complex RecordMap name before saving.
The Ensemble editors are:
Ensemble X12 Business Service Limits 999 Implementation Acknowledgement to Allowed Transaction Set Codes
In this release the X12 Business Service generates a 999 implementation acknowledgement only for only for HIPAA_5010 (or later versions) batch transactions that define it as a valid reply. In previous releases, the 999 implementation acknowledgement was returned for other transaction sets. In previous releases, the X12 Business Service also returned a 999 implementation acknowledgement for other HIPAA_5010 transaction sets.
X12 Business Services will now construct 999 responses only for X12 batch transactions which have one of the following as their Industry Identifier Code (associated Transaction Set Identifier Codes indicated in parentheses):
If you have code that expects the 999 implementation acknowledgement for other transaction sets, you can either modify this code or overide the OnConstructReply() method to revert the X12 Business Service to the previous behavior.
Compatibility Issues for Upgrades to Ensemble 2016.1
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
EnsLib.REST.Service Handles Query Parameters Differently
In this release subclasses of EnsLib.REST.Service need to get query parameters from attributes not from the URL. In previous releases, it was also possible to get it from the URL when the incoming request came through the CSP port. This change was required to fix problems matching the incoming URL with the URLMap. The query parameters are available as attributes of the stream object passed to OnProcessInput or from the %request object.
Note that we recommend directly subclassing %CSP.REST and not subclassing EnsLib.REST.Service. If you directly subclass %CSP.REST you can use the full features of that class. In order to use a subclass of %CSP.REST in an Ensemble production you need to call CreateBusinessService.
Upgrading Ensemble Sets _Ensemble User to Not Expire
In most cases, the _Ensemble user, which is used by Ensemble internally should be set to not expire and to have the password not expire. In this and future releases, upgrading Ensemble will reset the AccountNeverExpires and PasswordNeverExpires properties to true and notes the changes in the ensinstall log. If your environment requires that one or both of these properties be set to false, you must reset them after upgrading Ensemble.
Business Process Termination Error Now Includes Text from Underlying Error
In this release when a business process encounters an error, the termination error includes the text from the underlying error. If you have error handling code that is comparing the error text, you may have to modify your code.
Ensemble Checks that Default Database Allows Write Access
In this release, Ensemble checks the access to the default database before starting the production. If the default database is read-only, the management portal displays an error and does not start the production. In most cases, this condition is caused by a configuration error and the production would have failed after startup. Although it is not a recommended practice, it was possible to use global mapping to create a production that would work with a read-only default database. This configuration will not work in this release. You must modify the configuration so that the default database allows write access before starting the production.
Inbound TCP Adapters May Report Additional Errors on Startup
In previous releases the inbound and outbound TCP adapters set to be always connected (StayConnected = -1) handled startup differently. If an initial connection is not made within the alert grace Period, the outbound adapter reported an error but the inbound adapter did not. The inbound adapter only reported an error if the adapter was set to have only one listener and an existing connection ended.
In this release the TCP Inbound Adapter set to be always connected behaves the same during start up as the outbound adapter. It reports an error if the initial connection is not made within the alert grace period. This error may be triggered when systems are being brought back online after an outage leading to an Alert On Error if configured. If there is a lag in making the TCP connection in the normal startup, you can avoid this error by increasing the alert grace period.
Option to Improve Restart with Suspended Messages Changes Storage Location
In previous releases, when a production was stopped, any asynchronous messages on the ^Ens.Queue global queue was moved to the ^Ens.Suspended queue and when the production was restarted, they were moved back. For productions with many messages in the queue, this behavior could cause stopping and restarting a production to be slow. In this release, you have the option to avoid this move and the consequent delay in restarting. To avoid the move of suspended messages, set ^Ens.Configuration("Queues","KeepInQueues")=1 per namespace. The default is 0 which is to leave the current behavior.
This change does not have a compatibility impact on your code in your production even if you request the new behavior. But, if you have code that examines suspended messages stored in the database globals while the production is stopped, you should update your code to handle the new option.
Improved Validation of ebXML Messages Changes Behavior
This release includes improved validation of ebXML messages; consequently, some messages that were not valid passed validation in previous releases, but are now treated as errors. Specifically, an ebXML message is considered not valid if both the MessageId and ConversationId are empty. In previous releases, these messages could pass validation.
Additional Log Messages when Disconnecting Java Gateway
In order to successfully close the Java Gateway after a ping operation, this release sends additional send and receive messages to the gateway. This causes additional entries in the log.
Email Outbound Adapter Defaults Change
In previous releases, if there were any errors in the distribution list, the message would not be sent to any recipients. In this release, the message is sent to all recipients except to those addresses with an error. To have the outbound adapter return to the previous behavior and not send email to any recipient, set the ContinueAfterBadSend setting to false.
FTP Failure to Delete Network File Handled Without Reprocessing File
If an FTP adapter is configured to delete the file on the server and fails to then Ensemble should consider the file processed and not reprocess it. In past releases, this behavior was correct if the adapter could not delete the file because of permissions. But, if the adapter could not delete the file because of network problems, it incorrectly treated the file as new and reprocessed it. This problem has been fixed in this release. The adapter will not reprocess the file. If you have coded your production to deal with the past incorrect behavior, you should remove this code.
Router Sets Message Headers Correctly After Timeout
In previous versions, if a router timed out before processing a message, it would not set the message header correctly and the message header could not be purged. This error is fixed in this release. If you have developed a procedure to handle the unpurged messages, it is no longer needed for this condition.
BPL No Longer Allows Two Calls With the Same Name
In previous versions, the BPL wizard did not detect the error of having two calls with the same name. This condition could cause an unexpected call. In this version for synchronous calls that have a response, this error is detected by the BPL wizard. Consequently, BPLs that had this error would have compiled successfully in previous versions, but will trigger an error in this version.
TCP Counted Adapter Now Checks Incoming Length
In previous releases, the TCP counted adapter ignored the incoming length value if there was no character encoding; consequently, if the actual length did not match the specified length, the adapter accepted the message. In this release, the adapter makes this check and rejects the incorrectly formatted message. This change makes the behavior of the TCP counted adapter with no character encoding match its behavior with character encoding, where it has always checked the incoming length.
Disabling a Business Process with a Pool Size of 0
In previous releases if a business process with a pool size of 0 was disabled, all business processes that use the shared actor pool would be disabled. Typically, you only want to disable a specific business process, not all that use the shared actor pool. In this release if you attempt to disable a business process with a pool size of 0, Ensemble displays a warning and the business process is not disabled.
Note:
If you attempt to disable a business process with a pool size of 0, the business process is not disabled and is displayed as green on the production configuration diagram, but the enabled check box is not selected.
If you do want to disable a business process with a pool size of 0, you can do this by setting the pool size to a positive integer. If you do want to stop all business processes using the shared actor pool, set the Actor Pool Size to 0 in the production settings tab.
If you attempt to create a new business process that is disabled and that has a pool size of 0, the business process is created disabled, but the pool size is set to 1. This situation occurs if you:
In these cases, the disabled business process is set to have a pool size of 1 instead of the specified 0.
Improved Check of Permissions for Purging Alerts
The Ensemble Event Log page was failing to enforce the security requirement that the user needs USE permissions on the %Ens_Purge resource to purge event log entries. This is now corrected and the security requirement is now enforced. If a user without the permission clicks on Purge the alert "You are not permitted to perform this action" will be shown and the purge will not be carried out.
XML File and FTP Operations Write Search Table Data
In previous releases, if you specified a search table in an EnsLib.EDI.XML.Operation.FileOperation or EnsLib.EDI.XML.Operation.FTPOperation, the search table index was not created. In this release, the search table index is created. Note that when the message bodies are purged, the search table data is also purged.
Purging Completed Business Process Instances with Null TimeCreated Values
In previous releases completed business process instances might not be purged if the TimeCreated value was null. This situation only occurred if the debug flag was set to retain business process instances and custom code updated the TimeCreated value, which should not be set by user code. In this release, even in this case, the completed business process will be purged as expected.
Compatibility Issues for Upgrades to Ensemble 2015.2
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Compatibility Issues for Upgrades to Ensemble 2015.1
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
New Global and Database Used to Store Credentials Passwords
When you create a new namespace, credentials passwords are stored in a secondary database, which is, by default, not accessible to user accounts. For most productions this does not create a compatibility issue because Ensemble provides access to the password when it is needed by the business host. This change provides increased protection for stored passwords. Note that InterSystems recommends that you encrypt any database containing credentials passwords.
There are some conditions where this change can cause a compatibility issue. This section describes these conditions and ways you can avoid problems.
Note:
Some Ensemble licenses limit the number of databases allowed. This new credentials database is counted towards the limit.
When you create a new namespace, Ensemble creates a secondary database and names it by appending SECONDARY to the globals database name. For example, if you create the INVENT namespace with the INVENTG database for globals and the INVENTR database for routines, Ensemble also creates the INVENTGSECONDARY database for credentials passwords. In previous releases, Ensemble stored the credentials password in the ^Ens.Conf.CredentialsD, but in this release, Ensemble stores credentials passwords in the global ^Ens.SecondaryData.Password and maps that global to the secondary database.
For existing namespaces, upgrading Ensemble does not create the new secondary database, but when you first access credentials, the passwords are moved to the new global. If you call the %Library.EnsembleMgr:CreateNewDBForSecondary() method, Ensemble creates the secondary database for credentials passwords, migrates the password to the new secondary database, and maps the ^Ens.SecondaryData.Password to the secondary database. You should only call the CreateNewDBForSecondary() method when the production has been stopped.
In most cases, these changes do not impact production code or accessing credentials through the management portal, but it does create the following compatibility issues:
Note:
If you are running an instance of HealthShare, it does not create the secondary database for credentials passwords unless you explicitly call the CreateNewDBForSecondary() method. Do not call this method for a namespace used in a HealthShare Information Exchange.
New Databases and Changes to Where Temporary Globals are Stored
The Runtime and JobStatus data is now stored in the global ^CacheTemp.EnsRuntimeAppData subscripted by namespace. In previous versions, this data was stored in the global ^Ens.RuntimeAppData. In addition, metrics data, which is used for display in the production monitor, is now stored in the global ^CacheTemp.EnsMetrics. In previous versions, this data was stored in the global ^Ens.Metrics. In most cases, these changes do not cause a compatibility issue, but you should ensure the following:
Since these globals are now stored in a non-journaled database, the values are not available to mirror members.
Note:
Some Ensemble licenses limit the number of databases allowed. This new database for temporary globals is counted towards the limit.
JDBC SQL Returns Large Objects as Streams instead of Strings
When using JDBC SQL adapters, stored Procedure large object (LOB) output parameters are now returned as streams. In previous versions, these output parameters were returned as strings, which caused errors when the LOB exceeded the maximum string size. You should modify any code that accesses these output parameters to handle streams instead of strings.
As a temporary workaround, you can set globals to return string values for these output parameters. But even with these globals set, if the size of the LOB exceeds the maximum string size, the output parameters are returned as streams.
To configure Ensemble to return LOB output parameters as strings when size permits, set one of the following globals to 1:
Lookup Table Import and Export Format Changed to be Compatible with Studio
The Ensemble portal Import and Export buttons now use the same file format as Studio. In previous versions of Ensemble the portal export format was incompatible with the Studio export format.
If you exported a lookup table with the portal from a previous version of Ensemble, you must use the Import Legacy button on Ensemble 2015.1 or later to import it. If you are exporting a lookup table from Ensemble 2015.1 or later and intend to import it with an earlier version of Ensemble, you must import it on the earlier version using Studio; you cannot use the portal import.
Deleting X12 Objects Deletes Child Objects
In previous releases, deleting an X12 object would not delete its child objects. In this release, when you delete an X12 object, all its child objects are deleted.
DTL foreach Error Reported Correctly
Under some circumstances in previous releases, a Data Transformation would not report an error if you included the iterator key within the parentheses in a foreach. This error is now correctly reported.
Compatibility Issues for Upgrades to Ensemble 2014.1
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Also review the Caché 2014.1 Upgrade Checklist.
HL7 Sequence Manager Automatically Adds Index
The HL7 Sequence Manager, which ensures that HL7 messages are processed in the correct sequence, has added an index to improve efficiency. If your production has a business process that has a class of EnsLib.HL7.SequenceManager or a subclass of it, it automatically creates an index to improve performance when it processes its first message after the upgrade to Ensemble 2014.1.
You can manually create this index after an upgrade to Ensemble 2014.1 before this business process starts processing messages by doing the following:
  1. Ensuring that the Sequence Manager business process is stopped.
  2. Start the Ensemble terminal and set it to the namespace used for the production.
  3. Enter the following command:
    Set tSC=##class(EnsLib.HL7.SM.Version).Upgrade()
  4. Check tSC for an error status to ensure that the command executed correctly.
New Security Resource to Control Exporting Deployment Packages
In this release, the %Ens_DeploymentPkg security resource controls the ability to export a deployment package and the %Ens_Deploy security resource controls the ability to apply a deployment package to a production. In previous releases %Ens_Deploy controlled both of these abilities.
Ensemble HL7 Supports Long Strings
In this release, the Ensemble HL7 framework can take advantage of long strings when they are enabled for a system. See Support for Long String Operations in Caché Programming Orientation Guide for details on enabling long strings. To maintain the existing 32K limit on segment storage even if long strings are enabled, you can set ^Ens.Config("HL7-NoLongStrings") = 1.
GetProductionStatus Returns Improved Status Information
In this release, the GetProductionStatus() method may return localized text providing status information. If you are testing the return value you should use the StatusEnum field, which contains the numeric state value and will be consistent across all locales.
Ens.Settings has New GetSettingRow Method
The Ens.Settings class has a new GetSettingRow() generated method. If you have extended the Ens.Settings class and have previously defined a method with this name in the class, you should update your code. Rename your extension method before recompiling your code to avoid the method name collision.
Ensemble CSP Pages Set UseCookies Property
Ensemble now sets the UseCookies property to “Always” when the system is upgraded or a new CSP page is created.
Viewing EDI Raw Contents Inserts Newlines for Consistency
If you display the raw contents of an EDI message, Ensemble ensures that there is always a newline character between segments. In previous versions, some but not all segments were separated by newline characters. Consequently, if you copy and paste the text in the raw content display, the data from this release may contain newline characters that were not present in the data produced by the previous release.
Improved Handling of Spaces in FTP File Names
The FTP Inbound Adapter assumes that any spaces after the FTP file name are part of the file name and do not delimit other fields. This change allows the FTP Inbound Adapter to handle FTP servers that may include spaces in file names. The FTP Inbound Adapter, consequently, cannot support an FTP server that uses a space to terminate a file name and includes other fields after the file name.
Ensemble Automatically Recompiles VDOC Search Tables During Upgrade
When you upgrade to Ensemble 2014.1, it automatically recompiles all user-defined subclasses of Ens.VDoc.SearchTable in all Ensemble namespaces.
Ensemble Custom Schema Validation Reports Errors at Compile Time
In 2014.1, the validation of HL7 custom schemas has been improved and more errors will be shown when loading or saving a schema. For example, a message structure that was missing a closing } would show no errors when saved under 2013.1 but will give an error “ERROR #5002: Cache error: Mismatched braces '{' and '}' in message structure …” when loaded or saved on 2014.1. If a database containing an invalid message structure is upgraded, there will be no error during upgrade, but any later attempt to save the schema from studio or the schema editor will give an error. The run time behavior of a schema with this type of error is unpredictable and the newly identified error should be corrected. You should consider correcting the error on any prior version that is still running with the schema in question.
Port Declaration Property for TCP adapter Changed
In 2014.1, Port property used by EnsLib.TCP.InboundAdapter is declared as type Ens.DataType.TCPAgentPort, which has its own declaration and extends %String. In previous releases, the Port property was declared in the superclass EnsLib.TCP.Common as type %Integer. If you have developed a custom adapter class that subclasses EnsLib.TCP.InboundAdapter and declares Port as %Integer with MAXVAL and MINVAL qualifiers, compiling the class produces an error. To fix this error, you can declare Port as Ens.DataType.TCPAgentPort and remove any MAXVAL and MINVAL qualifiers.
Change in Handling HL7 Message Header Name Field
Ensemble calculates the HL7 message name based on the value of the MSH:9 field. This change modifies how Ensemble treats the MSH:9.3 subfield.
HL7 messages may use MSH:9.3 subfield in one of two ways: 1) to qualify the message name, typically with a number, or 2) to specify the message structure type. For example, if MSH:9 has the value “ORM^001^5”, MSH:9.3 has the value “5”, which describes a subtype of the ORM_001 message. But if MSH:9 has the value “ADT^A08^ADT_A01”, MSH:9.3 has the value “ADT_A01”, which specifies that the ADT_A08 message has the ADT_A01 structure type.
When Ensemble processes the MSH:9 field it tests whether the MSH:9.3 subfield has a simple value, such as “5”, or a structured value, such as “ADT_A01”, If it has a simple value, Ensemble appends the value to the message name and uses the message name to find the structure in the schema and to set the value of the Name property. If MSH:9.3 has a complex value, Ensemble ignores the value. Since Ensemble uses the schema definition to reliably get the message structure type, it does not need to use this value.
If you set the global ^Ens.Config("HL7NamePropOld")=1, Ensemble uses its original logic in handling MSH:9 and always appends the MSH:9.3 value to the message name, even if it represents a structure type. Set this global in the namespace used for the HL7 production.
Changes in HL7 Schema Representation
Ensemble 2014.1 includes the following enhancements in the HL7 schema definitions:
To implement these changes, we made changes in how the HL7 schema elements are stored internally in globals and minor changes to their XML representation. In most cases, these changes will not cause compatibility problems. However, if you are doing any of the following, you should check for compatibility issues:
Compatibility Issues for Upgrades to Ensemble 2013.1
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Also review the Caché 2013.1 Upgrade Checklist.
Simplified X12 Schema Representation
In this release, when you load a SEF file into Ensemble, Ensemble converts the schemas into a format that is simpler than the raw SEF definition. This simplified X12 schema format can be exported as XML and edited in Studio. The main simplifications of the schema format are as follows:
It is necessary to adjust any X12 virtual property paths that you created in Ensemble version 2012.1 or earlier.
Need to Perform Cleanup after Upgrading from Previous Versions
If you upgraded Ensemble from a previous version to version 2012.2, 2012.2.1, or 2012.2.2, the upgrade process cleaned up the UTC index. In some installations, this cleanup process took an extended time and delayed the upgrade process. In Ensemble 2012.2.3, Ensemble 2013.1, and later versions, this cleanup process is not automatically done during the upgrade but should be done manually after the upgrade. If you have already upgraded a system to Ensemble 2012.2.1 or 2012.2.2, the cleanup process has been completed and you do not need to do anything for any future upgrades.
If you are upgrading from Ensemble 2009.1 or earlier, some message headers or log entries won’t be visible until after you run the cleanup procedure. Consequently, you should run the cleanup procedure soon after upgrading Ensemble. If you are upgrading from Ensemble 2010.1 or later, you can run the cleanup procedure at a convenient time after upgrading Ensemble.
If you are upgrading from Ensemble 2012.1 or earlier to Ensemble 2012.2.3, Ensemble 2013.1, or a later version, follow this procedure:
  1. When Ensemble is being upgraded, it detects whether any namespaces on the system need the UTC index cleanup. If any namespaces need the cleanup, Ensemble logs a warning to cconsole.log indicating each namespace that needs to be cleaned up.
  2. Check the cconsole.log file after upgrading to find the namespaces that need to be cleaned up.
  3. After the system has been upgraded and Ensemble is running normally, you can run the cleanup on each namespace that requires it. You may wish to run the cleanup at an off-peak time when the system load is low. To run the cleanup for a specified namespace, enter the following in Ensemble Terminal:
    zn <namespace>
    Do ##class(%Library.EnsembleMgr).UpgradeUTCIndices()
You can also check to see if a namespace requires the UTC index cleanup by entering the following at the terminal:
Do ##class(%Library.EnsembleMgr).CheckUTCIndices(<namespace>,1,1)
If the namespace needs cleanup, CheckUTCIndices displays a message indicating that cleanup is required for the specified namespace. Otherwise it displays a message indicating that no UTC index globals need repair.
Improve Access to ASTM Documents by Building Index
Ensemble 2012.1 and later versions provide improved access to ASTM documents by adding an index for the OriginalDocId field. If you have created your production with Ensemble 2012.1 or later, this index is present for all ASTM documents. However, if you created your production with Ensemble 2010.2 or an earlier version and then have upgraded to 2012.1 or a later version, the index is created for new documents, but any existing documents created with the earlier version will not have the OriginalDocId index.
After upgrading Ensemble, if you have ASTM documents, you should build the index for the OriginalDocId field. You can build the index while the production is running, but you cannot build the index while ASTM messages are being purged or deleted. To rebuild the index, enter the following in Ensemble Terminal for each namespace that contains ASTM documents:
zn <namespace>
Do ##class(EnsLib.EDI.ASTM.Document).%BuildIndices("OriginalDocId")
For information on ASTM documents, see the Ensemble ASTM Development Guide.
Enable Access to DeepSee Dashboard Pages
Beginning in this release, application access to arbitrary %CSP pages, including DeepSee, can now be better controlled. By default, only the SAMPLES namespace can access DeepSee pages, including dashboards. To enable DeepSee access in the ENSDEMO namespace and its associated web application, /csp/ensdemo, enter the following command in an Ensemble terminal window:
Do EnableDeepSee^%SYS.cspServer("/csp/ensdemo/")
You should enter this command for any namespace that uses DeepSee dashboards or other DeepSee pages. In order to find the name of the web application associated with an Ensemble namespace, go to the [System Administration] > [Security] > [Applications] > [Web Application] page in the Ensemble management portal. Note that for HealthShare installations, the web application name is /csp/healthshare/ensdemo. Alternatively, you can enable DeepSee access for all namespaces and web applications by entering the following command:
Do EnableDeepSee^%SYS.cspServer(0)
For a detailed description of this issue, see Application Access To %CSP Pages Now Controlled in the Caché 2013.1 Upgrade Checklist.
Compatibility Issues for Upgrades to Ensemble 2012.2
The following changes in this release may affect the operation of your existing system. Review these following issues before upgrading a previous instance of Ensemble.
Also review the Caché 2012.2 Upgrade Checklist.
New Compiler Behavior for DTL Classes
In previous releases, the system threw an exception when you compiled a DTL and the source or target class does not exist. This means that your compiled DTL code was at risk of being incorrect. Now the compiler reports an error and fails if the source or target class does not exist.
New DTL Classes Created with IGNOREMISSINGSOURCE Parameter Set to True
Previous to this release, all DTL data transformation classes inherited from Ens.DataTransformDTL had the IGNOREMISSINGSOURCE 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 IGNOREMISSINGSOURCE = 1;
With this parameter value, the DTL suppresses errors caused by attempts to get field values out of absent source segments. The DTL also skips calling subtransforms where the named source segment is absent.
However, to maintain compatibility for existing DTL data transformation classes, the default behavior of the abstract class has not changed, and your existing DTL classes behave as in the past. The Ens.DataTransformDTL class declares the following:
Parameter IGNOREMISSINGSOURCE = 0;
You can review your transformations to see if updating the value of this parameter makes sense in your application.
Rules Conversion and Upgrade
During an upgrade to Ensemble 2012.1 or later, Ensemble ensures that any existing business rules are correctly converted and upgraded. As part of this conversion, Ensemble clears the custom function cache before performing the conversion. The cache is cleared initially to ensure that the correct resolution is performed while converting the rules.
In addition, the upgrade code compiles any custom FunctionSet classes (subclasses of Ens.Rule.FunctionSet) that need to be recompiled before converting and compiling rules created using the rules engine in 2010.2 and older. You should ensure that any mapped FunctionSet classes can be compiled in their target namespaces.
Change in Operator Precedence in Business Rules and Routing Rule Conditions
In release 2012.1, the precedence of conditions in rule conditions was not always correct. In particular, comparison operators took precedence over arithmetic and concatenation operators, so an expression of the form ‘a+b=c’ was being evaluated as ‘a+(b=c)’. In 2012.2 this is correctly evaluated as ‘(a+b)=c’.
If you have written rules in 2012.1 that relied upon this incorrect behavior, those rules will no longer function correctly and the rules will have to be changed. Note that the Visual Rule editor adds parentheses to conditions and there is no problem.
Conditions in rules upgraded directly from 2010.2 or earlier to 2012.2 will execute correctly.
Conditions in rules upgraded from 2010.2 or earlier to 2012.1 may not execute correctly in that version. After a subsequent upgrade to 2012.2 these rules will once again execute correctly.
Compatibility Issues for Upgrades to Ensemble 2012.1
The following changes in this release may affect the operation of your existing system. Review the following issues before upgrading a previous instance of Ensemble:
Also review the Caché 2011.1 Upgrade Checklist and the Caché 2012.1 Upgrade Checklist.
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.RuleLog class (SQL table Ens_Rule.RuleLog). The new rule log is stored in Ens.Rule.Log (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.
Important:
You cannot view business rule log entries created prior to an upgrade to Ensemble 2012.1 on the [Ensemble] > [Rule Log] page in the new Management Portal.
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.LegacyRuleLog page is subject to the same security restrictions as the EnsPortal.RuleLog 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 WRC 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:
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.MessageHeader 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.MessageHeader 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.MessageHeader 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.
Important:
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 from the [Home] > [SQL] > [Schemas] > [Tables] page of the Management Portal, see ExtentSize and Selectivity in the chapter “Optimizing Performance” in Using Caché SQL.
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 WRC 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.
Note:
After the upgrade to this release, your existing search tables contain updated metadata in the appropriate namespaces; you do not need to recompile them. However, you must follow the described compile procedure for any search tables you add or change.
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.SearchTable entry in the Class Reference for details.
Note:
Running the EnsLib.HL7.SearchTable.BuildIndex() class method generates journal entries and could take time. You can run it while messages are processing and you can run it in batches specifying a start and end ID. You do not need to include messages processed since the upgrade.
New DTL Classes Created with REPORTERRORS Parameter Set to True
Previous to this release, all DTL data transformation classes inherited from Ens.DataTransformDTL 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.DataTransformDTL 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.Item 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.MsgBankOperation) 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.Item class to permit the use of Default Settings to populate this value.
The original InactivityTimeout property of the Ens.Config.Item 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:
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.
Compatibility Issues for Upgrades to Ensemble 2010.2
The following changes in the 2010.2 release may affect the operation of your existing system. Review the following issues before upgrading a previous instance of Ensemble:
Also review the Caché 2010.2 Upgrade Checklist.
Remove Support for HL7v2 Framing with XML Text
This release of Ensemble removes support for all HL7 framing options that involve XML text being detected or generated in between successive HL7 message bodies in an HL7 data stream. This is an undocumented feature InterSystems believes no one is using. If you are using any of these options, contact the InterSystems WRC.
Update Error Handling on HTTP Outbound Adapter
This release of Ensemble updates HTTP outbound adapter processing to return an error status code (<Ens>ErrHTTPStatus) if the HTTP status it receives is something other than 200 (OK). Also, the adapter now sets the retry flag if it receives a status of 503 (Service unavailable due to a temporary overloading or maintenance of the server). The introduction of the new status code makes error handling more accessible to the Reply Code Actions setting feature. See Reply Code Actions in the reference section of Configuring Ensemble Productions.
This change also updates the HL7 HTTP outbound adapter to return the indicated ACK commit code according to the HTTP status conditions shown in the following table.
ACK commit code HTTP status condition
AA 200 — OK code
AR 503 — Service Unavailable due to a temporary overloading or maintenance of the server
AE All other non-OK codes
See HL7 Acknowledgement (ACK) Mode in the Ensemble HL7 Version 2 Development Guide for more information.
If you have code that expects a $$$OK status returned from methods of the HTTP outbound adapter even when the remote HTTP server returns a non-OK status, you may need to update the code to either change the error handling or configure the Reply Code Actions setting to recognize the new error code.
Update Error Processing in File Outbound Adapter
This release of Ensemble improves the error status checking and error trapping in the PutStream() method of the EnsLib.File.OutboundAdapter.
Change Return Status on HTTP Inbound Adapter
This release of Ensemble changes the HTTP inbound adapter return status to a server error instead of OK if the ProcessInput() method returns an error status.
If you have clients invoking an Ensemble service that uses the HTTP inbound adapter you may now see an HTTP error status code (500) when an error occurs in the Ensemble service, when formerly you saw an HTTP OK (200) status. This does not disrupt normal operation because it only affects behavior when the HTTP service fails. Additionally, Ensemble still returns its non-standard <error> block body. It is unlikely that your service has customized behavior based on this returned status; however, this change may trigger a different code path in your error handler and therefore you should review this code.
Add Requirement to Subclass Message Bank Production
This release of Ensemble changes the Ens.Enterprise.MsgBank.Production class to be an abstract class and adds a requirement that you must subclass it and copy the ProductionDefinition XData block, to run a Message Bank instance. This allows you to run multiple message banks in separate namespaces on the same instance, and it prevents future upgrades from deleting your configuration setting changes. It also removes an obstacle to allowing you to mark your ENSLIB database as read-only.
If you are an early adopter of the Message Bank from a previous release, you must copy your Message Bank production class (Ens.Enterprise.MsgBank.Production) to a subclass before upgrading. If you do not, the upgrade will overlay your configuration changes, and will not allow you to restart the common Message Bank production or reapply your configuration settings.
Update Disable Behavior of Business Processes
This release of Ensemble refines the behavior of disabling a business process. The behavior depends on the private Pool Size configuration setting of the business process:
If you upgrade to this release and your production contains a business process with Pool Size = 0, disabling the process now has different behavior.
For a detailed discussion of pool sizes, see Pool Size in Configuring Ensemble.
Compatibility Issues for Upgrades to Ensemble 2010.1
The following changes in the 2010.1 release may affect the operation of your existing system. Review the following issues before upgrading a previous instance of Ensemble:
Also review the Caché 2010.1 Upgrade Checklist.
Relocate RemoveItem() Configuration Method
In this release, Ensemble moves the RemoveItem() method from the CSPX.EnsConfigProperty class to the Ens.Config.Production class; it is now available for general use and not exclusively from the Ensemble Management Portal configuration page.
Calls to the undocumented CSPX.EnsConfigProperty.RemoveItem() method in your code, receive a <METHOD NOT FOUND> error. In the unlikely event you use this method, update your code to now use the Ens.Config.Production.RemoveItem() method. Instead of passing your production object as an argument, the new method is an instance method of your production object.
Add Configuration Setting on TCP Counted Outbound Adapter
This release adds a new FlushBeforeSend configuration setting to the TCP Counted Outbound Adapter. When set to True, this option causes the SendMessageStream() adapter method to do a zero-timeout read of all data pending in the inbound TCP buffer before writing its outbound data and optionally reading any subsequent returning data.
If you had implemented a block protocol using the TCP Counted Outbound Adapter in previous releases of Ensemble, you must override the default setting.
Correct Type Node in HL7 Sequence Manager Global
In previous releases, the Type subscript ^EnsHL7.SM("output",type) incorrectly used PerformOutputTransformationOn. The class documentation for EnsLib.HL7.SM.RuntimeData has been updated. See the entry in the Class Reference for details.
Existing applications will encounter problems if they have PerformOutputTransformationOn set to SequenceNumberOnly. If so, and you want to keep the existing output sequence number, perform the following:
Merge ^EnsLib.SM("output","Sender")=^EnsLib.SM("output","SequenceNumberOnly")
Also verify that your PerformOutputTransformationOn and OutputSequenceNumberIndexField are consistent.
Correct Behavior of HL7 Configuration Framing Setting
This release corrects the behavior of HL7 business services and business operations when you configure the Framing setting to have a value of None. This value now results in no framing characters being generated between HL7 messages as opposed to the previous behavior that used whatever framing was declared as the default in the relevant context.
Productions configured with Framing=None for various configuration items may be experiencing incorrect framing behavior that works in your context. This change corrects the behavior which may cause your production to stop working. For example, you may be sending outbound files to an entity expecting an ASCII LF between messages; even though the file operation is configured to put nothing between messages because previously it had been erroneously generating the LF between messages.
Add Support for Legacy FTPS Protocol to FTP Adapters
Release 2009.1 of Caché implemented the RFC4217 standard method of creating a secure FTP transfer, and it also removed the previous legacy mode which assumed that the command channel was to use TLS. However, some Ensemble implementations using FTP adapters were using this mode. The current release reintroduces this legacy connection mode with a special way in the FTP adapter configuration to indicate its use.
If you have been using the old non-standard FTPS protocol first implemented in the %Net.FtpSession class, you may find that your FTP adapters no longer work with the FTP servers to which they have been connecting. To restore proper functioning of the adapter, append an asterisk (*) to the SSLConfig property of the appropriate EnsLib.FTP.InboundAdapter or EnsLib.FTP.OutboundAdapter class.
See the SSLConfig property description in the EnsLib.FTP.Common entry of the Class Reference for details.
Changes in Mapping of Custom Schemas
In previous releases, your custom HL7 and EDI schemas were stored in the ENSLIB namespace; therefore, they were mapped to every namespace. However, the Ensemble upgrade procedure replaces everything in the ENSLIB namespace, so you would have to export and then import your defined schemas to save them when you upgraded.
Beginning with Ensemble 2007.1, only the standard schemas are available in all namespaces. Ensemble now stores all custom HL7 and EDI schemas in the namespace where you define them. If you depended on centrally located schemas in your previous Ensemble version, you must now compile your user-defined schemas in each namespace where you use them.
Compatibility Issues for Upgrades to Ensemble 2009.1
The following changes in the 2009.1 release may affect the operation of your existing system. Review the following issues before upgrading a previous instance of Ensemble:
Also review the Caché 2009.1 Upgrade Checklist.
Changes in HL7 Storage Structure
This release of Ensemble changes the storage structure for HL7 message segments to avoid block contention and improve throughput of large systems.
Ensemble now stores message segments in the new format and converts old message segments to the new format the first time it opens the message as an object. Access to HL7 messages from SQL and from the Management Portal is compatible with both formats.
This change is transparent to most applications; however, if you have code that directly accesses or manipulates the segment globals, you must modify it to be compatible with the new structure. Contact the InterSystems WRC for advice and guidance if you need to make such changes.
New ReplyCodeActions Property in Process and Operation Classes
This release introduces a new property, ReplyCodeActions, for all business process and business operation classes. Formerly, this setting was available only on HL7 TCP business operations. This property allows you to specify how the host should handle each kind of response it receives from the remote system.
This change adds a boolean return value to the existing business operation callback method OnFailureTimeout(). If you added an override of this method to your business operation classes, you must add Quit 0 to your implementation to preserve your custom behavior, and As %Boolean to your method signature for it to compile.
This update also changes the format and default behavior of the existing ReplyCodeActions property for HL7 business operations. If you are indicating a literal value found in field MSA:1 or using one of the described special values, you must start your reply code with a colon (:). See the description of the ReplyCodeActions property in the EnsLib.HL7.Operation.ReplyStandard entry in the Class Reference for details.
If you upgrade to this release and your production configuration has existing reply codes of this type that do not begin with a colon (:), Ensemble logs warnings in the Event Log for the item by the OnGetReplyAction() when the production starts. For example:
Unrecognized reply code: '?E'
Unrecognized reply code: '?R'
Unrecognized reply code: '~'
There were also other changes to the default behavior of properties that may affect your production:
Changes to Default Behavior of HL7 Business Operation Reply Code Actions
A previous release updated and expanded the default behavior of the ReplyCodeActions property with a value of:
:?R=RF,:?E=S,:~=S,:?A=C,:*=S,:I?=W,:T?=C
This default indicates that Ensemble retries messages with acknowledgment codes AR or CR; for those with codes AE or CE, it suspends the current message, logs an error, and moves on to the next message. This behavior is more consistent with common HL7 processing. The new default also treats any message with codes AA or CA as Completed OK and suspends messages that have a value in field MSA:1 that is not matched by any other listed reply code.
Changes to Default Behavior of Business Operation Retry Count
This release redefined the meaning of the RetryCount property from “the number of the current try not counting the first try” to “the number of the current try” by setting the default in the business operation class to a value of 1.
New Mechanism for Editing Messages Replaces the %DrawEditForm() Method
This release removes the Ens.Util.MessageBodyMethods.%DrawEditForm() method, which the Ensemble Management Portal called to display a message-specific content editor. A different mechanism now provides this functionality. See the following sections in the chapter “Viewing, Searching, and Managing Messages” of Monitoring Ensemble Productions for details:
Increased Alert Level for Data Transformation Errors
In previous releases, Ensemble did not trigger an alert when it encountered an error in a data transformation; errors were only logged in the Event Log. Ensemble now reports such errors as alerts if you enable the Alert On Error setting for the routing engine configuration item.
Changes to Pool Size Configuration Behavior on TCP Service
For TCP services, when Job Per Connection is True, a freshly spawned job handles each new incoming socket connection rather than the listener job itself. Only one job at a time can be the listener, and one job must be the listener, so a TCP service configured with a Pool Size greater than 1 still only starts one listener job. However, this listener can spawn an unlimited number of connection jobs if Job Per Connection is set to True. If you set the Pool Size to a value greater than 1, it serves as a limit on the number of simultaneous connection jobs that can exist. When this limit is reached, the listener does not accept any more connections until one or more of the existing connection jobs quits or dies. An Event Log warning appears when it first reaches the limit.
Renamed Column in Statistics Queries
This release of Ensemble renames a column in the EnumerateHostStatus() and EnumerateJobStatus() queries in the Ens.Util.Statistics class from LastAction to LastActivity. If your application refers to the column by name, you must update it.
Alert Support for Services Invoked Outside Ensemble
This Ensemble release adds error alerting and logging to the ProcessInput() method of business service classes when you invoke the service from a job not started by Ensemble and, therefore, not running in its OnTask() loop. The main examples of services invoked in this way are SOAP services and CSP web pages, but may also include language binding and stored procedure calls.
Changes in Empty Schema Category Behavior
In previous releases, if a data transformation processed an HL7 message that had no schema category associated with it, Ensemble modified the source message to have the schema category expected by the data transformation. In this release, the schema category remains empty. It is possible that if a message passed through multiple data transformations or routing engines, it may now fail in subsequent transformations or routing engines. To avoid this problem, specify the schema category in the business service.
Compatibility Issues for Upgrades to Ensemble 2008.2
Review the Caché 2008.2 Upgrade Checklist.
Compatibility Issues for Upgrades to Ensemble 2008.1
The following changes in the 2008.1 release may affect the operation of your existing system. Review the following issues before upgrading a previous instance of Ensemble:
Also review the Caché 2008.1 Upgrade Checklist.
DTL Validation Errors
In Ensemble 2008.1 and later, including this release, DTL validation is more strict than in the past. As a result, if a DTL code block contains an <assign> element with value='' and any of the following action values:
action='append'
action='insert'
action='set'
The code fails to compile, because a non-empty value is mandatory in these cases. Upon upgrade from a previous version to Ensemble 2008.1 and later, errors appear when user classes are recompiled. The error message is:
ERROR <Ens>ErrDTLNodeValidation: 'value' must NOT be empty string for action 'Assign'
If you have any DTL <assign> elements with value='' you must change this text to:
value='""'
This convention adds a pair of double quotes to indicate the null string.
AllowSessions Setting Removed from EnsLib.SOAP.Service
In the 2008.1 Ensemble release, the AllowSessions setting was removed from the EnsLib.SOAP.Service class. It is no longer configurable; instead, you must choose whether the service should use CSP/SOAP sessions at compile time using the SOAPSESSION class parameter. The default for the parameter is now SOAPSESSION = 0.
If your subclass of EnsLib.SOAP.Service relies on the AllowSessions setting to control session behavior, you must rewrite it to use the SOAPSESSION class parameter. If you are using sessions you must override it to SOAPSESSION = 1. If you do not use sessions, do not override the SOAPSESSION class parameter; you can rely on the default setting.
See Enabling SOAP Sessions in the chapter “Creating an Ensemble Web Service” in Creating Web Services and Web Clients with Ensemble.