Direct

The design for including NwHIN Direct with NwHIN Exchange specifications is based on the following principles:

CONNECT should make use of work that has already been completed in various existing communities so as not to "reinvent the wheel"
CONNECT should be flexible to work with components that may exist already in an adopter's infrastructure. For example, the Direct Java Reference Implementation (RI) uses the Apache James mail server to handle SMTP messaging, but CONNECT should not require that specific server

Design Considerations and Design Decisions

An over-arching decision was made not to force adopters to stand up the Direct RI Application. This led to the following considerations:

Use Direct Reference Implementation code as a library
Use of standard mail servers
Use of standard DNS servers + RFC4398
Use of SMTP agent config XML

In order to de-couple the Direct Processing Code from JavaMail, a package in the CONNECT Core Module provides generic SMTP and IMAP functionality using JavaMail. Those classes are Spring-injected into Direct Core Module classes.

In order to handle sending and receiving of messages using SOAP edge clients, the design decision was made to stand up an adapter-facing gateway endpoint for sending messages. Also, the receiving adapter endpoint can be configured.

Design Approach

At a high level the design for this feature is simple. CONNECT will integrate with an existing mail server via SMTP and IMAP protocols using the JavaMail API. We will use Greenmail for unit testing and Dovecot for our integration test environment. The CONNECT implementation of Direct does not have a dependency on any specific mail server software. The rest of the feature will be implemented using pieces of the Direct Java RI running in a Java container (one of CONNECT's supported application servers). Configuration information will be stored in property files.

In keeping with the first goal, CONNECT uses the Direct Java RI to handle complex aspects of the Direct specifications, such as encryption and certificate discovery, as well as specifics around the construction of Direct SMTP messages. The implementation of Direct specifications in CONNECT encompass a simple addition to the adopter's existing adapter suite, if the SOAP edge client is preferred. An endpoint, "/DocumentRepository_Service" is employed for sending messages. STMP and Java edge clients are also available.

Mail Server Abstraction

Given that the Direct specifications rely on SMTP as a transport protocol, there is a requirement to use a mail server to send and receive Direct messages. CONNECT includes an abstraction layer between the mail server and CONNECT, using the JavaMail API to communicate to the mail server. From the perspective of sending Direct messages, simply send a message to the mail server via SMTP using the JavaMail API. From the perspective of receiving Direct messages, again the JavaMail API can be used to retrieve messages from the mail server using IMAP. Note that the mail server must be configured to route Direct messages so that they can be consumed by CONNECT.

Direct Java RI Abstraction

Given that the Direct Java RI is a separate project maintained by a separate community from CONNECT, CONNECT used this code as a starting point for its support of Direct, with a level of abstraction between CONNECT and Direct Java RI interfaces and integration points, to insulate the CONNECT product from future changes to the Direct Java RI.

Event Logging

The following table describes events that are created during CONNECT Direct HISP use cases.

Event Name	Description	Data Points
BEGIN_OUTBOUND_DIRECT	Sending a Direct message Event logged when message is pulled from the internal mail server (SMTP edge) or received successfully from SOAP+XDR edge client	Message ID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
END_OUTBOUND_DIRECT	Sending a Direct message Event logged when Direct message is sent out to the external mail server	Message ID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
BEGIN_INBOUND_DIRECT	Receiving a Direct message Event logged when Direct message is pulled from the external mail server	Message ID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
END_INBOUND_DIRECT	Receiving a Direct message Event logged when the Direct message is sent to the internal mail server( SMTP edge) or to the SOAP+XDR edge client	Message ID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
BEGIN_OUTBOUND_MDN	Sending an MDN message in response to a Direct message Event logged when creation of MDN begins	Message ID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
END_OUTBOUND_MDN	Sending an MDN message Event logged when MDN message is sent out to the external mail server	Message ID Event Name Descriptor (JSON) Message Id Original Message ID (of the original Direct message that this MDN is in response of) Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success/Error)
BEGIN_INBOUND_MDN	Receiving an MDN message Event logged when MDN message is pulled from the external mail server	Message ID Event Name Descriptor (JSON) Message Id Original Message ID (of the original Direct message that this MDN is in response of) Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
END_INBOUND_MDN	Receiving an MDN message Event logged when processing is complete and in the case of SMTP edge MDN is relayed to the internal mail server. In the case of SOAP edge, it is logged but not sent out	Message ID Event Name Descriptor (JSON) Message Id Original Message ID (of the original Direct message that this MDN is in response of) Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Success)
DIRECT_ERROR	Any error that occurs during the processing of any of the above events is logged as an error event	Message ID and other information for the Message is available if error occurred during processing of any Direct or MDN message MessageID Event Name Descriptor (JSON) Message Id Timestamp Action (Event Name) Sender - Direct Sender /address Recipient - Direct Recipient /address Message status (Error)

Application Programming Interfaces

An endpoint for sending and receiving messages, "/DocumentRepository_Service", is employed for sending and receiving messages with the following supported operations:

On the sending side an adopter can use "DocumententRepository_ProvideAndRegisterDocumentSet-b" in order to send the message to the target Direct address as opposed to a community on the NwHIN. The from and to addresses are included as SOAP headers
On the receiving side, CONNECT can invoke a specified adapter endpoint in order to handle messages retrieved and processed from the configured mail server via the JavaMail API

Performance

Performance for Mail Server polling can be controlled by specifying how often the mail server is polled and how many messages can be handled at once. Each gateway can set these values according to their own preferences.