# Mail Merge

&kword; has the ability to use data from an outside database (or internal database) to personalize your documents for individual members/clients/friends.

This section of the manual will cover all aspects of creating, merging and printing documents that are specific to &kword;. This manual will not cover:

- Creating an external database.

- Security issues regarding databases.

- Detailed instructions on SQL. It is assumed you have some knowledge regarding SQL if you are using a SQL database for your data source.

- Accessing the network or internet.

For answers to these questions, other documentation is available on the internet that is specific to the software you have chosen.

If you want to use the internal database of &kword;, click here.

## Using an outside database (SQL) to create documents

&kword; has the ability to use several of the most popular open source databases as a source of data for personalized documents.

In order to access an outside database using SQL, your machine needs to have the appropriate database module compiled into your copy of QT.

For more information see the installation section of this documentation.

The database can be located on the same machine as &kword;, or on any computer which is accessable through your computer network or the internet.

In order to use the database, you must know the following information:

- Name of the database

- Host name/IP address of the computer the database is located on

- The port address on the specified computer granting SQL access

- A valid user name for the database

- A valid password for the user name

If you have all this information at your finger tips, you are ready to proceed.

Using an outside database to create personalized documents is a three step process:

1. Connect to the database and select your query.

2. Insert the merge fields to tell &kword; where to insert the database information

3. Print the personalized documents.

### Locate the database and query the records.

To begin, select Tools Configure Mail Merge... from the menubar. A dialog box will appear.

Click on Open Existing.... Another small dialog will appear.

There is currently only one option in this dialog box (QT-SQL source). Click on OK. A new dialog box will appear.

Enter the URL or IP address of the computer that holds the database in the text box labeled Hostname:.

Select the correct driver from the dropdown box labeled Driver:.

Enter the database name you were provided in the text box labeled Database name: and a user name in the text box labeled Username:.

If the database access is through a port other than the default port enter that port number in the text box labeled Port:.

If you are going to be using this database at other times, you can click on the button labeled Keep settings. &kword; will ask for a descriptive name.

When you want to restore these settings on future sessions, simply select the descriptive name from the dropdown box in the upper left of the dialog box.

When all information is correct, click OK. &kword; will ask you for a password to that database. Enter the password in the text box, and click OK.

This dialog box will re-appear.

Click on Edit Current.... Another dialog will appear.

This dialog is designed to help you enter and test your database query. The dialog is divided into three sections: Database information, Query information and Query line.

The database information section is labeled Information and consists of two combo boxes. The left combo box (Available tables) gives you a list of all available tables within the current database. Select the desired table from the list by clicking on the table name with the &LMB;. A list of all available fields from that table will appear in the right combo box.

The query line is a text box located near the bottom of the dialog labeled Query. Simply type your SQL query into this text box and click Execute. &kword; will query the database and return the specified query in tabular format in the Query result box. You can alter, or edit your query on the query line and each time you click Execute, the new query results will appear.

&kword; does not limit your query strings. They can be simple and straight forward:

`select * from eMail`

Or complex multitable queries:

`select eMail.FirstName, eMail.LastName, eMail.address, data.Birthday, data.EyeColour from eMail, data where data.FirstName=eMail.FirstName and data.LastName=eMail.LastName`

Clicking Setup, will allow you to log into a different database.

When you have the correct query in the Query text box, click OK to select that query.

This will return you to the mail merge main dialog box.

Click Close.

Now that you have selected your data query, it is time to insert the merge fields in the document. Click here to continue.

## Using an internal representation of tabular data to create documents

For small sets of data, or when you do not currently have a database containing the merge data, &kword; offers you the ability to enter the data directly into &kword; in tabular form. This internal data structure can then be used to create documents with this data inserted at predefined locations.

Using an internal representation of the data to create personalized documents is a three step process:

1. Enter the data into &kword;

2. Insert the merge fields to tell &kword; where to insert the database information

3. Print the personalized documents.

After the data has been created once, you can go back and change the data as needed, and produce another set of personalized documents from that data.

### Enter the data

To begin, select Tools Configure Mail Merge... from the menubar. A dialog box will appear.

Click on Create New.... Another small dialog will appear.

There is currently only one option in this dialog box Internal storage. Click on OK. A new dialog box will appear.

This is a record card for creating your tabular data file. Along the top is a toolbar and the main part of the dialog is space to hold your entry/data pairs.

#### Defining the structure of your data table

First, we need to add one or more entries (merge fields). This is accomplished by clicking the (Add entry) button (third button from the right along the toolbar). A small dialog box will appear. Type a descriptive name of your entry in the dialog box (Name, Address, Balance Due, etc....).

This is for the name of the entry, not the data that is contained within the entry.

Click OK, and the entry is added to the card.

Repeat this process until all needed entries are visible on this first card.

If you want to delete an entry, simply click once on the entry name with the &LMB; and select (Remove entry).

Be very sure you have selected the correct entry name. Once you tell &kword; to delete the entry, the entry and all of the data within those entries will be deleted immediately. You will not be given the option to stop or reverse the process once it is begun.

#### Entering the data into the table

Now that the structure of your data is defined, you can enter the data into your entries.

At the top of the dialog box, are 4 buttons surrounding a spin box. The spin box gives the current record number. All records are numbered in the order they are added starting with number 1. You can use the spin box to go directly to the desired record or you can use the arrows to graphically move through the list of records.

button | Action
| Move directly to record one
| Move back one record
| Move forward one record
| Move to the last record in the dataset

To enter the data, simply place the cursor in the text box to the right of the entry name, and type in the data. (&kword; uses No Value as the default value for all entries in newly created records.)

To add a record, click the button.

To delete a record, click the button.

Be careful when you are deleting records. Once deleted, the record can not be retrieved.

Continue to enter all data until your dataset is complete.

After your dataset is complete, click OK to save the changes to your dataset. This will bring up the mail merge main dialog:

Click Close. Now it is time to insert the merge fields in the document.

### Insert merge fields in document

Now that &kword; knows the entries available in your data source, you can insert the merge fields into your document.

A merge field is a placeholder within the document. This placeholder will be replaced in each personalized document with the value of the entry for that individual record.

#### Insert a merge field

To insert a merge field, place the cursor at the desired place in the document. Select Insert Variable Mail Merge... from the menubar. A list of available entries will appear. Select the desired entry, and click OK.

The merge field is inserted at the current cursor location. The merge field is surrounded by brackets.

You can place the cursor in a new location in the document and insert another placeholder. When you are done inserting placeholders, you can proceed to printing your document.

#### Delete a merge field

To delete a merge field, simply place the cursor at the end of the merge field, and press the &Backspace; key. The entire merge field will be deleted.

### Previewing and printing the merged document

Once you have inserted all the merge fields you want, you are ready to preview and print the personalized documents.

#### Preview your documents before printing

To preview your document select Tools Configure Mail Merge... from the menubar. A dialog box will appear.

Select Print Preview. You will be able to see the final output of your personalized documents prior to printing.

#### Print your personalized documents.

You print personalized documents using the same methods that you do to print traditional documents. For more information on printing see the section on Printing a Document.