Managing Word Formatted Output Templates

Vault allows you to use a Microsoft Word (*.docx) file to design formatted output templates (in contrast to Adobe formatted output templates, which require you to design templates in an XFA PDF file). By using Vault-specific syntax and tokens within your file, you can control the data included in the template, while also leveraging the formatting capabilities of Microsoft Word. Additionally, you can select either PDF (*.pdf) or Word (*.docx) as the output file format.

Microsoft Word Template Syntax

You can use Vault-specific syntax in the Microsoft Word (*.docx) file to define how data should display in the Word formatted output template. For example, ${HideTableIf(visit_status__c= 'incomplete__c')} hides the entire table if the expression provided evaluates to true. You must place this syntax in a table in the Microsoft Word (*.docx) template, and surround it with the following bracket notation: ${}. When the template is processed for an object record, Vault removes any remaining syntax once it is evaluated and executed.

The syntax below is case-sensitive. For example, ${rowSet()} is invalid. Also, this syntax is specific to Microsoft Word and cannot be used elsewhere.

Note: To view the use of the syntax below, download this template, which is based on the User object. You can add this as a test Word formatted output template to any Vault and use Download Preview to see how the syntax is resolved and view the final output.

You can also reference this template, which is the same template as above, but with comments that provide more details on the syntax and variables used to create the template.

Rowset

The ${Rowset(<relationship query>)} syntax queries a valid inbound or outbound object relationship name. The relationship must stem from the current object context (for example, the starting root object, or the current object iteration in the case of a nested table). You can include optional VQL criteria, such as the WHERE and ORDER BY clauses.

For example, ${Rowset(user__sysr WHERE status__v = 'Active')} queries all related users with an Active status, and sets the data context for the table. Once a ${Rowset()} is defined for a table, you can use a ${RepeatRow()} or ${RepeatTable()} syntax to print the queried ${Rowset()} data on the template.

You must place this syntax in the upper-left most cell of the table.

RepeatRow

The ${RepeatRow()} syntax repeats the current table row for each value returned in the currently defined ${Rowset()} syntax. If no values are returned by the ${Rowset()} syntax, Vault does not print this row on the template. You must define a ${Rowset()} syntax before using ${RepeatRow()}.

You must place this syntax in the upper-left most cell of the row.

RepeatTable

The ${RepeatTable()} syntax repeats the entire table for each value returned in the currently defined ${Rowset()} syntax. If no values are returned by the ${Rowset()} syntax, Vault does not print the table on the template. The ${Rowset()} syntax will persist into any nested tables in the Microsoft Word template file.

You must place this syntax in the upper-left most cell of the table.

HideRowIf

The ${HideRowIf(<Vault expression>)} syntax hides the entire table row if the provided Vault expression evaluates to true. The context for the expression is the current object context (for example, the starting root object, or the current object iteration if located within a ${RepeatRow()} or ${RepeatTable()} syntax). For example, ${HideRowIf(state__v = 'Inactive')} hides the row if the State field value is Inactive.

You must place this syntax in the left-most cell of the row.

HideTableIf

The ${HideTableIf(<Vault expression>)} syntax hides the entire table if the provided Vault expression evaluates to true. The context of the expression is the current object context (for example, the starting root object, or the current object iteration if located within a ${RepeatRow()} or ${RepeatTable()} syntax). For example, ${HideRowIf(visit_status__c= 'incomplete__c')} hides the entire table if the Status field value is Incomplete.

You must place this syntax in the left-most cell of the table.

How to Define Variables

You can define variables in the Microsoft Word template using #define <variable name> "<variable value>". This syntax allows you to use a variable name that is shorthand for a text string you want to reference later in the template. When the template is processed, this syntax finds every mention of the variable name and replaces it with the variable text value. Use this syntax to prevent visually cluttered templates with long syntax strings.

This syntax does not require bracket notation (${}) or placement in a table. You must define the variables before they are referenced in the template.

Variable names require a minimum of three (3) characters and can only contain alphanumeric characters, hyphens (-), and underscores (_). For example, _HIDETABLEEMPTY is a valid variable name.

Variable names cannot contain special characters (!, #, %, =, @, (), “) or use reserved syntax words, such as Rowset or HideRowIf. If your variable value contains double quotation marks, escape those with a backslash ( \ ).

You can use the following pre-defined variable to define a default value for empty field values returned on a template: #define X-VAULT-EMPTYVALUE "<default value here>". This variable displays the text value that should replace empty fields. For example, #define X-VAULT-EMPTYVALUE "N/A" prints N/A in place of any empty field values on the template.

Field Reference Syntax

To reference field values from the root object or related objects and documents, place the field name in its desired location in the Microsoft Word template with the surrounding bracket notation: ${}. You can also copy and paste these fields from the Data Model CSV file to your template. Listed below are some available fields.

Note: The bracket notation ${} is not needed if you place the field within a Microsoft Word template syntax. For example, {$HideTableIf(Rowsetcount()=0)} is valid, whereas ${HideTableIf(${Rowsetcount()}=)} is invalid.

Name	Effect
`${field_name__c}`	References a field value from the root object record.
`${outboundrelationshipname__cr.field2__c}`	To reference a specific field from an outbound related object, you can pre-pend the field name with the outbound relationship name using dot notation. This syntax only works for one (1) level of outbound relationships.
`${user__sys.first_name__sys}` `${user__sys.last_name__sys}` `${user__sys.name__v}` `${user__sys.username__sys}`	Displays the name and username of the user that generated the formatted output.
`${fo_generated_datetime}`	Displays the date and time when the formatted output was generated.
`${Rowsetcount()}`	Returns the total number of values returned in the `${Rowset()}` syntax.
`${Rowsetindex()}`	Returns the number (index) of the current `${Rowset()}` iteration for the given `${RepeatRow()}` or `${RepeatTable()}` syntax. This syntax is a 1-based index. You must place this field within a row or table with a `${RepeatRow()}` or `${RepeatTable()}` syntax.
`${file_name__sys;imageSize:200px}`	Prints the image of a related attachment on the template. Vault scales the image down so its largest dimension meets the specified pixel size. Vault supports the following image file types: .emf, .wmf, .pict, .jpeg, .png, .dib, .gif, .tiff, .eps, .bmp, .wpg. If the attachment file is not one of the aforementioned image file types, Vault prints nothing on the template. This syntax is only available for attachments on the object record (listed in the Attachments section) and not for the Attachment field. You can only use the `imageSize` syntax on the `file_name__sys` field. See below for an example of how to use this syntax in your template:

How to Create Word Formatted Output Templates

To create a Word formatted output template:

Navigate to Business Admin > Templates > Formatted Outputs.
Click Create Formatted Output.
Select Microsoft Word from the Input File Type picklist.
Enter the Label.
Optional: Modify the Name. This value does not appear to end users. It is used through the API.
Select an object from the Root Object picklist.
If the object has object types, select an object type from the Root Object Type picklist.
Optional: Click Download Data Model to download a CSV file that contains the fields from the root object, as well as related objects (up to two (2) levels) and their fields. You can use the CSV file to navigate object relationships you want included in your output, as well as copy and paste the ${Rowset()} and field syntax to your Microsoft Word template. Inactive objects and fields are excluded from the CSV file, as well as the repeated inverses of previously listed relationships (such as object B’s relationship back to object A, when the relationship from A to B was already included).
Design your template in Microsoft Word using the syntax described above.
Click Choose and upload your Microsoft Word (.docx) file. Once attached, the file name appears next to the Choose button. Vault runs an automated validation process at this time and may display an error message if any errors are detected.
Select Word or PDF from the Output Format picklist.
Click Save.
Click Download Preview to test your template with a record in your Vault to ensure the template operates as intended. This action downloads a zip file which contains the sample output file as well as a debug log, which includes any errors encountered during the process to assist with troubleshooting.

Once your template is complete, you can expose it as a user action.

How to Edit Word Formatted Output Templates

To edit a Word formatted output template:

From the Formatted Outputs page, click on a template from the list.
Click Edit.
Make any necessary changes. You can update the Label, Name, uploaded file, and output format. You cannot change the root object or root object type, or the input file type.
Click Save.

How to Delete Word Formatted Output Templates

To delete a Word formatted output template, hover over the template you wish to delete and click the red (x) button. From the Delete Formatted Output Template window, click Continue. You can also click on a template and click the Delete button.

Configuring the User Action to Download a Word Formatted Output Template

To allow users to generate an output from your configured Word formatted output template, you must configure the Download Formatted Output user action on an object lifecycle state. This is the same user action regardless of formatted output type (Word or Adobe).

If the object has attachments enabled, two (2) options are available for this user action:

Package and include Record Attachments with file: This includes the object record’s attachments in the download package.
Attach file to Root Object/Object Type Record: This attaches the generated Word formatted output to the object record.

If one of the above options are enabled, a user must have Edit access to the object to execute this action. If neither are enabled, users do not require Edit access and Vault can generate formatted outputs for object records in closed or locked states.

If the object has attachment security enabled, the object lifecycle state that the user action is configured on requires the following action permissions:

Package and include Record Attachments with file: Execute permission for the Attachments: View and Download action
Attach file to Root Object/Object Type Record: Execute permission for the Attachments: Upload action

Best Practices for Creating Word Formatted Output Templates

Follow these guidelines to ensure your Word formatted output template is accurate:

Design your Microsoft Word (.docx) file using the Microsoft Word template syntax and field reference syntax mentioned above. We highly recommend copying and pasting values from the Data Model CSV file to your template to reduce typo errors.
When creating your Word formatted output template, we recommend uploading your template frequently and testing incrementally during your design process. For example, start with the first group of data in your template, upload it, then test the template before adding more data. This process can assist in troubleshooting as your template grows.
When initially testing, select Word as the Output Format. This action allows for faster testing of your template. You can change this field back to PDF once testing is complete, if needed.
You can only use ${RepeatRow()} and ${RepeatTable()} in a table where a ${Rowset() is defined.
Start all variable names used in #define with an underscore (_) and use all capital letters (for example, _HIDETABLEEMPTY). This can help differentiate variables from other text in your document.
If some content is not operating as expected in your Microsoft Word document, such as spacing, padding, and text wrapping, check the settings of your table. Right-click the table and navigate to Table Properties (or use the Layout tab) to check your table’s details, such as cell margins, cell alignment, text wrapping, and fixed column width.

Limitations

Up to ten (10) pages per Word template input file.
Up to 2,000 records can be printed per individual relationship captured in a ${Rowset()} syntax.
Up to five (5) levels of relationship traversals are supported from the root object.
Up to 30 unique related entities can be referenced in the template. This includes related objects, documents, and attachments.
You can only use one (1) ${Rowset()} syntax per table. However, you can nest tables, and each nested table can have its own ${Rowset()} syntax.
You can only use one (1) ${RepeatRow()} or ${RepeatTable()} per cell.