Manual Migration from 4.5 to 5.0

To run the migration manually, the user can follow the below steps. If you have a FIN 4.5 project backup, but don't have FIN 4.5 installed, look at step 2 below on how to migrate that without the FIN 4.5 service.

1) FIN Stack 5.0 Installed

First, the user will have to have FIN Stack 5.0 installed on the machine. Look at FIN Stack 5.0 Windows Installation for how to install FIN 5.0.

2) Stop both FIN Stack Services

Then, the user will have to stop both FIN Stack 4.5 and FIN Stack 5.0 services. In order for migration to work, both services cannot be running. In the Services app, the FIN 4.5 service is called "FIN Stack service", while FIN 5.0 is called "FinStack5 service".

3) Navigate to bin folder of FIN 5.0 through Command Prompt

Next, the user will need to open a Command Prompt as admin. Once open, navigate to the 'bin' folder of FIN 5.0 directory. It should look something like below but with your version.

Command: cd "\Program Files (x86)\FIN Stack\FIN Stack 5.5.1153\bin"

Open

4) Migrate Command

Once looking inside the bin folder of FIN 5.0, the user will need to execute the migrate command below that has the path to the FIN 4.5 project to migrate. This will get the migration ready.

Migrate Command: migrate db -proj "C:\Program Files (x86)\FIN Stack\FIN Stack 4.5.851\db\demo"

Open

Note: If you have multiple projects and you want to migrate them at the same time, you can select the parent 'db' folder itself. That will migrate all the projects under the db folder at once.

Migrate Command: migrate db -proj "C:\Program Files (x86)\FIN Stack\FIN Stack 4.5.851\db"

5) Start Migration

Once the above is executed, the user will be able to see the locations that it will be looking at. The user will also be prompted if they want to continue with migration or not. Type 'y' for yes to continue.
You may see "The system cannot find the file specified." but just give it a few moments and it'll load.

If migrating multiple, it'll look like the screenshot below the first one.

6) Folio Migration Completed

Then once the initial folio record migration is complete, the user will get a result of errors if any. If they scroll up in the command prompt, they can see the errors and what it was for. Most will be pod errors, which is ok to continue with those. The user will type 'y' for yes to continue migration.

If migrating multiple projects, there will be a prompt for each one.

Here you can find possible folio migration errors we have come across Migration Errors.

7) Migration Complete

Once that is done, the migration is complete and the command prompt should return back to the bin folder. If there are errors, the user can scroll up to see them. Common ones might be weather-related which is ok ignore those. The user can now start the FIN Stack 5.0 service and log in to the project.

Here you can find possible DB migration errors we have come across Migration Errors.

8) Important Funcs

Once manual migration is complete, the user will have to run the below funcs per project to help update a lot of filters/tags with the correct id's, as well as update the bacnetServer tags if used. The id format has changed in FIN 5.0 from something like id==@1eeaf23d-b2ddf0f3 to something like id==@p:demo:r:1eeaf23d-b2ddf0f3

Funcs to execute in folio with bacnetServerMigrate being optional if being used in project:

• finMigrateFilterIds() - this would update the id's on certain filters such as graphicOn, programOn etc. If not updated, those records wouldn't appear or function without proper id format. For example a floor graphic usually only runs on a single floor so its graphicOn would be an id of a floor. They would have to be updated manually or using the function. If the user notices that the id's weren't updated, then can run the function in folio to update them. Then check to see if it worked. If not, contact your distributor.

  • Example use: finMigrateFilterIds()

• finMigrateFinFile() - this would update the id's on virtualPoints, bindings, query tags inside graphics, programs etc. However, may not update id's in a program/event inside a graphic. Those would have to be updated manually if there are any hardcoded in there. This can also be ran in folio if they weren't updated.

  • Example use: readAll(fin5).each x => x.finMigrateFinFile() OR finMigrateFinFile(@record_Id)

• bacnetServerMigrate() - this would update the below bacnet tag names to the new tag names in FIN 5.0. This would be for projects using bacnetServer in FIN 4.5. The ext needs to be enabled.

  • bacnetNetwork → bacnetServerNetwork

  • bacnetLocalAddress → bacnetServerLocalAddress

  • bacnetMacAddress → bacnetServerMacAddress

  • bacnetDevice → bacnetServerDevice

  • bacnetInstance → bacnetServerInstance

  • bacnetCovIncrement → bacnetServerCovIncrement

    • Example use: bacnetServerMigrate()

9) Program Status

After running the funcs above, the user now needs to remove the programStatus tag from the program records. To do this, go to Folio app and run the below query.

• Example run this query: readAll(program).toRecList.map(r => r.diff({-programStatus})).commit

• If you get an error with the previous query, run this one: readAll(program).toRecList.map(r => r.diff({-programStatus}, {transient})).commit

10) Users App Access

The users "Application Access" will need to be updated if there were restrictions on certain apps for certain users. The superuser would go to the Users and edit the users who need restrictions to certain apps and update the "Application Access" property. If they didn't have restrictions to any app, then they are fine.

11) Actions

If the user has modified their actions due to them being unique Niagara Network actions and used this doc Haystack Niagara Network Actions, then they need to update them. The change is a simple text of .parseRef appended after haystackWrite. You can use the Action Category Permission tool to mass update them.

12) Email SMTP Settings

The user will need to re-enter the email SMTP settings if they had that enabled for use in FIN 4.5. In the Home page after logging in to FIN 5, go to the Settings tab on the top. Then enter the email SMTP settings in the top section of that page.

13) Bacnet Connector Tag

If the user has Bacnet connectors and they have the bacnetForcePolling marker tag on them, then they would want to remove that tag from the connectors as its no longer supported in FIN 5. It was replaced with bacnetDisableCov marker tag and that goes on a tuning policy that is applied to the Bacnet connectors. If you don't have the bacnetForcePolling tag applied to the Bacnet connectors, you can skip this step.

1. Go to DB Builder and select the Tuning Policies tree

2. Select the tuning policy that is applied to the Bacnet connectors (this is assuming the Bacnet connector(s) already have one. If not, create one and apply it to them)

3. Then click on the i icon next to it on the left side under the Essentials column

4. Add the bacnetDisableCov marker tag and save it

5. Then disable the Bacnet Connectors

6. After disabling, re-enable a handful of Bacnet connectors at a time

Manual Migrate on a MAC Example

To run the migrate manually here is what you'll want to do: 

1. In your command line, use cd to reach your FIN’s bin folder. 

2. Once you're in the bin folder, run chmod +x migrate

3.  run  ./migrate db

4. It will then show you what will be migrated and ask you if you want to continue. enter "y" if you want to proceed.