A system conforming to this Core Interoperability Specification shall claim conformance at the level of a Use Case Actor (first columns of Table 1, Table 2 and Table 3). A system may claim conformance to one or more Use Case Actors among:
- PS-CA Producer
- PS-CA Consumer
- Document Repository (Local or Central)
- HIE Central Infrastructure
- Patient Portal
PS-CA Producer and PS-CA Consumer use case actor will primarily be taken up by EMR clinical solution vendors. Document Repository and HIE Central Infrastructure use case actor roles can be taken up by either by EMR clinical solution vendors or jurisdiction depending on the implementation approach that the jurisdiction decides to adopt. Similarly, Patient Portal use case actor can be taken up either by a vendor or jurisdiction depending on the approach and policies defined that allows for patient / subject of care access to their patient summary.
OpenAPI Specification
It is recommended to use the OpenAPI UI to access the interactive API documentation that lets developers try out the API calls directly in the browser. The following content is being developed and a link will be added once it is available.
Constraints on PS-CA Use Case Actors
There are some design constraints on use case actors when developing functionality to support the services mapped to those Use Case Actors.
Note: The scope of this section is limited to the constraints that are applicable to IHE MHD profile actors and transactions. The two key services supported by IHE MHD Profile are:
- Save PS-CA to Document Repository
- Retrieve PS-CA from Document Repository
This section provides key design constraints for implementation of these two required services using IHE methodology and FHIR standards.
Save PS-CA to Document Repository
The PS-CA Producer and Document Repository Use Case Actors are required to implement the Save PS-CA to Document Repository service.
These actors will use the IHE Transaction Provide Document Bundle [ITI-65] of MHD profile that passes a Provide Document Bundle Request from a Document Source to a Document Recipient.
Provide Document Bundle Request Message
This message uses the HTTP POST method on the target Provide Document Bundle endpoint to convey the metadata and the document(s) as a FHIR transaction.
Trigger Events
This method is invoked when the Document Source needs to submit one or more documents to a Document Recipient.
Message Semantics
The Document Source shall initiate a FHIR “transaction” using a “create” action by sending an HTTP POST request method composed of a FHIR Bundle Resource. The media type of the HTTP body shall be either application/fhir+json or application/fhir+xml.
Expected Actions
The Document Recipient shall accept both media types application/fhir+json and application/fhir+xml. On receipt of the submission, the Document Recipient shall validate the resources and respond with one of the HTTP codes defined in the response Message Semantics.
Refer to Provide Document Bundle [ITI-65] transaction details page for additional information
Retrieve PS-CA from Document Repository
The PS-CA Consumer and Document Repository Use Case Actors are required to implement the Retrieve PS-CA from Document Repository service.
These actors will use the following IHE Transactions of MHD profile to find document references, document list and retrieval of identified Patient Summary document:
- Find Document Lists [ITI-66]
- Find Document References [ITI-67]
- Retrieve Document [ITI-68]
Find Document List Request Message [ITI-66]
This message uses the search method parameterized query to obtain List Resources from the Document Responder.
Trigger Events
When the Document Consumer needs to discover List Resources matching various metadata parameters it issues a Find Document Lists message..
Message Semantics
The Document Consumer executes an HTTP search against the Document Responder List endpoint. The search target follows the FHIR HTTP specification, addressing the List Resource http://hl7.org/fhir/R4/http.html:
[base]/List?<query>
This URL is configurable by the Document Responder and is subject to the following constraints:
- The <query> represents a series of encoded name-value pairs representing the filter for the query as well as control parameters to modify the behavior of the Document Responder such as response format, or pagination.
- The Document Consumer may use GET or POST based searches. The Document Responder shall support both GET and POST based searches http://hl7.org/fhir/R4/http.html#search .
Query Search Parameters
The Document Consumer may supply, and the Document Responder shall be capable of processing all query parameters listed below. All query parameter values shall be appropriately encoded per RFC3986 “percent” encoding rules. Note that percent encoding does restrict the character set to a subset of ASCII characters which is used for encoding all other characters used in the URL.
- The Document Consumer SHALL include search parameter patient or patient.identifier, code, and status. The other parameters described below are optional.
- The Document Responder shall implement the parameters described below. The Document Responder may choose to support additional query parameters beyond the subset listed below. Any additional query parameters supported shall be supported according to the core FHIR specification. Such additional parameters are considered out of scope for this transaction. Any additional parameters not supported should be ignored.
| Query Search Parameters | Description | ||||||
|---|---|---|---|---|---|---|---|
code | This parameter, of type token, specifies the code.coding value supplied in the List Resource. The value of the code element indicates the List of type SubmissionSet or Folder as indicated | ||||||
date | This parameter, of type date, specifies the time when the List was created. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type. | ||||||
designationType | This IHE extension on parameters defined as List-DesignationType, of type token, specifies the designation type of the List. The value of the designation type element expresses contentType of submissionSet or the codeList of a Folder. Usually expressed in LOINC or SNOMED. Note that servers that do not support this extended search parameter will ignore it, and thus return more results than expected. | ||||||
identifier | This parameter, of type token, specifies an identifier for this List. The search results represent the results of a search on List.masterIdentifier and List.identifier. See ITI TF-2x: Appendix Z.2 for additional constraints on the use of the token search parameter type. | ||||||
patient | This parameter is of type Reference(Patient). The Document Consumer may get this reference through the use of the PDQm or PIXm Profiles, or by some other method. When the patient parameter is used, the Patient reference would need to be accessible to both the Document Consumer and the Document Responder. | ||||||
patient.identifier | This parameter, of type token, specifies an identifier associated with the patient to which the List Resource is assigned. This use of patient.identifier follows the FHIR Chaining Parameters search methodology. | ||||||
source.given and source.family | These parameters, of type string, specify the name parts of the author person which is associated with the List. This use of source.given and source.family follows the FHIR Chaining Parameters search methodology. | ||||||
sourceId | This IHE extension on parameters defined as List-SourceId, of type reference, specifies the source (author) value supplied in the List Resource. | ||||||
status | This parameter, of type token, specifies the status of the List. If included in the query, the Document Consumer shall populate the code portion of the token with one of the codes in the below table for status of List. The system portion of the token shall not be populated.
|
Expected Actions
The Document Responder shall process the query to discover the List entries that match the search parameters given.
Refer to Find Document Lists [ITI-66] transaction details page for additional information.
Find Document References Request message [ITI-67]
This message uses the search method parameterized query to obtain DocumentReference Resources from the Document Responder.
Trigger Events
When the Document Consumer needs to discover DocumentReference Resources matching various metadata parameters, it issues a Find Document References message.
Message Semantics
The Document Consumer executes an HTTP search against the Document Responders DocumentReference URL. The search target follows the FHIR HTTP specification, addressing the DocumentReference Resource http://hl7.org/fhir/R4/http.html:
[base]/DocumentReference?<query>
This URL is configurable by the Document Responder and is subject to the following constraints:
- The <query> represents a series of encoded name-value pairs representing the filter for the query, as specified in Section Query Search Parameters, as well as control parameters to modify the behavior of the Document Responder such as response format, or pagination.
- The Document Consumer may use GET or POST based searches. The Document Responder shall support both GET and POST based searches http://hl7.org/fhir/R4/http.html#search.
Query Search Parameters
The Document Consumer may supply, and the Document Responder shall be capable of processing, all query parameters listed below. All query parameter values shall be appropriately encoded per RFC3986 “percent” encoding rules. Note that percent encoding does restrict the character set to a subset of ASCII characters which is used for encoding all other characters used in the URL.
- The Document Consumer SHALL include search parameter patient or patient.identifier, and status. The other parameters described below are optional.
- The Document Responder must implement the parameters described below. The Document Responder may choose to support additional query parameters beyond the subset listed below. Any additional query parameters supported shall be supported according to the core FHIR specification. Such additional parameters are considered out of scope for this transaction. Any additional parameters not supported should be ignored.
| Query Search Parameters | Description | ||||||
|---|---|---|---|---|---|---|---|
author.given and author.family | These parameters, of type string, specify the name parts of the author person, which is associated with the DocumentReference Resource, or in Document Sharing nomenclature, the author of the Document Entry. This use of author.given and author.family follows the FHIR Chaining Parameters search methodology. | ||||||
category | This parameter, of type token, specifies the general classification of the DocumentReference Resource, or in Document Sharing nomenclature, the classCode of the Document Entry. | ||||||
creation | This IHE defined parameter defined as DocumentReference-Creation, of type dateTime, specifies a search against the DocumentReference.content.attachment.creation. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type. | ||||||
date | This parameter, of type date, specifies the time when the DocumentReference was created. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type. | ||||||
event | This parameter, of type token, specifies the main clinical acts documented by the DocumentReference Resource, or in Document Sharing nomenclature, the eventCodeList of the Document Entry. | ||||||
facility | This parameter, of type token, specifies the kind of facility found in DocumentReference.context.facilityType, or in Document Sharing nomenclature, the healthcareFacilityTypeCode of the Document Entry. | ||||||
format | This parameter, of type token, specifies the format of the DocumentReference Resource, or in Document Sharing nomenclature, the formatCode of the Document Entry. | ||||||
identifier | This parameter, of type token, specifies an identifier for this DocumentReference and/or the contained document. The search results represent the results of a search on DocumentReference.masterIdentifier and DocumentReference.identifier. | ||||||
patient | This parameter is of type Reference(Patient). The Document Consumer may get this reference using the PDQm or PIXm Profile. When the patient parameter is used, the Patient reference would need to be accessible to both the Document Consumer and the Document Responder. | ||||||
patient.identifier | This parameter, of type token, specifies an identifier associated with the patient to which the DocumentReference Resource is assigned. This use of patient.identifier follows the FHIR Chaining Parameters search methodology. | ||||||
period | This parameter, of type date, represents the time of service that is being documented by the DocumentReference. The period search parameter specifies an interval which the time of service overlaps. In Document Sharing nomenclature, this query parameter represents from/to parameters for the serviceStartTime and serviceStopTime of the Document Entry. See FHIR http://hl7.org/fhir/R4/search.html#date for use of the date search type. | ||||||
related | This parameter, of type reference, represents other identifiers associated with the DocumentReference Resource, or in Document Sharing nomenclature, the referenceIdList of the Document Entry. | ||||||
security-label | This parameter, of type token, specifies the security labels of the document referenced by DocumentReference Resource, or in Document Sharing nomenclature, the confidentialityCode of the Document Entry. | ||||||
setting | This parameter, of type token, specifies the specific practice setting of the DocumentReference Resource, or in Document Sharing nomenclature, the practiceSettingCode of the Document Entry. | ||||||
status | This parameter, of type token, specifies the status of the DocumentReference Resource, or in Document Sharing nomenclature, the availabilityStatus of the Document Entry. The Document Consumer shall populate the identifier portion of the token using one of the short codes in below table. The system portion of the token shall not be populated.
| ||||||
type | This parameter, of type token, specifies the specific type of the DocumentReference resource or in Document Sharing nomenclature, the typeCode of the Document Entry. See ITI TF-2x: Appendix Z.2 for additional constraints on the use of the token search parameter type. |
Expected Actions
The Document Responder shall process the query to discover the DocumentReference entries that match the search parameters given.
Refer to Find Document References [ITI-67] transaction details page for additional information including Find Document References Response message
Retrieve Document Request Message [ITI-68]
This transaction is used by the Document Consumer to retrieve a document from the Document Responder.
Trigger Events
The Document Consumer wants to obtain a document.
Message Semantics
The Document Consumer sends a HTTP GET request to the server. The Document Consumer request may be to retrieve the document content referenced by a DocumentReference.content.attachment.url.
The Document Consumer may provide HTTP Accept header, according to the semantics of the HTTP protocols. This enables the Document Consumer to indicate preferred mime-types such that the Document Responder could provide the document requested in an encoding other than the encoding indicated in the DocumentReference. For example, indicating application/fhir+json could result in the response from the Document Responder being a json FHIR Bundle of type document with all the content encoded as FHIR resources.
The only MIME type assured to be returned is the MIME type indicated in the DocumentReference.content.attachment.contentType.
The HTTP If-Unmodified-Since header shall not be included in the GET request.
Expected Actions
The Document Responder shall provide the document in the requested MIME type or reply with an HTTP status code indicating the error condition. The Document Responder is not required to transform the document.
Refer to Retrieve Document [ITI-68] transaction details page for additional information including Retrieve Document Response message.