Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 45 Next »

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, 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 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?

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.

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

My deploy of the CONNECT Binary failed.

Check to 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 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 about using a single username and password to communicate 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 (eHealh 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.


See Adopters Implementation Guidelines for more information.

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.

DNS Certificate issues

CONNECT uses the Direct JAVA RI for retrieving certificates via DNS. The logic used there is that it checks for an individual certificate 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 certificate at mail.testserver.com.

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 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.

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>

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=

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.

Validation Suite issues

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.

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.



  • No labels