Upgrading MasterFile Databases: Standalone, MasterFile Cloud and Domino server users
From MasterFile 6+, all upgrades take place locally and not on MasterFile Cloud or Domino servers.
For MasterFile Cloud or Domino server users, the upgrade workflow is new and explained in this article.
For Standalone users, there are no workflow changes.
If you prefer, you can also have our professional services staff complete your upgrade; please e-mail support for costs and further details.
Since briefcases must also be upgraded to work properly, and since only locked briefcases can be upgraded, any unlocked briefcase must first be completed and locked before its source database is upgraded. If that is not possible, and the source database must be upgraded, then the briefcase will need to be recreated after the source is upgraded.
In that case, use [R+ Evidence Cruncher/Tag with topic in source DB] from the briefcase to tag its profiles in its source database. You'll find them categorized by your topic in the '[L+ Documents > by Issue/Topic]' view from where you can easily select them all and add them back to a new briefcase in a click or two.
- The workstation on which upgrades are being performed should have the latest version of MasterFile installed. Although replication is disabled for databases being upgraded, as an additional precaution you may want to turn off Scheduled Replication on this workstation. You can upgrade using two or more workstations.
- Login to Notes with an ID that has full access to all the databases you wish to upgrade.
- Select the databases to upgrade. This is an 'Upgrade Batch'.
- Replicate the Upgrade Batch to the workstation and/or create any new replicas as needed. This step creates the local replicas of all databases in the Upgrade Batch. This the 'Local Upgrade Batch' and is what will be upgraded.
- Backup the local replicas of the databases being upgraded as described below under "Backing up." If an upgrade for a database fails, copy that database from the backup set, correct the errors reported and back that database again before reattempting the upgrade.
- After upgrades complete successfully, replicate the Local Upgrade Batch to the server to upgrade those databases on the server.
- Users working in databases in the Upgrade Batch should all have the latest version of MasterFile installed by this time. Those with local replicas must replicate with the server to upgrade their local replicas of the Upgrade Batch. Those working online can simply resume.
All users must close and exit databases in an Upgrade Batch. If they are working on local replicas of those databases they must replicate and then close those databases. Only begin upgrade after confirming no users are working on the Upgrade Batch. Users can work in other case databases but it is preferable if they wait until all upgrades are complete.
We suggest organizing and keeping track of your upgrade tasks in an Excel spreadsheet or similar so you work systematically. For example, which active databases to upgrade, which to defer, which ones are in the current 'Upgrade Batch', etc.
If you have a Domino Server (and are not using the MasterFile Cloud), and you have very large databases or want to run the entire upgrade process at one go and rarely create local replicas, please email us for an alternate upgrade process. That will involve shutting down the Domino server and working with Notes and MasterFile in local mode on the server itself. This method avoids making replicas of hundreds of cases or of very large databases. However, no users will be able to use MasterFile until the upgrade is complete.
No special tasks to perform other than backing up your databases as described below.
Prioritizing databases
It is not necessary to upgrade all databases. We suggest you upgrade just active cases and deal with others if they become active again. Any older case can be opened and browsed - but generally, not worked in until upgraded. Planning to upgrade all all your active databases as quickly as possible such as over a weekend is best practice.
When we refer to databases or cases in this article, we mean your active cases.
This moment might be a good opportunity to move complete, dormant or inactive cases into sub-folders or elsewhere where they are backed up. If you do leave them active, it might be helpful to organize these files under appropriate tabs on the Workspace.
To back up you databases, follow these steps
- Copy 'C:\Program Files (x86)\IBM\Notes\Data\MF' to a new folder outside 'C:\Program Files (x86)\IBM\'. If you are a MasterFile Cloud user your databases will be located under 'C:\Program Files (x86)\IBM\Notes\Data\V##?####\MF' where V##?#### is your MasterFile cloud account number.
- Note that you might have created MasterFile databases by mistake in 'C:\Program Files (x86)\IBM\Notes\Data\' itself. Those, like system databases, end in .NSF. Locate your cases and copy them to your backup area and to 'C:\Program Files (x86)\IBM\Notes\Data\MF' as well. Note that if you are asked to overwrite, it means you have two versions of the same case and you will have to open each to see which is the current version.
- If your MF folder is not a subfolder of 'C:\Program Files (x86)\IBM\Notes\Data\', and is located elsewhere on your system, please e-mail support, provide the full paths to your installation and data areas, and request instructions.
- Upgrade small batches of 10 or so databases; less if the databases are large (i.e. several hundred MB or more).
- Databases to be upgraded can be selected in three ways:
- Choose them one at a time. This is best when you have a few to upgrade all in one folder.
- Select an entire folder. Not recommended if there are more than 10 databases to upgrade, but a quick method if appropriate. Simply select one of the files in the folder and MasterFile will add the rest.
- Use 'Load databases from file'. This populates 'Databases to upgrade' with the list of databases in a text file. This is the preferred method if your databases are in different folders. It is also the best way to reprocess a set of databases as it saves picking the databases one by one again if there were errors.
- We suggest running 'Analyze' first which generates a summary file listing any databases with errors and log files for each database with the actual errors detected. No changes are made during this phase. Then correct any reported errors.
- Note that whether you are a Domino server or standalone user, the new corrected databases must be backed up (outside C:\Program Files (x86)\IBM\) as these will be used in case a new error is detected to fix that and re-run the upgrade. This is can be an iterative process.
You have to confirm the following have been completed for each database before proceeding with analysis or upgrade.
- Open the MasterFile_Template.
- Click [R+] > Administration > Upgrade Databases ...
- Check off all the questions.
'Select databases' loads a list of databases from a text file created previously using 'Save database list' or created manually.
'Save database list' saves the displayed list of databases as a time-stamped text file in MasterFile's default folder (C:\Progam Files (x86)\MasterFile) which can be used to re-load that set of databases.
'Remove a database' deletes it from the list of databases to be upgraded.
Databases with errors are displayed in the 'Databases to upgrade' area once the upgrade task completes. Save that list so you can easily reload them once you've dealt with the errors instead of having to re-selecting them again one-by-one.
- Select the databases to upgrade.
You can easily create a database list using Windows Explorer.
- Select your files in Windows explorer.
- Use Windows 'Copy Path' command in Windows Explorer's ribbon as shown below to copy the filepaths
- Paste into Notepad as shown and save the file.
In the example below, I saved the above list of four files as the file '4 files to upgrade.txt'.
Since Windows surrounds each filename and path with double quotes (") you need to remove them.
- In Notepad, press 'Crtl-h' which is the 'Replace' command.
- Type a double quote, ", in the 'Find what' field and leave the 'Replace with' field blank.
- Click 'Replace All' to remove all the double quotes and re-save the file.
When you are upgrading many databases, or large databases, 'Databases to upgrade' can several minutes to populate and Windows might display 'Upgrade Databases (not responding)' in the title bar. You can ignore that as Windows will adjust itself once the open process completes and the display the following message.
When the "Databases to upgrade" section is populated, you might see some databases flagged with warnings. In the example below, one has a warning message. Warnings can generally be ignored; errors need to be fixed before proceeding.
- Click on the file name to display more details about its errors or warnings. In the example below, you are alerted that one of the databases contains locked profiles. However as it's only a warning, you can still proceed with upgrading.
If errors are reported back after analysis,
- Save the displayed list of databases as a text file using 'Save database list' so you can re-load the list to upgrade easily again later.
- Resolve any errors as explained in 'Error resolution' below.
Note that the analyze step screens for errors that need to be fixed before the upgrade process. Additional errors may be detected during the upgrade process itself.
- Select Upgrade and check all boxes.
After an analysis task, only databases with errors are shown in 'Databases to upgrade'. You will need to reload your original list of databases for their actual upgrade.
- Click OK.
The upgrade tasks start.
If errors are reported,
- Save the displayed list of databases as a text file using 'Save database list' so you can re-load the list to upgrade easily again later.
- Resolve any errors as explained in 'Error resolution' below.
During upgrade
Since upgrades can be very fast taking less than a minute or run 10 minutes or even more depending on the MasterFile version, the database size and the number of errors, Windows might display the message "Not responding" as shown below. You can ignore this. Windows will update the title when it can.
The upgrade task automatically opens the default MasterFile folder (C:\Program Files (x86)\MasterFile) where upgrade log files are added and/or keep increasing in size as the upgrade tasks run so you can monitor progress.
Warnings are usually informative and can generally be ignored except for this one:
- "Replication of this database has been disabled due to a prior, failed attempt to upgrade this database."
In this case, upgrade was re-run on a database that had failed upgrade instead its backup after fixing the reported errors.
Errors all need to be fixed before proceeding.
When processing completes, a message declaring success or a count of databases that failed upgrade is displayed.
A summary of upgrade results ('Upgrade Log -- Summary.txt') which contains a list of databases with errors, and a detailed upgrade log for each database ('Upgrade Log -- database name.NSF') is created in MasterFile's default folder (default 'C:\Program Files (x86)\MasterFile') that is automatically opened in Windows Explorer by the upgrade task.
In this batch, three of four databases ended with upgrade errors.
- After clicking 'OK', the 'Upgrade Databases' window refreshes to show just those databases with errors.
- Click "Save database list" to save the list of databases shown to a text file.
- Note that whether you are a Domino server or standalone user, the new corrected databases must be backed up (outside C:\Program Files (x86)\IBM\ as these will be used in case a new error is detected to fix that and re-run the upgrade. This is can be an iterative process.
Since Windows Explorer is open at 'C:\Program Files (x86)\MasterFile' we can see the two types of log files that were created as the upgrade ran:
- The upgrade summary for a the previous batch of 3 files.
- The detailed upgrade log for each database.
Technically, these three databases only had 'warnings' so we needed take no action, but we're treating them as 'errors' to explain the process.
With only four databases, it is easy to see the files we need to fix and manage the process. If we were upgrading many more, it would not be possible to just glance and see those in error. In that case, we'd use the 'Upgrade Log -- Summary.txt' file which lists all databases and related errors.
Next, we examine each database's detailed error log, which starts off like this
and search for "ERROR" which highlights the offending profiles - the ones we need to fix - as in the example below. We can then locate the profile in the database using its identifying criteria (from, to, date, etc.) or ]simply by copying and pasting its UNID into the search bar, and then fix whatever error was reported.
The process is the same for MasterFile Cloud, Domino server and Standalone users. Since error detection can be iterative, you always restore the backup from the last pass, fix new errors, back up the corrected version, and then re-run its upgrade. You always use the most recent corrected version when re-running the upgrade task.
- Exit Notes.
- Copy the most recent backups of databases that failed upgrade to the 'C:\Program Files(x86)\Notes\Data\MF' folder, overwriting and replacing the ones there.
- Fix any errors reported.
- Back up the newly fixed up databases.
- Run the upgrade task again.
- In case of any reported errors, repeat 2 to 5 above.
Use 'Load database list' to re-populate the 'Databases to upgrade' section rather than finding and re-selecting those databases again.
Replicating the upgraded databases to the Domino Server
- Once the Upgrade Batch has been upgraded successfully, replicate it to the server. This step upgrades those databases on the server.
Installing the latest version of MasterFile
- Once replication completes, install the latest version of MasterFile for all users. Those users must replicate with the MasterFile Cloud or Domino Server to upgrade any local replicas of the Upgrade Batch unless they only work directly on the MasterFile Cloud or Domino Server, in which case they can simply resume working.