¶ DOCX Templates
The "Maven Documents Template Builder" add-in for DOCX files is a powerful tool that helps you build a template document with data from Salesforce.
¶ Install Template Builder
You can use the add-in in both the online and offline Microsoft Word versions. But here is the difference in installation.
¶ Offline version
Follow the next steps to install Maven Documents Template Builder on the offline version of Microsoft Word.
-
Go to appsource.microsoft.com/en-us/product/office/WA200004491 and click Get it now
-
After the installation is complete, click Open in Word
-
When Microsoft Word opens, you'll see the standard Microsoft page with quick instructions on launching the new add-in. Click on Trust this add-in button
-
You'll see the message that Template Builder is successfully loaded and the logo of the add-in appeared in Word taskbar
That's it! Now you have Maven Documents Template Builder installed!
¶ Online version
Follow the next steps to install Maven Documents Template Builder on the online version of Microsoft Word.
-
Go to Office.com and log into your Microsoft account
-
Create a new Word document or open an existing one
-
Select "Insert" tab in the Word taskbar and click on Add-ins
-
Click on Office store button and search for Maven Documents Template Builder
-
Select Template Builder add-in and you'll be redirected to the add-in's page. There you can find some useful links and information. Then click the Add button
-
Read and if you agree with the terms and conditions, check the respective box. Click Continue
-
You'll see Welcome message with some useful links. Click Let's go
Voilà! Maven Documents Template Builder add-in now could be used on the online DOCX file.
¶ Run the Template Builder Add-in
The first thing that you should do before building the template is to run Template Builder add-in on your DOCX file and log into the Salesforce account.
Follow the steps to run Template Builder add-in on the offline DOCX file:
-
Run Microsoft Word and create a new or open an already existing document.
-
In Home tab click on Maven Documents button on the right side of the Toolbar
-
You'll see Welcome message with some useful links. Click Let's go
Note: Welcome message appears for every new document and every first use of the add-in on the existing document. Once you've been working with Template Builder in the document, Welcome message will be skipped.
-
After Template Builder task pane appears click on Login to Salesforce button that looks like a gear
-
A new dialogue window should open, offering two login options. Select where you want to log in. We recommend you log in to Sandbox first to see if everything is working fine.
-
In the next dialogue window put in your credentials and click Log in
Note: If this is your first time logging into the Salesforce account with Template Builder, the verification of a user is required from the Salesforce side. You'll receive an email with the verification code which you should enter in the required field.
-
Click Allow
-
In the last dialogue window select the Document Solution, you would like to use
-
After you select the solution you can select Document Template to which you will upload the document
-
If you like to upload the file you are working on to the selected template, check the question box. Otherwise, leave it blank. You could upload the file later with Template Builder.
-
Click Done
Note: Notice, that under Solution/Template Select you'll see the information to which org you've connected Template Builder.
Once you finish the log-in process, you'll find the query, built with Query Builder, on Template Builder work pane.
As the taskbars in online and offline versions of Microsoft Word are a little bit different, the first steps to run the add-in on the online version will be the next:
- Go to Office.com and log into your Microsoft account
- Create a new DOCX file or open an already existing one.
- In Home tab click More options button, it looks like three dots.
- In Commands Group section select Maven Documents add-in
Template Builder work pane will appear on the DOCX file. You can follow the steps from the instructions on the offline version to log into the Salesforce account.
¶ Meet the Template Builder
Once you are done with the login process, you can finally use Template Builder.
Before you start, let's have a glance at what we call Template Builder work pane. Let's divide it into two parts: the work part and the administration part.
¶ The work part includes:
-
{} Fields section. Here you will find the objects and the fields you added to the query in the Document Solution. All objects and fields can be inserted into the document with one click.
-
</> Elements section. Here you have a picklist with the elements that could be inserted and used in the document. For detailed information on every element, you can check DOCX Elements Reference page.
-
fx or the Expression Builder section. Expression Builder lets you create expressions (similar to formula fields in Salesforce) without needing a formula field directly on your document. You can read more about expressions and their syntax on the "Expressions" page.
The icon in the bottom left of the expressions input field opens Expression Builder
First of all, you can see all available functions in Select function menu. The first dropdown menu filters functions by categories (date, number, string, etc.), and the second dropdown menu contains (filtered) functions you can use.
You can also insert your Salesforce fields into expressions by using the dropdown in Insert field menu (an arrow (>) next to a field suggests that it's a relationship field - e.g. Account > Contact > ...).
After the function and fields are inserted, they appear in Text field below. So you can edit the expression manually or use the expression builder again.
Note: Before inserting the function or a field, verify that you've selected the text you want to replace in the text field below
¶ The administration part includes:
- Refresh Nodes button. This button serves two purposes:
- Reflect changes made on the Salesforce side. For example, you've changed the name of an object or edited the query in Query Builder tab of Maven Documents. After clicking Refresh, you will see the changes in Template Builder.
- The second purpose is to refresh the context inside the document to see fields from sub-queries. For example, if the cursor is placed inside a repeater or table, which iterates through a record, its name and included fields will also appear in the list fields on Template Builder after refreshing.
- Login to Salesforce button. You are already familiar with this one. It helps to connect the Salesforce org with Template Builder and select what Document Solution and Document Template to use.
- Upload File to Template button. Click on this button to upload the DOCX file you are working on to the Document Template, that you selected in Login to Salesforce step.
Note: After changes are made in the DOCX file you need to upload it to the Document Template. Because once the file is uploaded to Salesforce it doesn't refresh automatically. And if you want to have the up-to-date version, you need to upload it after changes are made.
¶ Build Templates using Template Builder for DOCX files
Now, that you know how to install and run the Template Builder add-in on the DOCX file, it is time to create and modify the template document using all the "Template Builder" abilities.
Let’s see how we create Sales Quote document. You can use the created Document Solution from the Maven Documents gallery as a reference.
¶ Adding fields and expressions
Write down the header of the document and place the cursor under it, so you can insert the fields there.
Remember, that first of all, you need to log in to Salesforce to have the up-to-date query in Template Builder.
- In the header of the first page, you can place some information about the organization, for example, the name and address. You can select all these fields from Template Builder.
- First, we use Name field from Opportunity object to show from which opportunity you will take the data. Select {}Fields tab and click on Opportunity object. In the dropdown list of fields, click on {} Name field. So below the header of the document, you will have the following merge field {!Opportunity. Name}.
- Then use Name and Billing Address fields from Account object to indicate who will use the quote. Also, insert CreatedDate field directly from Opportunity to show when the quote was prepared.
- After you have the prepared date in the document, you need to have the expiration date in your quote. For example, it expires 30 days after the quote (document) has been generated. So let’s use some magic to do that. And by magic, we mean Expressions.
-
Select fx tab on Template Builder work pane. As you remember, this one stands for Expression Builder
-
Open Expression Builder by clicking on the icon in the bottom left of the expressions input field
-
In Select function section select Format function type and format date function. Click Insert. That function makes the date look in the "dd/mm/yyyy" format
-
Highlight the DateField in the text field below and select Date function type and addDays function in Select function section. Click Insert
-
Now you need to replace DateTime in the expression with the current date, which will also be a function. From Select function menu, choose Date function type and now() function
-
Highlight DateTime in the text field below and click Insert. This action will replace DateTime with now() function
-
Replace NumberOfDays with 30
-
The last thing to do is to change Format to short
The result should look something like this.
-
Click Insert Expression and then Insert Expression one more time.
All the fields we've put using {!QueryName.FieldName} notation will be dynamic, meaning they will depend on the results that our queries returned.
¶ Inserting elements
The next step you need to do is to show the information about our Opportunity's products. If you remember, in Query Builder article, you added OpportunityLineItems as a sub-query. For the sub-query to be available in Template Builder, you need to be in a specific context. Sub-queries can only be accessed from inside of an element that belongs to its parent query, for example, Repeater or Table" element. And this is where Elements part kicks in.
Note: Elements are the building blocks of every document and sheet. They allow Maven Documents users to turn a simple textual document into a rich, content-filled document that can satisfy the needs of a whole range of users. Elements are written in HTML-like code directly on the document template. More information on what are Elements and how to write them can be found here.
You will use Table element to show the information about the products. Table iterates through records selected in Value attribute, and for every record in the iteration, the table row is repeated. Variable attribute represents the current record in the iteration.
- Place your cursor where you want your products to be shown. Then, in Template Builder open Elements tab.
- In Element Type field select Table element
- Fill Attribute fields with the following values:
Name: line-items
Value: Opportunity.OpportunityLineItems
Variable: oli
Repeating row: 1
Rows: 3
Columns: 4 - Leave Hidden attribute unselected and click Insert Element.
Have a look at the screenshot.
Now, when the table has been inserted, you need to modify a few things.
Each column in the table is used for one field from the product. The first row (row 0) will be the header row and will be filled with the field names. In the bottom row (row 2) you will put Total Opportunity Amount, by adding the field from Template Builder.
Now, all you need to do is to fill out the repeating row (row 1) with field values.
- Place your cursor inside any cell of the table and click the refresh button to get the fields from the "oli" variable in Template Builder
- Insert the fields into their corresponding cells in the middle row
- Make some cosmetic changes, like changing the color of the rows and making the font bolder.
The table should look like this.
With the table inserted, you have the first page completed.
¶ Continuing the modification with known tools
On the second page of the template, you will be adding some additional content related to the terms and conditions. With the Microsoft Word editor, you can edit the content. And using Template Builder's features, you will add a few placeholders to dynamically populate the account name and delivery period, for example.
The third page of the template Sales Quote document stands for Payment Details.
Again, the combination of the Microsoft Word edit features alongside the Template Builder abilities helps you create the required template with all the data you need.
The last page will contain the contact details of a sales agent and a customer.
Add the sales agent's contact details by using the respective fields from Template Builder. To insert the customer contacts you can use the already-known table element:
- Place your cursor where you want the information to be shown. Then, in Template Builder open Elements tab
- In Element Type field select Table element
- Fill the attribute fields with the following values:
Name: contacts
Value: Opportunity.OpportunityContactRoles
Variable: con
Repeating row: 1
Rows: 2
Columns: 4 - Leave Hidden attribute unselected and click Insert Element
When the table is inserted, fill its cells with the needed data.
- As in the previous example, the first row will be the header row. So, populate its cells with the names of the fields.
- Put the cursor in the second row and refresh the query. With that move, you'll have the fields from the sub-query appear in Template Builder
- Insert the needed fields inside the respective cells of the table
In the screenshot below you can see what you could have as a result.
Here it is! That is how you can create any Document Template in Microsoft Word.
¶ Use parts of another document with the Include element
Imagine the situation, when some other documents already have the table or another element that you can use in the template. You can easily have this building block in your document by inserting it from another file. There's no need to replicate it from scratch: the Include element will do the magic for you.
Before using the element, make sure that you have additional DOCX-type Document Templates connected to the Document Solution you use. Or there is a DOCX file uploaded to Salesforce.
-
Select Include Element from the list in Template Builder
-
Name the element and select needed Source Type:
- Document Template. This Source Type allows you to select the needed element from the file uploaded to the selected Document Template or insert the whole content of that file
- Salesforce File. This Source Type allows you to define the needed DOCX file by its Content Version ID or Title.
-
Let's say you go for Document Template Source Type
-
After Source Type is selected, choose the template from the picklist in Source field
-
As you noticed, Element Name field appears after the template is selected
-
Pick the needed element and Insert it into the document
In the screenshot below you can see what the element's body looks like.
-
If your choice is Salesforce File, you can use a merge field that holds the necessary ID or Title of the preliminary uploaded to the Salesforce DOCX file or you can switch the toggle next to Source field and enter the data manually in Expression Builder textbox.
-
For the merge field option, after choosing Salesforce File Source Type, select the needed field in Source attribute
-
After you insert the element, it is going to look like in the screenshot below
-
If you want to insert the ID or Title manually, switch the toggle next to Source attribute and place the needed identifier of the uploaded DOCX file in Expression Builder text box.
For example, you can find the Content Version ID if you do the following:- Go to the uploaded file on Salesforce and open it
- Click Show More icon above the file and select View File Detail option
- In the address bar of the opened tab, copy the ID. The ID is located between ContentDocument/ and /view in the address bar
-
After you insert the element with the manually added ID, you need to remove the curly brackets, the exclamation point, and the dollar sign that wraps up that ID.
When using the file's Title, make sure that this Title is unique so Template Builder fetches the corresponding file or the generation process doesn't end in an error.
Once you generate the template, it will include the selected element or the whole content of the file you've chosen.
¶ Upload the DOCX File to the Document Template
Now, when you have the document ready, you can easily upload it to the Document Template that you chose during Login process.
All you need to do is to click on Upload File to Template button, on Template Builder work pane. Once you have done it, you'll see the message that the file has been successfully uploaded.
Now, if you go to Salesforce and select Document Template tab, and click on the respective Document Template in Maven Documents app, in Files section you will find the document.
Once the template document gets Template ID, you can generate the file.
Note: Be aware that Template Document ID will usually appear a couple of seconds after the file has been uploaded. If the ID doesn’t appear in a maximum of two minutes - try uploading the same file one more time.
The waiting time solely depends on the load that Salesforce is dealing with upload time.
If you want to add a new file to Document Template, you can use Add Files button or Upload New Version option. Maven Documents will use the latest file version that is uploaded. To keep things clean, it is good practice to have one file per Document Template uploaded. But if you have a couple of files attached to the template, the latest added file will be generated.
Note: If you built your template in the Online version of Microsoft Word or Autosave mode is available on the Offline version, the name of the generated document will include a URL with the path to the template.
¶ Debug Document with Playground
If you want to see what the actual data will be available on your Document Template, feel free to use Playground tab. It can also serve as a means to debug the flow when things aren't going as they should be.
Try changing the Locale definition in your settings, for example, and see how data changes. Magic isn't it?