API Posting EHR Visit Activity for
Patients Using the Patient Vault Plugin
for .NET and the Activity API

  August 26, 2014         ricardo@nd-soft.com

Overview

This article assumes that you have previously read Authenticating Patients – .NET Plugin article, if you have not read it, please do so before continuing, as this is a continuation of that document.

In this article you will learn how you can implement Patient Vault into your app using the Plugin for .NET. To perform this tutorial you will need Visual Studio 2012 or newer.

This diagram illustrates the process in which your app should handle the posting of a patient’s EHR visit to Patient Vault. Green steps indicate API calls to Patient Vault’s API.

Getting Started

For this scenario, we will learn how to work with the Activity API from a console application built on .NET 4.0.

NOTE: The Plugin also supports .NET 3.5

In this scenario the patient is visiting an organization that wants to post documents to the patient’s Patient Vault’s account.

For this the app needs to authenticate the user and obtain an access token. These steps are performed on Authenticating Patients – .NET Plugin tutorial, so make sure to read that one before completing this one.

These are the actors on this scenario:

  • A patient with an existing Patient Vault account, let’s call him John.
  • An organization that wants to post documents to John’s account, let’s call them GetWell Clinic.
  • A user of your app who is also an employee of GetWell Clinic, let’s call her Mary.

Create a new console application

From Visual Studio, create a new console application and name it PatientVault.Example:

Installing the NuGet Package

To begin you must install Patient Vault’s NuGet package from the package manager in Visual Studio. Right click the project and click Manage NuGet Packages:

 

VS2

 

From the Package Manager, enter ‘Patient Vault’ on the search box:

VS3

 

Click install. This will add all necessary files to your project to begin using Patient Vault.

Adding a configuration method

Before creating the client we will create a method that returns the configuration for our app on Patient Vault:

You must change the code snippet to include your API key, DEV key and Customer Key. If you do not have these please email api@patientvault.com to request them.

 

Adding an output method

Now we will create a function that allows us to display the responses of the service to the console, create the following function:

Steps for using the activity API

  1. Obtain John’s stored access token from storage.
  2. Call the PostEHRVisit method to post a new visit to John’s account.
  3. Post attachments to the posted visit.

 

Creating a the Patient Vault Client

To call services on Patient Vault we need to create a client object. To create a new client we’ll use the following code:

The plugin is designed to use dependency injection, so you first create the dependent services and then pass them to the client’s constructor.
On line 1 we create an encryption service, line 2 we get the configuration, on line 3 we create a factory that creates the post service for the client. Finally we create the client with these dependencies.

Posting the EHR visit

The first step in the process is creating the post request, for this we will include all the data that we have for John and John’s provider.

Parameters

Name Type Required Description
AccessToken string yes The access token that you saved for this patient when he was authenticated.
Note string no A note that will be seen by the patient and associated to the activity.
InstanceDescription string yes Patient’s birthdate.
Patient.Email string yes Patient’s email
Patient.FamilyName string yes  
Patient.Gender string yes (M) for Male or (F) for Female
Patient.GivenName string yes Patient’s first name
Patient.HomeAddressLine1
Patient.HomeAddressLine2
Patient.HomeCity
Patient.HomeCountry
Patient.HomeState
Patient.HomeZip
string no Address information for the patient’s home
Patient.RecordNumber string yes The patient’s record number on the provider’s records.
Provider.LocationName string depends This field is required if Provider.FamilyName and Provider.GivenName are empty.
Provider.Phone1 string no The provider’s phone number. The user will be able to touch this number to call the provider from the app.
Provider.Fax string no The provider’s fax number
Provider.AddressLine1
Provider.AddressLine2
Provider.City
Provider.Country
Provider.State
Provider.Zip
string no Address information for the provider. This will appear along with the activity.

 

The response to this call will be an object with these properties:

The ActivityId property on the response can later be used to post additional attachments to this activity. That’s it; Patient Vault will now show this information on John’s account. If this is the first time this data is sent to his account, he will have to confirm it by providing his birthdate, or the birthdate of the patient that was sent to his account.

 

Sending Attachments

Once an activity is sent to the patient’s account, you can proceed to add one or more attachments, to do this you create an ActivityAttachmentPostRequest and send the request.
Before we send attachments, we need a function to encode the attachments to base64, which is the format that the plugin expects the files to be in:

We then can create the request as such:

Parameters

 

Name Type Required Description
AccessToken string yes The access token that you saved for this patient when he was authenticated.
ActivityId quid yes The activity to which this attachment will be added to.
FileName string yes The name of the file with the extension. This is very important as it tells the system how to show the file to the patient.
EncodedFile string yes The file in base64 encoding.
FileHash string no The SHA-1 hash of the file. If this is empty the plugin will generate the hash automatically.
Title string yes The title of the file as it will appear to the patient.

 

If successful the response to this will be an object with the following properties:

You can download the complete example from:

https://github.com/NeoDeckHoldings/PatientVault.Plugin.Examples

Leave a Reply

Your email address will not be published. Required fields are marked *

Post comment