On this page:

1.1Changelog: 2021



A new feature
An existing feature has changed
A bug fix
A performance improvement
A security issue has been corrected

1.1.1Smile CDR 2021.05.R01 (Pre-Release)


Release Information

PRE-RELEASE This version of Smile CDR has not yet been released. It is included here to show upcoming features that have been completed and are committed for release.
HAPI FHIR Smile CDR 2021.05.R01 is based on HAPI FHIR 5.4.0, and includes all changes and fixes included in this version. Please see the HAPI FHIR ChangeLog for details about what has changed.


Added new Admin JSON endpoint /system-config, which prepares a ZIP file containing JVM information, a thread dump, the node module config, and node health statuses.

Support for accepting and processing HL7 v2.x VXU (Vaccine/Immuization) messages has been added.

Added support for Group Bulk export via the /Group/[id]/$export operation, which limited support for query parameters. The documentation indicate contains more details.

When using Smile CDR in Federated OAuth2 mode to connect to a third-party OpenID Connect provider, Smile CDR would fail to process the authorization if the third-party server used an ID Token signature algorithm other than RSA-256. This has been corrected.

1.1.2Smile CDR 2021.02.R02 (Odyssey)


Release Information

Released 2021-02-23
Codename Odyssey
HAPI FHIR Smile CDR 2021.02.R02 is based on HAPI FHIR 5.3.0, and includes all changes and fixes included in this version. Please see the HAPI FHIR ChangeLog for details about what has changed.

Upgrade Instructions

This version corrects an accidental dependency on JDK 11 that prevented Smile CDR 2021.02.R01 from starting correctly on JDK 8. This release is not necessary for users of JDK 11.


1.1.3Smile CDR 2021.02.R01 (Odyssey)


Release Information

Released 2021-02-18
Codename Odyssey
HAPI FHIR Smile CDR 2021.02.R01 is based on HAPI FHIR 5.3.0, and includes all changes and fixes included in this version. Please see the HAPI FHIR ChangeLog for details about what has changed.

Upgrade Instructions

This release has some breaking changes that are worth knowing about.

  • EMPI module has been replaced by the MDM module
  • Hibernate Search (the backing engine for all fulltext functions like lastN/Terminology Expansion/Fulltext Search) has been upgraded, which causes a full reindex to be required..


The EMPI module was capable of making golden record links for Patients and Practitioners. With the change to MDM (Master Data Management), it is now possible to do golden record linking for any resource that contains an identifier field. This is almost all clinical resources. For example, you can now perform matching on Organizations or Medications. Unfortunately EMPI and MDM modules are not fully compatible. To this end, we have fully deprecated the EMPI module. It no longer does anything, but still exists as a placeholder for configuration for existing installations.

Installations currently making use of EMPI should add a new module of type MDM. It bears nearly all the exact same configuration options as EMPI, with a notable exception. The EMPI Rule definition section has been changed slightly. Specifically, the JSON field now requires you to define which resource types you intend to perform matching on. This is done via a top-level key in the JSON, which can be set as follows:

   "mdmTypes": [

This informs the module which resource types are of interest for MDM purposes.

This changes also removes the usage of the Person resource as a linking object. As Person is unsuitable for linking resource types such as Organization or Medication, the links instead are held in internal tables, and can be queried with MDM Operations.

Hibernate Search Upgrade

The engine in HAPI-FHIR which handles fulltext functionality has been upgraded a major version. This change necessitates a full reindex of data for any Smile CDR installations which make use of the following features:

  • lastN Operation
  • Fulltext/Content search
  • Terminology Expansion

To get these features functional again, a full reindex is required. To perform this, you can execute the $mark-all-resources-for-reindexing operation.

POST http://example.com:8000/$mark-all-resources-for-reindexing

The changes vary depending on if you are using Lucene or Elasticsearch as the backend.


The recommended version of Elasticsearch is now 7.10. 6.X clusters are no longer actively supported.

A new property has been added to support https Elasticsearch clusters. This is set via the Protocol property. Elasticsearch is now the only backend provider supported when running SmileCDR in a cluster with more than one node.


Lucene is no longer supported while running Smile CDR in a cluster with more than one node. Lucene continues to be a viable option when operating on a single node.


When converting HL7 v2.x messages via the HL7 v2.x Listening Endpoint module, if MessageHeader creation is enabled, the MSH-10 Control ID value will now be copied to an extension in the generated MessageHeader resource.

A new validation mode called Repository Validation has been added, as well as a new ability to use a FHIR Storage (RDBMS) module specifically to provide validation support. This significantly improves the ability to require conformance to specific IGs in FHIR CDRs.

Refactoring of the SmileCDR Enterprise Master Patient Index solution to a Master Data Management solution to accommodate corresponding changes in HAPI FHIR EMPI. The following changes were made:

  • Module name was changed from cdr-persistence-empi to cdr-persistence-mdm
  • EMPI match on the Patient / Provider resources was changed to use new MDM semantic
  • New MDM match ($mdm-match) operation was introduced.
  • EMPI operations were renamed to MDM. E.g. $empi-update-link to $mdm-update-link, $empi-merge-persons to $mdm-merge-golden-resources, etc.
  • RESTful Service Path URLs path prefix changed from /empi to /mdm
  • EMPI permission category, while still in existence, is deprecated
  • Permission category for MDM was added

Added new OAuth2Exceptions API within the SMART on FHIR Outbound Security JavaScript execution environment to support returning failure codes other than HTTP 500 Internal Server Error. Returning HTTP 401 Unauthorized and HTTP 403 Forbidden are now also supported.

An example user revocation page skin has been added to the Demo Skin for the SMART Outbound Security module.

The SMART Client Revocation Page will now revoke active access and refresh token, as well as forgetting any previously approved scopes.

Access tokens generated by the SMART Outbound Security module will now include a claim called scope that contains a list of approved scopes associated with the token.

As IT Admin, I need ability to allow SmileCDR clients automatically receive their OIC secrets during creation process

Added new CDS-Hooks module that implements Version 1.1 of the CDS-Hooks specification.

Support has been added for the launch (EHR Launch Context) scope in the SMART Outbound Security module.

Added new functionality to the Realtime Export module to support retaining all historical versions of resources. This can be enabled by setting retainAllHistory to true in the JSON configuration of Realtime Export.

Added two auto-prefetch features to CDS-Hooks: auto prefetch from FHIR endpoint specified in request and auto-prefetch from FHIR Storage module.

Two improvements have been made to the Smile CDR .well-known discovery docs: * The OIDC discovery doc now includes the mandatory subject_types_supported element, which was previously missing * Support has been added for the SMART discovery endpoint, which supercedes the extensions added to the FHIR CapabilityStatement (although these have not been removed

Improved Channel Import to be able to handle plaintext, CSV, and non-FHIR JSON payloads. See the Documentation for more details about how to process incoming messages.

Added new variable ${client_attestation_accepted} that is now available to the login and approve skins that indicates whether or not that client has accepted the attestation to the policy.

Added support for the $evaluate-measure Operation as part of adding CQL support.

Two new variables ${client_scopes} and ${client_auto_grant_scopes} that are now available to the login skin that contain lists of oidc client scopes and auto-grant scopes respectively.

When using the Javascript Execution Environment Fhir object to access a FHIR Storage module that is configured to run in Request Tenant Selection Mode, a new method has been added to the JS API that allows tenant selection.

Mongo search default and maximum page sizes are now configurable. Also added Mongo support for searching with _offset.

The 2020.11.R01 release of Smile CDR introduced a new optimized SQL generator for RDBMS repositories. This new system was disabled by default in 2020.11 but has been enabled by default in 2021.02.R01

With a new version of HAPI comes an upgrade from Hibernate Search 5 to Hibernate Search 6. Anybody using fulltext search, terminology expansion, or the lastN operation will need to reindex all their data, as field formats have changed between versions. This change requires those using Elasticsearch as a backend to upgrade their Elasticsearch clusters to 7.10. Additionally, HTTPS connections to Elasticsearch clusters are now supported via the protocol property on the Elasticsearch Provider. WARNING: If you use Lucene in any capacity (fulltext search, terminology expansion, lastN), you must empty out your lucene storage directory before upgrading, as Lucene's index storage format has changed.

The instructions in the Smile CDR tutorial for launching the Growth Chart app have been replaced with new instructions that leverage the latest version of the app launched directly from the source code instead of using an old version that is bundled into Smile CDR.

When using the SMART Outbound Security module, the onTokenGenerating callback script was not called for authentications using the Client Credentials Grant type. This has been corrected.

When using the JSON API, searching the transaction log by transaction ID failed with a ClassCastException. This has been corrected.

With new modules accepting external input into kafka channels, Smile CDR now drops messages that fail deserialization (poison pills). Previously they would block the consumers as they were stuck on the poisoned offset.

When a client is configured to be allowed a SMART 'star scope' such as patient/*.read, it should be automatically permitted to request an equivalent but narrower scope such as patient/Observation.read. A regression in 2020.11 meant that the approval was allowed, but the narrower scope couldn't actually be used in any API calls. This has been corrected.

The onTokenGenerating(..) callback previously provided a mechanism to access approved scopes, but it was not populated and was therefore not usable. This has been corrected, and this function can now access and modify the list of approved scopes.

Fixed a bug that would cause message receive failure in Channel Import module when using ActiveMQ as a broker.

Smile CDR's JavaScript Execution Environment's FHIR Model API now supports extensions on primitive types using an underscore prefix (i.e. _).

A number of issues were found to occur when migrating Smile CDR databases with flyway disabled. These issues are now fixed.

When trying to retrieve a list of users from JSON Admin console, an error was returned if no sort criteria was selected. This has been fixed.

Tab is now supported as a delimiter by ETL Importer.

Addressed the following CVE reports via the removal of hibernate search 5, and related Elasticsearch libraries:

When Suppress Error Details was enabled, OIDC Client Credentials grants did not suppress the fact that an invalid client ID was truly unknown, allowing a malicious user to search for valid client IDs. This has been corrected.

1.1.4Smile CDR 2020.11.R02 (Numbat)


Release Information

Released 2021-01-19
Codename Numbat
HAPI FHIR Smile CDR 2020.11.R02 is based on HAPI FHIR 5.2.0, and includes all changes and fixes included in this version. Please see the HAPI FHIR ChangeLog for details about what has changed.

Upgrade Instructions

This version contains a backported fix for a bug with the --dry-run flag in the Smile util database migration command. There are no special upgrade instructions