Data Syndication API

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
Consumer Engagement Analytics	consumer-engagement-analytics
Dimensions EDW	dimensions-edw
Hierarchical Condition Categories Analytics	hcc-analytics
Longitudinal Record EDW	long-record-edw
Millennium ODS	millennium-ods
Outcomes Analytics	outcomes-analytics
Personnel Analytics	personnel-analytics
Wellness Analytics	wellness-analytics

Channel Types

The following channel types are currently available:

Name	Description
`DOWNLOAD`	Channels the data into archive files that can be downloaded using this API.
`S3`	Channels the data into a specified Amazon S3 bucket.

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

Authorization

Only authorized system accounts are able to access endpoints. Contact your HealtheIntent engagement leader if you need authorization granted.

Endpoint	System Account Authorization Required
/feeds	Must be authorized for feed administration
/feeds/{feedId}	Must be authorized to access the specified feed
/feeds/{feedId}/bundles	Must be authorized to access the specified feed
/bundles/{bundleId}	Must be authorized to access the feed to which the specified bundle belongs
/channels	Must be authorized for channel administration
/channels/{channelId}	Must be authorized to access the specified channel
/channels/{channelId}/deliveries	Must be authorized to access the specified channel
/deliveries/{deliveryId}	Must be authorized to access the channel to which the specified delivery belongs
/downloads/{deliveryId}	Must be authorized to access the channel to which the specified delivery belongs

Requesting a Feed and Channel

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 to request that these be set up.

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 of DOWNLOAD.
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 is DELIVERED, 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 the bundleReleasedAt and bundleReleasedAfter query parameters. You can use those parameters to download all the deliveries up to a certain date and time, then save the bundle.releasedAt value so you can use the value in the bundleReleasedAfter query parameter next time and download only the new deliveries.
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 to TAR_GZ, the file is a gzip-compressed tar archive file and should have a file extension of .tar.gz. If it is set to TAR_CONTAINING_LZ4, the downloaded file is a tar archive containing LZ4-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 within it can be decompressed using LZ4. The archive format used for a delivery also is included in the delivery’s metadata as the archiveFormat attribute. Note that a channel’s configuration can be updated to change the format of future deliveries. The format in a delivery’s metadata should be used when determining how to handle the file, since that reflects the actual format of the file.

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’s metadata 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.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.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.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.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.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.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.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.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.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.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

Retrieve a List of Channels

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.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.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.healtheintent.com/data-syndication/v1/channels?feedId=0f1c7802-6255-46f0-b898-6e5b851bc0af&orderBy=name&offset=0&limit=20",
  "lastLink": "https://cernerdemo.api.us.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.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.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

Deliveries

Retrieve a List of Deliveries

Example Request

require 'httparty'

HTTParty.get(
  'https://cernerdemo.api.us.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.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.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.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.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.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.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.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. Possible values: DOWNLOAD S3
feed	Feed Reference	Yes	The feed the channel delivers.
status	string	Yes	The lifecycle status of the channel. Possible values: PENDING - the channel is awaiting validation by Cerner ACTIVE - the channel is active and can deliver bundles for its associated feed INACTIVE - the delivery of bundles through this channel is stopped Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not 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`.

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.
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.

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. Possible values: IN_PROGRESS - The delivery is in progress. DELIVERED - The delivery was successful. FAILED - The delivery failed. PURGE_IN_PROGRESS - The archive file is in the process of being deleted and is no longer available for download (only applicable to the `DOWNLOAD` channel type). PURGED - The archive has been deleted and is no longer available for download (only applicable to the `DOWNLOAD` channel type). Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not 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 and is determined by the type of the channel this delivery belongs to.

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. Possible values: 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. Possible values: ACTIVE - the feed is active and will produce bundles INACTIVE - production of new bundles for the feed is stopped Additional status values may be added in the future. To allow for future additions, consuming systems must gracefully handle unknown or undocumented status values. Any unknown or undocumented status value can safely be treated as not 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 within 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.