Document Templates

Publish the details of your records in any App with a delightful, customer-facing PDF document. You can also choose the style and format that best suits you and your company by designing your template in Microsoft Word or Google Docs. Publishing PDFs is a great tool for generating Quotes or Proposals via FreeAgent!

User Permissions: Only Administrators and App Admins can use this feature.

In this tutorial, we will cover the following topics:

1. Docmosis Documentation
2. Create your PDF Template
   • Special Formats
   • Pro-Tip for Images
3. Upload Template to App
4. Configure Custom Code
5. Create Your Document
6. Samples
7. Troubleshooting

Note: If you haven't used Docmosis before we would highly recommend reviewing the guild as well as this article. Cloud (DWS3) - Template Guide

Create your Template

First, we recommend that you either use Microsoft Word or LibreOffice Writer to create your desired document with all the styles and elements that you would like to have. It could be a quote, an invoice, or even a project proposal. Once you have something like the samples shown in the image below, it is time to prepare the template. 

To create the template, you will be replacing the elements in your document with 'tags' (<<>>) that will point to an existing field within FreeAgent CRM. Let's go through the second sample image step by step.

Identify replaceable elements

Start by identifying those elements in your document that can and need to be replaced by the actual values from your record. In the first sample image, we have identified a few values which should be replaced with values within the FreeAgent record.

 
The top section includes your company's information as part of the header and doesn't change from quote to quote, so you can enter your company's consistent information (name, address, etc.). However, the Quote ID is a field in FreeAgent that changes from quote to quote so the system must replace it on the creation of a new quote. Use the following tag: <<id>> since the FreeAgent Field is called 'ID'. We do the same for all the other replaceable elements and we get:

The <<id>>, <<company>> and <<address>> tags that are seen here are all available as fields within the 'Quotes' App. Please note that the name of the App, as well as the available fields, will change according to your own FreeAgent CRM configuration.

When the field name is composed of two or more words, your tag will need to be capitalized as follows: twoOrMoreWords -> the first word of the field name is lowercase, while the rest of the words are capitalized, and there shouldn't be any spaces between words.

As for dates, they are available in the App as well, they just look slightly different from the other tags, as we are applying a specific format to them.

<<{dateFormat(yourDateFieldName,'MMM dd, yyyy')}>> will print the date in the following format
Apr 06, 2020

There are some special formats that you can apply to your fields according to their type. 

Let's review the second half of the template. Now we will add the information for the lines in our App. This section should be set up as a table to identify each of the elements in a row. All the elements inside the table, except the column name, will be replaced by values from the lines in the App. Therefore in the PDF template, the values have to become tags.

We just need one row for the items inside the table. We also need two additional rows to mark the beginning and the end of the lines within the table. The result would look something like this:

The column names are not replaced by tags. Then we have a row with <<rr_yourAppLine>> which tells the system that the information that goes after comes from a line and not the App itself. If your line name includes two or more words, remove the space between the words and capitalize the first letter of all of the words except the first one, which needs to be lowercase. <<er_yourAppLine>> marks the end of the line elements in your template.

To display quantities, amounts (currency), and other fields with the number type, please review the special formats section.

Once the template is ready save, export, or convert it to .docx as it is the only accepted format to import your template into FreeAgent CRM.

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.

Pro-Tip for Images

If you are looking to add a logo to your PDF template or any other image, we recommend that you follow the instructions described in the tutorial below to achieve the best results possible.

How to Achieve a Perfect Logo in your PDF Files

Upload Template to App

Open the menu and go to 'Admin Settings' to display the available options, then click App Setup.  From here navigate to your desired app.  Click on the new 'Document Templates' menu within the App menu.  In the top right-hand corner click on 'Add New Document Template.'

From here choose a template name and add your file.  Once ready click Save to add your new template.  You can add multiple templates in each App and edit them at any time.

Note: The only allowed type for the template is '.docx' 

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.

Create Your Document via App Action Button

Now there is a convenient App Action button to create and download your PDF or any of the formats you have set up.   Simply click and your download begins automatically based on your generation preferences. 

You've just created a gorgeous document that includes all of the relevant data you want to present in a simple, beautiful way.  

Samples

If you want to see some examples, click on the template you would like to download. You can use these to get an idea of how they work by modifying the values inside the <<>> for the name of your fields. It is important that you remove those that don't apply to your configuration, as it will prevent the PDF file from being exported correctly. 

Template for a simple quote
Template for a travel quotation

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!