KBA-01323: Overview of the WordTemplateConfig Rules

Overview:

The WordTemplateConfig rules configure and extend the data available to bookmark templates in Microsoft Word.

The WordTemplateConfig rule group is found in the Rules Maintenance tool on the System Admin Dashboard. Each rule in the group consists of a rule name and a result value.


Filter Value:

Any Doc type

The WordTemplateConfig rules accept a Doc type (as defined in the Doc Types tool and appearing in the filter drop-down) as the filter value. However, filters are rarely used.


Result Value:

Varies

Result values for the WordTemplateConfig rules depend on the rule and are indicated within the description of each rule. Note: there is a 196-character limit in the result value field. If your text is longer than 196 characters, you will need to:

  • Split your text into smaller segments, each of any length up to 194 characters,
  • Append $+ to the end of each segment, except the last one.
  • Add a rule row for each segment. These rules should have names that indicated they are a continuation of the first rule, for example: ciCost.LineDescription.01, ciCost.LineDescription.02, etc.

Some rules are enabled and disabled through a checkbox in the result value, for example:

checkbox result value


Rules:

It is impossible to list all the possible rules in this rule group. There are a number of Spitfire-defined rules; you can review and override these defaults as necessary.

The various rules fall into the following types of entries:

alias:FieldList

Specifies (in the result value) the fields to predefine for the indicated alias. The result value accepts a list of fields, separated by semicolons. Use this rule if you wish to add several fields that depend on one another (this rule controls the order of definition) or if you wish to use your computed field for sorting or filtering. For example: ciCost:FieldList = Subcontract;ProjEntity (with no filter) or DocMeetingAttendee:FieldList = NameCompany when used with the rule xFilterTable1_DocMeetingAttendee = NameCompany=’Acme’.

KBA01323_01

alias.fieldname

Specifies (in the result value) the computed definition for the indicated alias.fieldname. The result value accepts any computation. If the template engine encounters a bookmark that references a field that is not defined, it checks this rule for a dynamic definition. The formula definition follows the same principles as it would in a xCMP bookmark. Type can be DATE, DECIMAL, GUID, INTEGER or STRING. By default, your computed field will be defined as a STRING. You can specify the type using the extended syntax as type = formula.   A string value will be scanned for nested bookmark references (see KBA-01348.)  Some examples are:

KBA01323_05

qalias:Alias

Specifies (in the result value) the TSQL query that creates and defines an alias to be used in bookmarks on Microsoft Word templates. If the template engine encounters a bookmark that references an undefined alias that begins with a q, it checks this rule for a dynamic definition. The fields returned in the result set of the query are all accessible in the template using standard bookmark syntax, for example, for qDrawings:Alias, the following can be used: RR_qDrawings_Title, RRFT_qDrawings_ReferenceDate, etc.  In the query, you can reference @pProject for the current Project ID; @pDocMasterKey for the current (template) document, @pDocTypeKey for the current (template) document type and @pUID for the current user identity. (See KBA-01476 for details on Dynamic Aliases, including additional rules to modify the qAlias.) We suggest using the same rule in the QueryConfig rule group; in fact, to use QPList or QTimeout you must use a QueryConfig rule.

FDTXCents

Specifies (in the result value) the text that the FDTX bookmark prefix should use after the number of cents.  This rule is often used in conjunction with FDTXDollars (below).  A leading space is automatically added if the string does not begin with a slash(/).  Default is /100.

FDTXDollars

Specifies (in the result value) the text that the FDTX bookmark prefix uses after the number of dollars. This rule is often used in conjunction with FDTXCents (above). Leading and trailing spaces are automatically added.  Default is DOLLARS.

Table:ChildList

Specifies (in the result value) a temporary dynamic child relationship. A table has child rows if some combination of fields in the parent table identify a set of rows in the child table. It is only necessary to use this rule when a dynamic relationship is being used and the bookmark references the relationship using a Child() function. The child table must be a :ParentList rule entry (see below). The result value takes the form ChildTableName1;ChildTableName2;ChildTableName3; etc. For example, these two rules would work together: SubcontractDetails:ChildList = SubcontractLineIdleDetails and SubcontractLineIdleDetails:ParentList = SubcontractLines = SubcontractDetails(Subcontract).

KBA01323_06

Table:ParentList

Specifies (in the result value) a temporary dynamic parent relationships. One table can be the parent of another table if some combination of fields in the child table uniquely  identifies a single row in the parent table. The result value accepts a string in the format ParentRelationName = ParentTableName (parentfield1:childfield1, parentfield2:childfield2, etc.) Note: Use ParentRelationName in PARENT(ParentRelationName) computed field expression. See KBA-01437.

xDetailedTrace

Specifies (in the result value checkbox) whether detailed output should be generated. Once enabled, detailed output remains enabled until the application is recycled. You should also specify xSendDetails (below) in order to have the information emailed to you.  Note: this rule enables itself if any template generation results in an error.

  • unchecked = No (default).
  • checked = Yes

xFilter_alias

Specifies (in the result value) the name of the field that should be used as a filter by default for the indicated alias if the xFilter bookmark is not defined in the template. Note: If you filter on a computed field, you must also specify alias:FieldList (above). The result value is a .NET DataExpression.  If string literals are involved, use single quites.  For example: to exclude “not sent attachments”, xFilter_DocAttachedFile might be set to

MailRoute <> '0'

xFormat:FRanyformatname

Specifies (in the result value) a formatting nickname for any string of characters from 1 – 20 characters in length. This rule provides a way to work around lengthy date format bookmarks in templates.

xSaveOnServer

Specifies (in the result value checkbox) whether the body of template generation emails (without the generated document attachments) should be saved in an HTML file in the web application log folder. (See also the xSendDetails and xShowData rules below).

  • unchecked = No (default).
  • checked = Yes.

xSendDetails

Specifies (in the result value) the email address to which the template generation email should be sent, for example: support@spitfiremanagement.com.   You can specify a semicolon separated list.  There is no default. Without this rule, you need to examine server logs.

xSendExceptionsOnly

Specifies (in the result value checkbox) whether emails should be sent to the email address indicated in the xSendDetails rule only if the template processing encounters some sort of exception or issue.  Warning: this rule is overridden by xShowData.

  • unchecked = No, send all template generation emails to the email address.
  • checked = Yes, send only exception or issue emails to the email address.

xShowData

Specifies (in the result value) whether all the document data should be included at the bottom of the template generation email. This rule is recommended if you can’t find the data for which you are looking. Since this rule forces (a very long) email to be sent, specify xSendDetails (above).  The xSendExceptionsOnly rule (above) is overridden by this rule (which means every template matching the filter will send an email).   Use this rule sparingly.  Beginning with V2017, this rule requires a filter value.

  • unchecked = No (default).
  • checked = Yes.

xSort_alias

Specifies (in the result value) the name of the field that should be sorted by default if an xSort bookmark is not defined in the template. This allows the rule to provide a global default for all documents, for example: xSort_ciAllocSummary = AllocSeq,Description or xSort_ciDetail = ItemNumber,ItemSeq. Note: if you sort on a computed list, you must also specify alias.FieldList (above).


Additional Comments:

These rules improve the usability and extensibility of the advanced Microsoft Word Template features by making them more distributable and more like the Executive Dashboard (KBA-01227) and KPI formulas (KBA-01228). For more information about template aliases and fieldnames, see the Focus on Bookmark (Doc) Templates guide.


KBA-01323; Last updated: July 16, 2019 at 11:24 am; green text = new
Keywords:  settings for word templates, custom fields for word documents