How-toEpicor KineticUpgrade / Customization

Preserving Customizations When Upgrading to Epicor Kinetic

Question

how to preserve customizations when upgrading Epicor 10 to Kinetic

Also searched as

Epicor Kinetic upgrade customization not showing
Epicor classic customization to Kinetic conversion
Epicor 10 to Kinetic UI upgrade checklist
Epicor Application Studio migrate legacy customization

Short answer

Epicor Kinetic's web UI does not simply inherit classic smart-client customizations - most need to go through the Update Customization / Application Studio conversion process, and some WinForms-specific customizations cannot convert directly and must be rebuilt in the Kinetic designer. Plan the upgrade as a customization inventory and rework project, not a single technical cutover step.

Applies to: Epicor ERP 10.2.x moving to Epicor Kinetic 2021.1 and later

Plan the customization migration

1Inventory every active customization (Customization Maintenance, per form, per user/company) before starting - export the list rather than relying on memory, since customizations accumulate over years and not all are documented.
2Classify each customization: simple field/layout changes usually convert cleanly; anything referencing WinForms-specific controls, third-party ActiveX/COM components, or classic smart-client-only APIs will need a rebuild in the Kinetic Designer or Application Studio.
3Run the conversion tooling (Update Customization wizard or equivalent in your version) against a copy of the environment first, not production, and review each converted screen against the original behavior.
4Prioritize customizations by usage - pull usage data or ask department leads which customized screens are actually used daily versus ones nobody remembers the purpose of; do not spend rework budget converting dead customizations.
5Rebuild BPM-driven logic separately from UI customizations - BPM directives generally carry forward independent of the UI layer, but any directive that referenced smart-client-specific UI events needs review.
6Test dashboards and BAQ-based screens separately, since dashboard behavior in the Kinetic web client (search panel behavior, auto-refresh, tile layout) differs enough from the classic client that a straight carry-over often needs layout adjustment even when the data source is unchanged.
7Pilot with a small group of power users on the converted Kinetic customizations before the full cutover, and keep the classic client available in parallel where your license and Epicor version allow it during the transition window.
8Document the final state (what converted automatically, what was rebuilt, what was retired) so the next upgrade is not another full rediscovery exercise.

What converts cleanly and what does not

Field-level customizations - hiding, relabeling, or repositioning standard fields, adding simple calculated display fields, and dashboard/BAQ-driven grids - generally convert through Epicor's Update Customization tooling with limited rework. Customizations built around WinForms-specific behavior (custom ActiveX or COM controls embedded in the smart client, certain grid event handlers unique to the classic UI, or code that manipulates window-level UI objects the Kinetic web client does not expose the same way) do not convert automatically and need to be redesigned using the Kinetic Application Studio approach to that same requirement.

BPM logic is more portable than UI logic

Because BPM directives operate at the business object layer rather than the UI layer, most BPM-driven validation and workflow logic carries forward through an upgrade with far less rework than UI customizations do. The exceptions are directives that were written to react to or manipulate classic-client-only UI events - those need review, since Kinetic's web client event model is not identical.

Application Studio vs legacy Customization Maintenance

Kinetic's Application Studio is the newer, web-native way to build and maintain UI customizations, replacing the older Customization Maintenance/Visual Basic-style tooling for new work. Existing legacy customizations can often be brought forward through a conversion step, but any new customization work done as part of the upgrade project should be built directly in Application Studio rather than in the legacy tool, to avoid doing the same conversion again at the next major version.

Sequencing the upgrade to limit risk

Treat the customization migration as its own workstream with its own testing cycle, run in parallel with but not dependent on the core technical upgrade (database, application server, base configuration). Converting and testing customizations against a stable, already-upgraded test environment is far more reliable than trying to convert customizations and upgrade the platform in the same pass, since a failure becomes ambiguous - is it the platform upgrade or the customization conversion that broke.

Common pitfalls

!Assuming every classic customization will "just work" in Kinetic without a conversion and test pass.
!Converting every customization on the list instead of first checking which ones are still actually used.
!Running the conversion tooling directly against production instead of a disposable test copy.
!Treating BPM and UI customizations as the same migration effort when BPM generally needs far less rework.
!Skipping a pilot group and cutting the whole user base over to converted Kinetic customizations on day one.
!Not documenting which customizations were rebuilt versus auto-converted, leaving the same discovery work to redo at the next upgrade.

How an ERP-grounded AI assistant handles this

SyteRay-style grounded agents are built for exactly this kind of customization archaeology, and for Epicor shops ERPray plays the equivalent role: reading the legacy Customization Maintenance definitions and BPM directive source across an Epicor tenant and producing a first-pass inventory - which customizations reference WinForms-only controls likely to need a rebuild, which are simple field-level changes likely to convert cleanly, and which have had no recorded use in the audit or change logs. A developer still makes and tests every conversion decision; the inventory step that used to take days of manual review across every form becomes a starting list to verify.

See ERPray

Frequently asked questions

Can we run the classic smart client and Kinetic web client side by side during the upgrade?

In many Epicor 10.2/Kinetic version combinations, yes, for a transition period - check your specific version's supported configuration with Epicor or your partner, since exact client compatibility depends on the release. This is the most common way to pilot Kinetic with a small group before full cutover.

Do dashboards need to be rebuilt for Kinetic?

The underlying BAQ generally carries forward unchanged, but the dashboard layout, search panel, and tile behavior in the Kinetic web client differ enough from the classic client that most dashboards need at least layout review, and some need rework if they relied on classic-client-specific dashboard features.

How do we find customizations nobody remembers the purpose of?

Check Customization Maintenance's last-modified and last-used metadata where available, cross-reference with which users/companies have the customization assigned, and ask department leads directly - a customization with no recent use and no owner is a strong candidate to retire rather than convert.

Does upgrading to Kinetic require rewriting all BPM directives?

No - most BPM directives operate at the business object layer and carry forward with the upgrade. Review is only really needed for directives that interacted with classic-client-specific UI events or with customizations that are themselves being rebuilt.

Error fix

Fixing Epicor BusinessObjectException: BPM Directive Errors

A BusinessObjectException that says "A Business Process Management (BPM) directive has raised the following error" means a directive on that business object stopped the transaction, either deliberately via a Raise Exception widget or accidentally via an unhandled .NET error in Custom Code. Expand the InnerException on the error dialog to see the real message and the directive name, then open BPM Designer for that object and method to find the widget that fired.

How-to

Fixing a Slow Epicor BAQ (Business Activity Query)

A slow BAQ in Epicor is usually caused by unindexed join columns, a subquery or calculated field forcing a table scan, or the BAQ pulling far more rows than the dashboard actually displays before filtering client-side. Fix it by reading the SQL Server execution plan Epicor generates, moving filters into the BAQ criteria instead of the dashboard filter panel, and replacing subqueries with joins where possible.

Error fix

Fixing Epicor REST v2 API 401 Unauthorized Errors

A 401 Unauthorized calling Epicor's REST v2 (api/v2/odata) endpoint almost always comes down to one of three things: a missing or wrong x-api-key header, valid credentials but an API key scoped to a different company than the one in the URL, or REST services simply not enabled for that endpoint. Confirm the API key exists and is active in Application Studio (or the classic REST API help page), matches the company segment in the URL, and that the account used for Basic auth or OAuth has the right security group.

How-to

Epicor MRP Runs but Generates No Suggestions

When Epicor's MRP process completes without a job or purchase suggestion for a part you expect one for, the cause is almost always the part's own configuration (Part Class Type, Make Direct, Non-MRP flag, planning Time Fence) or the demand not being linked in a way MRP recognizes, not a defect in the MRP engine. Work through the part's Planning tab, its safety stock and lead time setup, and the demand source (sales order line status, job material requirement) before assuming the run itself failed.

Advanced

How to create and call an Epicor Function

Open Function Studio from the main menu (Customization > Function Studio) or from inside a BPM designer's Call Context widget, define a Library and Function with typed inputs/outputs, write the logic in the C# widget, then compile and test with the built-in test harness before calling it from a BPM directive, a dashboard, or another function.

Advanced

Epicor Application Studio: understanding customization layers

Kinetic UI is built in layers loaded in order - Base (Epicor-delivered), Customization (Application Studio, company/layer-wide), Personalization (user- or role-specific, applied on top), and optionally Extended (packaged add-on layers) - and a change you make will not appear if a higher layer overrides the same control or if you are testing in the wrong layer context.

AI for ERP

AI for Epicor Kinetic, Beyond What Prism Covers

Add AI to Epicor Kinetic beyond Prism: private LLM over BAQs, BPM data, and REST v2, on-prem or private cloud, with honest guidance on when Prism already covers you.