Multiple Outputs

In a single run of DocOrigin Merge, one can produce multiple outputs. There is no restriction to creating only a single file. The variety that is possible here seems quite endless.

One Output Per Run

Let's take a simple case of producing PDF output. The -config option you give to Merge will reference a PDF configuration file. Quite often, so often in fact that it is the default if no -config option is provided, that configuration file will be Default-PDF.prt. Of course, you may have customizations, typically with additional fonts, and you might say -config MyCustom-PDF.prt. Whatever the case, you do nominate, explicitly or implicitly, an output configuration file (a .prt file).

If your data stream contains only one document's worth of data, then yes you will get only one PDF file out. If your data stream contains the data for many documents, typically each housed between <Document>, </Document> bookends, then, for the Default-PDF.prt output configuration, you will still get only one output PDF!

Why is that? Well, well, ... we agonized over this long ago decision - the Default-PDF.prt stipulates

<CombineDocuments>Yes</CombineDocuments> 

That means that the output for all of the documents will be combined into a single, very archive-like, PDF. That's great, if that's what you want, and you very often do. You might ship that whole archive off to your print shop, or indeed use it as an archive. It is very easy to use the PDFExtract tool to extract any documents of particular interest.

One Output Per Document

But what if you want an individual PDF for each document's worth of data? Well, specify an overriding:

-PDFCombineDocuments No

in your invocation of Merge, or if you like, specify <CombineDocuments>No</CombineDocuments> in your custom PDF .prt file.

Now we've got a bunch of files, one per document, coming out in a single run of Merge. That can be, and often is, quite desirable. It's particularly desirable if you want to distribute those outputs in different ways! You might use _sendmail() to email them, or you might direct them to individual web folders based on client account information in the data stream. Good stuff.

Different Output Formats

Now that we're producing a different output (file?) for each document, who says they should all be the same format, PDF in our example? Surely, I don't have to split up my data streams into one for PDF, one for PCL, one for HTML, one for PS. Of course not. That would be crazy. We expect that you will want to cater to your end users' communication preferences. Some will want paper, some email, and some web postings, either in PDF or HTML.

A simple case is that of PDF + paper (let's say PCL, as an example). To accomplish that in one run of DocOrigin Merge, you simply specify a semi-colon-separated list of output configuration files as your -config  option. For example:

-config Default-PDF.prt;Default-LJ4Color.prt 

Now Merge is fully prepared to emit some outputs in PDF and some in PCL. You might look at the document's data for the account's communication preference and choose to create PDF for one document, but PCL for another. How do you do that?

The secret sauce is in the Ready-To-Print event. Here's something I coded recently in my SE Support role.

_logf("Print? %s", _cache.Print);
_logf(" Pdf? %s", _cache.Pdf);
_logf("Email? %s", _cache.Email);
_printer.setActive(false, "LJ4");
if (_cache.Print == "Yes") {
	_printer.setActive(true, "LJ4");
	_printer.setOutputFile("$U/Output/\[NCLI\]/EXT_\[NCLI\].pcl", "LJ4");
}
_printer.setActive(false, "PDF");
if (_cache.Pdf == "Yes") {
	_printer.setActive(true, "PDF");
	_printer.setOutputFile("$U/Output/\[NCLI\]/EXT_\[NCLI\].pdf", "PDF");
}
if (_cache.Email == "Yes") {
	_printer.setActive(true, "PDF");
	_printer.setOutputFile("$U/Output/\[NCLI\]/EXT_\[NCLI\].pdf", "PDF");
}

Naturally, I had included both an LJ4 and a PDF output configuration in my semi-colon separated -config option.

We needn't worry about how the _cache variables were set. There could be lots of ways, and one might well refer directly to a DOM element like:

_document.header.commPref._value 

or whatever your data stream holds. Naturally, you don't have to log out the values either, at least not after you have finished debugging!

Output drivers can be active or inactive. If they are active, output will be produced. If they are not active, output will not be produced. So the point of this code is to set one of these "drivers" active and the other "inactive".

Line 4, initially says that we do not want PCL output for this document, but lines 5 and 6 say that if "print to paper" is desired, we will make it active. Pretty simple.

Line 7 defines where I want the output to go. Naturally, as we are producing multiple outputs per run, we can hardly specify a single hard-coded name! So really, what line 7 does is to set an output name template. It references field names in square brackets causing dynamic text substitution to happen. It can reference a whole pile of %x type date/time elements too. Look inside any .prt file for a list or see: File Naming Conventions. And then there's script. You are in a scripting language. If for some astonishing reason the above flexibility isn't enough, you can certainly script your way to the perfect output file name.

Note that whether PDF is wanted or email is wanted, I make the PDF driver active. After all, I intend to email a PDF. It might be that if email is desired that I would direct the output to some staging area, then email it, then delete it. Whereas if email wasn't desired, I might direct the output to some client web folder.

I think you can see that this bit of script is not rocket science. You are empowered to create outputs of different formats in a single run.

Multiple Outputs Per Document

The above shows that you can create a different format output for each document's data. But more than that you can create multiple outputs (of the same or different formats) for each single document.

You'll note in my code sample above that making PDF active does not mean that LJ4 must be inactive. Not at all. It's quite fine to have multiple drivers active and have Merge emit multiple outputs for whichever documents deserve to have them.

Multiple Outputs Per Document 2

So far, the notion of having multiple outputs per document has been for the purpose of creating different format outputs. But what if I want to produce two PDFs say? Well, Merge can do that, or three, or ...

Try a -config  statement like:

-config Default-PDF.prt;Default-PDF.prt 

Yes, that's right, I used the same .prt file twice. What happens then is that Merge let's you refer to the first one as, in this case, PDF, and the second one as PDF2, etcetera if there were more than two of the same type.

Now you could produce a PDF to be sent to the account's folder, and another to be sent to the accountant's folder. Of course, you could do file copies too! A much more common usage is to have one .prt have <CombineDocuments>Yes</CombineDocuments> and the other to have <CombineDocuments>No</CombineDocuments>. That way you can produce the combined archive PDF and individual mailable, postable PDFs at the same time. Now that's handy!

Of course this technique expands to multiple format outputs as well. Endless possibilities.

Usage

Most of the usage for multiple outputs is pretty obvious but perhaps a couple others are worth mentioning explicitly.

You may very well want to switch between output destinations based on page count. That information is definitely available to you in the Ready-to-Print event and so it is quite easy to direct small number of pages documents to one paper handling destination and larger number of pages documents to a different paper handling destination. Different paper folding devices and envelope stuffing machines can then be applied. Savings are very possible in terms of postage and envelope costs.

The DocumentSort filter can be run seamlessly on the batch of data, sorting on any number of keys. This operates very quickly and then... you can easily break up your outputs based on a change of "region" or "branch" or some such thing. The "western region" can get all of its documents in one combined PDF while the "southeast" and "mid-west" get their own set of documents. Of course you could be creating an omnibus, all regions, output at the same time. It may make sense to sort on zip-code and achieve postage rate savings that way.

It's so easy to overlook. A form design has a Main Section but it can also have a Summary Section. You can design panes for that Summary Section as you see fit. Data that you collect throughout a batch can then be presented as a Summary Section report. And of course, that Summary Section output might have a different destination than what applied for the Main Section.

It might be that certain documents contain data values that are outside the norm or have larger-than-usual dollar amounts. Perhaps you would direct those to a 'special attention' output location, and/or to a watched folder that participated in a review workflow operation.

Output Configuration Names

Also known as "Printer Names".

In any .prt file there is a <Printer> section. They look like:

<Printer Name="XXX" Type="XXX"> 

Typically, those XXXs are the same, though they needn't be. When I coded

_printer.setActive(false, "LJ4"); 

the LJ4 was referring to a Name="LJ4" setting in one of the referenced .prt files. Naturally, if you reference the same output configuration file multiple times, then that same name will occur multiple times. As said before, when that occurs, Merge will automatically, name the second occurrence as XXX2, the third XXX3, and so on.