Create an MS Word Document Template

An MS Word document can be used as a document template. To do so, it is only necessary to insert record variables into a standard MS Word document.

Learn More:

• Document Templates
• Accessing Related Records

Creating the Template File

1. On your local system, create a Word document
2. Add boilerplate text and placeholder images.
3. Add place-holder images for any record images or charts you plan to add. Size them appropriately.
4. Insert template variables, record-specific images, and/or charts, as explained below.
5. Save it in .docx format.

Note: The .docx file is stored in an XML format the platform can work with. A .doc file is in a binary (numeric) format that won't work. The AgileApps document template feature does not support the documents generated through Microsoft Cloud (www.office.com). The access to the file should be unrestricted. A file type conversion could lead to an error when sending the email.

Working with Template Variables

Inserting Template Variables

To insert a template variable:

1. Begin to Add a Document Template or [Edit] an existing template.
   The Template Variable Tool appears.

   

2. Select the Category of fields to choose from.
   (Fields in the current object or Related Objects, User fields, or Company fields)
3. Under Fields, scroll down the list to find fields in the current record or in a Lookup target record.
4. Select the field to add.
   The variable name appears.
5. Copy the variable name to the clipboard.

6. In the template file, create a field:
   • Press Ctrl+F9, right click on the field, and select "Edit Field..."
   • Or click Insert > Quick Parts > Field

   The Field dialog opens.

7. Select the field type:
   • Categories: Mail Merge
   • Field names: MergeField

Note: The RTA field type is not supported in document templates of type .docx/.ppt. If you use RTA field type, then when you print the document template, Rich Text Area field is printed with HTML tags.

8. Under Field Properties, specify:

• Field name: Paste the variable name you copied in Step #5.

9. Click [OK]

Testing Boolean Values

Boolean values are seen in Velocity as strings with the value "Yes" or "No". So a test of a boolean field looks something like this:

#if ($BooleanField == "Yes"), or

#if ($BooleanField == "No")

Or, similarly,

#if ($BooleanField != "Yes"

#if ($BooleanField != "No")

Convert Currency Variables to Numbers

When you want to do calculations on a currency field in Velocity, you need to create a number from the currency strings delivered by the platform. That string has the form $24.95. The following code converts it to a number that can be used in calculations:

<syntaxhighlight lang="html4strict" enclose="div">

1. set($n = 0.00)
2. set($s = $YourObject.currency_field.substring(2) )
3. set($n = $n.parseDouble($s)

</syntaxhighlight> where:

• $n = 0.00 creates an instance of the double-precision float class (Double)
• $YourObject.currency_field.substring(2) removes the first two characters from the currency string. (The $ sign and the space that follows it.)
• parseDouble($s) converts the resulting string into a double-precision float--a number that can be used in calculations.

Inserting an Image Stored in an Object Record

To insert an image:

1. Select a placeholder image to replace.
2. Right click on the image. Choose Size...
3. Click the Alt Text tab
4. In the Alternative Text area, type in a platform IMG tag

IMG Tag

IMG{$objectName.imageFieldName}

where:

• objectName - The name of the current object. (This variable is in Velocity format. The object name effectively creates a namespace, ensuring that there is no conflict with another variable that might have the same name.)
• imageFieldName - The name of the field in the current record that contains the image to display, joined to the object name by a "dot" (.).

Important: This syntax uses braces: {...}. The braces and other underlined characters in this syntax are literals. Type them in exactly as shown.

Result

The URL for the image is inserted into the generated page. When viewed, the image is displayed.

Example

IMG{$Customer.logo_image}

Processing Related Records

Finding Related-Record Variables

Related Object variables are found using the Template Variable Tool.

Here, in the Email Template for Claims, the related ClaimItems object is being chosen from the category list:

Within that group, the Item Name field is listed, along with other fields in the ClaimITems object. Once selected, the variable name appears in the Variable area, along with the loop it needs to be surrounded by for processing:

#foreach( $ClaimItems_record in $ClaimItems ) $ClaimItems_record.item_name #end

If a loop already exists, you would use only the variable name part:

$ClaimItems_record.item_name

Note: For a many-to-many relationship like one between Claims and Tags, the variable looks like this: $Claims_Tags_record.related_to_Tags.tag_name where: $Claims_Tags is the Junction Object that produces the many-to-many relationship related_to_Tags is the name of the Lookup field in the Junction Object that references a Tags record tag_name is the field to display The "dot" separator (.) joins each of the segments in the variable name

Using Related-Record Variables

For HTML, you insert related records into a table by putting loop-controls around code that specifies the format for a row:

#foreach($i in $Order_Items)

     <tr>...row contents here...</tr>

#end

The problem in MS Office tables is that there is no place "outside the row" to put those loop controls.

The solution is to use two special constructs that go into the first cell of the row:

• @before-row#foreach($i in $Order_Items)
• @after-row#end

Considerations

• The constructs only need to be specified once in the row, in the first cell.
• Between them, include the field that will be displayed in the cell
• Like the fields, the loop construct are inserted into the cell as fields

• Insert > Quick Parts > Field, Category: Mail Merge, Field type: MergeField
• Or copy an existing field, right click, and select the Edit Field... option

• For other cells in the row, specify the field to include in that cell, without the extra constructs

Example

Cell 1:

«@before-row#foreach($i in $Order_Items)»
«$i.item»
«@after-row#end»

Cell 2:

«$i.quantity»

and so on...

The resulting table will look something like this (with line breaks included in the first cell to make it more readable):

Sample Template: OrderInvoiceWordTemplate.docx

Learn more: Solution: use @before-row @after-row