Citation Repositories

The following information is intended for advanced users.

Overview

The Citation Repositories feature provides a mechanism to add links for popular repositories to your citations without manually entering or maintaining a full URL in the citation.

In the example screenshot above, the Citation Repositories feature added the links at the end of each citation, "Nova Scotia Archives" for citation #1, and "Ancestry" for citation #2 and #3.

This feature requires you to add record IDs to your citations or sources. Record IDs are not always obvious. Online Repository Assistant (ORA) will detect record IDs and makes them easy to copy. Gedcom Publisher's predefined Citation Repositories expect record IDs in the format extracted by ORA.

Repositories sometimes change their URL formats but usually do not change the format of their unique record IDs. Storing the unique record ID makes it easier to react to URL format changes: you can update the HRef property in the Citation Repository item in Gedcom Publisher and all your citation links will be updated the next time you make the book.

Data Requirements

To generate a link, Gedcom Publisher needs both of the following data items:

• A URL to the repository that uses one of the repository's known domain names. Typically, the URL will be in the source definition, but it may also be in the citation.

  The URL may point to the main page of the repository ("https://www.ancestry.com") or to the main page for a specific collection. The URL does not have to appear in the formatted citation output.

• A record ID set to a unique identifier in the format required by the repository. The record ID is usually in the citation, but may be in the source.

  The record ID does not have to appear in the formatted citation output.

See the Application-Specific Notes section below for information about how to configure your genealogy application.

Sources Properties

Gedcom Publisher's Sources Section includes two properties related to this feature: Citation Repositories and Default ID Field.

Citation Repositories

The Citation Repositories property is a list of Citation Repository items. For your convenience, Gedcom Publisher adds several predefined Citation Repository items. They are disabled (unchecked) by default, but you may enable one or more of them.

Default ID Field

The Default ID Field property is the name of the citation or source field that contains a Record ID. Set the property to the field name that Gedcom Publisher should use to access the record ID. The default is "RecordID".

The Default Record ID Field applies to all Citation Repository items where the Citation Repository's ID Field is set to "Use Default".

Citation Repository Properties

Each Citation Repository item in the Citation Repositories list defines a repository. Gedcom Publisher will detect citations to the given repository when (1) the citation includes a URL for one of the repository's Domains and when (2) the ID Field is set to a value that matches the Record ID Pattern.

ID Field

The ID Field property is the name of the citation or source field that contains a Record ID. This property is specific to the current Citation Repository item. When ID Field is set to "Use Default", Gedcom Publisher will use the field indicated by the Default ID Field property in the Sources Section. To use a field that applies to the current Citation Repository item only, set the ID Field property to the desired value.

Record ID Pattern

The Record ID Pattern property must be set to a Regular Expression that should match the record ID value entered in the record ID field of the citations for this repository.

• For simple record IDs where the entire value is a single component, use a pattern that matches the value.

  Example 1: The Pattern for the predefined Find a Grave repository is "^\d+$". That pattern matches a value that is all digits (0-9). An example Find a Grave record ID is "7688868" (link).

  Example 2: The Pattern for the predefined Family Search repository is "^ark:\/[0-9]+\/[^/?# ]+$". That pattern matches a value that begins with "ark:/" followed by a number and a "/", followed by text that ends with a "/" or at the end of the field value. The pattern loosely validates the structure of the Family Search record ID. The result is still a single component. An example FamilySearch record ID is "ark:/61903/1:1:KWG6-Q4V" (link).

• For more complex record IDs where the value includes multiple components that must be rearranged to construct a valid HRef, use a pattern that matches the value and parses the value into components using Regular Expression groups.

  For example, the Pattern for the predefined Ancestry repository is "^(?:1,|^)?(\d+)::(\d+)$". That pattern matches a value that has two numbers separated by one or two colons. The pattern splits the two numbers into part 1 and part 2 because the parts are in reverse sequence in the HRef. An example Ancestry record ID is "3659::2441616" (link).

HRef

Set the HRef property to a template that yields a valid URL that links to a record in the online repository. Gedcom Publisher will make one or mroe substitutions to customize the URL:

1. If the HRef property includes the text "%domain%", Gedcom Publisher will replace "%domain%" with the domain found in the citation text. This substitution solves an issue where a repository uses multiple domains and you want to produce links that use your preferred domain.

   For example, for the predefined Findmypast repository the HRef property is set to:

   https://www.%domain%/transcript?id=%1%

   If the citation includes the URL "https://www.findmypast.com", Gedcom Publisher will replace "%domain%" in the HRef with "findmypast.com". However, if the citation includes the URL "https://www.findmypast.co.uk", Gedcom Publisher will replace "%domain%" in the HRef with "findmypast.co.uk".

2. The HRef property must include "%1%" as a placeholder for the record ID value. The HRef property may include "%2%", "%3%", etc., if the record ID has a complex structure containing multiple components that are used in multiple places in the HRef.

   For example, for the predefined Ancestry repository the HRef property is set to:

   https://www.%domain%/discoveryui-content/view/%2%:%1%

   "%domain%" is replaced as described above.

   "%1%" and "%2%" are replaced with the values matched by the groups in the Record ID Pattern.

   For the record ID "3659::2441616", the resulting HRef will be:

   https://www.ancestry.com/discoveryui-content/view/2441616:3659

Domain(s)

Set the Domain(s) property to one or more domains for the repository. Specify a single domain for repositories that use only a single domain, such as FamilySearch which uses "FamilySearch.org" only. Specify two or more domains for repositories that use two or more domains, such as Findmypast which uses "findmypast.com" and "findmypast.co.uk".

When the Domain(s) property includes two or more domains, separate the domains with a semicolon (";").

For a repository that has changed domains, you may specify both the new domain and the old domain. However, in the HRef property, do not include the "%domain%" placeholder. For example:

Domains: archives.novascotia.ca; novascotiagenealogy.com
HRef: https://archives.novascotia.ca/vital-statistics/%1%/?ID=%2%

Application-Specific Notes

• Family Historian v7
• The Master Genealogist v9

The Citation Repositories feature will probably work with other products. It should be possible to configure any program that supports named fields in citations and/or sources, including RootsMagic. Unfortunately, I haven't had the time to investigate. If you are interested in using Citation Repositories with another program, please contact me.

Family Historian 7

This feature only works with templated sources in Family Historian 7. The URL can be in any source or citation field. The unique ID must be in a field by itself and you must specify the name of the field in the Default ID Field in the Sources Section or in the ID Field for a specific repository.

In the following example, the URL for the specific collection is in the "Collection Url" source element. A collection-specific URL is not required, but a URL for Ancestry.com or Ancestry.co.uk, etc., must be present so that Gedcom Publisher knows the citation is for an Ancestry collection.

FH7 does not include the "Website with Record ID" Source Template. The example above uses a custom Source Template.

The Master Genealogist

The URL can be in any source or citation field.

In the following example, the URL for the specific collection is in the "Url" source element. A collection-specific URL is not required, but a URL for Ancestry.com or Ancestry.co.uk, etc., must be present so that Gedcom Publisher knows the citation is for an Ancestry collection.

The unique ID must be in the citation's Reference field. You should set the Default ID Field to "CREF", the field name that TMG uses for that value.