Converting Classic Epicor dashboards to Kinetic Application Studio: a phased migration guide

Key facts

• Classic UI Retirement Timeline: Epicor formally marked Classic WinForms forms as deprecated in Kinetic 2024.1. In 2024.2+, Classic entry is blocked by default across standard operational screens, culminating in the complete removal of the Classic Smart Client desktop runtime in 2026.1.
• What the Generator Handles: From Classic Dashboard Maintenance, Deploy > Generate Application converts basic BAQ grids into Kinetic Application Studio applications prefixed with Ice.UIDbd..
• What the Generator Consistently Drops:
  • Column groupings, summaries (sums/averages), and cell conditional formatting.
  • Publish/Subscribe inter-grid relationships.
  • Custom C# or VB.NET client script code (Application Studio uses JSON MetaUI event trees, not procedural code).
  • Tracker view prompt layouts and default values.
• Parent-Child Filtering (Pub/Sub): In Kinetic Application Studio, parent-child grids should use Provider Model > BAQ Options > Where List (server-side parameterized filtering) rather than client-side DataView relationships to prevent browser memory exhaustion on large datasets.
• Updatable BAQs (uBAQ): Must contain all primary key fields in the underlying DataView, and save actions must invoke the erp-baq widget with Mode set to Update.
• Built-in Developer Tools: Kinetic provides native developer diagnostics inside the browser: press Ctrl+Alt+8 to toggle MetaFx event logging in the DevTools console, and Ctrl+Alt+V to inspect live DataViews.

Phase 1: Inventory, usage audit, and retirement

Do not commit resources to migrating unused dashboards. Organizations often accumulate hundreds of dashboards over a decade, with less than 20% actively queried.

1. Cross-Reference Definitions with Active Menus

Querying Ice.DashBdDef alone only shows dashboard definitions—including broken and abandoned drafts. To identify dashboards that users can actually open, join Ice.DashBdDef against Ice.Menu:

SELECT 
    d.DefinitionID,
    d.Description,
    d.SysRevID,
    m.MenuID,
    m.MenuDesc,
    m.ParentMenuID,
    m.Enabled,
    m.Program
FROM Ice.DashBdDef d
INNER JOIN Ice.Menu m 
    ON m.Program LIKE '%' + d.DefinitionID + '%'
WHERE m.Enabled = 1;

2. Audit Telemetry & User Activity Tracking

In Kinetic 2023.2 and 2024.x, administrators can inspect the Telemetry & Activity Log (Ice.ActivityLog) or system audit logs to verify whether a dashboard menu item has been executed in the last 90 to 180 days.

• If a dashboard has had zero launches in 6 months, mark it for retirement.
• If a dashboard is simply an unfiltered inquiry screen for a single record type, evaluate replacing it with a standard out-of-the-box Kinetic Tracker (e.g., Job Tracker or Part Tracker), which eliminates custom maintenance entirely.

Phase 2: BAQ Verification & parameterization

Underlying Business Activity Queries (BAQs) maintain full SQL execution compatibility between Classic and Kinetic, as the BAQ engine executes server-side via Ice.BO.DynamicQuerySvc. However, client rendering differences require review:

1. Verify Date and Sorting Logic: Validate that date filters and calculated string formatting render correctly in the Kinetic web client.
2. Convert Prompts to BAQ Parameters: In Classic dashboards, prompt criteria were often handled via Dashboard Tracker Views. In Kinetic UX, defining formal BAQ Parameters in BAQ Designer causes Kinetic to automatically render a clean, native slide-out parameter panel upon app launch, reducing Application Studio event configuration.
3. Execution Performance: Optimize table joins (avoiding large outer joins on transactional tables like PartTran or TranGLC) before migrating the UI layer.

Phase 3: Choose the migration Track

Classify every dashboard into one of two architectural tracks:

Track A: Generate and Adjust (Simple Dashboards)

Best for: Single BAQ grids, read-only summaries, and simple list views without custom scripts.

1. Open the dashboard in Classic Dashboard Maintenance (in environments where Classic tools remain accessible).
2. Select Deploy > Generate Application, check Deploy, and click OK.
3. Open Menu Maintenance:
   • Create a new menu item.
   • Set Program Type to Kinetic App.
   • In the Program lookup, locate the generated application (named Ice.UIDbd.<DashboardID>).
4. Launch the application in the Kinetic browser interface.
5. Create an Application Studio customization layer to re-apply missing grid formatting, column order, and summary totals (sums/counts).

Track B: Direct Rebuild in Application Studio (Complex Dashboards)

Best for: Publish/Subscribe parent-child grids, Updatable BAQs, multiple tabs, and dashboards with legacy WinForms code.

Do not use the Classic generator for complex dashboards; repairing broken generated MetaUI layers takes longer than a clean build. Use the Application Studio Application Wizard (available in Kinetic 2022.2+):

1. Open Application Studio from the Kinetic home page or menu.
2. Create a new Application from template (e.g., Grid View or Multi-Grid layout).
3. Build the views, bind DataViews to your BAQs, and wire event handlers cleanly using native MetaUI components.

Phase 4: Rebuilding complex architectural patterns

1. Parent-Child Grids (Replacing Classic Publish / Subscribe)

Pattern A: Server-Side Parameterized Filtering (Enterprise Best Practice)

Use this pattern whenever datasets are large or dynamic. Rather than downloading thousands of child rows to the browser, the child grid queries the database only for rows matching the selected parent record:

• In Application Studio, add DataViews for both the Parent BAQ and Child BAQ.
• Select the Child Grid component in the designer.
• Navigate to Grid Model > Provider Model > BAQ Options > Where List.
• Add a filter criterion:
  • Column: The child table linking field (e.g., OrderNum or CustID).
  • Condition: =
  • Value: '?{ParentDataView.OrderNum}' (referencing the active row of the parent DataView).
• In the Event Designer, bind an event to the Parent DataView on row change (dataview-row-change) that invokes the grid-refresh (or baq-execute) action for the Child DataView.

Pattern B: Client-Side DataView Relationships (Lightweight Lookup Only)

• In Application Studio, edit the Child DataView properties.
• Under Parent-Child Relationship, select the Parent DataView and map the connecting key columns on both sides.
• Architectural Warning: The child BAQ must load its entire dataset into browser memory before filtering occurs. If the child BAQ is capped by max row limits (e.g., 500 rows) or contains large volumes, records will be missing from the child grid. Reserve this pattern strictly for small, static datasets (<200 rows).

2. Tracker Prompts & Slide-Out Panels

• In converted dashboards, Classic tracker panels are translated into slide-out panels.
• Known Defect Reference (PRB0276515): If a converted tracker slide-out panel is deleted directly within Application Studio, the application's top overflow menu can become corrupted or disappear entirely. If a converted slide-out is not needed, set its Visible property to False rather than deleting the component from the designer tree.

3. Updatable BAQs (uBAQ) in Application Studio

To ensure editable grids successfully persist modifications back to Epicor:

1. Primary Key Inclusion: Confirm that all primary key fields of the updating database table (e.g., Company, OrderNum, OrderLine) are present in the BAQ and mapped as keys in BAQ Designer. If key columns are missing from the DataView, Epicor's update Business Object cannot locate the target records.
2. Grid Model Configuration: In the Grid component, open Grid Model > Columns, locate editable fields, and verify that the Editable checkbox is selected.
3. Save Event Wiring: Create a Click event on the Save action button (or toolbar Save tool). Use the erp-baq widget with Mode set to Update (or call the DynamicQuery.Update method via the erp-service widget).
4. Row State Tracking: Kinetic ag-Grid automatically assigns RowMod = "U" (IceRow.ROWSTATE_UPDATED) to dirty rows in memory. If custom pre-processing events clear DataView flags, insert a row-update action prior to the BAQ execution to ensure RowMod is set to "U".

Phase 5: Reconciliation & validation in Pilot

Before deploying migrated dashboards to production users, execute side-by-side reconciliation between Classic and Kinetic in a Pilot environment:

Phase 6: Packaging, deployment & Security

1. Package via Solution Workbench: Add the underlying BAQs, Application Studio layout definitions, and Menu items into a Solution Workbench cabinet (.cab) file to move cleanly between Pilot and Production.
2. Menu Maintenance Registration:
   • Open Menu Maintenance.
   • Create the target menu item, set Program Type to Kinetic App, and select the Application ID (Ice.UIDbd.<Name> or custom App Studio ID).
   • If maintaining parallel access during a transition window, configure separate menu entries for Classic and Kinetic.
3. Menu Security Maintenance: Apply appropriate Security Groups in Menu Security Maintenance to govern user access.
4. Post-Upgrade UI Redeployment: Following major Kinetic environment upgrades, generated dashboards may occasionally produce metadata column errors (e.g., "Invalid column name"). In such cases, re-open the application in Application Studio and re-save/re-publish the customization layer to regenerate the MetaUI JSON definitions.

Developer diagnostics & debugging shortcuts

Kinetic includes powerful built-in developer tools accessible directly within the browser:

Best Practice: Always disable debug logging prior to exporting application layers to production environments.

Troubleshooting common migration defects

FAQ

When should I use the Classic generator vs. rebuilding from scratch in Application Studio?

Use the built-in generator (Deploy > Generate Application) only for simple, single-query tabular dashboards. Dashboards featuring Publish/Subscribe relationships, Tracker Views, custom scripts, or Updatable BAQs should be rebuilt directly in Application Studio.

Do existing BAQs need to be rewritten when moving to Kinetic?

No. BAQs execute on the server-side Business Object layer and maintain full SQL compatibility. However, you should review queries for hardcoded date formats and add formal BAQ Parameters to streamline Kinetic slide-out filters.

Will custom C# scripts in Classic dashboards carry over to Kinetic?

No. Classic WinForms customizations (.NET procedural code) cannot execute in the Kinetic web client. Custom logic must be rebuilt using Application Studio JSON event trees or moved to server-side Epicor Functions (EFx).

Why does my child grid drop records when using DataView Parent-Child relationships?

Client-side DataView relationships require the child BAQ to download all rows to browser memory before filtering. If the BAQ hits maximum row caps, child rows will be missing. Use server-side parameterized filtering via Grid Model > Provider Model > Where List.

References

Cross-check against official Epicor documentation matching your release and hosting model:

• Epicor Kinetic Help: Application Studio Overview & Application Wizard
• Epicor Kinetic Help: Grid Model Configuration – Provider Model and Where List Filtering
• Epicor Kinetic Help: Updatable BAQ Application Studio Integration & Event Wiring
• Epicor Kinetic Help: Menu Maintenance – Deploying Kinetic Applications
• Epicor Kinetic Problem Reference: PRB0276515 (Slide-out panel deletion and overflow menu loss)
• Epicor Technical Documentation: Classic Smart Client Retirement & UI Modernization Roadmap