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

Onboarding Process

esMD FHIR Onboarding Process Document

Introduction

The esMD FHIR onboarding process ensures that HIHs and Providers can securely interact with the esMD system for submitting and retrieving medical documentation. By following this step-by-step guide, your organization can integrate with the esMD FHIR REST APIs properly to ensure compliance, security, and reliability when exchanging healthcare data.

Prerequisites for Onboarding

Before beginning the onboarding process for esMD FHIR, ensure that the following prerequisites are met:

  1. Organizational Setup: The entity (HIH or Provider) must be registered with CMS and have all necessary credentials required to interact with the esMD System.
  2. Technical Capabilities: The entity (HIH or Provider) must have:
    • A FHIR client which has the ability to communicate with the esMD FHIR APIs.
    • A secure server infrastructure that supports OAuth 2.0 for authentication and authorization.
    • Support for the JSON format because esMD FHIR communicates exclusively using JSON.

Step-by-Step esMD FHIR Onboarding Process

Step 1: Request Access to esMD FHIR API UAT environment

Begin the onboarding process by requesting access to the esMD FHIR API UAT environment, a test environment that mirrors the esMD Production environment. The UAT environment allows HIHs, Providers, and RCs to integrate their systems with esMD and verify functionalities without affecting live data.

  • Action: Contact the esMD Service Desk for support via esMD Service Desk and request access to the esMD FHIR UAT environment. The esMD Service Desk will send the Onboarding form to get started with the process.
  • Expected Outcome: The CMS esMD Service Desk will provide access credentials, API documentation, and links to the UAT environment.

Note: Please reach out to esMD Service desk if you have any technical questions during this process.

Step 2: Obtain OAuth 2.0 Credentials

The esMD FHIR APIs are protected using OAuth 2.0, which requires clients to obtain an access token before making calls to the API.

  • Action: Register your client application with CMS and request OAuth 2.0 credentials (client ID and secret).
  • Documentation: Refer to the OAuth 2.0 documentation for the steps involved in the authorization flow.
  • Expected Outcome: The CMS esMD Service Desk will provide you with a client ID, client secret ID, and required access to the token endpoint for obtaining access tokens.

Step 3: IP Whitelisting

esMD FHIR uses IP address whitelisting for enhanced security. Whitelisting allows API access only from approved IP addresses.

  • Action: Submit the public IP addresses of your servers to the CMS esMD Service Desk for whitelisting in the Onboarding form.
  • Expected Outcome: The CMS esMD Service Desk confirms that the IP addresses have been added to the whitelist, thereby allowing your servers to interact with the esMD FHIR APIs.

Step 4: Configure the FHIR Client

After access to the esMD FHIR UAT environment and OAuth 2.0 credentials have been obtained, the FHIR client must be configured to connect with the esMD FHIR API.

  • Action: Configure your client and verify that it can:
    • Authenticate with the OAuth 2.0 token endpoint.
    • Send FHIR requests in JSON format.
    • Parse FHIR responses from esMD.
  • Configuration Check: Test basic connectivity by sending a request to a test FHIR API endpoint (e.g., /List) to ensure the configuration works.

Step 5: Set Up FHIR Resources and Profiles

The esMD system uses customized FHIR resources such as Esmd-BundleSubmission, Esmd-DocumentReference, Esmd-ListSubmissionSet and others to exchange medical documentation.

  • Action: Ensure that your system:
    • Uses the appropriate FHIR resources and profiles as defined in the esMD FHIR Implementation Guide.
    • Implements FHIR extensions where necessary. Details about supported extensions can be found in the extensions.html section of the esMD FHIR IG.
  • Documentation: Refer to the** esMD FHIR IG** for specific resource profiles and extension guidelines.

Step 6: Testing in the UAT Environment

The following test cases must be successfully validated in the esMD FHIR UAT environment. Testing is a critical step to ensure your system can properly communicate with the esMD System and handle various scenarios.

  • Test Cases:
    1. Submit a Bundle Transaction: Submit a sample bundle transaction with Esmd-DocumentReference, and Esmd-ListSubmissionSet resources to esMD.
    2. Retrieve Notifications: Query the esMD system for delivery or pickup notifications using the /List endpoint.
    3. Download Packages: Use the RC API to download packages from esMD.
    4. Send Notifications: Send notifications to esMD after successfully completing download transactions.
  • Action: Test all the Lines of Business that you are currently supporting in the Production environment. Test each scenario thoroughly and validate the responses from esMD. Ensure that all metadata, security tokens, and resource profiles are handled correctly. Refer to the Testing section of the esMD FHIR IG to obtain additional information regarding test scenarios.
  • Expected Outcome: Confirm to the esMD Service Desk that your system successfully handles esMD transactions in the esMD UAT environment.

Step 7: Verification and Database Assertions

During the UAT environment testing phase, verify that the transactions are recorded correctly in your internal systems and databases.

  • Action: Set up automated database assertions to validate that:
    • The submitted bundles are properly stored and tracked.
    • Notifications and transaction statuses are accurately reflected in the database.
  • Expected Outcome: All records in the database should match the transactions and notifications processed by esMD.

Step 8: Request Access to Production

Request access to the production esMD FHIR API after all required test scenarios and database operations are successfully validated in the esMD FHIR UAT environment.

  • Action: Contact the CMS esMD Service Desk to request access to the Production environment FHIR APIs. Update the Onboarding form to include the Production details. Provide your UAT testing results, ensure that your OAuth 2.0 credentials and IP address whitelist are set up for production.
  • Expected Outcome: The CMS esMD Service Desk grants production access which includes the necessary credentials and access points for live data exchanges.

Step 9: Go-Live and Monitoring

After receiving production access, your system is ready to go live with esMD's FHIR APIs.

  • Action: Begin submitting transactions and processing notifications in the live environment. Please do not submit test data in the Production environment.
  • Monitoring: Set up real-time alerts for potential issues like failed transactions, token expiration, or connectivity errors. Monitor the API responses and system performance closely during the initial days of production.
  • Expected Outcome: Seamless integration with the esMD production system using esMD's FHIR REST APIs which enable secure, real-time submission and retrieval of medical documentation.

Post-Go-Live Considerations

Be sure to take the following actions to ensure the best system performance.

  • Support and Maintenance: Regularly check for esMD FHIR updates and new features. Subscribe to CMS communications to receive notifications about maintenance windows or API updates.
  • Security Monitoring: Continuously monitor for unauthorized access and ensure that IP whitelists and OAuth 2.0 tokens are secure and properly configured.

IIf you have further questions or need technical support, feel free to contact the esMD Service Desk at esmd_support@cms.hhs.gov.