GemBox Support Forum

IF conditions in merge fields and catalog-style mail merges

Hi, I’m new to GemBox and I’m trying to replicate some existing mail merges using GemBox.Document and I’ve run into some problems that I can’t see how to solve.
I’ve looked at the forum etc but not found anything that seems relevant.

These mail merges are all using “flat” data files because that’s what Word can accept.
I really don’t want to re-write the data file creation if I can avoid it, and there’s a large number of existing customized template docuemnts outside of my control, so I’m looking for ways to make GemBox accept the current flat file data format and template and do a mail merge that is as close as possible to what Word would do.

Firstly: Conditional merge fields.

A couple of examples:

  1. There’s a need to skip “blank” records, i.e. records where a certain marker field is blank. It’s currently done like this:

{ SKIPIF MERGEFIELD ReportName = “” }

  1. Conditional contents.
    For example, if the “Notes” merge field is blank, don’t add the nicely formatted “Notes” heading.

{ IF MERGEFIELD Notes = “” “” "

Please find the case notes below.


This is just a very simple example.
Some of the more complicated ones involves whole sections being added / omitted and in some cases several levels of nested IFs.

Secondly: Catalog mail merges.

A number of the mail merges are using the Word “catalog” setting (multiple data rows on one page).
A simple example would be a report showing (say) the day’s total takings in different departments.
The data file would essentially be lines containing text / value pairs, but there’d be an extra “header” fields and control field to indicate if a line is a “sum”.
Something like this:

Data file contents:
“Dept 1” “Toys” “54.66” “”
“” “Food” “120.00” “”
“” “Keys” “100.00” “”
“” “” “274.66” “SUM”
“Dept 2” “Toys” “20.00” “”
“” “Food” “100.50” “”
“” “Keys” “15.00” “”
“” “” “135.50” “SUM”

The template would use IF conditions for layout of header and totals - e.g. { IF MERGEFIELD SUM (…) and produce something like this:

Dept 1 daily takings

Toys 54.66
Food 120.00
Keys 100.00



Dept 2 daily takings

Toys 20.66
Food 100.50
Keys 15.00




I’d appreciate some ideas, please.

Ok, answering one of my own questions here - always the best way :wink:

The conditional merge fields are working fine. The problem I had with IF was due to the way I loaded the old data file into a DataTable object. I expected the “” values in the file to be preserved, but they were converted to NULL.

And the next one: Catalog merges
It is possible to make an existing data file merge correctly as a Catalog merge by loading it into a DataTable and creating a a DataSet with a second “top level” table. And then create one record in the “top level” table and relate all the real records to that one record.

It does require a change in the template document, but it’s a simple one.
At the top of the document you need two RangeStart merge fields and at the bottom two corresponding RangeEnd merge fields. These can be inserted by the program that execute the mail merge.
Anything in between those two sets of merge fields will behave as a Catalog merge.

Hi Karin,

1.) Currently SKIPIF is not supported, you can find a list of all supported fields at the end of this help page:

Before investigating further this requirement, I wanted to check with you if you could use a quick workaround to this and just filter out the records in your data source?

2.) IF fields are supported, but it can contain only inline-level elements, not block-level elements. Also, the resulting text will always be formatted based on the IF field’s formatting.
Note that in the future we plan to address these limitations and provide better support for IF fields updating.

Last regarding the Catalog merge, is it possible for you to send us a small Visual Studio project that demonstrates your use case?
I would investigate your input document and the provided sample data (a small DataTable object).

Also, can you please send us the desired output document, the result that you would like to get from merging that provided sample data?
You can create such a document manually with Microsoft Word, I would just like to check exactly how the result should look like.


Thanks, Mario
I’ve come a long way since I asked the questions :slight_smile:

  1. SKIPIF: thanks for making clear that it won’t work. I can work around it by removing the record and the SKIPIF merge field.

  2. From the examples I have run it seems that most of the IFs in our existing templates works well enough. I’ll keep an eye out for large blocks, but I suspect they’re not block-level in the GemBox sense and so will be fine.
    If I hit something I can’t handle I’ll come back and ask a separate question.

  3. Catalog
    The use case is this:
    I have a database that in some cases stores tab-separated .csv data file (flat data file) and header source (the merge field names) and a .doc template.
    They are the audit trail of the documents that were sent out so they need to be accessible. For example invoices.
    Our programs allow each invoice in an invoice run to be opened separately, and that means mail merging with a data range.

The documents are stored this way because it saved space. One copy of the template file + all the merge data takes up less space than storing a copy of every finished .doc file separately.
(but that really doesn’t matter. They are there, and I have to deal with them)

Some of these stored documents are Catalog merges.

Note: this is the (very old) .doc mail merge that has existed “forever”. I’ve seen it used with Word 97 but it is older than that.

If you open the Mail Merge Helper dialog you see this:

In the screen shot you can see that the setting for Main document Merge Type says “Catalog”. That changes the behaviour so that all records are listed on the same page (only breaking page when it runs out of space).
The other main choice is “Merge Letter”, and that setting would give you a page per record in the data line.

The result of a Catalog merge would be the same as you’d get in GemBox if you had a DataSet data source with a header and a details table, with one (dummy) header record and our (flat) data file as the details table - all detail records related to the one header record.

So that’s what I’ve done. Read in the existing data file (tweak it a bit to add the merge field names as the first record), set up a DataSet as described, read in the template .doc, and – to make it work - programmatically add RangeStart: and RangeEnd: fields to the template document structure (first section and last section).

And it works!
(luckily I know precisely which templates are meant to be catalog and which are letter)

It would be nice if I did not have to tweak the data and add the fields. But at least I have a method that’ll work.

I can’t send a Visual Studio project. I do not work in C# natively, but in another language that has .Net support.

I can give you some idea of the contents of the files and the result but I’ll put them in separate replies. Apparently I’m a “new user” and not allowed to attach more than one image :slight_smile:


Template document contents:

A bit of a sample data file:

And (a page of) the result:

There is a header on page 1, but I thought I would show you the totals instead :slight_smile:

The data is deliberately rubbish, it’s from a test setup.


Can you please send us the template document, sample data, and the resulting document?
I would like to investigate them a bit and use them for testing purposes.


I’ll have to sanitize the data a bit first, I’m afraid.

Is there a less public email address I can send them to?