Synchronizing Family Historian Settings Using Directory Junctions

Creating directory junctions within Windows provides a mechanism whereby selected features, including plugins, queries, and fact sets, can be synchronized automatically between multiple PCs.  Users should have a good understanding of basic Windows file structures, using cloud storage, and working at the command line to set these up successfully .

Important note: Directory Junctions have been known to cause problems when installing ƒh updates, so it is more reliable if you use Directory Junctions as described to download the exe and install from that, rather than use the in-application upgrade procedure.

Why Are Directory Junctions Needed?

ƒh treats the storage of configuration data and files differently to the way it treats user projects. While the default location for user projects is the “Family Historian Projects” folder, within your Documents folder, this can be changed to any location that you wish to use, either locally on your PC, or even directly to network storage.

Other files that you may create while using ƒh do not have this flexibility.  For example, it expects to find plugins in a specific location in your ProgramData folder, and will not accept any other location.  For use on a single PC, this is not normally a problem.  However, if you are using ƒh on two separate PCs, as permitted by the standard licence, each copy of ƒh will only look in its own ProgramData folder, and not accept a common shared location.

As a result, additional features such as plugins, custom queries, and custom fact sets have to be copied manually between PCs whenever they change.  It would be very frustrating to be using ƒh away from home on a laptop, only to realise that the key plugin or query that you need has not been copied across.

What Are Directory Junctions?

Directory junctions are a facility available within current versions of Windows that effectively makes files or folders appear to be in two places at the same time. A full discussion of the various types of link that are available is beyond the scope of this introductory article, but more details are available in the links given at the end of the page. Directory junctions do not create a second copy of linked folders. There is only ever one physical copy of the file, but it effectively has two different addresses in the internal Windows file management system.  The linked folder is normally referred to as the Link, and the folder that actually contains the files as the Target.

Junctions can be created to link directories located on different partitions or volume, but only locally on the same computer, not to a network location. Both the source and target partitions must be formatted with the NTFS file system, but as this is the only file system now supported by Windows for its own partition, virtually all internal drives are formatted with NTFS on Windows PCs.

Junctions become even more powerful if used in conjunction with cloud storage. In the diagram below, folders in the user’s cloud storage synchronise automatically with the local OneDrive or Dropbox folder. If a directory junction is created on each PC linking a location within the OneDrive or Dropbox folder with a ƒh configuration folder, this means that any change in that folder on one PC are automatically mirrored on the other.

Cloud synchronisation

Which Way Round?

The easiest way to set up the links described above is to keep all the relevant ƒh folders in their original locations on each PC, and create a link folder within OneDrive or Dropbox. Cloud storage then keeps these two link folders synchronised. Unfortunately, neither OneDrive nor Dropbox fully support immediate two way synchronisation of link folders, and are only updated when full scans of changes are made, for example when first logging on, or forced manually. This is undesirable for our purposes, as key updates may not be replicated immediately.

The recommended solution for ƒh synchronisation is to move the original configuration folders to OneDrive or Dropbox as appropriate, and create the link folders where ƒh expects to find them. ƒh (and most other local apps) neither knows nor cares whether it is dealing with the link or the target, but with the target folders in cloud storage, synchronisation is automatic and immediate in both directions.

Which Folders to Synchronise?

As tempting as it might be to synchronise the entire ProgramData\Calico Pie\Family Historian folder between PCs to ensure that as much as possible is kept updated automatically, this is not in general a good idea, as some settings may be specific to an individual PC (and should definitely not be done if the two PCs are running different versions of ƒh).  While in principle it would be possible to synchronise any folder that can be exported or imported using the standard ƒh menus, it is best limited to folders that contain customised material that you use regularly.  The most common ones are:

  1. Plugins (C:\ProgramData\Calico Pie\Family Historian\Plugins)
  2. Custom Queries (C:\ProgramData\Calico Pie\Family Historian\Queries\Custom)
  3. Fact Types (C:\ProgramData\Calico Pie\Family Historian\Fact Types)
  4. Autotext (ƒh7 only) (C:\ProgramData\Calico Pie\Family Historian\Autotext)

Other candidates for syncing include Diagrams, Reports, Text Schemes, Flags, Icons, and Property Box tabs.

Setting Up a Junction

This work through is for creating a junction to synchronise the Plugins folder via OneDrive.  For other folders, change the folder name as appropriate, and in all cases substitute the path to the OneDrive or Dropbox folder on your PC.  Individual steps are described in sufficient detail for the advanced PC user to follow what is required.  You should ensure that you understand what each step below is doing prior to starting.

  1. The ProgramData folder is hidden by default, so ensure that File Explorer is set to display hidden files.
  2. It is best to pause OneDrive synchronisation while setting up this link, so right click on the OneDrive icon in the Notification area and select “Pause syncing”.
  3. Create a new folder in OneDrive to store ƒh settings.  This example uses FH as the folder name.  If you use the “Files On-Demand” facility in recent versions of OneDrive, it is best to ensure that this folder is always available locally, as per the screenshot below, to avoid any problems accessing it when off-line.
    OneDrive settings
  4. Move the C:\ProgramData\Calico Pie\Family Historian\Plugins folder to sit underneath the new folder created in OneDrive, in this case OneDrive\FH\Plugins.
  5. Creating a junction requires elevated privileges, so we need to open the Command Prompt as an administrator.  Enter “cmd” (without the quotes) into the Task Bar search box.  This displays a shortcut to the Command Prompt app.  Either right click on the shortcut and select “Run as administrator”, or click on the “Run as administrator” option if this is shown directly (different versions of Windows may display shortcuts slightly differently).  Windows User Account Control will prompt you for the administrator password for your PC. If you do not get a password prompt, it means that you are using an administrator account already.  This is not recommended for normal PC use.
  6. Directory junctions are created with the “mklink” command, with the following syntax:
    mklink /J Link Target

    where /J creates a directory junction, Link is the folder that is to be the new junction, and Target is the folder that serves as the target for the link, where the files are actually stored.  In this case

    mklink /J "c:\ProgramData\Calico Pie\Family Historian\Plugins" c:\Users\MyUserName\OneDrive\FH\Plugins

    Quotes are only required where the path includes spaces.  Do not use the %ONEDRIVE% shortcut to refer to your OneDrive folder, as this will create the junction in the Administrator’s OneDrive, not yours!  Spell out the path in full.

  7.  Repeat steps 2-6 on each PC that is to share the folder.

Junctions are displayed in File Explorer with a small link icon, as shown below for a PC with synchronised Plugins and Custom Queries folders.

Directory Junctions in File Explorer

To delete a directory junction, simply delete the Link folder (the one with the link icon).  Do not accidentally delete the Target folder, as this also deletes its contents.

Re-enable OneDrive (or Dropbox) synchronisation on each PC, and the folders will be kept synchronised automatically.  If the folder contents were different on each PC prior to setting up the junctions, they will be amalgamated, so it is recommended to review the contents of each folder first to ensure that any obsolete files are removed and the latest version of any common files is the one you want to make available on synchronised PCs.

If you are operating different versions of ƒh on each computer, this process works exactly the same, but it would be good practice to ensure that any plugins or queries that only run in one version are suitably renamed to make this clear in the ƒh menus.

If you need to reinstall ƒh for any reason, you will need to re-establish these links. Delete the default copies of the relevant folders within ProgramData, and rebuild the links as in steps 5-6 above.

Further Reading (Optional)

Graphical Method (Link Shell Extension)

The recommended method for setting up directory junctions for use in ƒh is to use the command line as described here, as it is easy to do and requires no additional software.  For those with a strong preference for working with graphical tools rather than the command line, there is an optional tool available as a free download, Link Shell Extension.

Other Uses For Directory Junctions

Even if you are working with a single PC, directory junctions may be useful for other purposes:

  • Continuous and automatic backup – creating junctions with a folder in your cloud storage will give you copies of the ƒh ProgramData and AppData folders that are always up to date, with the ability to roll back any unwanted changes.  This complements the Backup and Restore Family Historian Settings plugin rather than replacing it, as it does not backup configuration data stored in the Windows Registry.
  • Relocation of program folders – if you wanted to relocate the ƒh ProgramData folder to a high capacity second internal hard disk, creating a directory junction would allow you to do that.

Symlinks and File Systems

 

Last update: 08 Sep 2023