Merge External PDFs

(As of 3.2.001.01)

It is common for documents to have some fixed pages for things like Terms and Conditions and Standard Policies. As these types of documents are often legally binding, it is imperative that they remain exactly as authored. So, to ensure precise replication, DocOrigin uses "stitching" to support incorporating external PDF pages in your documents. Using stitching can reduce form development and form maintenance costs.

What do you do to achieve external PDF integration?

You have a normal DocOrigin form design file (.xatw) and an external PDF, let's say a Ts&Cs.pdf. Your task is to integrate those two source materials into a single output PDF.

To define a place for the external page in the XATW, add a new Page to your form design (often called a "placeholder" page) and add the tag "Underlay". The value is the fully pathed filename of the external PDF with no extension.

This will stitch all pages from your external PDF. You can use specific pages of your external document by appending ;Pages=n. n may be in form of a single page number, comma-separated list of individual numbers, dash-separated range or a mix of all of them, or an asterisk to indicate all pages.

So in our example case, it could be something like: $$F/Ts&Cs;Pages=1-3

Wherever the placeholder page ends up in the output document is where the identified page(s) from the identified external PDF are integrated. The "integration" is such that the external page "underlays" the Merge-generated placeholder page, which might not be blank. E.g. it would be possible to "stamp" a policy number on the integrated external pages or put your own page numbers over Ts&Cs's ones overlaying them with say white rectangle and your own page numbers.

If you are so inclined, you could set these Underlay tag values dynamically, with script. Indeed you can insertPage, or clone placeholder pages dynamically as well.

For example:

this.setTag("Underlay", "$U/Stitch/PolicyRider23");

That is all you need to make it work.

What Merge does

Merge will render the document, including the placeholder pages.

Behind the scenes, it will create a temporary trivial control file which identifies the physical page number of the placeholder page that Merge generated plus the name of the external PDF that is providing the page to place underneath the Merge-generated page. And of course the page number from that external PDF. Example:

9;"C:/DocOrigin/User/Stitch/CaliforniaRegulations.pdf";1
10;"C:/DocOrigin/User/Stitch/PurchaseTs&Cs.pdf";5

Note that the page numbers are always physical page numbers, not necessarily the same as the page number printed on the page.

That control file is passed to a supplied but overridable script named Default-DocOriginOverlay.wjs. The supplied script uses the aforementioned third-party technology to do the PDF file integration such that a single integrated PDF results.

The DocOriginOverlay.wjs script

The purpose of this script is to integrate traditional Merge and PDF overlaying tool.

The Default version of this script resides as $E/Default-DocOriginOverlay.wjs. You may override it in $O/DocOriginOverlay.wjs.

The script then goes on to log certain information that may be of interest and it uses the PDFBox facilities to affect the integration of pages per the control file.

The result is written over top of the original Merge-produced PDF document such that Merge is unaware of any changes. Merge carries on as it always has in terms of email production, document counting, etc.

Multiple documents per Merge run

The processing handles multiple documents per Merge run. That is, in either case, PDFCombineDocuments = Yes or No.