Global

We've detected that you're in . Would you like to go to the MediCam site?

Integrations

MediCam provides a Software Development Kit (SDK) and various API's to help institutions efficiently integrate MediCam into their workflow.


MediCam has been built to enable easy integration with various third party storage services and individual institutions' medical record systems.

Please be warned. This section has been designed for those with a solid understanding of technology. It's going to get technical!

1. Methods of Sending/Submitting Reports

The intimidating and confusing (at first look) diagram below shows that there are 7 types of integrations. Each will be discussed further below. This might not make sense now, but hopefully this page clears up any questions you have!

  1. Upload to Box (teal lines)
  2. Upload to Dropbox (royal blue lines)
  3. Email to Recipient (grey and pink lines)
  4. Email to Medical Record (grey and light blue lines)
  5. Upload to Medical Record (green lines)
  6. Upload to Medical Record (with Dynamic Key Encryption) (grey and yellow lines)
  7. Upload to Medical Record (with Static Key Encryption) (grey and purple lines)

Please note, the numbers next to the "methods" above do not correspond to the numbers in the diagram below. Use the colours above and match them to the diagram below (the grey lines are used by multiple sending methods).

Send options

Which method is best for me?

Please note this is just a guide. There are many more factors that might lead to a different method being suitable for your purpose.

1.1 Upload to Box

MediCam PRO enables you to capture photos, video and audio and upload reports to Box. This means that you can use this MediCam to keep an archive of patient media. This is particularly useful for areas of medicine where it is appropriate to store and track pictorial changes over time.

Upload to Box

Setup

To setup sending to Box, tap on the "Settings" button (on the main form), then tap the "Box" row under the "Integrations" heading. Then tap on the "Log in to Box" button. You will be guided through the process to log in to Box.

Setup Box

Sending

To send to Box, on the main form just above the "Submit" button is a "send to" field. Tap on that and select "Box". Upon submitting, the app will upload the report to your Box account (follow the teal line in the diagram at the top of the page).

Note, a "MediCam" directory will be created in your Box account and all reports will be uploaded here.

Security

Box, in conjunction with MediCam, can be used to help you comply with HIPAA and HITECH.

All reports are uploaded over HTTPS. We do not encrypt reports using the key server when submitting to Box as it is assumed that Box stores all reports securely. Please see the Box HIPAA And HITECH Overview And FAQs for more information.

1.2. Upload to Dropbox

MediCam PRO enables you to capture photos, video and audio and upload reports to Dropbox. This means that you can use this MediCam to keep an archive of patient media. This is particularly useful for areas of medicine where it is appropriate to store and track pictorial changes over time.

Upload to Dropbox

Setup

To setup sending to Dropbox, tap on the "Settings" button (on the main form), then tap the "Dropbox" row under the "Integrations" heading. Then tap on the "Log in to Dropbox" button. You will be guided through logging in to Dropbox.

Setup Dropbox

Sending

To send to Dropbox, on the main form just above the "Submit" button is a "send to" field. Tap on that and select "Dropbox". Upon submitting the app will upload the report to your Dropbox account (follow the royal blue line in the diagram at the top of the page).

Note, an "Apps/MediCam" directory will be created in your Dropbox account and all reports will be uploaded here.

Security

Dropbox, in conjunction with MediCam, can be used to help you comply with HIPAA and HITECH.

All reports are uploaded over HTTPS. We do not encrypt reports using the key server when submitting to Dropbox as it is assumed that Dropbox stores all reports securely. Please see Dropbox's Help Center article for more information.

1.3 Email to Recipient

Technically this not really an "integration" as sending reports via email is part of the core functionality of MediCam. To be comprehensive we have, nonetheless, included discussion here.

Email to Recipient

Setup

There is only one requirement - ensure that email is configured on your device. The vast majority of people will set this up when they first setup their device. If you don't have email setup you will be notified when trying to send.

In iOS email can be setup in "Settings" > "Main, Contacts, Calendars".

On Android, open your device's email application, tap "Menu", and tap "Accounts".

Sending

The following occurs. (Note: the numbers correspond to each number in the lines in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the users details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default the app will use a Key Server run by MediCam. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running your own key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a MediCam File ({reportID}.medicam).
    • The app opens the device's default mail client to compose a new email and attaches the MediCam File. The email is pre-populated with instructions as to how to open the MediCam File.
    The user can pick a recipient out of their devices built in address book and send.
  4. The recipient receives an email with a MediCam file attached to it. It includes instructions as to how to open it. Assuming the recipient has never used MediCam before...
    • They are instructed to download the app from the App Store or Google Play.
    • The user signs up for a MediCam account (free).
    • Their email address is validated and their details are stored in the User Server.
    • The User Server will return a User Token.
    Now the recipient has the app installed, if they tap on the MediCam File in the email they will be prompted to open the file in the MediCam app.
  5. For the app to display the report the following occurs:
    • The app opens up and unzips the MediCam file ({reportID}.medicam). This exposes the package.json file and the package.encrypted file.
    • The app extracts the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
    • The app sends a request off to the Key Server with the recipient’s User Token, and asks for the Key.
    • The Key Server logs the request and thereby produces an audit trail of who has accessed the report.
    • The Key Server responds with the Key used to decrypt the package.encrypted file.
    • The app decrypts the package.encrypted file and unzips it.
    The recipient can now see the report deals and media in the app. They can also view (and if necessary print out) a PDF report.

Security

Here we have securely captured patient data and media, recorded consent and transmitted it securely to a recipient. Because all patient and user data is strongly encrypted (in the attached MediCam file) we are able to share this file through email. If someone were sniffing traffic (i.e. they intercepted the email), the file will be meaningless gobbledygook! The only way they could do anything with it is by creating a MediCam account and thereby leaving an audit trail as to who they are. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running your own key server.

If we take the analogy of a doctor sending a confidential "paper" report through the post to another doctor, there is an implicit understanding and ethical obligation that the recipient will not in turn act inappropriately with that data (e.g. share it on Facebook). MediCam relies on the same implicit understanding and ethical obligation when giving the recipient the ability to view and print out a PDF report.

MediCam uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate MediCam into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.4 Email to Medical Record

Health institutions often have very restrictive firewalls and data passing in and out of the network is often blocked (understandably so). This often means IT departments are reluctant to open the firewall up to allow third party services such as MediCam through. Email, however, is an almost universal protocol that is allowed through all firewalls given its ubiquitous nature. Hence, we provide the option of sending email reports direct from a users device to an institution assigned email account.

Email to Medical Record

Institution Setup

To get MediCam reports into the patient medical record via email a few things need to be set up first.

  • You should set up an email address for the specific purpose of receiving MediCam reports (e.g. [email protected]). This is where all emailed reports will be sent initially.
  • You will have to build an Endpoint Server. This is essentially some middleware that reads the mailbox for new email, extracts the attached reports, decrypts them, parses the data and inserts into the medical record system. More detail on this is provided in the Running Your Own Endpoint server section below.

User Setup

Users within your institution should be instructed to set up an "Institution" within the MediCam app on their device(s). To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Email", enter the name of your institution (e.g. "My Hospital"), enter the specified email address in the "Endpoint" field, and in the "Key Server" field enter the URL of your Key Server if you have one (otherwise leave it blank).
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Email

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram at the top of the page.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the users details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default the app will use a Key Server run by MediCam. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running your own key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a MediCam File ({reportID}.medicam).
    • The app opens the device's default mail client and attaches the MediCam File to an email.
    • The email is pre-populated with the specified email address in the "To" field.
    The user then sends the the email.
  4. The End Point Server should be configured to routinely check the specified email account for new emails. When there is one it should...
    • Download the email and extract the attached MediCam File.
    • Unzip the MediCam File.
    • Read the contents of the package.json file to find the location of the Key Server.
  5. The Endpoint then has to send a request to the Key Server to get Key to decrypt the file. Upon getting the response it will...
    • Decrypt the package.encrypted file.
    • Unzip the package.encrypted file.
    • Parse the Metadata File to get the details of the report.
  6. The report can then be transferred into the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Here we have securely captured patient data and media, recorded consent and transmitted it securely through the institutions firewall and into a patient record. Because all patient and user data is strongly encrypted (in the attached MediCam file) we are able to share this file through email. If someone were sniffing traffic (i.e. they intercepted the email), the file will be meaningless gobbledygook! The only way they could do anything with it is by creating a MediCam account and thereby leaving an audit trail as to who they are. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by Running Your Own Key Server.

MediCam uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate MediCam into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.5 Upload to Medical Record

It is possible to upload reports direct to an endpoint hosted by your institution much like how the app uploads to Box and Dropbox. The report will not be encrypted prior to being sent but it will be sent over HTTPS and therefore can be deemed as being sent securely. When uploading direct to an Endpoint Server the app will upload a zip file containing all the media files, a metadata.json file and a PDF report.

Upload to Medical Record

Institution Setup

You will need to set up your own Endpoint Server. As part of this you will need to write your own middleware to take reports uploaded to the endpoint and move them into your medical record system (MediCam does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.medicam.io.

For more information please see the Running Your Own Endpoint Server section below.

User Setup

Users within your institution should be instructed to add an "Institution" in their app. To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.medicam.io), and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app does the following:
    • Generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • Packages these two files along with the media and relevant thumbnails into a zipped file (package.encrypted).
    • Uploads the report to your Endpoint Server.
  3. The Endpoint Server will...
    • Download the email and extract the attached MediCam File.
    • Unzip the MediCam File.
    • Read the contents of the package.json file.
    The report can then be transferred into the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

The app will submit the file to Endpoint Server with the following file path:

POST https://{endpoint url}/api/report medicam_file

The POST accepts the form with two fields:

  • token This is the User Token generated from the User Server. It will be decoded so you can verify the user sending the report is an authentic MediCam user and they are who they say they are.
  • medicam_file This is the binary zip file (as discussed above).

Security

All reports should be uploaded over HTTPS. Using this technique we do not encrypt reports prior to submitting therefore we rely on data been sent securely via HTTPS. It is assumed that the endpoint will store all reports securely. The endpoint server that you set up can be tested using HTTP but should only ever be used in production using HTTPS.

1.6 Upload to Medical Record (with Dynamic Key Encryption)

It is possible to upload encrypted reports direct to an endpoint hosted by your institution. Much like how reports are encrypted before being emailed, here reports are being encrypted before being uploaded to an endpoint.

Upload to Medical Record (with Dynamic Key Encryption)

Institution Setup

You will need to set up your own Endpoint Server. As part of this you will need to write your own middleware to take reports uploaded to the endpoint and move them into your medical record system (MediCam does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.medicam.io.

For more information please see the Running Your Own Endpoint Server section below.

Once the server has been setup you are able to send reports.

User Setup

Users within your institution should be instructed to set up an "Institution" within the MediCam app on their device(s). To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Dynamic Key)", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.medicam.io), and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload with Dynamic Key Encryption

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. The app sends a request with the users details in the User Token and a Report ID to the Key Server. The Key Server will verify that the user details are valid (this ensures that request has come from a trusted source). The Key Server responds with a Key that is used by the app for the report encryption later in the process. By default the app will use a Key Server run by MediCam. Should you want your institution to restrict recipients to be only staff members of their institution, this can be achieved by running your own key server.
  3. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a MediCam File ({reportID}.medicam).
    • The app then upload the report to your Endpoint Server.
  4. Before the report can be transferred to the patient medical record system, the following occurs:
    • The Endpoint Server opens up and unzips the MediCam file. This exposes the package.json file and the package.encrypted file.
    • The Endpoint Server extracts the URL of the Key Server that was used to produce the Key used to encrypt the package.encrypted file.
    • The Endpoint Server sends a request off to the Key Server with the recipient’s User Token, and asks for the Key.
    • The Key Server logs the request and thereby produces an audit trail of who has accessed the report.
    • The Key Server responds with the Key used to decrypt the package.encrypted file.
    • The Endpoint Server decrypts the package.encrypted file and unzips the package.encrypted file.
  5. The report can then be transferred into the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Using this technique, reports will be encrypted in MediCam before they are sent. This means that the endpoint does not necessarily need to be transmitted over HTTPS in order for it to remain secure.

MediCam uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate MediCam into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

1.7 Upload to Medical Record (with Static Key Encryption)

It is possible to upload encrypted reports direct to an endpoint hosted by your institution but rather than using a dynamic key (as described in the section above) you use a "static" key. Here we use Public-key cryptography (key pair). The public key is distributed to users (used to encrypt reports) and the private key is stored on the Endpoint Server (to decrypt reports).

Upload to Medical Record (with Static Key Encryption)

Institution Setup

You will need to set up your own Endpoint Server. As part of this you will need to write your own middleware to take reports uploaded to the endpoint and move them into your medical record system (MediCam does not perform this integration).

See the Sample Ruby on Rails Endpoint Server repository. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.medicam.io.

For more information please see the Running Your Own Endpoint Server section below.

You will have to generate a key-pair. The private key is obviously stored on the Endpoint Server while the public key is distributed to users.

Once the server has been setup you are able to send reports.

User Setup

Users within your institution should be instructed to set up an "Institution" within the MediCam app on their device(s). To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Static Key)", enter the name of your institution (e.g. "My Hospital"), enter the "Endpoint" URL (e.g. http://endpoint.medicam.io), and in the the "Key" field enter the provided key.
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setup Institution Upload with Static Key Encryption

Sending

Now when a user submits a report the following occurs. (Note: the numbers correspond to the number in the diagram above.)

  1. When a users signs in/up, the User Server will return a User Token. The User Token is a hashed and signed version of the user data. It is used later for verifying user requests.
  2. A bit happens here!
    • The app generates a Metadata File (metadata.json), and a PDF document (report.pdf).
    • The app then packages these two files along with the media and relevant thumbnails into a zipped file (package.zip).
    • Using the Key (fetched from the Key Server above), the app then encrypts the package.zip file to create an encrypted file (package.encrypted).
    • The app then generates a package file (package.json) which contains the URL of the Key Server (so when it comes time to decrypt the report the app will know where to get the key from).
    • The app then zips the package.json file with the package.encrypted file and creates a MediCam File ({reportID}.medicam).
    • The app then upload the report to your Endpoint Server.
  3. Before the report can be transferred to the patient medical record system, the following occurs:
    • The Endpoint Server opens up and unzips the MediCam File. This exposes the package.json file and the package.encrypted file.
    • Using the private key, the Endpoint Server decrypts the package.encrypted file and unzips the package.encrypted file.
    • The report can then be transferred into the medical record system using whatever method is available (varies between systems). See the Contents of a Report section below for what data you might want to put in the medical record. It may be you just want the PDF, or you can insert the media items individually.

Security

Using this technique, reports will be encrypted in MediCam before they are sent. This means that reports sent to the endpoint does not necessarily need to be transmitted over HTTPS in order for it to remain secure.

MediCam uses RNCryptor for encrypting reports. RNCryptor is a cross-language AES Encrypter/Decrypter data format. The data format includes all the metadata required to securely implement AES encryption, as described in "Properly encrypting with AES with CommonCrypto," and iOS 6 Programming Pushing the Limits, Chapter 15. Specifically, it includes:

  • AES-256 encryption
  • CBC mode
  • Password stretching with PBKDF2
  • Password salting
  • Random IV
  • Encrypt-then-hash HMAC

This format was used because it is widely supported. This makes it easier for institutions to integrate MediCam into their medical record systems. There are implementations of RNCryptor in Swift, Objective-C, C, C++, C#, Erlang, Go, Haskell, Java, PHP, Python, Javascript, and Ruby.

This method relies on you generating a private and public key pair. The public key is what the users enter in the app as the "Static Key". The private key is stored on the endpoint and is obviously used to decrypt reports.


2. Contents of a Report

File Structure

A Report is sent/uploaded as a .medicam file. See the structure below.

  • {ReportID}.medicam
    • package.json
    • package.encrypted
      • metadata.json
      • report.pdf
      • consent.jpg (if consent is signed)
      • consent.m4a (if consent is verbal)
      • {ItemID}-thumbnail.jpg
      • {ItemID}.jpg (if media is a photo)
      • {ItemID}.m4v (if media is a video)
      • {ItemID}.m4a (if media is a audio)

Multiple media items can be included in a report and therefore there can be multiple {ItemID}-thumbnail.jpg and {ItemID}-thumbnail.jpg|m4v|m4a files.

To extract the package.json file out of the .medicam file you should unzip the .medicam file.

package.json

The package.json file contains the following:

{
  "keyserver_url": "##keyserver_url##"
}

Obviously ##keyserver_url## would be replaced with the URL of the Key Server used to encrypt the report (e.g. https://key.medicam.io).

metadata.json

The metadata.json file contains the following:

{
  "report": {
    "patient": {
      "firstname": "##patientfirstname##",
      "lastname": "##patientlastname##",
      "day": "##birthday##",
      "month": "##birthmonth##",
      "year": "##birthyear##",
      "patientid": "##patientid##",
      "translator": "##translator##",
      "guardian": "##guardian##"
    },
    "user": {
      "userid": "##userid##",
      "title": "##title##",
      "firstname": "##userfirstname##",
      "lastname": "##userlastname##",
      "email": "##email##",
      "country": "##country##"
    },
    "details": {
      "notes": "##notes##",
      "datetime": "##datetime##",
      "reportid": "##reportid##",
      "sendtype": "##sendtype##",
      "sendto": "##sendto##",
      "reportendpoint": "##reportendpoint##",
      "ip": "##ip##",
      "location": {
        "latitude": "##latitude##",
        "longitude": "##longitude##",
        "address": "##address##"
      },
      "platform": "##platform##",
      "architecture": "##architecture##",
      "manufacturer": "##manufacturer##",
      "model": "##model##",
      "os": "##os##",
      "uuid": "##uuid##",
      "version": "##version##",
      "pro": "##pro##"
    },
    "consent": {
      "type": "##consenttype##",
      "treatment": "##treatment##",
      "education": "##education##",
      "publication": "##publication##",
      "consentlevels": "##consentlevels##"
    },
    "media": [
      {
        "mediaid": "##mediaItems[i].id##",
        "type": "##mediaItems[i].type##",
        "levels": "##mediaItems[i].levels##"
      }
    ]
  }
}

Obviously all values surrounded by hashes would be replaced with appropriate values. The data in the media element can contain multiple values.

It is recommended that you test decrypting reports locally to see all the variations/values that are possible.

Decrypting .medicam files from command line

  1. Create a file called decrypt.rb and place the following in it:
    require 'ruby_rncryptor'
    
    # encryption key
    key = '##key##'
    
    input  = ARGV[0]
    output = ARGV[1]
    
    if input.to_s =~ /^$/ or output.to_s =~ /^$/
      puts "Usage: decrypt.rb input output"
      exit 1
    end
    
    encrypted = File.open(input, 'rb').read
    decrypted = RubyRNCryptor.decrypt(encrypted, key)
    File.open(output, 'wb').write(decrypted)
  2. Copy decrypt.rb (in the root directory) to another directory (e.g. your desktop).
  3. Navigate to that directory and run:
    $ gem install ruby_rncryptor
  4. Run the decrypt file in this format:
    $ ruby decrypt.rb input output
    For example $ ruby decrypt.rb 1234567890.medicam 1234567890.zip

3. Running Your Own Key Server

A Key Server is used to dish out keys which are used to encrypt reports in the MediCam app prior to sending. See the Methods of Sending/Submitting Reports section above for details on which methods use the Key Server.

If you want to limit who can send and/or receive MediCam reports from within your organizations, or you want to access the audit trail of who has accessed reports then you will need to set up your own Key Server. If you don't need this functionality then you can use the default Key Server provided by MediCam.

Before explaining how to setup your own Key Server, a brief recap on how the MediCam send process works will help.

Process when sending via email

When sending via email

When a user composes a "report" in the MediCam app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. By default the app uses a Key Server run by MediCam (https://key.medicam.io). All that Key Server does is dishes out keys and logs who access those keys when a report is opened.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".medicam" file. The app opens the default mail program on the device and attaches the encrypted report. The user then picks to whom they want to send the report just like composing a normal email.
  3. When the recipient receives the email they will be prompted to open the .medicam file in the MediCam app.
  4. When they do, the app will open the .medicam file and get the location of the key server. It will then send a request to the key server asking for the key to decrypt the report. Along with this request it sends the users information thereby giving us an "audit trail" of who has accessed the report. Once the key is received the app will decrypt the report and the recipient can see its contents.
When uploading to a medical record.

When a user composes a "report" in the app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. By default the app uses a Key Server run by MediCam. All that Key Server does is dishes out keys and logs who access those keys when a report is opened.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".medicam" file. The app sends the report to endpoint (URL).
  3. The endpoint receives the .medicam file and sends a request to the Key Server to get the key to decrypt the report. It then decrypts the report and in turn sends it on.
  4. The endpoint can then be configured to send to report another location (e.g. a patients medical record).
Run your own Key Server

To set up your own Key Server, MediCam provides a turnkey Docker image. It allows you to very simply set up and host your own Key Server and it can be easily configured to whitelist or blacklist certain email addresses. For example, you could add a rule that says only MediCam users that have an email address that ends in "@myhospital.com" can access the key to unlock reports.

Instruct users to use your Key Server

Users within your institution should be instructed to set up an "Institution" within the MediCam app on their device(s). To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Email", enter the name of your institution (e.g. "My Hospital"), leave the "Endpoint" field blank, and in the "Key Server" field enter the URL of your Key Server (e.g. https://key.medicam.io)
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution.

Setting up a Key Server

The Key Server server is built using Elixr and Phoenix. For ease of deployment and distribution we use Docker. It is designed to be installed in multiple locations. MediCam hosts a version on Digital Ocean (key.medicam.io), but institutions can run their own version within their network or on their own web hosting. You will not need to install Elixr as that is included in the Docker image we provide.

Please follow these instructions:

  1. Register your Key Server You will have to register your Key Server with MediCam in order to get a Key Server Token. During the send process, requests that comes through to the Key Server will contain a User Token. The Key Server Token on the Key Server needs to be compatible in order to verify the users details. All requests to get a Key to either encrypt or decrypt reports are logged by Key Servers and we need to verify that all requests are legitimate in order to maintain an accurate log/audit trail.
  2. Install Docker. To install Docker follow Instruction here: https://docs.docker.com/engine/installation/
  3. Pull the Docker image
    $ docker login
    $ docker pull medicam/keyserver
  4. Run docker image. You can run the Image in either HTTP or HTTPS. It is recommended that you use HTTPS but HTTP is provided for testing.
    To run the HTTP-only version...
    $ bin/docker-run secret-key [container-name [port [data-dir]]]
    
    secret-key      -- the same key you defined in `key_server_secret` of `config/secrets.yml`
    container-name  -- (default: keyserver) set different names for different environments.
    port            -- (default: 80) port number to listen for connections
    data-dir        -- (default: /home/deploy/data) path to directory holding data for this server (database and blacklist / whitelist)
    
    To run the HTTPS version...
    • You need to generate SSL certs and put them into your /certs directory. Name them privkey.pem (private key), cert.pem (cert), and fullchain.pem (intermediate chain certs).
    • Next, you need to run the Docker image as above (just use a different script -- bin/docker-run-ssl):
      $ bin/docker-run-ssl secret-key [container-name [port [data-dir [pk-file cert-file fullchain-file]]]
      
      pk-file -- (default: /certs/privkey.pem) path to the private key relative to `data-dir`
      cert-file -- (default: /certs/cert.pem) path to the cert file relative to `data-dir`
      fullchain-file -- (default: /certs/fullchain.pem) path to the intermediate certs chain file relative to `data-dir`
      
  5. Blacklist and whitelist email addresses (optional). Decryption key can be requested by users with allowed email addresses only. By default, everyone is welcome, but you can specify match patterns in `/blacklist` and `/whitelist` files -- a pattern per line (empty lines ignored). Patterns support wildcards. For example:
    # blacklist
    *@gmail.com
    [email protected]
    
    # whitelist
    [email protected]
    The above two files will forbid `[email protected]` and everyone from `@gmail.com` except for `[email protected]` from accessing the key server.
    NOTE: in order for changes to these files to take effect, the application (Docker container) has to be restarted.
  6. Generate SSL certificates. We recommend using free SSL certificates from LetsEncrypt. Here's what you do:
    $ git clone https://github.com/certbot/certbot
    $ cd certbot
    Stop any web service or app running on port 80 here. You should not be running them, but anyway. It's important the port is unused.
    $ ./certbot-auto certonly --standalone -d 
    Follow simple instructions of the installer and you should get your certs saved to `/etc/letsencrypt/live/`.
    $ mkdir /certs
    $ sudo cp -L /etc/letsencrypt/live//* /certs
    This will copy your certs into the data dir that is visible from inside the Docker image. Verify that the names of files are:
    * cert.pem
    * privkey.pem
    * fullchain.pem
    You are ready to start the server.
  7. Renew SSL certificates (when required). In 3 months your certs will expire and you will need to renew them. LetsEncrypt has a simple script for this, but you must stop the service / app running on port 80 first, and then:
    $ ./certbot-auto renew
    $ sudo cp -L /etc/letsencrypt/live//* /certs
    Now you can restart the docker image.

4. Running Your Own Endpoint Server

An Endpoint Server is a server that you host that can accept uploaded MediCam reports. Even though it is not technically correct we also refer to the "Middleware" server that is used in the Email to Medical Record as an Endpoint Server.

The Endpoint Server will host middleware that your IT department will need to create. It simply takes reports uploaded to the endpoint and moves them into your medical record system. MediCam does not perform this integration. MediCam provides a Sample Ruby on Rails Endpoint Server that does this. It should be a reasonably easy task to write something similar in another language.

Before explaining how to setup your own Endpoint Server, a brief recap on how the MediCam send process works will help.

Encrypt the report in the app prior to sending (using a Dynamic Key)

In the diagram at the top of the page see the yellow lines. When a user composes a "report" in the app and presses the "Submit" button...

  1. The app fetches a Key from a Key Server. All that Key Server does is dishes out keys and logs who access those keys when a report is opened. You can use the Key Server run by MediCam or you can run your own Key Server.
  2. The app packages up the media, the data, and a PDF into a Report. This Report is then encrypted using the Key. The report is then packaged along with the location of the key server into ".medicam" file. The app sends the report to endpoint (URL).
  3. The endpoint receives the .medicam file and sends a request to the Key Server to get the key to decrypt the report. It then decrypts the report and in turn sends it on.
  4. The endpoint can then be configured to send to report another location (e.g. a patients medical record).
Don't encrypt the report in the app prior to sending.

In the diagram at the top of the page see the green lines. When a user composes a "report" in the app and presses the "Submit" button...

  1. The app packages up the media, the data, and a PDF into a Report. The app sends the report to endpoint (URL).
  2. The endpoint receives the Report (zipped file that contains the media, data and PDF).
  3. The endpoint can then be configured to send to report another location (e.g. a patients medical record).

HTTP or HTTPS

It is possible to send reports to an endpoint via HTTP or HTTPS. It is also possible to specify if the reports should be encrypted in the app prior to being sent. Obviously, it is possible to send reports that are encrypted in the app as well as sending via HTTPS also. This is recommended. If using HTTP you should make sure that reports are always encrypted in the app before being sent. This is a big security vulnerability if not!

Whether a report is send via HTTP or HTTPS is merely a matter of which protocol is specified when an institution is added. "http://endpoint.medicam.io" would send it via HTTP and "https://endpoint.medicam.io" would send it via HTTPS.

Encryption options

Below we will discuss the different processes relating to whether the report is encrypted in the app before sending or not.

Process when sending to an endpoint

The Test an Endpoint Server

To trial this system, you do not need to set up your own endpoint yet. We have a test endpoint but, please note, all reports are visible to the public. DO NOT USE IT FOR LIVE PATIENT DATA.

Test users within your institution should be instructed to set up an "Institution" within the MediCam app on their device(s). To do this they have to do the following:

  • Open the MediCam app and tap on "Settings".
  • Tap on "Institutions Medical Record" and then the "Add" button in the top right.
  • In "Send type" select "Post (Dynamic Key)", enter the name of your institution (e.g. "My Hospital"), in the "Endpoint" field enter "http://endpoint.medicam.io", and leave the "Key Server" field blank.
  • Tap the "Save" button in the top right and go back to the main form.
  • Now in the main form, in the "Send to" options there will be a "My Hospital" listing under "Institutions". Tap on that.

They are now able to send reports to your institution. When test users "Submit" a report they will be uploaded to the demo endpoint. Once finished uploading, if you go to http://endpoint.medicam.io/ you will see the reports uploaded. Obviously under normal circumstances a page like this would not be visible to the public.

Setup your own Endpoint Server

As stated above, you will need to set up your own Endpoint Server. As part of this you will need to write your own middleware to take reports uploaded to the endpoint an move them into your medical record system (MediCam does not perform this integration).

For details on how to handle the various tasks an Endpoint Server needs to perform, please see the Sample Ruby on Rails Endpoint Server. Although written in Rails, the code should reasonably easy to follow even if you are not familiar with Rails. You can see the result at http://endpoint.medicam.io.


5. Getting Reports Into the Medical Record

Please see the section above, Running Your Own Endpoint Server.


6. Licensing and User Management

Benefits of a License?

As well as allowing users within an institution to submit reports to a patients medical record, all users within an institution will have access to MediCam PRO features.

Who needs a License?

An institution that wants to allow their users to generate MediCam reports and have then inserted into the patients medical record will need a licence. As has been discussed above, this includes the following methods of sending/submitting reports:

If your institution uses Box or Dropbox for storage you will find it easier purchasing an enterprise licence rather than each user having to purchase access to MediCam PRO through the App Store or Google Play.

User Management

Assigning which users are part of the enterprise licence can be done by using the domain name in the email address of users (e.g. all users with an email address ending in "@myhospital.com") or by providing a comma separated list of email addresses.

Get a License

To learn more about a licence and which solution might best suit your needs, please contact us.

Contact Us About a License