Configuring Automated Linking & Link Evaluator

Submissions Publishing offers several methods for efficiently managing hyperlinks within eCTD submissions, for example Vault Link Annotations to permalinks. While this method allows for creating link annotations more dynamically, it requires selecting link targets of the same type to existing Vault locations.

With Automated Linking and Link Evaluator, authors can identify links earlier in your organization’s document authoring and publishing workstream: While drafting a Microsoft Word document, authors select an area targeting a link that does not yet exist. Once the document is uploaded and the submission is published, publishers can initiate a Content Plan user action to automatically create the links, then verify and resolve any broken links with the Link Evaluator.

Feature Overview & Components

Automated Linking and the Link Evaluator work in tandem to generate and verify links in eCTD submissions: When Automated Linking does not create a link or generates a broken link, the Link Evaluator is a visual component available to users to identify and fix it.

However, your organization can leverage the Link Evaluator’s capabilities without Automated Linking functionality. When configured, Vault allows users to manually identify and fix failed or broken links within a submission, regardless of the method used to create the link.

This section discusses how Vault generates and evaluates links from a technical perspective. A simpler flow for authors and publishers is available in Working with Automated Linking & Link Evaluator.

Automated Linking

Vault relies on both Microsoft Word and Vault components to automatically generate hyperlinks:

• After an author highlights a string of text in their draft document to be linked within Vault, they run a Microsoft Word macro. The macro parses the selected text and adds Veeva Specific URL(s) to the selection or parts of the selection, depending on how many destinations it contains. See About Microsoft Word Macros for Veeva-provided templates. You can also build a macro to suit your organization’s requirements.
• The Veeva Specific URL is a special URL scheme specific to Automated Linking and is encoded with the link target description. Vault uses the Veeva Specific URL (along with Automated Linking Rules) to identify and generate a permalink for the targeted destination.
• Automated Linking Rules are a class of object records where Admins define specific rules for automated link creation. The rules are captured in the below objects and join object records. Vault assesses these records against the various Veeva Specific URL components when generating links.
  • Automated Linking Rule
  • Automated Linking Group
  • Automated Linking Rule Group
  • Automated Linking Search Synonym
  • Automated Linking Destination Type
  • Automated Linking Rule Destination Type
• When a publisher runs the Create Automated Links action on a Content Plan or Content Plan Item record, Vault initiates the Automated Hyperlinking SDK job. During the job run, Vault reviews the published PDF document renditions matched to the record from which the action was run, as well as all active records below it. For each PDF rendition containing a Veeva Specific URL, Vault converts it to a link based on the Automated Linking Rule Group record referenced on the Automated Linking Rule Group field in the Content Plan Item record.
• When the job is complete, Vault sends a notification to the publisher who initiated the action. The notification includes a summary of links processed, successfully resolved, and failed, as well as a link to the Link Evaluator.

Link Evaluator

The Link Evaluator relies on the following Vault components:

• When a Content Plan or Content Plan Item record is published, Vault stores all publishing-specific information in a Publishing Metadata object record for that Content Plan or Content Plan Item record. Vault relates the two components via the Publishing Metadata field on the selected content plan record.
• When a user runs the Evaluate Links action on a Content Plan or Content Plan Item record, Vault displays the Link Evaluator. This UI element shows the link information for all published PDF renditions matched to the record from which the action was run. When running the action from a Content Plan record, Vault also considers and displays all active Content Plan Item records with matched documents below it.

Configuration Overview

Configuring Automated Linking

To configure Automated Linking in your Vault:

1. Assign the Automated Linking Group field to all Content Plan Item and Content Plan Item Template object types, then add it to all object page layouts.
2. On the Automated Linking Group object page layout, configure a related object section for the Automated Linking Rule object. This section displays all Automated Linking Rules Vault considers for a given Content Plan Item.
3. On the Automated Linking Rule object page layout, add related object sections for the Automated Linking Group and Automated Linking Destination Type objects. These sections display all Automated Linking Groups where the rule appears, as well as all Automated Linking Destination Type records Vault references in addition to the rule when locating links.
4. The Create Automated Links object action on the Content Plan Item object is provisioned as active by default. To enable it, assign it to all Content Plan Item object types.
5. Review your Vault’s Content Plan and Content Plan Item object lifecycles. By default, the Create Automated Links action is provisioned for these objects as Available in All Lifecycle States. This means you must ensure that, for each lifecycle state in which publishers will be reviewing and fixing links, their role must have Execute Atomic Security permission for the Create Automated Links action.
6. Review your Vault’s security configuration and ensure users are assigned a permission set with the following permissions, listed by tab:
   • Objects > Content Plan > Object Action Permissions > Create Automated Links > Execute
   • Objects > Content Plan Item > Object Action Permissions > Create Automated Links > Execute
   • Objects > Publishing Metadata > Read
7. Create and relate Automated Linking Rule, Automated Linking Group, and Automated Linking Destination Type records to suit your organization’s automated linking requirements.
8. Populate the related field for new Automated Linking Group record(s) on your Vault’s existing Content Plan Item and Content Plan Item Template records.

Additionally, your organization’s draft documents must use Microsoft Word macros for creating the Veeva Specific URL which Vault uses to generate automatic links. See About Microsoft Word Macros.

Configuring Link Evaluator

To configure Link Evaluator in your Vault:

1. The Evaluate Links object action on the Content Plan and Content Plan Item objects is provisioned by default as active. To enable it, assign it to the below Content Plan and Content Plan Item object types. Link Evaluator is supported for these object types only.
   • Clinical (Module 5)
   • Nonclinical (Module 4)
   • Quality (Module 3)
   • Regional (Module 1)
   • Summary (Module 2)
2. Review your Vault’s Content Plan and Content Plan Item object lifecycles. By default, the Evaluate Links action is provisioned for these objects as Available in All Lifecycle States. This means you must ensure that, for each lifecycle state in which publishers will be reviewing and fixing links, their role must have Execute Atomic Security permission for the Evaluate Links action.
3. Review your Vault’s security configuration and ensure users are assigned a permission set with the following permissions, listed by tab:
   • Objects > Content Plan > Object Action Permissions > Evaluate Links > Execute
   • Objects > Content Plan Item > Object Action Permissions > Evaluate Links > Execute
   • Objects > Contnet Plan Item > Edit (required for applying overrides)
   • Objects > Publishing Metadata > Read
   • Pages > Link Evaluator > View

Defining Automated Linking Rules

Along with the Veeva Specific URL, Automated Linking Rules and its related objects determine where Vault searches for potential links within a document. The Automated Linking Rule object fields listed below are required.

• Allowed Clarifier Pattern defines the possible Content Plan Item title elements Vault will encounter when assessing a document’s Veeva Specific URL and applying Automated Linking Rules. If a clarifier does not match the Automated Linking Rule record’s established pattern, Vault does not run the rule when generating links. See Defining the Allowed Clarifier Pattern.
• Target Search Phrase defines the Veeva Specific URL element Vault should use to search for the target document. See Defining the Target Search Phrase.
• Target Search Type specifies the location of where Vault should search for the clarifier, either in the Published Document Filename, Published Document Title, or both.
• The Sequence Search Type multi-select picklist field defines the sequence and scope of Vault’s search for potential links. Vault processes the various search type options according to the logic described in Defining the Sequence Search Type.
• Target Search Folder: A comma-separated list to define the folders in which Vault should search for the target document. See Defining the Target Search Folder for details.
• Target Uniqueness Policy: A single-select field which determines how Vault should create links when it finds duplicate matching results. When you select First Match, Vault searches the current Submission first, in the order specified in the Target Search Folder field. See Defining the Sequence Search Type for details on how Vault determines the current Submission.

Defining the Allowed Clarifier Pattern

The Veeva Specific URL uses a clarifier to target links within a published document, using the Content Plan Item record’s Title (xml_title__v) field, document’s Title field, or both. The document author defines the clarifier along with other Veeva Specific URL elements when they run the macro. See also About the Veeva Specific URL for further details.

To better locate hyperlinks, Vault also references the Allowed Clarifier Pattern within your Vault’s Automated Linking Rule records. This field indicates the format and order in which Vault can expect to locate a clarifier.

For example, a {#######}{*} Allowed Clarifier Pattern allows an Automated Linking Rule to run when a clarifier starts with seven (7) numbers and has any additional characters following those numbers. In this example, the wildcard token {*} denotes any characters appearing in the Content Plan Item record’s Title field, such as the file extension (“.pdf”). You can use up to three (3) wildcard tokens in a given pattern.

You can also populate the Allowed Clarifier Pattern with specific words which always appear in a given Content Plan Item record. For example, Report-{#######} allows an Automated Linking Rule to run when the clarifier (Content Plan Item record Title) begins with “Report-“ and is followed by seven (7) numbers.

When Vault encounters an invalid Allowed Clarified Pattern, it stops processing the Content Plan Item record and updates the Link Status field to Unresolved AH - Invalid Rule.

Defining the Target Search Phrase

The Target Search Phrase field defines which Veeva Specific URL element Vault should use to search for the target document.

Each Target Search Phrase option is listed below, with an accompanying list showing the example Target Search Phrase input options which Vault uses to determine the scope of the search. URL elements in bold are the inputs to the listed Search Scope.

For reference, the Veeva Specific URL format is {VeevaIdentifier}/{version}/{Clarifier}/{target-destination-type}/{target-destination}

{Clarifier}

• Target Search Phrase value: {Clarifier}
• Veeva Specific URL: v-auto-link:v1/Form FDA 356h/Section/1.2
• Search Scope: “Form FDA 356h”

{ClarifierNumberOnly}

• Target Search Phrase value: ema-responses-{ClarifierNumberOnly}
• Veeva Specific URLs:
  • v-auto-link:v1/Question 11/Section/1.2
  • v-auto-link:v1/Question 1.2.3/Section/1.2
• Search Scope: “ema-responses-11” or “ema-responses-123”

{ClarifierTextOnly}

• Target Search Phrase value: ema-responses-{ClarifierTextOnly}
• Veeva Specific URLs:
  • v-auto-link:v1/Question 11/Section/1.2
  • v-auto-link:v1/Quest 11 ion/Section/1.2
• Search Scope: “ema-responses-question”

{TargetDestinationType}

• Target Search Phrase value: {TargetDestinationType}-12
• Veeva Specific URL: v-auto-link:v1/Report 1234567/Appendix/12
• Search Scope: “Appendix-12”

{TargetDestination}

• Target Search Phrase value: {TargetDestinationType}-{TargetDestination}
• Veeva Specific URL: v-auto-link:v1/Report 1234567/Appendix/12
• Search Scope: “Appendix-12”

{TargetDestinationNumberOnly}

• Target Search Phrase value: {ClarifierNumberOnly}-csr-go-29754-{TargetDestinationNumberOnly}
• Veeva Specific URL: v-auto-link:v1/Report 1234567/16.1.1/Appendix
• Search Scope: “1234567-csr-go-1611”

{*} Wildcard Token

You can add the wildcard token {*} to any of the above Target Search Phrase options to expand the search to any character appearing after the search phrase. Below is an example of how Vault searches when the token appears after the clarifier.

• Target Search Phrase value: {Clarifier}{*}
• Veeva Specific URL: v-auto-link:v1/Report/16.1.1/Appendix
• Search Scope: Any document with “Report” appearing at the beginning of its title

Defining the Sequence Search Type

The Automated Linking Rule object’s Sequence Search Type field defines the sequence in which Vault searches for potential links. You can select one or more of the various search type options listed below, and Vault processes them as described.

• Current Submission: The Submission record with the highest Sequence ID field value, for example 0010. When selected, Vault always searches for this record first.
• Previous Submission: A Submission record with a Sequence ID field value which is lower than that of the current Submission record. For example, if the current Submission’s ID is 0010, Vault searches 0009 as the previous Submission.
• Recent 5 Submissions: Any of the five (5) Submissions preceding the current Submission, determined by the Sequence ID minus 5. For example, if the current Submission’s ID is 0010, Vault searches 0005 through 0009.
• Cross Application: When cross-application links are enabled, Vault searches Applications which share Lead Market, Health Authority, and Health Authority Division field values. When selected with at least one of the other options, Vault also searches Submissions in different Applications, as well as Submissions in the same Application.

About Previous & Recent Submissions

In addition to the criteria described in the picklist options above, a previous or recent Submission record must also meet the below criteria in order for Vault to consider it in a search:

• The Submission record must be active with a Sequence ID (xml_submission_id__v) value beginning with a numerical value 0 and higher, for example 0001 or 1000.
• The related Dossier Detail record must not have a Dossier Status of Publishing Active.
• The Submission record must have an Actual Submission Date.

Defining the Target Search Folder

The Automated Linking Rule object’s Target Search Folder field defines the module or modules in which Vault should search for a target document. For example, if you populate this field as m1,m2,m3, Vault searches these specific binder nodes only.

The Target Search Folder field also supports special {sameFolder} and {*} wildcard tokens for narrowing the search:

• Use the {sameFolder} token alone to search a folder within the same folder as the source document. For example, if the source document’s Content Plan Item path is “m1/us/2252.pdf”, {sameFolder} limits the search to binder nodes containing “m1/us” within the submission being searched.
• Use the {*} wildcard token to match any character, including forward-slashes (/). For example:
  • m1/{*} searches only binder nodes which start with “m1”
  • m3/33-lit-ref/{*},m4/43-lit-ref/{*},m5/54-lit-ref/{*} searches only binder nodes under “m3/33-lit-ref”, “m4/43-lit-ref”, or “m5/54-lit-ref” within the submission being searched.

Defining Automated Linking Destination Types

Automated Linking Destination Type records are optional records for specifying the locations Vault should search (as it pertains to the Veeva Specific URL) when applying the related Automated Linking Rule.

For example, if an Automated Linking Rule’s Target Search Phrase is defined for the {clarifier} element only, and the clarifier appears on a document page or in a bookmark, you can relate the rule to two (2) Automated Linking Destination Type records: One for the page, and one for the bookmark. Each of these locations are captured in the Automated Linking Destination Type field Target Destination Search Type.

Defining Automated Linking Groups

Once you’ve defined Automated Linking Rules and Automated Linking Destination Types for those rules, you’ll need to add the rule records to at least one Automated Linking Group record. A single Automated Linking Group record connects one Content Plan Item and the established rules and destination types for that item via the Content Plan Item record’s Automated Linking Group field.

The Automated Linking Group record also includes the Quit on Failed Match field to define how Vault should treat subsequent rules in the group when it cannot locate a matching target for one rule. When selected, the option prevents Vault from running any subsequent rules within the group.

About the Veeva Specific URL

The Veeva Specific URL is an intermediary between a potential link an author identifies in a Microsoft Word document and the actual hyperlink Vault creates within the document once published. It consists of several elements defined in the Microsoft Word macro.

Some elements also require you to further specify requirements for locating links via Automated Linking Rules, such as the Allowed Clarifier Pattern and Target Search Phrase, as well as the rule’s associated Automated Linking Destination Type records.

Each element is represented in the Veeva Specific URL per the below:

{VeevaIdentifier}/{version}/{Clarifier}/{target-destination-type}/{target-destination}

These elements map to the example source text and Veeva Specific URL as follows:

About Microsoft Word Macros

After an author highlights a string of text in their draft document to be linked within Vault, they run a Microsoft Word macro. The macro parses the selected text and adds Veeva Specific URL(s) to the selection or parts of the selection, depending on how many destinations it contains.

About Veeva-Provided Template Macros

The Veeva-provided DOTM file includes two macros, A and B. All document authors (users) generating links must have the macro installed locally. To use it, download the macro-enabled template Word document and distribute it to these users according to your organization’s requirements.

Macro A includes our recommended best practice, especially for organizations with a strict authoring style that can be replicated with every link. Macro B is a basic alternative for links authored in a unique format which cannot be easily converted with Macro A.

Customizing Microsoft Word Macros

If you plan to build a custom Microsoft Word macro, you must ensure it meets certain criteria in order for Vault to read the URL outputs.

Some characters (or unicode code points) cannot be added to a URL’s components as literal values. Instead, you must encode them with a percent (%) character as follows:

• Forward slash (/) must be encoded as %2F
• Percent (%) must be encoded as %25

Once percent-encoded, the characters appear in their encoded formats everywhere the character would normally appear.

Additionally, URLs can only include 7-bit ASCII values, and all characters outside of that range must be percent-encoded in the UTF-8 character set. In particular, all literal characters in the URL must have a numerical value of 127 or less.

For example, the 曾 character (unicode number U+66FE) must be encoded as %E6%9B%BE.