Migrating from Cerner DSTU2

What does migrating from Cerner DSTU2 involve?

Migrating from Cerner DSTU2 involves moving an app or integration from Oracle Health's DSTU 2 FHIR APIs to its R4 APIs: changing base URLs and media types, mapping DSTU 2 resources and fields to their R4 equivalents and US Core profiles, updating SMART authorization scopes, reconciling stored data, and testing every workflow before switching production traffic.

The work is more than a version bump. FHIR changed substantially between DSTU 2 and R4, so code that parses resources, builds queries or writes data needs review, and some resources were renamed or restructured.

The size of the job depends on how the app was built. A read-only patient app that uses a FHIR client library may need a few weeks of work, while an integration with custom parsing, write-back and stored resource copies across many tenants is a larger project with real risk.

Why does the DSTU2 retirement matter now?

The DSTU2 retirement matters now because the support date has passed. Oracle's DSTU 2 documentation states that as of December 2025 Oracle will no longer support DSTU 2 FHIR APIs and that they are replaced by the R4 version. An app still calling DSTU 2 depends on an unsupported interface that can stop working without further notice.

Health systems have their own reasons to push. Their app review processes increasingly expect R4 and US Core, and certified API requirements are built around R4. An app that cannot show R4 support may be blocked from new client sites even where an older connection still runs.

If you are not sure which version your app uses, check the base URLs in configuration and logs. Requests to paths containing dstu2 indicate the old APIs.

Treat the move as overdue maintenance rather than a feature project. Budget for it, give it an owner and a date, and avoid bundling it with unrelated redesigns that could delay the switch. Teams that keep the scope narrow usually finish faster and with fewer surprises at client sites.

What changes between the DSTU2 and R4 endpoints?

The endpoints change in version, path and media type. Oracle's documentation identifies the DSTU 2 APIs as FHIR DSTU 2 Final, version 1.0.2, and the R4 APIs as FHIR R4, version 4.0.1, with base paths that use /dstu2/ and /r4/ respectively.

• Base path: Service root URLs move from the DSTU 2 path to the R4 path for each tenant.
• Media type: DSTU 2 uses application/json+fhir, while R4 uses application/fhir+json, so Accept and Content-Type headers must change.
• FHIR version: Resource structures follow FHIR 4.0.1 rather than 1.0.2, affecting parsing and validation.
• Profiles: DSTU 2 followed Argonaut profiles; R4 aligns with US Core, which changes required elements and search parameters.
• Capability statement: Read the R4 capability statement for each tenant to confirm supported resources and searches.

Update the FHIR client library too, and pin the version you test against. Many libraries handle versions separately, and parsing R4 resources with a DSTU 2 model will fail or silently drop fields.

Which resources change the most?

The resources that change the most are those renamed or restructured between FHIR versions. Medication orders are the most common example: DSTU 2 used MedicationOrder, while the Oracle R4 APIs use MedicationRequest, with different element names and status values.

• Medications: MedicationOrder replaced by MedicationRequest, with changes to dosage, status and intent.
• Allergies: AllergyIntolerance status elements became coded concepts, changing how active and resolved allergies are read.
• Conditions: Clinical and verification status became coded concepts, and categories follow US Core.
• Conformance: The DSTU 2 Conformance resource is replaced by CapabilityStatement.
• References and codes: Many elements moved from simple values to coded types, affecting search and display logic.

Build a mapping document for every resource and element your app reads or writes. That document becomes the specification for code changes, tests and any conversion of stored data.

Include terminology in the mapping. US Core binds many elements to specific code systems and value sets, so a field that held a local code or free text under DSTU 2 may now carry a standard code, or several codings at once. Display and matching logic should choose the right coding rather than taking the first one in the list.

Pay particular attention to status and code values. Logic that filtered active medications or allergies by a DSTU 2 string value will return the wrong patients or the wrong lists if it is not updated for R4 coded statuses, and the app may still appear to work.

How do authorization scopes change?

Authorization scopes change because the Oracle R4 APIs support both SMART v1 and SMART v2 scope formats. The documentation gives examples such as patient/Condition.read in v1 style and patient/Condition.rs in v2 style, where the letters stand for read and search permissions.

Review the scopes your app requests, update them for the R4 resources it uses, and request only what it needs. Renamed resources need new scopes; for example, an app that read MedicationOrder must request access to MedicationRequest.

App registration may need updating as well. Check whether your registration in Oracle's developer console covers R4 and the new scopes, and plan for health system administrators to approve changes at each client site.

How should stored data and identifiers be handled?

Stored data and identifiers should be handled with care because many apps keep copies of FHIR resources or references to resource IDs. Do not assume IDs or reference formats match between DSTU 2 and R4 for every resource; verify this in the sandbox for each resource type you store.

Where stored data is in DSTU 2 shape, decide whether to convert it, refetch from R4 or keep it as historical data with a clear version marker. Refetching is usually safest for active patients, while conversion may suit archives.

Downstream systems also matter. Analytics pipelines, data warehouses and partner feeds that consume your app's data may expect DSTU 2 structures, so plan their changes in the same project.

Keep an audit trail of the conversion. Record which records were refetched, converted or archived, when, and by which job, so questions about historical data can be answered later without guesswork.

How should the migration be planned?

The migration should be planned as a staged project with a clear inventory, a mapping, a parallel test period and a controlled cutover for each client site.

• 1. Inventory: List every endpoint, resource, search, write operation and scope the app uses.
• 2. Map: Document DSTU 2 to R4 changes for each item, including profiles and value sets.
• 3. Build: Update the client, parsers, queries and scopes behind a configuration switch.
• 4. Test: Run against Oracle's R4 sandbox and compare results with DSTU 2 output for the same test patients.
• 5. Cut over: Switch sites one at a time, monitor errors and keep a rollback path while it remains possible.

A configuration switch per site lets you migrate gradually and handle sites with different readiness, which is common across health system clients.

Instrument the app before cutover. Log the FHIR version, endpoint, response status and timing for every call, so the team can see error rates by site and resource during the switch and confirm afterward that no traffic still reaches the old paths.

Which R4 behaviors catch teams out?

Several R4 behaviors catch teams out after the obvious changes are done. Pagination is one: results are returned in Bundles with links to the next page, and apps that read only the first page will miss data for patients with long histories.

Search parameters, required elements and error responses also differ under US Core. Write operations deserve careful testing, since the R4 documentation describes its own rules for creates and updates, including how partial updates are supported. Check each write path against the R4 documentation rather than assuming DSTU 2 behavior carries over.

Finally, test with realistic data volumes and patients with complex histories. Sandbox patients are often simple, and problems with paging, missing elements or unexpected codes appear only with real-world records.

How should you coordinate with health system clients?

You should coordinate with health system clients early, because each site controls its own app approvals, scopes and testing windows. A migration that is ready on your side can still wait weeks for a client's change board.

• Notice: Tell each client what is changing, why, and what you need from them, with target dates.
• Approvals: Confirm who approves the R4 registration and new scopes at each site.
• Testing: Agree on test patients and a validation period in the client's non-production environment where available.
• Support: Set a contact on both sides for cutover day and the first week after it.

Clinical users should hear about the change too, especially if screens, data or workflows look different after cutover. A short note that explains what changed and how to report problems prevents confusion and builds trust in the app.

How Agnotic can help

Agnotic Technologies migrates Oracle Health integrations from DSTU 2 to R4: inventory and mapping, client and parser updates, scope and registration changes, stored data conversion, sandbox testing and staged cutover across client sites.

We also use the migration to modernize, adding US Core conformance, better paging and error handling, and an abstraction layer that makes future FHIR version changes easier for your team to absorb.

Sources

• Oracle Health: Millennium DSTU 2 FHIR API documentation
• Oracle Health: Millennium R4 FHIR API documentation