Using the Merge Fields, you can trigger Vault to search within a Microsoft Word (DOCX only) or Microsoft Excel (XLSX) source file and replace certain tokens with field values from the Vault document. Merging fields can make it easy to create templates that auto-populate with details like product name, document status, and version date. You can also use this to add a title page to a document that shows the document name or document number from the Vault. Note that Merge Fields must be enabled by an Admin.
When Vault replaces tokens with field values, the system saves the updated version as the source file. If you download the source file on a document with field merging, you will see the Vault field values, rather than the tokens. Download the Unmodified Source file for a version that retains the Merge Field tokens.
Important: You can create merge tokens using the Vault token format described below. Vault does not support Microsoft tokens such as DOCVARIABLE tokens.
How to Add Vault Fields to a DOCX or XLSX File
Vault looks within the uploaded file for text that matches this pattern:
${vault:fieldname__v}
Note: All merge field tokens, except for VQL operators and filter criteria, must be lowercase. In addition, merge field tokens cannot exceed 1000 characters in length.
Document Fields
Vault fields that you reference in the source file can be custom or standard document fields. You must use the field names, not labels. Admins can find the name for a document field in its configuration details.
${vault:secondary_product__c} or ${vault:status__v}
Fields on Referenced Objects
You can also use fields on objects that are referenced by the document. Object field tokens follow this pattern:
${vault:relationshipname__vr.fieldname__v}
The first portion of the token is the name of the relationship between the object and document type. The second portion is the name (not label) of the field on the object. You can also include fields from objects related to the document’s related objects. For example, Advertisement documents reference Product records and Product references the Product Family object. You could add a token like
${vault:document_product__vr.product_family__vr.name__v}
to display the name of the related Product Family record. You can create tokens with up to five (5) relationships. These tokens support both inbound and outbound relationships.
Merge Fields with Rich Text
Vault supports merging on Rich Text fields in Microsoft Word files, allowing tokens to resolve and display using the rich text formatting specified in the Vault Rich Text Editor.
Rich Text object field tokens follow this pattern:
${vault:relationshipname__vr.rich_text_fieldname__v;richtext}
Note: Existing formatting on Rich Text tokens in Microsoft Word files may conflict with Rich Text formatting in Vault.
Supported Rich Text Fonts & Text Styling
Merged Rich Text fields support the font families and styles available in the Rich Text Editor:
| Font in Rich Text Editor | Merged Rich Text Fonts |
|---|---|
| Sans-serif | Inherit default, sans-serif |
| Serif | Times New Roman, sans-serif |
| Fixed width | Courier New, monospace |
| Wide | Arial Black, sans-serif |
| Comic Sans MS | Comic Sans MS, sans-serif |
| Garamond | Garamond, Times New Roman, serif |
| Georgia | Georgia, serif |
| Tahoma | Tahoma, sans-serif |
| Trebuchet | Trebuchet MS, sans-serif |
| Verdana | Verdana, sans-serif |
Supported font styles include:
- Bold
- Italics
- Underline
- Strikethrough
- Subscript
- Superscript
Supported text alignments include Align Left, Align Center, Align Right, and Justify. Ordered lists, bulleted lists, and indentations are also supported.
Vault supports the following symbols: β µ ~ < ™ ° ± α CM /Ct ö é ‡ Þ ñ ú X3 √ © ∑ Π ≠ π.
Merged Rich Text fields support the text and background colors available in the Rich Text Editor.
Hyperlinks
Vault supports hyperlinks for email and web addresses added in the Rich Text Editor with display text and email address or URL.
Limitations
The following limitations apply to merge fields on Rich Text fields:
- Vault does not support blockquotes in Rich Text merge fields.
- Vault does not support Rich Text fields in Merge Fields barcodes.
- Using Rich Text token syntax on a non-Rich Text field results in the token being merged as plain text.
Multi-Value Object Reference Fields
When you include a token for a multi-select object reference field or for fields on that object, Vault has two ways of populating:
Lists
If the token is not within a table, the process creates a comma-separated list. For example ${vault:document_product__vr.name__v} would become CholeCap, WonderDrug, Nyaxa. Vault limits merge field lists to 1000 values.
Tables
If the token is within a table in a Microsoft Word file, the process creates a separate row for each value. For example:
| Name | Status |
|---|---|
${vault: document_product__vr.name__v} |
${vault:document_product__vr.status__v} |
| Name | Status |
|---|---|
| Cholecap | Active |
| WonderDrug | Active |
| Nyaxa | Active |
If a row includes two unrelated multi-value fields, the first field will populate as rows, but subsequent fields will populate as lists.
Merging fields using the ${vault:fieldname__v} format does not repeat a row in a table. This format populates as a comma-separated list. To repeat a table row, use the full ${vault:document_objectname__vr:fieldname__v} format.
Note that barcodes do not automatically repeat in tables.
Vault limits merge field tables to 1000 rows.
Tables within Tables
Merge Fields supports tables within tables up to three levels. For example:
| Name | Status | Country | ||
|---|---|---|---|---|
${vault:document_product__vr.name__v}
|
${vault:document_product__vr.status__v}
|
|
| Name | Status | Country | ||||||
|---|---|---|---|---|---|---|---|---|
| Cholecap | Active |
|
||||||
| WonderDrug | Active |
|
||||||
| Nyaxa | Active |
|
When using repeaters in a table, Vault only displays values in nested tables that are relevant to the object record in the row.
Record Filtering & Sorting
You can include a WHERE clause in a token for a multi-select object reference field to allow Vault to filter on multiple data values and only display relevant information.
For example, the token pattern: ${vault:document_quality_event__cr.findings__cr.criticality__c;WHERE findings__cr.criticality__c = 'Major'} would return a filtered list of Findings related to the Quality Event, with a Criticality value of Major.
You can also include an ORDER BY clause in a token for a multi-select object reference field to allow Vault to order the displayed fields. Follow the clause with ASC for ascending order, or DESC for descending order.
For example:
${vault:document_quality_event__cr.lead_auditors__c; ORDER BY lead_auditors.name__v ASC} would return a list of Lead Auditors related to the Quality Event, sorted by name in ascending alphabetical order.
Record filtering and sorting are only available in Microsoft Word files. Learn more about filtering and sorting with merge fields.
Important: Filtering is not supported when using Merge Fields in Microsoft Excel.
Annotations with Merge Fields
Vault can use merged field values as the placemark location for an annotation. If you add, modify, or delete a value in a merged field that provides text for an annotation placemark, Vault may shift the annotation placement to the nearest adjacent text.
For example, Gladys views a document where the Product field (a merged field) contains the values “CholeCap” and “VeevaProm”. She creates a text annotation on the word “CholeCap” in her document, which is defined by the merged field. If a user then deletes “CholeCap” from the Product field, Vault re-renders the document and moves the annotation placement to the text in closest proximity to the previous position of “CholeCap”.
Barcodes
You can enter tokens that Vault uses to generate barcodes in your DOCX templates.
Vault replaces the field values with Code 39 Extended barcodes, and new source files have barcode images embedded in the document. When you download the new source file, the barcode will work on all computers. Barcode generation is only available in Microsoft Word files.
Invalid Tokens & Blank Fields
For the merge to occur, the field name must match an actual document field in the Vault, that field must be valid for the document, and that field must have a value. For example, if you upload a file that includes the token ${vault:document_country__vr.name__v} to a document whose Country field is blank, Vault won’t find a value to merge and will not replace the token in the source file. For tokens with multiple relationships, all tokens must be valid for Vault to replace tokens with field values.
You cannot merge formula-type fields.
Example Tokens
Here are some common tokens. Vault applications and configurations vary, so some of these tokens will not work with your documents.
| Token | Related Field | Example Value |
|---|---|---|
${vault:document_number__v} |
Document Number | WD-TMF-00394 |
${vault:status__v} |
Document Status | Approved |
${vault:name__v} |
Document Name | Confidentiality Agreement UCSFMC 2014-10-23 WonderDrug |
${vault:product__v} |
Product Name | WonderDrug |
${vault:document_product__vr.abbreviation__vs} |
Product Abbreviation | WD |
Controlling Factors for Field Merging
The following factors affect whether a document is eligible for merge:
- Source File Format: The source file must be a DOCX or XLSX file.
- Merge Fields Setting: The Merge Fields setting itself should remain hidden from end users. An Admin can specify field-level security settings on the document field Merge Fields to limit which power users can edit this field. Vault automatically sets this field on the document to Yes if the source file includes valid tokens and resets this every time you upload a new source file. You can set the field to No to prevent field changes from triggering a re-merge, but the value resets anytime there is a new source file.
- Prevent Merge Fields on Steady State: This option is enabled by default. This option disables Merge Fields when the document enters its lifecycle’s defined Steady state. For example, this prevents Merge Field updates to documents that have already been approved.
- Archive Document: When a document becomes archived, Vault automatically sets Merge Fields to No to help prevent any changes to the archived document’s content.
Triggers for Field Merging
The following situations will trigger Vault to merge or re-merge fields:
- Uploading a source file (for new documents, placeholders, and new versions)
- Copying a document and including the source file
- Creating a new document from a template
- Reclassifying a document
- Classifying an unclassified document
- Updating fields that are referenced by tokens within the source file (unless Merge Fields is set to No)
- Re-rendering a document
Field Merging in Protected Sections
Vault can merge fields within a protected section in a DOCX file, or protected cells in an XLSX file. The sections with merged fields will remain protected in the source file.
For this to work, the section must be set up in Microsoft Word as follows:
- Add section breaks within the document.
- Open the Restrict Editing pane.
- Set the restrictions to allow Filling in forms and select the sections to restrict.
Note that you must set a password through the Restrict Editing pane in Microsoft Word for Vault to merge fields in the protected sections.
Limitations
Vault displays Rich Text Merge Fields as plain text and does not support Rich Text fields in Merge Fields barcodes.