Medplum v4.0.0 Release

Medplum v4.0.0 is coming soon! Many of the new features in this release have already been rolled out incrementally, making the v4.0.0 designation more symbolic of the semantic versioning. We prioritize stability and backwards compatibility and work hard to minimize unnecessary changes. However, sometimes changes are necessary to keep the platform up-to-date and secure. This document outlines the key updates in v4.0.0, including important information for self-hosting deployments and TypeScript SDK users.

Self-Hosting Changes (Important)

Upgrading your self-hosted Medplum instance to v4.0.0 requires a critical two-step process involving data migrations. Attempting to upgrade directly to v4.0.0 without completing these steps will prevent the server from starting. These data migrations are essential for system stability and security.

Upgrade Process:

1. Upgrade to 3.3.0: First, upgrade your Medplum instance to version 3.3.0. Allow the deployment to fully complete before proceeding to the next step.

2. Run Data Migrations:

   • Log in as a super admin user.

   • Navigate to the super admin console.

   • Click the "Run Data Migrations" button.

   • Crucially, wait for the data migrations to complete. The duration of this step varies significantly depending on the size of your deployment:

     • Small deployments (e.g., under 1M resources): Typically completes in seconds.
     • Medium deployments (e.g., 1M+ resources): Can take minutes.
     • Large deployments (e.g., 10M+ resources): Can take hours.
     • Extra large deployments (e.g., 100M+ resources): Can take days.

     Several factors influence the migration time, including the number of resources, database size, and hardware resources. If you have any questions or concerns about the data migration process, especially for medium and large deployments, please contact your Medplum account manager before starting the upgrade.

3. Upgrade to 4.0.0: Once the data migrations are fully complete, you can proceed with the upgrade to version 4.0.0 as usual.

System Prerequisite Changes: The minimum required versions for several system components have been updated:

• Node.js: Node.js 20+ (previously Node 16)
• npm: npm 10+ (previously npm 7)
• PostgreSQL: PostgreSQL 13+ (previously Postgres 12)
• Redis: Redis 6+ (no change)

You must upgrade these components before or during the v4.0.0 upgrade. Failure to do so may result in instability or errors.

Other Self-Hosting Changes:

• Terminology Feature Flag Removal: The terminology feature flag has been removed. Ensure that the Rebuild ValueSets process has been run on your production environment before upgrading to v4.0.0. This is crucial for maintaining proper functionality of FHIR ValueSets.
• Database Proxy Endpoint Deprecation: The MedplumServerConfig.databaseProxyEndpoint setting is now deprecated. Instead of using this special-handling for RDS proxy endpoints, configure your database connection via database.host and database.ssl.require within Parameter Store.
• Legacy Chained Search Removal: The legacy chained search implementation has been removed. This feature has been off by default for a long time, so this change should not impact most deployments.

API Changes

The Medplum API remains backwards compatible. No changes are required for existing API integrations.

TypeScript SDK Changes

Several deprecated methods have been removed from the @medplum/core package. If your code uses any of the following methods, you will need to update it:

Old Method	Replacement/Alternative
matchesAccessPolicy	satisfiedAccessPolicy
searchValueSet	valueSetExpand
uploadMedia	createMedia
parseSearchUrl	parseSearchRequest
parseSearchDefinition	parseSearchRequest
parseCriteriaAsSearchRequest	parseSearchRequest
crawlResource	crawlTypedValue
crawlResourceAsync	crawlTypedValueAsync
ResourceVisitor	CrawlerVisitor
AsyncResourceVisitor	AsyncCrawlerVisitor
HL7 get and getAll	getSegment, getField, getComponent (context-dependent)
createAttachment (overloads)	Function signature changed, but function remains.
createBinary (overloads)	Function signature changed, but function remains.
createPdf (overloads)	Function signature changed, but function remains.

Additionally, the getReferenceString function now requires the input to have a reference string for Reference types or both resourceType and id for Resource types. This change improves type safety and prevents unexpected behavior when the input object lacks the necessary properties. Code using getReferenceString({}) will now result in a TypeScript error and must be updated.

Other Changes

• Filter eq Operator: The _filter search parameter with the eq operator now performs exact matching.
• Control Characters in Strings: Strings are now validated to ensure they do not contain control characters (Unicode character points below 32), except for horizontal tab, carriage return, and line feed, as per the FHIR R4 specification.

We strongly recommend carefully reviewing these changes and planning your upgrade accordingly. If you have any questions, please don't hesitate to reach out to the Medplum community or support channels.