Device Data

In MyDataHelps, participants may contribute data collected by wearables and other devices.

Because device data is a powerful tool available to RKStudio studies, we strongly recommend reading about device data concepts.

Query Device Data Points

MyDataHelps.queryDeviceData(queryParameters)

Parameters

namespace enum (required)

Specifies the source framework for the device data. Must be one of the following values:

  • “Project”: Data persisted by Project sources, including the Persist Device Data API described below.
  • “Fitbit”: Data persisted by a linked Fitbit account.
  • “AppleHealth”: Data imported from AppleHealth.
  • “GoogleFit”: Data imported from GoogleFit.
type string array

List of types of device data, e.g. HeartRate.

observedAfter date

Filters device data points to those observed after this date.

observedBefore date

Filters device data points to those observed before this date.

limit int

How many entries to include in each page of results. Default and maximum is 100.

pageID guid

Each page of results will return a nextPageID if there are additional pages that can be queried. Supply that to pageID to query the next page. When excluded, retrieves the first page.

Returns

Promise<DeviceDataPointsPage>

Resolves to a result object containing a page of device data points.

result.deviceDataPoints collection

A list of DeviceDataPoints filtered by the query parameters.

result.deviceDataPoints[n].id guid

Auto-generated, globally-unique identifier for this device data point.

result.deviceDataPoints[n].namespace enum

Identifies device data as from a specific source system. One of the following values:

  • “Project”: Data persisted by the Persist Device Data Points operation below.
  • “Fitbit”: Data imported from a linked Fitbit account.
  • “AppleHealth”: Data imported from AppleHealth.
  • “GoogleFit”: Data imported from GoogleFit.
result.deviceDataPoints[n].deviceDataContextID guid

Identifier for a group of device data points, which share some context. Will be null if the device data point isn’t grouped.

result.deviceDataPoints[n].insertedDate date

Date (in UTC) when the data point was first added.

result.deviceDataPoints[n].modifiedDate date

Date (in UTC) when the data point was last modified.

result.deviceDataPoints[n].identifier string

String used to name a device data point.

result.deviceDataPoints[n].type string

The general category this device data point belongs in, or what the device data represents.

result.deviceDataPoints[n].value string

The observed value for what this device data point represents, e.g. number of steps from a step tracker.

result.deviceDataPoints[n].units string

The units, if any, that the device data was recorded in.

result.deviceDataPoints[n].properties object

A non-standard object whose key-value pairs represent metadata associated with this device data point.

result.deviceDataPoints[n].source deviceDataSource

An object containing identifying information about the device which recorded the data point.

result.deviceDataPoints[n].source.identifier string

Identifying string for the data source. Natural key property for device data source.

result.deviceDataPoints[n].source.properties object

An object whose fields represent key/value pairs, describing the device data source.

result.deviceDataPoints[n].startDate date

The date at which this device data point began being recorded (for data that is recorded over time).

result.deviceDataPoints[n].observationDate date

The date at which this device data point was completely recorded.

result.nextPageID guid

An ID to be used with subsequent queries. Results from queries using this ID as the pageID parameter will show the next page of results. This field is null if there isn’t a next page.

Availability

MyDataHelps Applications
Web View Steps
Example: Querying for a Specific Page of Project Device Data Points
var queryParams = {
	namespace: "Project",
	type: "HeartRate",
	observedAfter: "2021-02-18",
	observedBefore: "2021-03-01T12:00:00-4:00",
	limit: 100,
	pageID: "a706abd5-cc85-482b-909c-ddd92c8abbde"
};

MyDataHelps.queryDeviceData(queryParameters)
	.then( function(result) {
		console.log(result);
	} );
Console Output
{ 
	"deviceDataPoints": [ 
		{ 
			"id": "d3a770d3-306b-eb11-aa7f-f8e4e3480e0d",
			"namespace": "Project",
			"deviceDataContextID": "8c8ca79c-cb62-4e01-acaf-3201ca88e7bb", 
			"insertedDate": "2021-02-19T23:45:07.497Z",
			"modifiedDate": "2021-02-19T23:45:07.497Z",
			"identifier": "41a0f952-a9eb-4e05-8ff1-20229460e333",
			"type": "HeartRate",
			"value": "73",
			"units": "BPM", 
			"properties": { "PostalCode": "48104", "Sequence": "32" },
			"source": {
				"identifier": "BPCuff1",
				"properties":
				{
					"Model": "BP130X",
					"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
				}
			},
			"startDate": "2021-02-19T23:44:06.0Z",
			"observationDate": "2021-02-19T23:45:05.999Z"
		} ], 
		"nextPageID": null
	}
}

Persist Device Data Points

MyDataHelps.persistDeviceData(deviceDataPoints)

Persist device data can be used to add new or update existing points. Each device data point is uniquely identified by a combination of its properties, called a natural key. Properties that are part of the natural key are identified below.

To update an existing device data point, persist one whose natural key properties exactly match the one to be updated. All non-natural key properties will be updated to your persisted point.

To add a new device data point, provide enough natural key properties to uniquely identify it. Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.

Parameters

identifier string

String used to name a device data point. Natural key property.

type string (required)

The general category this device data point belongs in, or what the device data represents. Natural key property.

value string (required)

The value of the recorded data point.

units string

The units, if any, that the data was recorded in.

properties object

An object whose key-value pairs represent properties of the device data point.

source deviceDataSource

An object containing identifying information about the device which recorded the data point.

source.identifier string

Identifying string for the data source. Natural key property for device data source.

source.properties object

An object whose fields represent key/value pairs, describing the device data source.

startDate date

The date at which this device data point began being recorded (for data that is recorded over time). Natural key property.

observationDate date

The date at which this device data point was completely recorded. Natural key property.

Availability

MyDataHelps Applications
Web View Steps
Example: Persisting Blood Pressure Device Data
var deviceDataSource = {
	identifier: "BPCuff1",
	properties:
	{
		"Model": "BP130X",
		"Serial": "17117bb6-177d-4f89-a25b-f9274eb8d4ff"
	}
};

var deviceDataPoints = [ {
	identifier: "c87223f6-174d-4453-bbfd-c24021a7161d",
	type: "HeartRate",
	value: "73",
	properties: {
		"PostalCode": 48104,
		"Sequence": "32"
	},
	source: deviceDataSource
} ];

MyDataHelps.persistDeviceDataPoints(deviceDataPoints)
	.then( function() {
		console.log( "Device data persisted" );
	} );