Sample Project: Print Transactional Jobs

The Print Transactional Jobs Sample Project creates an OL Connect project that produces transactional print output. It prints invoices to:

  • A single PDF for the entire job (in which the invoices are grouped per customer).

  • One PDF per customer.

  • One PDF per invoice.

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

Installing the project

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

Note: In order to use the project, OL Connect Server and OL Connect Workflow must be installed on the local machine.

The wizard lets you select the folder in which you want the solution to be installed. Since Sample Projects are versioned (see Versioned projects), the software suggests to store it in the OL Connect folder that is located in your Documents folder. By default, all versioned project have their own folder under Documents/Connect.

In the selected folder, the Sample Project 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.

Finally, enter the username and password that will allow the software to access the Connect Server.

Testing and running the project

Once the Sample Project 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 OL 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).

Tip: Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.

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 String replace).
Note that this is a native JavaScript function. Functions that are only available in Designer scripts are listed in the Designer Script API.

Dynamic Table

The table in the invoice is 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 Dynamic Table.

Note that this table does not use one of the default table styles, and that the style sheet with the default table styles is not present in the template. To add that style sheet to the template, insert a table using the Dynamic Table wizard.

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: Extracting transactional data.

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 Sample Project. (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 Sample Project 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 Sample Project 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 .)

  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.

Note: If the input data is JSON, you don't need a data mapping configuration: JSON data can be used in a template as is. See: Adding JSON sample data.
However, if you want the data to be saved in the Connect database, let the XML/JSON Conversion plugin convert the JSON to XML and create an XML data mapping configuration to extract the data.

Template

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

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

Tip: The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both.

Note that a Dynamic 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.

Tip: The Execute Data Mapping task, Create Job and Create Output task may be replaced with the All In One task, with its Output Creation set to None. Using the All In One instead of the separate tasks makes the process a little faster.