Skip to main content

· 3 min read
Cody Ebberson

Today, we received a thoughtful email from an engineering leader who installed Medplum for the first time:

Cody,

Medplum looks like really cool and I'd like to play with for a digital health company I am helping out.

When I tried to install it I got the following problems:

npm WARN deprecated trim@0.0.1: Use String.prototype.trim() instead
npm WARN deprecated stable@0.1.8: Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#browser_compatibility
npm WARN deprecated sourcemap-codec@1.4.8: Please use @jridgewell/sourcemap-codec instead
npm WARN deprecated @npmcli/move-file@2.0.1: This functionality has been moved to @npmcli/fs
npm WARN deprecated rollup-plugin-terser@7.0.2: This package has been deprecated and is no longer maintained. Please use @rollup/plugin-terser

added 3083 packages, and audited 3134 packages in 1m

410 packages are looking for funding
run `npm fund` for details

22 vulnerabilities (9 moderate, 13 high)

To address issues that do not require attention, run:
npm audit fix

Some issues need review, and may require choosing
a different dependency.

Run `npm audit` for details.

Have you updated any of these? Please let me know what to do.

Our Response

This is a great question!

By engineering policy, we upgrade dependencies at minimum once per month. In practice, we upgrade dependencies roughly once per week. We are strong believers in staying current, and providing Medplum developers the best version of all tools.

Our last dependencies upgrade was just yesterday, where we upgraded all direct dependencies to latest stable/release versions: https://github.com/medplum/medplum/pull/1789

The dependencies listed in your email are transitive / indirect dependencies. You can use the "npm list" command to see the dependency tree for any given package.

  • trim and stable are installed indirectly for Docusaurus (by Meta)
  • sourcemap-codec and rollup-plugin-terser are installed indirectly for Workbox (by Google)
  • @npmcli/move-file is installed indirectly for npm-check-updates (ironically, the tool that we use to upgrade dependencies)

The dependency warnings, and the output of npm audit in general, is sadly quite flawed. People much smarter than me have written at length about this. For example, I recommend this essay by Dan Abramov, lead engineer on React at Meta, titled npm audit: Broken by Design.

We continue to take dependency management very seriously, and use automation where possible:

  • GitHub Dependabot integration is enabled with continuous monitoring and alerts to the Medplum engineering team
  • CodeQL scans every PR
  • SonarCloud scans every PR
  • Snyk scans every Docker image

I'd be happy to discuss further if you have any questions, or if you have any suggestions on how we can do better. Join our Discord!

· 4 min read
Reshma Khilnani

This guide is for customers who are self-hosting Medplum, and this post assumes that your installation was complete and successful. We will refer to your base installation as $domainName, and this refers to the domain on which the Medplum app is running, for example on hosted Medplum the domain is app.medplum.com.

Now that the initial installation is complete, it's essential to verify that your environment is functioning correctly. In this article, we'll walk you through the necessary steps to ensure your Medplum installation is working.

The initial user created after you set up your account is referred to in this article as a super admin.

Change Default Password

The first step after installation is to change the default password for your super admin account. Using the default password poses a security risk, as it's easily accessible to unauthorized users. To change the default password, log in to your instance of the Medplum App using the default credentials provided and navigate to the "Security" settings on the left sidebar ($domainName/security will be the URL). Update your password with a strong, unique combination of letters, numbers, and special characters.

Note your password and logout by clicking on the Sign Out item on the top right menu.

Create a Medplum Project

A Medplum Project serves as a container for your FHIR resources.

To create a new project, follow these steps:

  • Navigate to the "Register" page in your Medplum app at $domainName/register.
  • Fill out your name and email and create a password.
  • Click the "Create account" button.
  • Provide a name and description for your project.
  • Click "Save" to create the project.

You will create a new (blank) Medplum project and be logged in.

Invite a New User to the Project

Now that you are logged into your new project. Inviting a new user to your project is a great way to confirm that your email notifications are set up and install is working. To send an invitation:

  • Click on the Admin -> Project item on your left navigation panel or visit $domainName/admin/project.
  • Go to the "Users" tab within the project.
  • Click the "Invite new user" link.
  • Enter the user's email address, name and (optional) Access Policy. e. Click "Invite."

The new user should receive an email invitation to join the project. This process confirms that your system emails are functioning correctly.

You can see a visual on these steps here.

tip

There is a Medplum Project that is set up with the base installation called Super Admin. Members of this project will have super admin privileges and will be able to see all resources in all Projects. Log in with your super admin credentials and invite other users to the super admin projects as needed.

Create a FHIR Patient Resource

To test the core functionality of your Medplum installation, create a FHIR Patient resource within your project:

  • Navigate to the "Patient Resources" page in your project on the left nav bar or by going to $domainName/Patient.
  • Click "New" on top, or navigate to $domainName/Patient/new.
  • Fill in the required fields for the patient.
  • Click "Save" to create the FHIR Patient resource.

Create, Deploy, and Execute a Medplum Bot

tip

Bots are not on by default for Medplum projects, to enable them login as super admin and navigate to the Projects page found here $domainName/Patient/new. Select the project you want to enable Bots for and add the following flag to the Project object:

"features": [
"bots"
]

Log out with your super admin account, and login with your user account.

To confirm that AWS Lambda is correctly configured, create, deploy, and execute a Medplum Bot:

  • Go to the "Bots" tab in your project in the Admin -> Project section or navigate to this url $domainName/admin/bots.
  • Click "Create new bot" and provide the necessary details.
  • Click "Create Bot" to create the bot.
  • Navigate to the Bot on the $domainName/Bot page, click on the editor and save the boiler plate code.
  • Deploy the bot by clicking "Deploy" in the editor window.
  • Once the bot is deployed, click "Execute" to run it.

If the bot executes successfully, AWS Lambda is correctly configured in your environment.

Check Log Files

Inspecting log files is crucial for identifying any errors or issues in your Medplum installation. Locate the log files in AWS Cloudwatch and confirm that you see AuditEvent resources appearing in the logs.

After following these steps, you can be confident that your Medplum environment is up and running. Remember to periodically check for updates and patches to ensure your system remains secure and efficient.

· 3 min read
Reshma Khilnani

Data privacy, locality, governance and compliance are huge issues in healthcare, and that's why we at Medplum support self-hosting. For those running on AWS, we use Aurora RDS, which supports auto-scaling. A common question we get is - how big is my database going to be?

tip

Medplum offers a hosted offering as well as self-hosted. Instructions to register can be found in our docs.

Say for example, you have 1M active patients annually - how does that translate to database size?

Unfortunately, there is no straightforward answer to that question, but the right way to think about it is to make a FHIR resource count estimate, per patient, annually. Applications with a lot of messaging and observation data are generally more resource intensive, while those that have visit notes and prescriptions are generally less resource intensive.

Here's an example of a resource projection.

Resource TypeCount per PatientTotal Count (M)Avg. Size / Resource (kb)Avg. History LengthTotal Storage (GB)
Patients__1510.052.5
Encounters101022.042.0
Coverage1122.04.2
DiagnosticReport101022.042.0
Observation151522.062.9
MedicationRequest101022.042.0
Media151522.062.9

Average History Length (column 5) refers to the number of times the resource is edited, as changes are tracked, historical data will increase storage size.

To calculate the total storage, we use an "overhead factor" (representing metadata, indexes, etc) of 10%. The following formula shows how to estimate column 6 - Total Storage

totalStorage = resourceCount * patientTotal * avgSize * avgHistoryLength / (1024 * 1024) * (1 + overheadFactor)

In this example, summing the Total Storage column, you get an estimated total of 308.4 GB of data per year.

Hopefully, this lightweight exercise can help you and your organization get a sense of your database needs today and over time.

· 2 min read
Reshma Khilnani

We are excited to hear about the release of Fast Healthcare Interoperability Resources (FHIR) R5, the latest version of the healthcare data interoperability standard. This new version builds on the previous versions of FHIR and incorporates new features and improvements to further support healthcare data exchange and interoperability.

FHIR R5 includes enhancements to the FHIR specification, including additional resources, improved support for clinical workflows, and improved alignment with other healthcare data standards. The new version also includes updates to the FHIR conformance framework, which helps ensure that FHIR implementations are interoperable with each other.

In the future, we will upgrade our service to support FHIR R5 side by side with R4. This includes ensuring that our solutions comply with the latest FHIR R5 specifications and testing our products for interoperability with other FHIR R5-compliant systems.

We will do this while maintaining our support for FHIR R4 - which most of our customers rely on today. We will use our Bot framework, TypeScript SDK and validation tools to help our customers implement the version of the spec that best suits their business needs.

We are excited about the potential of FHIR R5 to improve interoperability and enable better healthcare outcomes for patients. We continue to closely monitor industry adoption and compliance requirements and will strive to provide our customers with the most up-to-date solutions to meet their interoperability needs.

Thank you for your continued support, and we look forward to sharing more updates with you soon. If you are interested in updates related to FHIR R5, please reach out at hello@medplum.com.

· 2 min read
Reshma Khilnani

Patient deduplication is a tough problem, and there are many approaches to implementing a deduplication program. We provide this guide and sample code as a resource to teams who want to run a continuous deduplication program that is powered by automation and highly auditable.

There are three elements that we see playing a big role in deduplication:

  1. New patients evaluated for duplication at time of creation (event driven)
  2. Disciplined maintenance of identifiers from different systems
  3. Maintaining your de-duplication policy as code

Here is a 5 minute tutorial video on deduplication that summarizes the content of this post.

Event Driven Deduplication

In Medplum, by hooking a Subscription to the Patient resource, you can subscribe to the creation of new Patient. This is powerful because it allows you to check each new patient against the existing patient base and flag duplicates in real time.

We suggest making a Bot that listens for new patients and every time a new patient is created evaluation whether they can be merged with an existing patient, creating a duplication risk score or flagging for manual review.

A sample (skeleton) deduplication bot can be found in the Medplum Demo Bot repository.

Maintaining Identifiers

Many systems issue patient identifiers, like payors (e.g. United Healthcare), pharmacy and medication systems (e.g. DoseSpot) and even payment providers like Stripe. FHIR support maintaining multiple identifiers from different systems. If you maintain records with patient identifiers from different systems, this can be the basis for detecting duplicates with high accuracy.

The sample deduplication bot test shows a patient with multiple identifiers for reference.

Policy as Code

The stakes are high for deduplication. A false merge can cause treatment errors, incorrect data disclosure and more. Having an auditable policy as code, test coverage, source control and a system with robust audit history is an excellent tool for having that high fidelity deduplication process that is required for great patient care.

Resources

· 3 min read
Reshma Khilnani

Great workflow apps are core for us at Medplum, and we provide tools to build highly ergonomic asynchronous task tracking systems providers. Some examples of task management apps in the medical context are apps that:

  • Review and approve lab reports
  • Approve or reject medication refill requests
  • Instantiate custom care plans for a patient

Medical systems in general and FHIR in specific have robust workflow resources to create, track and implement workflows. Tasks and ServiceRequests are the most common workflow resources for asynchronous work.

Setting up Queues or Worklists

The core or a workflow app is a queue or sometimes called a worklist. This is exactly what it sounds like - a list of tracking tasks that represent the work to be done and it's current status. The FHIR Tasks as a group are often used to represent a queue. Tasks can be created programmatically, or via Questionnaire and Bot.

When populating the Task resource, it can be useful to populate the following fields:

  • Task.focus - this is what the task is about, for example you can link it to a DiagnosticReport, MedicationRequest or CarePlan
  • Task.businessStatus - this can be used for custom workflow, where you can set your own statuses that fit your workflow
  • Task.code - this can be useful to cue the Task specific user interface (below), example might be "Lab Review"
  • Task.executionPeriod - this can be useful for productivity tracking
  • Task.for - this is usually a link to the Patient

Once you have created some Tasks you can view Tasks in the Medplum App.

Once you have confirmed that tasks are formed the way you want them to be, you can embed a search control in your Task tracking application, there are examples in the sample application.

Like in the Medplum App, it is recommended that you have one page in your app that supports permalinking to a specific task search as it is useful for collaboration, integrating into chat apps and other common workflow tooling scenarios.

Task specific User interface

For each task, you will want to show a user interface that gives the user some context on how to resolve or take action on that task. This is very workflow dependent so customizability is important. You can see a video (70 seconds) on this topic here.

The exact components of the Task specific user interface are often driven by Task.focus or Task.code.

Dashboards

Turnaround times and productivity tracking are crucial for observing the health of your task-based workflow. Assuming you populate the timestamps correctly in the resources, it is straightforward to calculate how many work hours a certain task takes, or the turnaround time.

Here is an example of a timestamp calculation:

  • Turnaround Time for a Task: Task.executionPeriod.end - Task.authoredTime
  • Work hours for a task: Task.executionPeriod.end - Task.executionPeriod.start

Using these calculations, it is straightforward to make a dashboard that gives a very clear picture into the status and health of your queues. In this example below, each of the graphs is a representation of a Task search, with results bucketed by turnaround time or by work hours.

TAT Dashboard Sample

· One min read
Cody Ebberson

We're hiring! Check out the new Careers page.

Medplum was founded by industry veterans, experienced founders with a clear vision of how to tackle healthcare's biggest challenges. We are committed to maintaining a tight team of elite engineers. Medplum is open source and building in public. We use modern tools and follow industry best practices.

If that sounds interesting, please email careers@medplum.com with your resume and a short introduction. We're excited to meet you.

· 2 min read
Reshma Khilnani

2022 in Review

As we close out 2022, the Medplum team would love to thank our customers and community for joining us on this journey.

We wanted to highlight a few memorable moments and reflect on all that happened during the year. It was a lot of fun, and huge thank you to the team who pushed so hard to make all these things happen.

Open sourced our repository

✅ Achieved SOC2 Type 2 and HIPAA certification

✅ First Enterprise customer went live!

✅ Launched our Youtube Channel and Discord Community

✅ Had our YC S22 Demo Day

✅ Launched our sample patient portal Foo Medical, video, source code

CLIA/CAP Certified

✅ Launched on Hacker News

✅ 500+ Github Stars

✅ Published our Roadmap

Instead of going on about what the new year has to hold, I'll share a peek into the future in the most Medplum way possible - i.e. in excruciating technical detail. Please enjoy and feedback always welcome.

Product20222023
IntegrationChange logRoadmap
QuestionnairesChange logRoadmap
SchedulingChange logRoadmap
CommunicationsChange logRoadmap
Care PlansChange logRoadmap
MedicationsChange logRoadmap
ChartingChange logRoadmap
Billing/PaymentsChange logRoadmap
AuthChange logRoadmap
FHIR DatastoreChange logRoadmap
SubscriptionsChange logRoadmap
ReactChange logRoadmap
SearchChange logRoadmap
Self-HostingChange logRoadmap
ComplianceChange logRoadmap
Audit/LoggingChange logRoadmap

· 5 min read
Reshma Khilnani

Composability venn diagram

Composability is the ability of different components or systems to be combined and work together seamlessly. This allows developers to build on existing open source software to create new applications and solutions that meet their specific needs.

As a software engineer, when a system you are using supports enables composability you have this visceral feeling that you are moving fast, and you feel powerful. Ideally, you also feel a sense of confidence and safety, that the application you are building is going to work as expected.

Composability is so important to us here at Medplum that we have used the three biggest tools in our toolbox to enable it for healthcare applications and those are:

  • Standards
  • Open source software
  • API-First design

Standards

The needs of a healthcare organization are in constant flux. Some days the patient experience is top of mind, other days the provider workflow needs work, and yet other days the needs of payors or partners is crucial.

However, in a organization with active patient flow, upgrading tooling and technology to address needs can be a challenge.

Providers have a stack that looks something like this - with a mix of commercially available tools working together with home grown software. There is often a lively discussion on which tools to pick for which purpose. The diagram below shows (as an example) applications that are written in house as purple, and the ones that are bought in grey - but there are many possible configurations.

Abstract provider stack

In practice, a stack might look like the following, with different SaaS, on-premise, or other tools working together to enable a service. Sometimes teams within a company coalesce around a tool, and an information silo within an organization can form. We have even seen some groups where it is a person's job to move data from one tool to another.

Specific provider stack

After many years of doing implementations like these, and getting these systems to work together, we at Medplum have formed a strong opinion on how to get your stack to evolve to meet your needs and we want to emphasize one word: standards.

Getting your application to implement the functionality you need will be so much easier if you have a standards based approach. An example of a standards enabled stack might look:

Standard provider stack

Here are 5 specific ways standards can help your stack evolve.

StandardWhat is it?Enables what?
OpenIDIdentity provider standardBringing on new identity providers when you want/need them
SCIMIdentity data standardPortable identities, replace your auth
FHIRClinical data standardIntegrating with health systems, payors
UMLSOntology for medications, medical conditions and moreAdding/replacing ePrescribe, billing providers, computing CMS queries, HEDIS
OpenAPI(REST)Standard to describe REST APIAllow others to consume your product/service as API

Open Source Software

Open source is critical in enabling composability, and that is one of the top reasons why developers love it so much. When developing an application, it is common to get unexpected behavior and get stuck. Sometimes something that sounds so simple, like the way a regex is parsed or the way a dates are compared can cause chaos in or completely block an implementation.

Open source, providing line by line access can greatly speed debugging, and can help users get past blockers that would have caused enormous delays in the past. Similarly, understanding with specificity how something is implemented is critical to extending it.

At Medplum, we care a great deal about having our open source enable composability. Well organized and tested code, solid abstractions, with great issue management is what we strive for.

API First Design

Many, many applications have an API, but only allow limited functions to be accessed via the API. This limits the composability of said systems substantially because by definition some of the functions must be done manually in the app.

In healthcare, the most common pattern where you see the limitations of existing platforms is workflow. For example, there is a sophisticated workflow app with data capture, business logic and validation that triggers notifications. Inevitably, when the workflow needs to be amended and many organizations work around this by having humans do data entry and processing, or make an alternate datastore and copy and manipulate the data. This feels slow, is costly and error prone.

At Medplum we take great care to make nearly everything available via well-documented API. As needs change, if the workflow abstractions (data, users, business logic, notifications) are in place they can be altered to evolve with the changing needs of healthcare.

In Conclusion

We aim to enable extreme composability for healthcare apps - and we use standards, open source and API-first design to do it. We welcome your feedback via issues or discussions.

· 3 min read
Reshma Khilnani

What is ONC Certification?

ONC Certification graphic

The Office of the National Coordinator for Health Information Technology (ONC) certification is a program that ensures that electronic health records (EHRs) meet certain standards for interoperability and security. It is designed to help healthcare providers adopt and use EHRs more effectively, and to promote the widespread adoption of EHRs as a means of improving the quality and efficiency of healthcare. To be certified, an EHR must meet a set of standards and criteria that have been developed by the ONC in collaboration with other organizations and stakeholders in the healthcare industry. These standards cover a range of areas, including the exchange of health information(g10), patient access to their own health data (also g10), and the protection of sensitive health information(d1,d13,g12). By achieving ONC certification, EHRs can demonstrate that they meet these standards and are ready for use in a wide variety of healthcare settings.

From a technical perspective - the most important thing to understand about the certification is that it requires FHIR API access - for patients and practitioners.

The Benefits of Certification

The benefits of certification vary by the type of provider. The following are very tangible benefits to getting certified.

  • For those with a large CMS (Medicare, Medicaid) population, getting reimbursement at the optimal rate will require certification.
  • Supporting CMS Queries will streamline contracting with payors (other than CMS), who want insight into "quality metrics" and technical touch points.

Beyond the above there, certified systems do gain a benefit in contracting and partnerships because partners know they have a streamlined interface to exchange data.

The Certification Process

The certification process has is driven by examination, there are certification vendors, e.g. Drummond, who proctor vendors through a walk-through of developer products according to a specific script.

Some of the criteria, for example g10 have standardized test harness, like Inferno or Cypress, that verifies that APIs are working as expected.

This video shows an example of the Inferno tool in practice. The proctored exam will have developers walk through the test session like this one, and the output will be verified by the proctor.

Running the Inferno test harness as shown in the video will be meat of what goes on during the certification examination for that g10 criteria.

The Developer Perspective

For developers, it is important to understand that there are two types of criteria.

  • Self attested criteria: these will not be tested by the examiner, instead organizations will have to self-attest that the functionality is available and provide some documentation.
  • Live tested criteria: these will be tested by an examiner, in accordance with the scripts.

You do not need to certify for all criteria at once, you can batch them up and pursue subsets.

Prepare for frequent requirements changes. The regulations and requirements do change frequently, with amendments coming out each year. If you are on point to deliver a system with a certain compliance profile, you can expect to need to adapt to the changing regulations and requirements.

There are "spot" solutions for many specific functionality types, for example ePrescribe, custom reporting or vaccine registry transmission, which can be composed together to support many configurations.

However, at the core of your system, we recommend a highly programmable, well-documented. FHIR enabled infrastructure like Medplum as a base. This will give you the infrastructure needed to orchestrate the ever-changing suite of tools needed to comply with the required regs.