HealthBus REST API Use Cases

Phillip Odam

Modified on: Tue, 16 Oct, 2018 at 4:45 AM

The examples below use Unirest's Java synchronous method calls, this is done as it helps to keep the example short and succinct. However when implementing the calls into your application we recommend the use of the asynchronous methods, this is especially important if you are expecting to move a large volume of messages.

1. Send HealthBus message with attachments

// classes used
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;

import org.apache.commons.lang3.StringUtils;
import org.apache.http.HttpStatus;

import org.json.JSONObject;

import java.util.List;
import java.util.ArrayList;
import java.io.File;

// example code to upload a list of files and send a message with this files attached
HttpResponse<JsonNode> response;
JSONObject json;

List<File> fileList = GetYourListOfFilesToUpload(); // get your list of files to send
List<String> attachmentIDs = new ArrayList<String>();

// upload your files
for (File file : fileList) {
  response = Unirest.put("https://api.sandbox.rosettahealth.net/MailManagement/ws/v3/send/message/attachment")
                    .header("accept", "application/json")
                    .basicAuth("username", "password") // provide Direct address and password
                    .field("attachment", file) // provide file to upload
                    .asJson();
  if (response.getStatus() != HttpStatus.SC_OK) throw new Exception("HTTP response indicates a problem"); // handle case where upload unsuccessful
  json = response.getBody().getObject(); // json response
  if (!"PASS".equals(json.getString("state"))) throw new Exception("JSON response indicates a problem"); // handle case where upload unsuccessful
  attachmentIDs.add(json.getString("attachmentID"));
}

// send message
response = Unirest.put("https://api.sandbox.rosettahealth.net/MailManagement/ws/v3/send/message")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Direct address and password
                  .field("to", "") // provide required recipient address
                  .field("subject", "") // provide required message subject
                  .field("body", "") // provide required message body
                  .field("attachmentId", StringUtils.join(attachmentIDs, ","))
                  .asJson();
if (response.getStatus() != HttpStatus.SC_OK) throw new Exception("HTTP response indicates a problem"); // handle case where send is unsuccessful
json = response.getBody().getObject(); // json response
if (!"PASS".equals(json.getString("state"))) throw new Exception("JSON response indicates a problem"); // handle case where send is unsuccessful

// now that the file(s) have been successfully uploaded and sent in a message you can proceed with any clean up process you choose to implement

// for logging and tracking purposes the response from the send message call includes the
// Message ID of the sent message. We recommend keeping a log of this along with the address
// of the sender & recipient(s) to assist with any diagnostics.
System.out.println(json.getString("messageID"));

2. Retrieve HealthBus message, its attachments and finally delete message and its attachments

// classes used
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;

import org.apache.commons.io.FileUtils;
import org.apache.http.HttpStatus;

import org.json.JSONArray;
import org.json.JSONObject;

import java.io.File;
import java.io.InputStream;

// example code to retrieve a message, its attachments and finally delete the message
HttpResponse<JsonNode> jsonResponse;
HttpResponse<InputStream> streamResponse;
JSONObject json;
InputStream is;

// retrieve message
jsonResponse = Unirest.get("https://api.sandbox.rosettahealth.net/MailManagement/ws/v3/retrieve/message")
                      .header("accept", "application/json")
                      .basicAuth("username", "password") // provide Direct address and password
                      .queryString("messageID", "") // provide required message ID
                      .queryString("from", "") // provide required from address
                      .asJson();
if (jsonResponse.getStatus() != HttpStatus.SC_OK) throw new Exception("HTTP response indicates a problem"); // handle case where retrieval is unsuccessful
json = jsonResponse.getBody().getObject(); // json response
if (!"PASS".equals(json.getString("state"))) throw new Exception("JSON response indicates a problem"); // handle case where retrieval is unsuccessful

// retrieve attachments
JSONArray attachmentArray = json.getJSONArray("attachment");

for (int i = 0; i < attachmentArray.length(); i++) {
  String attachmentID = attachmentArray.getJSONObject(i).get("attachmentID").toString();
  streamResponse = Unirest.get("https://api.sandbox.rosettahealth.net/MailManagement/ws/v3/retrieve/message/attachment")
                          .basicAuth("username", "password") // provide Direct address and password
                          .queryString("messageID", "") // provide required message ID
                          .queryString("from", "") // provide required from address
                          .queryString("attachmentID", attachmentID) // provide required attachment ID
                          .asBinary();
  if (streamResponse.getStatus() != HttpStatus.SC_OK) throw new Exception("HTTP response indicates a problem"); // handle case where download unsuccessful
  is = streamResponse.getRawBody(); // attachment
  FileUtils.copyInputStreamToFile(is, new File("")); // if you want to save to file all you need here is a file path and name
}

// delete message
jsonResponse = Unirest.delete("https://api.sandbox.rosettahealth.net/MailManagement/ws/v3/remove/message")
                      .header("accept", "application/json")
                      .basicAuth("username", "password") // provide Direct address and password
                      .queryString("messageID", "") // provide required message ID
                      .queryString("from", "") // provide required from address
                      .asJson();
if (jsonResponse.getStatus() != HttpStatus.SC_OK) throw new Exception("HTTP response indicates a problem"); // handle case where delete is unsuccessful
json = jsonResponse.getBody().getObject(); // json response
if (!"PASS".equals(json.getString("state"))) throw new Exception("JSON response indicates a problem"); // handle case where deletion is unsuccessful

The retrieve message processing assumes you have two important pieces of information, the Message ID and the address of where the message is from. We offer two primary ways to get this information, either we'll call you and provide the information so you can retrieve your message or you can call us and we'll tell you if there are any messages waiting for you. ie. either we'll push notifications to you or you can poll us for notifications.

In the case of push notifications you'll need to provide an HTTPS endpoint for the RosettaHealth service to call you on. Our recommendation is to submit the notification to an MQ and for example have a consumer handle the logic detailed above in 2. retrieve message, attachment and delete message.

3. Push notification

// Spring controller method
@RequestMapping(value="/service/notificationservice/receive",
                method=RequestMethod.PUT, consumes={"application/x-www-form-urlencoded"})
public @ResponseBody void notify(@Valid DirectNotification notification) {
  // submit the notification to a MQ for later processing
  // whether the MQ consumer handles the retrieval of the message or for example record that
  // your user has a new message so when they are next logged in they are able to retrieve it all
  // depends on the architecture of your system and your exact use case
  directNotificationProducer.submitMessage(notification);
}

// POJO
public class DirectNotification {
  @NotNull private String from;
  @NotNull private String to;
  @NotNull private String subject;
  @NotNull private String date;
  @NotNull private String messageID;

  public DirectNotification() {}
  public String getFrom() { return this.from; }
  public void setFrom(String from) { this.from = from; }
  public String getTo() { return this.to; }
  public void setTo(String to) { this.to = to; }
  public String getSubject() { return this.subject; }
  public void setSubject(String subject) { this.subject = subject; }
  public String getDate() { return this.date; }
  public void setDate(String date) { this.date = date; }
  public String getMessageID() { return this.messageID; }
  public void setMessageID(String messageID) { this.messageID = messageID; }
}

For polled notifications we recommend something like the following run as a background task periodically polling the RosettaHealth service for new notifications. When it comes to retrieving the message and its attachments for a particular user, please see code above in 2. retrieve message, attachment and delete message.

4. Polled notification

// classes used
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.JsonNode;
import com.mashape.unirest.http.Unirest;

import org.json.JSONArray;
import org.json.JSONObject;

// example code to poll for notifications
HttpResponse<JsonNode> response;
JSONObject json;

response = Unirest.get("https://api.sandbox.rosettahealth.net/AccountManagement/ws/v2/notify/organization")
                  .header("accept", "application/json")
                  .basicAuth("username", "password") // provide Admin username and password
                  .queryString("domain", "") // provide domain to retrieve notifications for
                  .asJson();
json = response.getBody().getObject(); // json response

JSONArray messagesArray = json.getJSONArray("messages");
JSONObject message;

for (int i = 0; i < messagesArray.length(); i++) {
  message = messagesArray.getJSONObject(i);
  String messageID = message.getString("messageID");
  String from = message.getString("from");
  String to = message.getString("to");
  String subject = message.getString("subject");
  String date = message.getString("date");

  // you now have the details needed to retrieve the new message as well as which of your users
  // this message is for.
  // the following lines of code needing to be written will all depend on the architecture of
  // your system, for example you could record that your user has a new message so when they
  // are next logged they are able to retrieve it.
}

Related Articles