Do Caxton 4 Migration

Technical Document
Niagara AX to N4 Migration
Guide
June 1, 2020
Niagara AX to N4 Migration Guide
Tridium, Inc.
3951 Westerre Parkway, Suite 350
Richmond, Virginia 23233
U.S.A.
Confidentiality
The information contained in this document is confidential information of Tridium, Inc., a Delaware
corporation (“Tridium”). Such information and the software described herein, is furnished under a license
agreement and may be used only in accordance with that agreement.
The information contained in this document is provided solely for use by Tridium employees, licensees, and
system owners; and, except as permitted under the below copyright notice, is not to be released to, or
reproduced for, anyone else.
While every effort has been made to assure the accuracy of this document, Tridium is not responsible for
damages of any kind, including without limitation consequential damages, arising from the application of the
information contained herein. Information and specifications published here are current as of the date of this
publication and are subject to change without notice. The latest product specifications can be found by
contacting our corporate headquarters, Richmond, Virginia.
Trademark notice
BACnet and ASHRAE are registered trademarks of American Society of Heating, Refrigerating and Air-
Conditioning Engineers. Microsoft, Excel, Internet Explorer, Windows, Windows Vista, Windows Server, and
SQL Server are registered trademarks of Microsoft Corporation. Oracle and Java are registered trademarks
of Oracle and/or its affiliates. Mozilla and Firefox are trademarks of the Mozilla Foundation. Echelon, LON,
LonMark, LonTalk, and LonWorks are registered trademarks of Echelon Corporation. Tridium, JACE,
Niagara Framework, and Sedona Framework are registered trademarks, and Workbench are trademarks of
Tridium Inc. All other product names and services mentioned in this publication that are known to be
trademarks, registered trademarks, or service marks are the property of their respective owners.
Copyright and patent notice

This document may be copied by parties who are authorized to distribute Tridium products in connection
with distribution of those products, subject to the contracts that authorize such distribution. It may not
otherwise, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form without prior written consent from Tridium, Inc.
Copyright © 2020 Tridium, Inc. All rights reserved.
The product(s) described herein may be covered by one or more U.S. or foreign patents of Tridium.
Contents
About this Guide .................................................................................................5
Document change log ................................................................................5
Related documentation ..............................................................................6
Chapter 1 Migration overview..........................................................................7

Why a migration tool? ................................................................................7
Platform compatibility ................................................................................8
Platform resource requirements ........................................................9
Recommended minimum resources by controller type .......................9
Checking for minimum resource requirements .................................10
Driver and application support..................................................................11
Wire compatibility ....................................................................................12
File locations ............................................................................................14
System home .................................................................................15
Controller user home......................................................................16
Migration workflow process......................................................................23
Migration workflow diagram ...........................................................23
Assess and prepare for migration....................................................24
Station backup and database migration...........................................25
Supervisor upgrade ........................................................................25
Controller conversion and new station installation ...........................25
System cleanup ..............................................................................25
AX to N4 migration tool and code signing .......................................25
Chapter 2 Migration tasks ..............................................................................27

Preparing platforms for migration .............................................................27
Certificate export...........................................................................27
Exporting the certificates ...............................................................27
Configuring a station to migrate users.............................................28
Relocating the Kerberos keytab file.................................................28
Station backups..............................................................................29
Secure license files .........................................................................32
Run the migration tool..............................................................................33
About the migration tool ................................................................33
Running the migration tool .............................................................36
Migration tool command usage ......................................................37
Migrating modules made with the ProgramModule
component ...............................................................................39
Migration details ......................................................................................44
Migration execution .......................................................................44
Migration report (log file)................................................................45
Post-migration database tasks ..................................................................45
Modifying Program objects.............................................................45
Considerations if a station functions as an oBIX server .....................47
Preliminary checkout of migrated stations .......................................48
June 1, 2020 3
Contents Niagara AX to N4 Migration Guide
Upgrade/convert platforms and install stations..........................................48

Copying the Supervisor station .......................................................49
Performing station cleanup .............................................................51
Controller conversion .....................................................................51
Downgrading controllers ................................................................56
Chapter 3 System verification.........................................................................59
Non-default environment files...................................................................59
Verify station-to-station communications ...................................................59
Provisioning notes ....................................................................................60
Verify Supervisor to controller platform daemon
communications ........................................................................60
Provisioning considerations when JACE controllers remain ..............61
Station User notes in migrated stations .....................................................62
Permissions moved to Roles ...........................................................63
Authentication is user-specific.........................................................64
Chapter 4 Migrating Niagara Enterprise Security stations..............................65

Upgrading devDriver-based video drivers .................................................66
Mapping Supervisor cameras to AX controllers before migration to
N4 ......................................................................................................67
Preparing the BackupService ....................................................................69
Backing up by creating a distribution file ...................................................70
Migrating each station..............................................................................71
Copying the migrated files........................................................................71
Setting up database passwords ................................................................72
Configuring network device passwords .....................................................72
Deleting the old certificates......................................................................73
Reconnecting the Supervisor and remote stations .....................................74
Restoring the BackupService schedules .....................................................75
Chapter 5 Connecting a Supervisor station to a legacy controller
station...............................................................................................................77
1. Configuring the Niagara Enterprise Security 4.8 Supervisor station
connection ..........................................................................................77
2. Adding a remote controller 2.3 station ..................................................79
3. Logging in to the Supervisor from the controller ....................................81
4. Connecting from the Supervisor to the NiagaraAX-3.8 legacy security
station ................................................................................................82
Chapter 6 Migration reference .......................................................................85
Imports....................................................................................................85
API changes .............................................................................................85
Primitives.................................................................................................85
Security Manager .....................................................................................86
File reading/writing ........................................................................86
Runtime.exec() ...............................................................................86
Example Program object fix ......................................................................86
4 June 1, 2020
About this Guide
This topic contains important information about the purpose, content, context, and intended audience for
this document.
Produ ct D ocu men t at i on
This document is part of the Niagara technical documentation library. Released versions of Niagara software
include a complete collection of technical information that is provided in both online help and PDF format.
The information in this document is written primarily for Systems Integrators. In order to make the most of
the information in this book, readers should have some training or previous experience with Niagara 4 soft-
ware, as well as experience working with JACE network controllers.
Document Content
This guide provides information about migration of NiagaraAX system running AX-3.8 to Niagara 4 system
running N4.0, and has the following main sections.
• Chapter 1 Migration overview, page 7
Provides requirements, restrictions, compatibilities between NiagaraAX and Niagara 4, background on
the need for migration (including major differences), and a general migration workflow process.
• Chapter 2 Migration tasks, page 27
Provides tasks to start migrating stations, including collecting AX-3.8 station archives, running the N4 mi-
gration tool, migrated database cleanup, preliminary N4 station checkout, and installation of Niagara 4
software and controller upgrades.
• Chapter 3 System verification, page 59
Explains system areas that may need attention and possible configuration immediately following the in-
stallation of Niagara 4 upgrades and migrated stations.
• Chapter 6 Migration reference, page 85
Contains some details on Program object (component) changes in N4 , along with an example “Program
object fix”.
• Chapter 4 Migrating Niagara Enterprise Security stations, page 65
Describes how to migrate your NiagaraAX-3.8 based security Supervisor and controller stations to
Niagara 4.8 based security stations.
• Chapter 5 Connecting a Supervisor station to a legacy controller station, page 77
Describes how you can connect and join Niagara Enterprise Security 2.4 stations to Niagara Enterprise
Security 2.3 JACE-6 controllers.
Document change log

June 1, 2020
• Edited certificate descriptions and procedures.
• Confirmed upgrade procedures for Niagara Enterprise Security stations.
• Corrected variables used for document branding.
December 16, 2019
• Edited procedures for exporting certificate key information prior to migration.
• Removed procedure for configuring new Photo ID device in Chapter 5. This information is in the Niagara
Enterprise Security Installation and Maintenance Guide.
August 7, 2019
Edited procedures related to migrating Niagara Enterprise Security stations from NiagaraAX to N4.
June 1, 2020 5
Niagara AX to N4 Migration Guide
April 19, 2019

Added two chapters related to station migration and legacy controller connections.
November 13, 2017

Removed a reference to tagged categories from the procedure, “Tips for Configuring oBIX Authentication”.
November 19, 2016

Removed text in “Driver and Application Support” topic indicating N4 support for video drivers.
May 6, 2016
One change was made in the topic, “File Locations”: in the table under the heading Homes in a Supervisor,
corrected the path for the protected_station_home
February 22, 2016

• Added information about setting the configuration flag before migrating users. Changes were made to
two topics:
– “Features and compatibility between N4 and AX,” and “Assess and prepare for N4 migration.”
– The following topic was added: “Configuring an AX station to migrate users”
• Edited the entire document to streamline the way software names are used and to convert task material
to task steps.
August 7, 2015
Initial release document.
Related documentation
Additional information about Niagara platforms, installation and operation Workbench is available in the fol-
lowing documents.
• Niagara Platform Guide
• Getting Started with Niagara
June 1, 2020 6
Chapter 1 Migration overview
Topics covered in this chapter
♦ Why a migration tool?
♦ Platform compatibility
♦ Driver and application support
♦ Wire compatibility
♦ File locations
♦ Migration workflow process
The Niagara Framework® has evolved to the point where existing NiagaraAX platforms and stations, if
upgradable, must be migrated to Niagara 4. Therefore, after installing Workbench, you cannot simply use
stations saved in NiagaraAX.
Migration involves several concepts:
• Conversion of AX artifacts to the corresponding N4 format; for example, station .bog files, Px files. The
N4 migration tool handles this conversion.
• “Wire compatibility” (communications) between AX and N4, with the possibility that some migrated jobs
must retain some number of AX controllers. Some platform types cannot be migrated, for example,
JACE-2 controllers.
• For platforms to be migrated that use custom AX software modules, the custom modules must be
refactored as N4-compatible modules.
Why a migration tool?

Niagara 4 has different platform and resource requirements than NiagaraAX, and there are other considera-
tions that affect the suitability for a job to migrate from AX to Niagara 4. An understanding of these is essen-
tial before beginning migration work for any existing NiagaraAX job.
As a result of the fundamental changes and security improvements in Niagara 4, a migration process is re-
quired. Simple reuse of any saved AX station is not possible. Following, are a few of the major reasons:
• Directory structure changes
In NiagaraAX, all folders and files are installed and created/maintained under a single Sys Home direc-
tory. For example, for a Windows PC platform that directory is: C:\niagara\niagara-3.8.111. This directory
includes runtime files and executables (modules, JRE, bin) along with configuration data files (stations,
Workbench options and registry).
To improve security, these files and folders are relocated in Niagara 4. See File locations, page 14.
• Software modules were refactored
In NiagaraAX, each software module typically contains multiple content levels: “runtime”, “user inter-
face” (ui), and sometimes “doc”. When installing modules in JACE controllers that are unable to utilize all
levels, AX platform tools “filter” out unneeded content levels at install time. However, Niagara 4 uses the
J a v a S e c u r i t y M a n a g e r, which does not support this model. So, software modules in Niagara 4 were re-
factored, essentially split into two or more separate modules JAR files that differ by runtime profile (-rt,
-ux, -wb, -se, -doc). This also simplifies future module updates.
The N4 migration tool addresses refactoring when converting an AX station. However, if you have sta-
tions that use custom or third-party modules, those modules must be refactored the same way before
starting a migration.
• Users, Categories, and permissions were overhauled
June 1, 2020 7
Chapter 1 Migration overview Niagara AX to N4 Migration Guide
A number of changes to a station’s UserService and child User components occurred in Niagara 4, which
provide easier ways to manage large groups of station users. Coupled with new “Role” components and
“Tagged Categories”, permissions management is more logical and flexible. A related new Authentica-
tionService architecture allows the flexibility to specify the “authentication scheme” to use for station ac-
cess at the user level. Among other things, this lets you integrate LDAP users into a station’s standard
UserService, (no special LDAP or Active Directory user service required).
• Fox Service has moved
The F o x S e r v i c e component in Niagara 4 was relocated to each station’s main S e r v i c e s container, rather
than existing as a frozen slot under the N i a g a r a N e t w o r k component. Other related authentication
changes were made as well.
• Ports in QNX platforms are sometimes redirected
As part of increased security in Niagara 4, the station process in all JACE controllers runs as an “unprivi-
leged process”, where such processes cannot bind to TCP/UDP ports less than 1024. This affected some
services and network types operating as servers using standard ports in this range.
To accommodate this, a new “Server Port” component architecture is used, where client requests to the
standard privileged ports are automatically redirected to other (higher) unprivileged ports. Most notably,
the default HTTP and HTTPS ports of 80 and 443 for a station’s WebService are now automatically redir-
ected to ports 8080 and 8443. For related details, see “Server Port model” in the NiagaraAX Platform
Guide.
There are many other differences and numerous new features in Niagara 4, however ones like the above are
examples of “breaking changes” that require a database migration tool, and not just the simple addition of
new Java classes and methods.
Platform compatibility
The PC or host controller you wish to upgrade must meet hardware and software requirements.
To qualify as a candidate for migration, any of the supported platforms listed below should be running a re-
leased version of AX-3.8, with working communications to other platforms at the job site running the same
software version. Earlier versions are not supported for migration.
Host Model N4 supported / OS / note s N4 compatibility notes
Supervisor or Engineering Work- Supported OS is Professional or Windows Vista (all) and Windows XP (all) are unsup-
station Enterprise versions of Windows 7, ported. Linux OS support is unavailable. Prior editions
(“Workstation”) Windows 8.1, or Windows Server of Windows Server, such as Windows Server 2008, are
2012 or Windows Server 2012 R2 unsupported.
(either 64-bit or 32-bit editions of
any of these).
JACE-8000 Supported Initially supports only N4.0. At some future point, an

update release of AX-3.8 may be available that sup-
ports most features of this newest controller.
JACE-7 (JVLN) Supported with Niagara 4.4 and WiFi option is not supported. Some other option cards
earlier. are also not supported in (see NPM below).
JACE-6E, JACE-603, JACE-645 Supported with Niagara 4.4 and Unsupported options include: GPRS, Sedona wireless,
(NPM6E) earlier. and dialup modem. Minimum resources are required
(fully loaded units in AX may not run in N4.0). For de-
tails, refer to Platform resource requirements, page 9.
JACE-6, JACE-602 Express
(NPM6)
JACE-3E (NPM3E)
JACE-2, JACE-202 Express Not supported Support is available for data exchange with N4 plat-
(NPM2) forms. For example, these stations can be under the
8 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 1 Migration overview
Host Model N4 supported / OS / notes N4 compatibility notes
JACE-403 NiagaraNetwork of N4 Supervisor. For related details,

see .
JACE-545
JACE-NXT
JACE-NXS
SoftJACE
Supported Support is available for data exchange.
If you first upgrade a system to AX-3.8 in preparation for migration to N4, be sure to verify proper operation
of the system (including NiagaraNetwork communications between stations), before making station backups
to use in the migration process.
Niagara 4 platform compatibility
For any supported PC or host to be migrated, be sure it has the necessary resources available. See Platform
resource requirements, page 9.
P l a t f o r m re s o u rc e re q u i re m e n t s
N4 requires more disk space, more Java heap, and more system RAM to run than a similar AX station. There-
fore, AX-3.8 JACE running near capacity will probably not fit the same station when converted to N4. A brief
summary of reasons why are as follows.
• Disk space (Flash)
N4 requires between 14-16 MB more space than an equivalent AX installation. Additional space is re-
quired by the new Java 8 VM (vs. Java 5), and new UX features enabling a rich browser experience.
• Heap space
For an equivalent station, N4 requires more Java heap (a baseline of 10MB) due to new features and func-
tionality, and more system memory when running on JACE controller.
• History RAM disk size (NPM6/NPM6E only)
To free additional system memory, the maximum history RAM disk size on JACE-6 has been reduced
from 64MB to 32MB. This should not affect most units because the default RAM disk size is 32MB. If the
RAM disk on JACE-6 has been increased, then this increase in the RAM disk size comes at the expense of
Java heap. Maximum history count has not changed.
R ec omm end e d m ini m um res ourc es b y c ontrol ler typ e

Each platform you migrate requires a minimum of resources in preparation to run the new system.
The following table summarizes recommended resource requirements before converting to N4.
M i n i m u m F re e D i s k S p a c e , i n Java Max Heap, Minimu m Free Heap, in M B

JACE ty pe/mode l MB in MB (if maxHeap feature licens ed (1) )
NPM3 (JACE-3E) 22 94 38
NPM6 (JACE-6) 20 94 38
NMP6E ( JACE-603, 24 94 38
JACE-645)
JACE-7 22 94 90
(1) If an JACE is NOT currently licensed with the “maxHeap” feature, then heap usage will not be an issue in N4.
June 1, 2020 9
The Minimum Free Disk Space recommendation is based on the following:

• 4MB free reserve for future N4 expansion
• 4MB for Data Recovery (NPM3E and NPM6E)
• 14MB for N4 increase
• 2MB for JACE-6 boot partition increase
The Minimum Free Heap recommendation is based on the following:
(20% total 86 NB heap size = 17MB) + (13MB additional N4 overhead + 8 MB
smaller heap (J3/J6 only) = 38 MB
Chec ki ng for mi ni mu m reso urce req ui reme nts

There is a special BOG file with the AX-compatible Program component that you can use to determine if a
platform meets the minimum resource requirements for migration. Test results are provided for free disk
space, free heap memory, and ram disk size.
Fi gu re 1 Example resources check notification using the Program in AX-3.8 JACE station
Alternatively, you can manually check resources, and compare to the recommended resource minimums giv-
en in Table 2 on page 7.
Usin g t he re sourc e ch ec ke r Progr am

This program provides a binary result: Failed or Passed. Only hosts that pass can be migrated.
P r e r e q u i s i t e s : You have the BOG file with the resource checker program, Workbench, and can open a sta-
tion connection (Fox or Foxs) to the host controller.
Step 1 Copy the BOG file with the resource checker program component to your AX-3.8 system home
folder.
Step 2 Using Workbench, open the station (Fox or Foxs), and expand C o n f i g to find a folder to copy the
Program into, or else add a new folder. You can locate it anywhere under C o n f i g .
Step 3 In the Nav tree, locate the BOG file with the resource checker program (it may be named “N4Up-
gradeResourceCheckerV1_n”) and copy it into the station. You should be able to immediately
use the program.
10 June 1, 2020
Step 4 Right-click the program in the station, and select A c t i o n s → → E x e c u t e .

After a few seconds, a popup A X t o N 4 U p g r a d e R e s o u r c e C h e c k e r window opens with the test
results, as either “Passed” or “Failed”.
Step 5 Click O K to close the window.
Ma n ua ll y c he ck i ng fo r fre e di sk sp ac e
A minimum amount of free disk space is required.
P re re q u i s i t e s : The host platform is at AX-3.8 and running the station to be migrated.
Step 1 Using Workbench, open the station (Fox/Foxs)..
Step 2 Expand C o n f i g → S e r v i c e s and double-click P l a t f o r m S e r v i c e s .
The P l a t f o r m S e r v i c e C o n t a i n e r P l u g i n v i e w opens.
Step 3 In the F i l e s y s t e m entry for / f f s 0 , compare the Free value with the value in Table 2.
The JACE value should be equal or greater than this minimum value.
Manually checking heap usage

A minimum amount of Java heap is required.
P re re q u i s i t e s : The host platform is at AX-3.8 and running the station to be migrated.
Step 1 Using Workbench, open the station (Fox/Foxs), and access the S p y page
(in Nav tree, right-click S t a t i o n node and select S p y ).
Step 2 Click u t i l → g c
Step 3 Refresh the page several times, observing the u s e d M e m o r y value under the A f t e r G C heading.
This represents the low point of Java heap usage.
Driver and application support

The initial release of Niagara 4 supports most of the commonly used NiagaraAX drivers, including BACnet,
LonWorks, Modbus, SNMP, and some legacy serial-based drivers. Support was dropped for a few drivers.
The following table lists a few drivers and applications that are no longer supported.
Unsupported driv er / application Removed modules / notes
802.1x wired authentication support for Module “platIEEE8021X”

QNX-based JACE controllers
OpenADR client drivers (simple, smart) Modules “adr” and “dras”
June 1, 2020 11
Unsupported driver / application Removed modu les / note s
Alarms to relational database support Module “alarmRdb”. Superseded by module “alarmOrion”.

Note if a third-party application accesses alarms, it will be affected by this (change in
the exported schema).
Original crypto/security module, using Module “crypto”—replaced by “platCrypto” since AX-3.7 (should only be used by
“CryptoService” in station non-Hotspot JACEs, for example,. JACE-2).
Dust wireless mesh network Module “dust”
Energy Application System (EAS), also Module “eas”

known by the branded name VES
Support for FIPS 140-2 (Federal Information Special FIPS distribution (.dist) file
Processing Standard)
Floating license repository Module “flr”
Fox tunneling, HTTP tunneling, and plat- Improved security in N4 prohibits most tunneling. Only serial tunneling is supported
form tunneling in Niagara 4, via the “tunnel” module on the station (server) side and a separate cli-
ent-side tunnel application.
IBM DB2 relational database support Module “rdbDb2”
Lon tunneling Module “lontunnel”. Improved security in N4 prohibits this tunneling.
Sedona (SedonaNetwork, Module “sedonaInstaller” in AX builds, which, from a downloaded Sedona “bundle,”
SedonaJen6lpNetwork) would install Sedona-specific modules for integration. These are not supported.
Older video drivers based on the “dev- Modules “video” (base), “axis”, “dedicatedMicros”, “milestone”, and “rapideye”,
Driver”, superseded in AX by “nDriver” superseded in AX by modules “nvideo”, “naxisVideo”, “ndedicatedMicros”, “nmile-
based videoDriver framework stone”, and “nrapideye”.
Platform support forNiagara R2 on any Niagara R2 platform support on JACE-603/JACE-645 controllers requires Workbench
QNX-based JACE controller (3.6, 3.7, or 3.8).
N O T E : This is a partial list. Other rarely-used or limited-distribution software modules were not brought for-
ward to the new version. For more information, check with your support channel to verify availability.
Additionally, any OEM-specific or custom (non-Tridium) software modules used on any platform to be mi-
grated must be refactored for use in Niagara 4. This is a separate process from using the migration tool on a
saved AX station, and must be completed by the custom module developer before you migrate the station.
Wire c om p at ib i li ty
Supported communications, or “wire compatibility” between platforms and tools can be a factor in different
job scenarios. Version compatibility is also relevant when it comes to feature support between N4 and AX.
The following sections describe compatibility between the two major versions of Niagara with regard to
communications and features.
Supported connections
Workbench can connect to stations running NiagaraAX as well as stations running Niagara 4. The following
table summarizes the possible connections and indicates which are supported in Niagara 4.
12 June 1, 2020
Table 1 Communications support between Niagara 4 and NiagaraAX
F ro m To Supported Notes
AX Workbench N4 station, N4 Supervisor No Prohibited in software.
AX Workbench N4 platform No Prohibited in software.
AX Workbench AX platform Yes Provides support necessary for AX to N4 upgrades. A few

functions from the Workbench remote controller P l a t f o r m
A d m i n i s t r a t i o n view are unavailable, including the C o m -
m i s s i o n i n g W i z a rd function.
AX Workbench AX station No Prohibited in software. Note that ongoing AX station con-

figuration requires Workbench.
AX station N4 station, N4 Supervisor Yes Discovery of points, schedules, and histories in N4 stations
is unavailable. However, you can manually add points. Re-
fer to the following section (Features and compatibility) for
more details.
N4 station, N4 Supervisor AX station Yes Refer to the following section (Features and compatibility)
for more details.
N4 station AX Supervisor No Not prohibited in software, but unsupported.
Fe at u res an d compa ti bi l it y
A limited number of features are supported when communicating between Niagara 4 and AX-3.8.
This table indicates which features are supported when communicating between stations.
Table 2 Feature compatibility table
F e a t u re From N4 to AX F ro m A X t o N 4 Additional comments
Point discovery No (AX Yes (N4 AX stations cannot discover points in N4 stations. The al-
Supervisor) Supervisor) ternative is to manually add and configure the points.
Point data Yes Yes N4 supports virtual points in AX stations. AX supports vir-
tual points in N4 stations.
Export Histories No Yes N4 uses different history encoding, and so detects and
converts history records as they come in.
Import Histories No Yes
Alarms routed to and No Yes

acknowledged
Export Schedules Yes No
Import Schedules Yes No
Synchronize users out (sync Yes, but only No Supported users are those assigned an authentication
out) users AX is capa- scheme with a password that can be ported to the AX sta-
ble of supporting tion. The synchronization process is supported in only one
direction.
Synchronize users in (sync in) No Yes, but only
users AX is capa- LDAP is a good alternative for network user
ble of synchronization.
supporting Although AX stations do not support the HTML5 user pro-
totype, you can synchronize users configured with the
HTML5 user prototype to AX stations by enabling the
User Defined 1 configuration flag on the web_WebPro-
fileConfig property of the user prototype slot in the
AX station.
Virtual points Yes Yes
June 1, 2020 13
Feature F ro m N 4 t o A X From AX to N4 Additional commen ts
Tunneling n/a n/a As Fox, HTTP, and platform communications provide in-
sufficient security, they are not supported in N4. Serial
tunneling is supported.
Export tags No, stations can- Yes, stations can For the AX station (subordinate) to join an N4 station
not join as join as (Supervisor), prior to executing the export tag join, the
subordinates subordinates two-way Fox connection in each station’s NiagaraNetwork
must be established between the stations. Failure to pre-
configure the two-way connection results in an error dur-
ing the export tag join.
Using Px files with ExportTags may be problematic as all
Px files must be converted for use with N4.
File transfer using Fox (Niag- Yes Yes File permission checks are enforced.
artaDeviceFileExt) is
supported.
Provisioning Yes No Supported operations for AX subordinates include:

• Update licenses
• Backup stations
• Copy Supervisor file
• Install valid AX software
• Upgrade out-of-date AX software
• Restore prior station backup, for example, from the
step history view of a backup job.
N4 provisioning robots will not run on AX stations.
N O T E : For Niagara 4 Supervisor to provision AX stations in addition to its own stations, you must import
the software database from the prior Supervisor into the new Supervisor’s software database. However,
Niagara 4 Supervisor cannot directly upgrade platforms to Niagara 4.
File locations
During the Workbench installation and platform commissioning processes, the software differentiates be-
tween two types of files based upon the content of the files: configuration and runtime data. Files and fold-
ers that contain configuration data reside in separate locations from files and folders that contain runtime
data. This separation enhances security by denying general access to the runtime files and allowing each
user access to only their personal configuration files.
As a result of separating configuration and runtime data, the system supports multiple home directories on
the Supervisor or engineering workstation. These homes may be identified as:
• The system home contains runtime files, such as core software modules, the JRE, and binary executables.
• Workbench user home for each user contains configuration data, including option files, and registries.
• A platform daemon user home for the Supervisor or engineering workstation contains platform configu-
ration data.
• Two station homes called, protected station home and station home, are part of each user home.
Homes on a Supervisor
The following table provides a summary of the Supervisor or engineering workstation homes with shortcut
information.
14 June 1, 2020
Home in the
Home in th e Platform Ad-
Wo r k b e n c h N a v ministration File ORD
t re e view Niagara 4 alias Windows folder location and contents shortcut
My Host→My File System Home niagara_home C:\niagara\niagara-4.x.xx ! (as in Niag-

System→Sys ara4.x)
Home Executables and software files
My Host→My File N/A niagara_user_ C:\Users\userName\Niagara4.x\<brand> ~ (unique to N4)

System→User home
Home Workbench user home for each human user contains that
user’s unique configuration files.
shared folder N/A station_home C:\Users\userName\Niagara4.x\tridium\shared ^ (as in Niag-

ara4.x)
stations folder N/A protected_sta- C:\ProgramData\Niagara4.x\tridium\stations ^^ (unique to

tion_home \<stationName> N4)
N/A Us er Home niagara_user_ C:\ProgramData\Niagara4.x\<brand> ~ (unique to N4)

home
Platform daemon user home (non-human user) holds plat-
form daemon configuration files. Requires a local platform
connection to view in the P l a t f o r m A d m i n i s t r a t i o n view.
Home s o n a c on trol le r
On a controller there are two homes.
Home in th e Plat- Home in the Plat-
form Adminis tra- form Administra-
tion view tion view Niagara 4 alias OFD location an d contents File ORD shortcut
Platform→Remote System Home niagara_home /opt/niagara ! (as in Niagara4.x)

File System→Sys
Home (Re ad On ly ) Contains operating system data.
Platform→Remote User Home niagara_user_home /home/niagara ~ (unique to N4)

File System→User Contains configuration data and
Home (Re ad On ly ) the installed and running station.
System home
Sometimes identified by its alias, niagara_home, the system home is the sole location to which the Work-
bench installation wizard and platform commissioning wizard install Niagara runtime components, such as
core software modules, the JRE, and binary executables. License files and license certificates reside in the
Workbench system home, under the security subfolder. A system home contains no configuration files
that can be changed by a user. Except when it is time to upgrade, these runtime files are read-only.
June 1, 2020 15
Fi gu re 2 Example Sys Home (niagara_home) on Supervisor platform
The example above shows the file system for Niagara 4 Supervisor running on a Windows PC. In the Nav
tree, the system home folder is referred to as its S y s H o m e . In the P l a t f o r m A d m i n i s t r a t i o n view, the same
system home is referred to as S y s t e m H o m e .
In the example, the actual location of the system home folder on this PC is: C:\niagara\niagara-
4.7.109.14.
The system home on a controller appears as S y s t e m H o m e in the P l a t f o r m A d m i n i s t r a t i o n view. The actual
location of the system home folder for a controller is: /opt/niagara/opt/niagara.
Control le r u ser ho me
The user homes are the locations under which all configurable data reside. Included are stations, templates,
registry, logs, and other data. Referred to by the alias niagara_user_home, the separation of these files from
the runtime files stored in the system home folder is new in Niagara 4.
The JACE controller has one system home and one user home.
16 June 1, 2020
F ig ure 3 JACE Sys Home (niagara_home ) and User Home (niagara_user_home) locations
Callout 1 above identifies a controller’s system home (alias: niagara_home) in both the Nav tree and the P l a t -
f o r m A d m i n i s t r a t i o n view. In the Nav tree, you can find the controller’s system home by expanding P l a t -
f o r m → R e m o t e F i l e S y s t e m . The actual folder for the system home is /home/niagara.
Callout 2 identifies the controller’s user home or daemon user home (alias: niagara_user_home) that contains
the installed and running station and other configuration files. The actual folder for the daemon user home
is: /home/niagara.
Windows platform user homes

For security reasons, each person that is a user of a Windows platform, has their own user home. This means
that each Supervisor platform has at least two user home locations: Workbench U s e r H o m e (for people),
and a platform daemon U s e r H o m e (for the daemon server processes).
The Supervisor engineering workstation that is licensed to run a station has a daemon user home. The dae-
mon is a server process and represents a (non-human) user that manages the Supervisor’s running station.
The Supervisor’s daemon user home contains daemon-specific configuration information. The actual location
of the Supervisor’s daemon user home is C:\ProgramData\Niagara4.x\<brand>. The platform daemon
is installed to this location and started from this location as a Windows service.
N O T E : In Niagara 4.4 and later, the installation wizard provides the default daemon user home location
which you can change if you wish. In the step to select the Daemon user home location you have the option
to either accept the default location or specify an a different location.
C A U T I O N : The Daemon User Home and the Workbench User Home are intended to be installed in distinctly
separate locations. This separation of homes is for security reasons but it also prevents certain unintended
results. For example, when the two homes are installed in the same location the S t a t i o n C o p i e r becomes
unavailable, and you will not be able to make a portable copy of the station.
June 1, 2020 17
In addition to this daemon user home, a Windows host has a separate Workbench user home for each person
(operator, administrator) who logs on with credentials to a Windows-based platform licensed for Workbench,
meaning a Supervisor or engineering workstation. Any given PC or workstation has at least one, and may
contain multiple Workbench user homes.
Each person’s Workbench user home is available in the Nav tree as a node under M y H o s t → M y F i l e S y s t e m
and contains unique configuration information that is not shared. This is where to find any new Workbench
station, as well as any remote station backups, templates and other configuration files. The actual location of
each person’s user home is in the Niagara4.0 folder under your Windows User account.
If you open a local platform connection to your Supervisor PC, expand M y F i l e S y s t e m in the Nav tree, and
go to the P l a t f o r m A d m i n i s t r a t i o n view, you can see both types of user homes at the same time.
Fi gu re 4 Local platform connection to a Supervisor station with Workbench and daemon user homes
• Callout 1 identifies Workbench U s e r H o m e .

• Callout 2 identifies the daemon U s e r H o m e .
When you first install Niagara 4 on your PC and start the daemon (by choosing the install option Install
and Start Platform Daemon on installation), the installation program creates this daemon U s e r
H o m e (Niagara4.0 folder). Initially, it contains an empty stations sub-folder, until you copy a station to
it.
18 June 1, 2020
F ig ure 5 Example of a daemon User Home location in Windows Explorer
You can do this station copy in different ways. In Niagara 4, you can let the N e w S t a t i o n wizard initiate this
copy from its last Finish step. Or as needed, you can manually open a local platform connection and use the
S t a t i o n C o p i e r.
The actual location of each user’s home folder is under that user’s personal Windows account. Some example
Workbench user home locations are:
C:\Users\John\Niagara4.x\<brand>
C:\Users\Mike\Niagara4.x\<brand>
where “John” and “Mike” are separate Windows user accounts. The first time a Windows user starts Work-
bench, the system automatically creates that user’s unique user home folder.
• The person that installs Niagara 4 on a PC acquires the first such user home. If no other Windows users
log on to that PC, this may be the only Workbench user home on the platform.
• However, if another person logs on to Windows on that computer and starts Workbench, that user also
acquires their own Workbench user home.
The following figure shows an example Workbench user home location in Windows Explorer.
June 1, 2020 19
Fi gu re 6 Example of an automatically-created Workbench User Home in Windows Explorer
Station homes
Niagara 4 uses the Java S e c u r i t y M a n a g e r to protect against malicious from accessing station or platform
data and APIs. The S e c u r i t y M a n a g e r uses signed policy files that specify the permissions to be granted to
code from various sources. Included are tighter controls about which applications have access to parts of the
file system. Two folders under the Wo r k b e n c h U s e r H o m e serve to protect sensitive data while allowing au-
thorized access to data that can be shared.
• The s t a t i o n s sub-folder, otherwise known as the protected station home (alias: protected_station_home)
contains the running station’s file system, and may be accessed only by core Niagara software modules.
Station items that are always in protected station home, that is, items that are not under the shared
sub-folder include the following folders, as applicable:
– alarm
– history
– niagaraDriver_nVirtual
– provisioningNiagara
– dataRecovery
All files in the s t a t i o n s folder root (config.bog, config.backup.timestamp.bog, etc.) are always in pro-
tected station home. For this reason, in Niagara 4 it is no longer necessary to blacklist or whitelist station
files or folders.
• The s h a re d sub-folder, otherwise known as the station home (alias: station_home), allows all modules to
have read, write, and delete permissions.
The alias station_home retains the same file ORD shortcut (^) as used in NiagaraAX—only in Niagara 4
this points to the station’s s h a r e d sub-folder.
20 June 1, 2020
F ig ure 7 Example NiagaraAX station file folders compared to Niagara 4 station file folders
AX station folder N4 station folder
As shown in the figure above, comparing an AX station file folder structure (left side) to the same station mi-
grated to Niagara 4, a number of folders are now under this s h a r e d sub-folder. Included are folders and files
used in graphical (Px) views or navigation, such as images, px, nav and so on. Modules that are prevented
from writing to the station root by the S e c u r i t y M a n a g e r must also write to the s h a re d sub-folder.
F ig ure 8 File ORD for the station home in Niagara 4 now points to the shared folder
As shown in a station running above, the station home (alias: station_home) file ORD (^) now points to the
contents of the s h a re d sub-folder. Other items in protected station home are no longer accessible or visible.
June 1, 2020 21
Copying a new station to the daemon user home

In Niagara 4, the N e w S t a t i o n W i z a r d tool finishes with an option to copy the station from the station home
(the location for each new station) under your Workbench U s e r H o m e to the U s e r H o m e of the local plat-
form daemon.
P r e r e q u i s i t e s : The new station exists in the station home (under User Home).
Step 1 When the N e w S t a t i o n W i z a r d prompts you with the option to Copy station, select the option
and click F i n i s h .
Step 2 Make a local platform connection and log on.
The S t a t i o n C o p i e r transfers the station and prompts you with the options to start the station
after copying and enabling auto-start.
Step 3 Select the option to start the station.
The A p p l i c a t i o n D i r e c t o r opens with the new station present in the daemon U s e r H o m e .
The new station now exists in two locations on your local host: the original location in your Workbench U s e r
H o m e , and also in the platform daemon U s e r H o m e .
Once the station is running in the daemon U s e r H o m e , you can make a backup of the running station, where
the backup .dist file goes in the backups folder of your Workbench U s e r H o m e . Or, you can use the plat-
form S t a t i o n C o p i e r to copy the station back to the stations folder of your Workbench U s e r H o m e .
N O T E : Using the S t a t i o n C o p i e r to copy the station back to your Workbench U s e r H o m e is highly recom-
mended if you made any changes to the station. This is essential if you are installing it (copying it) to any re-
mote platform. Remember, the copy of the station in your Workbench U s e r H o m e is immediately obsolete
as soon as you make changes to the copy of the station running in the daemon U s e r H o m e .
R u n n i n g a s t a t i o n f r o m Wo r k b e n c h U s e r H o m e
Instead of running a station out of the daemon U s e r H o m e , you can run a station directly from your Work-
bench U s e r H o m e (outside of normal platform daemon control).
You do this using the Niagara 4 console command:
station stationName
This is not a recommended way to run a production station, but instead more of a developer utility that al-
lows quick access to station debug messages in the console window. If you run the station this way, be mind-
ful of possible port conflicts with any other station that the daemon user may be running locally (in daemon
U s e r H o m e ), meaning Fox ports, Web ports, and so on.
Sh are d fi le st r at e gy
A sharing strategy makes it possible for multiple users of a single Supervisor or engineering workstation to
share station files including backups.
If multiple people log on (differently) to Windows on Niagara 4 host and use Workbench, each person has
their own separate Workbench U s e r H o m e .
Windows users require permissions to access other users’ files; yet it’s possible that different users of a sys-
tem (Supervisor or engineering workstation) may need to share items such as station backups, station cop-
ies, saved template files, and so on. Such items may be in multiple Workbench U s e r H o m e locations in
Niagara 4 .
Therefore, in some scenarios you may need to establish a sharing strategy, perhaps re-copying such items to
a commonly-accessible folder location on the Niagara 4 Windows PC. For example, you might create a
shared folder under the Niagara 4 S y s H o m e location (Workbench U s e r H o m e is not shareable).
22 June 1, 2020
Mi g rat io n wor kfl ow p roc e ss

Based on an existing NiagaraAX job with a Supervisor and some number of JACE controllers, the workflow
process for migration to Niagara 4 may look similar to below:
Migration workflow diagram

Basic steps in migrating your NiagaraAX installation are included in the following diagram.
F ig ure 9 Migration steps diagram
Red items indicate NiagaraAX artifacts. Blue items indicate Niagara 4 artifacts. Green boxes indicate steps
you need to take in the migration process.
June 1, 2020 23
Environment files are shown in yellow, because they may be generic to all versions of Niagara. If so, and
changed from defaults, they may require individual attention to see if values in them should be re-applied.
Examples of such files include modified !lib/units.xml or !lib/colorCoding.properties.
More detailed migration steps are included in the section Migration workflow process, page 23.
As ses s a nd p rep are for m ig ra tion

This topic summarizes platform and station-related tasks to complete before migrating.
1. Identify those platforms to be migrated. JACE controllers must be running at least NiagaraAX 3.8.nn,
and be compatible with N4.0. See Platform compatibility, page 8 and Platform resource requirements,
page 9 for details.
2. Review the current drivers and applications running on the JACE controllers to be converted. See Driver
and application support, page 11 for details.
If any drivers or applications are unsupported in N4.0, but are critical to retain, you can opt to leave those
controllers running AX-3.8, and still integrate them with Niagara 4 Supervisor station. However, you can-
not integrate a Supervisor at AX-3.8 with Niagara 4 JACE controllers.
N O T E : For any job that will have a mix of Niagara 4 and AX-3.8 platforms, refer to the section Wire com-
patibility, page 12.
3. For each AX-3.8 platform to be migrated, identify custom or third-party software modules that it uses.
Prior to upgrading, arrange to have those modules refactored as Niagara 4 modules. Contact the custom
module vendor to arrange this.
NOTE:
You cannot migrate a station to N4 until all of the modules it uses have been refactored for Niagara 4.
If you are unsure if an controller has such modules, you can check by making a platform connection to it,
then going to the S o f t w a re M a n a g e r view.
a. Click the “Installed Version” column header to re-sort, as shown above. Scroll down as necessary.
Any third-party sourced modules must be refactored by the module vendor before the station can be
migrated to Niagara 4. This assumes that all modules installed in the JACE are required by the con-
troller’s currently running station. Any installed module that is not used by the station is inconsequen-
tial in for migration.
b. If you previously built custom modules of Program components, using the ProgramModule feature
and its “Program Module Builder” view, you must also refactor these modules. This is something you
can do during the migration process.
4. If you will synchronize users from the N4 Supervisor to the AX station that have been assigned an HTML5
prototype, enable the User Defined 1 configuration flag on the web_WebProfileConfig property of
each user prototype slot in the AX station. (This is necessary because the most likely type of user proto-
type to be selected is an HTML5 prototype. There is no equivalent prototype in an AX station. Conse-
quently, by default, the migration tool assigns the first prototype in the list to each migrated user. This
prototype happens to be the Velocity Doc Web Profile.)
5. Make an N4.0 license request for all platforms to be migrated. You need confirmation that these licenses
are ready before migrating the platforms (AX licenses do not work in Niagara 4).
In almost all cases, the calculated host ID remains the same. An exception is if, on a Windows platform,
you are moving from a 32-bit install to a 64-bit install (or vice versa), in this case, the host ID differs.
Be sure to archive the old AX-3.8 license files as well.
24 June 1, 2020
Station backup and database migration

Before migrating, you should back up each station and prepare databases for the new system.
Using Workbench, make a station backup of each JACE controller to be migrated, and do the same for the
job’s Supervisor station. Be sure to include history and alarm files.
Then run the migration tool against these stations, with output as N4.0 station copies.
Sometimes, post-migration database “cleanup” may be needed. You should always do a preliminary check-
out of each migrated station.
Supervisor upgrade
You migrate the Supervisor first.
Once migrated, it can start up and communicate with JACE controllers still running AX-3.8 (see Wire com-
patibility, page 12 for related details).
Co ntroll er co nvers io n and new sta tio n ins tal la tio n

After migrating the controller and Supervisor stations you can convert the controllers and install the new
stations.
Before converting JACE controller from AX, you must successfully migrate its station to N4, including an off-
line checkout of it using Workbench. Only then should a conversion to N4 be done.
System cleanup
Following the upgrade of all AX-3.8 platforms to N4.0, including installation of migrated stations, there may
be several areas that need attention.
AX to N4 migration tool and code signing

When running the AX to N4 Migration Tool in 4.3 or later, any program object encountered is signed if a
code-signing certificate has been configured in Workbench.
When the migrator encounters the first program object that needs signing, it prompts you for your code-
signing certificate password.
June 1, 2020 25
26 June 1, 2020
Chapter 2 Migration tasks
♦ Preparing platforms for migration
♦ Run the migration tool
♦ Migration details
♦ Post-migration database tasks
♦ Upgrade/convert platforms and install stations
This chapter provides migration tasks, along with reference details as needed.
Pre par in g p lat fo rms for m ig rat io n

The following sections describe tasks necessary before migrating stations and upgrading platforms.
Certificate export
If your controllers are configured to use secure communications with signed certificates, the best practice is
to create new certificates for each controller and install them after migration. However, it is also a good idea
to export the current certificates before migration in case you need them later.
To save your existing keys, export them from the User Key Store and the User Trust Store prior to migration.
These are deleted from each controller during migration to N4. After migration, if you choose to not create
new certificates, you can import the exported certificates back using Workbench and a platform connection.
Exporting the certificates

The User Key Store contains all certificates with their public and private keys. The User Trust Store contains
one or more root CA certificates with only their public keys.
P re re q u i s i t e s : The company serves as its own certificate authority.
Step 1 Using Workbench, access the controller platform’s C e r t i f i c a t e M a n a g e m e n t utility. To do this, ei-
ther open a platform connection and click T o o l s → C e r t i f i c a t e M a n a g e m e n t or open the station
and double-click on C e r t M a n a g e r S e r v i c e (under C o n f i g > S e r v i c e s > P l a t f o r m S e r v i c e s ).
Step 2 To export the station’s server certificate with its private key, click the U s e r K e y S t o r e tab, select
the certificate and click E x p o r t .
You need to export the unique server certificate from the User Key Store for each controller
station.
Step 3 Enable the Export the private key check box and enter an encryption password to protect the
private key in this file.
Step 4 To export a root CA certificate, click the U s e r T r u s t S t o re tab, select the certificate and click E x -
p o r t . Typically, this only needs to be done once because the root CA certificate is the same in every
controller station).
N O T E : It is not necessary to export certificates from the System Trust Store as these are default
certificates found in every System Trust Store. It is only necessary to export any additional certifi-
cates that stored in the User Trust Store.
Step 5 Repeat the steps above to export the server certificate for each controller station to be migrated.
Make sure exported certificates files are available to the Workbench PC to use later. For related details, refer
to the Niagara Station Security Guide.
June 1, 2020 27
Chapter 2 Migration tasks Niagara AX to N4 Migration Guide
Configuring a station to migrate users

If your N4 users will use the HTML5 prototype, which does not exist in AX, you must enable the User De-
fined 1 configuration flag on the web_WebProfileConfig property of each user prototype in your AX
stations before running the migration tool.
P r e r e q u i s i t e s : You have Workbench access to the remote station.
Step 1 Expand the C o n f i g → S e r v i c e s → U s e r S e r v i c e → U s e r P ro t o t y p e s node in the station Nav tree.
Step 2 To view the slot sheet, right-click the user prototype and click V i e w s → S l o t S h e e t .
Step 3 To access the configuration flags, right click the web_WebProfileConfig property.
The C o n f i g F l a g s window opens.
Step 4 Enable the User Defined 1 flag and click O K .
R e l o c a t i n g t h e K e r b e ro s k e y t a b f i l e
If your AX-3.8 stations use Kerberos authentication for user services (for example, L d a p V 3 A D U s e r S e r v i c e )
and they use a “keytab file” supplied by the site’s Kerberos administrator, the migration tool requires this file
to reside under an “ldap” subfolder of each such AX-3.8 station. This procedure relocates the Kerberos key-
tab file prior to migration.
N O T E : If applicable, do this before making source station backups for use with the migration tool.
Step 1 Using Workbench, open the station (Foxs or Fox), expand the C o n f i g node, and navigate to the
property sheet of the UserService’s authenticator.
For example: S e r v i c e s > L d a p V 3 A D U s e r S e r v i c e > A c t i v e D i r e c t o r y C o n f i g > a u t h e n t i c a t o r
The Key Tab Location property ORD value references the current location of the keytab file.
Keep this view open.
Step 2 If it is a remote station, open a new tab in Workbench, and open a platform connection to the re-
mote host and access the F i l e T r a n s f e r C l i e n t view.
28 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 2 Migration tasks
Step 3 In the (remote) right-side “F

Fi l e s o n I P a d d re s s ” area, navigate to s t a t i o n s → s t a t i o n N a m e , and cre-
ate a subdirectory titled ldap. This is the target location for the keytab file.
Step 4 In the same right-side area, navigate to the Key Tab Location noted in Step 1. Select and transfer
the keytab file from the remote (right-side) to the local (left-side).
Step 5 In the same right-side area, navigate to the s t a t i o n s → S t a t i o n N a m e → l d a p folder created in Step
3, then select and transfer the keytab file back from the local (left-side) to the remote (right-side).
The keytab file should now be in the !stations/stationName/ldap folder.
Step 6 Switch to the Workbench tab showing the property sheet of the UserService’s authenticator and
edit the Key Tab Location property ORD value to match the new location of the keytab file.
Click S a v e .
Step 7 Save the station (right-click the C o n f i g node, click S a v e ).
Step 8 Repeat all steps above for each applicable JACE station to be migrated to N4.
If this is a local AX-3.8 station, such as a Supervisor station, you can use Windows Explorer to make the new
ldap subdirectory under the !stations/stationName folder, and copy and paste the referenced keytab
file into it. Be sure to update the authenticator’s Key Tab Location value with the new location, and save
the station database (steps 6 and 7).
After relocating the Kerberos keytab files and updating authenticator properties, test out the operation in
AX-3.8. A successful operation should continue after the station is migrated to N4.
Station backups
For any AX-3.8 platform you are migrating, make a station backup using Workbench. You will use this station
backup dist file as the source when running the migration tool (n4mig.exe) from the command prompt of
a console window.
C A U T I O N : Backups for the purpose of station migration should be made only from the BackupService of
the running AX-3.8 station.
When you migrate a backup dist that was made using the Platform Backup available from the Platform
Administration tool, this contains all the stations that are on the platform. For non-embedded platforms,
this may be multiple stations, as subordinate stations are often copied to the Supervisor.
You should NOT use the Station Copier to make copies for migration.
The proper source for a migration is Niagara Backup Distribution file from a station's BackupService, ob-
tained from the host upon which the original station is running. The Backup contains the necessary additional
information to correctly migrate the station; a station folder does not. Also, you should use only backup dis-
tribution files obtained from the host upon which the original station is running for the source of the
migration.
Most of the time there will be one station in the backup that is to be migrated, or at most only a few. If there
is more than one station, you will be shown a list of the available stations in the backup. Then you will be
prompted to enter a choice selecting which station to migrate. Following, is an example of migration tool
output when run on a backup containing nine stations:
June 1, 2020 29
INFO [09:48:50 29-Apr-15 EDT][sys] Niagara runtime booted

("C:\niagara\niagara-4.0.13.3.550") on Win-CE9A-87C6-1526-58EF
[09:48:50 29-Apr-15 EDT][migration]
------------------------------------------------------------
[09:48:50 29-Apr-15 EDT][migration] Migrating station backup
_localhost_demo10_4.dist to backup_localhost_demo10_4.dist
The following station folders were found in this backup:
1 badCop
2 badCop_oldPwds
3 cgAxBac
4 cgOrdsAx
5 demoAppliance
6 goodCop
7 j38
8 nccb11320
9 nccb11602s1_ax
Please select a station from the backup to migrate:
8
Station to be migrated: nccb11320
------------------------------------------------------------
Migrating station nccb11320 to nccb11320
Se t ti n g Ba ck up S er vic e prope r ti e s
Prior to making a station backup, set properties as needed in the running station’s B a c k u p S e r v i c e . By de-
fault, backups exclude both the history and alarm databases. Other items are also excluded, such as prior
saved station database copies, console outputs, and lock files. In most cases, you want to migrate history
and alarms databases with your station to Niagara 4, so you need to modify default properties.
Prerequis i tes :
Stations are configured and running on a host compatible with Niagara 4.
In general, this is the recommended backup method for all platforms, and the only supported method when
making a local backup at the Supervisor PC.
Step 1 In Workbench, open the station and access the B a c k u p S e r v i c e property sheet.
Related BackupService properties shown above are:

a. In the BackupService for each AX-3.8 station to be migrated (whether host or Supervisor):
E x c l u d e F i l e s : remove *.hdb; *.adb;
E x c l u d e D i re c t o r i e s : remove file:^history and file:^alarm
b. In the Supervisor station’s BackupService, if configured for provisioning:
E x c l u d e F i l e s : remove *backup*;
This allows prior station backups to be brought over to the new N4.0 Supervisor.
30 June 1, 2020
Step 2 Review the Exclude Files and Exclude Directoriessettings and make adjustments as neces-
sary. These two properties apply to Fox online backups, that is, backups you initiate while the sta-
tion is running.
Step 3 The bottom two exclude properties apply when you initiate an offline backup with the station
stopped, using a platform connection and the P l a t f o r m A d m i n i s t r a t i o n view. By default, alarms
and histories are included (no Offline Exclude Directories entries, also as shown above).
N O T E : Make only online Fox backups (with station running) for any local station, such as a Supervi-
sor. Otherwise, if you run an offline backup from the P l a t f o r m A d m i n i s t r a t i o n view, it includes all
stations that may be on that platform. The migration tool rejects such a backup file, as it expects
only a single station to be in the backup file. Online Fox backups are more convenient to run than
offline backups.
Step 4 S a v e any changes made.
Examples
The following figure shows an example BackupService configured in JACE station.
F ig ure 10 Example BackupService properties in JACE station
Note that Exclude Directories still includes file:^dataRecovery (not useful in migration).
The following figure shows an example BackupService in a Supervisor station that is configured for
provisioning.
F ig ure 11 Example BackupService properties in Supervisor station configured for provisioning
Note that Exclude Files has no entry for: *backup*; (to allow prior provisioning backups to be brought
over to the N4 Supervisor).
Ma ki n g sou rce st a ti on ba ck u ps
A station backup (.dist file) from a B a c k u p command is the preferred archive source when migrating AX-
3.8 station.
P re re q u i s i t e s :
June 1, 2020 31
The station’s BackupService is configured appropriately.

Step 1 Using Workbench, you can make either a online backup (typical) or an offline backup.
• For an online backup, right-click the S t a t i o n node and select Backup Station.
The station continues running while first it saves is configuration locally, then saves a backup .
dist file in the backups folder of your niagara_home (install) folder.
• For an offline backup, make a platform connection, stop the station from the A p p l i c a t i o n D i -
r e c t o r, then, from the P l a t f o r m A d m i n i s t r a t i o n view, select B a c k u p .
NOTE:
An offline backup applies to JACE stations only. For any local station, such as a Supervisor, you
must make an online Fox backup (with station running).
After the backup completes, you may restart the station so that it can continue working while
you run the migration tool in preparation to convert the platform.
Step 2 As a best practice, consider renaming the resulting backup .dist file to a short, meaningful name.
This simplifies typing in the source .dist file name in the command-line migration tool. Do not re-
name the .dist extension.
For example, if the file name is backup_stationName_141221_0757.dist, shorten it to: sta-
tionName.dist, where stationName is a logical station name.
Step 3 If the new Supervisor or engineering workstation is on a different PC, copy the backup .dist file
to a location on that PC.
If the new station is on the same PC, simply leave all the backup .dist files in the default backups
folder.
For best performance, do not save backup.dist files in the Niagara 4 System home or User home
directories. The files can be located anywhere else, for example: C:\AxBackups.
Step 4 Repeat this procedure for all AX-3.8 stations to be migrated.
Sec ure l i cen se fi le s

Any converted platform (controller, Supervisor, or workstation) requires Niagara 4 license file, as existing AX
license files are incompatible.
• Before upgrading licenses, back up existing NiagaraAX license files for Windows hosts, and store them in
a safe place.
• You can perform migration work on all archived AX-3.8 stations without all N4.0 licenses secured, pro-
vided that you have at least one N4.0 Supervisor or engineering workstation converted and licensed.
However, you should not start upgrading controllers without first securing each license in preparation for
the upgrade process.
N O T E : The Niagara 4 license is not backward compatible with any NiagaraAX install.
• A controller, converted to N4.0 uses the same host ID as before the conversion. Provided its operating
system remains unchanged, a converted Supervisor PC or engineering workstation also uses the same
host ID as before the conversion.
Any new installation of Niagara 4 (N4.0) on a PC calculates the host ID for the first time. The end of the in-
stallation typically generates a “license request form” for web browser submittal, and includes this calcu-
lated host ID.
You reference the host ID when you request each N4.0 license.
• You need to submit the license request and receive either the license file, or confirmation of it on the li-
censing server, before you can use Workbench. For related details, refer to the Niagara 4 Installation
Guide.
32 June 1, 2020
• When you receive a new N4.0 license file for your Supervisor, do not copy it back to any NiagaraAX
home’s licenses folder on the same PC—otherwise Workbench no longer works. This can also occur if
NiagaraAX host downloads the (N4) license offered by the licensing server.
In hybrid systems that combine both N4.0 and AX-3.8 hosts, you need to retain Workbench to use for possi-
ble station modifications to controllers that remain at AX-3.8.
Run the migration tool

Included with Niagara 4 Supervisor or engineering workstation is a command line utility that you run from a
console. This utility is known as the N4 migration tool or migrator.
About the migration tool

The migration tool takes a source file, typically AX-3.8 station backup .dist file, and outputs a migrated
N4.0-compatible station folder. You can then use Workbench to open a platform connection to the target
platform (for example, a converted controller), and install this station using the N4.0 platform Station
Copier.
Important points to remember are:
• A source backup .dist file is not harmed in any way, regardless of the migration outcome.
Migration output always goes to a different location, along with a text log file that contains execution
details.
• The migration tool does not require AX-3.8 installed on the same PC, only a path to the source backup .
dist files.
• You run the migration tool from the standalone Niagara C o n s o l e window, typically launched from the
Windows Start menu.
The following is the log generated while running the migration tool on a very simple Supervisor station back-
up file. The migrator ran in a standalone Niagara C o n s o l e window.
N O T E : Running the migrator in the embedded Workbench Console is not supported, as it does not properly
process the necessary user inputs that may be required if your NiagaraAX station contains passwords that
need to be encrypted with a pass phrase.
June 1, 2020 33
Fi gu re 12 Example migration tool processing a Supervisor station backup

-----------------------------------------------------------------------------–-
C:\Niagara\Niagara-4.1.xx.xx>n4mig C:\niagara\niagara-3.8.111\backups\
backup_Supvsr_150526_1545.dist
INFO [15:48:41 26-May-15 EDT][sys.registry] Up-to-date [92ms]
INFO [15:48:41 26-May-15 EDT][sys.registry] Loaded [32ms]
INFO [15:48:42 26-May-15 EDT][sys] Niagara runtime booted
("C:\Niagara\Niagara-4.1.xx.xx") on Win-23A9-FCD0-B958-4E02
[15:48:42 26-May-15 EDT][migration]
-----------------------------------------------------------------------------------
[15:48:42 26-May-15 EDT][migration] Migrating station
backup_Supvsr_150526_1545.dist to backup_Supvsr_150526_1545.dist
Station to be migrated: Supvsr
-------------------------------------------------------–---–---–---–---–---–---–--
Migrating station Supvsr to Supvsr
Migration Templates:
1: Controller Migration Template (ControllerMigrationTemplate.ntpl)
2: Supervisor Migration Template (SupervisorMigrationTemplate.ntpl)
You can also use 'c' for default Controller and 's' for default Supervisor template.
Please select a Migration Template: 2
Using Migration Template SupervisorMigrationTemplate.ntpl
Completed Migration
Source: C:\Users\John\Niagara4.0\Rocket Industries\migTemp\Supvsr
Target: C:\Users\John\Niagara4.0\Rocket Industries\stations\Supvsr
Migration Report: C:\Users\jDoe\Niagara4.0\Rocket Industries\stations\Supvsr_miglog
_1505261548.txt
Important Migration Notes - see Migration Report for details

Using Migration Template SupervisorMigrationTemplate.ntpl
config.bog: REMOVED all uses of type niagaraDriver:NiagaraFoxService in bog
In the example above, the migration tool was launched with only the “n4mig” command and the source
backup .dist file path, without any options or explicit migration output location. As shown, the migration
template was not specified, so the tool paused and prompted for the migration template (1 or 2). After this
was entered, the tool continued processing and completed the migration.
The migration tool posts information while processing the backup .dist file. By default, the migration out-
put goes to the stations folder of your Workbench U s e r H o m e , as shown in the following figure.
34 June 1, 2020
F ig ure 13 Example migration tool output in Workbench User Home (station folder, migration log file)
In this example, notice that the migration process created a Supvsr folder and an associated log file in the
stations folder. The target station name is automatically determined from the station name inside the sta-
tion backup .dist file.
Entries in the log file (migration report) display source and target locations for items written, actions per-
formed, and so on. If needed, you can use command line options to create a greater level of log detail.
Console choice for migration

You should use only the Niagara console and not the embedded Workbench Console to run the migration
tool.
For migration , use the standalone Niagara command line console window, which you typically launch using
the shortcut from the Windows Start menu. You may also use a standard Windows command line tool avail-
able at [C]:\windows\system32\cmd.exe, for example.
June 1, 2020 35
I M P O R T A N T : The embedded console, that is, the Console prompt available within Workbench (shown
here), cannot be used for migration purposes.
Running the migration tool

With Niagara 4 installed on your PC, you run the migration tool on the AX-3.8 station backup .dist file to
migrate a station, or run it on a saved AX-3.8 BOG file (.bog) if necessary. NiagaraAX does not have to be in-
stalled on this PC—although in many cases, it may be.
N O T E : For any station that uses modules made using the ProgramModule feature, you will need to migrate
those modules to N4 (refactoring them) before the station can be successfully migrated. See Migrating mod-
ules made with the ProgramModule component, page 39.
You must have access to saved AX-3.8 station backups, for migrating stations. See Making source station
backups, page 31.
Running the migration tool

Step 1 At the PC, open a standalone Niagara Console window using the shortcut from the Windows Start
menu.
N O T E : Do not use the Workbench embedded Console because it cannot accept keyboard inputs,
and thus it hangs on input selections.
If you have a number of station backups in a single folder to migrate, it may be simplest to change
the console window’s current directory to that location. For example, your console prompt may be
similar to: C:\niagara\niagara-3.8.111\backups>
36 June 1, 2020
The above would apply if you have both NiagaraAX-3.8 and Niagara 4 installed on your PC. Alter-
natively, enter the full path to source station backup .dist files in the commands.
Step 2 Enter the migration tool command (n4mig) using syntax that specifies the source backup file, at a
minimum. By default (if left unspecified), the migration output targets the stations folder of your-
Workbench U s e r H o m e . Generally, this is the recommended method: specify source file only.
If you changed the console’s current directory to the location of station backups your command could be:
n4mig -t:2 backup_Supvsr_141117_1707.dist
(to migrate a backup .dist with that default file name, for a station named “Supvsr”).
C A U T I O N : Do not attempt a station migration using theWorkbench embedded Console. This console can-
not accept keyboard inputs, and thus will hang waiting for your input selection. The only workaround at that
point is to restart Workbench.
While the migration tool runs, operation activity is reflected in the console window. When finished, the end-
ing lines in the console window state where the target output results and log file can be found.
For reference details on the n4mig command, see Migration tool command usage, page 37. For general in-
formation, see About the migration tool, page 33.
Migration tool command usage

A number of commands may be added on the migration tool command line.
n4mig [options] <source> [target]
Parameter Re qu ired? De scription / Notes
source Yes Typically the AX-3.8 station backup .dist file, but it may also be a bog file, palette file, station folder,
or a zip archive of a station folder. You can enter an absolute file path, or a path relative to the current
directory of the Niagara 4 console.
target No (Optional) The output station folder name to write the migrated station or BOG file. An absolute file
path or a relative path can be entered. Any relative path is relative to the stations subfolder of your
Workbench U s e r H o m e , that is C:\Users\userName\Niagara4.x\<brand>\stations
T I P : Generally, in a station migration you do not specify a target, as you typically want to retain the ex-
isting station name in the migrated station. If it is not specified, the migration tool derives it from the
name of the source, its parent folder, or the name of a folder within the archive—whatever fits best.
The exception is a source named config.bog. In that case, the target is required. If the supplied target
is a relative path, the migration tool targets the result relative to the root of niagara_user_home/
stations.
If you do specify a target folder name, it cannot already exist (by default an existing station is never
overwritten); however, any file path above it must exist. For a related example, see Migrator syntax
example 2, page 39.
Options Description / Notes
-version Print NRE version information for this Workbench instance.
-log:level Specify the log level, where level is one of the following:
all, finest, finer, fine, config, info, warning, severe, off
The default is “info”. This produces the text log file migration report, which lists all the changes made
to the AX station as a result of the migration. This file is created in the root of the stations folder in
your Workbench U s e r H o m e . Of course the default (“info”) also includes any more problematic
“warning” or “severe” messages.
After becoming familiar with migrations, you could specify the “warning” log level instead—that lists
only the more problematic entries, shortening the log report.
June 1, 2020 37
Options D escription / Notes
-keepTemp Do not clean up temp directories after execution. If used, a “migTemp” folder is left in your Work-
bench User Home, with various subfolders of intermediate files used in the migration process. Only
use -keepTemp option for troubleshooting purposes.
-showSystemLogs Shows messages from all loggers; does not hide non-migrator logs.
-help, -? Print the usage information. By default you see this same information if you enter the n4mig command
alone, that is without any other parameters or options.
-o Overwrite the target station folder, if it already exists.
-t:<template> When migrating a station backup .dist, this is the template type to use, where template is one of
the migration station template types available on your system. Choices are:
1 = Controller migration template (for example, ControllerMigrationTemplate.ntpl)
2 = Supervisor migration template (for example, SupervisorMigrationTemplate.ntpl)
NOTE:
You can also use 'c' for the default Controller and 's' for the default Supervisor template.
Default migration template files listed above are found in your S y s H o m e folder under !defaults/
workbench/migrationTemplates. An empty migrationTemplates subfolder is also created in your
Workbench U s e r H o m e , to store any customized migration station template files. See the Niagara
Templates Guide for more details on working with Niagara 4 templates.
Migrator syntax example 1

Here, the current directory of the Niagara console window has been changed to the backups folder of the
AX-3.8 installation home, such that the prompt is C:\niagara\niagara-3.8.111\backups>
A command is entered specifying only the source, and not target (recommended for station migration).
C:\niagara\niagara-3.8.111\backups>n4mig -t:1 backup_J300E_W_150210_1715.dist
The migration tool processes the J300E_W backup .dist file in the current directory, as JACE station, and
the target output goes under the stations folder of your current Workbench U s e r H o m e . The standard log
file (migration report) is also created in the root of the stations folder.
So here, migration produces these items:
• C:\Users\userName\Niagara4.x\<brand>\stations\J300E_W (complete station folder)
• C:\Users\userName\Niagara4.x\<brand>\stations\J300E_W_miglog_150212_0846.txt
(log file or “migration report)
The name of the migrated station (folder), in this case “J300E_W”, is determined by the station name inside
the station backup .dist file, and is not affected by the name of the .dist file. Therefore, you could re-
name the source file frombackup_J300E_W_150210_1715.dist to, say, J3Wbu.dist before running the
migration tool, and run the command (again, specifying only the source):
C:\niagara\niagara-3.8.111\backups>n4mig -t:1 J3Wbu.dist
You would have essentially the same results, with these items:
• C:\Users\userName\Niagara4.x\<brand>\stations\J300E_W (complete station folder)
• C:\Users\userName\Niagara4.x\<brand>\stations\J3Wbu_miglog_150212_0847.txt (log
file or “migration report)
This may be useful to reduce the amount of typing in the console when migrating stations to N4.
38 June 1, 2020
Migrator syntax example 2

Here, the Niagara console window has been left at the default N4.0 directory (say when you open it from the
Niagara 4 Console Start menu shortcut), and absolute source and target directories are specified.
C:\Niagara\Niagara-4.1.xx.xx>n4mig -t:2 -log:finer C:\niagara\niagara-3.8.111\back-
ups\backup_BigSup_150210_1730.dist F:\migratedStations\BigSupN4
The migration tool processes the station BigSup backup .dist file from the absolute source path given, as
a Supervisor station, and the target output goes to the absolute “F: drive” location given (perhaps a remov-
able USB drive) in folder migratedStations\BigSupN4. The log file (migration report) is also created
there, but with finer level detail than the default.
So in this case, migration produces these items:
• F:\migratedStations\BigSupN4 (complete station folder)
• F:\migratedStations\BigSupN4_miglog_150212_0835.txt (log file with finer detail)
The folder F:\migratedStations must already exist, or else the command fails. The specified target sta-
tion folder BigSupN4 must not already exist, or else the command fails—it never overwrites an existing sta-
tion folder (unless the -o option switch is included in the command).
The target station folder determines the migrated station’s name, unlike when not specifying a target station
folder. In this example, the output station folder (and N4 station name), will be BigSupN4, which is different
than the one in the source backup .dist file. Generally this is not recommended when migrating stations,
especially if they are part of a NiagaraNetwork of stations, as other stations store remote station names (in
configurations of NiagaraStation and StationRecipient components, as two examples).
Therefore, when a migrating a station from an AX-3.8 station backup .dist file, it is typically best to specify
only the source .dist file name, and not specify any target. An example of this is described in Migrator syn-
tax example 1, page 38. After the migration tool completes, if needed, you can then manually copy or move
the migrated station folder to another location. For example, you could copy the migrated station folder
under a previously created “F:drive” location, say F:\migratedStations.
Mi gra tin g m od ule s m ad e with the Prog ra mMod ul e c omp on ent

If your installation uses custom modules of Program objects (components) made using the ProgramModule
component, they must be refactored for Niagara 4 before using them with any migrated AX-3.8 stations. If
you do not migrate the, Program objects they will be deleted in the migrated station.
Prerequisite: You need a working knowledge of the AX-3.8 ProgramModule (available in the program mod-
ule’s palette), including its P r o g r a m M o d u l e B u i l d e r view.
F ig ure 14 ProgramModule in AX-3.8 program palette
In the NiagaraAX installation, there are different ways the ProgramModule feature can be used to create ver-
sioned module JAR files that contain one or more Program objects:
• ProgramModule components copied into a folder under the Workbench file space of the local host, such
as a Supervisor, each saved as a BOG file. These ProgramModule components contain Program objects
copied from stations, used to build local modules with these Programs.
June 1, 2020 39
N O T E : This is the recommended use of ProgramModules.

Fi gu re 15 ProgramModules saved as BOG files in the Workbench file space
The figure above shows two such ProgramModule BOG files, under an “AprogBldr” folder in the Workbench
home. The resultant module JARs are also shown in the local modules folder.
• One or more ProgramModule components copied into a station run on a local host, such as a Supervisor.
Typically, this station also has the original Program objects that are now replicated in the station via local
modules built by the ProgramModule(s).
• Simply using the Workbench program palette and the ProgramModule in it, pasting in Program objects
from stations, then compiling and building local modules with these Programs. In this case, ProgramMod-
ules are not persisted—only the modules built using them.
N O T E : Such modules cannot be refactored for N4, unless you first use Workbench to copy ProgramMod-
ules from the program palette into a folder in the Workbench file space, and reconfigure again. Once
saved as AX-3.8 BOG files, you can run migration on the ProgramModules.
In all but the last case, migration of the modules is straightforward. Migration requires running the source
AX-3.8 ProgramModule through the migration tool (either as a BOG file, or if within a station, in a station
backup .dist file). Next you use Workbench on each migrated ProgramModule to recompile the contained
Program(s) and then rebuild the module, which refactors it for Niagara 4.
Mig r at in g modu le s f rom Progr amMo du le s sa ved a s BOG fi l es

If you have saved one or more ProgramModule components in your Workbench file space, you can run the
folder (BOG) file containing them through the N4 migration tool.
If necessary, you can do this on a PC still running an AX-3.8 Supervisor station, but with both Workbench and
Workbench installed.
Step 1 At the Workbench PC, open a console. This can be either a standalone Console window or the Con-
sole available in Workbench. See Console choice for migration, page 35.
Step 2 Enter the migration tool command (n4mig) using syntax that specifies the source folder with Pro-
gramModule BOG files. If using an absolute file path, an example command could look similar to:
n4mig C:\niagara\niagara-3.8.111\AprogBldr
for the AprogBldr folder as shown in the previous Figure 15 Figure 17 on page 34, page 40. Leav-
ing the target unspeciified (as here), results in a subfolder under stations in your Workbench U s e r
H o m e ”.
40 June 1, 2020
N O T E : After the tool finishes, you can simply cut and paste this “non-station” folder to a better
location.
While the migration tool runs, operation activity is reflected in the console window. When finished,
the ending lines in the console window state where the target output folder and log file can be
found. As shown above, you are not prompted for a station “type” (unlike if migrating the AX back-
up .dist file).
Step 3 If the target folder was created in your stations folder, move (cut and paste it) to another location
in your Workbench U s e r H o m e . You can do this in the Nav tree, using right-click commands.
Step 4 In the Nav tree, expand the target folder to see the BOG file(s) with ProgramModule(s).
Step 5 Double-click a ProgramModule for its P r o g r a m M o d u l e B u i l d e r view.
Step 6 Right-click one of the contained Programs and select V i e w s → P r o g r a m E d i t o r (as above).
Step 7 In the P r o g r a m E d i t o r, click Save & Compile (P

Pr o g r a m E d i t o r → S a v e & C o m p i l e ). Activity oc-
curs in the console area at the bottom of the Workbench window.
If successful, the Program status should be up-to-date, and the S a v e B o g icon should be
available.
Step 8 Click S a v e B o g .
N O T E : If a Program compile fails, you must make one or more modifications to that Program,
working in its P ro g r a m E d i t o r.
Step 9 Repeat steps 6 and 7 for all Programs in the selected ProgramModule, so that all Programs have
been successfully compiled and saved.
Step 10 Double-click the ProgramModule for its P r o g r a m M o d u l e B u i l d e r view, then click Build.
June 1, 2020 41
As shown above, a popup dialog appears while the module is created. Completion may take sev-
eral seconds. Related details should also appear in the console area at the bottom of the Work-
bench window.
Step 11 If multiple ProgramModules are in the folder, repeat steps 5 through 9 for each one, so that a mod-
ule for each is created. In the example folder shown here, there are two ProgramModules.
As shown above, the modules named yourPrgmModule1-rt.jar and yourPrgrmModule2-rt.

jar were created by the two ProgramModules.
Step 12 When finished migrating modules, close and restart Workbench. This is necessary to update the
registry. Modules should now be ready when running the N4 migration tool on a backup .dist file
of any AX-3.8 station that uses them. See Running the migration tool, page 36.
Mig r at in g modu le s f rom Progr amMo du le s i n a sta t ion d at a base

If ProgramModule components are used within the AX-3.8 station (instead of in standalone BOG files in our
Workbench file space), you need to migrate that station in the standard way, that is using a station backup .
dist file as the source.
Prerequis i tes :
However, before installing that migrated station, or any other migrated station that uses modules produced
by it, you must use Workbench to get refactored modules from its ProgramModules. This means recompiling
and saving Programs in each ProgramModule, then running a build on each one. Then you must migrate that
station again (now that the necessary refactored modules are available).
NOTE:
If necessary, you can do this on a PC still running the AX-3.8 Supervisor station, but with both Workbench
and Workbench installed.
Step 1 Run the migration tool on the saved AX-3.8 station backup .dist file.
Step 2 In the Workbench Nav tree, expand the stations folder under your U s e r H o m e , to see this
newly-migrated station.
Step 3 Expand the station’s config.bog file, and navigate to the first ProgramModule.
Step 4 Double-click the ProgramModule for its P r o g r a m M o d u l e B u i l d e r ni
42 June 1, 2020
Step 5 Right-click one of the contained Programs and select V i e w s → P r o g r a m E d i t o r (as above).
Step 6 In the P r o g r a m E d i t o r, click Save & Compile (P

Pr o g r a m E d i t o r → S a v e & C o m p i l e ). Activity oc-
curs in the console area at the bottom of the Workbench window.
If successful, the Program status should be up-to-date, and the S a v e B o g icon should be avail-
able. Click S a v e B o g .
N O T E : If the Program compile fails, you need to make one or more modifications to that Program,
working in its P ro g r a m E d i t o r. See Modifying Program objects, page 45.
Step 7 Repeat steps 5 and 6 for all Programs in the selected ProgramModule, so that all Programs have
been successfully compiled and saved.
Step 8 Double-click the ProgramModule for its P r o g r a m M o d u l e B u i l d e r view, then click Build.
As shown above, a popup dialog appears while the module is created. Completion may take sev-
eral seconds. Related details should also appear in the console area at the bottom of the Work-
bench window.
Step 9 If multiple ProgramModules are in the folder, repeat steps 4 through 8 for each one.
June 1, 2020 43
As shown above, the module named aaPrgmModule.jar was created by the ProgramModule.
Step 10 When done migrating modules, right-click the station’s config.bog file and click S a v e .
Step 11 Close and then restart Workbench. This is necessary to update the registry. Migrated modules
should now be ready when running the migration tool on AX-3.8 station backup .dist files, includ-
ing the station with the source ProgramModules.
Migration details
Details on migration are in the following reference topics:
Migration execution
The migration tool migrates a source artifact to its appropriate N4 target. The typical source is AX-3.8 sta-
tion backup .dist file. The output (target) is a station folder, in your Workbench U s e r H o m e .
At the conclusion of the tool execution, you see these Source and Target locations listed:
09:31:37,355 INFO [migration] Completed Migration
Source:C:\niagara\niagara-3.8.111\backups\backup_Supvsr_141117_1707.dist
Target:C:\Users\John\Niagara4.x\<brand>\stations\Supvsr
You can then install this migrated station into the daemon User Home of Niagara 4 platform, for example
the local platform if a Supervisor, or in a remote platform, such as the migrated station for a controller that
has been converted.
Upon execution, the migration tool scans each folder and file in the backup recursively, and migrates each in
turn as appropriate. Certain folders, such as the folder tree comprising the history database of a station, are
handled separately.
N O T E : Any environment files in the backup .dist that are outside of the station folder, for example, prop-
erties files in the AX platform’s !/lib folder, are not migrated. If you know of any that were edited from de-
fault values, and they still apply to N4 platforms, you may need to re-apply changed values in the platform
after upgrading to Niagara 4 (however, do not copy entire AX files into the N4 environment).
If desired, do this after installing the migrated station.
For each migrated artifact, the migration tool determines if a FileMigrator is registered to handle migrating
that file type. If no special migrator is registered, the default migration is to simply copy the file as is from
the source location to the target location.
In the case of BOG file migration, the BogMigrator opens the .bog file, and walks the XML element tree. For
each element it encounters, it checks to see if there is a BogElementConverter registered to handle convert-
ing that type.
• If no converter is registered, the type is simply passed through and re-encoded.
44 June 1, 2020
• If a converter is registered, the converter is given the element to process.

• If the element cannot be decoded, this is usually because the module that contains the type existed in
AX but was removed for N4. In this case the element will be removed from the station.
• In the case where the N4 equivalent module exists, the registry check provides a converter that can con-
vert the obsolete type into the appropriate N4 type.
Mi gra tio n rep ort ( lo g fi le )

The log file produced each time you run the migration tool answers the question “What did the tool do?” At
the default info log level, the migration report lists the changes made to migrate the source to the target.
If needed, you can have the migration tool generate even more detailed output by specifying another log
level (config, fine, finer, finest) as an option in your command.
You should always review the migration report to make sure that:
• Nothing was removed that is critical to your station’s operation.
• There were no failures, or items that could not be migrated by the tool.
In some cases, issues may require post-migration “cleanup” tasks.
In spe ct in g mig ra t ion re por t s (l og f il e s)

We recommend you inspect migration log files for:
• Migration failures
If any migration failure occurs, this will be noted in the report. You should report any migration failures to
your support channel. In some cases it may be necessary to modify this part of the station manually, and
your support channel should be able to help with that.
• Program compilation failures
The migration tool attempts to recompile all P r o g r a m objects in the station with the new modules. In
some cases, this may not be successful. Programs that cannot be compiled will be noted in the report,
and you will need to modify the program manually to allow it to compile.
• Removed station components
Station components whose type or module does not exist in N4, and for which there is not a type to mi-
grate to, are removed. This should not occur frequently, as the modules that were removed for N4 were
generally unused or deprecated modules.
If you find that a component has been removed that should not be, please report this to your support
channel, as it may be that a converter needs to be developed for that type.
• Any WARNING or SEVERE messages
These messages are included in the migration report prefixed by “WARNING” or “SEVERE”, as appropri-
ate. They indicate a more significant issue, likely a problem with the tool execution. You should inspect
items referenced in such messages to make sure migrated artifacts are what you want.
Post-migration database tasks

Sometimes you may need to perform post-migration tasks on migrated station databases, using Workbench.
For example, certain Program objects may need to be changed and recompiled in Niagara 4, as flagged in
the migration report (log file). Other possible station changes may be needed too, in certain circumstances.
Mod i fyi ng Pro gra m ob j ects

The migration tool attempts to compile all NiagaraAX Program objects (components) in the station to be
compatible with Niagara 4, flagging any that fail to compile properly in the migration report, or log file.
June 1, 2020 45
Using Workbench, you should modify any such Program objects until they recompile successfully, before in-
stalling the station.
Prerequisite: You must have a working knowledge of Java programming, Program objects, and the P r o g r a m
E d i t o r view in Workbench. Access to Developer-level Niagara 4 documentation may be needed.
Modi fyi n g a nd re compi li n g Progr a m obj e ct s offl in e

You can open a station offline in Workbench to modify and recompile Program objects if necessary, resaving
the station (config.bog file) when done. If necessary, you can do this on a PC still running an AX-3.8 Supervi-
sor station, but with both Workbench and Workbench installed.
Step 1 Open Workbench, if not already open.
Step 2 In the Nav tree, expand M y F i l e S y s t e m and navigate to the station folder of the migrated station
that had Program compilation failures.
Typically, such stations are under your U s e r H o m e , under the s t a t i o n s folder.
Step 3 Expand the station folder, and expand the config.bog file under it.
Step 4 In the station database, navigate to a Program object identified to have a “compilation failure” in
the migration report (log file).
Step 5 Open the P r o g r a m E d i t o r view for the component. (One way is from the Nav tree, right-click the
Program and select P ro g r a m E d i t o r ).
Step 6 In the P r o g r a m E d i t o r menu or toolbar, click Compile.
One or more errors result in the Console area at the bottom. Often all possible errors are not in-
cluded, as the compiler stops on failure and outputs an error. Therefore, once you correct one or
two errors, subsequent compile attempts may uncover other errors.
46 June 1, 2020
In this example, errors shown relate to the methods getOpenAlarms() and getRecord(BOrd)
having moved from the BAlarmService class to a new AlarmSpaceConnection class, located
in the javax.baja.alarm package of the alarm module. To fix this, you would need Developer-
level documentation on “breaking changes” in Niagara 4 Alarm API, and make the required
changes in the program code (further details are outside the scope of this document).
Depending on the Program object, other possible compile errors may require changes in its pack-
age import definitions (IIm p o r t s tab).
Step 7 Continue with changes until the Program compiles successfully, and click S a v e & C o m p i l e and
also Save Bog.
Step 8 Repeat steps 4 through 7 for each Program object identified to have a compilation failure.
Step 9 When finished, in the Nav tree right-click the station’s config.bog file, and ensure S a v e is
dimmed. If available (not dimmed), click S a v e .
Considerations if a station functions as an oBIX server

With the Niagara 4 addition of the new A u t h e n t i c a t i o n S e r v i c e , any oBIX request to a station must be au-
thenticated using the “HTTP Basic Scheme” (HTTP Basic Authentication Scheme). If your station has an
O b i x N e t w o r k that operates as an oBIX server, note that it is not possible for the N4 migration tool to deter-
mine which station users were used for oBIX authentication.
Since the HTTP Basic Authentication Scheme is assigned on a per-user basis, the migration tool updates the
authentication by completing the following steps:
1. Adds an HTTP Basic Authentication Scheme from the baja Palette to Services -> Authentication Service
-> Authentication Schemes
2. Creates a new user (the default name is "obix"). If a User with the name "obix" already exists, the Migra-
tion Tool will try "obix1", "obix2", etc. until a free username is found.
3. Sets the Authentication Scheme Name of the User created in Step 2 to the HTTP Basic Authentication
Scheme added in step 1.
N O T E : The password assigned to this user is the default password. It cannot be used by oBIX clients until
you manually assign a password.
oBIX authentication configuration

After migration, you MUST perform the following additional configuration to allow OBIX clients the proper
access to the station's oBIX server. These requirements apply to the default "obix" User created during mi-
gration or any other User that you are using to allow oBIX clients access.
June 1, 2020 47
Step 1 Open Workbench, if not already open.

Step 2 In the Nav tree of the migrated oBIX server station, expand M y F i l e S y s t e m and navigate to the
station folder.
Typically, such stations are under your U s e r H o m e , under the stations folder.
Step 3 Expand the station folder, and expand the config.bog file under it.
Step 4 Expand S e r v i c e s > U s e r S e r v i c e and double-click on the newly created “obix” user to open the
E d i t U s e r dialog box. The user that the migration tool created is a user name begining with the let-
ters “obix”, such as: “obix”, “obix1”, “obix2”, etc.
Step 5 In the E d i t U s e r dialog box, make the following changes:
• change the user password from the existing default value to a password that complies with the
Niagara 4 password configuration requirements.
• assign a Role to “obix” user that allows access to the necessary station components that you
desire to be accessible to oBIX clients.
• verify that the user permissions include read access to the ObixNetwork in order to provide ac-
cess to the ObixNetwork in order to provide access to the oBIX Lobby of ther server.
Step 6 Click the O K button to close the dialog box and save the station changes (e.g. in the Nav tree,
right-click c o n f i g . b o g and click S a v e ).
Tips for Configuring oBIX Authentication

The following list includes tips and considerations for configuring oBIX stations after migration.
• Assign Role from a previous user
During migration, the Niagara Role is created for each AX User in the station. If the AX station was being
accessed by OBIX clients, you can probably pick the User that clients were using, and simply select the
Role with that name as a starting point for N4 oBIX client access.
• Separate Users for each Client
Consider using a separate User for each oBIX client (or client type) that accesses the station's oBIX server.
This is another way to increase the security of your installation by encapsulating access and giving each
user the minimum access necessary to accomplish the needed function.
P re l i m i n a r y c h e c k o u t o f m i g r a t e d s t a t i o n s
Prior to installing stations, we recommend that you use Workbench to open each of the migrated stations
offline, that is in the stations folder under your Workbench U s e r H o m e , and check it out carefully. If neces-
sary, make and save any changes.
As for migrated JACE stations, if you have an extra, available JACE controller (of the same model type) that
has been converted, you can install a migrated station and observe startup behavior. However, expect many
errors from driver-sourced items—as you would for any unit disconnected from device networks.
Upgrade/convert platforms and install stations

Once you have stations migrated, you can upgrade/convert platforms to N4.0 and install the migrated sta-
tions. Typically you upgrade a Supervisor before upgrading any of its controllers.
Often, you use the same PC to run the migration tool, on the Supervisorstation archives, as well as the sta-
tion archives of all controllers being migrated. When this is the case, you usually do not choose to “Install
and start the (N4.0) platform daemon” when first installing the Niagara 4 software. This lets the AX-3.8 plat-
form daemon continue to host the Supervisor station while you use the migration tool. It also lets you be-
come familiar with Workbench, and yet still haveWorkbench available for interim tasks.
48 June 1, 2020
N O T E : When installing Niagara 4 software on the Supervisor PC, be sure to select the option “This instance
of Niagara 4 will be used as an installation tool”. Refer to the Niagara 4 Installation Guide for details.
Alternatively, you may have used a different PC to run the migration tool, and perhaps even to (eventually)
use as the new Supervisor host for the job.
As different combinations are possible in a transition such as this, use the procedures and steps provided to
serve as a general guide.
Copying the Supervisor station

The first step to preparing the Supervisor station is to copy the migrated station.
P re re q u i s i t e s : You have secured the required licenses and the station databases are ready to install.
Step 1 After installing Niagara 4 on the Supervisor PC and starting Workbench, open a platform connec-
tion to the AX-3.8 Supervisor station and stop the station.
Step 2 At the N4.0 Supervisor PC (with access to N4.0-migrated station folders), install and start the N4.0
platform daemon.
For example, from the S t a r t menu, select A l l P r o g r a m s >Niagara 4 4.0.3 → I n s t a l l P l a t f o r m
Daemon
In some cases, this daemon may already be running; however re-installing causes no issues.
Step 3 Start Workbench (if not already started) and click T o o l s → O p t i o n s → S t a t i o n C o p i e r O p t i o n s .
The Options window opens.
Step 4 Set Copy Remote Station Alarm Data and Copy Remote Station History Data to true, and
click O K
Step 5 Open a local platform connection
(in the Nav tree, right-click M y H o s t , and choose O p e n P l a t f o r m ).
Step 6 After platform login, go to the S t a t i o n C o p i e r platform view.
Ready-to-install migrated stations are on the left side, in your Workbench User Home, and there is
no station installed on the right side, in the daemon user home (localhost).If your migrated station
folders are not on the left side, copy them into your User Home. For example in: C:\Users\user-
Name\Niagara4.x\<brand>\stations
Step 7 Select the migrated Supervisor station, and copy (install) to the daemon user home.
June 1, 2020 49
Step 8 To transfer in this station copy, choose to Copy files from selected directories, and START
AFTER INSTALL... and AUTO-START... and click N e x t . As shown below, select all station
folders
Step 9 Select all station folders to be transferred and click N e x t → F i n i s h .
50 June 1, 2020
Performing station cleanup

After copying the Supervisor take a moment to confirm that the copy was successful and make any needed
changes to properties.
When the station is copied, open the A p p l i c a t i o n D i r e c t o r and observe startup messages. Then open a lo-
cal station (Fox or Foxs) connection to the Supervisor when it has started, and begin preliminary checkout.
F ig ure 16 Network Manager view
The figure above shows N4.0 Supervisor’s N i a g a r a N e t w o r k shortly after migration.

Stations that represent JACE controllers in the Supervisor’s N i a g a r a N e t w o r k should be communicating,
where all may still be at AX-3.8 (yet to be converted). For any that must remain at AX-3.8 (JACE-2s for exam-
ple), review, and if necessary, adjust client connection properties.
Save any changes make before upgrading your JACE controllers.
Co ntroll er co nvers io n
Typically, after upgrading a Supervisor, you convert JACE controllers to N4.0—or at least you convert all
those for which you successfully migrated a station. During the N4 commissioning of each JACE, you install
this station as one of the steps in the Commissioning Wizard.
CAUTION:
You must migrate the AX station from the JACE and confirm that the migration was successful first (all Pro-
grams report {ok}, for example), before installing the .dist file.
C o n v e r t i n g a c o n t ro l l e r
Perform the following procedure for each controller for which you have secured N4.0 license, and have suc-
cessfully migrated its station database.
P re re q u i s i t e s :
Workbench is open, you have used it to check the migrated station for this controller, and confirmed that
the migration was successful.
Step 1 Open a platform connection to the controller to be converted, and access the D i s t r i b u t i o n F i l e
I n s t a l l e r.
The list of distribution files opens.
June 1, 2020 51
N O T E : N4 may display the cleanDist or other files for other controllers, but you can select only
the file that is appropriate for your controller. This file is only for a unit already converted to
Niagara 4. If you do not see the appropriate *.dist file, verify that you are in the conversion fold-
er. If necessary, use the buttons at the bottom of the view to navigate and browse for the file.
Point the installer to the !/sw/N4buildNumber folder, for example: !/conversion/
4.0.15.619.
Only one of several listed should be selectable. This is an example of the file for converting a
controller:
aAXtoN4-qnx-jace-npm6e-etfs2048.dist
Step 2 Select the appropriate .dist file and click the I n s t a l l button.
N O T E : Installation clears all data in the controller, including AX licenses and certificates, environ-
ment and properties files, SSL certificates and key files, along with all station data and NiagaraAX
software. The controller’s IP configuration is retained. You must use the default platform creden-
tials to regain access.
Step 3 After this .dist file installs and the controller reboots, re-open a platform connection (port 3011)
using the factory default credentials.
Step 4 If you previously exported SSL certificate stores from this controller, access the platform C e r t i f i -
c a t e M a n a g e r view, and do the following:
a. On the U s e r T r u s t S t o re tab, click I m p o r t , and navigate to select the previously saved public
key certificate (typically common among all platforms at the job).
b. On the U s e r K e y S t o re tab, click I m p o r t , and navigate to select the previously saved private
key certificate unique to this platform.
c. Access the platform P l a t f o r m A d m i n i s t r a t i o n view, click the C h a n g e S S L S e t t i n g s button,
and select the new server certificate you just imported.
d. Run the platform C o m m i s s i o n i n g W i z a r d (right-click the P l a t f o r m node, and select C o m m i s -
s i o n i n g W i z a r d ).
In this initial commissioning of the controller, you typically use all default step selections. This in-
cludes most steps except Install lexicons (but if you use text-based lexicons, select this too).
52 June 1, 2020
In most cases you select to:

• Install the licenses from the licensing server (unless you already have these as files).
• Use runtime profiles RUNTIME and UX, or else RUNTIME, UX, and WB.
• Install the specific station that you migrated for this controller, choosing to:
Copy files from selected directories.
NOTE:
You typically select all directories shown in the migrated station, including the alarm and history
subfolder (to migrate prior alarms and histories). Apart from the migration, this is an unusual
practice. If you are installing the same station in different/multiple platforms, be sure to dese-
lect (clear) the alarm and history subfolders.
• Install all pre-selected software modules required for this station.
• Install all listed core software distribution files.
• Review, and if necessary change, the controller’s TCP/IP configuration.
• You must add at least one new platform admin user in the “Remove platform default user ac-
count” step (initial P l a t f o r m D a e m o n A u t h e n t i c a t i o n dialog). This replaces the factory-default
platform user. Note that in N4, platform credentials require a stronger password than in AX.
The password must be at least 8 characters, with at least 1 digit (numeral). If the password does
not meet this requirement, an error dialog prompts you to create a valid one.
Make note of these platform credentials; you should use a login as such a platform user upon
next access.
NOTE:
For this platform session, Workbench remembers the first platform admin user you created to
replace the factory default platform user. This simplifies re-connection after the controller
reboots.
For related details, see the JACE Niagara 4 Install and Startup Guide. Example screen captures of
a few of these C o m m i s s i o n i n g W i z a r d steps are shown in the Controller conversion examples,
page 55
Step 5 Review and finish the commissioning wizard, to install all selected items and reboot the controller.
After several minutes, the conversion completes, and platform access should be possible.
C A U T I O N : Do not remove power from the controller during this reboot, which may take up to 7
or more minutes to complete. Removing power could easily cause the unit to become unrecover-
able. If desired (and convenient), you can use a serial shell connection to the controller to monitor
progress as files are installed, the platform is rebooted, and the unit is prepared.
June 1, 2020 53
Step 6 Re-open a platform connection to the converted controller, using a new platform account you en-
tered in the wizard. Go to the A p p l i c a t i o n D i r e c t o r and view the station standard output.
Again, there may be warnings and messages, but its station status should change to “running”.
Step 7 In Workbench, open a station connection (Fox or Foxs) to the converted controller, typically using
the admin (superuser) login. Verify the station opens.
Step 8 For each remainin controller to be converted, repeat the above steps
When done with this, all converted controllers should be running stations as N4.0 platforms, as well as the
Supervisor station.
54 June 1, 2020
Con t roll er con ver si on ex amp le s

Following, are example Commissioning Wizard windows when converting JACE controller to Niagara 4.
Example conversion steps
F ig ure 17 Example “Set enable runtime profiles” step
F ig ure 18 Example “Install station” step (pick migrated station)
As shown above, by default all items are selected. If necessary you can de-select any items not wanted.
F ig ure 19 Example platform daemon authentication step (to replace factory platform user)
If this controller was previously provisioned by the AX Supervisor, you may wish to have at least one platform
admin user with the prior user name, and possibly prior password (if it was “strong” before). Otherwise, you
must update the platform connection Credentials property for this station back in the Supervisor station’s
NiagaraNetwork.
June 1, 2020 55
An even better practice might be to add another platform user in the JACE that no person uses to make
platform connections, but is only referenced back in the N4 Supervisor.
Downg rad i ng c ontrol l ers

In some cases it may be desirable or necessary to convert a controller from Niagara 4 to NiagaraAX. During
the commissioning of JACE controller, all station data are deleted. This includes SSL certificates and key files.
Niagara 4 stations cannot be converted to NiagaraAX stations. But, you can install a previously saved
NiagaraAX station during the downgrade commissioning process as one of the steps in the Commissioning
Wizard.
N O T E : Controller downgrade from Niagara 4 removes all data except the controller’s Ethernet TCP/IP con-
figuration. Platform credentials revert to factory defaults. The Niagara 4 license is not retained and
NiagaraAX license is required. All station data is deleted.
D o w n g r a d e p ro c e d u re
Perform the following for each controller to be downgraded, and for which you have secured NiagaraAX
license.
P r e r e q u i s i t e s : To restore an existing station, make sure you have access to the station file, or a backup dis-
tribution file.
Step 1 At the Supervisor, using Workbench, open a platform connection to the controller to be down-
graded, then open the A p p l i c a t i o n D i r e c t o r and stop any running station.
Step 2 With the platform still selected, choose the D i s t r i b u t i o n F i l e I n s t a l l e r from the view selector, navi-
gate to the location of the downgrade distribution file, and click C o n v e r s i o n .
N O T E : Some non-applicable files, such as N4 cleanDist, .dist or other files may be selectable
but, in this case, do not select these files. Click the C h o o s e D i r e c t o r y button to browse to the lo-
cation of the downgrade .dist file, for example: N4toAX-qnx-jace-<npm-model>etfs2048-
clean.dist.
Step 3 Select the appropriate .dist file and click the I n s t a l l button.
N O T E : Installation clears all data in the controller, including AX licenses and certificates, environ-
ment and properties files, SSL certificates and key files, along with all station data and software.
The controller’s IP configuration is retained. You must use the default platform credentials to regain
access.
Step 4 After this .dist file installs and the controller reboots, re-open a platform connection using Work-
bench (port 3011) and the factory default credentials.
N O T E : At this point, the JACE will be at 3.8.38 version. If you need an earlier release AX version,
use the clean .dist files in the AX-3.8 D i s t r i b u t i o n F i l e I n s t a l l e r. This will revert the JACE back
to the base-factory version.
Step 5 Run the platform C o m m i s s i o n i n g W i z a rd (right-click the P l a t f o r m node, and select C o m m i s s i o n -
i n g W i z a rd ). During the commissioning process you can choose to reinstall a station, if you have
one ready, perhaps from a previous backup, or you can restore from a backup as described in the
next step.
C A U T I O N : Do not remove power from the controller during this reboot, which may take up to 7
or more minutes. Removing power could cause the unit to become unrecoverable. If desired (and
convenient), you can use a serial shell connection to the controller to monitor progress as files are
installed, the platform is rebooted, and the unit is prepared.
For more details on commissioning the AX-3.8 controller, see the JACE Niagara 4 Install and Start-
up Guide.
Step 6 If you did not restore a station with the previous commissioning step, make sure you have a backup
.dist file and a platform connection to the rebooted AX-3.8 controller. Select the D i s t r i b u t i o n
F i l e I n s t a l l e r view and click on the B a c k u p s button or C h o o s e D i r e c t o r y button to navigate to
the appropriate dist file location.
56 June 1, 2020
Step 7 Select the .dist file and click the I n s t a l l button. Follow the prompts in the D i s t r i b u t i o n F i l e I n -
s t a l l e r to complete the installation.
June 1, 2020 57
58 June 1, 2020
Chapter 3 System verification
♦ Non-default environment files
♦ Verify station-to-station communications
♦ Provisioning notes
♦ Station User notes in migrated stations
Following the migration and initial upgrade of a system from AX-3.8, there may be additional considerations
and tasks that you need to verify operation.
The following sections include related topics:
No n-d ef aul t env iro nm ent f il es

The migration tool does not migrate all parts of the station backup .dist file. For any AX-3.8 host where
you made changes in properties files or xml configuration files, these settings may need to be re-applied to
equivalent files in the Niagara 4 host.
Some examples of files that may have been modified include:
• system.properties
• nre.properties
• daemon.properties
• units.xml
• unitConversion.xml
• facetKeys.properties
In most cases the station should at least run successfully, and these settings can be re-applied once the sta-
tion is running under Niagara 4. It may not even be necessary to make the same changes, so you should eval-
uate once you have the station running in Niagara 4.
N O T E : Do not copy entire files from the NiagaraAX platform to the Niagara 4 platform, but instead only
those values that were modified from defaults in the equivalent NiagaraAX file(s).
Ve r i f y s t a t i o n - t o - s t a t i o n c o m m u n i c a t i o n s
Ideally, station-to-station communications between the platforms converted to N4.0 and all others resume
after the upgrade. That is, communications between the Supervisor and controller stations, via the N i a g a r a -
N e t w o r k . Supervisor communications between any JACE stations which remain at AX-3.8 should also re-
sume. (Note this assumes all station names remained unchanged.)
However, in some cases you may need to take additional steps to restore communications, working in the
N4.0 Supervisor stations and/or controller stations (N4.0 JACEs, and if applicable, AX-3.8 too).
N O T E : If configuration of any AX-3.8 JACE station is required, say to edit “client connection” properties of
the NiagaraStation that represents the N4.0 Supervisor, need to use Workbench for this.
Some variation of the following sequence may be required:
1. In Workbench, re-open the Supervisor station and go to the S t a t i o n M a n a g e r view of its
NiagaraNetwork.
If new JACE controllers were added (not migrated) there will not be an existing station child for them—
you need to select and add them.
June 1, 2020 59
Chapter 3 System verification Niagara AX to N4 Migration Guide
2. For each NiagaraStation in the Supervisor station’s N i a g a r a N e t w o r k , verify that communications report
{ok}. The status of all stations in the network should be {ok}.
In cases where secure communication (Foxs) is being used with the default self-signed certificates, it may
be necessary to go to the Supervisor’s C e r t M a n a g e r S e r v i c e platform service, and perform other
actions.
The figure above shows allowed hosts exceptions for migrated controllers that need approval. This may
not be necessary, if previously-exported TLS/SSL certificates were imported before commissioning.
3. In a station connection to each JACE controller, go to the S t a t i o n M a n a g e r view of its N i a g a r a N e t -
w o r k , and verify communications to the Supervisor are {ok}.
Again, if Foxs (TLS/SSL) is being used by a Hotspot JACE station back to the Supervisor (and possibly
other JACE stations) you may need to go to the JACE station’s C e r t M a n a g e r S e r v i c e platform service,
and perform other actions.
4. While working in remote JACE stations, after verifying N i a g a r a N e t w o r k communications back to the
Supervisor are {ok}, verify other “inter-network” configuration is valid. For example, verify the correct
N i a g a r a S t a t i o n component (representing the Supervisor) is referenced in the appropriate S t a t i o n R e c i -
p i e n t component, under the station’s A l a r m S e r v i c e . Typically, this is necessary only if station names
were changed when migrating.
Prov is i oni ng n ot es
For any Supervisor migrated to N4.0 that was configured for provisioning stations in its N i a g a r a N e t w o r k ,
that is, using the provisioningNiagara components (for example, P r o v i s i o n i n g N w E x t , also B a t c h J o b -
S e r v i c e ) , there may be related post-migration measures needed.
Ve r i f y S u p e r v i s o r t o c o n t r o l l e r p l a t f o r m d a e m o n c o m m u n i c a t i o n s
You need to verify that communications from the Supervisor to the platform daemon of each controller are
{ok}.
Expand the Supervisor’s N i a g a r a N e t w o r k , and issuing a ping from the P l a t f o r m C o n n e c t i o n device exten-
sion of each child N i a g a r a S t a t i o n .
60 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 3 System verification
The figure above shows successful communications to the JACE platform daemon, using platformssl. How-
ever, you may first need to edit the Credentials property to match a new strong password for the plat-
form admin account in an migrated controller. And/or, perhaps (again) access the Supervisor’s
C e r t M a n a g e r S e r v i c e platform service, and perform other actions.
This station-to-platform provisioning communications is one-way only, from the Supervisor to each control-
ler. Therefore, no reciprocal configuration in controller stations is needed.
P ro v i s i o n i n g c o n s i d e r a t i o n s w h e n J A C E c o n t ro l l e r s re m a i n
Sometimes one or more JACE controllers may need to remain running AX-3.8, yet continue to be in the mi-
grated Supervisor’s N i a g a r a N e t w o r k . This is supported by the N4.0 Supervisor, including many provision-
ing operations. For example, the backup of AX-3.8 stations and installation of AX-3.8 software.
For proper support, you should import the software database of the former AX-3.8 Supervisor into the soft-
ware database of the N4.0 Supervisor. This copies over all the versioned NiagaraAX software modules and .
dist files to the new Supervisor, and makes them available for provisioning of the older platforms.
To do this when the N4.0 Supervisor is installed on the same PC as the former AX-3.8 Supervisor:
1. Use Workbench to open a platform connection to the N4.0 Supervisor, then access the S o f t w a r e M a n a g -
e r view.
2. Click the I m p o r t button at the bottom, and then Import software from directory.
June 1, 2020 61
3. As shown above, in the D i re c t o r y C h o o s e r popup, navigate to the AX-3.8 Supervisor’s installation fold-
er, then expand to find its sw subfolder. Select it and click C h o o s e .
Progress is displayed in a popup dialog similar to the one above, while software files are analyzed for ver-
sions and then copied into appropriate subfolders in the N4.0 Supervisor’s software database. When fin-
ished copying, the normal S o f t w a r e M a n a g e r view opens.
If the former AX-3.8 Supervisor is on a different PC than the N4.0 Supervisor, you perform the same proce-
dure. However, first copy the entire software database (!\sw folder) from the AX-3.8 Supervisor to a loca-
tion accessible from the N4.0 Supervisor, such as on a USB flash drive, etc. Then navigate to that location
from the S o f t w a re M a n a g e r while platform-connected to the N4.0 Supervisor.
Station User notes in migrated stations

A number of Niagara 4 changes were made affecting station users, meaning User components that are chil-
dren of a station’s U s e r S e r v i c e .
62 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 3 System verification
Permissions moved to Roles

The permissions map that every User had (Permissions property) was removed. The permissions map identi-
fies what operator-level and admin-level privileges are in place for different Category components in the
station.
The Permissions property was relocated to R o l e components (new in Niagara 4), which are children of a new
R o l e S e r v i c e in the station. Instead of a User being assigned permissions directly, now you assign each user
to one or more Roles. Permissions of those roles are “OR’ed” together to specify what privileges a user has
on the categories in the station.
In order to migrate Users from AX to N4.0, while preserving their existing category permissions, note an N4
migration results in a separate R o l e c r e a t e d f o r e a c h U s e r —and named identically to that U s e r.
F ig ure 20 Station migrated to N4.0 has default “one-to-one” mapping of new Roles to existing Users
This one-to-one mapping of created roles to users is shown above, where user JohnW has (by default), only
one role assigned: also named JohnW. (Note additional roles could be assigned, but are not here.) Effec-
tively, nothing changed here: the permissions map that used to be in user JohnW’s permissions property is
now in the “same named” R o l e component.
June 1, 2020 63
Fi gu re 21 Permissions map of User relocated to Role created with identical name
As shown above, you can see this in the popup E d i t window for each Role (in the R o l e M a n a g e r view on the
R o l e S e r v i c e ). The role now has the permissions map.
In summary, to make better use of roles, you should consider this a workaround effect of migration. For ex-
ample, you could create more duty specific roles and/or rename or delete roles, later reassigning to users in
various combinations. When adding or editing users, this can simplify how permissions are assigned.
The R o l e M a n a g e r lets you do all these things, except the assignment of one or more roles to users. That
you do from editing (or adding new) users in the U s e r M a n a g e r, or from User property sheets.
A u t h e n t i c a t i o n i s u s e r- s p e c i f i c
When looking at a U s e r in Niagara 4 station, notice that the Password property is now inside a new A u -
t h e n t i c a t o rcontainer, along with P a s s w o r d C o n f i g properties. In addition, each User has a specified A u -
t h e n t i c a t i o n S c h e m e N a m e , where the default is typically DigestScheme.
This is part of a new authentication architecture” in Niagara 4. Along with a new (and required) A u t h e n t i c a -
t i o n S e r v i c e and child AuthenticationScheme components, station security is improved, providing finer con-
trol. For the migration of existing station users, typically nothing remains to be adjusted. However, when
creating new users, this architecture may provide added flexibility.
For related details on authentication changes, refer to the Niagara Station Security Guide.
64 June 1, 2020
Chapter 4 Migrating Niagara Enterprise
Security stations
♦ Upgrading devDriver-based video drivers
♦ Mapping Supervisor cameras to AX controllers before migration to N4
♦ Preparing the BackupService
♦ Backing up by creating a distribution file
♦ Migrating each station
♦ Copying the migrated files
♦ Setting up database passwords
♦ Configuring network device passwords
♦ Deleting the old certificates
♦ Reconnecting the Supervisor and remote stations
♦ Restoring the BackupService schedules
Niagara Enterprise Security stations are Niagara stations that have some additional unique migration
requirements and options. The following topics describe the specific steps required to migrate your
NiagaraAX-3.8 based security Supervisor and controller stations to Niagara 4.8 based security stations. This
topic provides an overview of the process.
To reduce downtime, migrate the Supervisor station first and then the individual security stations.
A typical Supervisorstation includes persons, badges, access rights, schedules, threat level groups, intrusion
PIN, intruzion zones, NiagaraIntegration ID, tenants, new users, new roles, new categories, a
PhotoIDNetwork, and ObixNetwor, PxViews, additional personnel information, an Ldap network, alarm
class, custom Wiegand format, and keypad configuration.
The following list summarizes the aspects of the AX security system that need special migration attention:
• P a s s p h r a s e : Be sure to have the station passphrase available before starting the migration process.
Depending on the migration scenario you are using, you may need to re-enter existing passhphrases or
create new passphrases during the migration process. Refer to “System Passphrase” and related topics
in the Niagara Platform Guide for more details about passphrase usage.
• d e v D r i v e r b a s e d v i d e o d r i v e r s : Niagara 4 does not support RapidEye and Dedicated Micros legacy
devices. During migration, the migrator deletes devDriver-based devices, including these two. If your
installation includes one or more of these devices, please upgrade to the supported devices: Axis,
Milestone and MaxPro video drivers.
If your installation uses the devDrivers for AxisvideoNetwork and Milestone, a procedure in this chapter
documents how to use the V i d e o D r i v e r U p g r a d e t o o l to upgrade these drivers to nVideo-based
version of the drivers.
• R e m o t e V i d e o C a m e r a m a p p i n g : As part of AX to N4 compatibility restrictions, Supervisor cameras
cannot be discovered under the NiagaraNetwork from an AX controller. So, to migrate cameras to the
new Supervisor station, map them in a Niagara Enterprise Security 2.3 JACE before doing the station
migration. Then, during migration, the new station retains that mapping without additional changes after
migration.
• B a c k u p : Before migration, you will make a backup of the Supervisor station and all subordinate stations.
By default, the BackupService does not include alarms and histories. To retain these database records,
you must specifically include alarms and histories in the backup.
• B a c k u p s c h e d u l e s : Before migration you must use the web UI to unassign any schedules in the
BackupService and re-assign them after completing the migration.
June 1, 2020 65
Chapter 4 Migrating Niagara Enterprise Security stations Niagara AX to N4 Migration Guide
• P h o t o I D s t a t i o n A s u re I D L e g a c y D e v i c e : If you use AsureID to create photo ID badges, Niagara 4.8

does not support the AsureID Legacy Device. Before migrating, add the newer AsureID Client Device to
your Photo ID network.
Refer to the “Manually adding a Photo ID device (not legacy)” topic in the Niagara Enterprise Security
Installation and Maintenance Guide for guidance on how to configure the newer Asure ID Client Device.
• S u p e r v i s o r d a t a b a s e s u p p o r t : Niagara 4.8 supports MySQL 5.6 and later and SQL Server 2008 and
later. These are the minimum requirements for the Supervisor database.
N O T E : There is no special procedure for preparing the Supervisor database. If your database is older
than the supported versions, contact the database supplier for software upgrade procedures.
• R e m o t e s t a t i o n d a t a b a s e p a s s w o r d : The migrator clears the HSql password in each remote station.
After migration you will set up this password again for each station.
• R o l e s : Roles are handled differently in Niagara 4. The migrator removes all AX security roles from the
UserService and moves them to the Niagara 4 Role Service.
• C u s t o m m o d u l e s : If your installation includes custom modules made using the ProgramModule feature,
you will need to refactor them before migrating the Supervisor and subordinate stations. Refer to
Migrating modules made with the ProgramModule component in this guide.
U p g r a d i n g d e v D r i v e r- b a s e d v i d e o d r i v e r s
If you are using one or more devDriver-based video drivers, a conversion tool is available to upgrade these
drivers in each controller station to the newer nVideo-based drivers. You must upgrade these drivers before
you migrate each controller station.
P r e r e q u i s i t e s : Your laptop or PC is connected to the same network as your controller(s) and is running the
NiagaraAX version of Workbench. The driver upgrade module is available.
Step 1 From Workbench, open a connection to the desired controller station (F
Fi l e → S t a t i o n → O p e n S t a -
t i o n ) and enter credentials with admin privileges.
Step 2 From the main menu, click T o o l s → D r i v e r U p g r a d e T o o l .
The D r i v e r U p g r a d e T o o l window opens.
Step 3 Enter the host address, platform and station addresses and click N e x t .
The wizard reads the current station and scans its .bog (station) file. If a driver can be upgraded,
the wizard changes the .bog file and downloads any dependent modules. Be sure that you have
the required modules or an upgrade is not possible.
When it successfully completes the upgrade, the wizard indicates that is was successful.
66 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 4 Migrating Niagara Enterprise Security stations
NOTE:
The wizard does not delete the old devDriver based video driver modules.
Step 4 To conserve space in the controller, delete the old devDriver based modules if they are no longer
needed. devDriver modules that you can delete, include the following:
• devDriver.jar
• devHttpDriver.jar
• devIpDriver.jar
• devVideoDriver.jar
N O T E : The devDriver.jar may be required as a dependency for other drivers. If so, you cannot de-
lete it while that dependency exists.
Step 5 Delete any older driver modules, such as those for Closed-Circuit TV (CCTV) equipment associated
with the older drivers.
Map p i ng Su pe rv is or c am er as to AX c ont rol le rs b ef ore m i gr ati o n t o N4

As part of AX to N4 compatibility restrictions, Supervisor cameras cannot be discovered under the Niagara-
Network from an AX controller. This procedure describes a way to pre-configure your station before migra-
tion in order to retain the Supervisor camera to remote controller connection after migration.
P re re q u i s i t e s : The camera device address is available. The Supervisor IP address is known.
If you map the desired Supervisor camera to the remoter controller before migration (using this procedure),
the system maintains the camera relationship through the migration process and functions after migration
for use with readers and alarms.
Step 1 Using the Niagara Enterprise Security 2.3 Workbench, navigate to the following location: C o n f i g → -
Drivers→AccessNetwork→Remote Reader Module→Points→Door 1→Reader 1→Badge Does
Not Exist Alert
The property sheet view opens.
June 1, 2020 67
Step 2 To open the C o n f i g F a c e t s window, click the facets icon (>

>> ) next to the Meta Data property.
Step 3 Add facets as shown in the image above (also, refer to details in table below), where xxx.xxx.x.
xxx is the IP address of the Supervisor platform and xxxx is the actual cameraHandleOrd for the
camera you are mapping.
The following table indicates the key names, type, and values that go in the facets window.
Key Ty p e Va l u e
cameraOrd String ip:xxx.xxx.x.xxx|foxs:sta-

tion:|slot:/Drivers/Axis
$20Video$20Network
cameraHandleOrd String h:xxxx
goToPreset Boolean false
cameraPreset dynamicEnum 1
sendAlarmToDisplay Boolean false
startRecording Boolean true
68 June 1, 2020
N O T E : The startRecording property works only for Milestone cameras but not for Axis
Video cameras. Set the startRecording property to false for an AxisVideoCamera.
When this task is completed the station is ready for backup and migration as described in the tasks included
with Chapter 4 Migrating Niagara Enterprise Security stations, page 65 topic.
Pre par in g th e B ac kup Se rv ic e

By default, backups do not include alarm and history records. To preserve alarms and histories you need to
edit the excluded file values.
P re re q u i s i t e s : You are logged in to your NiagaraAX Supervisor station with admin privileges.
Step 1 Navigate to the C o n f i g → S e r v i c e s node in the Nav tree, right-click the B a c k u p S e r v i c e s node and
select A X P r o p e r t y S h e e t from the popup menu.
The B a c k u p S e r v i c e s property sheet opens.
Step 2 In the Exclude Files text field, select and delete the following: *.hdb; and *.adb; using your
keyboard and mouse.
This includes (not excludes) your database files.

Step 3 For the Exclude Directories property, select the following files and delete them using the re-
move icon ( ): file:^history and file:^alarm
This includes (not excludes) alarm and history files.
June 1, 2020 69
Bac ki ng u p b y c reati ng a d is tr ib ut io n fi le
This procedure backs up a Supervisor and any subordinate stations. Creating a single distribution (.dist) file
is the most complete way to back up a Supervisor station and its subordinate remote stations. The backup
file includes all station data and module-dependency information.
P r e r e q u i s i t e s : Your PC is connected to the network with any remote controller subordinate stations. You
are using a browser (the web UI) to connect to the Supervisor station.
Step 1 Open a browser and log in to the AX Supervisor station that you want to back up.
Step 2 From the Home view, click S y s t e m S e t u p → B a c k u p s .
The B a c k u p s view opens.
Step 3 Click the S y s t e m B a c k u p button.

The S y s t e m B a c k u p window opens with two option boxes selected.
Selecting the first option (check box) enables a backup of the Supervisor station and all its subordi-
nate stations. The second option (check box), when selected, automatically downloads the backup
to your local Downloads folder.
Step 4 To continue, click O k .
The J o b window displays a progress bar while the backup job runs. When the job finishes, another
L o c a l B a c k u p window opens with a “Show Details” link and a D o w n l o a d button.
Step 5 To display the history of this backup job, click the S h o w D e t a i l s link.
Step 6 To save the backup *.dist file to a designated location, click the D o w n l o a d button. In this case, the
browser saves the file to the temporary folder and prompts you to open or save the file.
N O T E : You must save the file within five minutes of creating it or it is not available.
Step 7 Give the file a short name that identifies the Supervisor and subordinate stations, and save the file
to a location other than the System Home or User Home.
70 June 1, 2020
Step 8 Finally, make a note of the date and where you saved the downloaded file for reference when mi-
grating the file.
Migrating each station

The migrator is a command line utility. Using the backup .dist file, it creates the Niagara 4 Supervisor and
subordinate station folders. Then, using Workbench, you open a platform connection to each new platform
and install each new station using the Station Copier.
P re re q u i s i t e s : Niagara 4 is installed on your PC. You know the name of the .dist file and where it is located.
Zip files must be “unzipped” to expose the “*.dist” file for the migrator to process.
Step 1 Open a standalone Console window using the shortcut from the Windows Start menu.
N O T E : Do not use the Workbench embedded Console. It cannot accept the required keyboard in-
puts during the migration process.
Step 2 Change directories to the location of the backup .dist file.
N O T E : If you change directories to the location of the backup .dist file you do not need to specify
the path to this file.
Step 3 Enter: n4mig distributionfilename.dist, where distributionfilename.dist is the
name of the backup .dist file you created.
If the current directory does not contain the .dist file, include the correct file path in the command
line to precede the .dist file name. For example: c:\path\distributionfilename.dist.
Step 4 When the process pauses, respond to the prompts in the console window, as follows:
a. Please select a migration template:1: Controller Migration Template or 2:
Supervisor Migration Template
b. Enter the passphrase used to protect Niagara 4 BOG files.
If you know the passphrase of the system that you are targeting with the migrated station(s),
enter it here. If you do not know or have access to the system passphrase, create one now and
remember it. You will have to enter it when you copy the migrated station to the Niagara 4 host
system. For more details about passphrase refer to the Niagara Platform Guide topics: ”System
Passphrase” and “System passphrase usage in backups and station copies”.
While the migration utility runs, it displays the log in the console window. The final message dis-
plays the source, target, and Migration Report locations for reference, as shown below:
Completed Migration
Source: backup_EntSec24Supervisor_190411_1415.dist
Target: C:\Users\User123\Niagara4.8\brand\stations\EntSec24Supervisor
Migration Report: C:\Users\User123\Niagara4.8\brand\stations\
backup_EntSec24Supervisor_190411_1415.dist_miglog_190411_1423.html
Step 5 Make a note of these locations.
Copying the migrated files

The migrator places all migrated files in the same location. You need to copy these files to the proper loca-
tion for installation.
P re re q u i s i t e s : The migrator ran successfully. You have installed Niagara 4 on your PC.
Step 1 Using the operating system’s File Explorer, copy the new, migrated, stations to the user_home/
Niagara 4.x/brand/stations directory.
Step 2 Launch the Workbench and make a platform connection to the Supervisor station.
June 1, 2020 71
Step 3 Do one of the following:

• If the PC you are using also runs the Supervisor station, use Station Copier to copy Supervisor
station from the user_home to the ProgramData directory.
• If the Supervisor station runs on a separate PC, export the tables from the My SQL or SQL Serv-
er database and copy the ProgramData directory with the exported tables to the other PC.
Sett in g up d at ab as e p as s word s
This procedure covers setting up database and driver passwords in all stations.
P r e r e q u i s i t e s : The Supervisor station requires a MySQL or SQL database. A controller station has a built-in
HSql database. The MySQL or SQL Server databases exist in the Supervisor station. If they do not exist, then
you need to create the database schema and import the database tables that you previously exported to
the new schema.
Step 1 Using a browser (web UI), make a connection to the station.
Step 2 Click C o n t r o l l e r ( S y s t e m ) S e t u p → M i s c e l l a n e o u s → C o n f i g u re D a t a b a s e .
The C o n f i g u r e D a t a b a s e view opens to the Database Services tab.
Step 3 Select the Database tab, set the Enabled property to true, verify the Host Address, database
name, User Name and Password and click S a v e .
After the database changes, you are prompted to restart the station. After the station restarts, the
database should connect using the new credentials, providing data communication from the newly
connected database.
Co nfi g uri ng n etw or k d ev ic e p as swo rd s

The devices on the station network may require password reentry in the migrated stations. For example, a
camera or DVR may have a unique device password that needs to be re-entered because it was cleared dur-
ing migration process.
P r e r e q u i s i t e s : Your PC is connected to the network with the remote controllers.
Step 1 From a browser (web UI), make a connection to the remote controller station.
Step 2 Navigate to the R e m o t e D r i v e r s view (C
Co n t ro l l e r S e t u p → R e m o t e D e v i c e s → R e m o t e D r i v e r s ).
N O T E : The following steps can be for any network device that requires a password. The steps be-
low show an example for a video camera device.
Step 3 For each network driver that may require a password, select the driver, click the H y p e r l i n k button
( ) on the menu and navigate to the device in the network (for example a Camera).
72 June 1, 2020
The screen capture shows this link for an Axis camera.

Step 4 To display and update the device properties, click the device link.
Step 5 Update the device password and click S a v e

The device password is updated.
Deleting the old certificates

To promote secure communication in Niagara 4 it is recommended that you install new TLS certificates. This
procedure deletes the old certificates. Perform these steps for each station, Supervisor and all remote
stations.
P re re q u i s i t e s : You are using the Supervisor PC running Workbench. All stations are idle.
N O T E : Subsequent procedures assume that this installation uses default self-signed certificates. If the com-
pany uses signed certificates (the most secure configuration), you will need to create a new root CA certifi-
cate, create a new server certificate for each platform/station, use the root CA certificate to sign each server
certificate and install each signed server certificate after completing the migration.
While you may delete certificates using the browser (web UI), this procedure manages all certificate proc-
esses using Workbench.
Step 1 Open a platform connection to the Supervisor PC or remote controller (F
Fi l e → O p e n → O p e n
Platform.
Step 2 Expand the P l a t f o r m node and double-click C e r t i f i c a t e M a n a g e m e n t in the Nav tree.
June 1, 2020 73
Step 3 In the User Key Store, select the certificate, click D e l e t e (as shown above) and click Ye s to confirm
the deletion.
Step 4 Select the Allowed Hosts tab, select an allowed self-signed certificate, click D e l e t e and click Ye s to
confirm the deletion.
This action deletes the certificate.
Step 5 Restart the station.
Step 6 Perform these steps in the Supervisor and each remote station.
Re c onn ec ti ng t he Sup er vi so r and rem o te st at io ns

This procedure reconnects the remote stations to the Supervisor station.
P r e r e q u i s i t e s : You have deleted all old AX certificates from all stations.
Step 1 Using the web UI, make a connection to the Supervisor station and accept the self-signed
certificate.
Step 2 Click S y s t e m S e t u p → R e m o t e D e v i c e s → S t a t i o n M a n a g e r.
The E d i t window opens.
Step 3 To re-establish the connection between the Supervisor and each subordinate station, enter the re-
mote station credentials.
Step 4 Approve each station’s self-signed certificate.
Step 5 For each subordinate station, do a J o i n , as described in “Joining a controller station to the Supervi-
sor station” in the Niagara Enterprise Security Installation and Maintenance Guide
74 June 1, 2020
Step 6 To set up data in each remote station, do a R e p l i c a t e , as described in the “Replicating a configura-
tion” topic in the Niagara Enterprise Security Installation and Maintenance Guide.
Restoring the BackupService schedules

This procedure describes how to restore the BackupService schedules.
P re re q u i s i t e s : You are connected to the Supervisor station using a browser (the web UI).
Step 1 Click S y s t e m S e t u p → B a c k u p s .
The B a c k u p s view opens.
Step 2 Click the B a c k u p S c h e d u l e tab.

The B a c k u p S c h e d u l e view appears.
Step 3 To select the backup schedule, click the Ref Chooser chevron (>
>> )
The R e f C h o o s e r window opens.
Step 4 To assign a schedule to the backup, select the desired schedule from the table and click O k .
Repeat this procedure for all the migrated stations.
June 1, 2020 75
76 June 1, 2020
Chapter 5 Connecting a Supervisor
s t a t i o n t o a l e g a c y c o n t ro l l e r s t a t i o n
♦ 1. Configuring the Niagara Enterprise Security 4.8 Supervisor station connection
♦ 2. Adding a remote controller 2.3 station
♦ 3. Logging in to the Supervisor from the controller
♦ 4. Connecting from the Supervisor to the NiagaraAX-3.8 legacy security station
Niagara Enterprise Security connections from Niagara 4- based stations to NiagaraAX (JACE-6 controller)
stations were not possible before the release of Niagara 4.8. With Niagara Enterprise Security 4.8, stations
can now connect and join to Niagara Enterprise Security 2.3 JACE-6 controllers by following the instructions
included in this document.
The goal of this process is to have the Niagara Enterprise Security N4Supervisor connect, join, and replicate
with a subordinate JACE-6 controller that is running Niagara Enterprise Security 2.3. After you complete this
procedure, the remote controller is connected and communicating with the Supervisor station as a
subordinate. With this relationship and communication established, you can join and replicate using the
same procedures that describe those tasks for JACE-8000 security controllers. Refer to Station join best
practices and Joining a controller station to the Supervisor station topics for details. Also, refer to Wire
compatibility, page 12 for details about communication and feature support between the two versions of
Niagara.
To establish communication (connect) between the Niagara Enterprise Security 4.8 Supervisor station and a
legacy NiagaraAX JACE-6 controller station, you need to use both Workbench and a browser to configure
the following:
1. Prepare the Niagara Enterprise Security 4.8 Supervisor station (add a user, configure WebService and
FoxService).
2. Discover and add the remote NiagaraAX controller station to the Supervisor station database.
3. Establish an authenticated user connection from the remote NiagaraAX controller station to the Niagara
Enterprise Security 4.8 Supervisor station.
4. Create the proper Supervisor – subordinate relationship between the two controller stations.
Each of these procedures are detailed in specific tasks that follow.
1. Configuring the Niagara Enterprise Security 4.8 Supervisor station

connection
This procedure describes how to setup the Niagara Enterprise Security 4.8 station so that a legacy JACE-6
controller (running a station with NiagaraAX-3.8) can connect and authenticate a user with the newer
station.
P re re q u i s i t e s : Niagara Enterprise Security 4.8 Workbench application is installed and running.
Step 1 Using Niagara Enterprise Security 4.8 Workbench, connect to the security Supervisor station that
will establish a connection with the legacy controller.
Step 2 In the Supervisor station, navigate to C o n f i g → S e r v i c e s and double-click on the UserService node.
The U s e r M a n a g e r view opens.
June 1, 2020 77
Chapter 5 Connecting a Supervisor station to a legacy Niagara AX to N4 Migration Guide
controller station
Step 3 In this view, create a new user that you will use later to authenticate the NiagaraAX controller sta-
tion connection back to this Supervisor station.
Step 4 Name the User and set the property values including these two properties:
• For Authentication Scheme Name, choose: AX digest scheme.
• For Roles, choose: admin.
Step 5 Navigate to C o n f i g → S e r v i c e s → We b S e r v i c e .
The WebService P r o p e r t y S h e e t opens.
Step 6 Set the Cipher Suite Group property value to the Supported option and click S a v e .
Step 7 Navigate to C o n f i g → S e r v i c e s → F o x S e r v i c e .
78 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 5 Connecting a Supervisor station to a legacy controller station
The FoxService P r o p e r t y S h e e t opens.
Step 8 Set Cipher Suite Groupto the Supported option and click S a v e .
Step 9 Navigate to the Supervisor Certificate Management view (P Pl a t f o r m → C e r t i f i c a t e M a n a g e m e n t )
and delete the remote controller certificate from the A l l o w e d H o s t s table.
Step 10 Within N4 Workbench, open a platform connection to your AX controller.

While you cannot connect to an AX station from N4, you can connect to the platform.
Step 11 Navigate to the remote controller C e r t i f i c a t e M a n a g e m e n t view (P
Pl a t f o r m → C e r t i f i c a t e M a n -
a g e m e n t ) and delete the Supervisor certificate from the A l l o w e d H o s t s table.
2. Ad d in g a re m ot e c ont rol le r 2. 3 s t ati on

Use this procedure to initiate the connection between Niagara Enterprise Security 4.8 stations and AX-3.8
stations. Authentication fails on the initial attempt to connect but may complete in a subsequent procedure.
P re re q u i s i t e s : The Supervisor station is configured to accept the NiagaraAX-3.8 user connection.
Step 1 Using the browser of your choice and the Java web launcher app, open a station connection to your
Supervisor and controller stations using the user with admin rights.
June 1, 2020 79
controller station
Step 2 To find the AX Stations to connect to from the N4 Supervisor, navigate to R e m o t e D e v i c e s and
run a discovery job.
The station appears in the D i s c o v e r e d pane.
N O T E : If discovery does not find the station, manually add the station (click the A d d button, and
provide the AX controller’s IP address and credentials).
Step 3 Select the station to add and click the add (+
+) button.
The A d d S t a t i o n ( s ) window opens.
Step 4 Starting with the left side of the window, enter the Username and Password for Supervisor to log-
in to the remote station (these credentials must already exist on the remote controller).
Step 5 On the right side of the window, enter the Username and Password for the newly created user so
that the remote AX-3.8 controller can log in to the Supervisor (these credentials must already exist
on the Supervisor).
Step 6 Make sure that the Desired Role property is set to Subordinate and click O k .
The Supervisor runs the add-station job and adds the remote station to the Supervisor database.
NOTE:
An Authentication Failure message displays at the completion of the job. This is because of
the different credential storage capabilities in the two different versions. The following steps pro-
vide a way to resolve this from the remote controller and complete the connection.
Step 7 Navigate to S y s t e m S e t u p → R e m o t e D e v i c e s → C e r t i f i c a t e M a n a g e m e n t and approve the re-

mote controller certificate.
80 June 1, 2020
3. Log g in g in t o the Su pe rv is or f rom th e c o nt rol ler

These steps connect from the NiagaraAX-3.8 legacy security station to the security Supervisor and authenti-
cate the connection using the newly-created credentials for a user with AXDigestScheme authentication.
P re re q u i s i t e s : The record for the remote legacy controller is added to the Niagara Enterprise Security 4.8
Supervisor station database.
Step 1 In the browser, connect to the remote NiagaraAX controller: from the main menu, select C o n t r o l -
l e r S e t u p → R e m o t e D e v i c e s and click on the C e r t i f i c a t e M a n a g e m e n t view, approve the Super-
visor certificate.
Step 2 From the main menu, select C o n t ro l l e r S e t u p → R e m o t e D e v i c e s and click on S t a t i o n M a n a g e r
to display the Station Manager Database view.
The Supervisor station displays as a row in the table view.
Step 3 Select the Supervisor station and click the Edit icon ( ).
The E d i t window opens.
Step 4 Enter credentials for the newly created NiagaraAX user, verify that the other properties are correct
for the connection and click C o n t i n u e t o R e m o t e C o n f i g u r a t i o n .
The connection to the remote station (Supervisor) continues and the R e m o t e C o n f i g u r a t i o n win-
dow appears.
June 1, 2020 81
controller station
Step 5 Click C a n c e l in the R e m o t e C o n f i g u r a t i o n window.

The system closes the window. To authenticate the connection, you must complete the process
with the following task.
4. C on nec t ing from t he Sup erv is o r to t he Ni aga raA X -3. 8 le gac y s ec u ri ty

station
The following task describes how to connect from a configured legacy controller station (running
NiagaraAX-3.8) to a properly configured Niagara Enterprise Security 2.4 Supervisor.
P r e r e q u i s i t e s : The legacy controller station has completed a user login to the Niagara Enterprise
Security 2.4 Supervisor station.
Step 1 In the browser, connect to the Supervisor and navigate to the station database view (S
Sy s t e m S e t u -
p→Remote Devices→Station Management)
Step 2 Select the remote NiagaraAX-3.8 legacy security station and click the Edit icon ( ). These fields
should already be populated. Verify the fields and click C o n t i n u e t o R e m o t e C o n f i g u r a t i o n .
The R e m o t e C o n f i g u r a t i o n window opens.
Step 3 Enter the newly created user credentials and click O k .

The R e m o t e C o n f i g u r a t i o n window closes, the configure job runs and establishes the connection
with the correct relationship between Supervisor and subordinate. You are ready to proceed with
station J o i n and R e p l i c a t e procedures.
82 June 1, 2020
Once the Niagara Enterprise Security 4.8 Supervisor station connects to the NiagaraAX-3.8 legacy station,
no further migration of the legacy station is required; it cannot be upgraded to Niagara Enterprise
Security 4.8.
June 1, 2020 83
controller station
84 June 1, 2020
Chapter 6 M i g r a t i o n re f e re n c e
♦ Imports
♦ API changes
♦ Primitives
♦ Security Manager
♦ Example Program object fix
A number of changes to NiagaraAX Program objects (components) need to be made to allow them to run
under Niagara 4. The N4 migration tool can make some of these changes for Programs as part of the station
migration process.
However, other changes often require post-migration work on certain Programs in the (offline) migrated
station.
Imports
The first step in converting Program objects to run under Niagara 4 is to update imports to declare depend-
encies on the appropriate runtime profile JAR files. In most cases, this will be the rt runtime profile JAR file
for the module (baja and nre do not have a runtime profile extension).
If your Program object was run through the N4 migration tool as part of a station migration, this change will
have been made for you.
API changes
If your Program objects use certain APIs that have had breaking changes, they will need to have their Pro-
gram code updated and recompiled using the new Niagara APIs.
Most notable are the “Collection API/Cursor”, “Alarm API”, “History API”, and “Logging API”. For more in-
formation on these changes and how to update your code, see the Niagara Developer Guide for each of
these API changes.
Also, note getProgram() was deprecated starting in AX-3.5 in order to support compiling Programs into
Program Modules. It has been removed for N4.0. While in the past, Program objects using this method
would still compile and run, they now require conversion to use getComponent() instead.
Primitives
Slots that are defined as baja:Boolean, baja:Double, baja:Float, baja:Integer, baja:Long and
baja:String now return their Java primitive types.
This means that you no longer need to call getBoolean(), getDouble(), getFloat(), getInt(), get-
Long() or getString() to cast the values of these slots to primitive values.
For example, for a slot defined on a Program as: Name=temperature, Type=baja:Double
NiagaraAX Program object:
double temp = getTemperature().getDouble();
Niagara 4 Program object:
double temp = getTemperature();
June 1, 2020 85
Chapter 6 Migration reference Niagara AX to N4 Migration Guide
Security Manager
Niagara 4 utilizes the Java Security Manager, which puts restrictions on what Program objects may do. Pro-
gram objects interacting with the station’s component tree should be largely unaffected by the Security
Manager.
F i l e re a d i n g / w r i t i n g
A restriction has been put on file reading and writing to only allow read-from and write-to the station_home
directory (file:^).
Runtime.exec()
The ability to call external executables is extremely useful in certain situations, however the use of Run-
time.exec() can allow potentially malicious code to be executed. As such, several restrictions are placed
on it to help protect your system.
Only station super users can add and edit Program objects. In NiagaraAX, there was a flag/entry to change
this behavior in system.properties. In Niagara 4, this ability has been removed.
Program objects can no longer directly call Runtime.getRuntime().exec(command). Instead, a wrapper
called ProgramRuntime behaves the same way as java.lang.Runtime, except that it takes the Program
object as an additional parameter. Commands executed by ProgramRuntime are logged and audited.
Additionally, to enable the use of ProgramRuntime, the hidden slot allowProgramRuntimeExec on the
station’s P ro g r a m S e r v i c e must be set to true.
N O T E : Only standalone Program objects can use ProgramRuntime.exec(). Program objects that have
been compiled into Program Modules cannot call this function.
An example of this in Program code is below
NiagaraAX Program object:
Runtime.getRuntime().exec(“notepad.exe”);
Niagara 4 Program object:
ProgramRuntime.getRuntime().exec(this, “notepad.exe”);
Exa m pl e Prog r am o b je c t fix

The following is a simple example fix for a Program object included in the widely-distributed NiagaraAX
demo station. It is one of several Programs flagged with a “WARNING unable to compile” entry when AX-
3.8 station backup .dist file for the demo station is used as source in the N4 migration tool.
A related snippet from the migration report (log file) looks like below.
WARNING unable to compile Program object PxHome.Graphics.Residential.First Floor.
GarageProgram
C:\Users\e333988\Niagara4.0\temp\Prog_ea44c5d3b904631ea44c5d3b904631.java:40: error:
cannot find symbol
Action action = getProgram().getAction("execute");
^
symbol: method getProgram()
location: class Prog_ea44c5d3b904631ea44c5d3b904631
This error relates to use of getProgram(), as described in API changes, page 85.
Opening the migrated “demo” station in your N4 Workbench, you can follow the ORD given in the warning,
and open the P ro g r a m E d i t o r view for that Program (“GarageProgram”), as shown in the following figure.
86 June 1, 2020
Niagara AX to N4 Migration Guide Chapter 6 Migration reference
F ig ure 22 Example Program with issues from migrated “demo” station
The WARNING snippet resulted from use of the now-obsolete getProgram(), which must be replaced by
getComponent(). Also note the Program status: “Program is out of date and requires compile.”
If you compile the Program now without making any changes, various errors (4) appear in the console area at
the bottom of the Workbench window, as shown below.
F ig ure 23 Example errors from a compile before making any Program changes
After replacing the two getProgram() instances to getComponent(), saving and then recompiling again,
errors are reduced to two—related to use of getDouble() for primitives (Figure 24 Figure 28, page 88).
June 1, 2020 87
Chapter 6 Migration reference Niagara AX to N4 Migration Guide
Fi gu re 24 Example Program with remaining issues from primitive syntax errors
This is no longer necessary, as explained in the section Primitives, page 85. To fix, simply remove the text
shown marked above.
As shown below, now after resaving the Program and recompiling, all errors are gone.
Fi gu re 25 Example Program object after fixing all issues and recompiling.
Now note the status of the Program is: “Program is up-to-date”, and there are no errors reported in the bot-
tom console area after the last compile and save.
88 June 1, 2020

Do Caxton 4 Migration

Uploaded by

Copyright:

Available Formats

Do Caxton 4 Migration

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Do Caxton 4 Migration

Uploaded by

Copyright:

Available Formats

Technical Document

Copyright and patent notice

Chapter 1 Migration overview..........................................................................7

Chapter 2 Migration tasks ..............................................................................27

Upgrade/convert platforms and install stations..........................................48

Chapter 4 Migrating Niagara Enterprise Security stations..............................65

Document change log

April 19, 2019

November 13, 2017

November 19, 2016

February 22, 2016

Why a migration tool?

Host Model N4 supported / OS / note s N4 compatibility notes

JACE-8000 Supported Initially supports only N4.0. At some future point, an

Host Model N4 supported / OS / notes N4 compatibility notes

JACE-403 NiagaraNetwork of N4 Supervisor. For related details,

R ec omm end e d m ini m um res ourc es b y c ontrol ler typ e

M i n i m u m F re e D i s k S p a c e , i n Java Max Heap, Minimu m Free Heap, in M B

The Minimum Free Disk Space recommendation is based on the following:

Chec ki ng for mi ni mu m reso urce req ui reme nts

Usin g t he re sourc e ch ec ke r Progr am

Step 4 Right-click the program in the station, and select A c t i o n s → → E x e c u t e .

Manually checking heap usage

This represents the low point of Java heap usage.

Driver and application support

Unsupported driv er / application Removed modules / notes

802.1x wired authentication support for Module “platIEEE8021X”

OpenADR client drivers (simple, smart) Modules “adr” and “dras”

Unsupported driver / application Removed modu les / note s

Alarms to relational database support Module “alarmRdb”. Superseded by module “alarmOrion”.

Dust wireless mesh network Module “dust”

Energy Application System (EAS), also Module “eas”

Floating license repository Module “flr”

IBM DB2 relational database support Module “rdbDb2”

Lon tunneling Module “lontunnel”. Improved security in N4 prohibits this tunneling.

Table 1 Communications support between Niagara 4 and NiagaraAX

AX Workbench N4 station, N4 Supervisor No Prohibited in software.

AX Workbench N4 platform No Prohibited in software.

AX Workbench AX platform Yes Provides support necessary for AX to N4 upgrades. A few

AX Workbench AX station No Prohibited in software. Note that ongoing AX station con-

F e a t u re From N4 to AX F ro m A X t o N 4 Additional comments

Alarms routed to and No Yes

Export Schedules Yes No

Import Schedules Yes No

Virtual points Yes Yes

Feature F ro m N 4 t o A X From AX to N4 Additional commen ts

Provisioning Yes No Supported operations for AX subordinates include:

My Host→My File System Home niagara_home C:\niagara\niagara-4.x.xx ! (as in Niag-

My Host→My File N/A niagara_user_ C:\Users\userName\Niagara4.x\<brand> ~ (unique to N4)

shared folder N/A station_home C:\Users\userName\Niagara4.x\tridium\shared ^ (as in Niag-

stations folder N/A protected_sta- C:\ProgramData\Niagara4.x\tridium\stations ^^ (unique to

N/A Us er Home niagara_user_ C:\ProgramData\Niagara4.x\<brand> ~ (unique to N4)

Platform→Remote System Home niagara_home /opt/niagara ! (as in Niagara4.x)

Platform→Remote User Home niagara_user_home /home/niagara ~ (unique to N4)

Fi gu re 2 Example Sys Home (niagara_home) on Supervisor platform

Windows platform user homes

• Callout 1 identifies Workbench U s e r H o m e .

F ig ure 5 Example of a daemon User Home location in Windows Explorer

Fi gu re 6 Example of an automatically-created Workbench User Home in Windows Explorer

AX station folder N4 station folder