Exchange Manager methods, objects, and functions

Owned by Tran Tang (Unlicensed)
Jul 02, 2019
5 min read

Overview

The Exchange Manager, and its internal counterpart Internal Exchange Manager, is responsible for managing the exchanges. Most of the functionality runs around obtaining information for a given organization from a combination of Exchange Name, Home Community ID, Service Name, and API Spec versions. The exchange manager is also responsible for loading and reloading the exchangeInfo.xml and internalExchangeInfo.xml files. The exchange manager is mostly used internally to retrieve a URL to be used when making an external SOAP request to another exchange, or internally for client provided proxy services such as the secure/unsecure adapter webservice layers. The exchange manager also supports Exchange Overriding which allows an exchange to override specific endpoints for various services. CONNECT also supports Exchange Targeting, which allows the Entity message to specify a requested HCID, Exchange Name, and API Spec Version by providing a NhinTargetCommunities element inside of the SOAP request.

Target Communities Example
<urn:NhinTargetCommunities>
    <urn1:nhinTargetCommunity>
       <urn1:homeCommunity>
          <urn1:description>{HCID DESCRIPTION}</urn1:description>
          <urn1:homeCommunityId>{HCID}</urn1:homeCommunityId>
          <urn1:name>{HCID NAME}</urn1:name>
       </urn1:homeCommunity>
    </urn1:nhinTargetCommunity>
    <urn1:useSpecVersion>{SPEC VERSION}</urn1:useSpecVersion>
    <urn1:exchangeName>{EXCHANGE NAME}</urn1:exchangeName></urn:NhinTargetCommunities>
 </urn:NhinTargetCommunities>

It should be noted that this element is optional in Standard mode, but required in Passthrough Mode. The functionality of this element, however, remains the same regardless of a service being in Passthrough or Standard mode. When the Entity request contains this element, any values provided here will take precedence over the default behavior / lookups for any subsequent requests to external webservices. The request may contain any combination of nhinTargetCommunity (Required), useSpecVersion (Optional), and exchangeName (Optional). These values will be propagated into the NhinTargetSystemType, which is used as the primary reference for the Exchange Manager when looking up webservice URLs.

If the service is in Standard Mode and the NhinTargetCommunities is absent, the service will invoke a fan out request if the service supports it.

Methods

Most public methods from the Exchange Manager is either invoked internally (Exchange Manager calling methods within itself), via the WebServiceProxyHelper, or ExchangeManagerHelper. Every service, at one point, will have invoked the Exchange Manager in order to retrieve a given URL for the outbound messages when communicating with an external organization. This is often done by an exchange lookup via the targeted HCID, service name, and exchange name. If there is a targeted API Spec version specified by the Entity message, that would be included as well. The following contains a list of all of the public methods used, a brief explanation of its purpose, as well as any classes that may be invoking Exchange Manager directly.

Objects

  • EndpointConfiguration - Schema mapping for a given endpoint to be used for an organization's service. Specifies the URL and API Spec Version.
  • OrganizationType - Schema mapping for a given Organization. Holds the Name, HCID, Type, Status, Description, Contact/Address information, endpoint configuration list (EndpointConfiguration), and the target region.
  • ExchangeType - Schema mapping for a given Exchange. Holds the name, certificate alias to be used for HTTPS, SNI Name, URL, tlsVersion, whether or not it is disabled, the time the exchange was last updated, and a list of organizations (OrganizationType).
  • ExchangeInfoType - Schema mapping for the root element of the exchange info. This holds the refresh interval, max number of backups, the default exchange to use, and a list of all the exchanges (ExchangeType)

Example Workflow for PD

This example assumes that PD is in Passthrough Mode. In this case, NhinTargetcommunities is required to be present in the Entity message.

Entity Layer:

  1. Converts NhinTargetCommunities to NhinTargetSystemType to be used in all future requests.
  2. Invokes OutboundPatientDiscoveryStrategyImpl
    1. Gets the URL from the NhinTargetSystemType and Service Name.
    2. Sets the URL on the NhinTargetSystemType to be used later.
    3. Invokes Nhin Webservice Proxy Class. (NhinPatientDiscoveryProxyWebServiceSecuredImpl.java)
      1. Attempts to use the URL provided in the NhinTargetSystemType if it is not NULL, otherwise retrieves Default URL from the HCID, ServiceName, and Exchange Name.
      2. Creates a CONNECT CXF Client with the returned URL (*See Connect Client flow below).
      3. Invokes the Nhin webservice via the CXF Client.

Nhin Layer:

  1. Processes requests and invokes the MPI Adapter Proxy
    1. Gets the URL from the Adapter Endpoint, which uses the Service Name and Highest API Level.
    2. Creates a CONNECT CXF Client with the returned URL(*See Connect Client flow below).
    3. Invokes the Adapter webservice via the CXF Client.

Adapter Layer:

  1. Processes request, and returns a response, which bubbles up to the previous layers.

CONNECT CXF Client:

  • If a targeted exchange was provided via the NhinTargetSystemType, the exchange name will be used as the exchange for future requests.
  • If the targeted exchange was *not* provided via a NhinTargetSystemType, the default exchange will be used.