Skip to main content

Release and Upgrade Information for Ensemble 2014.1

New Features in Ensemble 2014.1

Ensemble 2014.1 introduced the following new features and enhancements:

  • REST services and operations

  • Pass-through HTTP, REST, and SOAP services and operations

  • Alert management

  • HL7 Version 2 field-level validation and schema editor enhancements

  • Enhanced production export and import from the portal

  • XML VDoc enhancements

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é Release Note and 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.SettingsOpens in a new tab class has a new GetSettingRow() generated method. If you have extended the Ens.SettingsOpens in a new tab 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.SearchTableOpens in a new tab 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.InboundAdapterOpens in a new tab is declared as type Ens.DataType.TCPAgentPortOpens in a new tab, which has its own declaration and extends %StringOpens in a new tab. In previous releases, the Port property was declared in the superclass EnsLib.TCP.CommonOpens in a new tab as type %IntegerOpens in a new tab. If you have developed a custom adapter class that subclasses EnsLib.TCP.InboundAdapterOpens in a new tab and declares Port as %IntegerOpens in a new tab with MAXVAL and MINVAL qualifiers, compiling the class produces an error. To fix this error, you can declare Port as Ens.DataType.TCPAgentPortOpens in a new tab 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:

  • Segment length—In previous versions, you could only define the length of segments, which set the maximum length allowed. In this release, you can specify the minimum and maximum length of segments.

  • Components of data structure—In this release, you can specify the component minimum length and maximum length and whether the component is optional or required.

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:

  • Accessing the ^EnsHL7.Schema or ^EnsHL7.Description globals directly. These are internal Ensemble structures and may be changed to implement new Ensemble features.

  • Calling the EnsLib.HL7.Util.Generator method to generate the XML representation of the schema and then explicitly accessing the component length attribute or the data structures component. Specifically, the component length was specified by the length attribute in previous versions but is specified by the max_length attribute in Ensemble 2014.1. The same restriction applies if you generate the XML schema by exporting from the portal or from Studio.

  • Calling the EnsLib.HL7.SchemaOpens in a new tab DataStructures query. This query returns additional information, specifically, information about the elementary data types. If your code is dependent on the data returned by this query, there may be compatibility issues.

  • Exporting an HL7 schema in Ensemble 2014.1 or later and then attempting to import it into an earlier version of Ensemble. The earlier version of Ensemble will encounter errors caused by the new segment length attributes and component data structure. You can export an HL7 schema using an older version of Ensemble and then import it into Ensemble 2014.1 or later.

FeedbackOpens in a new tab