A shim is an adapter that reads raw data from a third-party API (e.g. Jawbone, Fitbit) and converts that data into an Open mHealth compliant data format. It's called a shim because it lets you treat third-party data like Open mHealth compliant data when writing your application. To learn more about shims, please visit the shim section on our site.

A shim is a library, not an application. To use a shim, it needs to be hosted in a standalone application called a shim server. The shim server API lets your application use a shim to read data from a third-party API. This data is available in two formats; the raw format produced by the third-party API and the converted Open mHealth compliant format. To make it easier to use the shim server, we've provided a shim server UI that can trigger authentication flows and make requests.

This repository contains a shim server, a shim server UI, and shims for third-party APIs. The currently supported APIs are:

• Fat Secret
• Fitbit
• Microsoft HealthVault
• Jawbone UP
• RunKeeper (application management portal)
• Withings

The above links point to the developer website of each API. You'll need to visit these websites to register your application and obtain authentication credentials for each of the shims you want to enable.

If any of links are incorrect or out of date, please submit an issue to let us know.

Please note that the shim server is meant as a discovery and experimentation tool. It has not been secured and does not attempt to protect the data retrieved from third-party APIs.

There are three ways to build and run the shim server.

1. You can run a Docker container that executes a pre-built binary.

• This is the fastest way to get up and running and isolates the install from your system.

1. You can build all the code from source and run it on your host system.

• This is a quick way to get up and running if your system already has MongoDB and is prepped to build Java code.

1. You can run a Docker container that builds all the code from source and executes the resulting binary.

• This isolates the install from your system while still letting you hack the code. But it can take a while to build the container due to the large number of libraries and subsystems that need to be downloaded and installed.
• If you know Docker and want to speed things up, remove optional components from the Dockerfile and link them from separate containers.

If you don't have Docker installed, download Docker and follow the installation instructions for your platform.

Then in a terminal,

1. If you don't already have a MongoDB container, download one by running

• docker pull mongo:latest
• Note that this will download around 400 MB of Docker images.

1. If your MongoDB container isn't running, start it by running

• docker run --name some-mongo -d mongo:latest

1. Download the shim server image by running

• docker pull openmhealth/omh-shim-server:latest
• Note that this will download up to 600MB of Docker images. (203MB for Ubuntu, 350MB for the OpenJDK 7 JRE, and 30MB for the shim server and its dependencies.)

1. Start the shim server by running

• docker run -e openmhealth.shim.server.callbackUrlBase=http://<your-docker-host>:8083 --link some-mongo:mongo -d -p 8083:8083 'openmhealth/omh-shim-server:latest'

1. The server should now be running on the Docker host on default port 8083. You can change the port number in the Docker run command.
2. Visit http://<your-docker-host>:8083 in a browser.

If you prefer not to use Docker,

1. You must have a Java 7 or higher JDK installed. You can use either OpenJDK or the Oracle JDK.
2. A running MongoDB installation is required.
3. Maven is required to build and install Microsoft HealthVault libraries.
4. You technically don't need to run the shim server UI, but it makes your life easier. If you're building the UI,
5. Node.js is required.
6. Xcode Command Line Tools are required if you're on a Mac.

Then,

1. Clone this Git repository.
2. Navigate to the shim-server-ui directory in a terminal and run
3. npm install
4. sudo npm install -g grunt-cli bower
5. bower install
6. grunt build
7. Navigate to the shim-server/src/main/resources directory and run
8. ln -s ../../../../shim-server-ui/dist public
9. Edit the application.yaml file.

• Check that the spring:data:mongodb:uri parameter points to your running MongoDB instance.
• You might need to change the host to localhost, for example.

1. Follow these instructions to install Microsoft HealthVault libraries. These libraries are currently required for the shim server to work.
2. To build and run the shim server, navigate to the base directory and run ./gradlew shim-server:bootRun
3. The server should now be running on localhost on port 8083. You can change the port number in the application.yaml file.
4. Visit http://localhost:8083 in a browser.

The Microsoft HealthVault shim has dependencies which can't be automatically downloaded from public servers, at least not yet. To add HealthVault support to the shim server,

1. Download the HealthVault Java Library version R1.6.0 archive.
2. Extract the archive.
3. Navigate to the extracted directory in a terminal.
4. Run mvn install -N && mvn install --pl sdk,hv-jaxb -DskipTests

This will make the HealthVault libraries available to Gradle.

If you don't have Docker installed, download Docker and follow the installation instructions for your platform.

Then,

1. Download the latest release of this Git repository or clone it.
2. Navigate to the docker/source directory in a terminal.
3. Run docker build -t="openmhealth/omh-shim-server" .

• This will require about 1.5GB of disk space.

1. Run docker run -d -p 8083:8083 -p 2022:22 openmhealth/omh-shim-server
2. The server should now be running on the Docker host on default port 8083. You can change the port number in the Docker run command.
3. Visit http://<your-docker-host>:8083 in a browser.

If you want to SSH into the container, run ssh root@<your-docker-host> -p 2022. The password is docker.

You need to obtain authentication credentials, typically an OAuth client ID and client secret, for any shim you'd like to run. These are obtained from the developer websites of the third-party APIs.

Once credentials are obtained for a particular API, navigate to the settings tab of the shim server UI and fill them in.

(If you didn't build the UI, uncomment and replace the corresponding clientId and clientSecret placeholders in the application.yaml file with your new credentials and restart Jetty. If you installed using Docker, you can restart Jetty using supervisorctl restart jetty. If you installed manually, terminate your running Gradle process and restart it.)

The data produced by a third-party API belongs to some user account registered on the third-party system. To allow a shim to read that data, you'll need to initiate an authorization process that lets the account holder grant the shim access to their data.

To initiate the authorization process from the UI,

1. Type in an arbitrary user handle. This handle can be anything, it's just your way of referring to third-party API users.
2. Press Find and the UI will show you a Connect button for each API whose authentication credentials have been configured.
3. Click Connect and a pop-up will open.
4. Follow the authorization prompts. You should see an AUTHORIZE JSON response.
5. Close the pop-up.

To initiate the authorization process programmatically,

1. Make a GET request to http://<host>:8083/authorize/{shim}?username={userId}

• The shim path parameter should be one of the names listed below, e.g. fitbit.
• The username query parameter can be set to any unique identifier you'd like to use to identify the user.

1. In the returned JSON response, find the authorizationUrl value and redirect your user to this URL. Your user will land on the third-party website where they can login and authorize access to their third-party user account.
2. Once authorized, they will be redirected to http://<host>:8083/authorize/{shim_name}/callback along with an approval response.

To pull data from the third-party API using the UI,

1. Click the nam of the connected third-party API.
2. Fill in the date range you're interested in.
3. Press the Raw button for raw data, or the Normalized button for data that has been converted to an Open mHealth compliant data format.

To pull data from the third-party API programmatically, make requests in the format

http://<host>:8083/data/{shim}/{endPoint}?username={userId}&dateStart=yyyy-MM-dd&dateEnd=yyyy-MM-dd&normalize={true|false}

The URL can be broken down as follows

• The shim and username path variables are the same as above.
• The endPoint path variable roughly corresponds to the type of data to retrieve. There's a list of these below.
• The normalize parameter controls whether the shim returns data in a raw third-party API format (false) or in an Open mHealth compliant format (true).

The following is a nested list in the format

• shim name
  • endpoint name
    • Open mHealth compliant data the endpoint can produce

The currently supported shims are

• fitbit
  • activity
    • omh:physical-activity
  • blood_pressure
    • omh:blood-pressure
  • blood_glucose
    • omh:blood-glucose
  • heart
    • omh:heart-rate
  • steps
    • omh:step-count
  • weight
    • omh:body-weight
• healthvault
  • activity
    • omh:physical-activity
  • blood_glucose
    • omh:blood-glucose
  • blood_pressure
    • omh:blood-pressure
    • omh:heart-rate
  • height
    • omh:body-height
  • weight
    • omh:body-weight
• jawbone
  • body
    • omh:body-weight
  • moves
    • omh:step-count
  • sleep
    • omh:sleep-duration
  • workouts
    • omh:physical-activity
• runkeeper
  • activity
    • omh:physical-activity
  • weight
    • omh:body-weight
• withings
  • body
    • omh:blood-pressure
    • omh:body-height
    • omh:body-weight
    • omh:heart-rate
  • intraday
    • omh:step-count
  • sleep
    • omh:sleep-duration

You can learn more about these shims and endpoints on the Open mHealth developer site.

The list of supported third-party APIs will grow over time as more shims are added. If you'd like to contribute a shim to work with your API or a third-party API, send us a pull request. If you need any help, feel free to reach out on admin@openmhealth.org or on the Open mHealth developer group.