ESMD FHIR Implementation Guide
1.0.0 - esmd

ESMD FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Faq

Frequently Asked Questions

1. Authentication and Security

Question: Is OAuth required to access the esMD FHIR APIs, and are there additional security measures like IP whitelisting?
Answer: Yes, the esMD FHIR APIs are secured using OAuth 2.0, which ensures only authorized users and applications can access sensitive healthcare using access tokens. Implementers must obtain the appropriate access tokens through the OAuth 2.0 authorization process before making API requests.
Additionally, esMD FHIR employs IP whitelisting for extra security, allowing access only from pre-approved IP addresses. Implementers should ensure that their server IPs are whitelisted for seamless access.
Please refer to the esMD FHIR Implementation Guide Security page for additional information.

2. Data Exchange Format

Question: What data formats are supported by the esMD FHIR APIs for data exchange between Health Information Handlers (HIHs)/Providers and esMD?
Answer: esMD FHIR APIs exclusively support the JSON format for all data exchanges between HIHs/Providers and the esMD system.

3. Clinical Document Support

Supported Clinical Document Types and Formats

Question: What types of clinical documents does esMD support?
Answer: esMD supports:
• HITSP C62: Used for support of unstructured clinical documents, such as scanned documents or free-text clinical notes.
• Consolidated Clinical Document Architecture (C-CDA): Used for support of structured and unstructured documents which contain headers for patient and provider information.

Question: What formats are supported for HITSP C62 unstructured documents?
Answer: esMD supports the following formats:
• PDF Document:

  • Format Code: urn:ihe:iti:xds-sd:pdf:2008
  • Usage: For PDF-encoded files (e.g., scanned clinical notes)
    • XML/JSON Document:
  • Format Code: urn:ihe:iti:xds:2017:mimeTypeSufficient
  • Usage: For unstructured text data encoded as XML or JSON

Question: Are there any restrictions on unstructured document formats for HITSP C62?
Answer: Yes, only PDF, XML, or JSON formats are accepted for unstructured documents. esMD relies on the format code to correctly identify the document type without performing content validation.

C-CDA Document Structure and Use

Question: How does esMD handle C-CDA documents?
Answer: C-CDA documents must have:
• A Header with classifications, patient/provider information, and identifiers.
• A Body for the clinical report, represented as either nonXMLBody (unstructured clinical document) or structuredBody (structured clinical document).
• esMD supports nonXMLBody for unstructured PDF documents and structuredBody for XML-based structured documents as FHIR attachments.

Question: What is the difference between nonXMLBody and structuredBody in C-CDA?
Answer:
• nonXMLBody: Used for unstructured documents (e.g., PDF), wrapped in a CDA header.
• structuredBody: Used for structured clinical data, organized per the C-CDA format.

Question: Can esMD perform validation on the contents of clinical documents?
Answer: No, esMD does not validate the contents of clinical documents but expects the correct format codes to ensure compatibility and processing.

4. FHIR Document Encapsulation

Question: How are esMD-supported documents encapsulated in FHIR?
Answer: esMD encapsulates documents as FHIR attachments:
• Unstructured documents such as PDFs, are wrapped in a nonXMLBody with a C-CDA header.
• Structured XML documents are wrapped in a CDA header, following FHIR attachment guidelines.

Question: Can I submit both unstructured and structured documents in esMD for FHIR?
Answer: Yes, both types are supported:
• Unstructured documents: (PDFs or text documents in XML/JSON) use HITSP C62 format codes.
• Structured documents: (C-CDA standard) are encapsulated in a structuredBody and submitted as FHIR attachments.

Question: What are the primary format codes used in esMD for document exchange?
Answer: esMD uses the following format codes:
• For PDF documents: urn:ihe:iti:xds-sd:pdf:2008
• For unstructured text documents: urn:ihe:iti:xds:2017:mimeTypeSufficient

Question: Who can submit clinical documents to esMD using the esMD FHIR Rest APIs?
Answer: Health Information Handlers (HIHs) and Providers who have completed the esMD FHIR onboarding process can submit clinical documents to esMD, using FHIR attachments to encapsulate unstructured and structured documents.

5. Sample Data and Implementation

Question: Can you elaborate on the examples provided in the esMD FHIR Implementation Guide (IG)?
Answer: The examples in the IG are for guidance and educational purposes only and do not contain real patient data. They illustrate FHIR resource structures within esMD, but actual implementations need specific business rules and compliance adherence.

6. Extensions

Question: Are FHIR® extensions supported in esMD FHIR, and where can I find more information about them?
Answer: Yes, esMD FHIR supports the Health Level 7 (HL7) FHIR® extensions as defined in the esMD FHIR profiles. Detailed information about supported extensions can be found in the Extensions section of the esMD FHIR Implementation Guide. Only extensions compliant with esMD Profiles are supported for interoperability within esMD.

7. Onboarding to FHIR

Question: Can Health Information Handlers (HIHs) onboard to esMD FHIR in phases?
Answer: Yes! esMD FHIR’s modular design allows HIHs to onboard to FHIR using a phased approach based on the following four functional module groups.

  1. Bundle Submission & Notification Retrieval
  2. Service Registration
  3. Document Retrieval
  4. Provider Delivery Confirmation

HIHs must consider the following things when onboarding to esMD FHIR using a phased approach:

  1. HIHs must configure their implementation environment to use the esMD Authentication API and the esMD Generate Presigned URL API along with the first set of modules that are implemented. These two APIs provide services that are used by all FHIR modules.
  2. HIHs have the option to onboard esMD FHIR modules in any order they choose.
  3. HIHs must onboard the Bundle Submission and Notification Retrieval modules during the same phase because those modules work together to provide the document submission and submission status notification services that make up the esMD FHIR document bundle submission functionality.
  4. Each HIHs is free to determine the length of time they take to onboard each module because esMD does not impose a specific timeframe for an HIH to be fully onboarded to esMD FHIR services.
  5. When an HIH onboards an esMD FHIR module, the onboarding applies to all supported LOBs which that HIH has currently onboarded to support in XDR Connect Gateway.

Question: Can HIHs submit requests to esMD using both the XDR Connect Gateway and esMD FHIR APIs?
Answer: Yes! esMD is implementing FHIR is a manner that allows HIHs to submit requests in both FHIR REST APIs and the current XDR Connect Gateway submission mechanisms.
HIHs must consider the following things when submitting requests to esMD using both XDR Connect Gateway and FHIR REST APIs:

  1. For any transaction request that is submitted in XDR, the corresponding response will be received in XDR. For any bundle submission transaction request that is submitted in FHIR, the corresponding response will be received in FHIR.
  2. esMD XDR and FHIR submission flows use the same database tables for storing data and metadata used to validate submissions. When testing XDR and FHIR submission transactions, HIHs must take care to ensure that they use different unique submission set or document metadata elements for the two submission flows.

Question: After onboarding to FHIR, can an HIH switch back to Connect Gateway if they encounter any issues?
Answer: “Switching back to Connect Gateway” is not necessary because esMD XDR Connect Gateway and esMD FHIR REST API services have been designed to operate simultaneously as independent flows. In this manner, onboarding to FHIR does not prevent an HIH from using the XDR Connect Gateway flow if they experience problems using the FHIR REST API approach. Please refer the following question for additional information, “Can HIHs submit requests to esMD using both the XDR Connect Gateway and esMD FHIR APIs?”

Question: What is the timeline to decommission the XDR Connect Gateway?
Answer: No timeline for decommissioning the XDR Connect Gateway has been set because there is currently no set timeline for all HIHs to complete onboarding to all esMD FHIR modules.

Question: Are there any changes to the current requirements regarding the maximum payload size included in a submission?
Answer: There are no changes to the maximum payload size included in a submission as part of the July 2025 release. esMD will accept a maximum payload size of 200 MB for FHIR Bundle Submission requests. If HIHs wish to submit payloads larger than 200 MB, they must utilize the split payload functionality. esMD is exploring options to increase the maximum payload size in future releases.