Run Microsoft Word (Merge) Tool

What is the Run Microsoft Word (Merge) Tool

The Run Microsoft Word (Merge) Tool is used to create a task step that creates single or multiple documents in common Microsoft Word formats containing merged data.

Microsoft Word documents or templates are imported into the Tool that contain mail merge fields. These are then automatically read from the document by the tool and presented in a table. Each mail merge field may then either be mapped to BPA Platform variables, formulas and columns or left to use the mail merge data source specified in the document. The mail merge data source may also be imported into the BPA Platform database.

The Run Microsoft Word (Merge) tool can therefore operate in mixed mapping mode if necessary, combining the data source specified in the document and data from BPA Platform. These documents can then be delivered using many of the Output steps as attachments or file contents.

Run Microsoft Word (Merge) Tool Features

• Single or multiple documents
• New document when data changes or for each row
• Merge static or dynamic data into the document
• Mixed mode allows original mail merge data source and BPA Platform data to be used in the same document
• Produce in Word, XML, HTML, RTF or plain text document formats

Run Microsoft Word (Merge) Tool: Technical Summary

Working with other Tools

The other tools that the Run Microsoft Word (Merge) tool interacts directly with, whether by exposing information to it or consuming information from it, are listed below.

Consuming from Other Tools

Icon	Tool Name	Tool Category
	Database Query (ODBC)	Input and Data Connectors
	Database Query (OLEDB)	Input and Data Connectors
	Import Flat File	Input
	Convert XML to Recordset	Format
	Filter Data	General

Objects Consumed

Objects that the Run Microsoft Word (Merge) Step consumes that are exposed by other Steps are listed below.

• Recordset — Information structured into columns and rows
• Variables (Text) — Textual data is extracted from selected Variables

Exposing to Other Tools

Objects that the Run Microsoft Word (Merge) Step exposes that can be utilised by other Steps are listed below.

• Documents — One or multiple Word, XML, HTML, RTF or plain text documents
• Mailmerge — Displays the data provided by the original merge document data source.
• RecordSource — Displays the data provided by the previous Step in the Task.
• FormatData, XMLData, RTFData, HTMLData, and TextData — For completeness, these nodes display the Step output data that will be provided for use to the next Step in the Task; depending on the document output type selected.
• Step Properties — A number of properties for the Step are exposed in the Environment tab of the Task Browser dialog box

Dependencies

The products, technologies, protocols or systems that are required for the Run Microsoft Word (Merge) Step to work are listed below.

• MS Word — Microsoft Word version ’97 onwards.

Global Configuration

The Run Microsoft Word (Merge) tool does not require any global configuration before being used in a task.

Step Configuration

To add a new Run Microsoft Word (Merge) step to an existing task, you either:

• Click and drag the Run Microsoft Word (Merge) icon from the Task Browser to the task Design area.
• From the task’s Design tab, right-click on empty space and select Add > Format > Run Microsoft Word (Merge).

For a detailed description of how to create new tasks, refer to the product help.

About the General Tab

The General tab is used to enter the following details for the step:

• Name — Enter a meaningful name for the step
  TIP: If this task instance makes use of two or more Run Microsoft Word (Merge) steps, ensure the Name used is unique for each individual step.
• Description — If required, enter a description of this step
• Use a Recordset — Enable this parameter if recordset data from a previous task step is required to populate the merge document
  • Input Recordset — Contains all available recordsets from steps previously created in the task

About the Main Tab

The Main tab provides features for importing a Word document or template containing mail merge fields. The mail merge fields can then either remain mapped to their original document data source or BPA Platform data from the Task Browser dialog box can be dragged and dropped against specific fields.

The tab contains the following:

• Current Input — Provides the following options:
  • Import — Displays a standard file browser dialog box to enable a MS Word document or template file to be selected for importing into the BPA Platform database.
  • Export — Displays a standard file browser dialog box to enable the imported MS Word document or template file to be exported from the BPA Platform database to another location and saved as a file.
  • File Name — Regardless of the existing name of the file being imported, another name can be specified by manually entering it into the field.
    • Edit — Opens the document in the MS Word application to enable it to be edited. After editing the existing document version in the BPA Platform database is overwritten with the new version when it is saved.
  • Use password for data source — If checked then the Password field is activated.
  • Password — With the Use password for data source check box selected, the password required to access the original data source at task run time may be manually entered.
  • Test — Tests the original document mail merge data source connection using where applicable the password entered in the Password field. A pop-up dialog box displays the results of the test.
• Field mapping — This area is used to map data against mail merge field as required. It contains a table that displays the mail merge fields available in the selected document under the following column headings:
  • Mail Merge field — Displays the mail merge field name.
  • Data source column — Displays [Mapped Field] where the Tool recognises that the field is correctly mapped to the mail merge data source. The column row is blank where no mail merge field is mapped. BPA Platform data may be dragged and dropped from the Task Browser dialog box into a column row against any mapped or unmapped mail merge field.
• Output document generation — This area is used to select how and how many documents are generated when the Step is run by selecting one of the following options presented as radio buttons:
  • One document — Only one document is produced when the Step is run.
  • New document when column changes — This option is used in conjunction with the Column drop down list to generate a document when the selected column changes.
  • Column — When an input recordset has been previously selected in the General tab, the available columns are displayed in a drop down list for selection.
  • New document for each row — A new document is generated for each row in the recordset.

About the Document Properties Tab

The Document Properties tab allows users to specify the document properties, either manually or dynamically at Task run time by dragging and dropping objects into the appropriate field from the Task Browser dialog box.

The tab contains the following:

• Override existing document properties — If selected the document property fields may be edited.
• Document fields — The following document fields are displayed and may be edited if the Override existing document properties option has been selected:
  • Title
  • Subject
  • Author
  • Manager
  • Company
  • Category
  • Keywords
  • Comments
  • Hyperlink base
  • Template (not editable)

About the Advanced Tab

The Advanced tab allows users to customise the mail merge document’s SQL statement that Word uses to select the applicable data source, either manually or by dragging and dropping objects into the SQL from the Task Browser dialog box.

The tab contains the following:

• Use custom query string — If selected the SQL statement displayed in the Scripting text box may be edited.
• Scripting — Initially the document’s SQL statement is displayed.
  • If the Use custom query string option is selected, the SQL script may be manually edited. Alternatively, variables, properties, columns, formulas, functions and scripting elements may be dragged and dropped into the script from the Task Browser dialog box.
• Test query — Checks the script syntax and displays the result in a pop up dialog box.

About the Options Tab

The Options tab allows you to define how errors in this step are handled at task runtime.

If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Task).

If Import data source file is selected then the mail merge data source file is imported along with the document.