Merge Codes


Merge Codes
A merge code is a "placeholder" within a document which is replaced by data (associated with the recipient) extracted from the database.

All merge codes consist of two parts separated by the pipe symbol (also called a vertical bar) which is displayed as | and surrounded by an opening and closing brace { } (curly brackets).  The first part selects the main category from which the merged data is to extracted and the second part the name of the data field to be merged.

The output of some merge codes is calculated on the fly and rely upon the correct data being in the database.  Others are date sensitive and will only provide data if a record exists that fits the date requirements of the field.  If the data is missing, (such as using a document with a vacate date and the tenant has not vacated), or you are trying to merge data the system thinks is logically impossible, the error is indicated in the letter preview.

Example If you use {Tenant|NewRentDate} and the date of the last rent change is earlier than today, an error is indicated by the field name showing with leading and trailing asterisks thus - ***NewRentDate***.  The reason being it is not logical to give a warning about a rent change in the past.  Incorrect or missing data will be indicated in a similar manner, but remember you can always enter new data or over-key the error indicated at the point of production then print the document without affecting the standard document.

DO NOT use braces { } as you would round ( ) or square [ ] brackets in the text of any letter.  Braces are reserved to delineate merge codes.

When creating documents be sure to select the merge codes associated with the intended recipient type, (landlord, tenant or supplier).  When producing a document for and a single recipient remember to work from the [Mail] button of that type of recipient.  Documents used in mail merge may have different criteria.

Creating a document with merge codes
This is a learn by doing section.  It will show how merge codes can be used to replace "variable data" relevant to the recipient chosen at the time of producing the document.  Carry out the instructions in this section on your computer to achieve the stated objective.

You may like to make use of the Training module if not keep track of where you save documents as you will probably want to delete them.

Create a standard document containing merge codes and use that to produce a letter to several different tenants.
Create an ad hoc letter to a landlord and inserting merge codes at the time of writing the letter.

Both the above objectives use the demonstration system data for names etc.  If you have a live system select your own recipients and check the results against the recipients records.  You may wish to use copy and paste to enter the sample text in this exercise.

XXXX   Reference skinny version / hand written etc

Objective 1 - Creating a standard document
Go to Setup menu > Standard documents.
Click [Add] (+)
Enter "00 Learn by doing standard letter with merge codes" in the Name field
Click [Save] (the tick)
Click [Edit]
Click in the main pane and enter the following text between, but not including, the rows of equal signs.

Capt J Cook
247 Balmoral Rd

22 August 2011

Dear James,

Outstanding Rent

Today our records show that you are only paid to 13 December 1769 and your rent is in arrears by $4000.00.  This is a breach of your tenancy agreement.

In order to remedy this breach you must pay those rent arrears within fourteen (14) days of the date of this letter, that is day, month, year.

Hope this finds you free of scurvy.

Yours sincerely,

Sunni Daze
Property Manager

Click [Save]

The outline saved shows how the standard document is to look and what it is to contain when it is produced.

The next step is to replace those portions of the document which are personal to the recipient with the correct merge codes.
This is done by selecting the appropriate merge code using the two list boxes and the [Paste] button in the header. 

Click [Edit]
In the first list box select Tenant
In the second list box select AddressTo
Highlight Capt J Cook and click [Paste]
You should see Capt J Cook replaced by the merge code {Tenant|AddressTo}

Repeat this selection and paste process for the remaining personal details.  Try working it out yourself then check that you have pasted the correct merge codes according to the list a little further below.

If you wish to save the document at any time you can press Clt+S which saves the document and leaves you editing the document.  Alternatively press [Save] then to continue editing press [Edit] again.

You may like to refer to the standard document titled "zG042 Letter Fields - Tenant letters".  If you follow the instructions at the top of that document you can have a printed list of the available merge fields and their output.

When you think you have the merge codes in place
save the document
close to the Tenants main screen
select a tenant, preferable one with an Outstanding Rent value
press [Mail]
select New letter ...
Chose "00 Learn by doing standard letter with merge codes" from the Standard Document list box
the standard document should now appear with the merge codes replaced by the relevant data.
Print the letter if you wish.

If things are not quite what they should be return to the Setup menu > Standard documents and select the document again.
If you would like a hard copy of the text and merge codes press [Print].
Check the merge codes entered against the list below and the comments following the list

{Tenant|AddressTo}   the tenant's "mailing" name 
{Tenant|MailAddress1}  the tenant's mailing address line 1
{Tenant|MailAddress2}  the tenant's mailing address line 2
{Tenant|MailAddress3}  the tenant's mailing address line 3
{Other|LetterDate}   the date of the letter
{Tenant|ContactName}  the tenant's contact name
{Tenant|PaidToDate}   the date the rent is fully paid to
{Tenant|RentDue}   the amount of the rent arrears
{Other|LetterDate+14}   the date by which the breach must be fixed
{Property Manager|Name}  the property manager's name
{Property Manager|Position}  the property manager's position

As can be seen it was necessary to make three selections in the first list box to locate all the merge codes required.
The tenant's mailing information is taken from the Tenants > Name and Address screen which should contain the Address for Service which may not be the property address.  If you were writing about the property in particular, such as with an inspection notice, the property address should be obtained by selecting Property in the first list box then the address lines you require.
The date for the breach to be remedied, in the list above used the merge code {Other|LetterDate+n} and "n" was replaced by 14.
Check you have a comma after the tenant's contact name, that there are spaces between all the words, and a dollar sign in front of the arrears amount.  The $ is not part of the merge code and must be entered from the keyboard.

The correct standard letter should be



Dear {Tenant|ContactName},

Outstanding Rent

Today our records show that you are only paid to {Tenant|PaidToDate} and your rent is in arrears by ${Tenant|RentDue}.  This is a breach of your tenancy agreement.

In order to remedy this breach you must pay those rent arrears within fourteen (14) days of the date of this letter, that is {Other|LetterDate+14}.

Hope this finds you free of scurvy.

Yours sincerely,

{Property Manager|Name}
{Property Manager|Position}


Try the standard document against other tenants and check the results against the financial summary panel and transactions grid.
Note that besides any overdue rent the tenant may also owe debt, letting fee, or bond none of which are taken into account in this document.

You will notice the document shown in this topic has additional formatting.  The heading "Outstanding Rent" is centred and parts of the text are in bold.  See    XXXX for how to format text.

Objective 2 - Creating an ad hoc document
This time we are writing to a landlord asking for verification of his email address.

First find a landlord with an email address by checking on the Name and Address screen.

Instead of needing to insert merge codes for the name and address, letter date, contact name and sign off every time you create a one-off document there are three sample templates supplied in the demonstration system which have these codes already in place.  They are in effect empty letters and this learn by doing exercise is going to make use of the landlord template.

Press [Mail]

In the Standard Document list box select "zG010 Landlord Template"
You will see a document appear which as all the personal details mentioned above but no content.
Change the Subject to read "Please verify your details."
Click at the end of the "Re:" line
Add a couple of spaces then "Email address verification"

Press enter once or twice to provide spacing lines then enter the text on the next 2 lines:-

The email address we have on file may be incorrect.
Would you please verify that xxx is the correct email address.

Once the text is entered highlight the xxx's
Right mouse click anywhere in the main pane
From the popup menu select Insert Letter Merge Code > Landlords > Email
The landlords email address will replace the x's.

But the email address does not stand out very well buried in the text so try making it bold by highlighting the email address then pressing Ctl+B on the keyboard.

How about centering the "Re:" line by clicking anywhere on the line then pressing Ctl+E on the keyboard.
Now make the line bold and underlined by highlighting the text and using Ctl+B and Ctl+U.

This document obviously needs to be printed and mailed, or faxed, or could be sent by SMS.  Sending by email may not be such a good idea!

If you save it as a Bring Up you can be reminded to check for a response in a few days or so.  I doubt it needs to be saved to the Correspondence File but there is no harm in doing so if that's your policy.

As you can see a simple one-off document can be knocked up in a minute or two. If you want a Bring Up add five seconds.  Most often it will probably contain data merged from the database.  Using one of the three templates leaves you with only the content to be keyed in and as you saw data can be plucked from the database very easily.

If you have not done so you really should read the Word Processing Features and Speed Keys topics because those cover formatting and text selection.  They will increase your proficiency in making documents attractive and able to emphasise the important items.

Which Merge Code?
By now you will be aware there is a wide range of data available which can be inserted into a document using merge codes, but which code to use and what does each one produce?

To help with those questions there are three sample documents called "zG040 Landlord Letter Fields", "zG042 Tenant Letter Fields" and "zG044 Supplier Letter Fields" which display the merge field labels and the resulting content.  Follow the instructions in each document to see what each merge code produces.

You will also find there are merge codes which are common, or at least available, to a document regardless of the intended recipient.  However, there are also those which may appear to give the correct answer "most of the time" but seem to make mistakes now and again.  It is more likely the mistake is yours.  As an example, in the tenant arrears document you created above, the tenant's address used the {Tenant|MailAddress1 - 2 & 3} merge codes.  Had the {Property|StreetAddress}, {Property|Suburb}, {Property|City} merge codes been used they would have produced the same result except where the tenant's mail address was different to the property address.  If the address for service (of legal notices) was the mail address any notice sent would be voided.

Another consideration in choosing the merge codes is how the document will be used.  Is it only to be used to communicate with individuals, or will it be used for mass communication?  I can hear you say "what difference does it make?" and the answer is a great deal and it is all due to the relationship that exists between the landlord, property and tenant.  The relationship of a tenant to a property and that of a property to a landlord is one to one.  That is a tenant can only be attached to one property and one property can only be attached to one landlord.  Thus if you know the tenant you also know the property and the landlord.

Whereas, the relationship of a landlord to the property may be one to many, that is one landlord may own multiple properties and each property may have multiple tenants attached to it albeit there should only be one current tenant.  So any document written to a landlord requires a particular property to be selected and if a tenant is involved they must be selected as well.  It should be apparent from that having to manually select a property and then possibly a tenant too is absolutely fine when the document is created from the landlord [Mail] button.  However, things will fall apart if an attempt is made to use the same document to communicate with many recipients using (bulk) Mail Merge from the menu bar.  There is more on this in the     XXXX   topic.

Most of the merge codes are self explanatory and their outcome is not in doubt, however, some of the merge fields worth a comment are:-

Quick Format
This inserts the generally accepted letter heading and sign off merge codes.  Use it when creating a new standard document or a one-off communication.

Contact Name
The Contact field in the Name and Address record.  Typically Bob, Mary, Mr G Horne etc. in the appellation follows "Dear" and should generally be used in preference to {Other|To} which can produce unusual results.

Payment Method
The landlord and supplier payment method (CHQ or DC) and in the case of payment by DC the bank account number recorded in their Payment Details.

Property Manager fields
The entries made on the Setup menu > Property Managers records.  When printing a letter some of these entries will be auto-filled.  See the Hints section below.

Tenant PaidTo
The Paid To date as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant RentDue
The amount of Rent outstanding "today" as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant DebtDue
The amount of Debt outstanding "today" as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant LettingFeeDue
The amount of Letting Fee outstanding "today" as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant BondDue
The amount of Bond outstanding "today" as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant Held
The amount of money being held in the tenant's account as shown on the main Tenant screen summary panel excluding    XXXX     future dated transactions.

Tenant TotalDue
The total of the above outstanding "today" as shown on the main Tenant screen summary panel which excludes future dated transactions.

Tenant RentAmount / Tenant RentPeriod
These fields are extracted from the last [Rent Changes] record with an increase date less than or equal to the letter date.  This will be the same as seen on the main screen unless the Rent Amount label is in red text indicating a future rent change.

Tenant NewRentAmount / Tenant NewRentPeriod / Tenant NewRentDate
These fields are extracted from the first [Rent Changes] record with an increase date after the letter date.

Tenant NextRentAmount / Tenant NextRentDueDate
These fields come from the first Rent Inv record with a transaction date later than today so you can say "...the full amount required to clear your arrears and pay the next {Tenant|NewRentPeriod}'s rent is {Tenant|NextRentAmount} and must be paid on or before {Tenant|NextRentDueDate}.

Combining the last three groups it is possible to create this document    XXXX

Tenant BondIncrease
The increase in the bond required associated with the item above.

Other LetterDate+n or -n
This allows you to insert a date into the text of the letter.  The date may be offset by plus or minus n days from the letter date.

Other SignedBy
This allows you to insert the content of the "Signed By" field into the letter text.  Eg. ....please contact {Other|SignedBy} before 2pm....

Other To
This generally inserts the content of the Contact name of the recipient, however, using the {major category|ContactName} is the preferred method.  Take care with this merge code as it can the produce unexpected results when used incorrectly.

Tenant MailAddress versus Property StreetAddress
Often these two merge codes will produce the same result but not always.  When you want the address of the property the tenant is residing in you should use {Property|StreetAddress} and possibly {Property|Suburb} etc not {Tenant|MailAddress1} etc or you may write a letter containing  ".... property at PO Box 12 345 ..." instead of ".... property at 13 Putney Place ..."


Defaulting Fields
When producing letters the Aspect Property Manager will fill in some fields using information based on the user name entered when starting / logging in to Windows and the Aspect Property Manager.  If it is incorrect it may be over keyed or different selections made, such as selecting a different Property Manager.  However, this new information will now be stored and offered next time a letter is produced.  So where a terminal is shared between different people care should be taken that the "automatic" selections made are correct or each user should have their own login.

The Aspect Property Manager fills fields based on fixed relationships which exist but where there is more than one possible selection a pop up window will permit a choice to be made.  An example would be when writing a letter to an individual landlord regarding one of his several properties you will be required to select which property is involved and possibly which tenant.

The sample standard documents contain three templates, one each for landlords, tenants and suppliers.  I suggest you set up three standard documents similar to these templates and name them for example, "010 Landlord Template", "010 Tenant Template" and "010 Supplier Template", in the style you want for your one-off documents.  The reason for using "010 " in the letter name is to force these three documents to the top of the selection list.  Now an easy to find template makes writing an ad-hoc document easier when you select the recipient > [Mail] > New Letter as only the body text needs entering.  See also the section on letter naming.    XXXX   link address elsewhere

Document Merge Codes
There are three sample documents called "Landlord Document Fields", "Tenant Document Fields" and "Supplier Document Fields" which display the merge field labels and the resulting content.  Follow the instructions in each of those documents to see what each merge code produces.

Printing on pre-printed forms
In general this is not recommended, however, it is possible to do by setting up a standard letter and careful placement of text or merge codes and manipulating the font size.  As with other letters variable vertical spacing can be achieved by changing the font size prior to pressing "Enter".