Merging PDFs Produces Blank Pages

So you're creating a number of individual PDFs, doing something with them, and then you want to merge them all into one, nice, long PDF at the end.

Something like this:
/* Merge! */
Local boolean &booMergeSuccess = &objMergeTool.mergePDFs(&arrFiles, &sNSMergedFileDestination | &sDirSep | "merged.pdf", &sError);

You can see this in Communication Generation for example.

But when you open the PDF only the first page has data, the rest are blank. What's going on?

I finally reduced this down to being something "wrong" with the individual PDFs that were being created, before they were merged. It wasn't the templates. It was something specific to the PDF files themselves.

Comparing them to an environment where (luckily) the merge did work showed that the PDFs that did merge had no security, while the ones that didn't merge did have security. File > Properties > Security.

xdo.cfg was the same in both environments. So where was this coming from?

I noticed that, in 8.53 at least, there are some new parameters for BI Publisher Report Definitions, namely PDF Security. The default for pdf-security was True.

I changed this to False and the merge worked. Finally.

This is overriding the global value at the report level. The global value is set at:
Reporting Tools > BI Publisher > Setup > Global Properties

tl;dr solution:

set propvalue = 'False'
where proplname = 'pdf-security';