Client Developer Guide

Documentation and Testing Workgroup > Documentation Priorities > SMTP Client Developer's Guide> Draft 01

Abstract

Table of Contents

Abstract

Fundamentals

Variations

Development

Receive incoming Message from a HISP

Send outbound Message to a HISP

Best Practices

Appendix

The SMTP Client Developer Guide enables SMTP Client Developer's Guide seeks to answer the following questions.

1. What is the purpose of the NHIN Direct SMTP Client Library?
2. How can a developer use the SMTP Client Library to:
   • Receive inbound messages from a HISP,
   • Construct an outbound message to a HISP

Fundamentals

<tony: ensure that relevant fundementals http://nhindirect.org/Content+Security+for+Simple+Health+Transport are addressed here>

Variations

<
Tony:
Describe the three different models>
a) HISP model: Agent is coupled with e-mail server (e.g., Exchange, Postfix, etc.), server stores decrypted mail messages, Client is configured with mutual TLS or server TLS + shared secret and uses normal e-mail retrieval (POP3/IMAP4)
b) HISP + organizational e-mail server: Agent+Gateway forwards to the "real SMTP server" via mutual TLS, "real SMTP server" makes email accessible to client.
c) HISP proxy: Agent speaks SMTP and IMAP4, sits in the firewall and encrypts/decrypts messages on the fly (we haven't built support for that yet, but it's a viable model).

Development

Receive incoming Message from a HISP

An inbound SMTP message is received, decrypted, and the XDM contents are unpackaged into individual files
 
  <Developer Resource... replace psuedo code with two example. One for C# and the other for Java>
 

and configure it Instantiate Listening Client NhinDirectClient client= new NhinDirectClient () { serverName =”myhisp.mydomain.com”, UseMutualTLS = true, PollTimeInSeconds= 60 }; Subscribe to the Event client.MessageReceived +=ClientMessageReceived; client.ReceiveAsync(); … public void ClientMessageReceived(object sender, NHINDMessage message) { foreach (Document document in message.Attachments) { DocumentType docType = document.DocumentType; CCD, CCR, Lab Results, … String docName = document.DocumentName; “PatientDischargeSummary” byte[] rawBytes = document.Document; Here are the raw bytes, do as you would. DoSomethingUseful(docType, docName, rawBytes); } }

Send outbound Message to a HISP

An outound SMTP message is encrypted, contents are packaged into an XDM, and addressed and submitted to a HISP
 
 <Developer Resource... replace psuedo code with two example. One for C# and the other for Java
 Taken from http://nhindirect.org/Requirements+for+Client+Library>
 

using Health.Net.Direct; var sender = new Address("arien.malec@nhin.example.org"); var receivers = from a in ["john.smith@nhin.example.org", "sally.jones@exchange.example.com", "jesus.walinsky@hie.example.org"] select new Address(a); var message = new Message(sender, receivers); message.TextMessage = File.ReadAllText("message.txt"); The following automatically extract metadata message.AddDocumentFromFile("clinical_summary.ccr"); message.AddDocumentFromFile("clinical_summary2.ccd"); message.AddDocumentFromFile("lab_oru_message.hl7"); Manual addition of metadata var document = new Document(); document.LoadFile("treatment_summary.pdf"); document.Author = new Author("Arien", "Malec"); message.AddDocument(document); Metadata metadata = message.Metadata; allows for getting/setting metadata properties XMLDocument xds_metadata = metadata.ToXDSMetadata(); XDMZip xdmzip = message.ToXDM(); string outgoing_email = message.ToRfc5322(); // RFC 5322 email message with Base64 encoded XDM attachment var client_config = new ClientConfiguration("config.xml"); var client = new Client(client_config); client.Send(message);

Best Practices

<October Code-A-Thon Team: Fill this out>

Appendix