The Mail Merge control allows Workflow data to be written out into a Microsoft Word document based on the structure of a provided template.
It can be configured so that it is either displayed to the agent as a simple button, or completely hidden.
This control is part of the Advanced control pack, and will only be available if you have the appropriate licence part.
How To
Add the Mail Merge control to the Page that the merge should be triggered on. The control's options and style can be configured in the
Options and
Styling tabs of the Field Properties, and
Validation and
Formatting can be applied if desired.
Once the Mail Merge control has been configured as desired, clicking the Advanced Options tab will allow the configuration of the merge:
The fields can either be populated with free-text, or they can be linked to Workflow Fields. If linked to a Workflow Field, then they will take the value held in the specified Field at the time the button is clicked.
|
Option
|
Description
|
|
Template Folder
|
The path to the folder containing the template document. It must be a location that the Scripting website can access, and must not require any additional actions (such as a login dialogue) to be reached.
|
|
Template Filename
|
The filename of the document to be used as a template. It must be a Microsoft Word document that uses the Open XML standard (.docx)
|
|
Output Folder
|
The path to the folder that the output file will be placed in. It must be a location that the Scripting website can access, and must not require any additional actions (such as a login dialogue) to be reached.
|
|
Output Filename
|
The filename that will be used as for the output file. If the specified filename already exists in the folder, then the generated filename will be altered to include (1) etc. in the normal manner of duplicate filenames within Windows.
|
|
Placeholder Style
|
The special characters that are used to indicate the placeholder to be replaced, as selected from a list of options.
|
The template document can be created and formatted as desired, and any places where Workflow data is to be inserted is indicated by having the relevant Field's name between a pair of special characters that indicate they contain a placeholder.
Notes
When the Mail Merge is triggered during a Workflow run, the Mail Merge control's value is set to the generated file's name and path once the file has been created. This can then be used for verification purposes (by checking the field has a value), used as the path and filename for an
Email attachment, or for any other desired purpose within Scripting.
Workflow or System Variables cannot be used within the merge, so if it is desired to bring data from a Variable into a merge then its value must be first moved into a Field which is then used instead.
When specifying the names of Fields within the template document, please note that the Field names are matched via a case-insensitive method unlike elsewhere within Scripting. As such, it's best to ensure that all Field names are truly distinct even when case-insensitive.
The output document will always be generated using the Microsoft Open XML (.docx) standard, even if a different file extension is specified.
The template document must not be open anywhere at the time a merge is attempted, or else the attempt will be immediately failed due to the template document being in-use.
If specifying a dynamic output file path or filename based on Workflow data, ensure that no
illegal characters are included. Doing so will cause the filename to be truncate to the section of the name prior to an illegal character being encountered.
As with other button-type controls, it is possible to require a Page pass
validation before the button will activate. This prevents the mail merge from being generated before all requisite details have been collected.
As with other button-type controls, upon activation the button will then be disabled until the action has completed.
As with other button-type controls, it is possible to trigger this by JavaScript or
Update Links. Please see the
.click() article for more information and an example regarding using JavaScript.
