Cerner DSTU2 to FHIR R4 Migration: What Changed After December 2025

Posted in EHR/EMR

Oracle Health ended support for the FHIR DSTU2 APIs on Cerner Millennium on December 1, 2025. Applications using these APIs now need to move to FHIR R4 (4.0.1), the supported version on Millennium. The migration involves updating API connections, resource mappings, and application permissions. R4 also provides access to additional clinical data and supports more specific access controls. This guide explains how to move an existing Cerner application from DSTU2 to R4 on the same Millennium tenant. It covers the changes developers need to make, the resources that need updating, and the steps involved in testing the application.

Why Did Cerner DSTU2 Stop Working?

Oracle Health announced the retirement of DSTU2 in June 2024 and provided an 18-month transition period. The company ended support for the DSTU2 FHIR APIs on December 1, 2025.

The announcement on the Oracle Health developer forum included the following dates.

Milestone	Date
Deprecation announced; no further DSTU2 enhancements	June 3, 2024
Last day to register a new DSTU2 application	September 3, 2025
DSTU2 APIs deprecated; R4 only	December 1, 2025
Both versions supported in parallel	June 3, 2024 to December 1, 2025

Oracle Health had been moving FHIR API traffic from DSTU2 to R4 since January 2023. At the time of the announcement, more than 90% of FHIR traffic on its service was already using R4.

The change also allowed Oracle to focus on newer FHIR standards, including the development of FHIR R6.

The Millennium Platform API documentation now identifies R4 as the replacement for DSTU2. Applications need to use the R4 endpoints because extended DSTU2 support and an R4 compatibility layer are unavailable.

DSTU2 to R4 API Changes

FHIR R4 uses the same REST API approach as DSTU2. Applications can continue requesting healthcare data through API calls. The first change is the API endpoint. Each application call must be directed to the R4 tenant endpoint.

Developers also need to update how the application reads and processes the information returned by the API. There are four main areas to review:

1. Resource names

FHIR stores healthcare information in resources. Each resource represents a type of information, such as a patient record, medication, or clinical observation. Some resource names and structures changed in R4.

For example: 

MedicationOrder became MedicationRequest. Information previously available through DSTU2 MedicationStatement is expected to be served through MedicationRequest on R4.

Applications that use these resources need to update their API requests and the code that processes medication information.

2. Profiles

FHIR profiles define the structure and requirements of clinical data. They specify which fields a resource uses and the values those fields can contain. Cerner DSTU2 used Argonaut profiles. R4 uses US Core profiles.

As a result, some resources have different field names, required elements, and value sets. These changes can apply even when the resource name remains the same. Developers need to review each resource against the corresponding US Core profile.

3. Data types and references

R4 has more specific requirements for certain data fields and references between resources.

For example: 

A feild that previously accepted a single code value may now require a coding or CodeCncept. These data types organize cinicla codes and their meanings in a standard format. 

4. New clinical data

R4 provides access to more clinical information. This includes Clinical Notes through DocumentReference and diagnostic report, provenance information, and additional vital-sign profiles such as pulse oximetry.

Provenance identifies the source of a clinical record. DocumentReference helps applications find and access clinical documents. Teams can review these additional resources during migration and include the information that supports their application’s workflows.

Once the endpoint and resource changes are complete, each resource should be validated against its R4 US Core profile.

Which Resources Need Remapping?

FHIR resources provide a standard way for healthcare applications to exchange clinical information. When moving to R4, developers need to review every resource the application currently uses through DSTU2.

Each DSTU2 resource type must be supported on the corresponding R4 server. The mapping also needs to follow the updated US Core profiles.

Some resources need minor field changes. Others require more work because their names, structures, or accepted values have changed.

HL7 provides cross-version mapping guidance. The following table shows the main resources used in Cerner applications and the estimated effort required.

DSTU2 (Argonaut) profile	R4 (US Core) profile	Mapping effort
Patient	US Core Patient	Low. Field-level changes only
AllergyIntolerance	US Core AllergyIntolerance	Low
Condition	US Core Condition	Low to medium. Category and clinical status value sets changed
Encounter (Cerner DSTU2 resource; no Argonaut profile)	US Core Encounter	Medium. Class moved from a code to a Coding
Observation (results)	US Core Laboratory Result Observation	Medium. Already a separate profile from vital signs in Argonaut; status value set expanded
Observation (vital signs)	US Core Vital Signs profiles	Medium. Separate profiles per vital, including new Pulse Oximetry
Medication Order	US Core MedicationRequest	High. Resource renamed; dosage and dispense structures reorganized
Medication Statement	No US Core profile in R4; map to MedicationRequest	High. Data must be folded into MedicationRequest
Diagnostic Report	US Core DiagnosticReport (Lab, Note)	Medium to high. Result references and effective date handling changed
Care Plan	US Core CarePlan	High. Activity structure and status values changed; care team data held in DSTU2 CarePlan must move to the R4 CareTeam source
Procedure	US Core Procedure	Low to medium
Immunization	US Core Immunization	Low
Device	US Core Implantable Device	Medium. Scope narrowed to implantables
Not in DSTU2	US Core Provenance	New. Required by US Core on R4
Document Reference (Argonaut)	US Core DocumentReference (Clinical Notes)	Low to medium. Resource existed in DSTU2; R4 adds more note categories and the Diagnostic Report note profile

Resource IDs need verification

Every FHIR resource has an identifier that an application uses to find it. HL7 recommends keeping these IDs consistent across versions. However, the IDs may change during migration. Applications should check stored DSTU2 IDs against the corresponding R4 records.

Existing Clinical Data Should Remain Available

The information available through DSTU2 should also be accessible through R4. Some fields may have a different structure, and R4 may provide additional information.

Medication Data Needs Updated Handling

MedicationStatement may be deprecated on R4, with its data mapped to MedicationRequest. Applications that previously retrieved medication lists from both resources need to update their code to use the R4 structure.

These changes help developers determine how much mapping work is needed for each application.

R4 Authorization and Scope Changes

Applications moving to R4 need to update how they receive permission to access healthcare data. DSTU2 authorizations are linked to the older API endpoints. Users and backend systems must authorize access again through R4.

Oracle Health also uses the same SMART on FHIR authorization server and framework for R4 that it used for DSTU2 and R4 adds support for  SMART app launch 2.0 scopes alongside the existing 1.0 scopes. SMART on FHIR uses OAuth 2.0 to manage application access to healthcare information. Access is controlled through scopes.

A scope specifies which FHIR resources an application can access and which operations it can perform. R4 supports more specific scopes, giving applications better control over the patient information they request.

Patient-facing apps need updated consent

• Patients who previously authorized the DSTU2 application will need to approve access again.
• The new consent process should display the specific R4 scopes requested by the application. 
• This helps users understand which types of information the application can access.

Backend applications need updated authentication

• Backend services exchange information directly with the EHR without requiring a patient to sign in for every request.
• For R4, these applications can continue to authenticate with the same system account’s client’s ID, or they can use a signed JWT assertion. Applications that choose JWT auth (required for bulk data access) need RSA or EC key pair (RS384 or ES384), a JWKS registered in Cerner Central System Account Management, and a signed JWT assertion.
• The RSA keys support secure authentication. The JWKS registered with oracle makes the public keys available for verification, while the signed JWT assertion helps confirm the application’s identity when it requests an access token.

Applications need a new R4 registration

• Developers must configure R4 FHIR product APIs for the application in code Console, either by updating the existing application registration or by creating a new one. 
• The new registration includes the required SMART v2 scopes and authentication settings. Existing DSTU2 registrations remain separate from the R4 registration.
• Testing these changes in Oracle’s sandbox is an important part of the migration. Teams should also validate the authorization process when the application launches in the customer’s environment.

What Data Carries Over to R4?

The clinical information stored in Cerner Millennium should remain accessible when an application moves from DSTU2 to R4.

Patients, encounters, allergies, conditions, and clinical results continue to be available through the updated API.

Some information is returned in a different structure. Applications also need to update certain saved references and access permissions.

What carries over:

• Clinical data: Information previously available through DSTU2 should remain accessible through R4. Applications may need to use updated resource structures to retrieve it.
• The Millennium tenant: The application continues to use the same Millennium tenant with a new R4 endpoint path.

What has to be rebuilt:

• Resource IDs: Stored DSTU2 resource IDs must be checked against R4. HL7 recommends stable IDs across versions, although changes are possible. Applications should update any saved IDs that identify different records.
• Medication data: DSTU2 MedicationStatement information is mapped into MedicationRequest on R4. Applications that previously displayed separate medication lists need to update how they retrieve and combine the information.
• Authorizations and tokens: Users and backend systems need new R4 authorization. Existing DSTU2 tokens and authorizations cannot be reused.

What is new on R4 and worth adding during the move:

• Provenance: New in R4; US core requires R4 servers to support it. Although applications are not required to consume it. It provides information about the system that created or supplied a clinical record.
• Clinical Notes: DocumentReference was already available in DSTU2, but R4 adds more not categories and the US core DiagnosticReport note profile. Some documents are provided as Binary content, which must be decoded before use.
• Additional vital signs: R4 supports profiles such as pulse oximetry that were unavailable through DSTU2.
• Pediatric observations: R4 includes additional observation profiles for pediatric clinical information.

Teams can use the migration to review the data their application needs and determine whether the new R4 resources would be useful.

Millennium R4 vs AI Application Suite

Oracle Health provides FHIR R4 APIs through two products: the Oracle Health Millennium Platform and the Oracle Health AI Application Suite. Both products use FHIR R4. Each has its own API behavior and validation requirements.

Oracle’s change log explains these differences. They affect how applications search for records, handle custom fields, validate resources, and manage access.

Most existing Cerner applications will move to Millennium R4. Applications serving customers who are moving to the AI Application Suite should follow the requirements for that platform.

Behaviour	Millennium Platform R4	AI Application Suite R4	Oracle’s impact rating
Default _count on searches	Varies by resource	50 for all resources	Medium
Maximum _count	Varies by resource; applied maximum not always shown in link[self]	1000 for all resources; link[self] reflects the applied maximum	Medium
_id length	Length limit enforced on some resources only	64-character limit on all resources, per the FHIR specification	High
Search bundle error handling	Additional rules may apply	Noncompliant resources are excluded from search bundles; operations validated against Oracle and US Core profiles	High
Custom Encounter extensions	Fields can be configured and returned through FHIR	User-defined fields not supported	High
Encounter hospitalization fields (dietPreference, specialCourtesy, specialArrangement, contained)	Returned	Not currently supported	High
Encounter search by account	Supported	Not supported	Medium
Granular scopes	Available	Access-control rules aligned to the FHIR specification	High

Two differences are especially important for applications that retrieve Encounter records and search results.

Search result limits

• On the AI Application Suite, searches return 50 results per page by default.
• Applications that previously used resource-specific page sizes on Millennium need to account for this change.
• Developers should check the application’s pagination logic to make sure it retrieves all available records.

Custom Encounter fields

• Millennium allows configured custom Encounter extensions to be returned through FHIR.
• The AI Application Suite currently does not support user-defined Encounter fields.
• Applications that use these fields should review their data requirements and identify which supported fields are available in the AI Application Suite.
• Oracle also notes that error responses on the AI Application Suite provide less detail than those on Millennium. Developers should account for this when setting up validation and application logging.
• Confirming the customer’s Oracle Health platform early helps teams prepare the correct mapping and testing requirements.

How Should You Sequence the Migration?

A structured migration begins with reviewing the existing application. Teams can then update authorization, map resources, and test the R4 connection.

The following sequence covers the work involved:

1. Inventory every DSTU2 call

Review the application code and identify every request made to a DSTU2 endpoint. Search for the DSTU2 base URL and list the resources, search parameters, and stored IDs used by the application.

Include scheduled jobs and components that cache FHIR responses. This inventory helps the team understand which parts of the application need updating.

2. Pick the R4 target

Confirm whether each customer uses Millennium Platform or the AI Application Suite. Document the differences in pagination, extensions, and search behavior for each tenant. This information will guide the mapping and testing work.

3. Register the app for R4

Create a new R4 application registration through Oracle’s developer program. Configure the SMART v2 scopes required for the application’s resources. For backend applications, generate the RSA key pair and publish the JWKS endpoint. The application registration references this information.

4. Rebuild authorization

Update the application launch and token processes for R4. Test the authorization process against Oracle’s public sandbox. Patient-facing applications need an updated consent screen. Backend applications need signed JWT assertions and token caching. Complete these changes before testing access to clinical resources.

5. Remap resources against US Core

Review each resource used by the application and update its structure to match the R4 US Core profile. Use the mapping table to estimate the development work. Check stored DSTU2 resource IDs and verify that they resolve to the correct R4 records.

6. Add Provenance and the new profiles

Include Provenance for the resource types the application reads, as required by US Core on R4. Provenance helps identify the source of clinical data and can support the review of records during migration. Teams can also add relevant clinical notes, vital-sign, and pediatric observation profiles.

7. Run both versions in parallel on test data

Use archived DSTU2 responses and compare them with live R4 responses. DSTU2 is no longer available in production, so archived responses provide a useful reference for testing. Compare resource fields, returned values, and clinical records to confirm that the application retrieves the expected information. This process can identify mapping differences that individual unit tests may miss.

8. Cut over tenant by tenant

Move each customer tenant to the R4 configuration after testing is complete. Re-authorize users and backend systems, update the API base URL, and verify the results. Keep the DSTU2 code path available for review during one release. Developers can use it to compare the previous and updated application behavior.

The same sequence applies to Millennium Platform and the AI Application Suite. Teams should follow the appropriate platform requirements in step 2 and use the corresponding validation rules in step 7.

Post-Cutover Failure Points

After moving to R4, teams should check that the application retrieves and displays the expected clinical information. Some API requests may complete successfully and still return fewer records than expected. Reviewing the following five areas during the first week can help teams identify these issues early.

1. Scope mismatch

SMART v1 wildcard scopes may not provide the same access under the R4 authorization model. An application may receive authorization and still return empty bundles for certain resources.

Check the R4 registration and confirm that every required resource has the appropriate SMART v2 scope.

2. Missing medication entries

Medication lists may appear incomplete if the application still requests MedicationStatement data using its old DSTU2 logic. R4 serves the relevant medication information through MedicationRequest.

Review the medication queries and confirm that the application retrieves the expected entries.

3. Short pages

The AI Application Suite returns 50 search results per page by default. Applications that previously expected a different page size may retrieve only part of the available information.

Test pagination to confirm that the application continues requesting records until the complete result set has been retrieved.

4. Dropped resources in search bundles

The AI Application Suite validates resources against Oracle and US Core profile requirements. Resources that fail validation are excluded from search bundles.

This means an application may receive a successful search response with fewer records than expected. Compare the returned records with the expected data to identify any differences.

5. Stale IDs

Resource IDs saved from DSTU2 need to be verified against R4. Some IDs may change, and a previously saved ID may resolve to a different resource version.

Check the actual resource contents when validating stored IDs. This confirms that the application is accessing the correct records. The AI Application Suite also provides less detailed error responses than Millennium.

Keeping complete request and response logs during the first few weeks, with appropriate security controls, gives developers the information needed to investigate unexpected results.

Let Folio3 Digital Health Handle FHIR Version Moves

Folio3 Digital Health provides HL7 and FHIR integration services to help healthcare organizations connect EHRs, exchange clinical data, and migrate between FHIR versions.

Our team supports Cerner DSTU2 to R4 migration, including API updates, resource mapping, and SMART on FHIR authorization. We work with Epic, Oracle Health, and other EHR platforms to keep clinical data accessible and applications connected. Whether you’re upgrading an existing integration or building a new one, we can help you meet the latest FHIR requirements.

Closing Note

Moving from DSTU2 to R4 brings Cerner applications in line with Oracle Health’s supported FHIR standard. It also provides an opportunity to update authorization, review clinical data access, and make use of the additional resources available through R4. The scope of work depends on the application’s existing resources and how it connects with Millennium. Teams that review these requirements early can plan the development and testing work more accurately. With the right preparation, the migration can be completed in a clear sequence while maintaining access to the clinical information the application needs.

Frequently Asked Questions

1. How long does a Cerner DSTU2-to-R4 migration take? 

Usually, a Cerner DSTU2-to-R4 migration takes 4 to 6 months. Since Oracle Health deprecated DSTU2 endpoints at the end of 2025, developers can use pre-built migration patterns and sandbox templates from the Oracle Health Developer Program to help keep the migration within this timeframe.

2. Which migration tasks require involvement from the hospital’s Oracle Health administrators?

Customer teams help with access to the app, coordinate environment provisioning, and approve access to protected resources. 

3. Does an existing Cerner application need a new Oracle Health review or approval before going live on R4?

Yes, it does. An existing application moving from legacy Cerner DSTU2 APIs to FHIR R4 requires re-registration and review through the Oracle Health Code Console.

4. What is a practical recovery plan if the R4 cutover fails and DSTU2 is no longer supported? 

If a switch to FHIR R4 fails and the old DSTU2 system is no longer supported, you cannot simply switch back to the old system. Instead, you need a temporary solution that translates data between systems, prioritizes critical health information, and keeps services running while developers fix the R4 issues.

 

About the Author