Knowledge - Creating Merge Document Templates

The HowNow Merge Document system uses Microsoft Word merge document templates combined with the firm's master style template to create documents populated with data from an external database and other sources.

HowNow uses bookmarks inside these templates to specify where data is to be inserted. Bookmarks are areas within Word documents that have been given names. These areas can then be referenced using those names. HowNow bookmark names consist of the word HowNow followed by the description of the function of the bookmark. For example, HowNowAddress inserts the address block.

HowNow bookmarks can perform different functions. Some bookmarks simply specify the area where data is to be inserted; others allow entire sections of the document to be changed or replaced depending on the value of another bookmark; still others perform calculations and ask for more data. See HowNow Bookmarks for the complete list of bookmarks and examples.

A HowNow merge document template is a Microsoft Word document containing two separate areas: the body area and, optionally, the enclosure area. Each of these areas are enclosed by the bookmarks, HowNowBody and HowNowEnclosure. Note that the body area does not normally include the address and closing paragraphs - these are usually contained in the firm's master style template.

The firm's master style template contains the address block, the closing paragraphs and two special bookmarks, HowNowMasterBody and HowNowMasterEnclosure. These bookmarks specify where the body of the document and the enclosure areas will appear when the merge is completed. The master style template also contains the firm's document style and font settings.

When HowNow creates a new merge document, it first loads the specified master style template. It then loads the specified merge document template and copies the text contained in the HowNowBody bookmark into the area specified by the HowNowMasterBody bookmark in the master style template. The same thing occurs with the enclosure bookmarks. Note that any text outside the HowNowBody and the HowNowEnclosure bookmarks is not copied to the master style template and is lost.

Any bookmarks in the master style template, the body and enclosure areas are then replaced with the respective data and the document is saved as a new record.

Preparing to create merge document templates

In Microsoft Word, select the Insert tab, and select the Bookmarks checkbox. Also select the Hide/Show option to show the formatting marks. These two options make it easier to create merge templates.
Because of a Word anomaly, a bookmark cannot start immediately where another ends. This case is rare but if it occurs, the bookmarks must be separated by at least one character (e.g. a paragraph mark or a space). If a space is inappropriate, an @@ can be used instead. HowNow automatically removes any @@’s it finds after a merge document is completed. In addition, HowNow also removes any @ symbol-paragraph mark pairs of characters (@^P) it finds. This facility can be used to remove superfluous paragraph marks from a document. Note: The case of two bookmarks ending and starting at the same location is rare, so do not insert @ or @@ symbols unless they are needed.
By convention, the text enclosed by a bookmark is the bookmark name. The only exceptions to this are the HowNowSelectText, HowNowAskData, HowNowGridTotal, HowNowTextEntry, HowNowCalculate and HowNowUserField bookmarks. In these cases the enclosed text is the data needed for these bookmarks to function.
In Word, bookmark names must be unique, so in cases where the same bookmark is required more than once, add an underscore character and a unique number to the bookmark name. For example, HowNowTodaysDate and HowNowTodaysDate_1.
- SelectText bookmarks within SelectText bookmarks are a special case. To ensure that the inner SelectText bookmarks are processed before the outer, enclosing, SelectText bookmark, they are processed in alphabetical order. To enable this, inner SelectText bookmarks must have lower numbers (alphabetically) than the enclosing SelectText. Therefore, SelectTexts should be numbered with left padded numbers so that the digits line up and sort correctly alphabetically. For example, _006, _020, _123. Note: Alphabetical sorting proceeds from left to right, hence the left zeros to align the digits correctly.
- If a DataField bookmark is needed more than once, place one or more alpha characters after the field number as in HowNowDataField_1, HowNowDataField_1a and HowNowDataField_1b. These bookmarks all reference field number 1 but satisfy Word's need for unique bookmark names.

How to insert bookmarks into a Word template

Type the HowNow bookmark name or field details into the document where it is required.
Select the text and press CTRL+C to copy it.
Type Alt, I, K to display the bookmark editor (or select from the menu Insert > Bookmark).
If the bookmark is not HowNowSelectText, HowNowAskData, HowNowTextEntry or HowNowCalculate, press Ctrl+V to paste the selected text into the bookmark name field. Otherwise, type the bookmark name.
If a bookmark is used more than once, make the bookmark name unique by adding an underscore (_) and a number to the end of the name. Note item 4 in the previous section.
Press Enter to save the bookmark and close the bookmark editor.

A completed merge document template will look like the sample below.

Creating a HowNow merge document template

The HowNow knowledge database contains a large collection of merge templates. It is often easier to duplicate one of these templates and modify it rather than creating a new one from scratch.

Create a blank Word document. In the Knowledge tab, right-click the search results screen and select New.
At the Type Selection screen, select New Word Template and click Next.
Enter a title and description and keywords if required. Choose a document type (e.g. Letter) and a procedural area (e.g. Production). Click Next.
Click Document has merge fields to tell HowNow that this is a merge document. Select a Firm Master Style Template in in the dropdown. Click Next.
Click Next until the Finish button is enabled. Click Finish to save the new document.
The new document will be displayed, ready for editing.
Type the entire body of the document and the enclosure, if required. Type the bookmark names where appropriate but don't create the actual bookmarks at this stage. Add paragraph marks between paragraphs for clarity. These will be removed later.
Go back and insert the bookmarks. In general, the simplest method is to follow the procedure outlined in the section, How to insert bookmarks in Word template, above. If a SelectText bookmark contains another SelectText bookmark, do the inner ones first and assign them a lower (alphabetically) number than the outer SelectText.
When all of the bookmarks have been inserted, highlight the entire body section and apply the HowNowBody bookmark. Do the same with the enclosures section.
Save the document and try creating a test record. If there are errors, check that you have used the correct bookmark names, that the syntax is correct and that the bookmarks enclose the correct text. Check also that no two bookmarks end and start at the same point.
If the merge document template tests OK, make it current and it will be available to all users.

Creating a sample merge document

This example assumes that you have followed the above instructions up to step 7. This is an activity statement notice that handles either Business or Instalment activity statements, depending on the user's selection. Line numbers are shown for reference only and are not part of the document. See HowNow Bookmarks for a complete list of bookmarks.

HowNowEntityName
HowNowABN|True|ABN HowNowABN
HowNowDataField_01|BAS|Business|Instalment Activity Statement
We enclose your HowNowDataField_01|BAS|Business|Instalment Activity Statement for the HowNowDataField_02 ending HowNowDataField_03.
HowNowDataField_04|True|If you would like us to complete your Activity Statement, please complete the enclosed questionnaire and return it to us by HowNowDataField_05.
If you wish to prepare the Activity Statement yourself we would be happy to review it before lodgment is due. Your lodgment date for this Activity Statement is HowNowDataField_06.
Activity Statement Details
|Activity Statement Type|LISTBOX1;BAS;IAS
|Period|LISTBOX2;year;quarter;month
|Period end date|FULLDATE3
|Offer to review;Include the offer to review before lodgment|CHECKBOX4
|Return information by;;O;4;1|FULLDATE5
|Lodgment date|FULLDATE6

Enclosed: Activity Statement

Line 1 is a bookmark that shows the entity name of the client. In this case the text enclosed by the bookmark is the name of the bookmark. This is simply a convention that makes the template easier to read and correct later if there are errors.

Select the text and press CTRL+C to copy it. Type Alt, I, K to display the bookmark editor (or select from the menu Insert > Bookmark). Press Ctrl+V to paste the selected text into the bookmark name field. Press Enter to add the bookmark.

Line 2 is a HowNowSelectText bookmark that shows the client's ABN if it exists or removes the entire line if it doesn't. A HowNowSelectText bookmark has four parts, each separated by a vertical bar. Any bookmarks in the text are first evaluated. Then the values in the first and second parts are compared and it they are equal (True) then the third part is inserted in the document. If the comparison fails (False) then the fourth part, if it exists, is inserted in the document. In this case the first part holds the client's ABN. If it exists, the result is True and if it doesn't the result is False. The second part holds the value to compare to. In this case it is the word True. Thus, if the client's ABN exists, True matches True and the third part is inserted in the document. If the client doesn't have an ABN then nothing is inserted and the line disappears. Note that for this to happen, the HowNowSelectText bookmark must enclose the paragraph mark at the end of the line.

To add a HowNowSelectText bookmark, select it's text (including the paragraph mark, if required) and add a bookmark with the name HowNowSelectText_XX, where XX is the next number required to make the bookmark name unique. Left pad the number so that the digits line up as in _006, _020 and _123.

Note: be careful with bookmark names. If you add two bookmarks with the same name, the first one will be deleted.

Line 3 is another HowNowSelectText bookmark that inserts the words Business Activity Statement or Instalment Activity Statement in the subject line depending on the user's choice. The difference here is that the bookmark in the first value section is a HowNowDataField. This one has a number (_01) attached and this signifies that the value is to come from the first field on the AskData data entry screen described below. So if the user's choice was BAS, the subject would read Business Activity Statement; if the choice was IAS then the subject would read Instalment Activity Statement.

Line 4 contains a HowNowSelectText bookmark the same as in line 3, along with two HowNowDataField bookmarks that insert the name of the period (field 2) and the period end date (field 3), the return date (field 4) and the lodgment date (field 5), respectively.

Line 5 contains a HowNowSelectText bookmark the same as in line 3, along with a HowNowDataField bookmark that inserts the return date (field 5). This line only appears and the return date field is only enabled if the 'Offer to Review' check box (field 4) on the AskData screen is checked. See the explanation for lines 11 and 12 below.

Note: don't forget to enclose the paragraph mark in the bookmark as you want the entire paragraph to be hidden if this option isn't wanted.

Line 6 contains a HowNowDataField bookmark that inserts the lodgment date (field 6).

Lines 7 to 13 contain the text for the HowNowAskData bookmark. The HowNowAskData bookmark creates a data entry screen that pops up each time a new merge document is created from this template. It allows the entry of data and settings that determines the content of the finished document. The AskData bookmark text can appear anywhere within the body of the template. It is removed after it has been used so it is not saved with the final document. Lines 7 to 13 must be included in the AskData bookmark.

Line 7 is the title of the data entry screen (the AskData screen). It should describe the function of the screen.

Line 8 is the first field to appear on the AskData screen. It must begin with a vertical bar. It consists of two main parts, a prompt and a field type. In this case the prompt displays the phrase 'Activity Statement Type'. The field type is a list box that shows two options, BAS and IAS. The number immediately following the field type name is the field number and it is used to reference this value via the HowNowDataField bookmark. The field number cannot exceed 999.

Line 9 asks for the period name. Its field type is a list box that has the three options 'year', 'quarter' and 'month'.

Line 10 asks for the period end date. The FullDate field type specifies that the date is to be inserted in dd MMM YYYY format.

Line 11 asks if a review is required and displays a check box. The text 'Include the offer to review before lodgment' is optional help text that is displayed if the cursor is moved over the field. Use help text when more explanation than is provided by the prompt is required.

Line 12 asks for the date when the information must be returned. The text ';;O;4;1' after the prompt describes the following: the ;; is to allow for the optional help text. If it is absent the two semicolons must still appear. The 'O' specifies that this field is optional. If the letter was 'M' then this field is mandatory and must be filled in. The 4;1 specifies that this field should only be enabled if field 4 (the offer to review) is checked. The '1' is the value of a checkbox if checked; an '0' is its value if unchecked.

Line 13 asks for the lodgment date.

Line 14 is the enclosures area. It can contain other bookmarks. For example, a HowNowSelectText bookmark could be used to show or hide the enclosures area depending on user choice.

Now highlight the entire body section and add it as a bookmark named HowNowBody. Do the same for the enclosure section, and call it HowNowEnclosure. Note: any text outside the body and enclosure bookmarks is ignored.

This is how the document should look when completed. The bookmarks are highlighted in red:

[[HowNowEntityName]
[HowNowABN|True|ABN HowNowABN]
[HowNowDataField_01|BAS|Business|Instalment] Activity Statement
We enclose your [HowNowDataField_01|BAS|Business|Instalment] Activity Statement for the [HownowDataField_02] ending [HowNowDataField_03].
[HowNowDataField_04|True|If you would like us to complete your Activity Statement, please complete the enclosed questionnaire and return it to us by [HowNowDataField_05]].
If you wish to prepare the Activity Statement yourself we would be happy to review it before lodgment is due. Your lodgment date for this Activity Statement is [HowNowDataField_06].
[Activity Statement Details
|Activity Statement Type|LISTBOX1;BAS;IAS
|Period|LISTBOX2;year;quarter;month
|Period end date|FULLDATE3
|Offer to review;Include the offer to review before lodgment|CHECKBOX4
|Return information by;;O;4;1|FULLDATE5
|Lodgment date|FULLDATE6] ]
[Enclosed: Activity Statement]

Save the document and double-click it to run a test.

If there are errors, check that you have used the correct bookmark names, that the syntax is correct and that the bookmarks enclose the correct text. Check also that no two bookmarks end and start at the same point.

Use the Diagnostic Mode check box to switch on the inbuilt diagnostics to help with debugging the document. In diagnostic mode, HowNow displays the text of each Select Text bookmark before it is executed. Diagnostic mode can also be set by using the AskData option 'X'. See HowNow Bookmarks.