Difference between revisions of "API Method DirectAddressValidate"

From Updox API
Jump to: navigation, search
(Code Samples)
(Domain-level Certificates)
 
(22 intermediate revisions by one user not shown)
Line 5: Line 5:
 
The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.
 
The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.
 
    
 
    
 +
  
 
== Behind the Scenes ==
 
== Behind the Scenes ==
When a call is made to <code>/DirectAddressValidate</code>, a search is performed for a current, non-revoked certificate for the target Direct address.  There two types of certificates to search for:
+
When a call is made to <code>/DirectAddressValidate</code>, a search is performed for a current, non-revoked certificate for the target Direct address.  There two types of certificate searches performed:
  
 
=== Address-level Certificates ===
 
=== Address-level Certificates ===
For a recipient Direct address of <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>, the first certificate search looks for a certificates issued for the recipient address: <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>.  If the immediate issuer (or any of the parent issuers) of the certificate is trusted and the certificate has not been revoked, then <code>/DirectAddressValidate</code> will return <code>true</code>. This does '''not''' mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked certificate signed by a trusted agency can be found for the address
+
The first certificate search looks for a certificate issued for the full recipient address: <code>DrTom@DrTomsPractice.MyEHRDirect.com</code>.  If all of the following are true, then <code>/DirectAddressValidate</code> will return <code>"validDirectAddress": true</code>:
 +
* a certificate is found (either via DNS or LDAP)
 +
* the found certificate has not been revoked
 +
* the found certificate is trusted itself or is signed by a trusted TrustAnchor
 +
* the found certificate is either:
 +
** not signed by DirectTrust or
 +
** signed by DirectTrust and the inquiring user's practice has been [[DirectTrust_Activation|"vetted"]]
 +
 
  
 
=== Domain-level Certificates ===
 
=== Domain-level Certificates ===
For a recipient Direct address of <code>DrBob@DrBobsPractice.OtherEHRDirect.com</code>, if no trusted, non-revoked certificate can be found for the ''address'', the next certificate search will be performed on the ''domain'' of the intended recipient: <code>DrBobsPractice.OtherEHRDirect.com</code>.  A Domain-level certificate is used for all users in a given domain.  The same certificate will be used to sign messages from <code>DrBob@DrBobsPractice.OtherEHRDirect.com</code> as will be used to sign messages from <code>NurseRatchett@DrBobsPractice.OtherEHRDirect.com</code>.  Since there ''aren't'' any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct-address is valid is to confirm the existence of a trusted, non-revoked certificate for the domain.  Again, this does '''not''' mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked certificate signed by a trusted agency can be found for the domain.
+
If no valid certificate can be found for the ''address'', the next certificate search will be performed on the ''domain'' of the intended recipient: <code>DrBobsPractice.OtherEHRDirect.com</code>.  A Domain-level certificate is used for all users in a given domain.  The same certificate will be used to sign messages from <code>DrBob@DrBobsPractice.OtherEHRDirect.com</code> and messages from <code>NurseRatchett@DrBobsPractice.OtherEHRDirect.com</code>.  Since there ''aren't'' any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct address exists is to confirm the existence of a trusted, non-revoked certificate for the ''domain''The same requirements apply to a domain-level certificate for it to be valid as apply to an address-level certificate:
 +
* a certificate is found (either via DNS or LDAP)
 +
* the found certificate has not been revoked
 +
* the found certificate is trusted itself or is signed by a trusted TrustAnchor
 +
* the found certificate is either:
 +
** not signed by DirectTrust or
 +
** signed by DirectTrust and the inquiring user's practice has been [[DirectTrust_Activation|"vetted"]]
 +
 
 +
 
 +
IMPORTANT NOTE: ''A response from <code>/DirectAddressValidate</code> of <code>"validDirectAddress": true</code> does '''not''' mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address or domain.'' For information about delivery confirmation, read about [[FAQ#MDNs|MDN processing]].
 +
 
 +
=== Special Case ===
 +
If all of the following are true:
 +
* a valid address-level or domain-level certificate is found
 +
* it is signed by DirectTrust
 +
* the inquiring user's practice has '''not''' been [[DirectTrust_Activation|"vetted"]]
 +
 
 +
the following components will be included in the <code>/DirectAddressValidate</code> response:
 +
    ....
 +
    "validDirectAddress": false,
 +
    "vettingRequired": true,
 +
    ...
 +
 
 +
This means that in order for the inquiring user to be able to send messages to the specified address, their practice must go through the [[DirectTrust_Activation|Direct Trust Activation]] process.  Once that process is completed and the practice is [[DirectTrust_Activation|"vetted"]], the same call to <code>/DirectAddressValidate</code> will return the expected:
 +
    ....
 +
    "validDirectAddress": true,
 +
    ...
 +
 
 +
 
 +
 
  
 
==  Prerequisites ==
 
==  Prerequisites ==
  
 
{{PreReq Vendor Credentials}}
 
{{PreReq Vendor Credentials}}
 +
 +
{{PreReq Account Identifier}}
 +
 +
{{PreReq User Identifier}}
 +
 +
 +
  
 
== Code Samples ==
 
== Code Samples ==
Line 36: Line 80:
 
| align="top" | Java || <div class="mw-collapsible mw-collapsed" style="width:65px">
 
| align="top" | Java || <div class="mw-collapsible mw-collapsed" style="width:65px">
 
<div class="mw-collapsible-content" style="width:810px">
 
<div class="mw-collapsible-content" style="width:810px">
 +
   
 +
 
 +
{{Java UpdoxTestClass Header}}
 
{{Talk To Updox - Core - Java|directAddressValidate|directAddressValidate}}
 
{{Talk To Updox - Core - Java|directAddressValidate|directAddressValidate}}
 
    
 
    
{{Json Auth Block - Account - Java}}
+
{{Json RequestBlock Header- Java}}
 
{{Json DirectAddressValidate Block - Java}}
 
{{Json DirectAddressValidate Block - Java}}
 +
{{Json Auth Block - User - Java}}
 +
{{Json RequestBlock Footer - Java}}
 
    
 
    
 
{{Base_Code_for_Consuming_API_Using_Java}}
 
{{Base_Code_for_Consuming_API_Using_Java}}
 +
{{Java UpdoxTestClass Footer}}
 
|}
 
|}
 +
 +
 +
  
 
== Messages ==
 
== Messages ==

Latest revision as of 08:23, 26 June 2014


Contents

Description

The following code samples describe the processes involved in "validating" a Direct address and discuss what happens behind the scenes with domain-level address validation and address-level validation.


Behind the Scenes

When a call is made to /DirectAddressValidate, a search is performed for a current, non-revoked certificate for the target Direct address. There two types of certificate searches performed:

Address-level Certificates

The first certificate search looks for a certificate issued for the full recipient address: DrTom@DrTomsPractice.MyEHRDirect.com. If all of the following are true, then /DirectAddressValidate will return "validDirectAddress": true:

  • a certificate is found (either via DNS or LDAP)
  • the found certificate has not been revoked
  • the found certificate is trusted itself or is signed by a trusted TrustAnchor
  • the found certificate is either:
    • not signed by DirectTrust or
    • signed by DirectTrust and the inquiring user's practice has been "vetted"


Domain-level Certificates

If no valid certificate can be found for the address, the next certificate search will be performed on the domain of the intended recipient: DrBobsPractice.OtherEHRDirect.com. A Domain-level certificate is used for all users in a given domain. The same certificate will be used to sign messages from DrBob@DrBobsPractice.OtherEHRDirect.com and messages from NurseRatchett@DrBobsPractice.OtherEHRDirect.com. Since there aren't any user-specific (aka Address-specific) certificates available to be searched, the most precise anyone can be about determining if the recipient Direct address exists is to confirm the existence of a trusted, non-revoked certificate for the domain. The same requirements apply to a domain-level certificate for it to be valid as apply to an address-level certificate:

  • a certificate is found (either via DNS or LDAP)
  • the found certificate has not been revoked
  • the found certificate is trusted itself or is signed by a trusted TrustAnchor
  • the found certificate is either:
    • not signed by DirectTrust or
    • signed by DirectTrust and the inquiring user's practice has been "vetted"


IMPORTANT NOTE: A response from /DirectAddressValidate of "validDirectAddress": true does not mean that the address itself is guaranteed to exist or that messages sent to it will be picked up by the intended recipient - only that a valid, non-revoked, trusted certificate can be found for the requested address or domain. For information about delivery confirmation, read about MDN processing.

Special Case

If all of the following are true:

  • a valid address-level or domain-level certificate is found
  • it is signed by DirectTrust
  • the inquiring user's practice has not been "vetted"

the following components will be included in the /DirectAddressValidate response:

   ....
   "validDirectAddress": false,
   "vettingRequired": true,
   ...

This means that in order for the inquiring user to be able to send messages to the specified address, their practice must go through the Direct Trust Activation process. Once that process is completed and the practice is "vetted", the same call to /DirectAddressValidate will return the expected:

   ....
   "validDirectAddress": true,
   ...



Prerequisites

1 This API call requires Vendor-level credentials. The credentials should be populated into the applicationId and applicationPassword fields of the auth block:

 {
   ...
   "auth": {
     "applicationId": "vendorId",
     "applicationPassword": "vendorPassword",
     "accountId": "",
     "userId": ""
   }
 }

2 This API call requires a Practice/Account-level identifier. The identifier should be populated into the accountId field of the auth block:

 {
   ...
   "auth": {
     "applicationId": "vendorId",
     "applicationPassword": "vendorPassword",
     "accountId": "practiceId",
     "userId": ""
   }
 }

3 This API call requires a User-level identifier. The identifier should be populated into the userId field of the auth block:

 {
   ...
   "auth": {
     "applicationId": "vendorId",
     "applicationPassword": "vendorPassword",
     "accountId": "practiceId",
     "userId": "userId"
   }
 }



Code Samples

Language Source Code Examples
C#
 public void TalkToUpdox() {
   string json = new JavaScriptSerializer().Serialize(new {
     recipient = "DrTom@DrTomsPractice.MyEHRDirect.com",  // required
     auth = new {
       applicationId = "vendorId",
       applicationPassword = "vendorPassword",
       accountId : "accountId",
       userId: "userId"
     }
   });
   string url = "https://updoxqa.com/io/directAddressValidate";
   SendReceiveJSON(json, url);
 }
 
 private void SendReceiveJSON(string json, string url)
 {
   var httpWebRequest = WebRequest.Create(url);
   httpWebRequest.ContentType = "application/json";
   httpWebRequest.Method = "POST";
   using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
   {
     streamWriter.Write(json);
     streamWriter.Flush();
     streamWriter.Close();
     var httpResponse = (HttpWebResponse) httpWebRequest.GetResponse();
     using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
     {
       var result = streamReader.ReadToEnd();
     }
   }
 }
Java


   import com.fasterxml.jackson.databind.JsonNode;
   import com.fasterxml.jackson.databind.ObjectMapper;
   import org.apache.http.HttpEntity;
   import org.apache.http.HttpResponse;
   import org.apache.http.client.HttpClient;
   import org.apache.http.client.methods.HttpPost;
   import org.apache.http.entity.StringEntity;
   import org.apache.http.impl.client.DefaultHttpClient;
   import org.apache.http.util.EntityUtils;
   import java.util.HashMap;
   import java.util.Map;
 
 
   public class UpdoxTest {
 
 
   public void TalkToUpdox() throws Exception {
       String uri = "https://updoxqa.com/io/directAddressValidate";
       ObjectMapper mapper = new ObjectMapper();
       Map<String,Object> messageData = BuildMessage();
       String jsonData = mapper.writeValueAsString(messageData);
       HttpResponse httpResponse = SendReceiveJSON(jsonData, uri);
       HttpEntity responseEntity = httpResponse.getEntity();
       String response = EntityUtils.toString(responseEntity);
       JsonNode actualObj = mapper.readTree(response);
 
       System.out.println(actualObj.get("responseCode"));
       System.out.println(actualObj.get("responseMessage"));
   }
 
   private Map<String,Object> BuildMessage() throws Exception
   {
       Map<String,Object> messageData = new HashMap();
       Map<String,String> authData = new HashMap();
       messageData.put("recipient", "DrTom@DrTomsPractice.MyEHRDirect.com");
       Map<String,Object> authData = new HashMap();
       authData.put("applicationId", "vendorId");
       authData.put("applicationPassword", "vendorPassword");
       authData.put("accountId", "accountId");
       authData.put("userId", "userId");
       messageData.put("auth", authData);
       messageData.put("auth", authData);
       return messageData;
   }
 
   private HttpResponse SendReceiveJSON(String jsonData, String uri) throws Exception {
       HttpClient httpClient = new DefaultHttpClient();
       HttpResponse response = null;
       StringEntity params = new StringEntity(jsonData);
       try {
           HttpPost request = new HttpPost(uri);
           request.addHeader("content-type", "application/json");
           request.setEntity(params);
           response = httpClient.execute(request);
       } catch (Exception ex) {
           // handle exception here
       } finally {
           httpClient.getConnectionManager().shutdown();
       }
       return response;
   }
 
 
   }



Messages

Destination Address

 https://updoxqa.com/io/directAddressValidate

Request JSON

 {
   "recipient": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "auth": {
      "applicationId": "vendorId",
      "applicationPassword": "vendorPassword",
      "accountId": "",
      "userId": ""
   }
 }

HTTP Response Status

 200 OK

Response JSON

 {
   "successful": true,
   "responseMessage": "OK",
   "responseCode": 2000,
   "recipient": "contact:171099",
   "name": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "directAddress": "DrTom@DrTomsPractice.MyEHRDirect.com",
   "validDirectAddress": true,
   "vettingRequired": false,
   "reason": null
 }



Relevant Response Codes

In addition to the General Error Set, this method may return the following values in the responseCode and responseMessage fields:

responseCode responseMessage