Below is a list of builds that require migration, along with a brief description of each to help guide the transition process.

FIN 5.2.0

Automated update

Upon startup, schedule and weather objects are automatically migrated using the finMigrateProject() function. This process updates the relevant records to ensure compatibility with the latest build. Additionally, alarm routing and notification records are injected for both new and existing projects to maintain consistent alarm notification behavior. The alarm digest has been refactored into a configurable job, allowing users to define its parameters and schedule according to their needs.

Schedule

The most significant change regarding schedules is the handling of ‘week’ type special events. These events are now automatically split into weekly (daily) events, and the original special event record is removed.

Example:

Open

If you previously had a single special event scheduled for Saturday and Sunday from 8 AM to 5 PM, the migration will convert it into two separate recurring weekly events—one for Saturday and one for Sunday—and remove the original special event entry.

If you had special events of the 'week' type, please verify that the newly created weekly events do not overlap with existing ones. Overlaps may cause unintended behavior.

While the system attempts to map all schedule events accurately, 100% accuracy is not guaranteed. We strongly recommend reviewing your schedules after the upgrade to ensure everything is configured correctly. If you notice any discrepancies, you may need to manually adjust the affected records.

Weather

• Removing weather tag from weather stations.

• Renaming weatherPoint to weather for all weather points.

• Renaming weatherRef to weatherStationRef for all recs.

Alarm records

Both the alarm routing and notification records are injected for both new and existing projects to maintain consistent alarm notification behavior.

• Alarm Route

  • dis - Alarm Route

  • alarmRoute - notification

  • routeOn - alarm

• Alarm Notification

  • dis - Alarm Notification

  • notificationTarget - emailTopic

  • topic - alarm

  • notificationOn - active or state == "normal"

  • subject - Alarm: ${sourceRef}

Alarm digest

The alarm digest configuration has been redesigned. Previously managed through the alarm extension record using a dateTime tag, it is now implemented as a job. This new approach allows users to create, configure, and run the digest on demand, offering greater flexibility and control.

Manual update

The following items require manual updates.

MQTT

Existing deployments using the previous MQTT configuration must be updated to align with the new setup. Link: https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/33888436225

Alarm topic filters

If applicable, users need to update their alarm topicOn filters to align with the new alarm app tags.

Update and replace the old tags used on the left side of the = with their corresponding values on the right:

How to find and update alarm topics:

1. Go to Folio > Launch and query for alarmTopic to view all alarm topics.

2. For any other tags, update them based on the tags found in the alarm records.

   • To view available tags, go to Folio > Launch and run the query: alarms().

Alarm and schedule app references

If applicable, any saved Favorites, user HomePath, Top Level Graphic, Custom Header, custom app or models, or custom graphic programs that reference the new apps will need to be updated to reflect the latest versions.

Extensions update

https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/33648738306 is a major update and will requires some updates to build scripts and code files for custom pods with Fantom code to work properly with this new version.

Below is a outline of the major changes and then a list of common areas that require change.

Recompile All Pods with Fantom code using the new 5.2.0 release

All pod with Fantom code will need to be re-compiled using the latest 5.2.0 FIN release which includes pods from SkySpark (3.1.5), Haxall (3.1.5), and Fantom (1.0.78) as there has been some API and library name changes from 5.1 to 5.2. Even if no code changes are required, the pods should still be re-compiled against 5.2.0.

Dependencies

Dependencies in the build.fan file should be updated to the most recent versions

• FIN pods should be updated to 5.2.0

• SkySpark pods should be updated from 3.0.20 to 3.1.5

• Haxall pods should be 3.1.5

• Fantom pods can remain as 1.0+ or updated to 1.0.78

• Refer to https://fantom.org/doc/sys/Depend for more information on the various formats of versions (1.0 vs 1.0.1 vs 1.0+ vs 1.0 - 1.0.2, etc)

Libraries

Haxall has been fully integrated into FIN Framework; some libraries have been moved, renamed, or removed and so build.fan files and other code will need to be updated:

• many core exts, such as Task, I/O, Point, Haystack exts are now Haxall libs and have been renamed (pointExt is now hxPoint, haystackExt is now hxHaystack, etc), dependencies in build.fan files and import statements will need to updated to reflect new names and library locations

• the core lib has been removed and split between hx and skyarc

  • SysMods or Exts with a lib.trio that previously contained defs with a dependent on the core lib will need to be updated depend on hx or skyarc (or both)

• HxMsg replaces many of the previously message classes like SysModMsg and ConnMsg

• toRec and toRecList now reside in Etc class instead of SysLib

• toRec signature and return type has changed

  • checked flag parameter has been removed (setting this flag to true would return a null value instead of raising an exception if a object
    could not be cast to a Rec)

  • will now always returns a non-nullable Dict

    • all code that relied on toRec returning null will need to be updated.

• Several REST APIs have been updated/changed and some of FIN will need to be updated accordingly

  • filetypes replaces formats

  • ops now returns a table of defs

  • defs and libs ops added

  • format() and ops() are now defs instead of functions

• Pods that were previously Exts but are now HxLibs will have their class names updated as follows:

  • Pod name: fooExt.pod hxFoo.pod

  • Main file: FooExt.fan FooLib.fan

  • Axon exposed library of functions: FooLib.fan FooFuncs.fan

Modbus

• build.fan: modbusExt → hxModbus

• classes: using modbusExt → using hxModbus

• ModbusLib.modbusRegMaps() → ModbusFuncs.modbusRegMaps()

• ModbusLib.modbusRegMap() → ModbusFuncs.modbusRegMap()

• ModbusLib.modbusRead() → ModbusFuncs.modbusRead()

• ModbusLib.modbusWrite() → ModbusFuncs.modbusWrite()

• ModbusLib.modbusRegMapSave() → ModbusFuncs.modbusRegMapSave()

• ModbusLib.modbusPing() → ModbusFuncs.modbusPing() - but deprecated

  • using hxConn

  • hxConn 3.1.5+ should be a dependency in the build.fan

  • ConnFwFuncs.connPing(conn)

Point

• build.fan: pointExt → hxPoint

• classes: using pointExt → using hxPoint

• PointLib.pointWrite() → PointFuncs.pointWrite()

• PointLib.pointConvert() → PointFuncs.pointConvert()

IO

• build.fan: ioExt → hxIO

• classes: using ioExt → using hxIO

• IOLib.ioReadCsv() → IOFuncs.ioReadCsv()

• IOLib.ioWriteCsv() → IOFuncs.ioWriteCsv()

• IOLib.ioWriteTrio() → IOFuncs.ioWriteTrio()

Task

• build.fan: taskExt → hxTask

• classes: using taskExt → using hxTask

• TaskLib.taskRun() → TaskFuncs.taskRun()

Alarm

• AlarmLib.alarms() → AlarmFuncs.alarms()

• alarmRewrite - deprecated

• ackToConn - use alarmAck instead

• alarmRollup - deprecated

• alarmsCommit - deprecated

Misc

• SysLib.tzdb() → HxUtil.tzdb()

  •  using hx

  • hx 3.1.5+ should be a dependency in the build.fan

Deprecated

• Int.clip → Int.clamp

• SysLib.context → HxCoreFuncs.context

• SysLib.toRecList → Etc.toRecs

• SysLib.toRec → Etc.toRec

  • Important: if before SysLib.toRec(null) returned null, now both SysLib.toRec(null) and Etc.toRec(null) throw an error at runtime

• Proj.readBin

• Proj.writeBin

FIN 5.1.7

Automated update

BACnet

Upon startup, certain objects are automatically migrated using the bacnetMigratePoints() function. This process updates the relevant records to ensure compatibility with the latest build and BACnet configurations.

• Accumulator points (ACC)

  • Change the kind type of accumulator points in the database from String to Number.

• Schedule points (SCH)

  • Update the point configuration in the database:

    • bacnetWrite -> bacnetScheduleWrite

    • schedulable -> bacnetScheduleWriteLevel

    • writable -> removed

    • bacnetScheduleRead -> new tag

  • writeSchedule marker tag will be removed from any schedule tuning policy as this is no longer necessary for BACnet.
    Note: If this was being used for Haystack schedules as well, a separate tuning policy with this tag will need to be created specifically for those schedulable points.

FIN 5.1.0

Manual update

The following items require manual updates.

Database

The migration covers the below tag changes:

• weather → weatherStation

• weatherRef → weatherStationRef

• job → now a marker tag

• jobExpr → new tag that contains the job function

• schedule → now a marker tag

• scheduleGrid → new tag that contains the schedule events

• as well as other behind the scenes db format changes

Windows migration: https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/8129249370

Linux migration: https://finproducts.atlassian.net/wiki/spaces/FINFramework/pages/32697450497