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
The esMD (electronic Submission of Medical Documentation) FHIR (Fast Healthcare Interoperability Resources) testing scenarios are essential for ensuring the successful implementation of the framework. These scenarios help verify the application's functionality, enhance quality, and improve security by identifying issues early in the development process. Additionally, they facilitate integration with external systems, support user experience, and ensure compliance with FHIR standards and regulations. By systematically executing these testing scenarios, we aim to create a robust system that enhances operational efficiency and contributes to better healthcare outcomes.
| Testcase No | Test Scenario | Test Scenario Description | Expected Outcome | Submission bundle json | Response json |
| TC001 | esMD recommends HIHs to validate their ability to successfully submit an ADR response bundle for all NON-PA programs. Note: This scenario is mandatory for all NON-PA program validations during UAT. |
HIHs must submit a valid ADR transaction containing SubmissionSet metadata and associated clinical document payload document reference. Upon successful submission, esMD will return a real-time acknowledgment confirming receipt. | HIHs should receive an acknowledgment from esMD confirming the successful upload of the ADR bundle. | Bundle-TC001-BundleSubmission | Bundle-TC001-BundleSubmission-Response |
| TC002 | To verify that esMD correctly processes the submitted ADR bundles and returns validation notifications. | After receiving the ADR bundle, esMD performs validation and generates a Validation Success notification if all requirements are met. This confirms the package is ready to be delivered to the Review Contractor. | HIHs should be able to retrieve the Validation Success notification from the esMD FHIR server. | GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List?transaction-status-type=ready-to-download
Authorization: Bearer [token] |
Bundle-TC002-BundleSubmission-Validation-Success.json |
| TC003 | Pickup Confirmation & Admin Error Notification by Review Contractor | After the Review Contractor downloads a submitted package, the esMD system automatically generates a Pickup Confirmation notification. This notification is available for HIHs to retrieve, confirming that the package has been successfully accessed by the Review Contractor. | HIHs should be able to retrieve the Pickup Confirmation notification from the esMD FHIR server. If there are any issues (e.g., administrative errors), they should also receive an appropriate Admin Error notification. | GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List?transaction-status-type=ready-to-download
Authorization: Bearer [token] |
Bundle-TC003-BundleSubmission-Pickup-Success.json Bundle-TC004-BundleSubmission-Admin-Errors.json |
| TC004 | Submission of Invalid Bundle with Unique ID Exceeding Allowed Characters Note : Allowed Unquie ID value in 64 Alphanumeric and underscore and Hypen are allowed |
The HIH submits a bundle where the uniqueId exceeds the allowed character length or includes invalid characters. The esMD system performs validation and rejects the transaction, returning an acknowledgment response containing an OperationOutcome error detailing the uniqueId violation. | HIHs should: |
TC004Invaliduniqueidrequest.json | TC004Validationfailedresponse.json |
| TC005 | To ensure HIHs can validate how esMD handles submissions where the claimId is invalid, and properly process the follow-up validation failure notification. | The HIH submits a bundle request with an invalid claimId.
|
HIHs should be able to:
|
TC005Invalidclaim.json | TC005Invalidclaimresponse.json |
| TC006 | Retrieval of Validation Failure Notification for Invalid Claim ID | Following the invalid bundle submission from the previous test case (TC005), HIHs should:
|
HIHs are able to successfully access and review the validation failure notification through the esMD FHIR server, confirming that the claimId issue is clearly reported. | GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List?transaction-status-type=ready-to-download
Authorization: Bearer [token] |
TC006Validation_failure.json |
| TC007 | esMD recommends HIHs to validate their ability to successfully submit an ADR response bundle with multiple payloads. | As part of UAT, the HIH submits a valid Response to an ADR transaction. This bundle contains the required SubmissionSet metadata along with multiple clinical document payloads. The esMD system receives the submission, performs both technical and content validations, and processes the request accordingly. Upon successful submission and validation, esMD returns a real-time success acknowledgment followed by a validation success notification. | TC007Multiplepayloadrequest.json | TC007Multiplepayloadresponse.json | |
| TC008 | esMD recommends HIHs to validate their ability to successfully submit an ADR response bundle with split payloads. | As part of UAT, esMD recommends that HIHs validate their ability to submit an ADR response bundle with Split Payloads. In this scenario, the HIH submits a valid ADR transaction that includes SubmissionSet metadata and multiple clinical document payloads split across separate DocumentReference resources. The esMD system verifies the submission and returns a real-time success acknowledgment once the bundle is accepted. | |||
| TC009 | esMD recommends HIHs to validate their ability to successfully submit an ADR response bundle with duplicate uniqueId. | As part of UAT, esMD recommends that HIHs validate how the system handles bundle submissions that include a duplicate uniqueId — i.e., a uniqueId that was previously submitted and already exists in the esMD system. In this scenario, the HIH submits a new bundle with a uniqueId that matches a previously accepted transaction. The esMD system performs internal validation and detects the duplication. | TC009Duplicateuniqueidrequest.json | TC009Duplicateuniqueidresponse.json | |
| TC0010 | esMD recommends HIHs to validate their ability to successfully submit an Ambulance Prior Authorization Request bundle with 200MB Payload. | As part of UAT, the esMD team recommends that HIHs validate their ability to submit a valid bundle request with a payload size of 200MB. This bundle must include appropriate SubmissionSet metadata and corresponding clinical document payloads. This test is critical for verifying that large payloads are properly received, processed, and acknowledged by the esMD system under Prior Authorization (PA) programs. | TC0010Ambulance_request.json | TC0010Ambulanceresponse.json | |
| TC0011 | esMD recommends HIHs to validate their ability to successfully submit an PWK bundle submission request. | As part of UAT, esMD recommends that HIHs validate their ability to submit a valid PWK (Paperwork) bundle request. The bundle must include proper SubmissionSet metadata and corresponding clinical document payloads as required for PA (Prior Authorization) programs. The esMD system performs validation and returns a real-time acknowledgment upon successful submission. | TC0011unsolicitedpwkrequest.json | TC0011pwkresponse.json | |
| TC0012 | esMD recommends HIHs to validate their ability to successfully submit an AMB(Ambulance PA Program) bundle submission request. | As part of UAT, esMD recommends that HIHs validate the successful submission of a valid AMB (Ambulance) bundle request. This includes submitting a bundle with correct SubmissionSet metadata and required clinical document payloads. The esMD system verifies the submission and provides a real-time success acknowledgment. | TC0012Ambulance_request.json | TC0012Ambulanceresponse.json |
| Testcase No | Test Scenario | Test Scenario Description | Expected outcome | Request json | Response json |
| TC001 | esMD recommends that HIHs validate their ability to successfully submit the Practitioner resource for provider registration. | As part of UAT, the esMD team recommends that HIHs validate their ability to register a provider by submitting a Practitioner resource with Action Code 'A' to the esMD FHIR endpoint. This test ensures that the system correctly processes new provider registrations and returns an appropriate confirmation response. | TC001Practitioneradd.json | TC001Practitioneraddresponse.json | |
| TC002 | Update Provider Status via Practitioner Resource Submission. | esMD recommends that HIHs validate updating a provider's status from 'B' to 'E' by submitting a Practitioner resource with the appropriate Action Code. | A SUCCESS status is returned in the OperationOutcome resource from esMD, confirming that the status update was processed. | TC002Practitionerupdaterequest.json | TC002Practitionerupdateresponse.json |
| TC003 | Remove a Provider via Practitioner Resource Submission | esMD recommends validating provider removal by submitting a Practitioner resource with Action Code 'R'. | esMD returns a SUCCESS status in the OperationOutcome, confirming successful removal of the provider. | TC003Practitionerremoverequest.json | TC003Practitionerremoveresponse.json |
| TC004 | Register Multiple Providers in a Single Bundle | As part of UAT, HIHs should verify successful registration of multiple providers by submitting a bundle of Practitioner resources using the Service Registration bundle for the EEP service. | A SUCCESS status for each Practitioner resource is included in the JSON response's OperationOutcome. | TC004Practitionerbundleaddrequest.json | TC004Practitionerbundleaddresponse.json |
| TC005 | Process Multiple Practitioner Actions in a Service Registration Bundle | HIHs are encouraged to test the submission of a service registration bundle that includes multiple Practitioner resources with different action codes: |
A SUCCESS status is returned for each Practitioner resource in the OperationOutcome within the JSON response. | TC005Practitionerbundlemultiupdaterequest.json | TC005PractitionerbundleMultiupdateresponse.json |
| TC006 | Submit Invalid Practitioner Bundle with END_DATE_LESS_THAN_START_DATE | esMD recommends that HIHs test system validation for date consistency by submitting a Practitioner bundle with an end date that is earlier than the start date. | A 202 Accepted response is returned, along with an OperationOutcome containing relevant error messages regarding the date inconsistency. | TC006Bundlemultiplepractitionerenddatelessthanstartdate_request.json | TC006Bundlemultiplepractitionerenddatelessthanstartdate_response.json |
| TC007 | Submit Practitioner Bundle with Invalid Action Code | HIHs should validate that esMD correctly handles Practitioner submissions with unsupported or invalid action codes. | A 202 Accepted response is returned, and the OperationOutcome contains appropriate validation error details for the invalid action code. | TC007BundleMultiplepractitionerInvalidactionrequested.json | TC007bundlepractitionerinvalidactionrequestedresponse.json |
| Test case # | Test Scenarios | Test Scenario Description | Expected outcome | Get Query | Response |
| TC001 | HIH run a Scheduler Job to Retrieve Ready-to-Download Documents from esMD | As an HIH, I need to run a scheduler job every 5 minutes to retrieve documents marked as ready-to-download from esMD. The documents should include: 1. EMDR (prepay, postpay, postpayother) 2. LETTERS (Review Results Letter) 3. PAResponse/PAReject I will generate a DocumentReference GET request with search parameters: |
As an HIH, I can successfully retrieve a bundle of document references containing metadata and binary URLs for downloading attachments. | Query: GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/DocumentReference |
Example-EMDRPrePay-FindBundleDocumentReferences Example-EMDRPostPay-FindBundleDocumentReferences Example-EMDRPostPayOther-FindBundleDocumentReference Example-Letter-FindBundleDocumentReference Example-PAReject-FindBundleDocumentReference Example-PAResponse-FindBundleDocumentReference |
| TC002 | Storing Binary URLs in HIH Database for Future Re-downloading of Documents | After retrieving document references, I need to store the binary URLs in the HIH database to allow re-downloading of documents in the future. | As an HIH, I successfully store binary URLs in the database for future document retrieval. | Query for PDF document: GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/Binary/PBE0060432669EC_20250212113936_1 Query for Clinical document: GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/Binary/PBE0060432669EC_20250212113936_2 |
Example-Binary-ResponseJSON.json Example-Binary-ResponsePDF.json Example-Binary-ResponseXML.json Example_LETTERS_NOTIFICATION_ATTACHMENT_JSON.json Example_PAREJECT_CLINICAL_XML.xml Example_PAREJECT_CLINICAL_XML_JSON.xml Example_PAREJECT_NOTIFICATION_ATTACHMENT.json Example_PAREJECT_NOTIFICATION_ATTACHMENT_XML.xml Example_PARESP_ATTACHMENT_XML.xml Example_PARESP_NOTIFICATION_CLINICAL_XML.xml Example_POSTPAYOTHER_NOTIFICATION_ATTACHMENT_XML.xml Example_POSTPAYOTHER_NOTIFICATION_CLINICAL_XML.xml Example_POSTPAY_NOTIFICATION_ATTACHMENT_XML.xml Example_POSTPAY_NOTIFICATION_CLINICAL_XML.xml Example_PREPAY_NOTIFICATION_ATTACHMENT_XML.xml Example_PREPAY_NOTIFICATION_CLINICAL_XML.xml |
| TC003 | Analyzing Esmd-Ext-RequestType Extension to Determine Document Type After Downloading | After downloading documents, I need to analyze the Esmd-Ext-RequestType extension to determine the document type and store it in the appropriate folder. | As an HIH, I can correctly categorize and store documents in the appropriate folders based on request type | ||
| TC004 | HIH Re-downloading Documents from esMD Using DocumentReference GET Request | As an HIH, I need to redownload documents from esMD. The documents should include: 1. EMDR (prepay, postpay, postpayother) 2. LETTERS (Review Results Letter) 3. PAResponse/PAReject I will generate a DocumentReference GET request with search parameters: • transactionid = 'ABC1234567890EC' |
As an HIH, I can successfully retrieve a bundle of document references containing metadata and binary URLs for redownloading attachments. | Query: GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/DocumentReference?transactionid=PVS0060432569EC |
Redownload-Bundle-Example-EMDRPostPay-FindBundleDocumentReferences.json Redownload-Bundle-Example-EMDRPostPayOther-FindBundleDocumentReference.json Redownload-Bundle-Example-EMDRPrePay-FindBundleDocumentReferences.json Redownload-Bundle-Example-Letter-FindBundleDocumentReference.json Redownload-Bundle-Example-PAReject-FindBundleDocumentReference.json Redownload-Bundle-Example-PAResponse-FindBundleDocumentReference.json |
| TC005 | HIH Redownloads the document with missing transaction id | HIH wishes to redownload, with missing transaction ID as a parameter in the GET Document Retrieval API." | If HIH doesn’t provide the transaction ID for redownloading the file the following error message will be received "esMD requires Transaction ID when trans-status-type is processed. Correct and resubmit." | Query: GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/DocumentReference?transactionid=PVS0060432569EC |
Redownload-Bundle-Example-MissingTransactionID.json |