Creating Word Add-in Templates

There are three key parts to setting up and creating Word templates with Workbooks:

1. Word Template, which should be designed in MS Word
   1. This could be a templated letter with placeholders for names and addresses, or it could be an Invoice document with a Line Item table and with placeholders for the Payment Date, Payment Terms and other Invoice details.
2. The data source, which is determined using Workbooks reports. This can be based on a Workbooks template report or you can create a new report
   1. The Workbooks reports must include all the fields that will be used within your Word Template and be accessible to any user using the template(s) linked to the report.
3. Linking the Word template and data from the report, which is done by creating a template in Workbooks

1. Designing the Word Template

To get you started, we have created some example templates, which can be found here.

You should start out by building out the layout of your document – we recommend using tables to create the structure.

Then add in your text – your Word template will consist a combination of fixed text, like field labels or column headers, and data that will be pulled from Workbooks, like customer details or invoice amounts. In place of where you want data to be pulled in from Workbooks, you will need to add in placeholders. 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:

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].

HTML / Rich Text Placeholders

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]

Line Item Tables / Iterating Tables

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.

The second row should contain the placeholders; for example, if building a Line Item table, it might look like the following:

When this Template is generated from Workbooks, the second row will then be repeated as many times as there are line items to produce the following:

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

Creating the Workbooks Report

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.

Creating the Template within Workbooks

Once you have created the Report and the Word Template Document you are ready to bring the two together within Workbooks.

To do this you will first need to go to either

Start > Marketing > Templates > New Template,

alternatively System Admins will be able to go from

Start > Configuration > Templates > New Template.

From either option select A Word template.

Next select the record type you want the Word template to use.

This will open a new window where you will need to provide additional details to configure the Template:

Name: The name of the Word Template as it will appear to users.
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.
Document Template: The word document file that you have configured – remember this must a be a .docx file
Report: The name of the Report used with your template
View: The name of the view that contains all the columns used within your template
Document Id Column: The name of the column that specifies the Record’s Id

Filename Column: This will allow you to select a column in the Report that the add-in will use to name the document. In the example below, this column is an Organisation Name (as the Report is based on an Organisation) so the word document will be have the same title as the Organisation Name. If left blank, the Word Document generated will be titled with an Object Reference (eg.- ORG-117.)

When the fields have been configured be sure to set up the Sharing Permissions for the Template using the sharing padlock at the top of the page. Typically, we’d recommend giving Read access to the relevant users and only those users that have the Template shared with them will be able to access it on the Record.

Once you have set this up, select the Activate button at the top of the Template.

Now when you open a Record of that type you will see a Generate Word button along the toolbar next to the Generate PDF button, here you will be able to select any available Word Document.

Creating a Template Using Multiple Reports or Summary Views

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.