Document Templates (Docmosis)

You can automatically generate documents such as quotes or proposals right from within FreeAgent using Document Templates. You can personalize the format and style of these templates to fit your brand.  

User Permissions: Only Administrators and App Admins can create new Document Templates. 

This article covers the following topics:

1. Docmosis Documentation
2. Creating a DOCX template
3. DOCX Template Example: Sales Quote- Header
   - Placeholder Elements
   - Tags
   - Adding your Logo
4. DOCX Template Example: Sales Quote- Body
   - Pulling Information from a Line
5. Upload a DOCX Template to FreeAgent
6. Special Formats
7. Configure Custom Code for Document Generation
   
8. Troubleshooting 

FAQs

What is a Document Template?

A document template is a preformatted document used to generate various types of documents in FreeAgent such as quotes and orders. 

What is an App field?

An App field is a specific piece of information or data that is collected, stored, and managed in a FreeAgent App record.

What is a Line?

A line contains the details of individual products or services, including specific attributes related to those items such as price and quantity.

Can I use information from a line in a Document Template?

Yes. See Pulling Information from a Line.

Docmosis Documentation

If you haven't used Docmosis before, we would recommend reviewing the Docmosis Cloud Template Guide. Cloud (DWS3) - Template Guide

Creating a DOCX Template

The first step in creating a Document Template for FreeAgent is creating a DOCX version in Microsoft Word or LibreOffice Writer. This version should include all the style and brand elements you want in the Document Template as well as all the information you want the document to contain.

DOCX Template Example: Sales Quote- Header

Let’s take a look at an example. We will make a Sales Quote DOCX template, starting with the Header. 

As you can see, we have added our logo and address to the top left corner of the template Header. We have also chosen our preferred fonts and colors. 

On the right hand side we have named the template (Sales Quote) and designated a place to display the Sales Quote ID# and Issued Date.

Next, we need to identify our placeholder elements.

Placeholder Elements

While some of the information in a Document Template will remain consistent from document to document, most of the information will need to be updated based on the specific details of each individual document.

For example, in our Sales Quote template Header, the Koda Company logo , address elements, and the document name will all remain the same from quote to quote. 

The Sales Quote ID# and the Issued Date elements however, will need to be updated each time a new Sales Quote is created. Elements that need to be updated like this are called placeholder elements. 

Here we have outlined the placeholder elements in green.

Next, we need to replace those placeholder elements with Tags.

Tags

Tags designate an existing field within a FreeAgent App. Information from the designated field will be used to populate the placeholder element that contains the Tag. 

Tags are formatted as follows: <<fieldname>>. For example, a Tag for the Account field in the Quotes App would look like this: <<account>>. 

For fields that have multiple words, the first word is spelled out in lowercase letters and the next word begins with a capital. There are no spaces between the words. For example, a Tag for the Contact Name field in the Quotes App would look like this: <<contactName>>.

Here’s what our Sales Quote template example looks like with the Tags entered. You can see we replaced the placeholder elements we identified with Tags that correspond to the fields in our FreeAgent Quotes App that contain the information we want to populate those placeholder elements with.

Note: The name of available fields will vary based on your FreeAgent CRM configuration.

Adding your Logo 

If you need help adding your logo to the DOCX template (or any other image), see our tutorial, How to Achieve a Perfect Logo in your PDF Files.

DOCX Template Example: Sales Quote- Body

Let’s move onto the body of our Sales Quote template. First, when designing the body of a Document Template, it is best to create separate tables that contain similar types of information.

For example, all of the Account specific information for our Sales Quote template could be contained in a single table that includes the account name, address, primary contact, and the primary’s contact’s phone number and email. 

In this example we have included a “Prepared By” section as well. Deciding what information you want in a template, as well as how to organize it, is not a science and will require you to play around a little bit to find the right fit for you and your brand. 

Next, we identify our placeholder items and then replace them with Tags.

Pulling Information from a Line

If you need a Document Template to pull information from a Line, rather than a field, you can do so. 

First, we recommend each Line have its own table. This allows you to create rows in the table with commands that tell FreeAgent to pull the information from a Line in the App and not a field in the App. Those commands are:

1. <<rr_appLines>> This command tells FreeAgent that the information that comes after this row is to be pulled from a Line in an App, not a field. 
2. <<er_appLines>> This command tells FreeAgent to stop pulling information from that Line.

These rows act as a closed loop that allows you to select several elements from a Line to be displayed together. 

Note: Replace “app” in the command with the name of the App you are using for your Document Template. 

Let’s take a look at an example from our Sales Quote template.

As you can see, we have created a new table in our DOCX document for the Line. We started by creating a header row that indicates what information from the Line each column will hold (product info, List Price, Discount, etc.). 

Next, we created a row for our first command and replaced the word “app” with “quote” because we want to pull information from a Line in the Quotes App. The command now looks like this: <<rr_quoteLines>>.

After that we created a row for the placeholder elements in each column that we will replace with Tags and outlined those placeholder elements in green.

Lastly, we created a row for our second command (<<er_quoteLines>>). 

Now we can replace our placeholder elements with Tags.

Upload a DOCX Template to FreeAgent

From the Navigation Menu, go to Settings > Advanced > Document Templates and click the Add Document Template button.

This will pull up the Add Document Template window. From here you can name the template, select what App to associate the template with and upload the DOCX template file.

Special Formats

Dates/Time/Numbers

You can specify a different format in the bold section, to print your preferred date time.

Referencing Different Field Types

Some Field types in FreeAgent require different tags to produce results in your template.

Configure Custom Code for Document Generation

FreeAgent CRM supports document generation in the following formats: PDF, DOC, HTML, RTF, TXT, and ODT.  These formats are controlled by API parameters and will require some simple coding to set up generation within your App Action.  

To learn more about API, click here.  For more information on setting up App Actions, click here.  The following is a sample of the custom code required to configure your document generation preferences.  

(async function(record, context){
try{
const entity = await context.clientAPI.getEntityIdFromName({entity_name:'leads'}); 
const response = await context.clientAPI.getPdfByTemplate({
fa_entity_id: entity.data.getEntityIdFromName.fa_entity_id, 
instance_id: record.id, 
template_id: 'DOC100001',
output_format: 'pdf',
show_activity: true,
output_file_name: 'Output File Name'
})
if (response.error) {
await context.clientAPI.showErrorMessage(response.error);
} else {
const url = response.data.getPdfByTemplate.attachment_url; 
window.open(url, '_blank');
await context.clientAPI.showSuccessMessage("Generate Document Successfully!"); 
}
} catch(e){
await context.clientAPI.showErrorMessage(e);
}
}(record, context));

Refer to the below table to customize the code to your desired result.  There are five parameters you will need to configure manually.

Troubleshooting

If you have followed this tutorial but nothing happens when you click on the PDF icon to download, then most likely there is something missing in your template. Some of the most common mistakes are:

1. The file is missing some characters, it could be an initial < or a closing > or other characters like apostrophes (' or ') or curly brackets ({ or }).
2. There is a tag <<field>> that either doesn't exist in your App or in the lines of your App or is not following the naming convention fieldName.

If you have reviewed your template but are still having issues downloading your PDF, email the template to support@freeagentsoftware.com or share it through the Support Chat!