0

SOURCE-MEDIA SYNCHRONIZER

Synchronizes the Family Historian Media Titles and Filenames with that of the associated Source Title. 

*** THIS PLUGIN PERFORMS OPERATIONS ON BOTH YOUR PROJECT AND THE LINKED MEDIA.***

BEFORE RUNNING THIS PLUGIN, IT IS HIGHLY RECOMMENDED THAT A FULL FH BACKUP IS MADE AND THAT ANY EXTERNAL PROJECT MEDIA ARE ALSO BACKED UP. REMEMBER; THE FAMILY HISTORIAN ‘UNDO’ CAPABILITY CANNOT RESTORE CHANGES MADE TO THE NAMES OF MEDIA FILES. TO RELIABLY RESTORE A PROJECT, RESTORE BOTH THE PROJECT AND ITS MEDIA FILES FROM THEIR ASSOCIATED BACKUP SET.

Design Concept

Upon invocation, Source-Media Synchronizer displays an initial notification panel to alert the user that the plugin alters data and backups are recommended. The user can choose to “Ok” to proceed or “Cancel” to exit. This panel also provides access to online help via a “Help” button..

Upon selecting “Ok” the plugin performs a detailed scan of the media-related linkages of a project to produce a list of source that it is capable of processing. Synchronization attempts to utilize a source title as the basis for the title of media items, including their links/filenames. Filenames of a directory must be unique. Therefore, the noted scan is focussed on ensuring that attempting synchronization with the source name would not result in an “illegal” filename.

Upon completion of the scan, the plugin detects the presence of any Local Media Objects (LMO) that should be converted to the standard media objects. The use of standard media objects is strongly encouraged in FH7, to the extent that it will automatically offer to convert them when a project is opened and as part of project validation. As the presence of LMOs could result in those files not being synchronized; the plugin will alert the user to the presence of LMOs, suggest the user convert them and then terminate.

If there were no LMOs, the user is presented with a list of those sources for which the associated media can safely be synchronized. The user may select one or more of those sources, which will be submitted for synchronization upon pressing the “Ok” button.

Just as the initial scan performs a series of checks, so does the subsequent processing phase. Here validations are focussed on issues that a user can easily repair, as well as detecting sources requiring no change and can be skipped. Typically;  these issues include the length of titles and broken links.

During synchronization; file-handling errors associated with renaming/retitling will also be detected and logged. The plugin first attempts to update the filename. If this is successful, it will then update the Family Historian title and linkage to the file. Renaming is carried out in a way that ensures that a copy of the original file is preserved, until the renamed copy is in place. Therefore; should the renaming be unsuccessful, the original file can be located in the plugin’s data directory.

It should be noted that, when the plugin predicts that the initial scan or subsequent processing might result in long periods of apparent inactivity, it will display a progress bar to allow one to see the progress of the current operation.

Once the processing phase is complete, a Result Set will be displayed. The Result Set shows the status of each key step in synchronizing the sources, as well as any errors encountered in the process. It also reports the total number of sources processed.

A Result Set displays the Source ID, Source Title, Media ID, Old Media Title, New Media Title, Type and Message. The noted ID fields are actually linked to the associated source or media properties panel, to facilitate examination/editing. Be aware that some errors, such as file-system failure issues, cannot be addressed via these links. The last two fields, the Type and Message fields, are important. The Type field displays the category for the subsequent longer Message field, which provides a more detailed description. Typical types and Messages are;

ERROR

  • “Source title too long.” [Title is greater than 260 characters.]
  • “Non-existent file (broken link).”
  • “Error moving file: ” .. <specific error>
  • “Set media title: Failed.”
  • “Set media file link: Failed.”

INFO

  • “No change required.”
  • “Moved file.” [File has been renamed.]
  • “Set media file link.” [Link has been set.]
  • “Set media title.” [Media title has been set.]
  • “User cancelled processing.”
  • <number> .. ” sources processed.”

Standard Features

  • To ensure that media item link paths and filenames are Windows-compliant any occurrence of one or more of the set of illegal characters [\/:*?”<>|] are replaced with a single tilde [~]. This substitution is only performed on modified file links. It is not required for Source Titles and Media Item Titles, as FH has no similar constraint on title naming.
  • Media records may have one or more associated files. Currently; FH7 only recognizes the first in producing reports etc. Let us call this; “Standard Naming”. However; this plugin will handle the full set, but names them slightly differently. Let us call this; “Augmented Naming”. If any instance requiring “Augmented Naming” is detected; the whole source will use this naming style, which is more appropriate to cases in which multiple image file are attached to media records.
    • “Standard Naming”
      When one or more media items are associated with a source, the first occurrence is named to reflect the source title. Subsequent attached media are also named to reflect the source title, but a numeric suffix [ie. #2 ..] is added to ensure the resulting name is still unique. Note that this affects both the media item title and the link.
    • “Augmented Naming”
      All occurrences are named to reflect the source title, but also have a suffix. The suffix takes the form #1-1, #1-2.. #2-1, #2-2.., which affects both the media item title and the link. The first number reflects the media item of the media record and the second pertains to the file of the media item.

Safety Notes

  • Unforeseen events (eg. power failures etc.) can potentially result in catastrophic system failures. While these are hopefully very rare, there is no reliable way to predict or prevent them. While this plugin does protect against foreseeable issues, regular data and project backups remain the ultimate risk mitigation strategy.

Frequently Asked Questions

  • How does this plugin handle [long] Titles and Short Titles?
    • The FH behaviour, with respect to the use of [long] Titles and Short Titles is a user configurable option. The user can access it via a checkbox (see “Tools > Preferences > Records Window > Use Short Title for Source record names if available”).  The plugin honours that preference in  displaying the Title or Short Title in the Records Window.
  • Some of my filenames are in a different case than their title in the project. Can the plugin handle this?
    • The Windows filesystem is not case sensitive, so one may not have consistently used case in the naming of media files at the system or at the project level. This plugin will correct filenames to reflect the case used in the source with which they are associated.
  • I have stored some media inside the Project, but some are stored externally. Can I still use this plugin?
    • Yes. Be aware that when a source has multiple media records, synchronization with the source results in a suffix being added. This is because the plugin views each source as pertaining to a set of data. So; you may wish to subsequently colocate all the media for a given source.

 

Help content on this page is provided by, Gary Gauthier, the plugin’s author.

[Last updated: 8 June 2025]

[Reason: Released v0.1.9]

Help content on this page is owned and provided by Gary Gauthier, the plugin's author, Calico Pie takes no responsibility for its content.