Question:
How to troubleshoot common Merge Field issues in Vault?
Answer:
There are a number of issues that can arise concerning Merge Fields. This article helps the user troubleshoot these issues.
Common Issue #1: Token is blank in document viewer in Vault
When a document is uploaded and the merge field token is replaced and is left as a blank (in the document viewer), this issue can be due to the following:
-
Root Cause: The field that the token is referencing is not populated with a value prior to the document merging.
Solution: Populate the field that the token is referencing. Either re-render the document or re-upload the document. If re-rendering, be sure that the Prevent Merge In Steady State field is disabled if the document is in the Steady State. This can be done by navigating to: Admin --> Settings --> Rendition Settings --> Merge Fields. Or, move the document to a non-Steady State.
-
Root Cause: The relationship between the field referenced by the merge field token and the document type does not exist.
Solution: Be sure there is a relationship between the field referenced by the merge field token and the document type. One should be able to go from the field in the document info pane to the value the token is referencing. If not, there is an indication that the relationship does not exist. The user can create tokens with up to five (5) relationships. These tokens support both inbound and outbound object relationships.
Common Issue #2: Token is showing in the document viewer in Vault
When the document is uploaded and the merge field token is viewable in the document viewer, the issue can be due to the following:
-
Root Cause: The source document is not a Microsoft Word™ (DOCX only) or Microsoft Excel™ (XLSX) source file. These are the only file types that are compatible with the merge field functionality.
Solution: Recreate the document in Microsoft Word™ (DOCX only) or Microsoft Excel™ (XLSX) and upload the document to Vault.
-
Root Cause: The Merge Fields shared field is not added to the document type. This is required for merge field functionality.
Solution: Add the Merge Fields shared field to the document type that the document is classified as.
-
Root Cause: The merge field token syntax is not correct.
Solution: Review the correct syntax that is listed in the Vault Help Documentation: Using Merge Fields for Microsoft Word™ & Excel™ and make corrections to the token. Re-upload the document to Vault.- Ensure that there are no line breaks or other hidden characters in the token
- Check if the Merge Token contains any '/' characters, as '/' characters currently can cause merge tokens to fail in Vault.
Common Issue #3 Token did not update in the document viewer in Vault
When the document fails to update to a new value, the issue can occur due to the following:
-
Root Cause: Vault has the Prevent Merge In Steady State enabled and the document is in the Steady State. The value in the document field that the token is referencing is updated after the document is in the Steady State.
Solution: Disable Prevent Merge In Steady State. This can be done by navigating to: Admin --> Settings --> Rendition Settings --> Merge Fields. Re-render the document. Or, move the document to a non-Steady State.
-
Root Cause: The Merge Fields document field is set to No prior to the document field getting updated.
Solution: Be sure Prevent Merge In Steady State is disabled in Vault. Change the Merge Fields document field to Yes. Move the document to a non-Steady State.
-
Root Cause: The field the token is referencing is a related object field and that object field is updated. Updating a related object's fields does not trigger merge fields and thus the document is not updated. Only updating document fields triggers the document to merge and update.
Solution: One option is to make the related object field a field on the document type. Or, be sure the field is populated prior to the document creation.
Related Documentation:
Vault Help Documentation: