MasterFile DocumentationHow Tos ArticlesUpgrading MasterFile 5.x to 6.x for standalone and Domino server users

Upgrading MasterFile 5.x to 6.x for standalone and Domino server users


From MasterFile 6.x, the upgrade process, error handling and reporting has been significantly improved.

All upgrades now take place locally and not on a Domino server. For standalone users, this means there is no conceptual change in the steps you go through, but for those using a Domino server, i.e. have multi-user setups , the workflow is new and also explained below. The actual upgrading step is very simple; the preplanning organziation and backup is what requires some thought and explained in its own section below.

Note that briefcases must also be upgraded if they are to work properly. However, since only locked briefcases can be upgraded, any unlocked briefcase will have to be completed and locked before its source database is upgraded. If this is not possible, and the source database must be upgraded, then the briefcase will need to be recreated. Use the [R+ Evidence Cruncher/Tag with topic in source DB] function to tag the briefcase's contents in its source database. All those profiles will then appear categorized by your topic in the 'documents by Issue/Topic' view so you can easily add them back to a new briefcase created with MasterFile version 6.x.

If you prefer, you can also have our professional services staff complete your upgrade; please mail support for costs and further details.

Domino server users - process

Since the upgrades are all run locally, managing the replication process is the key aspect for a smooth upgrade process, the main steps of which are:

  1. Select a MasterFile workstation with the latest version of MasterFile (v6.x) installed on which upgrades will be run. We'll call this the Upgrade Workstation. Scheduled replication on this workstation must be turned off.
  2. Login with a Domino Administrator ID.
  3. Select a few databases to upgrade. We'll call this the Upgrade Batch. 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 you want to upgrade, which will be deferred, which ones are in the current Upgrade Batch, etc.
  4. Users working with databases in the Upgrade Batch on-line must must close those databases Users that have local replicas must replicate with the server and then close those databases. During the upgrade process, users can continue to work in other case databases, i.e. not in the Upgrade Batch, but if they can wait until the batch is upgraded, that would be preferable.
  5. Replicate the Upgrade Batch to the Upgrade Workstation and/or create any new replicas as needed. This step creates the local replicas of all databases in the Upgrade Batch. We'll call this the Local Upgrade Batch. The Local Upgrade Batch is what will be upgraded.
  6. After upgrades complete successfully, replicate the Local Upgrade Batch to the server. This step upgrades those databases on the server.
  7. Once replication completes, install MasterFile 6.x for users working in databases in the Upgrade Batch. These users must replicate with the server to upgrade any local replicas of the Upgrade Batch database unless they work directly on the Domino server, in whcih case they can simply resume working.

If you have very large databases or want to run the entire upgrade process at one go and you 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 cases. However, no users will be able to use MasterFile or Domino until the upgrade is complete.

Standalone users - process

Standalone users have no special tasks to perform.

Backing up

Prioritizing databases to upgrade

It is not necessary to upgrade all your databases; in fact, this might be a good opportunity to move dormant and in-active cases into subfolders and/or appropriate tabs in Notes. You can therefore upgrade just active cases and deal with others if they become active again. Any case created with an older version of MasterFile can be opened and browsed -- but generally not worked in until upgraded. This is why we strongly recommend that you upgrade all your active databases as quickly as possible such as over a weekend.

Note that henceforth when we refer to databases or cases, we mean your active cases -- whether that is some or all of your cases.

Domino Server users

As local replicas of server databases are upgraded, the server 'copies' therefore serve as the "backup" when you need a fresh, new replica in which to fix reported errors from a failed upgrade before re-attempting upgrade. This is why all replication and scheduled replication must be turned off on the Notes client. See the section "Fixing errors" below for more information.

Standalone users

Standalone users must back up all their case databases before beginning.

  1. Copy the Notes Data\MF folder to a folder outside the parent Notes folder. Note that you may have MasterFile databases that were created in the  Notes Data folder itself, and in that case, copy those to your backup MF folder and move them into the Data\MF subfolder as well.
  2. If you use a MasteFile database folder(s) that is not a subfolder to the Notes Data folder and/or it's located elsewhere on your system, please email support, provide the full paths to your installation and data areas, and request instructions.

If a database upgrade failes, you will need to shut down Notes, delete the database that failed to upgrade from the Notes\Data\MF or respective folder and copy that database into that folder from your backup. After fixing errors in the restored backup of the failed database, re-run the upgrade. This is explained in the section "Fixing errors" below.


Things to note

  • We suggest you upgrade small batches of 10 or so databases; less if the databases are large (i.e. several hundred MB or several GB or more);  more if the databases are small.
  • There are three methods to populate the "Databases to upgrade" section of the Upgrade databases dialog box.
    1. Choose individual databases one at a time from their folders. This is preferable when you're upgrading a small batch of 1 - 5 databases and they're all in one folder.
    2. Select an entire folder. We don't recommend this unless there are approximately 10 or so databases in the folder as explained above, but it's a quick method if appropriate, as you have to simply select a file in that folder and MasterFile will add all its files to the "Databases to upgrade" section.
    3. Use the "Load databases from file" command. This lets you populate the "Databases to upgrade" section from a list of databases in a text file. This is the preferred method if your databases are in different directories. It is also easier and faster to reprocess a set of databases as it saves picking the databases one by one again if there were errors and is explained further below.
  • We suggest running the Analyze function first; several log files are created in this phase. A summary file lists databases with errors; log files for each database list the actual errors detected. No upgrade changes are made during this phase.
  • The next step is to correct any errors reported, and then for standalone users, to back up any corrected databases to a new folder outside the parent Notes data folder. You will need this newer version to restore in case its actual upgrade fails due to other errors.

Step 1 - Database preparation

You will have to confirm the following steps have been completed for each database so please ensure they have been checked before proceeding with analysis or upgrade.

Step 2 - Analysis

Open the MasterFile_Template, click on [R+] > Administration > Upgrade Databases ...

and you will see the following dialog box.

Select the databases to upgrade.

The Upgrade Databases window's buttons
  • Choose a database and Choose a directory - these are self-explanatory.
  • Load database list - this loads a list of databases to upgrade -- either a manually prepared TXT file or one that was previoulsy saved with the "Save database list" button. The format is one line per database, using the full path. See the section "Creating a list of the databases in a folder" below.
  • Save database list - this command saves the current list shown as a timestamped TXT file in the MasterFile program folder (default C:\Progam Files (x86)\MasterFile). It can be used to reload the set of databases shown. After an actual upgrade step, any databases still with errors will be listed in the "Upgrade databases" section of the dialog box. Saving that list lets you easily reload them once you've dealt with the errors instead of re-selecting them again indivdiually.
  • Remove database - removes the selected database from the list of databases to be upgraded.
Creating a list of the databases in a folder

You can easily create a database list using Windows Explorer.

Select your files in Windows explorer.

Use the Windows Copy Path command in Windows Explorer's ribbon bar to copy the paths of the files, paste into Notepad as shown and save the file. In the example below, I saved the file as "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 resave the file.

Note that with many or large databases this can take several minutes and you might see the Notes title bar display a message from Windows saying "Upgrade Databases (not responding)" which can be ignored. Windows will adjust itself once the open process completes and you'll see the following message:

Running the analysis

When the "Databases to upgrade" section is populated, you might see some database flagged with warnings. In this batch one database has a warning message. Warnings can generally be ignored; errors need to be fixed before proceeding. Clicking on the file name displays more details about errors and warnings shown in the "Database details" section. In this case, the warning line states the database contains locked profiles but they will  still be upgraded.

If there were errors reported during analysis, you must correct those before proceeding. We suggest you first save the displayed list of databases as a text file using "Save database list" so you can reload them to upgrade easily. This function is explained in "Fixing errors" below.  Once you've resolved any errors, exit Notes and back up the corrected database (to a new folder outside the Notes data folder) as you will need that version in case its upgrade fails during the upgrade process itself.

Note that the analyze step is a prescreen for errors that need to be fixed before the upgrade process. Addtional errors may be detected during the upgrade process itself.

As there are no errors in this batch, we can proceed to upgrade.

Step 3 - Running the upgrade

Select "Upgrade" and check all boxes.

Also check the list in the "Databases to upgrade" section as after analysis, only databases with errors are shown in this area and you will need to reload your original list of databases for upgrade.

Click OK to start the upgrade of each database listed.

Errors, if any, will be displayed in the dialog box's "Database details" section, an example of which is shown below. A Summary log for the batch and detailed log files for each database are also created during the upgrade process in the MasterFile root folder, C:\Program Files (x86)\MasterFile by default.

During upgrade

Since the upgrade step can take significant time -- from less than a minute to10 minutes or more depending on the database version, its size and the number of errors -- the Notes window might often display the message "Not responding" as shown below. You can ignore this. Windows will update the title when it can. To check upgrade progress, open the MasterFile root folder (default "C:\Program Files (x86)\MasterFile") and you will see upgrade log files being added and/or the latest one increasing in size as the upgrade process runs.

Fixing errors

Several kinds of errors can arise and these fall into two classes: Warnings and Errors.

  • Warnings: These can generally be ignored and you can proceed with upgrade except if you receive this warning message:

"Replication of this database has been disabled due to a prior, failed attempt to upgrade this database."

This most probably means you tried to upgrade a database that had failed a previous upgrade attempt instead of using its backup (or in the case of Domino sever users, a freah replica). See the section "Backing up" above.

  • Errors: All databases with errors need to be fixed. At the end of processing, you will see message pop up declaring succesful upgrade or a count of failed upgrades. A summary of the upgrade results and which databases had errors (called "Upgrade Log -- Summary.txt") as well as a detailed upgrade log for each database (each called "Upgrade Log -- A database name.NSF") is created in the MasterFile root folder (default "C:\Program Files (x86)\MasterFile").

Using the error results and log files - overview

We'll look at an example where the upgrade process has ended in which three o fthe four databases being upgraded had errors.

When the dialog box is dismissed, the Upgrade Databases window refreshes to show just the databases with errors.

The checkboxes are all deselected and databases that need fixing before their upgrade is tackled again are listed.

  • Click on "Save database list" to save the list of databases shown to a text file.
  • Standalone users:
    1. Exit Notes and
    2. Restore the databases that failed from your backup
  • Domino server users:
    1. Delete the local replicas (take care not to delete the server version by mistake) and
    2. create new replicas of the databases that failed from your Domino server.
  • When you are ready to rerun the upgrade, use "Load database list" to re-populate the Databases to upgrade section rather than finding and reselecting these databases again.

Looking in the MasterFile root folder at "C:\Program Files (x86)\MasterFile" we see the log files that were created as the upgrade ran.

  1. The upgrade summary for a the previous batch of 3 files.
  2. The detailed upgrade log for each database.

In this case, there were only three databases with errors (technically, these are 'warnings' so we need take no action, but we will used the results to explain the process as if they were actual errors). As we were upgrading four, it's easy to see the files we need to fix and manage the process. In the event we were upgrading many more, it would not be possible to just glance and see the ones we need. That's where the "Upgrade Log -- Summary.txt" file come in. It looks as below and as you can see list all databases with errors together.

The next step is to examine each of those database's detailed error log, which starts off like this

and search for "error" which will highlight the offending profiles -- which is what we need to fix -- as in the example below. We can then locate the profile in the database by its identifying criteria (from, to, date, etc.) or more simply by copying and pasting its UNID into the search bar and then fix whatever error was reported.

Error resolution - process

Now that we have the log files handy, we will

  1. Exit Notes.
  2. Copy the most recent backups (which would be the versions subsequent to Step 3 -  Analysis) of the three databases that failed upgrade to the Notes/Data/MF folder, overwriting and replacing the ones there.
  3. Fix the errors reported.

After we've fixed all the errors, we will

  1. Exit Notes.
  2. Back up these newer versions as we will need this newer version in case more errors are detected when we rerun their upgrade. In rare cares, the upgrade process can be iteratives new errors might occur each time you re-run the upgrade. Therefore, remember to save the corrected version at each iteration.
  3. Use "Load database list" and the text file we saved earlier to re-populate the Upgrade Databases dialog box and the rerun the upgrade on the three databases.

Domino server users - Final steps

  • Replicating the Upgrade Workstation 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 MasterFile 6.x on user workstations
    Once replication completes, install MasterFile 6.x for users working in databases in the Upgrade Batch. These users must replicate with the server to upgrade any local replicas of the Upgrade Batch database unless they work directly on the Domino server, in whcih case they can simply resume working.

Note that users with MasterFile version 6.x installed can open older database versions for viewing or simple editing tasks but may not run any operations like Express Load, Evidence Cruncher, etc. on them. Users still working in version 5.x can not open version 6.x databases.