Please watch the below video, or read on, for how to set up and use the Word Add-in within Workbooks.

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

1. Word Template, which should be designed in MS Word
   • This could be a templated letter with one or two 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 a Workbooks report. This can be based on a Workbooks template report or you can create a new report 
   • The Workbooks report 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
   • This will bind the report created in Workbooks and the Word Template together, which allows the Word Document to be generated from the specific record 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, 100x200]. 

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 one table that iterates 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. 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: 

Binding your Template

Once you have created your Template design you will need to bind the template, this is only possible once the Word Add-in has been setup and deployed. 

Before binding the template click ‘Login to Workbooks’, which will open a dialog box where you can log into Workbooks using your usual credentials and select the database you want to login to.

Once you are logged in your username and database will appear above the Bind Template button.

Now you can bind the template through the bind template button. You should now see a success message appear in the Add-in. 

Additionally, if you hover over a placeholder you will see a Word content control tag associated with them such as below:

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

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.