KWord/1.5/Manual/MailMerge

From KDE UserBase Wiki

Pending Deletion

This page has been proposed for deletion for the following reason:
KWord has been superseded by Calligra Words.
Please use the discussion section of this page to voice your opinion on this.

Mail Merge

Introduction

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.

You can retreive your mail-merge data from a number of sources:

  • If you want to use an outside SQL database, click here for instructions.
  • If you want to use a KSpread file for your data, click here.
  • If you want use information from your KDE Address Book, click here.
  • If you want to use the internal database of KWord, click here.

Using an external SQL database as a data source

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

Note
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.

Select QT-SQL Source and 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 driver named QMYSQL3 from the combo 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:.

Tip
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 combo 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.

KWord will now ask if you want to replace your current data source with the source you have selected. Click Yes.

You are now connected to the database. Now you need to select the data from the database. This dialog box has re-appeared.

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 left mouse button. 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.

Note
KWord does not limit your query strings. They can be simple and straight forward:
select * from Clients

Or complex multitable queries:

select Clients.FirstName, Clients.LastName, Clients.address, data.Birthday, data.EyeColour from eMail, data where data.FirstName=Clients.FirstName and data.LastName=Clients.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 a KSpread file as a data source

KWord can use data in a KSpread document for personalizing documents.

Note
In order to use this data, you only need to know the location of the KSpread document and the worksheet (page) number the data is located on.

Using a KSpread document to create personalized documents is a three step process:

1. Select the file the data is located within.
2. Insert the merge fields to tell KWord where to insert the database information
3. Print the personalized documents.

Selecting the file that contains the data.

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

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

Select KSpread Table Source from the drop down box labeled Available sources: and click on OK. A new dialog box will appear.

Enter the URL or file name of the KSpread document in the text box labeled URL:. You can type the file name directly into the text box, or click on the button with the blue folder and use the file dialog to select the KSpread file.

Once you have selected the KSpread document, the drop down box labeled Page number: will show you all the available pages or worksheets within the KSpread document. Select the page (or worksheet) that contains the mail merge data.

When all information is correct, click OK. KWord will ask you if you want to replace the current data source. Click Yes to continue.

You will again see 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 your KDE Address book as a data source

KWord can use data in your address book for personalizing documents.

Using address book entries to create personalized documents is a three step process:

1. Select the people you want included in the mail merge.
2. Insert the merge fields to tell KWord where to insert the database information
3. Print the personalized documents.

Select the people you want included

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

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

Select KDE Addressbook Plugin from the drop down box labeled Available sources: and click on OK. A new dialog box will appear.

The dialog consists of two listboxes labeled Address Book and Selected Addresses. By moving entries from your Address book to the Selected Addresses listbox, you will be including those entries in your merge document.

To add an entry, select the entry in the left listbox by clicking with the left mouse button. Then click Add.

To remove an entry, select the entry in the right listbox by clicking with the left mouse button. Then click Remove.

Tip
You can locate entries quickly by entering the first 2-3 letters of an entries name in the textbox labeled Filter on:
Note
You can load the full address book application by clicking the Address Book... button.

You can also save a distribution list using the Save as Distribution List... button. For more information on distribution lists, see the documentation on the KDE Addressbook.

When you have selected all the entries and distribution lists you want, click OK. KWord will ask you if you want to replace the current data source. Click Yes to continue.

You will again see 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....).

Note
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 left mouse button and select Remove entry.

Warning
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.


Warning
Be careful when you are deleting records. Once deleted, the record cannot 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

You can delete a merge field two ways.

  • Place the cursor at the end of the merge field, and press the Backspace key.
  • Place the cursor at the beginning of the merge field, and press the Delete key.

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.

400px|thumb|center

Click 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 [[Kword/Mnual/PrintDoc|Printing a Document].

Prev Contents Next
Document Structure Book-like Headers and Footers