Recovering from a Failed Dynamics 365 Upgrade: Unsupported Customisations and Deprecated JavaScript

What does a Microsoft deprecation notice actually mean for your Dynamics 365 system?

A deprecation notice, whether it reaches you as a Message Center post in the Microsoft 365 admin center, an email to your tenant administrators, or an entry on the deprecation announcement pages on Microsoft Learn, tells you that a feature or API is no longer being developed and will be removed. Deprecated does not mean broken. In most cases the feature keeps working until its removal, which is exactly why these notices get filed and forgotten: nothing fails, so nothing is fixed, until a release wave or an auditor turns a quiet dependency into an incident.

Read every notice for three things. What is going: a client API, a service endpoint, an authentication method, or a whole feature. When: some notices carry a removal date, others only announce the deprecation, and a notice without a date is not a notice without risk. And what replaces it, because the replacement determines whether the fix is a one-line code change, a configuration change, or a redesign. What the notice cannot tell you is whether your own system uses the thing being removed. Only an inventory of your own solutions, and of the systems that call into them, answers that.

How do you map a deprecation notice to the components in your own solutions?

Translate each notice into something you can search for, then search every place it can hide. A notice about the Client API becomes a list of tokens to find in JavaScript web resources and ribbon definitions. A notice about the 2011 endpoints becomes a question for every plugin, integration and scheduled job, not only for form scripts. A notice about legacy authentication becomes a review of every service account and connection string that talks to Dataverse from outside. The result is a deprecation map: one row per notice, the components that depend on it, the business process behind each component, who owns it, and the date that matters.

The search mechanics for the client-side surface, including unpacking solutions with the Power Platform CLI, the exact tokens to look for and how to check which event handlers pass the execution context, are set out on our page on common Dynamics 365 customization mistakes and the Xrm.Page migration. We do not repeat them here. This service is about turning those hits into a plan someone can budget and sign off.

What should a Solution Checker inventory include, and what does it miss?

Solution Checker, run from the maker portal or with pac solution check against an exported solution file, analyses plugin assemblies, custom workflow activities and web resources against a published rule set and rates each finding by severity. Its web resource rules cover the problems that break on update directly: direct access to the form DOM, reaching into window.top or the parent frame, calls to the deprecated 2011 service endpoints, and calls that have a supported Navigation or context API replacement. Run it over every solution, not only the one the audit named, and keep the report. A dated checker report before remediation and a clean one after is the evidence a security or compliance reviewer asks for.

Treat the checker as the severity source, not the coverage source. It only sees what is inside the solution you give it. It does not see integrations and jobs running outside Dataverse, changes made directly in an environment outside your custom solutions, scripts that are registered but never called, or a handler that never passes the execution context. Those gaps are why the inventory combines the checker report with a source-level search and a review of the external callers, and why the assessment below lists each finding against the component, the form or process it affects, and the business owner rather than as a list of rule IDs.

How do you classify findings into must-fix, replace with configuration, and delete?

Every finding in the inventory goes into exactly one of three buckets, and the classification is what turns a long, frightening report into a budget. The question for each one is not "is this unsupported" but "does the business still need what this code does, and is code still the right way to do it".

Do not underestimate the delete bucket. Scripts written for a form that has since been replaced, buttons nobody clicks, and processes that were superseded by a flow years ago all show up in a checker report with the same severity as the code the business depends on. Deleting them is the cheapest remediation there is, and every one removed is one less thing to test on every future update.

What do deprecated client APIs actually break when Dynamics 365 updates?

The honest answer is that most deprecated client APIs break nothing on the day of the update and everything on the day of removal, which is a worse failure shape than an immediate error because it arrives all at once and across every form that shares a library. Xrm.Page still resolves in model-driven apps for backward compatibility, but it refers to a single global form, so code that relies on it can behave unpredictably where Unified Interface has more than one form open at once, such as a quick create form or a main form opened in a dialog. Those are defects that can exist today, not only a future risk, and they tend to be reported as intermittent bugs nobody can reproduce.

Scripts that reach into the parent frame or window.top depend on how the page happens to be hosted and fail when the hosting changes. Calls to the deprecated Xrm.Utility helpers keep working until they are removed, then fail on every form that uses the shared library. Anything calling the 2011 endpoints from the browser or from a server fails hard when the endpoint goes, and an integration failure is usually discovered by the business missing data rather than by an error on screen. The remediation for each of these, including a compatibility shim that stabilises the environment in the first week, is on the customization mistakes page.

What does unsupported DOM manipulation break on an update?

The HTML that Unified Interface renders is not a documented contract. Element IDs, class names and page structure can change in any service update, not only in the twice-yearly release waves, and Microsoft does not announce those changes because nobody is supposed to depend on them. Code that finds a field by its element ID to recolour it, hides a section by manipulating styles, injects controls into the page, or reads values out of the markup instead of through the Client API will stop doing its job without warning.

The failures are usually quiet. A field that should be hidden reappears, a warning colour disappears, a validation that ran in the DOM no longer runs so bad data gets saved, or a script throws on load and the handlers after it on the same event never fire. None of this shows up as a failed update; it shows up as users reporting that the system behaves differently this week. The supported replacements are the Client API methods for visibility, requirement level and notifications, business rules, and for genuinely custom UI a PCF control, which is the supported way to change how a field or grid renders.

Why remediate in slices rather than attempt a big-bang re-platform?

Because a big-bang rewrite of a customisation layer nobody fully understands moves all of the risk to one go-live, and a failed security audit is a bad reason to take that bet. A slice is one business process or one form and the code behind it: its must-fix items rewritten, its configuration replacements built, its dead code deleted, tested against that process in a sandbox and released as a managed solution. The system is better after every slice, the business can stop after any of them, and a problem in one slice is contained to one process.

We sequence slices by risk rather than by convenience. Items with a removal date and non-user-facing callers such as integrations go first, because they fail hardest and need no user retraining. Shared libraries follow, then forms in order of use and business impact. Before each slice, a copy of production in a sandbox with early access updates enabled shows how the remediated code behaves on the next release wave before production gets it. The detailed phase order for the JavaScript itself is on the customization mistakes page; this is the delivery wrapper around it.

What does a rollback plan look like for each remediation slice?

A rollback plan is written before the slice is built, and rehearsed once in a test environment before the first slice reaches production. For code and configuration, rollback means redeploying the last known-good managed build from source control, not restoring a backup and not someone remembering what the form looked like. That only works if the solutions are already in source control and deployed through a pipeline, and for many environments that fail an audit they are not. In that case putting the ALM in place is the first slice, following the approach in our guide to moving from manual ZIP files to PAC CLI and pipelines.

Slices that change data, for example a script replaced by a business rule that now defaults a field differently, need a data rollback as well as a code rollback, so the plan records which records the slice touches and how to put them back. Take an on-demand environment backup before each production release as a last resort, but do not treat it as the rollback plan: restoring a production backup also discards every record entered since it was taken. For each slice the plan names the trigger for rolling back, the person who decides, and the maximum time before the decision is made.

How do you estimate Dynamics 365 remediation honestly before committing a budget?

Estimate from the classified inventory, never from lines of code or the number of checker warnings. The cost of a finding is driven by what it takes to test the business process behind it, not by the size of the code change: a one-line fix in a library every form loads can need more regression testing than a rewrite of a script on one rarely used form. So each must-fix and configuration item is estimated as build plus test for its slice, and deletions are estimated as the confirmation with the business owner plus a release.

An honest estimate also states what it does not know. The usual unknowns are external systems nobody has documentation for, undocumented business rules living in scripts, and whether a usable test environment and test data exist. We put each unknown on the estimate as a named assumption with a range, and where one item dominates the risk, such as a large HTML web resource that manipulates the form, we recommend a short, time-boxed spike on it before the full budget is set. A single number with no assumptions attached is the estimate most likely to be wrong.

What does the fixed-scope upgrade remediation assessment deliver?

The assessment is a fixed-scope piece of work with a defined end, designed for an organisation that has an audit finding or a deprecation notice and no internal developer to interpret it. It stands on its own: you can hand the output to your own team or any Microsoft partner. If you also need a wider read on security, performance, data quality and governance rather than only unsupported code and deprecations, take the broader Dynamics 365 health check and technical audit instead, which covers upgrade readiness as one of its areas.

• A Solution Checker baseline across every solution in the environment, with the dated reports kept as audit evidence.
• A deprecation map linking each relevant Microsoft notice to the components, processes and owners in your system that depend on it.
• The full inventory, with every finding classified as must-fix, replace with configuration, or delete, and the business process it affects.
• A review of the callers Solution Checker cannot see: integrations, scheduled jobs and legacy authentication.
• A remediation plan in slices, ordered by risk and removal date, with a rollback approach for each slice.
• An estimate per slice with its assumptions and ranges stated, and any spike we recommend before the budget is fixed.
• The ALM gaps that would make safe releases and rollbacks impossible, with what to put in place first.

When is remediating the existing customisations not the right answer?

Occasionally the inventory shows that most of the custom code exists to make Dynamics 365 behave like a different product, and that the organisation is paying for Microsoft licensing it no longer uses. When that is the case we say so. We recommend the right solution - whether that's Microsoft Dynamics 365, Power Platform, or a custom-built CRM. Some businesses need the Microsoft ecosystem. Others need full control without licensing. We deliver both. For organisations that need full control without Microsoft licensing we build custom CRM on React, Node.js, PostgreSQL and .NET, and the assessment inventory becomes the requirements baseline for that decision rather than wasted work.

Two limits on scope, stated plainly. This service covers Dynamics 365 Customer Engagement (Sales, Customer Service, Field Service and Customer Insights) and Power Platform on Dataverse. Solzet does not upgrade or remediate Dynamics 365 Finance, Supply Chain Management or anything else on Finance and Operations, Business Central or Dynamics NAV, and does not do ERP implementations. And where a stalled project rather than old code is the real problem, the project rescue and takeover service is the better starting point.