Module Migration from Niagara AX to Niagara 4

Overview

This guide will help you convert an existing Niagara AX module to be compatible with Niagara 4. There are a number of changes we’ll need to make including the directory structure, build files and API changes.

Code Base

Since we’ll need to make some significant changes to both the directory structure of our code as well as the code itself, we’ll need to keep our Niagara AX code separate from our Niagara 4 code.

If you’re using a version control system such as Mercurial, Git or CVS, we recommend creating a branch for your Niagara AX code base and working on your Niagara 4 changes on the main or default branch.

In this guide we’ll assume that you have your Niagara AX code and Niagara 4 code checked out to separate folders on your file system.

To get started we’ll need to divide our module into one or more module parts (each with different runtime profiles). We can do this by hand, creating the new folder structure, converting build.xml files to .gradle files, moving source files and splitting apart module-include.xml, or we can make use of some of the Niagara tools to do a lot of that work for us.

New Module Wizard

We can create the proper directory structure and gradle files by using the New Module Wizard.

Execute New Module Wizard

You’ll need to run the New Module Wizard once for each module part that you need to create. For most Niagara AX modules this you’ll run it once for the rt module part and once for the wb module part.

Notes:

Copy gradle files

Copy the .gradle files from the ‘dev’ folder of the Niagara 4 Developer image zip file. You will need:

These should be placed in the parent folder that you chose in the New Module Wizard.

Edit vendor.gradle to set the correct group/vendor and moduleVersion.

Copy and fix module part gradle build files

Since we have multiple module parts, we want to setup a multi-module build environment. The .gradle files from the ‘dev’ folder set this up but we need to make a few changes to the build.gradle files that the New Module Wizard produces (as it produces single moule build files). Rename <moduleName>-rt/build.gradle to <moduleName>-rt.gradle and <moduleName>-wb/build.gradle to <moduleName>-wb.gradle. In each of these gradle files, remove the line:

apply from: "${System.getenv("niagara_home")}/etc/gradle/niagara.gradle"

Note: we do this because the niagara gradle plugin is already applied by the root build.gradle file. Now you can continue with the file copy and IDE import!

The ext { } section can also be removed from these files since it will override the values in vendor.gradle

Copy Source Files

Now as a starting point we need to copy the files over from the Niagara AX source location to the Niagara 4 source location.

  1. Use the install=“ui” flag in your Niagara AX build.xml file to determine which files to copy to your wb module part
  2. Copy rt runtime profile source files to your rt module part
  3. Copy module.lexicon and module.palette into your rt module part
  4. Copy module-include.xml into BOTH the rt AND wb module parts

Import into IDE

You can do this using Eclipse or IntelliJ IDEA. The following instructions are for importing into IntelliJ IDEA 2016.1.

  1. Open IntelliJ IDEA. Select File > Open… to open the dialog for opening a project.
  2. Navigate to the build.gradle created by the New Module Wizard. It should be at n4/nolademo/build.gradle. Click OK.
  3. Select to ‘Use gradle wrapper task configuration’. Click OK.
  4. After a brief pause, you will have a dialog saying ‘Gradle Project Data To Import’. Ensure all three choices are selected and click OK.
  5. After this, you should have the IntelliJ workbench open, with the nola-rt, nola-wb, and nolademo parts available in the Project view on the left.

If you are using Eclipse or older versions of IntelliJ IDEA, you’ll want to execute gradlew eclipse or gradlew idea from your project directory to auto-generate project files for your IDE. You can then open the project file in your IDE.

Migrate the Code

Migrate Slot Code

Niagara 4.2 introduces a new gradle task for converting Niagara AX style slot definitions to Niagara 4 annotation style slot definitions. While Niagara AX style slot definitions will continue to work in Niagara 4, we recommend moving to Niagara 4 annotation style slot definitions as IDEs provide syntax highlight and auto-completion for this style as well as being able to auto-generate module-include.xml files.

The slot tool migration serves two purposes in this guide.

  1. We need to get the type definitions into the correct module part locations, as they must only be specified in a single module-include.xml.
  2. It converts the old-style AX syntax to the new N4 annotation syntax.

Open the Gradle projects window, and execute the task

niagara > niagara (root) > niagara > migrateSlotomatic.

This is equivalent to executing the console command

gradlew slotomatic -Dslotomatic.migrateBeforeRecompile

Then remove module-include.xml from both the rt and wb module parts. These files will be regenerated with the correct type information during the build process.

Apply N4 Code Changes

Finally you need to fix the code to use the new Niagara 4 APIs. You can identify these by running the Gradle task from the Gradle projects window:

niagara > niagara (root) > build > build

Or, from the command line:

gradlew build

Or, you can open the files in your IDE and identify the items highlighted in red.

Common API Changes

Collections API

The Collections API are detailed in the Collections section of Doc Developer. One common change is in BQL Ord resolutions. - Remove the import of the (nonexistent) javax.baja.collection.BICollection - Update BQL Ord resolutions:

// Niagara AX
BICollection result = (BICollection)BOrd.make("bql:select displayName").get(this);
BITable table = result.toTable();
// Niagara 4
BITable<BObject> table = (BITable<BObject>)BOrd.make("bql:select displayName").get(this);

Alarm & History APIs

The Alarm and History APIs were updated to be connection oriented APIs in Niagara. Calls to the Alarm and History Databases will need to be updated. These changes are details in the Alarm and History sections of Doc Developer.

Build the module

Build the module using the gradlew build task. Again, you can build it from the IDE or the command line.

Station Migration

Remember to migrate your Niagara AX station as well. You can use the n4mig executable to do this from the Niagara 4 console.