Device event subType: status

Jump to...(notable fields on this type)

NB: All fields are required unless otherwise noted.

Jump to example JSON:

type

[ingestion, storage, client] The string deviceEvent.

QUICK SUMMARY
Required:
    jellyfish: yes
    platform: yes

subType

[ingestion, storage, client] The string status.

QUICK SUMMARY
Required:
    jellyfish: yes
    platform: yes

This is the Tidepool data type for an insulin pump's insulin delivery status, basically only used to represent suspensions of insulin delivery—intervals of time when neither bolus or basal insulin was delivered by an insulin pump. When a user suspends an insulin pump or, alternatively, when the pump suspends itself for some reason automatically, any bolus currently in progress is terminated, resulting in a partially delivered bolusa, and the basal constant drip of background insulin is also stopped.

In the same way that suspensions of insulin delivery can be either manual (programmed by the user) or automatic, the resumption of insulin delivery can be the result of user action or automatic.


status

[ingestion] String value encoding insulin pump status as suspended or resumed.

[storage, client] The string suspended.

QUICK SUMMARY
Required:
    jellyfish: yes
    platform: yes
Range:
    jellyfish: Must be one of:
        `suspended`
        `resumed`
    platform: The string `suspended`.

An insulin pump can only be in one of two insulin delivery states: normal operation or suspended.

The legacy jellyfish ingestion service accepted data with two possible values for status: suspended or resumed. The service then looked for tuples of events starting with a suspended and concluding with a resumed, merging each tuple into a single suspended event with a duration calculated from the timestamps of all included events. Events were chained together by embedding the immediately preceding status event inside each new status event in a previous field. See this document on the previous field on status events for a detailed explanation of this soon-to-be-deprecated system.

In Tidepool's new platform APIs under construction at the time of the drafting of this documentation in June, 2016, the only accepted value for the status field is suspended.


duration

This field is optional when ingesting data through the jellyfish service but required when ingesting data through the new platform APIs.

[ingestion, storage, client] An integer value representing a duration of time in milliseconds.

QUICK SUMMARY
Required:
    jellyfish: no (optional)
    platform: yes
Numerical type: Integer value representing milliseconds.
Range:
    min: 0
    max: < ∞

When ingesting data through the legacy jellyfish data ingestion service, duration is optional because jellyfish also uses the sequence of pump status events to determine their durations (in particular the duration of suspensions) - see previous for details.

In Tidepool's new platform APIs (under active development as of June, 2016 at the time of the initial drafting of this document), the duration field will be required on all status events. In essence, we are moving to a system that places the burden on the client uploading data to determine the duration of suspensions of insulin delivery based on the sequence of suspend and resume events.

There is no upper bound on the value of the duration for suspensions of insulin delivery because there is no upper bound on this value in reality: a user may switch between different insulin delivery devices or go on a "pump vacation" and thus leave a particular device in the suspended mode for an arbitrary duration of time counted in days, weeks, or even months.


expectedDuration

This field is optional. At present, it is only added by the jellyfish data ingestion service.

[storage, client] An integer value representing an original programmed duration of time in milliseconds, copied from the duration field on ingestion when a following event has resulted in truncation of the original programmed duration.

QUICK SUMMARY
Required:
    jellyfish: no (optional)
    platform: no (optional)
Numerical type: Integer value representing milliseconds.
Range:
    min: >= `duration`
    max: < ∞

The majority of insulin delivery devices do not provide an interface for scheduling suspensions of insulin delivery such that the insulin pump will automatically resume at the conclusion of the scheduled time period. However, the Insulet OmniPod insulin delivery system does provide an interface of this kind. It is thus only for an OmniPod system that it is possible - though still optional - for an expectedDuration field to appear. When this field is present, the value of expectedDuration is the original user-programmed duration for the suspension of insulin delivery, and the duration of the event will have a smaller value representing the actual elapsed time of the suspension, which must have been canceled by the user prior to its scheduled conclusion.

Note that there is one common workflow that will result in the early cancellation of a scheduled suspension of insulin delivery for OmniPod users: in order to change the device's display date & time on an OmniPod system, it is necessary to suspend the device (by scheduling a suspension of insulin delivery).


reason

[ingestion, storage, client] An object with two key-value pairs encoding the cause of a suspended or resumed event as manual (user-initiated) or automatic (pump-initiated).

QUICK SUMMARY
Required:
    jellyfish: yes
    platform: yes
Range: Must be one of:
    `manual`
    `automatic`

The reason is a simplified indication of why the pump delivery status changed, both on suspension of insulin delivery and on resumption. In the legacy jellyfish system (described in detail in previous), reason is an object with one key-value pair, either a key suspended with possible values manual or automatic or resumed with the sample possible values. As part of the ingestion process, jellyfish will collect the reasons for suspension and resumption into a single reason object with both key-value pairs in the final form of the event stored in the database.

On the other hand, when pushing up data through the new platform APIs, the reason object should include both the suspended and resumed keys with possible values of manual and automatic for each.

We define manual suspension or resumption as any user-initiated method of effecting these states, and we define automatic as anything not user-initiated. One type of automatic suspension (and potentially also later resumption) occurs on insulin pumps that include a low-glucose suspend feature whereby the pump, when "listening" to data from a blood glucose sensor (i.e., cbg data), suspends insulin delivery if the blood glucose values in the data stream either drop below a certain threshold or are predicted to soon drop below the threshold. The insulin delivery device may also automatically resume from the suspended state in response to rising blood glucose values or after a certain amount of time has elapsed.

By convention, we also include more device-specific information about the cause of suspensions and resumptions, if available, in the optional payload embedded object on the event. For example, in the case of the Medtronic 530G insulin pumps with the low-glucose suspend (LGS) feature, there is a distinction between circumstancesa in which the pump resumes from an LGS suspension automatically after two hours depending on whether the user interacted with any of the LGS alarms during the duration of the suspension. We represent this distinction on the event in the payload as follows (specifically in the user_intervention key under resumed):

{
    ...
    "reason": {
        "suspended": "automatic",
        "resumed": "automatic"
    },
    "payload": {
        "suspended": {
            "cause": "low_glucose",
            "threshold": 80
        },
        "resumed": {
            "cause": "timed_out",
            "user_intervention": "ignored"
        }
    }
    ...
}

previous

This field is optional when ingesting data through the jellyfish service but will no longer exist when ingesting data through the new platform APIs.

[ingestion] An object representing the status event just prior to this event or, equivalently, just the id of said object.

[storage, client] This field does not appear, as it is only used in processing during ingestion and not stored.

QUICK SUMMARY
Required:
    jellyfish: no (optional)
    platform: nonexistent

See previous for detailed documentation on this deprecated field.


clockDriftOffset

See common fields.


conversionOffset

See common fields.


deviceId

See common fields.


deviceTime

See common fields.


time

See common fields.


timezoneOffset

See common fields.


uploadId

See common fields.


_active

See common fields.


_groupId

See common fields.


_schemaVersion

See common fields.


_version

See common fields.


createdTime

See common fields.


guid

See common fields.


id

See common fields.


example (client)

{
    "type": "deviceEvent",
    "subType": "status",
    "status": "suspended",
    "duration": 3600000,
    "expectedDuration": 4320000,
    "reason": {
        "suspended": "automatic",
        "resumed": "automatic"
    },
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "deviceId": "DevId0987654321",
    "deviceTime": "2016-06-13T19:05:45",
    "guid": "08aa9d8f-d9df-4263-a178-68fbcdd066ef",
    "id": "0380cf9a82ea4fe2b044e71a9f086382",
    "time": "2016-06-14T02:05:45.320Z",
    "timezoneOffset": -420,
    "uploadId": "SampleUploadId"
}

example (ingestion)

{
    "type": "deviceEvent",
    "subType": "status",
    "status": "suspended",
    "duration": 48600000,
    "expectedDuration": 58320000,
    "reason": {
        "suspended": "manual",
        "resumed": "manual"
    },
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "deviceId": "DevId0987654321",
    "deviceTime": "2016-06-13T19:05:45",
    "time": "2016-06-14T02:05:45.321Z",
    "timezoneOffset": -420,
    "uploadId": "SampleUploadId"
}

example (storage)

{
    "type": "deviceEvent",
    "subType": "status",
    "status": "suspended",
    "duration": 32400000,
    "expectedDuration": 38880000,
    "reason": {
        "suspended": "automatic",
        "resumed": "manual"
    },
    "_active": true,
    "_groupId": "abcdef",
    "_schemaVersion": 0,
    "_version": 0,
    "clockDriftOffset": 0,
    "conversionOffset": 0,
    "createdTime": "2016-06-14T02:05:50.321Z",
    "deviceId": "DevId0987654321",
    "deviceTime": "2016-06-13T19:05:45",
    "guid": "ec271750-46cc-429d-85c3-0488304945ad",
    "id": "71845a4f9f1a4cb188552836286238c1",
    "time": "2016-06-14T02:05:45.321Z",
    "timezoneOffset": -420,
    "uploadId": "SampleUploadId"
}
a. Specifically determining whether or not a temp basal that was in effect before the automatic suspension is resumed or not (assuming it's programmed duration would have it still be in effect). If the user did not interact with any of the alerts during the automatic suspension, the temp basal is not resumed. If the user did acknowledge the automatic suspension, however, a temp basal that would still be in effect is resumed at the conclusion of two hours of suspension. This is explained on pages 124-125 of the Medtronic 530G user manual.