Data Syndication API v1
Data Syndication facilitates the bulk delivery of HealtheIntent data. It provides direct, low-level, asynchronous access to the information that HealtheIntent solutions create, curate, and operate against. This API is used mainly to populate a data warehouse or other third-party data store for research, reporting, or analytical activities.
Release Considerations: The Data Syndication endpoints are available at both of the URLs below; however, as of December 5, 2018, the /syndication
path is deprecated and should not be used. Any existing scripts that use /syndication
should be updated to use /data-syndication
. This note will be removed or updated when the /syndication
path no longer is supported.
https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/{resource}
https://{tenantMnemonic}.api.{region}.healtheintent.com/syndication/v1/{resource}
Terminology
Term | Definition |
---|---|
feed types | The types of available data sets, for example, Longitudinal Record. |
feeds | The set of data that you want to receive on a schedule, for example, Longitudinal Record for population ABC. |
bundles | The output of a feed, for example, Changes to the Longitudinal Record for population ABC between 2018-04-01 and 2018-04-02. |
channel types | The ways you can have bundles delivered, for example, DOWNLOAD . |
channels | Specifies that you want to receive a feed’s bundles using a particular channel type and provides any necessary configuration for the channel type. For example, a channel could specify that you want to receive your Longitudinal Record for Population ABC feed using the DOWNLOAD channel type. |
deliveries | The status of delivering a particular bundle using a particular channel. For example, you would use the Deliveries endpoint to determine whether the archive file for changes to the Longitudinal Record for population ABC between 2018-04-01 and 2018-04-02 bundle is available for you to download. |
To help understand these concepts, consider an analogy to the delivery of physical products. Suppose you want to have a newspaper, the Cerner Post, delivered to you by the postal service every day, but that you are only interested in the classifieds section. In this example:
- The feed type is the Cerner Post.
- The feed specifies that you want to receive only the classifieds section, and that you want the newspaper every day.
- Every day a bundle is generated containing the classifieds section for that day.
- The channel type is the postal service.
- The delivery channel contains everything the postal service needs to deliver to you, for example, your name and address.
- Every day a delivery happens when the postal service delivers the bundle to your mailbox.
Feed Types
The following feed types are currently available:
Name | Mnemonic |
---|---|
Analytics Custom EDW | analytics-custom-edw |
Challenges Analytics | challenges-analytics |
Consumer Engagement Analytics | ce-analytics |
Consumer Onboarding Analytics | cons-onboarding-analytics |
Dimensions EDW | dimensions-edw |
Health Tracker Analytics | health-tracker-analytics |
Hierarchical Condition Categories Analytics | hcc-analytics |
Learning Modules Analytics | lm-analytics |
Longitudinal Record EDW | long-record-edw |
Millennium ODS | millennium-ods |
Outcomes Analytics | outcomes-analytics |
Personnel Analytics | personnel-analytics |
Revenue Cycle Analytics | Each file in the Revenue Cycle Analytics bundle has its own feed type. See the linked overview of the Revenue Cycle Analytics feed types for more information about its feed type mnemonics. |
Risk Assessment EDW | risk-assessment-edw |
Wellness Analytics | wellness-analytics |
Wellness Campaign Analytics | wellness-campaign-analytics |
Channel Types
The channel types below are currently available. Deliveries have associated metadata, the schema of which depends on the type of the channel the delivery belongs to.
Name | Description | Delivery Metadata Schema |
---|---|---|
DOWNLOAD |
Channels the data into archive files that can be downloaded using this API. | Download Channel Type Delivery Metadata |
S3 |
Channels the data into a specified Amazon S3 bucket. | S3 Channel Type Delivery Metadata |
Download Channel Type Archive Structure
Each delivery contains data that corresponds to one or more entities, for example, allergies or claims. Each entity may have one or more parts. The data can be laid out with the parts combined or separate in deliveries for a DOWNLOAD
channel.
Parts Combined
This is the default format. Currently, any newly created channels will use this format.
When this format is used, all entity parts are combined into a single file in the delivery archive. For example, if the bundle has two entities (entity1
and entity2
) and each entity has two parts (part1
and part2
), the part files are combined and the resulting delivery archive file has the following contents after it is unarchived:
|-- entity1
|
|-- entity2
In the above example, entity1
and entity2
are both files that contain the contents of their respective part1
and part2
parts concatenated together. Note that the files do not have file extensions. Depending on the feed type, the format of the data in the files may be different. See the documentation for each feed type for more information.
Parts Separate
When this format is used, all entity parts remain separate in the delivery archive. For example, if the bundle has two entities (entity1
and entity2
) and each entity has two parts (part1
and part2
), the part files remain separate and the resulting delivery archive file has the following contents after it is unarchived:
|-- entity1
| |-- part1
| |-- part2
|
|-- entity2
| |-- part1
| |-- part2
In the above example, entity1
and entity2
are both directories that contain their respective part1
and part2
part files. The part files may or may not have file extensions. Depending on the feed type, the format of the data in the files may be different. See the documentation for each feed type for more information.
S3 Channel Type Delivery Structure
For S3 channels, the delivery data is written directly to the bucket and not packaged in an archive file. For example, if the bundle has two entities (entity1
and entity2
) and each entity has two parts (part1
and part2
), the data written to the bucket has the following structure:
|-- entity1
| |-- part1
| |-- part2
|
|-- entity2
| |-- part1
| |-- part2
Data Retention
Download Channel Type
Due to the size of archive files, it is not practical for Cerner to retain them indefinitely.
Each archive file produced using the DOWNLOAD
channel type is available for three weeks from the time when the delivery is completed, as indicated by the deliveredAt
timestamp in the corresponding delivery object.
After three weeks, Cerner deletes the file and the delivery’s status
is changed to PURGE_IN_PROGRESS
or PURGED
to indicate that the file can no longer be downloaded.
If a system attempts to retrieve the delivery after that time, a 404 HTTP status code (Not Found) is sent.
S3 Channel Type
Cerner does not manage files after they are delivered using the S3
channel type to client-owned Amazon S3 buckets.
If you use the S3 channel type, you are responsible for defining your data retention policy for the delivered files.
Getting Started
Requesting a Feed
Before you can use the Data Syndication API, you must have at least one feed and at least one channel for that feed. Contact your HealtheIntent engagement leader or log a service record (SR) in eService to the solution related to the feed type to request a new feed for a particular feed type.
You can use the /channels
endpoint to create new channels for existing feeds. Note that when a bundle is produced, deliveries are performed using only channels that are active at the time. This means that when a new channel is created, deliveries are not retroactively performed using that channel for bundles that were produced before the channel’s creation.
See Configure Data Syndication Feeds and Channels for more information.
Authorization
Only authorized system accounts can access endpoints. Contact your HealtheIntent engagement leader to request that authorization be granted or authorize the system account for the authorization policy scopes in HealtheIntent Console below. See Configure Data Syndication Feeds and Channels and Viewing, Adding, and Editing API Authorizations Using HealtheIntent Console for more information.
Authorization Policy Scope | Endpoints | Description |
---|---|---|
data-syndication:feeds | The system account must be authorized for overall feed administration. | |
data-syndication:feeds/{feed_id} | The system account must be authorized to access the specified feed or the feed to which the specified bundle belongs. | |
data-syndication:channels | The system account must be authorized for overall channel administration. | |
data-syndication:channels/{channel_id} | The system account must be authorized to access the specified channel or the channel to which the specified delivery belongs. |
Looking Up Feeds and Deliveries
You can use the /feeds/{feedId}/bundles
endpoint to view all the bundles that have been produced for a given feed or the /channels/{channelId}/deliveries
endpoint to see all the deliveries that have occurred for a given channel.
Downloading the Latest Deliveries
Example Automated Downloading Script
require 'fileutils'
require 'httparty'
# Replace cernerdemo with your tenant mnemonic.
BASE_URL = 'https://cernerdemo.api.healtheintent.com/data-syndication/v1'
# Replace this with the ID of the channel for your feed.
CHANNEL_ID = '5fcdb1e1-3b82-4272-acfb-1242d456e4f4'
# Insert a valid Authorization header here.
AUTH_HEADER = '...'
# This script divides each download into parts. This constant sets the maximum number of bytes in each part.
PART_SIZE = 1024 * 1024 * 600
def download_new_deliveries
loop do
# Get the timestamp of the last downloaded bundle from persistence.
last_released_at = File.read('checkpoint.txt') if File.exist?('checkpoint.txt')
query_params = { orderBy: 'bundleReleasedAt', offset: 0, limit: 1 }
query_params.merge!(bundleReleasedAfter: last_released_at) unless last_released_at.nil?
headers = { 'Authorization' => AUTH_HEADER, 'Accept' => 'application/json' }
url = "#{BASE_URL}/channels/#{CHANNEL_ID}/deliveries"
response = HTTParty.get(url, headers: headers, query: query_params)
unless response.code == 200
raise StandardError, "Unable to retrieve latest deliveries. Response code = #{response.code}. Response body:\n#{response.body}"
end
delivery = response.parsed_response['items'].first
if delivery.nil?
puts 'No more bundles are available for download at this time.'
break
end
if delivery['status'] == 'IN_PROGRESS'
puts 'The download for the next bundle is still being prepared. Try again later.'
break
end
if delivery['status'] != 'DELIVERED'
raise StandardError, "The delivery with ID #{delivery['id']} failed. Contact your HealtheIntent engagement leader for support."
end
released_at = delivery['bundle']['releasedAt']
filename = "#{released_at.delete('-:.')}#{get_file_extension(delivery['metadata']['archiveFormat'])}"
puts "Downloading bundle released at #{released_at}."
download_file(delivery['id'], filename)
File.write('checkpoint.txt', delivery['bundle']['releasedAt'])
end
end
def get_file_extension(archiveFormat)
if archiveFormat == 'TAR_GZ'
'.tar.gz'
elsif archiveFormat == 'TAR_CONTAINING_LZ4'
'.tar'
end
end
def get_download_size(id)
headers = {
'Authorization' => AUTH_HEADER,
'Accept' => 'application/octet-stream'
}
url = "#{BASE_URL}/downloads/#{id}"
response = HTTParty.head(url, headers: headers)
content_length = response.headers['Content-Length']
unless response.code == 200 && content_length
raise StandardError, "Unable to retrieve file size. Response code = #{response.code}. Response headers:\n#{response.headers}\nResponse body:\n#{response.body}"
end
content_length.to_i
end
def download_range(id, range, part_filename, retries = 3)
headers = {
'Authorization' => AUTH_HEADER,
'Accept' => 'application/octet-stream',
'Range' => "bytes=#{range}"
}
url = "#{BASE_URL}/downloads/#{id}"
response = HTTParty.get(url, headers: headers)
if response.code != 206
raise StandardError, "Unexpected response code when attempting to download range. Response code = #{response.code}. Response body:\n#{response.body}"
end
File.binwrite(part_filename, response.body)
rescue StandardError => ex
puts "Error: #{ex}"
if retries > 0
puts 'Retrying...'
sleep 5
download_range(id, range, part_filename, retries - 1)
else
raise StandardError, 'Unable to download range. Try again later.'
end
end
def download_file(id, filename)
length = get_download_size(id)
puts "File size: #{length} bytes"
dir = "#{filename}.parts"
FileUtils.mkdir_p(dir)
range_start = 0
part_filenames = []
while range_start < length
range_end = [range_start + PART_SIZE, length].min - 1
range = "#{range_start}-#{range_end}"
part_filename = File.join(dir, "#{range_start}-#{range_end}")
part_filenames << part_filename
if File.exist?(part_filename) && File.size(part_filename) == (range_end - range_start + 1)
puts "Already downloaded range #{range}."
else
puts "Downloading range #{range}."
download_range(id, range, part_filename)
end
range_start += PART_SIZE
end
puts "All ranges downloaded. Combining ranges into final file: #{filename}"
file = File.open(filename, 'wb')
part_filenames.each do |part_filename|
part_file = File.open(part_filename, 'rb')
FileUtils.copy_stream(part_file, file)
part_file.close
end
file.close
# Delete the temporary files containing the separate parts.
FileUtils.rm_r(dir)
end
download_new_deliveries
If you have a channel that uses the DOWNLOAD
channel type, then you likely want to set up an automated process that regularly scans for new deliveries and downloads them.
Complete the following steps to automatically download the delivered bundles:
- Determine your channel ID. You can use the
/feeds
endpoint to determine the feed ID, then use the/channels
endpoint to determine the channel with that feed ID and a channel type mnemonic ofDOWNLOAD
. - Use the
/channels/{channelId}/deliveries
endpoint to determine the list of available deliveries.- You will use the delivery’s
id
in the next step to perform the download. - Look for deliveries whose
status
field isDELIVERED
, indicating they are available to download now. - Each delivery includes a
bundle.releasedAt
field that indicates the date and time when the bundle was produced. You can order and filter the response by specifying thebundleReleasedAt
andbundleReleasedAfter
query parameters. You can use those parameters to download all the deliveries up to a certain date and time, then save thebundle.releasedAt
value so you can use the value in thebundleReleasedAfter
query parameter next time and download only the new deliveries.
- You will use the delivery’s
- Use the
/downloads/{deliveryId}
endpoint to download the data.- The format of the downloaded file is determined by the channel configuration’s
archiveFormat
attribute. If it is not set or is set toTAR_GZ
, the file is a gzip-compressed tar archive file and should have a file extension of.tar.gz
. If it is set toTAR_CONTAINING_LZ4
, the downloaded file is a tar archive containing LZ4-compressed files and should have a file extension of.tar
. If it is set toTAR_CONTAINING_GZ
, the downloaded file is a tar archive containing gzip-compressed files and should have a file extension of.tar
. While a.tar.gz
file can be extracted and decompressed all at once, the.tar
first needs to be extracted then the files in it can be decompressed using LZ4 or gzip. The archive format used for a delivery also is included in the delivery’smetadata
as thearchiveFormat
attribute. Note that a channel’s configuration can be updated to change the format of future deliveries. The format in a delivery’smetadata
should be used to determine how to handle the file, because that reflects the actual format of the file.
- The format of the downloaded file is determined by the channel configuration’s
Note: The Data Syndication service does not guarantee the order in which deliveries are performed. When incremental data is downloaded, deliveries must be consumed in order of the oldest to the most recent bundleReleasedAt
value, regardless of the time of delivery. This means that a given incremental delivery cannot be consumed until all incremental deliveries with older bundleReleasedAt
values in the same feed are consumed.
The example automated downloading script demonstrates how to download all the deliveries of a given channel in order. The script can be run automatically on a schedule to ensure that you retrieve new deliveries as they become available. You will likely want to include the following features of the script in your code:
- The Range header is used to download files in chunks of a specific size, rather than downloading the entire file at once. The script reassembles the chunks into the full file once they have all been downloaded.
- If the downloading of a chunk fails, the script retries a fixed number of times. If it still fails, the script resumes the download at that chunk the next time you run it.
- Deliveries are processed in order, and processing stops if any deliveries in a status of FAILED or IN_PROGRESS are encountered. This is because while you can download the files out of order, you may need to import the data the files contain into your system in the correct order to ensure that changes from earlier incremental bundles do not overwrite changes in later incremental bundles.
- The
archiveFormat
attribute of the delivery’smetadata
should be used to identify the format of the file and determine the correct file extension.
Feeds
Retrieve a List of Feeds
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name'
Example Response
{
"items": [
{
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
"name": "Primary Population Records",
"status": "ACTIVE",
"scope": {
"population": {
"id": "5bdb91f7-c779-450d-8309-e14cd7672589"
}
},
"feedType": {
"mnemonic": "long-record"
},
"createdAt": "2018-04-06T21:17:55.423Z",
"updatedAt": "2018-04-06T21:17:55.423Z"
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20",
"lastLink": "https://cernerdemo.api.devhealtheintent.com/data-syndication/v1/feeds?feedTypeMnemonic=long-record&orderBy=name&offset=0&limit=20&",
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds
Retrieves a list of feeds matching the query.
Query Parameters
Parameter | Default | Required | Description | Accepted Values |
---|---|---|---|---|
feedTypeMnemonic | N/A | No | Filters results to the given type of feed. | |
status | N/A | No | Filters results by feed status. | ACTIVE, INACTIVE |
orderBy | name | No | Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). | name, -name |
offset | 0 | No | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | |
limit | 20 | No | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. |
Responses
Status | Type | Description |
---|---|---|
200 | Feed List Response | Collection of Feed objects |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
Retrieve a Single Feed
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af'
Example Response
{
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af",
"name": "Primary Population Records",
"status": "ACTIVE",
"scope": {
"population": {
"id": "5bdb91f7-c779-450d-8309-e14cd7672589"
}
},
"feedType": {
"mnemonic": "long-record"
},
"createdAt": "2018-04-06T21:17:55.423Z",
"updatedAt": "2018-04-06T21:17:55.423Z"
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}
Retrieves a single feed.
Path Parameters
Field | Description |
---|---|
feedId | The ID of the feed |
Responses
Status | Type | Description |
---|---|---|
200 | Feed | Single Feed object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Bundles
Retrieve a List of Bundles
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt'
Example Response
{
"items": [
{
"id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"releasedAt": "2018-04-11T18:37:25.063Z",
"metadata": {}
},
{
"id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"releasedAt": "2018-04-11T20:21:12.461Z",
"metadata": {}
}
],
"totalResults": 2,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/feeds/0f1c7802-6255-46f0-b898-6e5b851bc0af/bundles?releasedAfter=2018-02-03T01:00:00.000Z&orderBy=releasedAt&offset=0&limit=20",
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/feeds/{feedId}/bundles
Retrieves a list of bundles matching the query.
Path Parameters
Field | Description |
---|---|
feedId | The ID of the feed |
Query Parameters
Parameter | Default | Required | Description | Accepted Values |
---|---|---|---|---|
releasedAfter | N/A | No | If provided, only bundles released after the provided date and time are returned. The expected format is YYYY-MM-DDThh:mm:ssZ with optional milliseconds. | |
orderBy | -releasedAt | No | Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). | releasedAt, -releasedAt |
offset | 0 | No | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | |
limit | 20 | No | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. |
Responses
Status | Type | Description |
---|---|---|
200 | Bundle List Response | Collection of Bundle objects |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
Retrieve a Single Bundle
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/bundles/5ebcac9e-1f1a-4181-8c0f-4300a3af83d9'
Example Response
{
"id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"releasedAt": "2018-04-11T18:37:25.063Z",
"metadata": {}
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/bundles/{bundleId}
Retrieves a single bundle.
Path Parameters
Field | Description |
---|---|
bundleId | The ID of the bundle |
Responses
Status | Type | Description |
---|---|---|
200 | Bundle | Single Bundle object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Channels
Create a Channel
Example Request
require 'httparty'
require 'json'
HTTParty.post(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels',
headers: {
'Accept' => 'application/json',
'Content-Type' => 'application/json'
'Authorization' => '<auth_header>'
},
body: {
name: 'Download Primary Population Records',
feed: {
id: '0f1c7802-6255-46f0-b898-6e5b851bc0af'
},
downloadConfig: {
archiveFormat: 'TAR_GZ'
}
}.to_json
)
curl -X POST -H 'Authorization: {auth_header}' -H 'Accept: application/json' -H 'Content-Type: application/json'
-d '{"name": "Download Primary Population Records", "feed": {"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"}, "downloadConfig": {"archiveFormat": "TAR_GZ"}}'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels'
Example Response
{
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
"name": "Download Primary Population Records",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"type": "DOWNLOAD",
"config": {
"archiveFormat": "TAR_GZ"
},
"status": "ACTIVE",
"createdAt": "2018-04-11T17:02:40.936Z",
"updatedAt": "2018-04-11T17:02:40.936Z"
}
POST https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels
Creates a new channel.
Note that in the request body, the following config
attributes can be used: downloadConfig
and s3Config
. These correspond to the different channel types that can be created. Only one config
attribute is in the response so that the response body schema is consistent between this endpoint and the Retrieve a Single Channel endpoint.
Choosing an Archive Format
When a DOWNLOAD
channel is created, an archive format must be provided. The main determining factor in this decision is the speed of delivery versus the resulting archive size and ease of consumption. See the following information about the size and ease of consumption of the file formats:
The TAR_GZ format produces archives in the regular .TAR.GZ format, which can be unarchived using tools included in most operating systems. This format produces the smallest resulting archive size, but deliveries with this format take the longest. This format is recommended for channels with delivery sizes usually less than a few hundred gigabytes.
The TAR_CONTAINING_GZ format produces tar archives that contain files individually compressed with gzip. First the archive must be unpacked, then each resulting file must be decompressed individually. This format produces archives comparable in size to the TAR_GZ format much faster, but the archives are more complex to consume due to the need to decompress each file individually. This format is recommended for only channels with delivery sizes regularly more than a few hundred gigabytes.
The TAR_CONTAINING_LZ4 format produces tar archives that contain files individually compressed with LZ4. As with TAR_CONTAINING_GZ, first the archive must be unpacked, then each resulting file must be decompressed individually. The difference is that the individual files are compressed in the LZ4 format, which is not supported as widely as the gzip format. This format produces larger archives than the TAR_GZ or TAR_CONTAINING_GZ format, but deliveries with this format are the fastest. Compared to TAR_GZ, deliveries with the TAR_CONTAINING_LZ4 format take about one sixth the amount of time, and the resulting archive file is about 1.5 times the size. This format is recommended for only channels with delivery sizes regularly more than a few hundred gigabytes. Before choosing this format, ensure that the LZ4 compression format is supported by the consuming processes.
Note that the relative speeds of the archive formats affect the time it takes to produce deliveries only after bundles are available; it does not affect the amount of time it takes to produce bundles.
S3 Channel Authorization
When an S3
channel is created, the response includes a roleArn
attribute. This is the ARN of the AWS role that Cerner will use to deliver data to the bucket provided in the request. For deliveries to be performed successfully, this role needs to be granted s3:PutObject
and s3:PutObjectAcl
permissions in the bucket’s policy.
The bucket policy statement that grants access should be similar to the following statement:
{
"Effect": "Allow",
"Principal": {
"AWS": "<role ARN>"
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::<bucket name>/<base bucket path>/*"
}
The above statement is the recommended way to grant permissions, but if a Condition
is preferred, it would be in the following format:
Note: If this Condition
is used, AWS flags the bucket as having public access.
{
"Effect": "Allow",
"Principal": "*",
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::<bucket name>/<base bucket path>/*",
"Condition": {
"ArnEquals": {
"aws:PrincipalArn": "<role ARN>"
}
}
}
Note: If the bucket is encrypted with a custom KMS key, a KMS key ARN should be provided in the request to create the channel, and the role ARN also needs to be granted kms:GenerateDataKey*
, kms:Encrypt
, and kms:Decrypt
permissions for the KMS key.
See the Provide Cross-Account Access to Objects in S3 Buckets page on the AWS website for more information about the strategy Data Syndication uses for cross-account S3 bucket access, which is referred to as resource-based policies and IAM policies in the AWS documentation.
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
body | body | postChannel | true | N/A | No description | - |
Responses
Status | Type | Description |
---|---|---|
200 | Channel | Single Channel object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Retrieve a List of Channels
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name'
Example Response
{
"items": [
{
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
"name": "Download Primary Population Records",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"type": "DOWNLOAD",
"config": {
"archiveFormat": "TAR_GZ"
},
"status": "ACTIVE",
"createdAt": "2018-04-11T17:02:40.936Z",
"updatedAt": "2018-04-11T17:02:40.936Z"
}
],
"totalResults": 1,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20&"
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels
Retrieves a list of channels matching the query.
Query Parameters
Parameter | Default | Required | Description | Accepted Values |
---|---|---|---|---|
feedId | N/A | No | Filters results to the given feed. | |
type | N/A | No | Filters results to the given channel type. | DOWNLOAD, S3 |
orderBy | name | No | Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). | name, -name |
offset | 0 | No | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | |
limit | 20 | No | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. |
Responses
Status | Type | Description |
---|---|---|
200 | Channel List Response | Collection of Channel objects |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
Retrieve a Single Channel
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4'
Example Response
{
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4",
"name": "Download Primary Population Records",
"feed": {
"id": "0f1c7802-6255-46f0-b898-6e5b851bc0af"
},
"type": "DOWNLOAD",
"config": {
"archiveFormat": "TAR_GZ"
},
"status": "ACTIVE",
"createdAt": "2018-04-11T17:02:40.936Z",
"updatedAt": "2018-04-11T17:02:40.936Z"
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}
Retrieves a single channel.
Path Parameters
Field | Description |
---|---|
channelId | The ID of the channel |
Responses
Status | Type | Description |
---|---|---|
200 | Channel | Single Channel object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Retrieve the Status of a Channel
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status'
Example Response
{
"status": "ACTIVE"
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/status
Retrieves the status of a channel.
Path Parameters
Field | Description |
---|---|
channelId | The ID of the channel. |
Responses
Status | Type | Description |
---|---|---|
200 | ChannelStatus | Channel status object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Modify the Status of a Channel
Example Request
require 'httparty'
require 'json'
HTTParty.put(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status',
headers: {
'Accept' => 'application/json',
'Content-Type' => 'application/json',
'Authorization' => '<auth_header>'
},
body: {
status: 'ACTIVE'
}.to_json
)
curl -X PUT -H 'Authorization: {auth_header}' -H 'Accept: application/json' -H 'Content-Type: application/json'
-d '{"status": "ACTIVE"}'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/status'
Example Response
{
"status": "ACTIVE"
}
PUT https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/status
Modifies the status of a channel.
Path Parameters
Field | Description |
---|---|
channelId | The ID of the channel. |
Parameters
Parameter | In | Type | Required | Default | Description | Accepted Values |
---|---|---|---|---|---|---|
body | body | ChannelStatus | true | N/A | No description | - |
Responses
Status | Type | Description |
---|---|---|
200 | ChannelStatus | Channel status object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Deliveries
Retrieve a List of Deliveries
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt'
Example Response
{
"items": [
{
"id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
"bundle": {
"id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
"releasedAt": "2018-04-11T18:37:25.063Z"
},
"channel": {
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
},
"status": "DELIVERED",
"deliveredAt": "2018-04-12T16:02:01.333Z",
"metadata": {
"bytesSize": 1073741824,
"archiveFormat": "TAR_GZ"
}
},
{
"id": "f9647569-aa13-42c2-81ad-a20b46be775c",
"bundle": {
"id": "8d75de0e-358b-434d-97fe-6f1ba3598098",
"releasedAt": "2018-04-11T20:21:12.461Z"
},
"channel": {
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
},
"status": "IN_PROGRESS"
}
],
"totalResults": 2,
"firstLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20",
"lastLink": "https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/channels/5fcdb1e1-3b82-4272-acfb-1242d456e4f4/deliveries?bundleReleasedAfter=2018-02-03T01:00:00.000Z&orderBy=bundleReleasedAt&offset=0&limit=20"
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/channels/{channelId}/deliveries
Retrieves a list of deliveries matching the query.
If the channel corresponds to the DOWNLOAD
channel type, this endpoint can be used to list available deliveries that you have not yet downloaded and processed into your application. If you store the releasedAt
time of the last delivery that was downloaded, it can be used as the bundleReleasedAfter
query parameter of this endpoint to list deliveries after this last downloaded bundle in time sequence order.
Note: The feed type for your channel may have certain processing order requirements that must be followed by API consumers to maintain data integrity. For example, feed types that produce bundles with incremental changes might require processing to strictly follow bundleReleasedAt order as new bundles may depend on previous bundles. See the documentation for your particular feed type for details.
Path Parameters
Field | Description |
---|---|
channelId | The ID of the channel |
Query Parameters
Parameter | Default | Required | Description | Accepted Values |
---|---|---|---|---|
bundleReleasedAfter | N/A | No | If provided, only deliveries for bundles released after the provided date and time are returned. The expected format is YYYY-MM-DDThh:mm:ssZ with optional milliseconds. | |
orderBy | -bundleReleasedAt | No | Orders results by a given value in ascending or descending alphabetic order. To specify descending, prefix the value with a hyphen (-). | bundleReleasedAt, -bundleReleasedAt |
offset | 0 | No | The number of results to skip from the beginning of the list of results (typically for the purpose of paging). The minimum offset is 0. There is no maximum offset. | |
limit | 20 | No | The maximum number of results to display per page. The minimum limit is 1. The maximum limit is 100. |
Responses
Status | Type | Description |
---|---|---|
200 | Delivery List Response | Collection of Delivery objects |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
Retrieve a Single Delivery
Example Request
require 'httparty'
HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
headers: {
'Accept' => 'application/json',
'Authorization' => '<auth_header>'
}
)
curl -X GET -H 'Authorization: {auth_header}' -H 'Accept: application/json'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/deliveries/5e8af1e6-1cdf-45f6-9d9a-3c314beac597'
Example Response
{
"id": "5e8af1e6-1cdf-45f6-9d9a-3c314beac597",
"bundle": {
"id": "5ebcac9e-1f1a-4181-8c0f-4300a3af83d9",
"releasedAt": "2018-04-11T18:37:25.063Z"
},
"channel": {
"id": "5fcdb1e1-3b82-4272-acfb-1242d456e4f4"
},
"status": "DELIVERED",
"deliveredAt": "2018-04-12T16:02:01.333Z",
"metadata": {
"bytesSize": 1073741824,
"archiveFormat": "TAR_GZ"
}
}
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/deliveries/{deliveryId}
Retrieves a single delivery.
Path Parameters
Field | Description |
---|---|
deliveryId | The ID of the delivery |
Responses
Status | Type | Description |
---|---|---|
200 | Delivery | Single Delivery object |
400 | Error | Bad request |
401 | Error | Unauthorized |
403 | Error | Forbidden |
404 | Error | Not Found |
Downloads
If you have a channel whose channel type mnemonic is DOWNLOAD
, then each delivery in that channel with a DELIVERED status is available for download.
Use the Deliveries endpoint to find what downloads are available to you; use this endpoint to download the content.
Note: Downloads are available for only three weeks. See the Data Retention section for more information.
Retrieve a Single Download
Example Request
require 'httparty'
response = HTTParty.get(
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597',
headers: {
'Authorization' => '<auth_header>',
'Accept' => 'application/octet-stream',
'Range' => 'bytes=0-104857599'
}
)
File.binwrite('bundle.tar.gz', response.body)
curl -X GET -H 'Authorization: {auth_header}' -H 'Range: bytes=0-104857599'
'https://cernerdemo.api.us-1.healtheintent.com/data-syndication/v1/downloads/5e8af1e6-1cdf-45f6-9d9a-3c314beac597' > bundle.tar.gz
GET https://{tenantMnemonic}.api.{region}.healtheintent.com/data-syndication/v1/downloads/{deliveryId}
Retrieves the archive file containing the data from the bundle.
Note: To ensure no data was lost due to a failed connection, check that the downloaded file’s size is correct.
If you requested a specific range using the Range
header, check that the size matches what you requested.
Otherwise, check that the size matches the Content-Length
response header.
Path Parameters
Field | Description |
---|---|
deliveryId | The ID of the delivery |
Range Header
If a file download times out due to its size, you may optionally include a Range
header to indicate that you only want to download a portion of the file. After downloading all portions of the file, you can concatenate the portions and decompress the combined file.
You can also use the Range
header in order to download multiple segments of the file in parallel.
To do this, you would start multiple threads or processes, each of which makes a request for a different byte range, then concatenate the portions after they have all been downloaded.
There are diminishing returns for increasing the number of concurrent requests; we suggest downloading files in segments of about 600MB and retrieving 5-10 segments at a time.
For more information about byte ranges, see Byte Ranges on the RFC 7233 page on the Internet Engineering Task Force (IETF) website.
The range header should take one of the following forms:
bytes=<start>-<end>
, where<start>
and<end>
are non-negative integers specifying an inclusive range of byte indexes.bytes=<start>-
, where<start>
is a non-negative integer specifying that you want to receive all bytes from that index to the end of the file.bytes=-<length>
, where<length>
is a non-negative integer specifying that you want to receive the last<length>
number of bytes in the file.
Although RFC 7233 defines a way to specify multiple ranges in a single request, the downloads endpoint does not currently support this.
See the download example request for an example of this header being set.
Data Syndication API Definitions
Bundle
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the bundle. |
feed | Feed Reference | Yes | The feed the bundle belongs to. |
releasedAt | dateTime | Yes | The date and time when the bundle was produced, in International Organization for Standardization (ISO) 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. This field implies the ordering of bundles in a feed. |
metadata | object | Yes | The metadata related to the bundle. The schema of this object varies and is determined by the feed type of the feed the bundle belongs to. |
Bundle List Response
Name | Type | Required | Description |
---|---|---|---|
items | [Bundle] | Yes | The list of bundles. |
totalResults | integer | Yes | The total number of results for the query. |
prevLink | string | No | The previous page of results. Absent on the first page of results. |
nextLink | string | No | The next page of results. Absent on the last page of results. |
firstLink | string | Yes | The first page of results. |
lastLink | string | Yes | The last page of results. |
Bundle Reference
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the bundle. |
releasedAt | dateTime | Yes | The date and time when the bundle was released, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
Channel
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the channel. |
name | string | Yes | The human-readable name for the channel. |
type | string | Yes | The channel type of which the channel is an instance. The following values are possible:
|
feed | Feed Reference | Yes | The feed the channel delivers. |
status | string | Yes | The lifecycle status of the channel. The following values are possible:
ACTIVE by consuming systems. |
config | Channel Configuration | Yes | The configuration of the channel. |
createdAt | dateTime | Yes | The date and time when the channel was created, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
updatedAt | dateTime | Yes | The date and time when the channel was last updated, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
Channel Configuration
The schema of this configuration object varies depending on the channel type. Each channel type can have a different set of configuration options.
Download Channel Type Configuration
Name | Type | Required | Description |
---|---|---|---|
archiveFormat | string | No | The format of the files that are downloaded through the channel. The default format is TAR_GZ . The following values are possible:
|
S3 Channel Type Configuration
Name | Type | Required | Description |
---|---|---|---|
bucketName | string | Yes | The name of the Amazon S3 bucket to which the channel delivers. |
baseBucketPath | string | No | The path in the bucket to which the channel delivers. The default is the bucket’s root path. Cannot begin or end with a forward slash (/). |
region | string | Yes | The region of the bucket to which the channel delivers. |
roleArn | string | Yes | The Amazon Resource Name (ARN) for the Identity and Access Management (IAM) role that delivers the files to the specified bucket. |
kmsKeyArn | string | No | The ARN of the Key Management Service (KMS) key used to encrypt data delivered to the bucket. This is necessary only if the bucket is configured to require KMS encryption. The default is to not use KMS to encrypt delivered data. |
postChannel
When creating a channel, the channel type is determined by which config
value is provided. If downloadConfig
is provided, a DOWNLOAD
channel is created. If s3Config
is provided, an S3
channel is created. Exactly one of these config
attributes must be provided.
Name | Type | Required | Description |
---|---|---|---|
name | string | Yes | The human-readable name for the channel. |
feed | Feed Reference | Yes | The feed that the channel delivers. |
downloadConfig | New Download Channel Configuration | No | The configuration for the DOWNLOAD channel to create. |
s3Config | New S3 Channel Configuration | No | The configuration for the S3 channel to create. |
New Download Channel Type Configuration
Name | Type | Required | Description |
---|---|---|---|
archiveFormat | string | Yes | The format of the files that will be downloaded through the channel. The following values are possible:
|
New S3 Channel Type Configuration
Name | Type | Required | Description |
---|---|---|---|
bucketName | string | Yes | The name of the Amazon S3 bucket to which the channel should deliver. |
baseBucketPath | string | No | The path in the bucket to which the channel should deliver. The default is the bucket’s root path. Cannot begin or end with a forward slash (/). |
region | string | Yes | The region of the bucket to which the channel should deliver. |
kmsKeyArn | string | No | The ARN of the KMS key used to encrypt data delivered to the bucket. This is necessary only if the bucket is configured to require KMS encryption. The default is to not use KMS to encrypt delivered data. |
Channel Status
Name | Type | Required | Description |
---|---|---|---|
status | string | Yes | The lifecycle status of the channel. The following values are possible:
ACTIVE by consuming systems. |
Channel List Response
Name | Type | Required | Description |
---|---|---|---|
items | [Channel] | Yes | The list of channels. |
totalResults | integer | Yes | The total number of results for the query. |
prevLink | string | No | The previous page of results. Absent on the first page of results. |
nextLink | string | No | The next page of results. Absent on the last page of results. |
firstLink | string | Yes | The first page of results. |
lastLink | string | Yes | The last page of results. |
Channel Reference
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the channel. |
Delivery
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the delivery. |
bundle | Bundle Reference | Yes | The bundle for the delivery. |
channel | Channel Reference | Yes | The channel the delivery belongs to. |
deliveredAt | dateTime | No | The date and time when the delivery was completed (was delivered for failed), in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
status | string | Yes | The lifecycle status of the delivery. The following values are possible:
DELIVERED by consuming systems. |
purgedAt | dateTime | No | The date and time when the delivery moved to PURGED status, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
metadata | object | No | The metadata related to the delivery. The schema of this object varies based on the following information:
DOWNLOAD and a status of either DELIVERED or PURGED . The S3 Channel Type Delivery Metadata is provided for deliveries with a channel type of S3 and a DELIVERED status. |
Delivery Metadata
Download Channel Type Delivery Metadata
Name | Type | Required | Description |
---|---|---|---|
bytesSize | integer | Yes | The total size of the downloadable archive in bytes. |
archiveFormat | string | Yes | The format of the downloadable archive. The following values are possible:
|
S3 Channel Type Delivery Metadata
Name | Type | Required | Description |
---|---|---|---|
bucketPath | string | Yes | The location in the bucket to which the delivery was uploaded. This begins with the following path: <bucketName>/<baseBucketPath>/ . |
Delivery List Response
Name | Type | Required | Description |
---|---|---|---|
items | [Delivery] | Yes | The list of deliveries. |
totalResults | integer | Yes | The total number of results for the query. |
prevLink | string | No | The previous page of results. Absent on the first page of results. |
nextLink | string | No | The next page of results. Absent on the last page of results. |
firstLink | string | Yes | The first page of results. |
lastLink | string | Yes | The last page of results. |
Error
Name | Type | Required | Description |
---|---|---|---|
code | integer | Yes | The HTTP status code representing the error. |
errorDetails | [ErrorDetail] | No | A list of additional error details. |
message | string | Yes | A human-readable description of the error. |
ErrorDetail
Name | Type | Required | Description |
---|---|---|---|
domain | string | No | A subsystem or context where an error occurred. |
location | string | No | The name of the field that caused an error. |
locationType | string | No | The location or type of the field that caused an error. The following values are possible: body, formData, header, path, query |
message | string | No | A human-readable description of the error. |
reason | string | No | A codified value representing the specific error resulting in the current error status. |
Feed
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the feed. |
name | string | Yes | A human-readable name for the feed. |
feedType | Feed Type Reference | Yes | The feed type of which the feed is an instance. |
scope | Scope | Yes | The domain of the data contained in bundles produced by the feed (for example, for bundles whose data is population-wide, this contains the population ID). Which fields are present in the scope object vary depending on the feed type. |
status | string | Yes | The lifecycle status of the feed. The following values are possible:
ACTIVE by consuming systems. |
createdAt | dateTime | Yes | The date and time when the feed was created, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
updatedAt | dateTime | Yes | The date and time when the feed was last updated, in ISO 8601 YYYY-MM-DDThh:mm:ss.SSSZ format. |
Feed List Response
Name | Type | Required | Description |
---|---|---|---|
items | [Feed] | Yes | The list of feeds. |
totalResults | integer | Yes | The total number of results for the query. |
prevLink | string | No | The previous page of results. Absent on the first page of results. |
nextLink | string | No | The next page of results. Absent on the last page of results. |
firstLink | string | Yes | The first page of results. |
lastLink | string | Yes | The last page of results. |
Feed Reference
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique identifier of the feed. |
Feed Type Reference
Name | Type | Required | Description |
---|---|---|---|
mnemonic | string | Yes | The mnemonic identifier of the feed type. |
Scope
Name | Type | Required | Description |
---|---|---|---|
population | Scope Part | No | A scope part representing a population on the HealtheIntent platform. |
Scope Part
Name | Type | Required | Description |
---|---|---|---|
id | string | Yes | The unique resource identifier for the scope part. |
name | string | No | A human-readable name for display purposes. |