NAV

Data Collector API

The Data Collector Service is a web service used to ingest data into the HealtheIntent platform.

Entity Data (Uploading)

Definitions

Entity

An entity is the smallest complete unit of data stored in the Cerner Cloud. Entities have the following elements, defined below:

Entity Type

The data type definition for the entity. Entity types are case-sensitive.

An entity type consists of one or more concatenated parts formatted as:

/{part-name}:{part-type}

Parts should generally be hierarchically arranged and become more specific in nature from left to right. The supported {part-type} values are int64, string, and uuid. The {part-name} cannot be blank and may contain only US-ASCII alphanumeric characters (a-z, A-Z, and 0-9) except for the following nonalphanumeric characters: _ (underscore), - (hyphen), and . (period). No limit is enforced for the number of parts comprising an entity type or for the length of individual part names, but to maximize compatibility with downstream data delivery and storage processes, moderation is encouraged. A fairly reasonable upper bound guideline for entity type size is probably about eight parts, or 120 total characters.

For example, an entity type might look something like:

/patient-id:uuid/order-type:string/order-time:int64

Entity Key

A unique identifier for the entity data. Entity keys are case-sensitive. The entity key must comply with the entity’s entity type definition, supplying a valid value for each part of the entity type. More specifically, part values must adhere to the following type requirements:

No limit is enforced for the length of entity keys or for individual string parts, but to maximize compatibility with downstream data delivery and storage processes, moderation is encouraged. A fairly reasonable upper bound guideline for entity key size is probably about 256 total characters.

For example, an example entity key for the /patient-id:uuid/order-type:string/order-time:int64 entity type example above might look something like:

/patient-id:b5f13e30-f5e7-4e99-9068-70d0c39bbbfa/order-type:Vitamin-C,daily/order-time:1300

The Cerner system account used when authenticating is assumed and is automatically prefixed by the Data Collector Service as an additional /source:string entity type part to uploaded entity keys. However, a different parent /source:string value can be provided for uploaded entities if the system authenticated is configured to serve as an authorized proxy for the data source.

Version

A numeric version for the entity data. The value must be between 0 and 263-1. The Data Collector Service will generate a version value if one is not specified for an entity. The generated value is the number of elapsed milliseconds since 00:00:00 (midnight) on January 1, 1970 Coordinated Universal Time (UTC), excluding leap seconds.

Operation

The type of data operation that the entity represents. The Data Collector Service supports the following operation values:

The differentiation between DELETE and PURGE operations affords downstream data delivery processes the option of conditionally excluding PURGE operations from real-time processing to ensure acceptable performance for the other operation types, which represent more recent events requiring lower processing latency.

Value

The data payload bytes representing the entity. The value data format is user-defined. Commonly used formats include Apache Avro, Google Protocol Buffers, JSON, CSV, and PDF, for example. The data format should be uniform for all entities having the same entity type, as the entity type is expected to be used during downstream processing to determine the data format. While data format flexibility for an entity type can be achieved by including format information in the entity key, that approach is generally discouraged.

The value bytes do not need to have data compression applied, as downstream processing will apply appropriate compression automatically for both transmission and storage, and the HTTP request body can be compressed in its entirety. No limit is enforced for the value size. However, very large values (ranging from multi-MB to multi-GB) may be incompatible with certain downstream processing systems and may need to be conditionally avoided.

For DELETE and PURGE operations, the value is typically empty. It is also acceptable for a WRITE operation to have no value.

Encryption

The value can be encrypted. Currently, only PGP decryption is supported. The value must be compatible with the OpenPGP Message Format defined in RFC-4880, and should be compressed both to save space and to make the encryption more secure.

The collector service’s public key manages different aspects of encryption, such as which symmetric cipher and compression algorithms are used. It is recommended to allow the preferences on the key to be used during encryption and to not override them. It is also recommended to not use ASCII armor conversion as the resulting file size can be approximately 40% larger than the original binary output (the default option for GPG).

See the [PGP Encryption Public Keys] section of this page for the PGP encryption public keys.

Metadata

The metadata bytes represent supplementary information about the entity. The metadata format is user-defined in the same manner as described for entity value above, and data compression is similarly unnecessary. No limit is enforced for the metadata size. However, large values (multi-MB and larger) may be incompatible with certain downstream processing systems and may need to be conditionally avoided. Entity metadata is typically very small. A reasonable upper bound guideline for metadata size is probably about 8 KB. Metadata is optional and does not need to be provided. If provided, it should not be encrypted, as encryption is only supported for the value.

Request Details

To upload entity data to the Data Collector Service, send a POST request in the following format:

POST https://api.data-collector.cernercentral.com/entity/{entity-name}

Path Parameters

Parameter Value Description Optional?
entity-name A short string, for example, orders A simple and descriptive name for the data type being uploaded, typically used for routing purposes by downstream data delivery processes. The entity name should correspond closely to the entity type. However, no relationship between the entity name and entity type is established or enforced by the Data Collector Service, as both the entity name and entity type are simply attached as opaque metadata to the entity. Generally, nonalphanumeric characters should be avoided. A reasonable upper bound guideline for entity name length is probably about 32 characters. It is valid to upload more than one entity in a single POST request. While each entity in the POST request may have a different entity type, because the entity name is a URL path segment, it must remain the same throughout. Consequently, separate POSTs would be necessary if uploading data of multiple entity types that need to be associated with different entity names. If an entity name is not provided, it does not matter whether the request URL ends with a / character. Yes

Query Parameters

Parameter Value Description Optional?
notify false A query parameter that can be added to the request URL to disable generating notifications for the uploaded entities during downstream real-time data delivery, with the general expectation that downstream batch processing will be used to process the uploaded data more efficiently, therefore ensuring acceptably low latency for other uploaded entities that represent more recent events. This parameter is commonly used when uploading a substantial amount of historical data, such as the initial onboarding of a new data source or when reuploading previously uploaded data to correct raw data content issues. If this parameter is not specified, data delivery processes have their own internal configuration settings that will control whether notifications are generated. The only supported value is false. Any other value will be ignored, reverting to the previously mentioned default behavior. The parameter name is case-sensitive, and the value is case-insensitive. Yes

HTTP Headers

The request can contain any of the following HTTP headers.

Header Value Description Optional?
Content-Type multipart/mixed; boundary={boundary}; protocol={protocol} Indicates that the request is a MIME multipart message according to RFC 2045 and RFC 2046. The boundary value must not occur in the data of any of the parts. Programmatically generating a random UUID is usually how that is ensured. The protocol parameter is optional and is used to indicate that the entities are encrypted. Only encrypted entity payloads are supported. The MIME headers or metadata should remain unencrypted. Currently the only supported value is “pgp-encrypted” (no quotes). No
Accept application/json Indicates that the response is a JSON object. No
clientVersion A software version string, for example, python-1.0.2 Indicates the version of the client library being used. Each client library or application should take reasonable steps to attempt to provide a globally unique client version value, for example by attaching a short descriptive prefix to the version. Yes
Content-Encoding gzip Indicates that the request body is compressed using the gzip encoding scheme according to the RFC 1952 standard. This header is recommended, especially for large requests. For PGP-encrypted uploads, the payload for each entity should be compressed before encryption, as described in section 2.3 of the RFC-4880 standard. Compression is controlled using the collector service’s public key. If the payloads are properly compressed, the upload does not need to be compressed again. Yes
Content-Length An integer, for example, 67832 The size of the request body in bytes. If the request is compressed, this is the post-compression size. Yes
Accept-Encoding gzip Indicates that the response body should be compressed using the gzip encoding scheme. Providing this header is not necessary or recommended because the response body is only approximately 15 to 20 bytes. Yes
Transfer-Encoding chunked Indicates that the request data is sent in chunks, instead of providing the Content-Length header, according to the RFC 2616 standard. If a Content-Encoding of gzip is also being used, each chunk would be individually compressed. This header is recommended, especially for large requests. A reasonable maximum chunk size might range from about 16 KB to 64 KB. Yes
Authorization OAuth followed by a comma-delimited list of key=“value” pairs with the prefix oauth_, for example: OAuth oauth_consumer_key=“…”, oauth_nonce=“…”, oauth_signature=“…”, oauth_signature_method=“…”, oauth_timestamp=“…, oauth_token=”…“, oauth_version=”…“ An authorization header generated from a signed OAuth access token. The OAuth access token must be obtained from a Cerner OAuth Service using a valid Cerner system account ID and secret. The specific details for making that request are beyond the scope of this documentation. No

Request Body

The POST request can contain one or more entities. Each entity must reside in a separate MIME part. The general structure of the request body looks like:

    --{boundary}
    {header-name}: {header-value}
    {header-name}: {header-value}
    ...

    {value-bytes}
    --{boundary}
    {header-name}: {header-value}<br>
    {header-name}: {header-value}<br>
    ...

    {value-bytes}
    --{boundary}--

Note that a blank line is required between the MIME part headers and the part body. Each line in the request body terminated by a carriage return followed by a line feed pair of characters, for example, 0x0D 0x0A, escaped as \r\n in most programming languages.

The supported headers are documented below.

MIME Part Headers

Each MIME part must start with a collection of MIME part headers describing the entity contained in the part.

Header Value Description Required?
Entity-Type An entity type, for example, /patient:int64/order:int64 The data type for the entity, as defined above. This header value is case-sensitive. Yes
Entity-Key An entity key, for example, /patient:975/order:531 A unique identifier for the entity data, as defined above. This header value is case-sensitive. Yes
Value-Size An integer, for example, 123777 Indicates the entity value size in bytes as a hint to the Data Collector Service. The value must be between 0 and 263-1. If not provided the Data Collector Service will dynamically determine the value size as it reads the request. No
Operation WRITE, DELETE, or PURGE Indicates the type of data operation that the entity represents. This header value is case-insensitive. If not provided the default value is WRITE. No
Version An integer, for example, 67832 The version of the entity data. The value must be between 0 and 263-1. If not provided the default is the number of elapsed milliseconds since 00:00:00 (midnight) on January 1, 1970 UTC, excluding leap seconds. No
Metadata A Base64 string, for example, QSB0aWdlci4= The entity metadata bytes, in Base64-encoded form according to the RFC 2045 standard. The header value can be folded across multiple lines according to the RFC 2822 standard. If not provided, the entity will be created without metadata. No

Two additional MIME part header values, "Content-Type: application/octet-stream” and “Content-Transfer-Encoding: binary”, are implicitly assumed and do not need to be supplied.

The header names are case-insensitive. Each header can be provided a maximum of one time in each part.

MIME Part Headers

Following the part headers, the body of the MIME part is the payload of entity value bytes. The payload can be empty if the entity has no value, for example for a DELETE operation.

Response Details

The service will return an HTTP response status code according to the RFC 7231 standard.

Status Type Description
201 Item count The upload of the entire stream of data was successful.
400 N/A OAuth credentials were not presented, or the request data did not match the expected format. Possible causes include an invalid entity key or version value, a missing required MIME part header, or the payload was malformed and unable to be decrypted (if protocol parameter is specified).
401 N/A Validation of the provided signed OAuth access token failed.
403 N/A A system attempted to upload data for a data source for which it had not been authorized to serve as a proxy system.
408 N/A A timeout occurred while reading data from the upload stream.
500 N/A An internal server error occurred.
503 N/A The service is temporarily unavailable.

For any kind of failure to upload entity data to the Data Collector Service, it is safe to assume that the upload can be retried, as all internal operations are idempotent.

HTTP Headers

The response can contain the HTTP headers below.

Header Value Description
WWW-Authenticate Bearer realm=“…”, error=“…”, error_description=“…” If present, contains information indicating why the request failed according to the RFC 7235 standard. A common reason is attempting to use an expired OAuth access token. OAuth access tokens have a limited lifetime and need to be refreshed occasionally.
Content-Type application/json If present, indicates that the response body is a JSON object. This header will always be set if the request was successful and a status code of 201 was returned.
Content-Encoding gzip If present, indicates that the response body is compressed using the gzip encoding scheme. This header will only be set if the “Accept-Encoding: gzip” request header was set.

Response Body

If the request is successful (indicated by the 201 HTTP status code), the response body is a JSON object containing the count of items in the request.

{"itemCount":{item-count}}

For example:

{"itemCount":99}

Otherwise, the contents of the response body are undefined.

PGP Encryption Public Keys

The PGP encryption public keys for each region.

Prod-US

URL: https://api.data-collector.cernercentral.com/

—–BEGIN PGP PUBLIC KEY BLOCK—– Version: GnuPG v1

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 3/ViWrM3GBU62CWzJQ== =xxtH —–END PGP PUBLIC KEY BLOCK—–

Prod-UK

URL: https://data-collector-api.eu.cernercentral.com

—–BEGIN PGP PUBLIC KEY BLOCK—– Version: GnuPG v1

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 9jX/LCxdE39KUyB+xg== =09Ud —–END PGP PUBLIC KEY BLOCK—–

Note: This page includes links to external resources. These resources are provided for reference purposes and should be used with caution. Contact your Oracle Cerner support team for more information about third-party content.