Project Wizard: Print Transactional Jobs

The Print Transactional Jobs Project Wizard creates an OL Connect project that produces transactional print output.

This project extracts data from an XML file and uses that data to personalize a promotional letter. The output is a single file containing all the letters, in the format that was selected in the wizard (PDF, PCL or PostScript Level 3).

For an introduction to this Project Wizard, see Project Wizards overview video on the OL Learn website (start at 7:56) or on Youtube: Print Transactional Jobs.

Installing the project

Select File > New > Project Wizards > Print Transactional Jobs from the menu to start the wizard. See also: Transactional Print Jobs - Project Wizard.)

The wizard lets you select the folder in which you want the solution to be installed.
In the selected folder, the Project Wizard will create two subfolders: Configurations and Workspace.
The project's resource files are saved to the Configurations folder.
The Workspace folder is used for debugging or running the solution. It has an In folder that may be used to monitor incoming data and an Out folder to write output files to.

The selected folder's path is saved to a global variable in the Workflow configuration (see Workflow configuration).

That variable is used in the settings of the Capture Folder task.
The path is also copied to the Output Creation Presets which are used in the Create Output tasks.

Testing and running the project

Once the Project Wizard has finished the installation, the project is ready to be tested.

1. Locate the Workflow configuration in the Configurations\Workflow folder and open it in OL Connect Workflow.
2. Select the pr_tran_generate_output process.
3. Open the Debug ribbon and click Run.

The debugger always skips the first Input task. It needs a sample data file to work with. Normally you'd have to select a sample data file in Workflow. However, the project is pre-configured to use this file: Sample Data.xml (located in the project's Configurations\Data folder). The dates in the file are based on the date on which the project is installed.

A successful test run results in the following output in the Workspace\Out folder:

• One PDF containing all invoices, grouped by customer number.
• A subfolder containing PDFs that have one invoice each.
• A subfolder containing one PDF per customer. (Some customers have more than one invoice.)

Running the project

Having tested the project, you will be ready to send it to PlanetPress Workflow service; see Saving and sending a Workflow Configuration in Workflow's Online Help.
To test the project when it runs on the server, copy the Sample Data.xml file from the Configurations\Data folder to the Workspace\In folder. The same output should appear in the same folders as before.

Project details

The invoice template

The invoice is designed in the PR_TRAN Invoice template. It contains one Print section (see Print sections) and one Master Page (see Master Pages).

The Media (virtual stationery) is included in the output - it is printed on the page's background - , according to a setting in the Output Creation Presets.

Styling is done via style sheets (see Local formatting versus style sheets). The style rules are in the context_print_styles.css file. Note how they combine the HTML tag, ID and class of elements to select them. (See also: Selectors in Connect.)

Scripts

Scripts personalize content. Most of the scipts in the Information folder (on the Scripts pane) are made with the Text Script Wizard (see Using the Text Script Wizard).

Text that should be replaced by data is not only surrounded by @ (e.g. @date@) but also wrapped in a span (see Span). Each span has an ID, or a class if the same text occurs more than once, to use that as the selector of the script. The selector of the Invoice Total script, for instance, is a class: .inv-total.

Wrapping elements in a box (see Boxes) or in a semantic HTML element makes it easier to target them in a script or in a style sheet. Place the cursor in the element or select multiple elements. Then, on the menu, click Insert > Wrap in Box. You can now use the wrapper element as a script's or style's selector; see Using the Text Script Wizard and Styling and formatting.

The Text Script Wizard has an Expand button that opens the Script Editor, where you can edit the code or add your own. (For an introduction, see Writing your own scripts).
When you double-click on the Invoice Meta script, the Script Editor opens immediately. This script shows how to add data using the replace() method (see https://www.w3schools.com/jsref/jsref_replace.asp).
Note that this is a native JavaScript function. Functions that are only available in Designer scripts are listed in the Designer Script API.

Detail Table

The table in the invoice is a Detail Table (also called a Dynamic Table). It is filled and expanded dynamically by the scripts in the Products folder. To learn how to insert and edit such a table, see Detail Table.

The data mapping configuration

The template is merged with data from an XML file: Sample Data.xml. They are extracted from the XML file with a data mapping configuration, made with the DataMapper (see The DataMapper).
The data mapping configuration first extracts the common invoice fields, and then the transactional data, in a loop. For information about how to extract transactional data from an XML file, see: From an XML file.

Of course, this will only work with the appropriate data files. This data mapping configuration was designed for XML files that are structured like this the sample file: Sample Data.xml.
It is located in the Configurations\Data folder, but you will also see it when you open the data mapping configuration itself: select File > Open from the menu; browse to the Configurations\Resources folder and select the data mapping configuration: PR_TRAN Data XML.

Print settings

A Print context and Print sections can have their own print settings (see Print settings in the Print context and sections). The only print setting that the Print section has in this template, is the Duplex setting. (Right-click the section and select Sheet Configuration. See also: Sheet Configuration dialog.)

All other print settings are in the three Output Creation Presets. These are used by the Create Output tasks in the Workflow process.
To see the exact settings, open an Output Creation Preset in the Designer: first select File > Output Creation Presets from the menu; then click the Import button and browse to the Configurations\Resources\Output presets folder to select the preset.

The three Output Creation Presets all create PDF output, add the template's name to the PDF's meta data, and save the file in a certain directory. They all have the Print Virtual Stationery option enabled. So, what are the differences between these presets?

Groups and separation

The PR_TRAN PDF Full Job preset outputs only one file.
The PR_TRAN PDF per Invoice preset outputs one file per invoice, separating the output by document.
The PR_TRAN PDF per Customer preset outputs one file per customer, separating the output by document set.

The last output preset needs the invoices in the job to be grouped in document sets first (by customer number, in this case). That is what the Job Creation Preset does. This preset is used by the Create Job task in the Workflow configuration.

Variable file names

The Job Creation Preset does something else, too: it attaches extra information - meta data - to the documents and to the document sets. Both Output Creation Presets that produce multiple files use that information in the output file names.
They do that by using a variable in the file output mask field. The variable refers to certain meta data attached to items at a certain level (the document or document set, respectively). For more information see Print output variables.

Workflow configuration

Whenever new input data appears in the Workspace\In folder, the invoices are automatically merged with the data and printed to one file, one file per customer, and one file per invoice. That is, if the Workflow server is running with the Workflow configuration installed by the Project Wizard. (See Running the project.)

This project's Workflow configuration contains just one process. It is a typical OL Connect Print process (see Print processes with OL Connect tasks), with the difference that it does not have one Create Output task, but three. Each of them uses its own Output Creation Preset (see Print settings).

Note that the Branch tasks back up the job file and job information, so that the main branch continues with a job file that is unaffected by what happens to the job file inside the branch.

The Folder Capture task reads the project's Workspace path from a global variable. The value of that variable is set by the Project Wizard when it installs the project.

Customizing the project

A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project.

Do you intend to expand the project into a solution where Workflow runs on a different machine that also has a different regional setting? Then indicate the desired encoding in the Designer preferences (see Project Wizard deployment settings) before installing the project.

Input data

Here's how to adjust the project to input data that has a different structure or file type or comes from a different source.

1. Create a new data mapping configuration to match your input data. (See Creating a new data mapping configuration.)
2. When it's finished, send the new data mapping configuration to Workflow (see Sending files to Workflow).
3. Open the Workflow configuration: Print Promotional Data.
4. Double-click the Folder Capture Input task and change the file mask, or replace the task by the appropriate Input task. See: Input tasks in Workflow's Online Help.
5. Double-click the All In One task and select the new data mapping configuration on the Data Mapper tab.

Template

There are countless ways to customize the template to meet your exact requirements. You could, for example:

• Add text, images and other elements (see Content elements)
• Change the layout (see Styling and formatting)
• Change the Media
• Change the Master Pages
• Add sections (see Print context)

In order to further personalize the invoice, you need to open your data mapping configuration. (See: Personalizing content.)

Note that a Detail Table can't exist without a detail table in the data.

When the template is ready, send it to Workflow (see Sending files to Workflow).

Finally, in Workflow, adjust the process: double-click the Create Print Content task to open it, and select the new template. This is only necessary when the file name has changed.
Send the Workflow configuration to the server (see Saving and sending a Workflow Configuration in Workflow's Online Help).

Print output

To save the output to another type of file, or to send it to a printer, you must change the Output Creation Presets. Output Creation Presets are edited in the Designer.

1. Select File > Output Creation Presets from the menu.
2. Click the Import button and browse to the Configurations\Resources\Output presets folder to select the preset.
3. Click Next and adjust the Printer and Output options.

To separate the output differently, for example, by city in which the customers live, you need to change the Output Creation Preset as well as the Job Creation Preset.

1. Open the Job Creation Preset in the Designer: select File > Job Creation Presets from the menu.
2. Change the Grouping Options by selecting the relevant fields on the Job, Job Segment, and/or Document Set tab.
3. Adjust the Separation Options in the Output Creation Preset accordingly.