Overview
Troubleshooting is a long process of log analysis and knowing expected exception. Here are quick answers 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.
Adapter Issues
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, change the service URL port and protocol to HTTPS and try:
https://localhost:8181/Gateway/DocumentRetrieve/2_0/EntityService/EntityDocRetrieve
For Adapter, change the service URL port and protocol to HTTPS and change it in the internalExchangeInfo.xml file.
For example you can change the "adapterdocretrieve" service URL to
https://localhost:8181/Adapter/DocumentRetrieve/A_0/AdapterDocRetrieve
How to unmarshall CONNECT adapter messages?
If your local gateway uses the CommonType JAR, make sure it is the correct version. Otherwise, please make sure your local gateway is using the correct schema.
What are the 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
Where's the documentation on how to build an adapter?
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 web service is being used, ensure the web proxies are set and the URL of your web service is listed in the Internal Exchange Info configuration under the correct service name and API spec level.
Build Exceptions
What can I do if I can't build the EAR due to Validation Suite failing?
The EAR is 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.
Configuring and Deploying CONNECT
Why is my deploy of CONNECT Binary failing?
Make sure your container server meets the minimum requirements and you have followed all of the setup instructions.
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.
How do I set up Authentication in CONNECT?
Auth framework SAML is a little bit of a different flavor than Single Sign On (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 would have some assurances and feel safer with your service.
How can we implement/Setup MPI?
Message Passing Interface (MPI) is not part of CONNECT. There are several MPI's available like OpenMPI, MirthMatch, etc.
You will 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
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 the certificate is a self-signed certificate then you may also have to put the certificate in the truststore (default one is cacerts.jks) also. CONNECT uses 2-way SSL authentication, you have to import the CONNECT certificate into your application truststore and also enable 2-way SSL (eHeatlh exchange WS-Security requirement). Please note the secured Adapter interfaces use the same security polices as that of health exchange.
General errors
Audit records not appearing in Admin GUI?
Make sure the auditrepo data source in standalone.xml has the right database URL, username and password.
Why can't I log into the Admin GUI?
Ensure you are using the correct Username and Password.
You can reset the GUI accounts by running the supplied SQL scripts to reset the database to its default CONNECTAdmin account.
How do I change the CONNECT Administrator password?
See Adopters Implementation Guidelines for more information.
'nhinc.properties.dir' property is not found?
Check your Java Virtual Machine (JVM) making sure the path is being specified: -Dnhinc.properties.dir=//Your/Path/Here/
Security Exceptions
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.
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
Add the system property '-Djavax.net.debug=ssl' to your JVM. This property will output some pretty verbose logging but it's a good way to track the SSL handshake.
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.
Server Exceptions
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.
Why is my Connection to Database timing 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>
SOAP Faults
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=
Validation Suite issues
How to run SoapUI at a remote location?
Change the endpoint so that the message is sent to the correct location.
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.
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.