Creating Word Add-in Templates

Creating a Word Add‑in Template involves three core components:

1. A Word template designed in Microsoft Word
2. A Workbooks Report that supplies the data
3. A Template record in Workbooks that links the Microsoft Word file to the Workbooks Report

For more guidance on building Word Templates you can review our Tips & Tricks page

The Word template defines the layout, formatting, and static text of your document. You can download and adapt example templates provided by Workbooks to help you get started.

What the template can include:

1. Fixed text (for example: headings, labels, terms and conditions)
2. Placeholders for dynamic data from Workbooks Report (for example: customer name, invoice date, totals). These should be the name of the field that you want to be mapped, between square brackets, like so

[Customer Name]

Here is an example of what the header of an Invoice Word Template would look like with placeholders added:

• Use tables to structure the document
• Use unformatted tables so formatting remains consistent when data is merged

From this, you can see that not only are there placeholders to pull in details from the Invoice like Invoice Reference and Invoice Date, but also the Own Organisation details, so that if you have multiple Own Organisations, the correct details will be pulled through, instead of requiring multiple templates. Placeholders need to be configured slightly differently for images or for HTML/Rich Text fields

Adding Image Placeholders

The Word Add-In allows you to pull images from Workbooks into your template. For example, as part of your Line Items table you may want to pull through product images to show customers what they have purchased, or you may want to pull in a different header logo for your different Own Organisations. To do this, the placeholder requires additional parameters inside the square brackets.

[Picture file@image]

The placeholder is formed of the name of the field the image is pulled from, followed by ‘@image’ so that the Word Add-In knows to display the image and not just the image file name or URL. You can also specify the dimensions of the picture, for example:

• You can specify the width of an image as 100px using [Picture file@image, 100x] or,
• You can specify the height of an image as 200px using [Picture file@image, x200] or,
• You can specify both dimensions using [Picture file@image, 100×200].

If you have Rich Text fields on your records, then in order for the text formatting to be pulled through into your Template, like bold or highlighted text, the placeholder requires an additional parameter. The placeholder is formed of the name of the field the text is pulled from, followed by ‘@html’:

[Product Description@html]

The Word Add-In will support tables that iterate to produce multiple rows. The most common use of this would be to add Transaction Line Items to a document, but could also be used anywhere you have multiple records related to your header record, like Activities related to Cases, or People related to Organisations.

To do this, your Template needs to contain a table with one header row, and a second row for the data that will iterate. On the line above your table, you must write the syntax:

<repeat_table>

and in the line below write:

</repeat_table>

In order for the table to iterate.

Once you are happy with the Template, save the document as a .docx file, as you’ll need to upload it to Workbooks later.

The report is the mechanism that passes the data into the templates. Mostly the report will just need to be a simple list report that has columns for each of the fields that you would like in your template, but you can add in calculated columns and drill through to related record types.

When creating the Report for the Word Add-in you will need to ensure the below:

• On the Report View that will be used in the Template there is a column for the Record’s Id. If you have built a Line Item Report, you will need to include the Document Id, not the Line Item Id.
• When using  multiple reports, all the reports must include the Record Id for the Record on which template is placed. If the template is on an Organisation Record, then all Reports used must have an Organisation Id column. The reports can be on any Record type, but must include this Id Column.
• The Report is shared with all the Users that will have Read access to the Word Template; this is controlled through the Padlock Icon.
• The Column names within the Report need to have exactly the same spelling as the merge fields in your Word Template. They do not need to be a case sensitive match but look out for spelling and additional spaces.
• Consider carefully any criteria you apply to the Report; if a record does not appear in the Report you will be unable to create a Word document for it.

Once the Report has been created you are now able to bring this together with the template.

Once the Microsoft Word document and Workbooks Report are ready, you create a Workbooks Word Add‑in Template record in Workbooks to link them together.

System Admins will be able to go from Start > Configuration > Templates > New Template.

Template Categories: Selecting a Template Category means that this can only appear on Form Layouts with the same template category – leaving this blank means that it will appear on all form layouts.

The Word Add-In can use data from multiple Reports.  This is achieved by adding syntax to your template in Word, before adding the template to Workbooks. This is to specify the new Report you are using, as well as the View and Id column used within that report. Before the table you want to populate in Word, type the following, amending the text in bold to match your report:

<repeat_table data_view=’Report Name:View Name‘ id_column=’Record Id‘>

The process is the same when using a different summary view on the same report as in the template setup, the Report Name, View and Record Id must be filled in.

For example, I have a report called ‘Word Add-in Test – Employees’. I am using the ‘Details’ view and my template is on Organisation Records, so I am using the ‘Organisation Id’ as the id column.

Therefore, the table in my Word Template will look like this:

With the syntax

<repeat_table data_view=’Word Add-in Test – Employees:details’ id_column=’Organisation Id’>

above the table, and

</repeat_table>

below the table.