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
Notifications
Notifications Retrieval
High-level Notifications Retrieval Overview
The esMD FHIR Notifications Retrieval process uses custom esMD FHIR profile resources and esMD FHIR REST APIs to provide structured, secure interactions that enable HIHs (Health Information Handlers) or Providers to obtain notifications related to the status of various transactions. The Notifications Retrieval process enables HIHs and providers to automate the notification request submission and notification retrieval tasks using scheduled jobs to submit queries based on transaction status, request type, and unique ID.
The following custom esMD FHIR profile resources and esMD FHIR REST APIs are used in the notifications retrieval process:
- Authentication API – The Authentication API (Auth API) is an esMD FHIR REST API that uses the Open Authorization (OAuth 2.0) framework to facilitate secure access to the esMD System by validating user credentials and providing access tokens for use in subsequent API requests.
- Notifications Retrieval API – The Notifications Retrieval API is an esMD FHIR REST API that makes use of two custom esMD FHIR profiles:
- Esmd-FindListTransactionNotification - This profile is used by the Notifications Retrieval API to enable HIHs to request a list of notifications which are available for the HIH to retrieve.
- Esmd-FindBundleListNotifications – This profile is used by the Notifications Retrieval API to return a FHIR SearchSet bundle which contains a collection of List resources which contain notification information about the HIHs transactions.
The esMD FHIR Notifications Retrieval process follows the steps that are summarized below:
- HIHs securely authenticate to the esMD System using the esMD Auth API.
- HIHs use a scheduler to automate the task of using the Notifications Retrieval API to periodically send a request to the esMD FHIR server using the Esmd-FindListTransactionNotification resource to identify notifications that are available for retrieval. The esMD System uses the Notifications Retrieval API to return a FHIR SearchSet bundle that is based on the Esmd-FindBundleListNotifications resource. This resource contains the notification details related to each transaction identified by a valid unique ID.
- HIHs must parse, correlate, and persist the notifications with previously submitted transactions using the transaction unique ID and store the notifications locally for future reference and auditing. Refer to the esMD Notification Categories for a description of esMD supported notifications.
- HIHs log and take corrective action to address any received errors which fall within their responsibility to correct.
esMD Notification Categories
| Notification Category | Notification Category Description | HIH Response to Notification |
| Transaction Bundle Validation Success Response Notification | This notification is generated when a bundle submission transaction is successfully validated (with or without warnings), and the clinical documents are sent to the Review Contractors (RCs) as a package. | No further action is required from HIH at this point. HIHs are informed the package is being sent to the RCs for further review of the Bundle Submission. HIHs will also be informed of any warnings that apply to the submission. |
| Transaction Bundle Validation Failure Response Notification | This notification is generated when esMD processes a bundle submission transaction and identifies validation errors (with or without warnings). All error messages related to the validation failures are returned in the response. | HIHs must review the validation failures and warnings, correct the errors and resubmit the bundle submission. |
| Package Pickup Success or Failure Notification | This notification is generated to indicate either success or failure when the RC attempts to retrieve a package delivered by esMD. A successful pickup response indicates no issues were encountered by the RC. A failure response will identify issues that prevented the RC from successfully picking up the package. | Pickup Success: No further action is required from HIH. Pickup Failure: The HIH must look into the cause of the failure and resubmit the package. |
| Administrative Error Notification | This notification is generated by the RC when it identifies issues with the package or its contents that results in the package or its contents being unusable. (e.g., problems with PDF/XML files or metadata). | The HIH must review the error details, make the necessary corrections to the package or its metadata, and resubmit the package. |
Note: Each of the Notification Categories listed above applies to the following supported esMD Lines of Business.
Supported esMD Lines of Business
The esMD FHIR Notification Retrieval process enables HIHs to download notifications which are related to the following supported esMD lines of business:
| Line of Business (LOB) | CTC(s) | LOB Description |
| ADR Responses | 1 | Response message sent for Additional Documentation Request (ADR) |
| Unsolicited PWK Documentation | 7 | Unsolicited Paperwork (PWK) Documentation |
| Ambulance | 8.1 | Prior Authorization (PA) Requests for Repetitive Scheduled Non-Emergent Ambulance Transport |
| HHPCR | 8.3 | Prior Authorization (PA) Requests for Home Health Pre-Claim Review request (HHPCR) |
| DMEPOS | 8.4 | Prior Authorization (PA) Requests for Durable Medical Equipment, Prosthetics/Orthotics & Services (DMEPOS) |
| HOPD | 8.5 | Prior Authorization (PA) Requests for Hospital Outpatient Department Services (HOPD) |
| IRF | 8.6 | Prior Authorization (PA) Requests for Inpatient Rehabilitation Facility (IRF) |
| First Level Appeal Requests | 9 | Requesting a First Level Appeal Request |
| Second Level Appeal Requests | 9.1 | Requesting a Second Level Appeal Request |
| ADMC Requests | 10 | Advanced Determination of Medicare Coverage Requests (ADMC) |
| RA Discussion Requests | 11 | Recovery Auditor Discussion (RAC) Requests |
| DME Discussion Requests | 11.1 | Durable Medical Equipment (DME) Phone Discussion Requests |
Detailed Workflow for Retrieving and Managing Notifications
The following diagram along with steps 1 and 2 provide a description of the automated process that HIHs use for retrieving notifications from the esMD System. Steps 3, and 4 address managing notifications. Managing notifications is outside of the functionality of esMD and that implementation will be unique to each HIH.
Authentication/Token Generation
- The HIH uses its clientId, client_secret, and Scope Header to authenticate using esMD's Authentication API.
- If the authentication operation is successful, the HIH receives an authentication (Auth) token that is used for further communication with esMD.
- This Auth token will be used in the Authorization header for subsequent GET requests.
- The clientId from the Auth token will be used to validate the identity of the HIH in subsequent steps of the notification retrieval process.
- Authentication tokens are valid for 30 minutes, and automatically expire 30 minutes after they are issued. HIHs must request a new authentication token once the current token expires.
- If authentication fails, an error is returned. Please refer to the Authentication API page for detailed information about the API.
2. Retrieve Notification SearchSet Bundles
- HIHs use a scheduler to send GET requests to the Notifications Retrieval API using the Esmd-FindListTransactionNotification resource.
- The GET request includes the Auth token (Authorization header) and the following search parameters:
| Search Parameter | Required /Optional | Description |
| transaction-status-type | Optional | The status of the transaction: |
| requesttype | Optional | The type of notification requested: |
| uniqueid | Optional | The unique identifier assigned by the HIH to each document within the Submission Set. Required only when transaction-status-type = processed. |
NOTE: If the transaction-status-type search parameter is not used, the system defaults to retrieving notifications which have a transaction-status-type of ready-to-download.
- esMD uses the clientId from the Auth token to validate the identity of the HIH such that access to the notifications are limited to the authorized HIH.
The following scenarios provide examples of how to use the Esmd-FindListTransactionNotification resource and Notifications Retrieval API to retrieve the notifications which are available for the HIH.
| Scenario | Query Syntax | Query Outcome (Success) |
| Download all notifications for an HIH that have never been downloaded. | /fhir/List?transaction-status-type=ready-to-download | Returns a SearchSet bundle based on the Esmd-FindBundleListNotifications resource which contains notification details for each available notification. |
| Redownload a specific notification using the unique Id. | /fhir/List?transaction-status-type=processed&uniqueid =1234 | Returns a SearchSet bundle based on the Esmd-FindBundleListNotifications resource which contains notification details related to the specified unique Id. |
| Download all Admin Error notifications that have never been downloaded. | /fhir/List?transaction-status-type=ready-to-download&requesttype=ADMIN_ERROR | Returns a SearchSet bundle based on the Esmd-FindBundleListNotifications resource which contains notification details for each available Admin Error notification. NOTE: Change the requesttype parameter to match the desired notification type. |
| Redownload a specific Admin Error notification using the unique Id. | /fhir/List?transaction-status-type=processed&uniqueid=1234&requesttype=ADMIN_ERROR | Returns a SearchSet bundle based on the Esmd-FindBundleListNotifications resource which contains notification details related to the Admin Error for the specified unique Id. NOTE: Change the requesttype parameter to match the desired notification type. |
The following validations and errors apply to GET requests which use the Notifications Retrieval API to retrieve notifications using the Esmd-FindBundleListNotifications resource.
| Validation Rule | Error Message | Comments |
| The uniqueid is mandatory for notification retrieval when the transaction-status-type = processed. | The uniqueid parameter is required when the transaction-status-type is processed. | The uniqueid parameter is used in other validations that limit access to authorized users. |
| A valid combination of the requesting HIH’s organizationid and uniqueid is required to redownload notifications. | The received UniqueId {1} is not associated with the requesting OrganizationId {0}. Correct UniqueId {1} and resubmit. | This validation ensures that the requesting HIH is authorized to download or redownload notifications. {0}is a dynamic placeholder for Organization Id and {1} is a dynamic placeholder for Unique Id. The Organization Id is taken from the clientId in the Auth token. |
| An active organization ID must be in the esMD database | Either HIH OID is invalid or agreement has expired. Correct and resubmit. | This validation is used to limit access to authorized users. |
- When the request passes all validations, esMD responds with a SearchSet bundle that contains a maximum of 20 Esmd-FindBundleListNotifications resources per bundle segment.
- The esMD System uses a pagination feature which returns a multiple segment SearchSet bundle that contains a maximum of 20 Esmd-FindBundleListNotifications resources per segment.
- If search results contain more than 20 Esmd-FindBundleListNotifications resources, then the pagination feature provides the next bundle segment of 20 Esmd-FindBundleListNotifications resources which have a "ready-to-download" status.
- This process repeats until all Esmd-FindBundleListNotifications resources are received by the HIH. When an HIH receives a bundle segment, the status of each Esmd-FindBundleListNotifications resource within that segment is updated to "processed".
- Updating the status identifies the Esmd-FindBundleListNotifications resource as being available to redownload. Please refer to the esMD Pagination Feature description for more details.
- When the request fails any of the validations, the esMD System returns an OperationOutcome response that contains a description of the errors.
Parse, Correlate, and Persist the Notifications
- After receiving the SearchSet bundle with transaction notifications, the HIH shall process the List resources within the bundle. Each List resource represents a notification for a specific transaction.
- The HIH must parse these notifications to:
- Extract the uniqueId of the transaction.
- Retrieve relevant List entries (if included) for each notification.
- Check the status of the transaction (e.g., completed, pending, or error).
- The HIH must correlate each notification with its corresponding submitted transaction based on the uniqueId field. This ensures that the status of each transaction is updated appropriately in the HIH system.
- The HIH system must map the uniqueId with the submitted transactions and verify whether the transaction is successful or if there are issues that need to be addressed (e.g., errors or rejections).
- All notifications must be persisted in the HIH system for future reference, auditing, and reconciliation.
- Storing notifications enables the HIH system to keep track of the transaction lifecycle, ensuring that no updates are missed, and providing a history of transaction statuses.
Error Management
- If a notification indicates an error (via OperationOutcome or another error code), the HIH system must handle the error appropriately. - The required actions may involve notifying relevant personnel, reprocessing the transaction, or taking corrective actions to ensure the transaction is completed successfully.