CONNECT FAQ

Owned by Sovann Huynh
Last updated: Aug 13, 2019 by Eric McDonald
10 min read

Build:

Can CONNECT be used for Carequality implementation?

CONNECT is not currently designed for Carequality exchange.

Do I need to build CONNECT from source code?

You can Downloading CONNECT Binaries and Source Code as a pre-compiled binary. Please note that each CONNECT release has its own version of the Admin GUI, which has only been tested for compatibility with those specific CONNECT versions. These CONNECT and Admin GUI files are clearly grouped together on our download page.

How do I install CONNECT?

Depending on which release you wish to build, you can get installation instructions from the following wiki page - Downloading CONNECT Binaries and Source Code.  Software requirements and deployment instructions for each application server, binary or source code installation instructions are available through each release link. 

How to do configurable builds?

An in-depth summary can be found here for details on building a customized CONNECT EAR. In short, the EAR is sectioned into various Maven profiles which will add the chosen services into the compiled EAR. If the profile is not specified, it will not be deployed. They are as follows:

  • AD - Admin Distribution
  • PD - Patient Discovery
  • DQ - Document Query
  • DR - Document Retrieve
  • DS - Document Submission
  • DDS - Document Data Submission (Pilot)
  • X12 - Core X12
  • Direct - Direct Core
  • admingui - Administrative GUI *.WAR, and the corresponding web services into the compiled *.EAR.
  • was - Enterprise Application Archive (EAR ) for websphere application server
  • weblogic - Enterprise Application Archive (EAR ) for weblogic application server 
  • jboss7 - Enterprise Application Archive (EAR ) for Jboss EAP 7 and wildfly application server.

How can I switch from MySQL to Oracle database?

Follow the Steps below to run CONNECT Oracle Scripts for a fresh install:
1. Run dropall_oracle.sql
2. Run nhincdb_oracle.sql 
3. Run populateTestData_oracle.sql
4. Run loadTestDocumentData_oracle.sql (Please Note: This script can't be run from SQL Plus due to line limitation, you have to use SQLDeveloper or some other COTS product like TOAD, PL/SQL Developer)

How do I configure my CONNECT TLS/SSL settings?

TLS settings are not configured via CONNECT but CONNECT does provide some TLS override features such as /wiki/spaces/CONNECTWIKI/pages/118035664

How do I customize Assertion AttributeStatements?

Currently only the the elements defined in the AssertionType (check NhincCommon.xsd schema) are supported. You can modify the source to add custom assertion attributes, below are the steps:

  1. Change the AssertionType in NhincCommon.xsd schema (Add a new element with name/value or any type based on your requirement)
  2. Generate Common Types and Connect WebServices jars
  3. Use the Common Types and Connect WebServices jars in CONNECT
  4. Add the respective getters in gov/hhs/fha/nhinc/callback/openSAML/CallbackMapProperties.java & CallbackProperties.java
  5. Extract the value from the entity and set it on the request context --> gov/hhs/fha/nhinc/saml/extraction/SamlTokenCreator.java
  6. Create the new Attribute (Attribute statement) that you need to pass to the other gateway --> gov/hhs/fha/nhinc/callback/openSAML/HOKSAMLAssertionBuilder.java & gov/hhs/fha/nhinc/callback/openSAML/OpenSAML2ComponentBuilder.java

How do we change/add text to ED datatype in Java using CONNECTCommonTypesLib?

CONNECT common type library is part of the CONNECT product suite and it caters the needs of the CONNECT product requirements. The main reason we put it in the maven repository is make our build easier and address the requirements that we support.  It is specifically designed for CONNECT and may not address some of your requirements.

But you can always fork the source from GitHub and extend it to your needs. Also, you can build your own extended library into your own private repository and reference it from there.

What is CONNECT's Source code branching strategy?

CONNECT is our “master” branch, developers commit code (by merging pull requests) into CONNECT_integration. The CI jobs then validate the commits and merge them into CONNECT. Therefore we know CONNECT will always build and be stable. This same process is repeated for all of the release branches (4.2/4.2_integration, 4.3/4.3_integration), however those branches don’t enjoy the same level of activity as the CONNECT/CONNECT_integration branches.

What is HCID/OID?

HCID is home community identification. HomeCommunityId is structured as an OID limited to 64 characters and specified in URI syntax.  For example, the homeCommunityId of 1.2.3 would be formatted as urn:oid:1.2.3

What is the limit on length of an HCID/OID?

There is no limit to the length of an ISO OID. Some standards, such as DICOM, have declared an arbitrary length limit of 64 characters, so if you wish to use the OID you are registering in such a standard, you should try to conform to those other restrictions. HL7 does not put any restriction on the length of an OID, but the website software cannot accept an ‘External’ OID longer than 128 characters at this time.

For more information, please see FAQ from HL7: https://wiki.hl7.org/index.php?title=HL7_OID_Registry_Frequently_Asked_Questions

Where is the CONNECT source code repository?

Source Code: https://github.com/CONNECT-Solution/CONNECT

Schema: https://github.com/CONNECT-Solution/Common-Types

WSDL: https://github.com/CONNECT-Solution/CONNECT-Webservices

General:

How do I configure my own Entity, NwHIN, and Adapter processors?

Injection points into CONNECT are controlled by Spring Bean lookups. Injection can be done in one of 2 ways: Java or Web Services.

For Java injections, simply point the bean for the service you wish to replace in its respective property file to your custom implementation. For example, to change the Document Submission Adapter, the "adapterdocsubmission" alias inside the DocumentSubmissionProxyConfig.xml file would be changed to your custom bean. By default, there are example beans for most services with the "java" postfix - in this case "adapterdocsubmissionjava". This pre-defined bean may be repurposed by changing the "class" to your own java class file.

For webservice injections, the bean alias would be set to either the secure or unsecure beans already defined in the respective XML file. Instead of injecting a custom java class, the appropriate endpoint inside of the internalExchangeInfo.xml file must be changed to point to the URL of where your custom service is deployed. As an example, if we wanted to change the Document Submission Adapter endpoint, we would find the "adapterxdrsecured" service name (Or "adapterxdr" if you are using an unsecured service) and change its URL to point to the custom service. It should be noted that these custom services must implement their respective WSDLs

Is there documentation of the fields in the drop-down menu lists?

The contents of the drop-down menus are configurable. They currently come from a properties file in CONNECT. The NHIN specification team has defined what code sets they come from. When you install CONNECT you can see the list, but again that is configurable.

What is the Admin GUI, and how can I use it?

Admin GUI is front-end user application. It is meant to serve as an extension to CONNECT in order to manage the gateway, certificates, properties, and perform basic queries for information about the gateway. Admin GUI is also capable of serving a cross query client, as well as an interface for viewing Audit and Failure logs. Admin GUI may be deployed either on the same servlet container, as well as on a different server entirely (There may be some additional setup steps in order to configure your Admin GUI onto an external server).

A full user manual on the Admin GUI can be found here.

What is the difference between Standard and Passthrough Modes?

Currently, the CONNECT gateway is designed to operate in two modes, entity (standard) and passthrough. Entity (Standard) allows for further processing by the gateway including policy checks, mpi queries, and fan-out capabilities. Passthrough sends the message directly from gateway to adapter and vice versa. 

What are the different layers of CONNECT, and how are they used?

  • Entity - Internal endpoints used to construct NwHin requests to be sent to an external Gateway via NwHin endpoints.
  • NwHin - Endpoints that will be hit from an external gateway. This is the crossover point between the Initiating and Responding gateways. For the Initiating gateways, this will be an outbound request to another implementor. For the Responder, this will be an inbound request in which the gateway is expected to process and respond to the request by calling its Adapter.
  • Adapter - Implementor specific components which will serve as the communication layers between CONNECT and the proprietary databases,architecture, and services of the implementor. These get called by CONNECT through the NwHin layer when the gateway in question is a responder to a request.

What are these beans defined in the proxy property files for each service?

Each service may have a respective property file to configure a proxy to be used when communicating with a service. By default, there may be up to four pre-configured beans: NoOp, Java, Secured and Unsecured beans.

  • NoOp - Will always return a successful invocation, or a blank response - depending on the expected context of the bean. Does not invoke any web services or call any methods.
  • Java - Will use pure java calls to CONNECT code, can be substituted for any java class compiled with the CONNECT EAR, including custom Entity, NwHin, and Adapter implementations
  • Secured - Will use a secured port to communicate to a given endpoint configured via the internalExchangeInfo.xml file.
  • Unsecured - will use an unsecured port to communicate to a given endpoint configured via the internalExchangeInfo.xml file.

When downloading CONNECT SOURCE, there are lots of repeats like DocumentSubmission_10, DocumentSubmission_20, etc. Are they different versions?

CONNECT supports both 2010 and Summer 2011 Nationwide Health Information Network specifications. . The 20, 10 etc. suffix is used to indicate the spec version for any service and is dependent on the service.

Information on the design can be found in 'UDDI-Based Backwards Compatibility'
There is a document link in the wiki page above that has details.(This feature was introduced in Release 3.3)

Also a list of the interfaces can be found at - Service Interfaces

Exchange:

Can CONNECT 5.2 be used with FHIR Resources? Is there any way to incorporate Patient resources, Medication resources, etc.?

CONNECT 5.2 can GET organization resources from a FHIR STU3 compliant Directory. Other functionality has not been implemented into CONNECT.

Can I override exchange's partners endpoints locally?

CONNECT facilitate custom overrides for an exchange partner. You can define them in exchangeInfo.xml. Refer to CONNECT 5.1.2#Organizationalendpointoverride

Can I still demonstrate Patient Discovery, Doc Query, Doc Retrieve services using test data only, and without implementing a custom adapter?

You should be able to do Patient Discovery (PD), Query for Documents (QD) and Retrieve Documents (RD) with test data without any configuration if you have installed and configured your system as given in the CONNECT installation instructions. In this case, you get docs from local database. You can configure the hibernate config files if you want to install CONNECT database on different machine. If you want to use your own database with different schema/tables, you need customize the adapters.

Does Connect support other registry queries?

The CONNECT gateway does support these other XDS stored queries, however our reference adapters are limited to the "find documents" query. You must implement the other queries in your own adapter.

How can I import eHealth Exchange Chain of Trust?

Importing the eHealth Exchange Chain of Trust

How can I resolve third party Dependency DTD/SCHEMA URLs?

CONNECT uses Java JEE standard for developing all the Web/Web Service modules. The JEE web application/Enterprise application uses DTD/SCHEMA to verify the XML deployment descriptors used, which are specific to each application server vendor and these DTD/SCHEMA are hosted by the application vendor and referenced from CONNECT Web/Web Service applications. We recently noticed that one of the application server vendor's site (hosting these DTD/SCHEMAs) was down causing the CONNECT system to be down. For example, the sun.com site which was hosting some DTD/SCHEMA was down and due to this CONNECT was not deploying/working for one of the CONNECT users. Implementation teams can resolve this issue by doing any of the following:

1. Creating a ticket with the application server vendor. 
2. Internally hosting DTD/SCHEMA site and put all the referenced DTD/SCHEMAs there.

How do I configure the Patient Correlation Expiration Length?

Use PCConfiguration.xml, in nhinc.properties.dir folder, to configure Patient Correlation Expiration length

<?xml version="1.0" encoding="UTF-8"?> 
<Configuration>
    <expirations defaultDuration="1" defaultUnits="YEAR">
        <expiration assigningAuthority='1.1' unit='YEAR'>10</expiration>
        <expiration assigningAuthority='2.2' unit='YEAR'>1</expiration>
    </expirations>
</Configuration>

How do I initiate exchange directory download?

CONNECT can download from web services registry from both UDDI  and FHIR directories. You can configure the download in exchangeInfo.xml. For more information see Exchange Manager#ConfiguringExchange and Sample exchangeInfo

Is there any legal guidance for independent CONNECT developers accessing client EMR database, including read/writes for purposes of connecting it to HIE?

eHealth Exchange (formally known as NwHIN Exchange and now managed by a private the non-profit HealtheWay) requires their participants to sign a Data Use and Reciprocal Support Agreement (DURSA) to formalize the exchange partnership. Please see the link for more information and a PFD of a DURSA, http://healthewayinc.org/index.php/exchange/dursa.

Patient Discovery/Doc Query - Fan Out vs target a specific NHIE gateway for PD & DQ requests

Each message on either the entity interface or the message proxy allows you to target a specific entity by providing the homeCommunityId within a nhinTargetSystem. Fan out only occurs if this element is not provided.

When configuring multiple gateways, do we need to configure ExchangeInfo and InternalExchangeInfo.xml?

ExchangeInfo.xml is used to communicate with other gateway while InternalExchangeInfo.xml is used for internal adapters within its own gateway. If you participate in ehealth exchange network, you don't need to change ExchangeInfo.xml since CONNECT pulls the latest UDDI/FHIR from UDDI/FHIR servers periodically.

Where can I find more information about support, configuration, or use of CDA within CONNECT?

CONNECT does not create CDA documents that could be transferred in either the Doc Submission (XDR) or Doc Retrieve services. CONNECT is the mechanism to transfer these documents over the NHIN, not to create them and insert them into the message.

The Adapter code is responsible for either creating these documents dynamically or pulling them from an existing "repository" or file store and inserting them into the request message to CONNECT.

NHIN:

How do we authorize into NHIN? How do we retrieve userName and password for services?

NHIN does not call for cross-HIE authentication. Instead, you authenticate your users locally however you choose, then "assert" the authentication info (who is the user, why they are requesting data, etc.) and pass this in the entity assertion class, which gets represented in the NHIN message as a SAML token. The receiving gateway then uses its own policies to determine if it will allow for this call.

I want to enable my CONNECT to "grab" medical data from existing EMR systems like OpenMRS or OSCAR. Which service of CONNECT should I use?

To enable your CONNECT to "grab" medical data from an existing EMR you would probably use 3 services:

  • Patient Discovery - A NHIN service to query nodes on the NHIN for information on patient's based on demographics.
  • Document Query - A NHIN service to query nodes on the NHIN for metadata relating to documents about a specific patient
  • Document Retrieve - A NHIN service to retrieve documents from nodes on the NHIN.

In order to use these services, you would write an adapter which integrates with these productions or depending on these product's capabilities, maybe create services in OpenMRS, OSCAR, or some integration tool which provision the adapter interface for each of these services. Then when CONNECT receives one of these requests over the NHIN, CONNECT will call your services and the EMR can respond in turn.

We are looking to integrate CONNECT into our solution by leveraging reports from other agencies, analyze them and compare them to our reports. Is there any suggestions on how to set up and configure the adapter for this system?

NHIN currently provide two mechanisms for collecting clinical data: a real time query for data (provided by "doc query" and "doc retrieve") and an async pub/sub model (provided by HIEM).

The way things look to be evolving on the NHIN specification factory (the group that makes the specs for NHIN) is that HIEM will contain sub-specs to detail for what you can issue subscriptions, called a profile. At the moment, the only thing that you are really "allowed" to subscribe for is a "consumer preference profile" (document containing the rules about who can see a "my" data). The next soon-to-be-released profile spec is for GIPSE, which covers subscriptions/notifications that contain aggregated data, expected to be used for groups like CDC collecting data from public health agencies (think: "how many people had the flu yesterday").

What mechanism is NHIN using for identifying the Patients?

Each organization can identify its patients how it chooses. When you share patient data, you communicate the patient identifiers using a qualified patient id (local patient id + a globally unique assigning authority).