...
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.
| Table of Contents |
|---|
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, 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
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.
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.
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.
Build Exceptions
What can I do if I can't build the EAR due to validation suite failing?
...
This is a known issue with Spring / CXF. Remove the EAR deployment, restart the server, and redeploy.
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 tohttps://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 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.
...
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.
General errors
Why
...
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?
...
Check your jvm making sure the path is being specifed: -Dnhinc.properties.dir=//Your/Path/Here/
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.
Security Exceptions
Why are later versions of CONNECT throwing SAML exceptions?
...
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.
Validation Suite issues
SoapUI at a remote location
...