Disclaimer

The CONNECT Solution Release 2.1 is published as an alpha version of the CONNECT software. Known defects in the product are listed below. However, defects which may occur within the product are not limited to these issues. The product and accompanying written materials are provided "as is" without warranty of any kind. This software is not warranted or guaranteed, nor are any representations made regarding the use, or the results of use, of the product in terms of correctness, accuracy, reliability, currentness, or otherwise. The Federal Health Architecture (FHA) shall not be held liable for any direct, indirect, consequential or incidental damages arising out of the use of or inability to use this product.

Major Modifications Since Release 2.0

This section lists the major changes that have occurred between Release 2.0 and Release 2.1.

The Release 2.0 version of the gateway introduced an architecture that allows for customization of key components without the need to modify "core" gateway code. However, that version of the gateway used demonstration versions of several key components. In particular, the MPI was represented by a text file; the policy engine was written to support a single rule of opt-in/opt-out for a patient; the document repository was a roll-your-own application. In general, these components were good enough to demonstrate the functionality of the gateway, but were not robust enough to take into a production environment. Furthermore, because these were all developed internally, these components would need to be maintained by the CONNECT development community.

The primary goal of Release 2.1 is to introduce "Enterprise Service Components" (ESC's) that fulfill the role of these components. The criteria for the 2.1 ESC's is a system that is robust enough to use in a production environment, is open source, and has its own community to support it. The selected systems are listed below under "more detail".

The development group recognizes that there are two competing needs for the gateway out-of-the-box. For the first set of needs, some groups will appreciate the ESC's because this will be a set of tools already integrated with CONNECT, allowing a group the quickest path to production with a robust toolset. For the second set of needs, some implementers are not interested in the ESC's, either because they are planning on integrating their own systems or because they are more in the exploratory development phases. This group is more interested in getting the gateway up-and-running as quick as possible with as small of a footprint as possible.

To accommodate both needs, the main installation/configuration is based on a core gateway/adapter, with light-weight implementations for the adapter components. Separately, a set of "plug-ins", including the ESC's, are available for download. This allows for the implementer to choose the set of tools that is appropriate for them.

This also sets a "framework" for distribution of other "plug-ins" in the future. As the new wizz-bang MPI becomes integrated with CONNECT, the artifacts (instructions, adapter code, etc) can become available for download from the portal.

More detail, and other highlights of the release are listed below.

• Mural has been integrated as the Adapter MPI ESC, and is available as a CONNECT plug-in. Mural provides a rich set of tools for modeling a patient data model and robust matching algorithms. Mural's primary responsibility as the gateway's MPI is to respond to a "find candidates" message during subject discovery.
• The NIST Document Repository has been integrated as the Adapter Document Registry and Repository, and is available as a CONNECT plug-in. The NIST software is an implementation of the IHE XDS specification for a document registry and repository actor. The software is responsible for storing and registering an adapter's patient related medical documents (including a patient's consent document) for later query and retrieval.
• OpenSSO has been integrated as the Adapter Policy Engine, and is available as a CONNECT plug-in. OpenSSO is used by the Policy Enforcement Point (PEP) as a means for sending an XSPA based XACML policy request to a Policy Decision Point (PDP).  An implementation of the PDP was also created using OpenSSO.
• A Jericho Policy Decision Point (PDP) has been integrated as a second PDP option for the the Adapter Policy Engine and is available as a CONNECT plug-in.
• HIEM has been refactored to be more configuration driven. The primary intent here is to be able to respond to future "topics" with little-to-no gateway code change. The adapter/entity interfaces have been modified from a per-topic interface (i.e. Subscribe to Documents) to a more generic interface in-line with the WS-BaseNotification specification (i.e. Subscribe).
• The gateway and adapter resource footprints have been decreased as compared to the 2.0 version of the gateway. It is now possible to run the core gateway and adapter on a single machine. It is recommended, however, to run the ESC's on their own machine.
• The NHIN interfaces have been upgraded to SOAP 1.2, in-line with NHIN specifications. The internal, entity, and adapter interfaces continue to use SOAP 1.1.
• The NHIN HIEM Notify operation has been upgraded to support WS-ReliableMessaging.

From the down-in-the-weeds point of view, some other notable modifications:

• Migrated two subsystems (audit query and HIEM) from BPEL to Java/EJB. This was done for a combination of reasons, including functionality (better control of SOAP headers, required for HIEM), performance, and memory consumption. This migration will serve as patern going forward to port other critical subsystems away from BPEL.
• Introduction of "component proxy pattern" to encourage loose coupling of components, and provide for easy swap of component connection protocol (in-memory Java interface vs SOAP calls) through dependency injection.

Specification References

The complete list of NHIN specifications that the Release 2.1 Gateway implements can be found here.

Known Issues

This section lists the known significant issues of the CONNECT Gateway.  The numbers following the items below (example: [#123]) refer to stories or defects in the CONNECT Gateway development tracking system ("Target Process").

• WS-RM on HIEM Notify appears to always resend a message once.  According to the Glassfish server log it looks like the   HIEM Notify is successfully sent, but then some number of seconds later another message is sent.  The second message is formatted slightly different (no soap action is one symptom) and it does not appear to actually get to the EJB servicing the WSDL.  This is being tracked by bug [#16940] for investigation in a future release to determine if this indeed is a defect or just a logging oddity.

Compatibility Issues

• As mentioned in the enhancements section, the 2.1 CONNECT Gateway uses SOAP 1.2 on the NHIN interfaces. Therefore, the 2.1 CONNECT Gateway cannot communicate with previous versions of the CONNECT Gateway, nor with other NHIN gateway using SOAP 1.1.
• As mentioned in the enhancements section, the 2.1 CONNECT Gateway implements WS-ReliableMessaging on its NHIN HIEM Notify interface. This (in addition to the SOAP versioning) prevents it from sending/receiving Notify messages from previous versions of the CONNECT Gateway, and with other NHIN gateways not using WS-ReliableMessaging on their Notify interface.
• The way in which consumer preferences are stored and transmitted has changed.  The format of the CPP document is now stored according to the IHE Basic Patient Privacy Consents (BPPC) specification.  The patient opt-in/opt-out settings are now stored as a clinical document using CDA, rather than as a XACML policy xml document. This will prevent exchange of CPP content with other gateways (including previous versions of the CONNECT gateway) that use XACML to represent preferences.

System wide

• On all soap messages, the soap elements ("Header", "Body", etc) and WS-Address elements ("To", etc) must contain a namespace prefix. [#5417]
• Cannot retrieve reference schemas from URL provided in WSDL [#5697]
• Non-fatal logging errors occur when logging certain item ("java.util.logging.ErrorManager: 5: Error in extracting Name Value Pairs") [#14064]
• In general, the gateway does not handle missing values in messages gracefully.  These minimal values are not currently documented (outside of the WSDL/schemas).  These will be included in the future as part of an ICD.
• The NHIN interfaces use SSL.  Therefore, cross-machine communication requires that the machines trust each other.  Sun provides development certificates intended to allow communications between two machines. This worked in 1.0, however, due to a bug [#13830] with certificate processing, these development certificates no longer work in 2.1. Users must now establish a system of trust between development machines. There are two ways this trust can be established: 1) Exchange self-signed certificates between the two machines or 2) Have both machines use the same trusted root.
• Audit log entries are occasionally saved with incorrect or blank patient ID and home community ID values. [#14477, #14487, #14507, #14508, #14509]
• Not all operations correctly implement the "service" flags to allow for a service to be disabled.

Build / Deploy

• The full build of the core gateway and adapter takes approximately 90 mins.
• WSDL and schemas must be located on the run-time server in the same structure as on the development machine ("C:\projects\nhinc\Current\Product\Production\Common\Interfaces\src\wsdl\..") [#14431]

Stability

• After deploying EJB's, occasionally errors occur that indicate that the WS-Address headers are missing. This can be resolved by restarting GlassFish.

Subject Discovery

• In Release 2.0 and 2.1, the acknowledgment message contains the status of the transaction ("Success", "Patient Not Found", "Internal Gateway Error") instead of the Java error stack information.

Authorized Case Follow-up

• Improper handling when "real identifier" not found [#14403]

Doc Query / Retrieve

• A soap fault is returned if the document ID in a document retrieve request does not exist on the responding gateway. [#14475]

HIEM

• There is no policy engine check for entity "unsubscribe", "subscribe", and "notify".
• The current matching algorithm used to find a matching subscription based on a notify could not be ported to SQL. Therefore, in order to perform this match, all subscriptions for that topic must be retrieved from the subscription repository. This is expected to affect scalability when it comes to processing notify messages on a gateway with lots of subscriptions.

Audit Log Query

• Audit log query performs exact matches with patient ID, not a logical match based on the local patient identifier and the assigning authority. [#7365]

OpenSSO

• Deploy and Undeploy of opensso.war requires a restart of Glassfish. The actions of a deploy/undeploy causes authentication errors on the Glassfish console. The authentication error is resolved with a restart.