AX to N4 Upgrade: How to Prevent the Headaches Nobody Warns You About

Upgrading from Niagara AX to N4? Here's what actually trips people up — from deprecated Java calls to credential migration — and how to avoid it.

NSES Engineering Team2026-04-0611 min read

AX to N4 Upgrade: How to Prevent the Headaches Nobody Warns You About

You Think You’re Ready. You’re Not.

You’ve got your N4 modules downloaded, the migration tool installed, and a weekend blocked off. Your AX station is backed up, the field controllers are documented, and you’ve read through Tridium’s official upgrade notes. What could go wrong?

A lot, actually.

We’ve helped dozens of facilities migrate from Niagara AX to Niagara 4, and the pattern is almost always the same. The migration tool runs, the station converts, and then the real problems start surfacing — problems that no module compatibility chart warned you about. This article covers the stuff that actually bites you.

What Everyone Already Tells You

Let’s get the basics out of the way. Every AX-to-N4 guide covers these, and they matter:

Module compatibility — Confirm that every module in your AX station has an N4-compatible version. The migration tool will flag missing modules, but you need to source them ahead of time.
Platform requirements — N4 requires a 64-bit JVM and has different OS support than AX. Verify your JACE or supervisor hardware is on the N4 compatibility list.
Backup everything — Station backup, dist backup, license files, and a full config export. Non-negotiable.
The migration tool — Tridium’s niagaraax-migration module handles the bulk conversion. It converts your station database, renames modules, and remaps component references.

If that’s all you’ve prepared for, you’re going to have a rough weekend.

The Stuff Nobody Warns You About

1. User Credentials Don’t Come Over Clean

This one catches almost everyone. Niagara AX and Niagara 4 have fundamentally different security and user models. Here’s what actually changed:

Permissions moved to Roles — In AX, every User had a Permissions property mapping their privileges to station categories. In N4, that property was removed entirely. Permissions now live in Role components under a new RoleService. The migration tool creates a one-to-one Role for each User (named identically), but this default mapping often needs cleanup — especially if you want to consolidate permissions into logical role groups rather than carrying forward the per-user mess from AX.
Authentication is now user-specific — N4 enforces per-user authentication schemes. You can’t just rely on a station-wide default anymore.
Certificate-based communication — N4 uses TLS certificates for station-to-station communication (foxs:// instead of AX’s fox://). Every station needs valid certificates, and you should export your Trust Store and Private Key Stores from AX before migration.
HTML5 user prototypes require a pre-migration flag — If your N4 users will use the HTML5 prototype (Hx), you must enable the User Defined 1 configuration flag on the web_WebProfileConfig property of each user prototype in your AX stations before running the migration tool. Miss this step, and your users won’t have the right web profile in N4.

The migration tool brings user accounts over, but stale accounts from former employees or contractors come along for the ride — now sitting in your N4 station with auto-generated Roles and unclear permission levels.

The fix: Use ProgramService to audit and auto-flag users.

Before or immediately after migration, deploy a Program object under Niagara’s ProgramService to scan your user database. Here’s the approach:

// Scan all user accounts and flag those needing review
// Navigate: Config > Services > UserService
BUserService userService = (BUserService)
    Sys.getStation().getService(BUserService.TYPE);

// Iterate through user prototypes and check for stale accounts
BComponent users = userService.get("User Prototypes");
Cursor c = users.getProperties();
while (c.next()) {
    BUser user = (BUser) c.get();

    // Flag accounts that haven't been active
    if (!user.getEnabled()) continue;

    // Check for legacy credential state, missing role assignments,
    // or accounts that predate your migration window
    log.info("Review needed: " + user.getName()
        + " | Roles assigned: " + user.getRoles().length());
}

After the audit, work through the new RoleService to consolidate your permission model:

Review the auto-generated one-to-one User→Role mappings
Consolidate into logical Roles (e.g., “Operator”, “Engineer”, “Admin”) rather than per-user Roles
Disable stale accounts immediately — don’t just plan to “get to it later”
Force password resets for every active user under N4’s stricter policy
Verify the User Defined 1 flag was set correctly for HTML5 web profiles
Export and install station certificates for foxs:// communication
Document the final user/role roster as part of your migration record

Don’t treat user migration as an afterthought. In a security audit, orphaned accounts with auto-generated admin Roles on a building automation system are a finding that nobody wants to explain.

2. Your Java Programs Are Broken — `getProgram()` Is Gone

This is the one that causes the most frustration, because the migration tool flags it but most people don’t understand the full scope of what needs to change.

When you run the n4mig migration tool against your AX-3.8 station backup, it attempts to compile all Program objects to be N4-compatible. Any that fail get flagged in the migration report with a WARNING unable to compile entry. Here’s what that actually looks like in the log:

WARNING unable to compile Program object PxHome.Graphics.Residential.First Floor.GarageProgram
error: cannot find symbol
  Action action = getProgram().getAction("execute");
                  ^
  symbol: method getProgram()

The root cause: getProgram() was deprecated starting in AX-3.5 and has been fully removed in N4.0. In AX, it still compiled and ran even though it was deprecated. In N4, it’s gone. Every instance must be replaced with getComponent().

But that’s just the tip of the iceberg. Here’s the full list of breaking API changes from the official migration reference:

getProgram() → getComponent()

// AX (broken in N4):
Action action = getProgram().getAction("execute");

// N4 fix:
Action action = getComponent().getAction("execute");

Primitive slot accessors removed

Slots defined as baja:Boolean, baja:Double, baja:Float, baja:Integer, baja:Long, and baja:String now return their Java primitive types directly. You no longer need .getDouble(), .getInt(), etc.

// AX — for a slot defined as Name=temperature, Type=baja:Double:
double temp = getTemperature().getDouble();

// N4 — the slot already returns a primitive:
double temp = getTemperature();

This one is subtle — your code may compile but produce ClassCastException or boxing errors at runtime if you still have the old accessor calls.

Runtime.exec() → ProgramRuntime

N4 introduced a Java Security Manager that restricts Program objects. You can no longer call Runtime.getRuntime().exec() directly. Instead, use the ProgramRuntime wrapper, which logs and audits every execution:

// AX:
Runtime.getRuntime().exec("notepad.exe");

// N4:
ProgramRuntime.getRuntime().exec(this, "notepad.exe");

Additionally, you must set the hidden slot allowProgramRuntimeExec to true on the station’s ProgramService — and only standalone Program objects can use it. Programs compiled into Program Modules cannot call ProgramRuntime.exec() at all.

File I/O restricted — Programs can now only read/write within the station_home directory (file:^). If your AX programs accessed files outside this path, they’ll fail silently.

Only super users can edit Programs — In AX, you could change this via system.properties. In N4, that escape hatch is gone.

How to audit before you upgrade:

# After exporting program sources from your AX station
grep -rn "getProgram\|getDouble()\|getFloat()\|getInt()\|getLong()\|getString()\|Runtime.getRuntime" ./exported-programs/

Critical note on ProgramModule components: If your station uses custom modules built with the ProgramModule component (from the AX program palette), those modules must be refactored for N4 before migration — otherwise, every Program object from them gets deleted in the migrated station. The migration tool will not do this for you. You need to open each ProgramModule in N4 Workbench, fix the code in the Program Editor, recompile, and rebuild the module JAR before the station can run.

The migration tool catches some of these issues. But it misses deprecated calls inside utility methods, abstract classes, and third-party wrappers. Manual code review is essential. If your station has more than a handful of custom programs, budget real time for this — it’s not a checkbox task.

3. Everything Else That Isn’t “Just Modules”

Beyond users and Java code, here’s the full list of migration pain points we see repeatedly in the field:

Driver and Protocol Compatibility

Some AX drivers don’t have N4 equivalents. This is especially common with older or niche protocol drivers — legacy LonWorks drivers, proprietary OEM integrations, and some older BACnet implementations. Check every driver in your station against Tridium’s N4 driver availability list before you start. If a driver doesn’t exist for N4, you’re looking at a protocol gateway, a different integration approach, or potentially replacing field hardware.

Graphics Migration (PX to Hx)

This is an entire project by itself. AX used PX (JavaFX-based) graphics pages. N4 uses Hx (HTML5-based) graphics. They are completely different technologies. The migration tool does not convert your graphics — it can’t. Every PX page needs to be rebuilt as an Hx view from scratch.

For large campuses with hundreds of custom floor plans, equipment graphics, and dashboards, the graphics rebuild alone can exceed the time spent on the rest of the migration. Plan for this. Budget for it. Don’t let anyone tell you it’s a quick find-and-replace.

Alarm and History Migration

Alarm classes in AX and N4 are structured differently. Your alarm routing, escalation rules, and acknowledgment workflows may not map cleanly. Similarly, history configurations — rollup policies, retention periods, and archive schedules — may need reconfiguration. The data itself migrates, but the configuration around it often doesn’t.

Network Architecture — fox:// to foxs://

AX used unencrypted fox:// for station-to-station and workbench-to-station communication. N4 defaults to foxs:// (Fox over TLS). This means:

Every station needs a TLS certificate
Firewalls need to allow the new port (default 5011 for foxs:// vs. 1911 for fox://)
Workbench connections need to trust the station certificates
Supervisor-to-JACE communication must be re-established under the new protocol

If you’re managing a multi-station campus, this is a significant amount of network configuration work.

Licensing

N4’s licensing model differs from AX. Feature entitlements, point counts, and module licensing may not translate 1:1. Verify your N4 license files cover everything your station needs before you start the migration — discovering a licensing gap mid-upgrade is a bad time.

Third-Party Modules

If your station uses modules from third-party vendors (controls manufacturers, analytics platforms, custom integrations), confirm that N4-compatible versions exist and are available. Some vendors have been slow to release N4 updates, and a few have discontinued products entirely. Identify these gaps early.

Pre-Upgrade Checklist

Before you touch the migration tool, work through this list:

We’ve Been Through This Before

The NSES engineering team has migrated AX stations ranging from single JACEs to multi-building campus supervisors. The migrations that go smoothly are the ones where the pre-work was done properly — auditing Java code, cleaning up users, verifying driver and module compatibility, and having realistic expectations about the graphics rebuild.

If you’re staring down an AX-to-N4 migration and want a second set of eyes on your station before you pull the trigger, we’re happy to do a pre-migration assessment. We’ll flag the specific issues in your station so there are no surprises on migration day.

We also covered this topic in a video walkthrough — check it out here: AX to N4 Upgrade Guide on YouTube.

For the official Honeywell/Tridium reference, the AX to N4 Migration User Guide (EN2Z-1025GE51 R0917) is the authoritative source. Chapter 4 covers the API changes and Program object fixes in detail.

Nimbus Stratus Energy Solutions provides building automation engineering, controls integration, and facility management services across the Mid-Atlantic region. Have a migration question? Get in touch.

Topics

Niagara AXNiagara 4N4TridiumBAS upgradeDDC controls