Overview

The Smart Document Word Add-in is available for all licensed users of Microsoft Word (see supported versions in our Technical Requirements page under the Software Dependencies section). Installation is performed through the Office Add-in Store. It helps you create and administrate your document templates using dynamic content placeholders (tags) that will then be populated with real data later on, upon document generation. Let's start with the definition of helpful concepts when trying to implement Smart Document.

Template

A Template is a document with a docx extension created in Word with the Smart Document Word add-in tool. A Template has a Data Source Model defined by the User. A Template contains Tags placed in the Word document body. The maximum number of pages in a Template is 100. The maximum number of tags in a Template is 500. The maximum number of hierarchical depth in iteration is 5. The maximum sub-template depth is 5. Please refer to the Governor Limits page for the full list.

Sub-template

A Sub-template is a document created in Word with the Smart Document Word add-in tool. It is referenced in another template (Master Template).

Generated Document

A Generated Document is a Word document generated by the Generation Server based on a defined template. The maximum number of pages of a Generated Document is 1,500.

Data Source Model

The Data Source Model is defined for a Template and stored in the meta-data of the Word document. Users don’t need to set the Data Source Model again when they open an already existing document. The User can replace a Data Source Model of a Template. The Data Source Model must be a valid JSON file. The Data Source Model must contain all these definitions:

• Column definitions
• Field definitions
• Row template definitions
• View definitions
  • Component definitions

The data type of column and field definitions are limited to:

• Percentage
• String
• Integer
• Business
• Monetary
• XML
• JSON
• Error
• Long
• Currency
• Boolean
• Local_Date
• Datetime
• BigDecimal
• Unit_Of_Mesure
• Locale
• URL
• HTML
• Scale Price
• Attachment (used for 2D drawings)

Every data type has a unique and specific display.

Tags

The Template creation is based on tags. A Tag has two related parts:

• A visible one in the text of the document
• A hidden one in the meta-data of the document

The user must not alter the visible part of a tag directly inside the Word document at risk of breaking the consistency of the two parts of the tag.

A tag is a concatenation of text:

• “#”: Tag always starts with hash
• Type: The type of the tag (Field, Table, Section…)
• “_”: An underscore
• Id: The unique id of the tag
• “_”: An underscore
• Name: The name of the tag, free text (alphanumeric). It can’t be empty and must not contain spaces.

Sample of tags:

• #Field_34_CustomerName
• #Col_27_ProductName
• #BeginSection_18_Hosting
• #EndSection_18_Hosting

There are two placements for tags:

• Inline: Can be placed anywhere in a paragraph.
• Block: Must match a paragraph.

List of all single tags (Functional usage described later in other help topics):

• Field: Inline tag
• Image: Block tag
• Sub-template: Block tag
• Column (Col): inline tag, must be placed in a table or inside an iteration
• BeginSection: Block tag, always related to an EndSection tag
• EndSection: Block tag, always placed after the related BeginSection tag
• BeginIteration: Block tag, always related to an EndIteration tag
• EndIteration: Block tag, always placed after the related BeginIteration tag
• BeginTable: Block tag, always related to an EndTable tag
• EndTable: Block tag, always placed after the related BeginTable tag

Table, Section, and Iteration are meta-tags (Also called tags in this document) composed by:

• The Begin tag
• The related End tag
• The content between Begin and End

Section can have any other tags in its content.

Iteration can have any other tags in its content unless Sub-template. If a Section is inside an Iteration, it can’t contain a Sub-template tag.

Word table related to Table tag can contain Field tags and Columns tags.

The template doesn’t support the intersection of tags. If a Section or an Iteration starts inside another it must be closed before the parent tag closes.

To be able to select a tag the user must place the text cursor inside the tag text and the selection must be empty.

An Iteration tag is also selected if the text cursor is inside the content of the Iteration. A Table tag is also selected if the text cursor is inside the related Word Table.

Conditions

Conditions are used for diverse purposes:

• Configure visibility through a display condition (more information in Smart Document - Sections)
• Filter a Data Context (more information Smart Document - Dynamic tables)
• Set conditional formatting on table lines (more information Smart Document - Dynamic tables)
• Set an iteration criteria (more information Smart Document - Iterations)

SINGLE CONDITION

A single condition is made by a trinomial:

A data tag

• A data field from View/Component (Prefixed with F)
• A data column from parent Data Context (Prefixed with C)
• A system value (Line Template, Depth of hierarchical data source, …) (Prefixed with S)

An operator

• =
• !=
• >
• <
• >=
• <=
• contains
• does not contain
• is empty
• is not empty

A value

• Free text value - The value is case-sensitive.
• A line template name from a drop-down list coming from the datasource in case you chose the LineTemplate’s system property
• A quote field - in that case, tick the "Based on variable" checkbox and pick the field you want to use.

To determine if a condition is valid or not, the text value is converted to the type of the selected property (String, Integer, Boolean…) and then compared using the selected comparator with the property value.

MULTIPLE CONDITIONS

A multiple condition is made by a list of single conditions. A multiple condition has three modes:

MODE	IMAGE
AND: Valid if all single conditions are valid
OR: Valid if one of the conditions is valid.
CUSTOM: Valid if a formula is valid. For the CUSTOM mode, each single condition has an id, the formula support parenthesis, “and” keyword and “or” keyword.

HOW TO EDIT A CONDITION

To edit a condition the user must click on it in the condition list. The Data tag, Operator, and Value can be changed just below.

HOW TO DELETE A CONDITION

To delete a condition the user must click on the delete icon next to the condition in the conditions list. The condition number will be removed from the custom logic field.

Data Context

Data Context is the source of data used by Iterations and Tables to iterate on a grid content. Data Context can be either:

• A selected View/Component from the Data Source Model
• The parent Data Context if the object is placed in another iteration (More information: Smart Document - Iterations)