¶ 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 online and offline Microsoft Word versions. But here is the difference in installation.
¶ Online version
Follow the next steps to install Maven Documents Template Builder on the online version of Microsoft Word.
-
Go to Office.com or Microsoft OneDrive and log into your Microsoft account.
-
Create a new Word document or open an existing one.
-
In the Home tab on the Word taskbar and click on the Add-ins icon.
-
In the dropdown menu click the +More Add-ins button.
-
It opens the Office store. Search for Maven Documents Template Builder there.
-
Select the 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 the Welcome message with some useful links. Click Let's go.
Voilà! The Maven Documents Template Builder add-in can now be used on the online DOCX file.
¶ 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 the Trust this add-in button.
-
You'll see the message that Template Builder is successfully loaded and the logo of the add-in appears in the Word taskbar.
That's it! Now you have Maven Documents Template Builder installed!
¶ Sandbox Version
To test Maven Documents features in Sandbox Orgs, we developed a separate Template Builder add-in.
You can install the add-in by following the steps we provided above for the Online and Offline versions. You only need to select the Maven Documents Template Builder (sandbox) add-in.
¶ Run the Template Builder Add-in
The first thing that you should do before building the template is to run the Template Builder add-in on your DOCX file and log into the Salesforce account.
Follow the steps to run the Template Builder add-in on the online DOCX file:
-
Go to Office.com or Microsoft OneDrive and log into your Microsoft account.
-
Create a new DOCX file or open an already existing one.
-
In the "Home" tab click on the "Add-ins" button.
-
Select the "Maven Documents" add-in.
-
You'll see the Welcome message with some useful links. Click Let's go
The 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, the Welcome message will be skipped.
-
After the Template Builder task pane appears click on the 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, user verification 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'd 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 the 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 offline version will be the following:
-
Run the desktop Microsoft Word application and create a new or open an already existing document.
-
In the Home tab click on the Maven Documents button on the right side of the Toolbar.
-
You'll see the Welcome message with some useful links. Click Let's go.
The Template Builder work pane will appear on the DOCX file. You can follow the steps from the instructions on the online 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 the Template Builder work pane. Let's divide it into two parts: the work part and the administration part.
¶ The work part includes:
-
The {} Fields tab. 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.
-
The </> Elements tab. 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 the DOCX Elements Reference page.
-
The fx or the Expression Builder tab. 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 the 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 the 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 the 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:
- The 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 the 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.
- The 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.
- The 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 the 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. 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 have a look at how we create a 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 the Name field from the Opportunity object to show from which Opportunity you will take the data. Select the {}Fields tab and click on the Opportunity object. In the dropdown list of fields, click on the {} Name field. So below the header of the document, you will have the following merge field: {!Opportunity. Name}.
- Then use the Name and Billing Address fields from the Account object to indicate who will use the quote. Also, insert the 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. By magic, we mean Expressions.
-
Select the fx tab on the 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 the Select function section select the Format function type and the 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 the Date function type and the addDays function in the 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 the Select function menu, choose the Date function type and the now() function.
-
Highlight DateTime in the text field below and click Insert. This action will replace DateTime with the 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 the {!QueryName.FieldName} notation will be dynamic, meaning they will depend on the results that our queries returned.
¶ Inserting elements
The next step is to show information about our Opportunity's products. If you remember, in the 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 the inside of an element that belongs to its parent query, for example, the Repeater or Table element. This is where the Elements part kicks in.
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 the HTML-like code directly on the document template. More information about Elements and how to write them can be found here.
You will use the Table element to show the information about the products. The Table iterates through records selected in the Value attribute, and for every record in the iteration, the table row is repeated. The 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 the Elements tab.
- In the Element Type field select the Table element.
- Fill in the Attribute fields with the following values:
Name: line-items
Value: Opportunity.OpportunityLineItems
Variable: oli
Repeating row: 1
Rows: 3
Columns: 4 - Leave the 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 the 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 the 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 your first page.
¶ 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. 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 the Elements tab.
- In the Element Type field select the Table element.
- Fill in the attribute fields with the following values:
Name: contacts
Value: Opportunity.OpportunityContactRoles
Variable: con
Repeating row: 1
Rows: 2
Columns: 4 - Leave the 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 Document Templates connected to the Document Solution you use. Or there is a DOCX file uploaded to Salesforce.
-
Select the Include Element from the list in Template Builder.
-
Name the element and select the 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.
Due to Microsoft limitations on online DOCX files, you currently can't select a specific element from the needed Document Template. Once you choose the template in the Source field, you get a warning message.
However, if you close the message and insert the Include element into your document, you will include the whole content of the selected Document Template. If needed, you can manually add the needed element from the Document Template by putting theelementName="The Name of the needed element"attribute into the body of the inserted Include element.- 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 the Document Template Source Type.
-
After the Source Type is selected, choose the template from the picklist in the Source field.
-
As you noticed, the 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 the Source field and enter the data manually in the Expression Builder textbox.
-
For the merge field option, after choosing the Salesforce File Source Type, select the needed field in the 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 the Source attribute and place the needed identifier of the uploaded DOCX file in the 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 the Show More icon above the file and select the 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 includes 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 the Login process.
All you need to do is click on the Upload File to Template button, on the 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 the Document Template tab in Maven Documents, on the respective Document Template, in the Files section, you will find the document.
The way the uploaded file is displayed in the corresponding Document Template is different for online and offline versions of the file.
- If you are uploading the online DOCX file, the Document Template Id field is populated with the file's URL. The Document Title field is automatically populated with the title of the uploaded file
- If you are uploading the offline DOCX file, the Document Template Id field is populated with the ID of the uploaded file. The uploaded file appears in the Files section of the Document Template.
Once the Document Template Id field is populated, you can generate the file.
Be aware that the Template Document Id will usually appear a couple of seconds after the file has been uploaded. If the ID doesn’t appear in 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 the Document Template, you can use the Add Files button or the Upload New Version option. Maven Documents uses the latest version of the uploaded file. 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 the Autosave mode is available in the Offline version, the name of the generated document will include a URL with the path to the template.
¶ Protect parts of the document
One of the native Microsoft Word functionalities is the ability to protect some parts of the document from editing. You can follow the link to see the instruction on how to to that.
We are mentioning that because you can use this feature on templates built with the help of Template Builder. Even if you decide to protect parts that have merge fields, elements, or expressions, be sure, they are going to be processed and generated. In the generated document, parts that are marked as protected stay protected, including those Maven Documents elements inside.
Select the necessary parts carefully. For example, if you want the content of the Repeater to be protected, the whole "body" of the element with opening and closing tags should be in the restricted part.
There are still some limitations from the Microsoft side though. For example, you can set partial protection only using the desktop version of Microsoft Word. The online version doesn't have such a functionality. You would only open restricted documents online and see the restricted parts, but to make edits, Word will force you to use the desktop version.
It is important to know when you are using Maven Documents. You can generate the document with the restricted parts and save it as a file on OneDrive, but it will be in the View mode. You can try and click Edit Document.
But the end result is a message telling you to use the desktop Word version or continue with the View mode.
¶ Debug Document with Playground
If you want to see what the actual data will be available on your Document Template, feel free to use the 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?