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.

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 three values only
  1. uddi - indicates an UDDI Web Service Registry
  2. fhir - indicates  FHIR directory
  3. local - indicates your local CONNECT instance
• name: name of an exchange. 
• url: url for downloading the web services endpoints
• disabled: if disabled set to true, CONNECT will not download from this exchange.
• 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

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

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

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

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)