MailMergeSettings

Inheritance: java.lang.Object

All Implemented Interfaces: java.lang.Cloneable

public class MailMergeSettings implements Cloneable

Specifies all of the mail merge information for a document.

To learn more, visit the Mail Merge and Reporting documentation article.

Remarks:

You can use this object to specify a mail merge data source for a document and this information (along with the available data fields) will appear in Microsoft Word when the user opens this document. Or you can use this object to query mail merge settings that the user has specified in Microsoft Word for this document.

You do not normally need to create objects of this class directly because Mail merge settings of a document are always available via the Document.getMailMergeSettings() / Document.setMailMergeSettings(com.aspose.words.MailMergeSettings) property.

To detect whether this document is a mail merge main document, check the value of the getMainDocumentType() / setMainDocumentType(int) property.

To remove mail merge settings and data source information from a document you can use the clear() method. Aspose.Words will not write mail merge settings to a document if the getMainDocumentType() / setMainDocumentType(int) property is set to MailMergeMainDocumentType.NOT_A_MERGE_DOCUMENT or the getDataType() / setDataType(int) property is set to MailMergeDataType.NONE.

The best way to learn how to use the properties of this object is to create a document with a desired data source manually in Microsoft Word and then open that document using Aspose.Words and examine the properties of the Document.getMailMergeSettings() / Document.setMailMergeSettings(com.aspose.words.MailMergeSettings) and getOdso() / setOdso(com.aspose.words.Odso) objects. This is a good approach to take if you want to learn how to programmatically configure a data source, for example.

Aspose.Words preserves mail merge information when loading, saving and converting documents between different formats, but does not use this information when performing its own mail merge using the MailMerge object.

Methods

Method	Description
clear()	Clears the mail merge settings in such a way that when the document is saved, no mail merge settings will be saved and it will become a normal document.
deepClone()	Returns a deep clone of this object.
getActiveRecord()	Specifies the one-based index of the record from the data source which shall be displayed in Microsoft Word.
getAddressFieldName()	Specifies the column within the data source that contains e-mail addresses.
getCheckErrors()	Specifies the type of error reporting which shall be conducted by Microsoft Word when performing a mail merge.
getConnectString()	Specifies the connection string used to connect to an external data source.
getDataSource()	Specifies the path to the mail-merge data source.
getDataType()	Specifies the type of the mail-merge data source and the method of data access.
getDestination()	Specifies how Microsoft Word will output the results of a mail merge.
getDoNotSupressBlankLines()	Specifies how an application performing the mail merge shall handle blank lines in the merged documents resulting from the mail merge.
getHeaderSource()	Specifies the path to the mail-merge header source.
getLinkToQuery()	Not sure about this one.
getMailAsAttachment()	Specifies that the documents produced during a mail merge operation should be emailed as an attachment rather than the body of the actual e-mail.
getMailSubject()	Specifies the text which shall appear in the subject line of the e-mails or faxes produced during mail merge.
getMainDocumentType()	Specifies the mail-merge main document type.
getOdso()	Gets the object that specifies the Office Data Source Object (ODSO) settings.
getQuery()	Contains the Structured Query Language string that shall be run against the specified external data source to return the set of records which shall be imported into the document when the mail merge operation is performed.
getViewMergedData()	Specifies that Microsoft Word shall display the data from the specified external data source where merge fields have been inserted (e.g.
setActiveRecord(int value)	Specifies the one-based index of the record from the data source which shall be displayed in Microsoft Word.
setAddressFieldName(String value)	Specifies the column within the data source that contains e-mail addresses.
setCheckErrors(int value)	Specifies the type of error reporting which shall be conducted by Microsoft Word when performing a mail merge.
setConnectString(String value)	Specifies the connection string used to connect to an external data source.
setDataSource(String value)	Specifies the path to the mail-merge data source.
setDataType(int value)	Specifies the type of the mail-merge data source and the method of data access.
setDestination(int value)	Specifies how Microsoft Word will output the results of a mail merge.
setDoNotSupressBlankLines(boolean value)	Specifies how an application performing the mail merge shall handle blank lines in the merged documents resulting from the mail merge.
setHeaderSource(String value)	Specifies the path to the mail-merge header source.
setLinkToQuery(boolean value)	Not sure about this one.
setMailAsAttachment(boolean value)	Specifies that the documents produced during a mail merge operation should be emailed as an attachment rather than the body of the actual e-mail.
setMailSubject(String value)	Specifies the text which shall appear in the subject line of the e-mails or faxes produced during mail merge.
setMainDocumentType(int value)	Specifies the mail-merge main document type.
setOdso(Odso value)	Sets the object that specifies the Office Data Source Object (ODSO) settings.
setQuery(String value)	Contains the Structured Query Language string that shall be run against the specified external data source to return the set of records which shall be imported into the document when the mail merge operation is performed.
setViewMergedData(boolean value)	Specifies that Microsoft Word shall display the data from the specified external data source where merge fields have been inserted (e.g.

clear()

public void clear()

Clears the mail merge settings in such a way that when the document is saved, no mail merge settings will be saved and it will become a normal document.

deepClone()

public MailMergeSettings deepClone()

Returns a deep clone of this object.

Returns: MailMergeSettings

getActiveRecord()

public int getActiveRecord()

Specifies the one-based index of the record from the data source which shall be displayed in Microsoft Word. The default value is 1.

Returns: int - The corresponding int value.

getAddressFieldName()

public String getAddressFieldName()

Specifies the column within the data source that contains e-mail addresses. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getCheckErrors()

public int getCheckErrors()

Specifies the type of error reporting which shall be conducted by Microsoft Word when performing a mail merge. The default value is MailMergeCheckErrors.DEFAULT.

Returns: int - The corresponding int value. The returned value is one of MailMergeCheckErrors constants.

getConnectString()

public String getConnectString()

Specifies the connection string used to connect to an external data source. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getDataSource()

public String getDataSource()

Specifies the path to the mail-merge data source. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getDataType()

public int getDataType()

Specifies the type of the mail-merge data source and the method of data access. The default value is MailMergeDataType.DEFAULT.

Returns: int - The corresponding int value. The returned value is one of MailMergeDataType constants.

getDestination()

public int getDestination()

Specifies how Microsoft Word will output the results of a mail merge. The default value is MailMergeDestination.DEFAULT.

Returns: int - The corresponding int value. The returned value is one of MailMergeDestination constants.

getDoNotSupressBlankLines()

public boolean getDoNotSupressBlankLines()

Specifies how an application performing the mail merge shall handle blank lines in the merged documents resulting from the mail merge. The default value is false .

Returns: boolean - The corresponding boolean value.

getHeaderSource()

public String getHeaderSource()

Specifies the path to the mail-merge header source. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getLinkToQuery()

public boolean getLinkToQuery()

Not sure about this one. The Microsoft Word Automation Reference suggests that this specifies that the query is executed every time the document is opened in Microsoft Word. But the OOXML specification suggests that this specifies that the query contains a reference to an external query file which contains the actual query. The default value is false .

Returns: boolean - The corresponding boolean value.

getMailAsAttachment()

public boolean getMailAsAttachment()

Specifies that the documents produced during a mail merge operation should be emailed as an attachment rather than the body of the actual e-mail. The default value is false .

Returns: boolean - The corresponding boolean value.

getMailSubject()

public String getMailSubject()

Specifies the text which shall appear in the subject line of the e-mails or faxes produced during mail merge. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getMainDocumentType()

public int getMainDocumentType()

Specifies the mail-merge main document type. The default value is MailMergeMainDocumentType.DEFAULT.

Remarks:

The main document is the document that contains information that is the same for each version of the merged document.

Returns: int - The corresponding int value. The returned value is one of MailMergeMainDocumentType constants.

getOdso()

public Odso getOdso()

Gets the object that specifies the Office Data Source Object (ODSO) settings.

Remarks:

This object is never null .

Returns: Odso - The object that specifies the Office Data Source Object (ODSO) settings.

getQuery()

public String getQuery()

Contains the Structured Query Language string that shall be run against the specified external data source to return the set of records which shall be imported into the document when the mail merge operation is performed. The default value is an empty string.

Returns: java.lang.String - The corresponding java.lang.String value.

getViewMergedData()

public boolean getViewMergedData()

Specifies that Microsoft Word shall display the data from the specified external data source where merge fields have been inserted (e.g. preview merged data). The default value is false .

Returns: boolean - The corresponding boolean value.

setActiveRecord(int value)

public void setActiveRecord(int value)

Specifies the one-based index of the record from the data source which shall be displayed in Microsoft Word. The default value is 1.

Parameters:

Parameter	Type	Description
value	int	The corresponding int value.

setAddressFieldName(String value)

public void setAddressFieldName(String value)

Specifies the column within the data source that contains e-mail addresses. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setCheckErrors(int value)

public void setCheckErrors(int value)

Specifies the type of error reporting which shall be conducted by Microsoft Word when performing a mail merge. The default value is MailMergeCheckErrors.DEFAULT.

Parameters:

Parameter	Type	Description
value	int	The corresponding int value. The value must be one of MailMergeCheckErrors constants.

setConnectString(String value)

public void setConnectString(String value)

Specifies the connection string used to connect to an external data source. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setDataSource(String value)

public void setDataSource(String value)

Specifies the path to the mail-merge data source. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setDataType(int value)

public void setDataType(int value)

Specifies the type of the mail-merge data source and the method of data access. The default value is MailMergeDataType.DEFAULT.

Parameters:

Parameter	Type	Description
value	int	The corresponding int value. The value must be one of MailMergeDataType constants.

setDestination(int value)

public void setDestination(int value)

Specifies how Microsoft Word will output the results of a mail merge. The default value is MailMergeDestination.DEFAULT.

Parameters:

Parameter	Type	Description
value	int	The corresponding int value. The value must be one of MailMergeDestination constants.

setDoNotSupressBlankLines(boolean value)

public void setDoNotSupressBlankLines(boolean value)

Specifies how an application performing the mail merge shall handle blank lines in the merged documents resulting from the mail merge. The default value is false .

Parameters:

Parameter	Type	Description
value	boolean	The corresponding boolean value.

setHeaderSource(String value)

public void setHeaderSource(String value)

Specifies the path to the mail-merge header source. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setLinkToQuery(boolean value)

public void setLinkToQuery(boolean value)

Not sure about this one. The Microsoft Word Automation Reference suggests that this specifies that the query is executed every time the document is opened in Microsoft Word. But the OOXML specification suggests that this specifies that the query contains a reference to an external query file which contains the actual query. The default value is false .

Parameters:

Parameter	Type	Description
value	boolean	The corresponding boolean value.

setMailAsAttachment(boolean value)

public void setMailAsAttachment(boolean value)

Specifies that the documents produced during a mail merge operation should be emailed as an attachment rather than the body of the actual e-mail. The default value is false .

Parameters:

Parameter	Type	Description
value	boolean	The corresponding boolean value.

setMailSubject(String value)

public void setMailSubject(String value)

Specifies the text which shall appear in the subject line of the e-mails or faxes produced during mail merge. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setMainDocumentType(int value)

public void setMainDocumentType(int value)

Specifies the mail-merge main document type. The default value is MailMergeMainDocumentType.DEFAULT.

Remarks:

The main document is the document that contains information that is the same for each version of the merged document.

Parameters:

Parameter	Type	Description
value	int	The corresponding int value. The value must be one of MailMergeMainDocumentType constants.

setOdso(Odso value)

public void setOdso(Odso value)

Sets the object that specifies the Office Data Source Object (ODSO) settings.

Remarks:

This object is never null .

Parameters:

Parameter	Type	Description
value	Odso	The object that specifies the Office Data Source Object (ODSO) settings.

setQuery(String value)

public void setQuery(String value)

Contains the Structured Query Language string that shall be run against the specified external data source to return the set of records which shall be imported into the document when the mail merge operation is performed. The default value is an empty string.

Parameters:

Parameter	Type	Description
value	java.lang.String	The corresponding java.lang.String value.

setViewMergedData(boolean value)

public void setViewMergedData(boolean value)

Specifies that Microsoft Word shall display the data from the specified external data source where merge fields have been inserted (e.g. preview merged data). The default value is false .

Parameters:

Parameter	Type	Description
value	boolean	The corresponding boolean value.