Sample Project: Print Promotional Jobs

The Print Promotional Jobs Sample Project creates a simple, yet complete OL Connect project that produces promotional print output.

The 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 Sample Project, see Sample Projects overview video on the OL Learn website (start at 0:52) or on YouTube: Print Promotional Jobs.

Installing the project

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

Alternatively, open the Welcome screen, click New at the left, then Project at the right and select the project type.

Tip: Click the Home icon Home icon at the top right to reopen the Welcome screen.

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 and Send to Folder tasks.

Next, you have to select the desired output type: PDF, PCL or PostScript Level 3. Each of the output types is available in two variants. The 'Stationery' variants will include the virtual stationery (stored in the OL Connect template) in the output. This is a setting in the Output Preset (see Print settings).

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_prom_generate_output process.

  3. Open the Debug ribbon and click Run.

In Debug mode, the first Input task is skipped and the process is executed using a sample data file. This project is pre-configured to use the file: Sample Data.xml.

A successful test run results in a subfolder in the Workspace\Out folder, named after the current month and year. The Print output is written to that subfolder. It consists of one file that should have the proper file extension.

Running the project

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

Project details

The letter template

The promotional letter is designed in the PR_PROM Letter template. It contains one Print section (see Print sections).

There are two Master Pages that are each applied to different pages in the Print section (see Applying a Master Page to a page in a Print section).

The Media contains the virtual stationery. Whether this is included in or omitted from the final output depends on a setting in the Output Preset.

Personalization is mostly done via simple text scripts. Such scripts look for a text surrounded by @ (e.g. @city@) and replace that by the correct data. (See: Variable data in text: scripts and placeholders.)

A few scripts are a little bit more sophisticated.

  • The sales_rep script combines some data fields and adds a line break. Double-click the script to open the Text Script Wizard with which this script was made. (See: Using the Text Script Wizard.)

  • The Promo script shows or hides a paragraph (with the ID 'promo') depending on whether the customer's address is in Montréal. (See: Showing content conditionally.)

  • The year script changes the year in the conditional paragraph to the current year. This script only has to look for @year@ in an element that has the ID 'promo', instead of in the entire letter, which makes it run faster.

  • The Dynamic Signature script switches the signature, with a file name based on a data field. (See: Dynamic images.)

  • The sender's address is adjusted depending on where the customer lives. The two different sender's addresses are saved in snippets. (See: Loading a snippet via a script.)

Styling is done via CSS. The context_all_styles.css file contains style rules for certain HTML elements (level 1 and 2 headings) and for elements with a certain class or ID.

The data mapping

The data with which the template is merged come from an XML file: Sample Data.xml. They are extracted from the XML file with a data mapping configuration: , made with the DataMapper module in the Designer.
The data mapping configuration is very straightforward. It extracts all data without modifications and it does no pre- or post-processing. Simple data mapping configurations like this are made with the XML Data Mapping Wizard (see: Using the wizard for XML files). The wizard creates a configuration with only one step: the Extract All step.

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 file: Sample Data.xml.
The sample file 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_PROM Data XML.

Print settings

The Print context and Print sections can have their own print settings, such as Duplex printing or binding style (see Print settings in the Print context and sections). But in this template, they don't have any. The way the letter is outputted is determined (mostly) by an Output Preset.

The Sample Project installs six Output Presets; two for each type of output. Per output type, all settings in the Output Presets are the same, except one: Print Virtual Stationery. The ones that have this option enabled will include the Media - the Virtual Stationery - in the output. The other presets will not print the Media.
Only the selected Output Preset is put to use in the Workflow configuration.

To see the exact settings, open an Output Preset in the Designer: first select File > Open from the menu; then browse to the preset.
Note that the Output Type, on the Print Options page in the Output Creation dialog, is set to Prompt for file name. This setting is overruled in the Workflow configuration (see below).

Workflow configuration

Whenever new input data appears in the Workspace\In folder, the letter template is automatically merged with it and then printed. That is, if the Workflow server is running with the Workflow configuration installed by the Sample Project.

This project's Workflow configuration: Print Promotional Jobs, contains just one process: a basic OL Connect Workflow Print process (see Print processes with OL Connect tasks).

 It consists of three plugins:

  • The Folder Capture Input task. This task retrieves all XML files that enter the Workspace\In folder.

  • The All In One plugin. This plugin uses the data mapping configuration and template that come with the project, and the Output Preset selected in the Sample Project. The plugin is set to handle the output 'Through Workflow'. This means that the task will return the output file to the Workflow process.

  • The Send to Folder Output task. This task writes the output file to a subfoler in the Workspace\Out folder. It makes use of system variables (see Standard variables) to dynamically create a subfolder based on the current month and year (%M_%y). The name of the file consists of the original file name (%O), the current time (%h%n%s) and the file extension. The file extension (.pdf, .pcl or .ps) matches the output technology selected in the Sample Project.

Both the Folder Capture and the Send to Folder task read 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 letter, 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.

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

Finally, in Workflow, adjust the process: double-click the All In One task to open it, and select the new template on the Content Creation tab. 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 kind of file, you could use one of the other Output Presets. To do that, adjust the process in Workflow: double-click the All In One task to open it, and select the Output Preset of your choice on the Output Creation tab.

To change the settings in an Output Preset, open it in the Designer: select File > Open from the menu and browse to the preset.

All of the presets provided by the wizard save the output to one file. You might want to save the output to a number of files, for instance, one per customer. The Transactional Print Jobs project shows you how to do that.