Exchange manager

Overview

With CONNECT 5.1, exchangeInfo.xml and internalExchangeInfo.xml is introduced replacing uddiConnectionInfo.xml and internalConnectionInfo.xml respectively. These files are present in properties directory. The exchangeInfo.xml, in addition to keeping an inventory of Web services endpoints, is also used to configure downloading the web services information.

Important note regarding UDDIConnectioninfo.xml, internalConnectionInfo.xml and gateway.properties

UddiConnectionInfo.xml and internalConnectionInfo.xml have been replaced by exchangeManager.xml and internalExchangeManager.xml. The following properties that were previously defined in gateway.properties are now set in the new exchangeManager.xml (see below for more details on the use of these properties):

refreshInterval
maxNumberOfBackups
disabled (replaces UDDIRefreshActive to set exchange data refresh to true or false and this setting is now configured for each exchange)

Configuring Exchange

Below is a list of configuration provided in exchangeInfo.xml. User can update these value using Exchange Manager GUI or by manually updating the exchangeInfo.xml file.

refreshInterval: This property is used to configure the scheduled download process. The value is in minutes and default is 1440 (1 day in minutes).
maxNumberOfBackups: This is used to configure the maximum number of backups allowed for exchangeInfo.xml. A value of 1, means that CONNECT will keep only one backup of exchangeInfo.xml. the backup file name will be exchangeInfo.xml.<last-update-timestamp>, for example exchangeInfo.xml.01-02-2018_08-39-11. If this property is missing or has a value of zero, no backup will be created during exchange refresh.
defaultExchange: CONNECT can have more than exchanges in exchangeInfo.xml. defaultExchange holds the name of exchange that is used to look up services with a given HCID. This field is mandatory as of CONNECT 5.2+
type: Exchange type is a mandatory element and can have four values only
1. uddi - indicates an UDDI Web Service Registry
2. fhir - indicates FHIR directory
3. local - indicates your local CONNECT instance
4. overrides - indicates that this exchange should override endpoints specified in another exchange with the same name and HCID.
name: name of an exchange.
url: url for downloading the web services endpoints during a refresh
disabled: if disabled set to true, CONNECT will not download from this exchange. This should be set to true for internal exchanges
lastUpdated: holds the timestamp when the exchange was last refreshed.
certificateAlias: A mandatory element which specifies which certificate alias to use for a given exchange or exchange override. (CONNECT 5.3 only)
sniName: An optional element, if present, is send to responding gateway to initiate an SSL connection. The responding gateway will pick the appropriate certificate, based on sniName, to present for SSL handshake. If absent, responding gateway will use the default certificate for SSL handshake. (CONNECT 5.3 only)

Samples

exchangeInfo.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<exchangeInfo xmlns="urn:gov:hhs:fha:nhinc:exchange" xmlns:ns2="urn:gov:hhs:fha:nhinc:exchange:directory">
  <refreshInterval>1440</refreshInterval>
  <maxNumberOfBackups>1</maxNumberOfBackups>
  <defaultExchange>Exchange 1</defaultExchange>
  <exchanges>
    <exchange type="uddi">
      <name>Exchange 1</name>
      <url>https://YourUDDIExchangeUrl/</url>
      <disabled>true</disabled>
      <lastUpdated></lastUpdated>
      <organizationList>
        <organization>
          <ns2:name>Gateway 1</ns2:name>
          <ns2:hcid>urn:oid:1.1</ns2:hcid>
          <ns2:endpointList>
            <ns2:endpoint>
              <ns2:name>QueryForDocuments</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://localhost:8181/Gateway/DocumentQuery/2_0/NhinService/RespondingGateway_Query_Service/DocQuery</ns2:url>
                  <ns2:version>2.0</ns2:version>
                </ns2:endpointConfiguration>
                <ns2:endpointConfiguration>
                  <ns2:url>https://localhost:8181/Gateway/DocumentQuery/3_0/NhinService/RespondingGateway_Query_Service/DocQuery</ns2:url>
                  <ns2:version>3.0</ns2:version>
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
		  </ns2:endpointList>
        </organization>
      </organizationList>
    </exchange>
    <exchange type="fhir">
      <name>Exchange 2</name>
      <url>https://YourFhirDirectoryServer/Organization/?_format=json</url>
      <disabled>true</disabled>
      <lastUpdated></lastUpdated>
    </exchange>
  </exchanges>
</exchangeInfo>

internalExchangeInfo.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<exchangeInfo xmlns="urn:gov:hhs:fha:nhinc:exchange" xmlns:ns2="urn:gov:hhs:fha:nhinc:exchange:directory">
  <defaultExchange>adapter</defaultExchange>
  <exchanges>
    <exchange type="local">
      <name>adapter</name>
      <disabled>true</disabled>
      <lastUpdated/>
      <organizationList>
        <organization>
          <ns2:name>Gateway 1</ns2:name>
          <ns2:hcid>urn:oid:1.1</ns2:hcid>
          <ns2:endpointList>
            <ns2:endpoint>
              <ns2:name>entityconfigadmin</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://localhost:8181/CONNECTGateway/GatewayService/ConfigAdmin</ns2:url>
                  <ns2:version>LEVEL_a0</ns2:version>
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
           </ns2:endpointList>
          <ns2:targetRegion>US-NY</ns2:targetRegion>
          <ns2:targetRegion>US-VA</ns2:targetRegion>
        </organization>
      </organizationList>
    </exchange>
  </exchanges>
</exchangeInfo>

Overriding endpoints

When a request is triggered, CONNECT will scan through the override entries first in locating endpoints. If an entry exists that matches the HCID, service type and spec version*, the corresponding service URL (if defined) will be used as the target endpoint. If no match is made or no service URL is defined, CONNECT will continue with normal endpoint lookup processing. The following is a summary of the override process from a code perspective:

HCID, service type and spec version must match exactly for override to occur
If an HCID is matched but there is no exact match based on service type or spec version, a new endpoint will be "created" as long as a service URL is defined
If there is no exact match based on HCID, nothing will be done

Scenario	Result
HCID match, Service type match, spec version match	Existing endpoint is overridden with the service URL provided (no processing if service URL is not defined)
HCID match, Service type match, spec version NO match	New endpoint is created IF spec version AND service URL is provided Nothing to process if spec version and/or service URL is not provided
HCID match, Service type NO match	New endpoint is created IF spec version AND service URL is provided Nothing to process if spec version and/or service URL is not provided
HCID NO match	Nothing to process

*spec version maps to the <version> element in the exchangeInfo.xml and not the <useSpecVersion> element from <nhinTargetCommunities>

Sample exchangeInfo.xml with overrides Exchange Type

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<exchangeInfo xmlns="urn:gov:hhs:fha:nhinc:exchange" xmlns:ns2="urn:gov:hhs:fha:nhinc:exchange:directory">
  <refreshInterval>1440</refreshInterval>
  <maxNumberOfBackups>0</maxNumberOfBackups>
  <defaultExchange>Exchange 1</defaultExchange>
  <exchanges>
    <exchange type="uddi">
	..
    </exchange>
    <exchange type="overrides">
      <url>https://testurl/uddi/list</url>
      <organizationList>
        <organization>
          <ns2:name>Gateway 2</ns2:name>
          <ns2:hcid>urn:oid:2.2</ns2:hcid>
          <ns2:endpointList>
            <ns2:endpoint>
              <ns2:name>QueryForDocuments</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentQuery/2_0/NhinService/RespondingGateway_Query_Service/DocQuery</ns2:url>
                  <ns2:version></ns2:version>
                </ns2:endpointConfiguration>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentQuery/3_0/NhinService/RespondingGateway_Query_Service/DocQuery</ns2:url>                  
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
            <ns2:endpoint>
              <ns2:name>RetrieveDocuments</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentRetrieve/2_0/NhinService/RespondingGateway_Retrieve_Service/DocRetrieve</ns2:url>
                  <ns2:version>2.0</ns2:version>
                </ns2:endpointConfiguration>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentRetrieve/3_0/NhinService/RespondingGateway_Retrieve_Service/DocRetrieve</ns2:url>
                  <ns2:version>3.0</ns2:version>
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
            <ns2:endpoint>
              <ns2:name>PatientDiscovery</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/PatientDiscovery/1_0/NhinService/NhinPatientDiscovery</ns2:url>
                  <ns2:version>1.0</ns2:version>
                </ns2:endpointConfiguration>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/PatientDiscovery/1_0/NhinService/NhinPatientDiscovery</ns2:url>
                  <ns2:version>2.0</ns2:version>
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
            <ns2:endpoint>
              <ns2:name>DocSubmission</ns2:name>
              <ns2:endpointConfigurationList>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentSubmission/1_1/DocumentRepositoryXDR_Service</ns2:url>
                  <ns2:version>1.1</ns2:version>
                </ns2:endpointConfiguration>
                <ns2:endpointConfiguration>
                  <ns2:url>https://<<server-url:port>>/Gateway/DocumentSubmission/2_0/DocumentRepositoryXDR_Service</ns2:url>
                  <ns2:version>2.0</ns2:version>
                </ns2:endpointConfiguration>
              </ns2:endpointConfigurationList>
            </ns2:endpoint>
          </ns2:endpointList>
          <ns2:targetRegion>US-NY</ns2:targetRegion>
          <ns2:targetRegion>US-VA</ns2:targetRegion>
        </organization>
      </organizationList>
    </exchange>  
 </exchanges>
</exchangeInfo>

Connection Manager to Exchange Manager conversion

A converter has been developed for users who need to convert existing uddiConectionInfo.xml and internalConnectionInfo.xml files into the new exchangeInfo.xml and internalExchangeInfo.xml files.

Download UDDIExchangeTransformerUtility.jar based on CONNECT version.
From the location of the downloaded jar, execute the following command:
- java -jar UDDIExchangeTransformerUtility.jar "<PATH_TO_XML_FILES>" ← Make sure the existing uddiConectionInfo.xml and internalConnectionInfo.xml files are located in that directory
The new Exchange Manager files will be created in the specified directory (PATH_TO_XML_FILES)

CONNECT Version	Converter
5.1.2	UDDIExchangeTransformerUtility.jar
5.2 and newer	UDDIExchangeTransformerUtility-2.0.jar