CCD On Demand

IMAT contains a CCD on-demand product which uses all information about a patient across multiple source records. There are three methods of access available to users who have access to PHI and have been given a the searchappliance_ccd_on_demand role to access the CCD on-demand product. Note this role may not exist upon installation, and you may need to create a new group by this name before you can assign users.

• UI - IMAT has a UI that allows users to specify an MPI, date range to filter results to, MRN, and a filter to exclude and include facilities. This can be accessed from a UI located at https://{customerurl}/brand/ccda.html. Note this may not be installed by default. If you find you need this, contact IMAT support for help.
• RESTful API - IMAT has a RESTful API which allows exporting of a single patient or can be used to export a population.
• Interface engine - Using IMAT’s interface engine, you can generate and send CCDs through standard IHE profiles.

To gain access to the API an access token must be generated. IMAT recommends this access token be limited to the APIs required for export; this is the /extensions/IMAT-API and /search/results path. For patient populations, you will need to use /search instead of /search/results. Access tokens should be limited to an IP or IP range when possible.

Single Patient Export

The Generate CCD call is an asynchronous command, this means that the system will return an ID used for tracking status and retrieving items. The following three API calls will be used for the entire lifecycle of the call.

GET: /extensions/IMAT-API/patient/{MPID}/generate-ccd-script

This call starts the ASYNC process within the IMAT platform. IMAT will start generating the CCD in the background and status can be retrieved using the status call.

Request example:

GET https://<baseurl>/extensions/IMAT-API/patient/{MPID}/generate-ccd-script?start_date=20230101&end_date=20231231

The response from this call will be an ID used for tracking status and retrieving the generated CCD.

Example response:

 <?xml version="1.0" encoding="utf-8"?>
<result_id>7Z9Y7D6NCHNN287P6AP66HGX</result_id>

• mpid={number} - This is the internal IMAT MPID for the patient (a patient lookup call may be issued to lookup the MPID if not known)
• start_date,end_date={date yyyymmdd} - Used to filter the data included in the CCD to the date range supplied. If no dates are passed then the CCD will use all data for a patient within IMAT
• facility={string} - A comma separated list used to filter the CCD to only include data from a particular facility
• exclude_facility={string} - A comma separated list used to ignore data from included facilities
• fmrn={string} - A facility medical record number of the format of facility~mrn where facility can be the name or OID of the location. This can be used to filter records that include this MRN from this facility.

GET: /search/results/{result_id}/status

This retrieves the status of the CCD on demand process.

This will return one of the following statuses:

• Running - The request is still processing
• Aborted - The patient doesn't have enough information to process a CCD
• Failed - IMAT has run into a problem generating the CCD
• Complete - A user may now retrieve the completed CCD
• Ready - The result-ID directory is populated, but the queue command has not yet been issued to the QueryController
• Queued - The job is in the QueryController queue waiting to be processed
• Aborted - The user (or admin) aborted the job while it was running (or queued)
• Done - The same as Complete, but Done has been deprecated

Request example:

GET https://<baseurl>/search/results/7Z9Y7D6NCHNN28P6AP66HGX/status

Example response:

<result>
	<status>COMPLETE</status>
	<exit_code>None</exit_code>
	<exit_message>None</exit_message>
</result>

GET: /search/results/{result_id}/output/{filename}

The call retrieves output from the CCD generation process.

The CCD file is named ccda.xml.

Request example:

GET https://<baseurl>/search/results/7Z9Y7D6NCHNN28P6AP66HGX/output/ccda.xml

Example response:

<ClinicalDocument xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:hl7-org:v3" xsi:schemaLocation="urn:hl7-org:v3 infrastructure/cda/CDA_SDTC.xsd">
...
</ClinicalDocument>

Patient Population Export

A user will be set up with access granted to the patient population which is being requested. This can come from a treatment relationship, member roster, or some other data driven criteria.
The user will then issue a call to get a list of all MPIDs available for export using the following command.

GET: /search

Request example:

GET https://<baseurl>/search?q=()UNIVERSE&fields=mpid&store=mpi-persona&format=csv&limit=-1

• q={string} - IMAT Query string to search the data. ()UNIVERSE is a keyword for all data.
• fields={string} - The fields that are being requested back.
• store={string} - Limits the search to the specified store.
• format={string} - Available formats are CSV or XML.

The example searches for all patients available to the users, and extracts a list of MPIs in either XML or CSV targeting the MPI store.

Example response for CSV:

   mpid
	2
	3
	11
	15
	16
	19
	21
	23
	24
	27

Example response for XML:

<response xmlns:ps="http://software.perfectsearchcorp.com/sdk/query-v1">
		<timestamp>2023-12-04 11:30:22</timestamp>
		<hits total="-1" sample="0" skip="0" count="10" match="exact" grosscount="10">
			<hit ref="2" score="0" store="1101" space="1101">
				<mpid>2</mpid>
			</hit>
			<hit ref="3" score="0" store="1101" space="1101">
				<mpid>3</mpid>
			</hit>
			<hit ref="22" score="0" store="1101" space="1101">
				<mpid>11</mpid>
			</hit>
			<hit ref="26" score="0" store="1101" space="1101">
				<mpid>15</mpid>
			</hit>
			<hit ref="27" score="0" store="1101" space="1101">
				<mpid>16</mpid>
			</hit>
			<hit ref="30" score="0" store="1101" space="1101">
				<mpid>19</mpid>
			</hit>
			<hit ref="32" score="0" store="1101" space="1101">
				<mpid>21</mpid>
			</hit>
			<hit ref="34" score="0" store="1101" space="1101">
				<mpid>23</mpid>
			</hit>
			<hit ref="35" score="0" store="1101" space="1101">
				<mpid>24</mpid>
			</hit>
			<hit ref="38" score="0" store="1101" space="1101">
				<mpid>27</mpid>
			</hit>
		</hits>
		<query lang="eng">
			<q> ()UNIVERSE </q>
		</query>
		<timing>
			<prep_sec>0.000067</prep_sec>
			<search>
				<engine_sec>0.000005</engine_sec>
				<total_search_sec>0.000131</total_search_sec>
			</search>
			<build_report_sec>0.026357</build_report_sec>
			<total_sec>0.026555</total_sec>
		</timing>
	</response>

For each MPID returned, use the APIs for single patient export.

IMAT also has an interface engine which can be used to programmatically export patients.

IMAT's professional services team may also be contacted to help with or complete any of these tasks on a time and materials basis.

For more information see IMAT's API documentation page for more detailed instructions. A specific version can be found at https://{base_url}/ui/documentation/#/.

IMAT’s CCD conform to the latest CDA R2.1 R4.1 STU 2023 specifications.