The Mail Merge Control allows Field data to be written out into a Microsoft Word or Adobe PDF document based on the structure of a provided template file.
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 Intermediate Control pack, and will only be available if your System has the appropriate licence.
Add a Mail Merge to the Page. The options and style can be configured in the
Options tab and
Styling tab of the Field Properties, and
Validation can be applied if desired.
Mail Merge Fields can be styled in a Stylesheet by referencing the control-mail-merge class.
Once the Mail Merge has been configured as desired, clicking the Advanced Options tab will allow the configuration of the merge:
The options can either be populated with free-text, or they can be linked to Fields or Variables. If linked to a Field or Variable, then it will take their value at the time the button is triggered.
|
Option
|
Description
|
|
Template Folder
|
The path to the folder containing the template document. It must be a location that the Intelligent Agent webserver 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 Intelligent Agent webserver 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. Output file extension should be either .docx or .pdf, and the chosen extension controls the output file format.
|
|
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.
When the Mail Merge is triggered during a Workflow, the Field'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 Intelligent Agent.
System and Workflow 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 Intelligent Agent. 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 either the Microsoft Open XML (.docx) standard, or Adobe Portable Document Format (.pdf) standard.
The template document must not be open by any other process 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 Fields, it is possible to require that a Page passes
Validation before the button will activate. This prevents the merged document from being generated before all requisite details have been collected.
As with other button-type Fields, upon activation the button will then be temporarily disabled until the action has completed.
As with other button-type Fields, 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.
