¶ DOCX Templates
The Maven Documents Template Builder add-in for DOCX files is a powerful tool that helps you build a template document using 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, 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 desktop 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's 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 Template Builder
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.
¶ Online DOCX
-
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 start working with Template Builder in the document, the message is 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:
- Log in to Production
- Log in to Sandbox
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 provide your credentials and click Log in.
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 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 right away, check the question box. Otherwise, leave it blank.
You can upload the file later with Template Builder. -
Click Done.
Under the "Solution/Template Select" title, you'll find the information to which org you've connected Template Builder.
Once you finish the log-in process, you'll see that template Builder reflects the query from the connected Document Solution.
¶ Offline DOCX
-
Run the desktop "Microsoft Word" application and create a new document or open an already existing one.
-
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 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 on 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 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.
Before inserting the function or a field, verify that you've highlighted the text you want to replace in the text field below
¶ The "administration" part includes:
-
The "Refresh Nodes" button.
This button serves two purposes:- To reflect changes made on the Salesforce side. For example, you've changed the name of an object or edited the query in Query Builder. 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 Document Template, that you selected in the Login to Salesforce step.After changes are made in the DOCX file you need to upload it to 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
Now, that you know how to install and run Template Builder, it is time to create and modify the template document using all of 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 Template Gallery as a reference.
¶ Adding fields and expressions
Write down the header of the document and place the cursor below so you can insert the fields there.
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. 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. From the Select function menu, choose the "Date" function type and the "now()" function. This function reflects the current date and time.
-
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 are dynamic. It means they 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 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.
Table iterates through records selected in the "Value" parameter, and for every record in the iteration, the table row is repeated. The "Variable" parameter 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 fields with the following values:
Name: line-items
Value: Opportunity.OpportunityLineItems
Variable: oli
Repeating row: 1
Rows: 3
Columns: 4 - Leave the "Hidden" parameter untouched and click Insert Element.
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) put the total opportunity amount by adding the respective field from Template Builder.
Now, all you need to do is to fill in the repeating row (row 1) with field values.
- Place the cursor inside any cell of the table and click the "Refresh" button to get values 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 add some additional content related to the terms and conditions. Using Template Builder's features, add a few placeholders to dynamically populate the account's name and delivery period, for example.
The third page of the "Sales Quote" document stands for payment details.
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 selectTable.
- Fill in the fields with the following values:
Name: contacts
Value: Opportunity.OpportunityContactRoles
Variable: con
Repeating row: 1
Rows: 2
Columns: 4 - Leave the "Hidden" parameter as it is 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.
¶ Using 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 Document Solution you use or that 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 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.
- Document Template.
-
Let's say you go for the "Document Template" Source Type.
-
After 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 have the following options:
- Use a merge field that holds the necessary ID or the title of the preliminary uploaded to the Salesforce DOCX file.
- 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 braces, 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.
¶ Uploading the DOCX File to Document Template
Now, when you have the document ready, you can easily upload it to 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 Document Template.
Once the "Document Template Id" field is populated, you can generate the file.
The Template Document Id appears a couple of seconds after the file was 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.
¶ 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.
You can generate the document with the restricted parts and save it as a file on OneDrive, but it opens in the "View" mode. You can try and click "Edit Document".
But the 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?