Creating Precedent Merge Templates

Overview

As outlined in our article Uploading your firms own Precedents it's easy create your own precedents. For a simple precedent that has no merge capability it's as easy as uploading the template document (this can be any type of document) and giving it a title and classification.

However merge enabled precedents are more complex to prepare and require the creation of a second "Merge Template" document. We've explained the process below and examples of merge templates can be downloaded at the bottom of this article.

If you need assistance preparing a merge template just email a copy of the document you want to upload as a precedent to support@connectworks.com and we'll get in touch to help out.

Contents

1. Merge-enabled precedents

2. Creating merge templates

3. Standard merge fields for all entities

4. Additional merge fields for trusts

5. Standard merge fields for companies

6. Standard merge fields - various

7. Address merge fields

8. Custom fields

9. Example merge template download

 

 

Merge-enabled precedents

Alongside the basic precedent template mentioned above, you may also provide a second template to enable merging. This must be a Microsoft Word document and contain either merge fields or special references (discussed below) that indicate where and what information from the selected entity is to be auto-populated on the document.

Creating merge template can be a little tricky but don't worry, we allow you to edit a precedent and re-supply the merge template. This means you can test out your merge template and then make changes, without needing to start over completely.

We also allow you to specify your own custom fields. These are typed as text, numbers, dates, options and formulas to control how information is populated on the document. We describe custom fields in more detail in the following section.

 

 

Creating merge templates

All merge templates must be Microsoft Word documents. We support the so-called "Mustache" template directives which simplifies how merge documents can be created. In the following example we will restrict ourselves to this "Mustache" format.

The "Mustache" way of looking up and inserting a single piece of information requires you to reference information using pairs of brackets. For example, to insert the name of a company into a document one would simply use the directive {{name}} and then in a document generated using the merge option, all instances of {{name}} will be replaced by the entity's name.

A chart of standard merge fields is outlined below for your reference.

Some merge information is provided as lists. For example: lists of the directors of a company, or trustees of a trust.

You can create region within your template that repeats for each member in the list using the #foreach directive. This is best illustrated with an example, below is a merge template to generate a named signing field for each shareholder within a selected company:

{{#foreach shareholder}}

_____________________

{{name}} - Shareholder

{{/foreach shareholder}}

The example above simply repeats the content between the {{#foreach shareholder}} and {{/foreach shareholder}} for all shareholders of the selected company.

 

Standard merge fields for all entities

Reference Description Example
{{name}} The name of the entity. For the {{name}} entity.
{{currentDate}} The current date Dated {{currentDate}}.
{{balanceDate}} The balance date (if set) for the most recent year. Balance date of {{balanceDate}}.
{{registrationNumber1}} The primary business registration number. Company Office number {{registrationNumber1}}.
{{registrationNumber2}} The secondary business registration number. The NZBN is {{registrationNumber1}}.
{{taxNumber1}} The primary tax number. IRD number {{taxNumber1}}.
{{taxNumber2}} The secondary tax number. GST number {{taxNumber1}}.
{{serviceAddress}} The address for service. This is of type address. Mail is sent to {{serviceAddress.country}}.
{{registeredAddress}} The registered address. This is of type address. The company is registered in {{serviceAddress.country}}.

 

Additional merge fields for trusts

Reference Description Example
{{settlementDate}} The settlement date Settled on {{settlementDate}}.
{{vestingDate}} The vesting date Vesting on {{vestingDate}}.
{{vestingEvent}} The vesting event Vesting when {{vestingEvent}}.
{{trustee, trustee_List}} This is a collection and references the trustees and are of type relationship. The trustees are {{trustee_list}}.
{{trusteePending, trusteePending_List}} This is a collection and references the pending trustees and are of type relationship. The future trustees are {{trusteePending_list}}.
{{settlor, settlor_list}} This is a collection and references the settlors and are of type relationship. {{#foreach settlor}}{{name}} - Settlor{{/foreach settlor}}.
{{beneficiary, beneficiary_list}} This is a collection and references the beneficiaries and are of type relationship. {{#foreach beneficiary}}{{name}} - Beneficiary{{/foreach beneficiary}}.
{{discretionaryBeneficiary, discretionaryBeneficiary_list}} This is a collection and references the discretionary beneficiaries and are of type relationship. The discretionary beneficiaries are {{discretionaryBeneficiary_list}}.
{{primaryBeneficiary, primaryBeneficiary_list}} This is a collection and references the primary beneficiaries and are of type relationship. The primary beneficiaries are {{primaryBeneficiary_list}}.
{{secondaryBeneficiary, secondaryBeneficiary_list}} This is a collection and references the secondary beneficiaries and are of type relationship. The secondary beneficiaries are {{secondaryBeneficiary_list}}.
{{finalBeneficiary, finalBeneficiary_list}} This is a collection and references the final beneficiaries and are of type relationship. The final beneficiaries are {{finalBeneficiary_list}}.
{{appointer, appointer_list}} This is a collection and references the beneficiaries of type [relationship]. {{#foreach beneficiary}}{{name}} - Beneficiary{{/foreach beneficiary}}.

 

Standard merge fields for companies

Reference Description Example
{{incorporationDate}} The incorporation date Incorporated on {{incorporationDate}}.
{{director, director_list}} This is a collection and references the directors and are of type relationship. {{#foreach director}}{{name}} - Director{{/foreach director}}.
{{directorPending, directorPending_list}} This is a collection and references the pending directors and are of type relationship. {{#foreach directorPending}}{{name}}{{/foreach directorPending}}.
{{shareholder, shareholder_list}} This is a collection and references the shareholders and are names only. {{#foreach shareholder}}{{name}} - Shareholder{{/foreach shareholder}}.

 

 

Standard merge fields - various 

Relationships

Reference Description
{{name}} The (common) name of the relationship.
{{phone1}} The first recorded (common) phone number.
{{phone2}} The second recorded (common) phone number.
{{email}} The (common) email.
{{registrationNumber1}} The first corporate registration number (for an organisation).
{{registrationNumber2}} The second corporate registration number (for an organisation) if relevant.
{{taxNumber1}} The first tax number (i.e. the IRD number).
{{taxNumber2}} The second tax number (i.e. the GST number).
{{dateOfBirth}} The (common) date of birth (for a person).
{{locationOfBirth}} The (common) location of birth (for a person).
{{countryOfBirth}} The (common) country of birth (for a person).
{{address}} The service address or, if not assigned, the registered address. This is of type address.
{{serviceAddress}} The service address. This is of type address.
{{registeredAddress}} The registered address. This is of type address.

 

 

Address merge fields

Reference Description
{{street1}} The first street address.
{{street2}} The second street address.
{{town}} The city or town.
{{postcode}} The postal code.
{{country}} The country.


When an address is accessed directly (without reference to a specific field in the address) then a fully formed address is generated with line breaks. For example:

{{#foreach trustee}} {{name}} {{serviceAddress}} {{/foreach trustee}}

this will display each trustee down the page and for each trustee will display the name of the trustee followed by the full formatted service address (if present).

If you want to access specific field then use the dot notation:

{{#foreach trustee}} {{name}} Resident in {{registeredAddress.country}} {{/foreach trustee}}

or we can be more sophisticated and include a check:

{{#foreach trustee}} {{name}} {{#foreach registeredAddress.country_exists}}Resident in {{country}}{{/foreach registeredAddress.country_exists}} {{#foreach registeredAddress.country_notexists}}Of unknown residence{{/foreach registeredAddress.country_notexists}} {{/foreach trustee}}

note that in this instance the reference to the country is direct and the reason for that is that the foreach uses the dot notation on the registered address and this brings the address into context (and so property references are made relative to the address). This situation only occurs in this instance.

 

 

Custom fields

As noted above we support the creation of custom fields that can be used to capture information from the user that is fed into the merge template. We support the following field types:

Text
A simple text field.
Number
A whole number (plus zero).
Decimal
A number with a decimal place (often used for prices).
Date
Allows selection of a date.
Option
Allows the inclusion of an option which may control or provide content for the template.
Formula
This does not result in any information being collected from the user but rather combines the information captured from other custom fields to generate new information that is passed to the template for merge.

Text and date fields

Text fields are very straight forward and will suit most circumstances; the content is passed verbatim to the template. The same is true of dates which are formatted in long form (i.e. 12 October 1927).

Number and decimal fields

Numbers and decimals restrict what the user can enter and define special fields that carry specific formatting of the values the user enters. For numbers a new field is created by adding _formatted to the end of the reference value for that field (for example, if the field has the reference amount then the formatted version can be access using {{amount_formatted}}. This is the number formatted with commas at the 1000's places. For decimals there is an extra field _formatted2dp which provides a version that is rounded to 2 decimal places. This is useful for currencies.

Formula fields

Formulas don't capture any user input but rather process the values provided from other custom fields entered by the user. A simple example is used to calculate the GST on a dollar amount entered. Suppose that a custom decimal field whose reference is amount collect a dollar value from the user. You may create another formula field whose reference is amountWithGST and whose formula is round (amount * 1.15, 'cur'). Now referring to {{amountWithGST}} in your template will display the value the user entered for amount multiplied by 1.15 rounded to 2 decimal places formatted for currency (that is what the 'cur'means). We describe what you can do with formulas in more depth in the reference section below.

Option fields

Options are very special in that they are generally used to control the inclusion of content. As such they are employed in quite a specific manner.

In the default case an option will generate two sets of data that correspond to the selected and unselected case. Again this is best described by example. To this end support of an option with reference includeClause1 is created. Now consider:

{{#foreach includeClause1}}This is clause 1{{/foreach includeClause1}}{{#foreach includeClause1_not}}This is not clause 1{{/foreach includeClause1_not}}

If the user selects the option then This is clause 1 will be generated in the template, otherwise This is not clause 1will be inserted. So the special case is the use of _not which takes care of the unselected case. As an aside you may use{{name}}, {{label}} and {{description}} inside the foreach that will reference values from the definition of the option.

Building on the above we may group options together with a prefix separated by a period. An example are two options with references clauses.clause1 and clauses.clause2. In this cause one may use the following to group these options (note that the number is using Words number feature for lists):

1. {{#foreach clauses}}{{description}}{{/foreach clauses}}

This will generate a numbered list with entries displaying the description provided for each selected option. This is very useful for generating minutes or agenda items whereby the user selects from a list of pro-forma clauses. We also have a special case for these options (and the same applies to list valued properties, such as a list of directors or shareholders) that can test if the collection is not empty. To perform such a test we just use the same nomenclature as for iterating over the option values but this time we add an _if. The following example illustrates this where the entire region is included in the final document only if there is at least one clause option selected:

{{#foreach clauses_if}}The following clauses apply:

1. {{#foreach clauses}}{{description}}{{/foreach clauses}}{{/foreach clauses_if}}

An important exception for grouped options is that there is no corresponding "not" variation as provided for ungrouped options.

 

Formulas

Formulas will do their best to convert the underlying value to the most sensible form to use. For example, a text field that involves a multiplication will try to be converted to a number.

Formulas support the standard number operations such as +, -, * and / that operate with numbers. For text the + operation acts as concatenation.

Formulas also support functions. The available functions are:

Function Description Example
round (value, dp) Rounds a number to the specified number of decimal places (dp). If dp has the value 'cur'then the number will be rounded to 2 decimal places and formatted for currency (i.e. ###,##0.00).

 

 

EXAMPLE DOWNLOAD

The following documents have 2 pages, that actual raw information on how the document is created with the merge fields, and how it looks once uploaded into Connectworks and merged. The documents only show an example and not every merge option available in Connectworks.