Documentation/WollMux/Mail Merge/Source Document
TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
The source template or document
Template or document
Even though you can use any form or existing document, or even a new document for mail merge, it is a good idea to consider whether using a proper template for the mail merge is the best option. In most cases, the answer to this question should be yes. The following table shows the main differences between using a template or a document:
Template |
Document |
|
Letterhead data |
The data of the current editor is entered - this allows multiple people to work with the template |
Fixed data of the creator - can therefore also only be used by this person |
Letterhead visible in the "template"? |
No |
Yes |
Updating the letterhead data |
All data will be updated |
Not possible |
Use of already contained fields (e.g. Empfaengerfeld1). |
Possible without restrictions - even if the fields are not visible in the template. |
Possible without restrictions |
Use of form functions |
Possible without restrictions |
Possible without restrictions |
Use of Content based directives |
Possible without restrictions |
Possible without restrictions |
Edit |
Right click → Edit template |
Double click to open the document |
The manual assumes that a template is used to create the form letter, because that is usually the better way. However, the procedure for using a document is not significantly different from this, so for this the contents of the manual apply in the same way.
Selection of the template or letterhead
You can use any mixed template, any letterhead from WollMux or any existing template or document as the basis for your form letter. If you want to combine your mail merge with form functions or Content based directives, you should have a look at the corresponding manuals.
Because in practice the external letterhead will probably be the most common use case, this will be used as an example.
Creation of the serial letter
Fixed contents
The best way to start the mail merge is to insert all fixed contents - if not already existing. Fixed contents are the parts that will be the same in every mail merge letter. The parts that will contain the mail merge data can be filled with placeholders or pseudeo data at this time. It would be as well to finally structure and format the template or document right away - ideally with styles.
Variable contents - the mail merge fields
After you have entered all fixed components of the source template, the variable components are now integrated.
To do this, you must first create a connection between the mail merge data (data source) and the source template or document (current document). Only then can you insert the mail merge fields of the selected data source into the source document.
Connection of source template and data source

Open the sidebar for the WollMux mail merge. There you have four options to link a data source:
- File...: Here you can select an existing Calc file from the file system as data source. This file will be opened automatically.
- Database: To select a database it must have been registered under LibreOffice before.
- If a data source (Calc file) is already open, these appear as entries below the button "Database" and can be selected by clicking.
- In which you select New Calc table, you can create a data source for your mail merge. Afterwards it goes on as described in chapter The data source.
If a data source contains multiple spreadsheets, an entry will appear in the data source list for each spreadsheet.
Checking and replacing the data source
If you open the mail merge sidebar, you can see directly if the template is connected to a data source. Then below "Database" an entry is marked in the data source list.
Inserting mail merge fields
With the template open and connected to the data source, proceed as follows:
- Position the cursor at the place where you want to insert the mail merge field.
- Press the Mail merge field button. An alphabetical list with all the fields of the data source will appear.
- Click on the required entry. The field appears at the cursor position.
Deleting mail merge fields
Mail merge fields can be deleted in the same way as other characters. So by
- Del, when the cursor is in front of the serial letter field.
- Backspace, if the cursor is placed after the serial letter field.
- Del or Backspace if the form letter field is selected.
Replacing existing WollMux form fields with mail merge fields
If you want to use an already finished WollMux form as a basis for your mail merge letter, or even just a letter header, you don't have to manually delete all the fields you don't need anymore because they will be replaced by mail merge fields. You can replace these fields directly from the sidebar.
To do this, follow these steps:
- Connect your form to your data source - if you haven't already.
- Click the Customize all fields button in the sidebar.
A window will appear with a list of all fields that are not from the data source. In the right column you can enter the new fields directly or select them by pressing the Mail Merge Field button.
Customize fields using declaration of assignment as an example The Customize Fields button replaces the old fields with the new ones.
Any fields that are part of the letterhead should not be replaced. Fields that are not needed remain empty and therefore do not interfere. For the required fields, the customization should be done in the data source (see chapter Adapt data source to WollMux fields).
WollMux form fields that are not replaced by mail merge fields will be populated with the data from the form.
Special fields
Special fields, depending on the mail merge data, help to control the content in the mail merge letter without entering everything in the data source. For example, if you need a variable salutation in your letter in addition to the address data, there are several ways to do this:
- Without special fields: You create an additional column in the data source with the field name Letter salutation.
For each record, you enter the appropriate salutation, such as "Dear Mr. Huber," "Dear Ms. Maier,". In the source document, simply enter the mail merge field Letter salutation (<Letter salutation>) in the appropriate place.
- With special fields: You use the Salutation field to distinguish between Ms. and Mr. and use the Gender special field by specifying: Whenever the Salutation field says Ms., Dear Ms. should be entered in the letter, and whenever the Salutation field says Mr., Dear Mr. should be entered in the letter. This saves you the additional column in the data source.
Special fields help to keep your data source clear and to work flexibly with your data in the form letter.
Inserting and editing special fields
Special fields are inserted and deleted in the same way as normal mail merge fields.
If you want to rework special fields, select the desired special field and choose Special Field → Edit Field in the sidebar. The special field will open and can be edited.
Gender function
The special field Gender can be used to insert gender-specific designations based on a mail merge field (usually salutation with the content Mrs./Mr. - m/f - female/male).
If the field Salutation contains Mrs, w, or female, the text in the field Text female will be written into the mail merge letter, if the field Salutation contains Mr, m, or male, the text in the field Text male will be written into the mail merge letter. If there is anything else in the corresponding field, the text from the field Text other will appear in the mail merge letter.

If...Then...Else
In principle, the gender function is a special case. The If...Then...Else... function can be used to control the contents of a field more universally. So if a field in the data source takes a certain value, a defined value should be displayed, otherwise a different value.
If...Then...Else fields are nestable, but here you should take care that the nested fields remain reasonably clear. In addition, mail merge fields can be used in these fields via the button Mail merge field.
The text in the Then or Else area of the field can be of any length.
Example: Suppressing emerging blanks
If you work with mail merge fields, which can also be empty, unwanted blank characters or lines can occur. These empty spaces can be suppressed with the special field If...Then...Else....
If you include titles in the salutation, you will have some people who have titles, but many will be without titles. In the template, without the If...Then...Else... function, it would look like this:
<Salutation>;-<Title>-<LastName>,
.
will either display the following for people with titles:
Mrs.-Dr.-Müller,
or for persons without a title:
Mr.-Müller,
.
So there would be two spaces between salutation and surname for persons without title. This is visually not particularly nice, but can be easily fixed with the If...Then...Else... function:
The entry in the form letter now looks like this:
<Salutation>-<Title><LastName>,
.
Where the Title field is now no longer a mail merge field but a special field and between <Title> and Last Name no Space is allowed to be.

- If: Here is the condition that the title is exactly empty.
- Then: If the field is empty
- Else: The title is displayed and a space after it, but it is not visible. But if you click into the field, you see the space between <title> and the blinking cursor.
This leads to the following result:
- With title:
Mrs.-Dr.-Müller,
.
- Without title:
Mr.-Müller,
.
Thus, for both cases, the number of spaces between each field is correct.
Example: Value range
A letter is to be sent to examinees, which among other things also states whether they have passed an exam or not. In our data source the score of the examinees is stored. In this example, out of a possible 15 points, one must score at least 6 points to have passed the exam.
For this case, add again a special field If...Then...Else... that refers to the score. The field should look like the following image.

Of course, it is just as correct to specify the function in reverse: If score < 6 THEN not passed OTHERWISE passed
.
Nesting of If...Then...Else...functions
If...Then...Else...functions can not only be used on one level, but can also go over several levels - this is also called nesting. For this purpose the button "New condition" is available in the Then- and Else-.
IF Statement1 THEN do this OTHER IF Statement2 THEN do that OTHER do something else.
Example Value Range
Adding to the exam results example from the previous chapter that examinees with exam results of 14 and 15 points passed with distinction, and examinees with 5 points can take a re-exam, requires a nested If...Then...Else...function.
Result |
Entry in field |
14 -15 |
Passed with distinction |
13 - 6 |
passed |
5 |
Failed (possibility to retest). |
4 - 0 |
Failed |
Again, there are several possible solutions. One can be seen in the following figure.

Regular Expressions
In the If query of the If...Then...Else... field you can work with regular expressions. Regular expressions are placeholders that you can use when searching in LibreOffice.
Examples:
- Placeholder for exactly one arbitrary character: .
- Placeholder for any number of arbitrary characters: .*
You can find more regular expressions in the LibreOffice help.
Record number
This special field allows you to print on each letter the number of the record in your data source. In the case of record 100, 100 will then be printed on the letter.
If each letter is to be printed in a separate file when printing, e.g. in order to mail the file, a file name can be automatically generated via the field Record number.
Serial letter number
Using this special field, you can have the serial letter number of the respective printout output on each letter. So if you have 100 records and print all records, record number and serial letter number are identical.
If you use only records 50 - 100 for your mail merge, the first letter will have record number 50 and mail merge number 1.
If you want to print each letter to a separate file when printing, e.g. to mail the file, a file name can be automatically generated using the serial letter number field.
Next record
This special field can be used to print several records on one page. E.g. this field is needed if you want to create labels via WollMux mail merge.