Message Headers

Overview

When sending telemetry data to the Cold Chain Data Interchange, Telemetry Providers must include a set of required metadata, which are communicated via HTTP message headers. In addition to the required metadata, Telemetry Providers may also provide other metadata -- including custom or proprietary fields -- through this same HTTP header method. This page provides technical details and requirements for use of HTTP message headers with the Data Interchange, including documentation on required, optional, and custom headers.

Telemetry Consumers should pay special attention to the section Special considerations for Telemetry Consumers, later in this document.

Required Metadata Headers

Some required metadata must be included in the HTTP headers of each published report. The following headers are required in each HTTP POST when sending data to the Data Interchange:

ce-id

Type - string
Description - The unique identifier for this data report
Example - 831-002::2020-09-18T12:01:38.376Z

Telemetry Providers must ensure that ce-source + ce-id is unique for each distinct event sent to the Data Interchange. If a duplicate event is re-sent (e.g. due to a network error) it MAY have the same ce-id. Telemetry Consumers MAY assume that Events with identical ce-source and ce-id are duplicates.

It is common to generate the value for the ce-id header by combining a cold chain equipment identifier (such as a data logger serial) with the originating event timestamp.  For example, if a report were sent from a logger with serial 83421AZ-143 a reasonable ce-id might be constructed as 83421AZ-143-2020-01-01T12:30:00.828Z.

ce-specversion

Type - string
Description - The CloudEvent specification version
Example - 1.0

The value 1.0 is the only value that is currently supported by the Data Interchange.

ce-type

Type - string
Description - The type or classification of the transmitted data report
Example - org.nhgh.varo.report.v1

The value for this field is defined by the Telemetry Provider. In absence of an existing naming convention, is recommended that Telemetry Providers use reverse domain name notation (as shown in the example) to identify the type of data reports. In the example shown above, the value for this field also includes an optional version element (i.e., v1), which may be helpful to Telemetry Consumers when the format of a report changes.

It is common for Telemetry Consumers to receive a variety of different data reports and formats in the same event stream. To ensure that different data is processed correctly, the Telemetry Consumer must be able to identify the content of each event. In addition to the basic HTTP Content-Type, the ce-type field helps the Telemetry Consumer identify the content of the payload for accurate processing.

Note that ce-type may not, by itself, be sufficient to indicate the data schema of the payload. It is possible that reports sent from multiple devices could use different schemas, but may be identified with the same ce-type. The Data Interchange does not enforce any rules to prevent this scenario. If a detailed schema is formally documented, it is recommended that Telemetry Consumers reference this schema in the optional ce-dataschema header defined in the optional metadata section.

ce-source

Type - uri
Description - The source of the event. The value of this field may be any valid URI registered with the Data Interchange.
Example - /widget-maker/telemetry/v1, https://telemetry.widget-maker.org/v1

A source URI must be registered in the Data Interchange upon creation of a new Telemetry Provider organization. Registered source URI values for your Telemetry Provider organization can be reviewed and updated by logging in to the Data Interchange and navigating to the Organization page.

dx-token

Type - string
Description - An access token, provided by the Data Interchange, that permits publication of data to the Data Interchange.
Example - 675F928zkT993xjfT1ZL0Aprn5

This token will be generated in the Data Interchange upon creation of a new Telemetry Provider organization. As with the ce-source (above), Telemetry Providers can identify the correct value of this field by logging into the Data Interchange.

dx-owner

Type - uri
Description - URI of a Data Owner, registered with the Data Interchange, to which the data transmission should be routed.
Example - https://health.gov.ng

The value of this field will be registered in the Data Interchange upon creation of a new Data Owner organization. Telemetry Providers can identify valid values of this field by logging in to the Data Interchange and navigating to the Data Owners page.

Strongly Recommended Metadata

In addition to the required metadata headers, there is additional metadata that is strongly recommended to be sent with each data payload -- if such data is available. Although the Data Interchange does not enforce hard requirements on the inclusion of this data, Telemetry Consumers have a reasonable expectation that such metadata is included whenever it is available. This optional metadata can provide valuable context to downstream reporting tools/processors that consume data from the Data Interchange. The Data Interchange does not use this additional metadata for routing; it simply passes it through to the data consumer.

At the bottom of this document you'll find definitions for additional headers that can be sent when publishing events.

By convention, all headers that include the dx- prefix provide extra metadata about the report itself. In addition to the headers documented here, Telemetry Providers may include custom metadata by using the prefix dx-ext- in the name of any custom HTTP headers that are sent to the Data Interchange. Any custom headers that are supplied will be passed through the Data Interchange, to Telemetry Consumers, along with all other headers that are described in this document.

Although optional, the ce-time header is especially valuable. ce-time should be the time the originating event was created.

Logical Metadata Groups

The following sections describe logical groupings of headers, which clarify the relationship between different headers.

Logger group

The temperature data logger (tdl) headers dx-tdl-manufacturer, dx-tdl-model, and dx-tdl-serial can be used to uniquely identify the data logger that generated the report. For cold chain equipment with an integrated monitoring system, these headers may be identical to the dx-fridge- headers below.  

Location group

The location headers dx-location-latitude, dx-location-longitude, and dx-location-accuracy can help associate a report with a region inside a country. Accuracy is important to indicate the area around the latitude and longitude values where the device may have been. Even if the accuracy is greater than hundreds of meters this information can still be invaluable for correlating a report to a facility. 

Fridge group

The fridge headers dx-fridge-manufacturer, dx-fridge-model, and dx-fridge-assigned-id are used to uniquely identify the cold chain equipment (fridges and freezers), if this data is available.

Facility group

The facility headers dx-facility-name, dx-facility-contact-name, and dx-facility-contact-phone are also very useful headers that can help managers or telemetry consumer dashboards with contact information when there are issues with cold chain equipment. The facility name can also be used to help locate and identify the facility associated with the report.  

Field Encoding

Because HTTP headers are generally restricted to a subset of the US-ASCII charset, it may sometimes be necessary to encode the data. There is a special header, dx-header-encoding, that can have a value of base64. If set to this value, the field indicates that the values of all other header fields (i.e., those prefixed with dx-) have been base64 encoded. Encoding is commonly used to ensure proper handling of names that include letters with diacritical marks (e.g., names of tiers, facilities, contacts, etc.).

When this header is set the Data Interchange will attempt to base64 decode all dx- prefixed headers before forwarding them along with the payload to consumers. 

Complete Header Documentation

Below are definitions and examples for all required and recommend headers that can be sent to the Data Interchange. As noted elsewhere, Telemetry Providers can define additional, custom headers (using the dx-ext- prefix) which the Data Interchange will pass through to Telemetry Consumers.

Name	Description
ce-id string	The unique identifier for this data report. Example: 831-002::2020-09-18T12:01:38.376Z
ce-specversion string	The CloudEvents specification version. Example: 1.0 (this is the only supported value at present)
ce-type string	The type or classification of the transmitted data report. Example: org.nhgh.varo.report.v1
ce-source string($uri)	The source of the event. The value of this field may be any valid URI. Example: /widget-maker/telemetry/v1; https://telemetry.widget-maker.org/v1
dx-token string	An access token, provided by the Data Interchange, that permits publication of data to the Interchange. Example: 675F928zkT993xjfT1ZL0Aprn5
dx-owner string($uri)	URI of the Data Owner, to which the data transmission should be routed. Example: https://health.gov.ng
ce-time string($date-time)	The rfc3339 formatted time of the event. Example: 1985-04-12T23:20:50.5232Z
ce-dataschema *string($uri)	A URL that refferences the schema of the event payload. Example: https://wwww.schemas.com/myschema.json
dx-tdl-manufacturer string	Temperature data logger manufacturer name. Example: Berlinger
dx-tdl-model string	Temperature data logger model. Example: FridgeTag
dx-tdl-serial string	Temperature data logger serial. Example: 20859898785985
dx-fridge-manufacturer string	Fridge manufacturer name. Example: Dometic
dx-fridge-model string	Fridge model. Example: TCW40
dx-fridge-assigned-id string	Fridge assigned id or serial number. Example: 0824980808897
dx-country string	Country code in Alpha-2 format. Example: NG
dx-facility-name string	Name for a facility. Example: Bauchi Primary Health Care
dx-location-accuracy integer($int32)	Accuracy in meters. Example: 50
dx-location-latitude number($double)	Latitude of fridge location. Example: 11.485
dx-location-longitude number($double)	Longitude of fridge location. Example: 17.921
dx-tier0 string	Top most administrative region name, typically a country. Example: South Africa
dx-tier1 string	Name of administrative subdivision region 0, such as a state or province. Example: Gauteng
dx-tier2 string	Name of administrative subdivision region 1, such as a county, LGA, or municipality. Example: Sedibeng
dx-facility-contact-name string	Name of the facility contact. Example: Wedge Biggs
dx-facility-contact-phone string	Phone number of the facility contact. Example: 1982809300808

Special considerations for Telemetry Consumers

Telemetry Consumers receive data from the Data Interchange via Kafka, not HTTP. When forwarding messages to Telemetry Consumers, the Data Interchange first converts the HTTP headers (as defined above) to Kafka headers, following the Kafka binary content mode specification. This means all HTTP headers that begin with ce- prefix will be renamed to have a ce_ prefix in Kafka headers (i.e., the dash becomes an underscore). Headers beginning with the dx- prefix will not be renamed as they pass through the Data Interchange.

All other characteristics and values of metadata Headers remain unmodified by the Data Interchange.