Overview
Troubleshooting is a long process of log analysis and knowing expected exception; here are quick answer to common knowledge that may or may not solve the issue but provide a starting point to understanding the problems. If the issue is not found below, it may be found under CONNECT Community Forum.
Why are later versions of CONNECT throwing SAML exceptions?
Older versions of CONNECT provided default values that could pass SAML validation on most responding gateways but CONNECT 5.1 and later versions encourage implementors to provide more appropriate values for parameters such as subject info since CONNECT does not actually confirm user authenticity.
Why are my requests timing out / not going to the correct URLs?
Double check the Exchange Info configuration is correct and that it is listed under the correct exchange and HCID.
One of my service endpoints is 404'ing. Why?
Ensure the EAR was built with the correct profiles if built from source. Webservices are only included if they were built with the respective profile. If the profile is enabled and the error still persists, ensure the context root is correct.
I deployed CONNECT again, and the deploy failed and it ran out of memory. Why?
This is a known issue with Spring / CXF. Remove the EAR deployment, restart the server, and redeploy.
Why isn't my custom adapter being called?
Double check the proxy settings are correct. If you are using a Java bean as your adapter, ensure you have defined the bean and set the alias configuration to use that bean instead. Also double check the class is correct and is being injected via Spring. If a webservice is being used, ensure the web proxies are set and the URL of your webservice is listed in the Internal Exchange Info configuration under the correct service name and API spec level.
Why can't I log into the Admin GUI?
Ensure you are using the right Username / Password. You can reset the Admin GUI accounts by running the supplied SQL scripts to reset the database to its default CONNECTAdmin account.
What can I do if I can't build the EAR due to validation suite failing?
The EAR is still built before this state and can be located in the Target folder. You can deploy this EAR file manually to your server and debug it with your IDE of choice. You may then run the SoapUI validation suite manually while being able to use breakpoints and step into the methods / features that are failing.
SOAPUI ValidationSuite fails to run correctly
Make sure your SoapUI has the libraries (FileUtils and MySQL jars) installed to run the ValidationSuite.
SoapUI Validation Fails with NPE before it hits the server
Make sure your GatewayPropDir property points to the nhinc property folder
The property 'nhinc.properties.dir' is not being found
Check your jvm making sure the path is being specifed: -Dnhinc.properties.dir=//Your/Path/Here/
CONNECT is using SOAP 1.2 instead of SOAP 1.1. How do I change this?
CONNECT currently doesn't support 1.1 encoding soap message
DNS Certificate issues
CONNECT uses the Direct JAVA RI for retrieving certs via DNS. The logic used there is that it checks for an individual cert first, in your case it would be admin.mail.testserver.com, and if this CERT record isn’t found then it will look for the organization cert at mail.testserver.com.
My deploy of the CONNECT Binary failed.
Check to make sure your container server meets the minimum requirements and you have followed the setup instructions.
The PKIX path errors are because one machine doesn't trust the other.
Make sure the certificates with the machine you are communicating with has its respective certificates imported into the trust store.
Unable to create HOK Assertion: null (failed to create saml)
This error generally occurs when the saml.properties, signature.properties, and truststore.properties files in the configuration directory are either not found or the values in those files are incorrect/missing.
CONNECT failing to complete SSL Handshake
Adding the system property '-Djavax.net.debug=ssl' to your jvm. This will output some pretty verbose logging but have found that it's a good way to track the the SSL handshake.
Validation tests are failing because of certificate path problems
The keystores were set up for you automatically. If this is the case, your gateway is using self-signed certificates. The Java keystore, gateway.jks, contains your gateway's certificate, which is known by the alias "gateway". This certificate has also been imported into the truststore, cacerts.jks, so that the gateway can make secured connections to itself. You may make secured connections to yourself when testing, so that your local gateway acts as both the requesting and responding gateway, and also at other times depending on your gateway configuration. If you want to send a message to a remote gateway, the same "gateway" certificate must be imported into the remote gateway's truststore.
SoapUI at a remote location
All that needs to be done is to change the endpoint so that the message is sent to the correct location.
Large Payload testing: "XDS MISSING DOCUMENT" from my submissions
The payload did not convert correct. It should be in base64 encode format from file:///<file path location> . For example:
your encode value should be simliar like this ZmlsZTovLy9jOi9sYXJnZXBheWxvYWQvb3V0Ym91bmQvdGVzdC50eHQ=
How can we implement/Setup MPI?
MPI is not part of Connect. There are several MPIs available like OpenMPI: https://www.open-mpi.org/ , MirthMatch etc., you need to create an Adapter to connect to these MPIs. An example to connect to MPI is also available in our WiKi page: 'Create an MPI Adapter'
Better response codes for invalid requests
The wrong format in subject:role element, that causes the exception to happen. However, when CONNECT catches any exception, it will throw SOAP fault in response message along with 500 error code in header. The SOAP specification under section 6.2 SOAP HTTP Response (https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383510) indicates that requirement.
Unable to unmarshall CONNECT adapter messages
If your local gateway uses the CommonType JAR, make sure it the correct version. Otherwise, please make sure your local gateway is using the correct schema.
How to configure unsecured adapter and entity web services to use SSL/TLS
By default the unsecured Entity and Adapter services should work over SSL/TLS as long as you configured your application server in two way TLS (which is the base requirement for CONNECT).
For Entity, just change the service url port and protocol to https and try:
https://localhost:8181/Gateway/DocumentRetrieve/2_0/EntityService/EntityDocRetrieve
For Adapter, do the same, change it in the internalExchangeInfo.xml, for example you can change the "adapterdocretrieve" service URL to
https://localhost:8181/Adapter/DocumentRetrieve/A_0/AdapterDocRetrieve
How do I set up Authentication in CONNECT
Auth framework SAML is a little bit of a different flavor than SSO SAML - so there isn't a username/password in the exchange SAML. Unless you are only exchanging with a set of predetermined partners, there is no way to know which users will be attempting to query your exchange.
Suggestion: develop a set of policies to accept or deny messages based on the information that is in the exchange saml (Subject ID, Subject Organization, Subject Role, Purpose Of Use, Home Community ID, Organization ID, Resource ID (Optional), National Provider Identifier (Optional)), and then implement a custom CONNECT policy engine adapter to enforce these policies. If a message is OK per your policies then you could have some assurances and maybe feel safer about using a single user/pass to communicate with your service.
Differences between secure and unsecure adapter web service requests
the wsdls are different because the secured versions translate the CONNECT assertion element into an actual SAML assertion, while the unsecured version just keeps CONNECT assertion element
How do I configure what certificate should be used to properly authenticate the request?
Try adding the certificate in the CONNECT application keystore (default one is gateway.jks). If it’s a self-signed certificate then you may also have to put it in the truststore(default one is cacerts.jks) also. CONNECT uses 2-way SSL authentication, you have to import the CONNECT cert into your application truststore and also enable 2-way SSL, it’s a eHealh exchange WS-Security requirement. Please note the secured Adapter interfaces use the same security polices as that of health exchange.
Where's the documentation on how to build an adapter?
the reference adapter which come with CONNECT are a great place to start. In general adapters can be developed on three different interfaces; java, web services, and secured web services. You can implement the adapter’s java interface and package your implementation in the CONNECT application (ear), or go for web services. The WSDLs are in github so if you are familiar with WSDL first web services you can go that route.
Please refer to the Adapter Implementation wiki page for more information.
Seeing WSSecurityException "The message has expired (WSSecurityEngine: Invalid timestamp The security semantics of the message have expired)"
Mostly, unsynchronized system times causes this exception. Check if both initiating gateway and responding gateway have synchronized clocks.
Connection to Database timed out
Set check-valid-connection-sql to select 1 to avoid Database time out. Below is sample configuration:
<datasource jta="true" jndi-name="<<jndi name>>" pool-name="<<data_source name>>" enabled="true" use-ccm="true">
<connection-url>jdbc url</connection-url>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<driver>mysql-connector-java-5.1.10.jar</driver>
<security>
<user-name>username</user-name>
<password>password</password>
</security>
<validation>
<check-valid-connection-sql>select 1</check-valid-connection-sql>
<validate-on-match>false</validate-on-match>
<background-validation>true</background-validation>
<background-validation-millis>10000</background-validation-millis>
</validation>
</datasource>
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. If you have an adapter which implements the other XDS stored queries then you should be ok.
Is there any legal guidance for independent CONNECT developers accessing client EMR database, including read/writes for purposes of connecting it to HIE? A boilerplate non-disclosure agreement maybe?
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 formlize 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.
without customizing any part of current Adapter implementation, can I still demonstrate Patient Discovery, Doc Query, Doc Retrieve services using test data? In this case, patient information and documents are from CONNECT local database not the existing organization medical systems. Did I understand correctly?
You should be able to do PD,QD and RD with test data without any configuration if you have installed and configured your system as given in the CONNECT installation instructions. Yes, in that case you get docs from local database. You can configure hibernate config files if you want to install CONNECT database on different machine. But, if you want to use your own database with different schema/tables, you need customize the adapters.
Now I want to enable my CONNECT to "grab" medical data from existing EMR systems like openmrs or OSCAR. How can I do it? Which service of CONNECT I should 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.
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.
Asynchronus Response from CMS
The NHIN Specification Factory defines Asynchronous, or Deferred Messaging as it is referred to in the specs, to be 2 separate services each with a request/response operation. These are two different services because the amount of time between when the request was sent out and the response could come back could be a very long time, up to a month.
So in order to implement Deferred Doc Submission on the client side the Adapter Software will need to setup a service that handles Deferred Document Submission Responses. In CONNECT this WSDL would be: AdapterComponentXDRResponse.wsdl. Requests would be sent on the Entity Deferred Doc Submission Interface (EntityXDRRequest.wsdl).
In the Adapter Software you would need to correlate responses with previously received requests if you are concerned with making sure you get responses back eventually. This can be done using the WS-Addressing MessageID and RelatesTo fields that are in the header.
Here are a couple links to the CONNECT Wiki where you can get more information on this: 'Asynchronous Messaging' and 'Generic Asynchronous Communication'
Want to send XDR PnR to Adapter then to Gateway. Is this possible without writing my own CONNECT Adapter piece?
If there is a way for your EHR system to send a web-service call to the Entity Document Submission WSDL then you would not need CONNECT Adapter code on the Initiating side. In essence your EHR system would be the CONNECT Adapter.
If your EHR system does not have the ability to send a web-service message to this WSDL or cannot be modified to do so you would just need to write a little bit of Adapter Code that would take the output of your EHR system convert it to the message type that the Entity Document Submission WSDL expects and make a web-service to that Interface. But in this case it would just be a very thin layer that will create an interface between your specific EHR system and the CONNECT Gateway.