PlanetPress Connect User Guide Planet Press 1.5 Operating Instructions 15 EN
User Manual: Pdf PlanetPress Connect - 1.5 - Operating Instructions User Guide for Objectif Lune PlanetPress Software, Free Instruction Manual
Open the PDF directly: View PDF 
.
Page Count: 849
User Guide
Version: 1.5
User Guide
Version 1.5
Last Revision: 2017-04-12
Objectif Lune, Inc.
2030 Pie-IX, Suite 500
Montréal, QC, Canada, H1V 2C8
+1 (514) 875-5863
www.objectiflune.com
All trademarks displayed are the property of their respective owners.
© Objectif Lune, Inc. 1994-2017. All rights reserved. No part of this documentation may be
reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever
without the express written permission of Objectif Lune Inc. Objectif Lune Inc. disclaims
responsibility for any errors and omissions in this documentation and accepts no responsibility
for damages arising from such inconsistencies or their further consequences of any kind.
Objectif Lune Inc. reserves the right to alter the information contained in this documentation
without notice.
Page 4
Table of Contents
Table of Contents
5
Welcome to PlanetPress Connect 1.5
12
Icons used in this guide
Setup And Configuration
12
14
System and Hardware Considerations
System Requirements
Environment considerations
Database Considerations
Network considerations
Language and Encoding considerations
Performance Considerations
Installation and Activation
Installation Pre-Requisites
User accounts and security
The Importance of User Credentials on Installing and Running PlanetPress Connect
Installing PlanetPress Connect on Machines without Internet Access
Installation Wizard
How to Run Connect Installer in Silent Mode
Activating a License
Migrating to a new computer
Information about PlanetPress Workflow 8
Upgrading from PlanetPress Suite 7.6
What do I gain by upgrading to PlanetPress Connect?
Server Settings
Server Security Settings
Server Extension Settings
Uninstalling
Important Note: Stop any Anti-Virus Software before uninstalling Connect.
Impacts upon other Applications and Services
Uninstallation Wizard
The DataMapper Module
14
14
15
17
20
20
21
23
24
25
26
28
29
35
38
41
41
42
45
48
48
49
52
53
53
53
55
Basics
What's Next?
55
56
Page 5
Data Mapping Configuration
Creating A New Data Mapping Configuration
Opening a Data Mapping Configuration
Saving a Data Mapping Configuration
Data Mapping Workflow
Selecting Data
Extracting Data
About Promotional and Transactional Data
Steps
The Data Model
How to Use a Data Model?
About Records and Fields
Data Model File Structure
Data Source (Settings)
Input Data (Delimiters)
Boundaries
Data Samples
External JS Libraries
DataMapper User Interface
Menus
Panes
Example
Example
Left Operand
Condition
Operators
JavaScript
Defining Boolean Values
Boolean Expressions
Defining String Values
Building String Values
Defining Integer Values
Building Integer Values
Defining Float Values
Building Float Values
Defining Currency Values
Building Currency Values
56
56
66
66
67
67
76
89
89
103
104
105
106
108
108
108
109
109
110
111
115
122
127
184
185
186
193
196
196
197
197
198
198
199
199
200
200
Page 6
Extracting dates
Defining a date/time format
Examples of masks
Entering a date using JavaScript
Example
Defining Object Values
Toolbar
Shortcut Keys
Welcome Screen
DataMapper Scripts API
Objects
Functions
Methods
Write Your Own Scripts
Boundaries Using JavaScript
Objects
Functions
Methods
The Designer
Basic Steps
Templates
Contexts
Sections
Features
Print
Pages
Headers, footers, tear-offs and repeated elements (Master page)
Stationery (Media)
Creating a Print template with a Wizard
Print context
Print sections
Pages
Master Pages
Media
Email
Designing an Email template
Creating an Email template with a Wizard
201
201
202
202
203
203
203
205
205
207
207
208
209
214
216
222
229
236
255
255
256
269
271
274
275
276
276
276
277
281
284
291
299
302
307
308
311
Page 7
Email context
Email templates
Email header settings
Email attachments
Web
Creating a Web template with a Wizard
Web Context
Web pages
Forms
Using Form Elements
Using JavaScript
Capture OnTheGo
COTG Forms
Creating a COTG Form
Filling a COTG template
Testing the template
Sending the template to the Workflow tool
Using COTG data in a template
Designing a COTG Template
Capture OnTheGo template wizards
Using Foundation
Using COTG Elements
Testing a Capture OnTheGo Template
Content elements
Element types
Editing HTML
Attributes
Inserting an element
Selecting an element
Styling and formatting an element
Barcode
Boxes
Business graphics
COTG Elements
Date
Forms
Form Elements
315
317
320
324
326
327
331
332
337
342
346
348
349
349
350
352
352
353
355
358
362
365
369
373
374
375
375
376
377
378
379
419
422
424
429
430
435
Page 8
Hyperlink and mailto link
Images
Table
Text and special characters
Snippets
Adding a snippet
Creating a snippet
JSON Snippets
Styling and formatting
Local formatting versus style sheets
Layout properties
Styling templates with CSS files
How to position elements
Styling text and paragraphs
Background color and/or image
Border
Colors
Fonts
Spacing
Styling a table
Rotating elements
Locale
Personalizing content
Variable data
Conditional content
Dynamic images
Dynamic tables
Snippets
Scripts
Loading data
Variable Data
Formatting variable data
Showing content conditionally
Dynamic Images
Dynamic table
Personalized URL
Writing your own scripts
438
440
445
449
451
451
452
452
453
453
453
454
462
464
468
469
472
476
478
479
483
484
485
486
486
486
487
487
487
488
497
503
506
508
510
514
515
Page 9
How scripts work
Creating a new script
Writing a script
Managing scripts
Testing scripts
Optimizing scripts
Loading a snippet via a script
Control Scripts
Designer User Interface
Dialogs
Menus
Panes
Toolbars
Welcome Screen
Print Options
Job Creation Presets
Output Creation Settings
Designer JavaScript API
Designer API
Control Script API
Designer Scripts API
Control Script API
Generating output
Print output
Email output
Web output
Optimizing a template
Scripts
Images
Generating Print output
Saving Printing options in Printing Presets.
Connect Printing options that cannot be changed from within the Printer Wizard.
Print Using Standard Print Output Settings
Print Using Advanced Printer Wizard
Adding print output models to the Print Wizard
Splitting printing into more than one file
Variables available in the Output
515
516
517
519
523
526
530
532
546
547
617
628
643
648
649
701
710
728
728
728
729
782
798
798
798
799
799
799
800
801
802
802
803
804
805
806
806
Page 10
Generating Fax output
Generating Tags for Image Output
Generating Email output
Email output settings in the Email context and sections
Generating Email output from Connect Designer
Generating Email output from Workflow
Email attachments
Using an ESP with PlanetPress Connect
Generating Web output
Attaching Web output to an Email template
Generating Web output from Workflow
Web output settings in the Web context and sections
Release Notes
813
814
815
816
817
818
819
820
825
826
827
828
829
Overview
Connect 1.5 Designer Enhancements and Fixes
Connect 1.5 DataMapping Enhancements and Fixes
Connect 1.5 Output Enhancements and Fixes
Connect 1.5 General Enhancements and Fixes
Connect 8.5 Workflow Enhancements and Fixes
Known Issues
Copyright Information
829
830
834
834
836
837
838
843
Legal Notices and Acknowledgments
844
Page 11
Welcome to PlanetPress Connect 1.5
Note
Since we are always looking for new ways to make your life easier, we welcome your
questions and comments about our products and documentation. Shoot us an email at
doc@ca.objectiflune.com, or visit the online help: help.objectiflune.com and use the
feedback tool at the bottom of the page.
PlanetPress Connect is a series of four tools designed to optimize and automate customer
communications management. They work together to improve the creation, distribution,
interaction and maintenance of your communications.
The PlanetPress Connect Datamapper and Designer is designed to create output for print,
email and the web within a single template and from any data type, including formatted print
streams. Output presets applied outside the design phase make printing device independent.
The Designer has an easy-to-use interface that makes it possible for almost anyone to create
multi-channel output. More advanced users may use native HTML, CSS and JavaScript.
PlanetPress Connect also includes a process automation server, called Workflow. It is capable
of servicing response form web pages and email to provide interactive business
communications.
PlanetPress Connect can create documents for tablets and mobile devices that run a free
CaptureOnTheGo App. Users with a CaptureOnTheGo subscription can then download
documents to their own devices, interact with them and send the captured data back to
PlanetPress for conversion into additional documents or workflows.
This online documentation covers PlanetPress Connect version 1.5.
Icons used in this guide
Icons are used throughout this guide to point your attention to certain information.
Page 12
Note
Complementary information that is not critical, but may help you better use PlanetPress Connect.
Tip
Information that is useful or suggests an easier method.
Technical
Information that may require specific knowledge to understand.
Warning
Information that is potentially critical to using PlanetPress Connect. Pay close attention.
Page 13
Setup And Configuration
This chapter describes the PlanetPress Connect installation and the different considerations
that are important in regards to the installation and use of PlanetPress Connect.
l
"System and Hardware Considerations" below
l
"Installation and Activation" on page 23
l
"Server Settings" on page 48
l
Uninstalling
System and Hardware Considerations
There are a variety of considerations to be aware of. These are documented in the following
pages:
l
"System Requirements" below
l
"Environment considerations" on the next page
l
"Database Considerations" on page 17
l
"Network considerations" on page 20
l
"Language and Encoding considerations" on page 20
l
"Performance Considerations" on page 21
System Requirements
These are the system requirements for PlanetPress Connect 1.5
Operating System (64-bit only)
l
Microsoft Windows 2008/2008 R2 Server
l
Microsoft Windows 2012/2012 R2 Server
l
Microsoft Windows Vista
l
Microsoft Windows 7
l
Microsoft Windows 8.1
l
Microsoft Windows 10
Page 14
Note
Windows 8.0, Windows XP, Windows 2003 and older versions of Windows are not
supported by PlanetPress Connect.
Minimum Hardware Requirements
l
NTFS Filesystem (FAT32 is not supported)
l
CPU Intel Core i7-4770 Haswell (4 Core)
l
8GB RAM (16GB Recommended)
l
Disk Space: At least 10GB (20GB recommended)
Note
For tips and tricks on performance, see "Performance Considerations" on page 21.
Environment considerations
Virtual Machine Support
PlanetPress Connectsupports VMWare Workstation, VMWare Server, VMWare Player,
VMWare ESX (including VMotion), Microsoft Hyper-V and Microsoft Hyper-V/Azure
infrastructure environments as software installed on the Guest operating system.
Warning
Copying (duplicating) a Virtual Machine with Connect installed and using both images
simultaneously constitutes an infringement of our End-User License Agreement.
Note
While some virtual machine environments (from VMWare and Microsoft) are supported,
other virtual environments (such as Parallels, Xen and others) are not supported at this
Page 15
time.
Terminal Server/Service
PlanetPress Connect does not support Terminal Server (or Terminal Service) environment as
possible under Windows 2000, 2003 and 2008. This is to say, if Terminal Service is installed
on the server where PlanetPress Connect is located, unexpected behaviours may occur and
will not be supported by Objectif Lune Inc.. Furthermore, using PlanetPress Connect in a
Terminal Service environment is an infringement of our End-User License Agreement.
Remote Desktop
Tests have demonstrated that PlanetPress Connect can be used through Remote Desktop. It is
however possible that certain combination of OS could cause issues. If problems are
encountered, please contact OL Support and we will investigate.
PlanetPress Connect 1.3 and later have been certified under Remote Desktop.
64-bit Operating Systems
PlanetPress Connect is a 64-bit software and can only be installed on 64-bit operating systems.
Antivirus Considerations
l
l
Antivirus software may slow down processing or cause issues if they are scanning in
temporary folders or those used by PlanetPress Connect. Please see KB-002: Antivirus
Exclusions for more information.
Antivirus software might interfere with installation scripts, notably a vbs script to install
fonts. McAfee, in particular, should be disabled temporarily during installation in order for
MICR fonts to install and the installation to complete successfully.
Windows Search Indexing Service
Tests have concluded that the Windows Search service, used to provide indexing for Windows
Search, can interfere with Connect when installing on a virtual machine. If the installation
hangs during the last steps, it is necessary to completely disable this service during installation.
l
Click on Start, Run.
l
Type in services.msc and click OK.
Page 16
l
Locate the Windows Search service and double-click on it.
l
Change the Startup Type to Disable, and click Stop to stop the service.
l
Try the installation again.
l
Once completely, you may re-enable the service and start it.
Commandline switches and .ini entries
PlanetPress Connect is intended to work stably and reliably, based on Java and the Eclipse
framework. To ensure this reliability and robustness, many Java and Eclipse parameters have
been tested and tuned, which is reflected in the respective .ini entries and the used command
line switches. A collection of valuable settings has been elaborated and found its entry in
PlanetPress Connect “good switches list” (called the “whitelist”).
The protection of the end user’s system is one of our main goals and therefore we have
implemented a very strict verification mechanism, which ensures, that only these whitelisted ini
entries and commandline switches are accepted, when one of Connect components is started
and run. Please be therefore advised, that any non-whitelisted ini entry or commandline switch
will be accepted and will - if tried to be used - lead to the respective application’s “sudden
death”. If you should encounter such a behaviour then please double-check your Connect log
file/s for respective entries.
Database Considerations
This page describes the different considerations and pre-requisites for the database back-end
used by PlanetPress Connect, whether using the MySQL instance provided by the installer, or
pre-existing instance.
Using the MySQL Instance from the Installer
The MySQL Instance provided in the Installation Wizard is already pre-configured with options
to provide the most stable back-end setup.
These are the specific options that have been changed in our version of "my.ini":
l
max_connections = 200 : PlanetPress Connect uses a lot of database connections. This
number ensures that even in high volume environments, enough connections will be
available.
Page 17
l
l
max_allowed_packet = 500M : In some implementations, especially when using Capture
OnTheGo, large packet sizes are required to allow transferring binary files. This
substantial packet size maximum setting ensures that the data received by PlanetPress
Connect will be able to be stored within the database.
character-set-server = utf8 , collation-server = utf8_unicode_ci , default-characterset=utf8 : These indicate database support for UTF-8/Unicode.
Using a pre-existing MySQL Instance
If MySQL server is already installed and you wish to use it, the following should be taken into
consideration:
l
l
l
The MySQL account must have access to all permissions using the GRANT Command,
including creating databases.
The database configuration must include the options detailed in the "Using the MySQL
Instance from the Installer" on the previous page topic above.
The SQL instance must be open to access from other computers. This means the bindaddress option should not be set to 127.0.0.1 or localhost.
Using MS SQL Server from the Installer
l
l
l
When MS SQL is selected, the default values for root user are sa and 1433 for the port.
If db settings from a previous installation are found, the pre-exising settings will be
displayed for the matching db type (for MS SQL settings, this will only work if they were
created with Server Config Tool 1.5.0 or later, or the Connect installer 1.6.0 or later). If the
db type is changed in the configuration page, the default values for this db type will be
displayed. If the pre-existing db settings are set to Hsqldb, the default db type selection
will be MySQL.
Selected db settings are stored in the preferences as usual (C:\ProgramData\Objectif
Lune\Ol
Connect\.settings\ConnectHostScope\com.objectiflune.repository.eclipselink.generic.pref
s)
Updating With No Local MySQL Product
l
When updating a Connect installation from 1.5.0 which contains a Server Product but no
local MySQL Product, the DB Configuration Page will detect which db type was set
before (especially if the db configuration was switched from MySQL to MS SQL using the
Server Configuration Tool), and default to those settings.
Page 18
l
On Update from 1.4.2 or earlier, the DB Configuration Page will always default to MySQL
connection settings, and if the installation was manually tweaked to connect to MS SQL
Server, the user has to switch to "Microsoft SQL Server" type and enter connection details
again.
Installing / Updating Connect Using a Local MySQL
l
l
l
The Configuration page for the local MySQL is displayed.
MySQL settings are pre-filled with default values if no existing MySQL db configuration is
found.
MySQL settings are pre-filled with existing db configuration settings, if they point to a
MySQL db type.
When modifying Connect
l
l
If local MySQL is removed from an installation, the DB Configuration page will offer
additionally the Microsoft SQL Server db type with respective default values.
If local MySQL is added to an installation, the usual MySQL Configuration page with
default values will be displayed.
Important
If a Server Product and a MySQL Product were selected to be installed on Connect 1.5.0, and
then the Server Configuration Tool is used to switch the database used by the Server to an
external Microsoft SQL, then the Update to 1.6 requires an extra step. The procedure is as
follows:
1. Run the Update to Connect 1.6. This will assume the local MySQL database needs to
be updated and configured, so the user has to enter a root password on the MySQL
Configuration Page (can be any password matching Connect security rules).
2. After the update, the Connect 1.6 Setup needs to be run once more to modify Connect.
3. On the Product Selection page, now the MySQL product can be unselected.
4. When stepping forward in the Wizard, the DB Configuration page will be displayed which
allows to configure the Microsoft SQL Server with appropriate settings.
After this modification, the local MySQL is removed, and also the service dependency from
Server to MySQL is removed.
Page 19
Note
If Connect was initially installed not containing the local MySQL product (i.e. on 1.5 installation an
external MySQL was configured as database), then the Update to 1.6 will allow to select either
external MySQL or external Microsoft SQL on the DB Configuration Page.
Network considerations
The following should be taken into consideration in regards to network settings and
communications
l
If a local proxy is configured (in the Internet Explorer Optionsdialog, the option Bypass
proxy server for local addresses must be checked, or some features depending on
local communication will not work.
Language and Encoding considerations
Please note the following considerations:
l
Language:
l
PlanetPress Connect is currently offered in several languages. These languages
can be switch between via the Preferences dialog. The current languages include:
l
English
l
French
l
German
l
Spanish
l
Italian
l
Portuguese
l
Chinese (Simplified)
l
Chinese (Traditional)
l
Japanese.
The default language is English.
Page 20
The PlanetPress Connect help system (this document) is currently only available in
English.
l
Encoding:
l
Issues can sometimes be encountered in menus and templates when running
PlanetPress Connect on a non-English operating system. These are due to
encoding issues and will be addressed in a later release.
Performance Considerations
This page is a comprehensive guide to getting the most performance out of PlanetPress
Connect as well as a rough guideline to indicate when it's best to upgrade.
Performance Analysis Details
In order to get the most out of PlanetPress Connect, it is important to determine how best to
maximize performance. The following guidelines will be helpful in extracting the best
performance from PlanetPress Connect before looking into hardware upgrades or extra
PlanetPress Connect performance packs.
l
Job Sizes and Speed: In terms of pure output speed, it's important to first determine what
job size is expected, and adjust Scheduling Preferences accordingly. The basic rules are:
l
l
l
l
If processing a small number of very large records (when each individual record is
composed of a large number of pages), more instances with an equal amount of
speed units is better. For hardware, RAM and Hard Drive speeds are most
important, since the smallest divisible part (the record) cannot be split on multiple
machines or even cores.
If creating a very large number of small records (hundreds of thousands of 2-3 page
individual records, for instance), a smaller number of instances with a large number
of speed packs would be better. As for hardware, then the number of cores becomes
critical, whereas RAM and hard drive are secondary. Performance Packs, as well as
the MySQL instance being separate, would be helpful if your most powerful
machine starts struggling.
Mix and match. For example, one instance prioritized for large jobs and the rest for
smaller, quicker jobs. Or the contrary. Or, whatever you want, really.
RAM Configuration: By default, each instance of the Merge Engine and Weaver Engine
is set to use 640MB of RAM. This means that regardless of speed units, if not enough
memory is available, output speed might not be as expected. Assuming that the machine
itself is not running any other software, the rule of thumb is the following: The total number
Page 21
of used memory in the machine should be pretty much the maximum available (around
95%).
For each engine, it's necessary to modify the .ini file that controls its JAVA arguments.
Edit as follows:
l
l
l
l
For the Merge Engine: see C:\Program Files\Objectif Lune\OL
Connect\MergeEngine\Mergeengine.ini
For the Weaver Engine: see C:\Program Files\Objectif Lune\OL
Connect\weaverengine\Weaverengine.ini
The parameters are -Xms640m for the minimum RAM size, -Xmx640m for the
maximum RAM size. Explaining Java arguments is beyond the scope of this
document. Please read references here, here and here for more details (fair
warning: these can get pretty technical!).
Template and data mapping optimization: Some functionality offered by the
DataMapper and Designer modules are very useful, and sometimes downright awesome,
but can cause the generation of records and of contents items to slow down due to their
nature. Here are some of them:
l
l
l
l
l
Preprocessor and Postprocessor scripts: manipulating data using a script may
cause delays before and after the data mapping action has actually taken place,
especially file conversion and data enrichment from other sources.
Loading external and network resources: In Designer, using images, javascript
or css resources located on a slow network or on a slow internet connection will
obviously lead to a loss of speed. While we do our best for caching, a document
with 100,000 records which queries a page that takes 1 second to return a different
image each time will, naturally, slow output generation down by up to 27 hours.
External JavaScript Libraries: While loading a single JavaScript library from the
web is generally very fast (and only done once for the record set), actually running a
script on each generated page can take some time. Because yes, JavaScript will
run for each record, and often take the same time for each record.
Inefficient Selectors: Using very precise ID selectors in script wizards can be much
faster than using a text selector, especially on very large documents. (more details
on this in another upcoming page).
Complex Scripts: Custom scripts with large, complex or non-optimized loops can
lead to slowing down content creation. While it is sometimes difficult to troubleshoot,
there are many resources online to help learn about JavaScript performance and
coding mistakes. Here, here, and here are a few. Note that most resources on the
Page 22
web are about JavaScript in the browser, but the greatest majority of the tips do,
indeed, apply to scripts in general, wherever they are used.
High-Performance Hardware
The following is suggested when processing speed is important. Before looking into a
Performance Packs to enhance performance, ensure that the below requirements are met.
l
l
l
l
A physical, non-virtualized server. VMWare servers are great for reducing the numbers
of physical machines in your IT space, but they must share the hardware between each
other. While you can create a virtual machine that seems as powerful as a physical, it will
still be sharing hardware with any other virtual machines, and this will adversely affect
performance.
MySQL Database on a separate machine. MySQL's main possible bottleneck is file I/O,
and as such a high-performance setup will require this server to be on a separate
machine, ideally with a high-performance, low-latency hard drive. A Solid State Drive
(SSD) would be recommended.
High-Quality 16+ GB Ram.This is especially true when working with many server
instances ("speed units") running in parallel. The more parallel processing, the more
RAM is recommended.
4 or 8 physical cores. We're not talking Hyper-Threading here, but physical cores.
Hyper-Threading is great with small applications, but the overhead of "switching"
between the virtual cores, and the fact that, well, they're virtual, means the performance is
much lesser on high-power applications such as OL Connect. In short, a dual-core
processor with Hyper-Threading enabled is not equivalent to a quad-core processor.
Installation and Activation
This topic provides detailed information about the installation and activation of PlanetPress
Connect 1.5.
Note
A PDF version of this guide is available for use in offline installations. Click here to
download it.
Page 23
PlanetPress Connect 1.5 is comprised of 2 different installers: one for the PlanetPress Connect
software and one for PlanetPress Workflow 8.
Where to Obtain the Installers:
The installers for PlanetPress Connect 1.5 and PlanetPress Workflow 8 can be obtained on
DVD or downloaded as follows:
l
l
If you are a Customer, the installers can be downloaded from the Objectif Lune Web
Activations page: http://www.objectiflune.com/activations
If you are a Reseller, the installers can be downloaded from the Objectif Lune Partner
Portal: http://extranet.objectiflune.com/
For information on licensing, please see Activating your license.
Installation Pre-Requisites
l
l
l
l
l
l
Make sure your system meets the System requirements.
PlanetPress Version 1.5 can be installed under a regular user account with Administrator
privileges.
Connect must be installed on an NTFS file system.
PlanetPress requires Microsoft .NET Framework 3.5 already be installed on the target
system.
In order to use the automation feature in Version 1.5, PlanetPress Workflow 8 will need to
be installed. This can be installed on the same machine as an existing PlanetPress®
Suite 7.6 installation or on a new computer. For more information, please see Information
about PlanetPress Workflow 8.
As with any JAVA application, the more RAM available, the faster the product will
execute.
Users of Connect 1.1
In order for users of PlanetPress Connect 1.1 to upgrade to any later version through the
Update Manager it is necessary to install a later version (1.1.8 or later) of the Objectif Lune
Update Client.
If you do not have such a version installed already, the next time you run your Update Client it
will show that there is an update available of itself to Version 1.1.8 (or later).
Page 24
Simply click on the download button in the dialog to install the new version of the Update
Client. Note that it is no problem to run the update while the Client is open. It will automatically
update itself.
Once you have done this, PlanetPress Connect 1.5 will become available for download.
Note
From PlanetPress Connect Version 1.2 onwards, the new version (1.1.8) of the Update
Client is included by default with all setups.
Users of Connect 1.0
Users of this Connect version 1.0 cannot upgrade directly to Version 1.5. This is because
Connect Version 1.0 is a 32 bit version of Connect.
Users must first upgrade to Version 1.1 and from there upgrade to Version 1.5
If you are updating manually you must first upgrade to Version 1.1 before installing 1.5. If you
attempt go directly from Version 1.0 to Version 1.5 the installation will fail.
Also see "Users of Connect 1.1" on the previous page for extra information about updating from
that version.
User accounts and security
Permissions for PlanetPress Connect Designer
PlanetPress Connect Designer does not require any special permissions to run besides a
regular program. It does not require administrative rights and only needs permission to
read/write in any folder where Templates or Data Mapping Configurations are located.
If generating Print output, PlanetPress Connect Designer requires permission on the printer or
printer queue to send files.
Permissions for PlanetPress Connect Server
The PlanetPress Connect Server module, used by the Automation module, requires some
special permissions to run. These permissions are set during installation, in the Engine
Page 25
Configuration portion of the Installation Wizard, but it can also be configured later by modifying
permissions for the service. To do this:
l
l
l
l
In Windows, open the Control Panel, Administrative Tools, then Services (this may
depend on your operating system).
Locate the service called Serverengine_UUID , where UUID is a series of characters that
depend on the machine where the software is installed.
Right-click on the service and select Properties.
In the Connection tab, define the account name and password that the service should
use. This can be a local account on the computer or an account on a Windows Domain.
The account must have administrative access on the machine. It should also correspond
to the user account set up in PlanetPress Worfklow.
The Importance of User Credentials on Installing and
Running PlanetPress Connect
OL Connect and required credentials depends heavily on the Connect component and
respective tasks and what sort of user credentials are needed.
First of all, it is important to distinguish between installation and run-time
Installation
The Connect installer puts all required files, folders, registry entries and much more to their
correct places and locations. As many of these locations are protected against malicious
accesses, that very user under whose context the Connect installation is started and running,
needs very extensive rights on the respective computer. This user must belong to the Local
Administrators group on that machine. Here are some required capabilities, this user:
l
l
l
l
l
Must be able to write into the "Programs" folder.
Must be allowed to check for existing certificates and must also be allowed to install new
ones into the global certificate store on that machine.
Must be able to write into HKLM and any subtree of it in the registry.
Must be able to INSTALL, START and RUN services and also to MODIFY service
settings.
Must be known in the network the machine belongs to and must also need to be able to
use shared network resources like shared drives and/or printers etc.
Page 26
This list may not be complete, but it gives the extent of the requirements. Generally, the local
administrator of the machine will have all these credentials, but there may exist network
restrictions and policies, which will block one or more of these capabilities. In such cases, the
respective network administrator should provide a valid user account for the installation.
User Account
The user account shall be used to later RUN one of the Connect Server flavors (Server or
Server Extension). This dedicated user account has to be entered on the respective installer
dialog page and must be allowed to START, STOP and RUN services on this machine. This is
different from the credentials of the installation user account, which additionally requires the
right to INSTALL services. Please be aware of this fact!
Additionally, the Server user must be able to access any network resources that are required for
OL Connect to function properly. This includes e.g. additional drives, printers, scanners, other
computers and, where appropriate, internet resources, URLs, mail servers, FTP servers,
database servers and everything else planned to be used for the intended operation of
Connect. The Server user is the run-time user.
Connect Components
Usually, a standard end user will only be facing Connect Designer and maybe the License
Activation Tool. Designer this does not require administrator rights. Either everything required
to create documents or also to run some tasks will be already available (installed by the
installer) or be accessible in a way, where no specific credentials are required. However some
tasks like starting an email campaign will possibly require a respective account at a mail server.
But this has generally nothing to do with the credentials of the Designer user.
Activation Tool
To run the Software Activation Tool, administrator rights are required because this tool needs to
write the license file in one of the protected folders of Windows. The tool will however allow to
restart it with respective credentials if required.
MySQL
MySQL database service is installed by the install user (thus again the requirement of
installing, starting, running and modifying services). Once running it will just work.
Page 27
Merge and Weaver Engines
These components do run under the Designer (if only Designer is installed) or the Server /
Extension service(s) and inherit the rights of their parent application.
Server (Extension) Configuration Tool
This component needs to access the settings of the Server. As these are stored and read by the
Server, it should be clear that the user used to run the Configuration tool should be the same as
the Server Service user as explained above.
Installing PlanetPress Connect on Machines without
Internet Access
Installing PlanetPress Connect1.5 in offline mode requires some extra steps. These are listed
below.
GoDaddy Root Certificate Authority needs to be installed.
In order to install PlanetPress Connect it is necessary for the GoDaddy Root Certificate
Authority to be installed (G2 Certificate) on the host machine and for this to be verified online.
When a machine hosting the installation does not have access to the Internet, the installation
will fail because the verification cannot be performed. To solve this problem one must first
ensure that all Windows updates have been installed on the host machine. Once the Windows
updates are confirmed as being up to date, then complete the following steps:
1. Go to https://certs.godaddy.com/repository and download the following two certificates to
copy to the offline machine:
l
l
GoDaddy Class 2 Certification Authority Root Certificate - G2 - the file is gdrootg2.crt
GoDaddy Secure Server Certificate (Intermediate Certificate) - G2 - the file is
gdig2.crt
2. Install the certificates: Right mouse click -> Install Certificate, and follow the steps through
the subsequent wizard.
3. Now copy the PlanetPress Connect installer to the offline machine and start the
installation as normal
Page 28
Windows certificate validation - Certificate Revocation List retrieval should be switched
off
For your security Objectif Lune digitally signs all relevant files with our own name and
certificate. The integrity of these files is checked at various times by different, context related,
methods. One of these checks, done during the installation process, uses the Windows
certificate validation check. .
The Windows certificate validation process not only checks the integrity of a file against its
signature, but also usually checks if the certificate itself is still valid. That check is done against
the current Certificate Revocation List (CRL), which needs to be retrieved from the internet.
However, if the machine in question does not have internet access, the retrieval of the CRL
must fail, which will lead to subsequent validation issues.
To circumvent such issues it is highly recommended to switch off the CRL retrieval prior to
installing Connect on machines without internet access. There is no security risk associated
with this, as the CRLs would never be retrievable without internet access, anyway. Advantage
of the switch will not only be found during the installation and operation of Connect, but also in
some speed improvements for any application which use signed binaries.
To switch off CRL retrieval on the computer, complete the following steps:
1. Open the “Internet Options” via the Control Panel
2. Select the “Advanced” tab and scroll down to “Security” node.
3. Uncheck the entry “Check for publisher’s certificate revocation” under that node.
4. Click the OK button to close the dialog.
5. Re-start the computer.
Installation Wizard
Starting the PlanetPress Connect installer
The PlanetPress Connect installer may be supplied as an ISO image or on a DVD:
l
l
If an ISO image, either burn the ISO onto a DVD or unzip the contents to a folder (keeping
the folder structure)
If on a DVD, either insert the DVD and initiate the installation from there or copy the
contents to a folder (keeping the folder structure)
Page 29
Navigate to the PlanetPress_Connect_Setup_x64.exe or and double-click on it. After a short
while the Setup Wizard will appear as a guide through the installation steps.
Note
PlanetPress Connect requires prior installation of Microsoft .NET Framework 3.5 (please refer to
https://www.microsoft.com/en-us/download/details.aspx?id=21 for more details).
Selecting the required components
After clicking the Next button, the component selection page appears, where the different
components of PlanetPress Connect can be selected for installation. Currently, the following
are available:
l
l
l
l
PlanetPress Connect Designer: The Designer module. It may be used as a standalone
with no other installed modules, but it will not have certain capabilities such as
automation and commingling.
PlanetPress Connect Server: The Server back-end giving capabilities such as
automation, commingling, picking. It saves all entities generated from the Automation
module into a database for future use.
MySQL Product: The database used by the PlanetPress Connect Engine to save its
items. This item is optional if an existing MySQL server, either on the same computer or a
separate server, is to be used.
Installation Path: This is the location where modules are to be installed.
The installer can also calculate how much disk space is required for installing the selected
components as well as how much space is available:
l
l
l
l
Disk space required: Displays the amount of space required on the disk by the selected
components.
Disk space available on drive: Displays the amount of space available for installation on
the drive currently in the Installation Path.
Recalculate disk space: Click to re-check available disk space. This is useful if space
has been made available for the installation while the installer was open.
Source repository location: Displays the path where the installation files are located.
This can be a local drive, installation media, or a network path.
Page 30
Selection Confirmation
The next page confirms the installation selections made. Click Next to start the installation
itself.
End User License Agreement
The next page displays the End User License Agreement, which needs to be read and
accepted before clicking Next.
MySQL Configuration
The Default Database Configuration page only appears if the MySQL Product module was
selected in the Product Selection screen. It defines the administrative password for the MySQL
server as well as which port it uses for communication. Note that the installer will automatically
configure the Server to use the supplied password and port.
l
MySQL user 'root' Password: Enter the password for the 'root', or administration
account, for the MySQL server. The password must be at least 8 characters long and
contain at least one of each of the following:
l
a lower case character (a, b, c ... )
l
an upper case character (A, B, C ...)
l
a numeric digit (1, 2, 3 ...)
l
a punctuation character (@, $, ~ ...)
For example: "Th1sIs@K"
Note
When updating from an earlier Connect version, the appropriate MySQL password
must be entered or the update will fail.
If the password is subsequently forgotten, then the MySQL product must be
uninstalled and its database deleted from disk before attempting to reinstall.
l
Confirm 'root' Password: Re-enter to confirm the password. Both passwords must
match for installation to continue.
Page 31
l
TCP/IP Port Number: The port on which MySQL will expect, and respond to, requests. A
check is run to confirm whether the specified TCP\IP Port Number is available on the
local machine. If it is already being used by another service (generally, an existing
MySQL installation), the number is highlighted in red and a warning message is
displayed at the top of the dialog.
Note
The MySQL Product controlled by the OLConnect_MySQL service communicates
through port 3306 by default.
l
Allow MySQL Server to accept non-local TCP connections: Click to enable external
access to the MySQL server.
Note
This option is required if MySQL Server will need to be accessed from any other
machine.
It is also required if the MySQL database is on a separate machine to PlanetPress
Connect.
Tip
This option may represent a security risk if the machine is open to the internet.
It is heavily recommended that your firewall is set to block access to port 3306 from
external requests.
The Database Connection page appears if the MySQL Product module was not selected. It
defines the necessary information required to connect to an existing database.
l
l
Database Configuration: Select the database type to use for the PlanetPress Connect
Engine. Currently only MySQL is supported.
Administrator Username: Enter the username for a user with administrative rights on the
database. Administrative rights are required since tables need to be created in the
Page 32
database.
If accessing a database on a different machine, the server must also be able to accept
non-local TCP connections, and the username must also be configured to accept remote
connection. For example, the "root" MySQL user entered as root@localhost is not allowed
to connect from any other machine than the one where MySQL is installed.
l
l
l
l
l
Administrator Password: Enter the password for the above user. The appropriate
MySQL password must be entered or the Connect installation will fail.
TCP/IP Port Number: Enter the port on which the database server expects connections.
For MySQL, this is 3306 by default.
Database Host Name: Enter the existing database server's IP or host name.
Server Schema/Table: Enter the name of the MySQL database into which the tables will
be created. The Connect standard name is "objectiflune".
Test Connection button: Click to verify that the information provide into previous fields is
valid by connecting to the database.
Note
This test does not check whether the remote user has READ and WRITE
permissions to the tables under the objectiflune schema. It is solely a test of
database connectivity.
PlanetPress Connect Server Configuration
The Server Configuration page is where the Connect Server component is configured.
The Connect Server settings are as follows:.
l
Run Server as: Defines the machine username and password that thePlanetPress
Connect Server module's service uses.
Note
The "Server Security Settings" on page 48 dialog can only ever be executed from
the user specified here.
Page 33
l
l
l
Username: The account that the service uses to login. If the machine is on a
domain, use the format domain\username.
This account must be an existing Windows profile with local administrator rights.
Password: The password associated with the selected user.
Validate user button: Click to verify that the entered username and password
combination is correct and that the service is able to login.
This button must be clicked and the user validated before the Next button becomes
available.
Click Next to start the actual installation process. This process can take several minutes.
Completing the installation
This screen describes a summary of the components that have been installed.
l
l
l
Configure Update Check checkbox: This option is enabled by default. It causes the
Product Update Manager to run after the installation is complete. This allows
configuring PlanetPress Connect to regularly check for entitled updates.
Note: this checkbox may not be available in the event that an issue was encountered
during the installation.
Show Log... : If an issue was encountered during the installation, click this button to
obtain details. This information can then be provided to Objectif Lune for troubleshooting.
When ready, click the Finish button to close the installation wizard, and initialize the
Product Update Manager, if it was selected.
The Product Update Manager
If the Configure Update Check option has been selected, the following message will be
displayed after clicking “Finish” in the setup:
Click “Yes” to install or open the Product Update Manager where the frequency with which the
updates can be checked and a proxy server (if required) can be specified.
Note: if the Product Update Manager was already installed by another Objectif Lune
application, it will be updated to the latest version and will retain the settings previously
specified.
Select the desired options and then click OK to query the server and obtain a list of any
updates that are available for your software.
Page 34
l
l
Note that the Product Update Manager can also be called from the “Objectif Lune Update
Client” option in the Start menu.
It can be uninstalled via Control Panel | Programs | Programs and Features.
Product Activation
After installation, it is necessary to activate the software. See Activating your license for more
information.
Technical
Before activating the software, please wait 5 minutes for the database to initialize. If the
software is activated and the services rebooted too quickly, the database can become
corrupted and require a re-installation.
How to Run Connect Installer in Silent Mode
PlanetPress Connect can be installed in a so called "silent mode" to allow an automated setup
during a company wide roll-out or comparable situations. The trigger for the Connect Installer to
run in silent mode is a text file with the fixed name install.properties, which is located either in
the same folder as the PlanetPress_Connect_Setup_x86_64.exe or in the unpacked folder of
the installer.exe.
Note
Only the installation can be run silently. Silent mode does not apply to the uninstallation.
The file needs to be a properties file with the following line types:
l
Comment Lines, starting with # (e.g. # The options to configure an external database)
l
Key=Value pairs (e.g. install.product.0 = Connect Designer)
For supported keys, please refer to the next paragraph.
Page 35
Note
install.properties file notation must follow Commons Configuration rules. Please refer to Properties
files for more details.
Required and Optional Properties
Here is an example of an install.properties file.
# Verbose logging
logging.verbose = true
# Product selection
install.product.0 = Connect Designer
install.product.1 = Connect Server
# Server settings
server.runas.username = Localadmin
server.runas.password = admin
# Database configuration
database.type = mysql
database.host = 192.168.116.10
database.port = 3308
database.username = root
database.password = admin
database.schema = my_ol
Verbose Logging (Optional)
By default, the Silent Installer will log in the same way as the GUI installer. That means
logging of error and warnings, and certain information during database configuration. A more
verbose logging can be switched on by using logging.verbose = true.
Page 36
Product Selection (Optional)
By default, the Silent Installer will install all products which are visible to the user in the
respective brand (except for the Server Extension, because only Server or Server Extension
can be installed at the same time).
However, it is possible to define the products to be installed using their visible product names,
and using a counter for the install.product property, e.g.
l
install.product.0 = Connect Designer
l
install.product.1 = Connect Server
Other possible product names are Connect Print Manager, Connect Server Extension and
MySQL Product.
Server / Extension configuration (required if Server / Extension is selected for install)
For both, Server and Server Extension, the user credentials who will be running the Server
service need to be provided:
l
server.runas.username
l
server.runas.password
Additionally for the Server Extension, some properties to define the Master Server are required:
l
server.master.host
l
server.master.port
l
server.master.authenticate = true_or_false
l
server.master.username
l
server.master.password
Database configuration
If the MySQL Product is part of the installation, the following properties should be defined:
l
database.type = mysql (required)
l
database.password (required, needs to match the security rules)
l
database.port (optional, the default is 3306. The defined port needs to be available.)
Page 37
Additional properties are required when the configuration of an external MySQL database is
required (this is the case if a Server product but not MySQL product is installed):
l
database.host
l
database.username
Optionally, the "schema" name can be defined (the default is objectiflune):
l
database.schema
Activating a License
PlanetPress Connect and PlanetPress Workflow 8 includes separate 30 day trial periods
during which it is not necessary to have a license for reviewing basic functionality. If a
modification to the license if required, such as to allow an extension to the trial period, or for
extra functionality or plugins (e.g., the PReS Plugin for Workflow 8), then a new activation code
will need to be requested.
Obtaining the PlanetPress Connect Magic Number
To obtain an activation file the OL™ Magic Number must first be retrieved. The Magic Number
is a machine-specific code that is generated based on the computer's hardware and software
using a top-secret Objectif Lune family recipe. Each physical computer or virtual computer
should have a different Magic Number, thus require a separate license file to be functional.
To get the PlanetPress Connect Magic Number, open the PlanetPress Connect Designer
application:
l
Open the Start Menu
l
Click on All Programs, then Objectif Lune, then PlanetPress Connect
l
Open the PlanetPress Connect Designer [version] shortcut.
l
When the application opens, if it has never been activated or the activation has expired,
the Software Activation dialog appears:
l
License Information subsection:
l
Magic Number: Displays the PlanetPress Connect Magic Number.
Page 38
l
l
Licensed Products subsection:
l
l
l
l
l
l
l
l
l
Name: Displays the name of the application or module relevant to this
activation.
Serial Number: Displays the activation serial number if the product has been
activated in the past.
Expiration Date: Displays the date when the activation will expire (or the
current date if the product is not activated)
Web Activations: Click to be taken to the online activation page (not yet
functional).
End-User License Agreement (Appears only when loading a license file):
l
l
Copy to Clipboard: Click to copy the Magic Number to the clipboard. It can
then be pasted in the activation request email using the CTRL+V keyboard
shortcut.
License: This box displays the EULA. Please note that this agreement is
legally binding.
I agree: Select to accept the EULA. This option must be selected to install the
license.
I don't agree: Select if you do not accept the EULA. You cannot install the
license if this option is selected.
Load License File: Click to browse to the .olconnectlicense file, once it has been
received.
Install License: Click to install the license and activate the software (only available
when a license file is loaded).
Close: Click to cancel this dialog. If a license file has been loaded, it will not
automatically be installed.
Note
The Software Activation dialog can also be reached through a shortcut located in All
Programs, then Objectif Lune, then PlanetPress Connect and is named Software
Activation. Since it does not load the software, it is faster to access for the initial activation.
Page 39
Requesting a license
After getting the Magic Number, a license request must be done for bothPlanetPress Connect
and Workflow 8:
l
l
Customersmust submit their Magic Number and serial number to Objectif Lune via the
Web Activations page: http://www.objectiflune.com/activations. The OL Customer Care
team will then send the PlanetPress Connect license file via email.
Resellerscan create an evaluation license via the Objectif Lune Partner Portal by
following the instructions there: http://extranet.objectiflune.com/
Note that if you do not have a serial number, one will be issued to you by the OL Activations
team.
Accepting the license will activate it, after which the PlanetPress Connect services will need to
be restarted. Note that in some case the service may not restart on its own. To resolve this
issue, restart the computer, or start the service manually from the computer's Control Panel.
Activating PlanetPress Workflow 8
PlanetPress Workflow 8 uses the same licensing scheme as PlanetPress Connect. There are
two ways of activating the license for Workflow 8 after saving it to a suitable location:
l
l
If only PlanetPress Workflow 8 is installed, double-click on the license for the PlanetPress
Workflow 8 License Activation dialog to open. Applying the license here activates all of
the Workflow 8 components.
If you have both PlanetPress Workflow 8 and PlanetPress Connect installed, it will not be
possible to double-click on the license file as this will always open the PlanetPress
Connect Activations Tool. Instead, open PlanetPress Workflow 8 manually and apply the
license through the activations dialog within.
Activating PlanetPress Connect
To activate PlanetPress Connect, simply save the license file somewhere on your computer
where you can easily find it, such as on your desktop. You can then load the license by doubleclicking on it, or through the start menu:
l
Open the Start Menu
l
Click on All Programs, then Objectif Lune, then PlanetPress Connect
Page 40
l
Open the PlanetPress Connect Designer [version] shortcut. The “PlanetPress Connect
Software Activation” tool displays information about the license and the End-User License
Agreement (EULA).
l
Click the Load License File button.
l
Read the EULA and click I agree option to accept it.
l
Click Install License to activate the license. The license will then be registered on the
computer and you will be able to start using the software.
Warning
After installation message will appear warning that the Server services will need to be restarted. Just
click OK to proceed.
Migrating to a new computer
Currently there are no special migration tools to move data from one PlanetPress Connect
installation to another.
Instructions for migration will be available for later versions of the software when those tools
become available.
Information about PlanetPress Workflow 8
If you wish to use PlanetPress Workflow (automation) in conjunction with PlanetPress Connect,
you will need to install PlanetPress Workflow 8 onto the same machine. Workflow 8 is provided
through a separate installer which is available on CD or for download as follows:
l
l
If you are a Customer, the installer can be downloaded from the Objectif Lune Web
Activations page: http://www.objectiflune.com/activations
If you are a Reseller, the installer can be downloaded from the Objectif Lune Partner
Portal: http://extranet.objectiflune.com/
PlanetPress Workflow 8 can be installed in parallel on the same machine as an existing
PlanetPress® Suite 7.x installation. Note however:
l
If both versions need to be hosted on the same machine, PlanetPress Workflow 8 should
always be installed after the legacy PlanetPress® Suite 7.x installation.
Page 41
l
l
l
l
When uninstalling PlanetPress Workflow 8, you may be prompted to repair your legacy
PlanetPress® Suite 7.x installation.
If PlanetPress Workflow 8 has been installed alongside PlanetPress® Suite 7, Capture
can no longer be used with Workflow 7. The plugins are now registered uniquely to
Workflow 8 and the messenger for Workflow 7 is taken offline. It is only then possible to
use Capture from PlanetPress Workflow 8.
PlanetPress Workflow 8 and PlanetPress® Workflow 7 cannot run simultaneously, since
only one version of the Messenger service can run at a time. In fact, no 2 versions of
PlanetPress Workflow can on the same machine simultaneously, whatever version is
installed.
It is possible to switch between different versions running by shutting down one version's
services and then starting the other. However, this is not recommended. There are no
technical limitations that prevent processes from previous PlanetPress Workflow versions
(as far back as Version 4) to run on PlanetPress Workflow 8, removing the need to run
both versions.
For more information on the licensing of Workflow 8, please see Activating your license.
Upgrading from PlanetPress Suite 7.6
Note
This document is intended for people who already received their upgrade to PlanetPress Connect.
They should already have their new serial number(s) in hand and the PlanetPress Connect installers.
With the release of PlanetPress Connect, Objectif Lune’s innovative new technology, existing
users of PlanetPress Suite version 7 and 6 have the possibility to migrate to an introductory
version of PlanetPress Connect called “PlanetPress Connect Print-Only”.
This migration benefits existing users in many ways and has limited impact on their current
processes and how they use PlanetPress Suite version 7 and 6.
This document provides information on the migration process and the requirements and
considerations for existing PlanetPress Suite users to upgrade to the latest generation of our
products.
Page 42
Note
PlanetPress Connect Print-Only is available for existing users of PlanetPress version 7 or 6 with a
valid OL Care agreement. If you are using a previous version or are not covered by OL Care,
please contact your reseller or your Objectif Lune Account Manager for more information.
What does PlanetPress Connect Contain?
PlanetPress Connect is comprised of the following modules:
l
PlanetPress Workflow 8. This is the natural evolution of PlanetPress® Workflow 7
(Watch, Office or Production). PlanetPress Workflow 8 is very similar to PlanetPress®
Workflow 7 version but contains new features and has the ability to run PlanetPress
Connect, PlanetPress Suite, PrintShop Mail and PReS Documents.
o
o
l
l
Imaging for PlanetPress Connect is available as an option. It contains:
l
PlanetPress Fax
l
PlanetPress Image
l
PlanetPress Search
PlanetPress Capture is still supported in PlanetPress Workflow 8 but only with
documents created with the PlanetPress Design 7.
PlanetPress Connect Designer. This is the design tool based on completely new
technology. It is not backwards compatible and therefore cannot open PlanetPress
Design 7 documents. If you need to continue editing those documents you can keep
doing so in PlanetPress Design 7.
PlanetPress Connect Server. This is the core of the Connect technology. This new
module automates the merging of data with your new templates and generates the output.
It is required for PlanetPress Workflow 8 to handle templates created with the
PlanetPress Connect Designer. It can be installed on the same or a different machine as
PlanetPress Workflow 8.
IMPORTANT: PlanetPress Connect does not contain the PlanetPress Design 7.
GOOD NEWS: PlanetPress Connect does not need any printer licenses to print from
PlanetPress Connect or PlanetPress Suite. It can also print PrintShop Mail 7 and PReS 6
documents if these programs are licensed.
Page 43
You can keep everything you have
The first thing to know is that you can keep your current PlanetPress Workflow 7 configuration
and your PlanetPress Design documents. When upgrading to PlanetPress Connect, they will
remain functional.
Please note that PlanetPress Workflow 7 and PlanetPress Workflow 8 cannot run at the same
time. See Information about PlanetPress Workflow 8 for information about these limitations. The
only exception is the PlanetPress Suite Design tool that you can continue to use as it is not part
of PlanetPress Connect.
For customers upgrading to the free “Print only” version, if you wish you to continue your OL
Care engagement, the next year will be priced at the same price as your current price.
For customer upgrading to the full version of PlanetPress Connect, with or without new options,
the next year of OL Care will be priced at the value of the new software you upgraded to.
Before going into any further details, please read the following section carefully.
PlanetPress Connect installation considerations
PlanetPress Suite could run by default on a computer with a minimum of 1GB of RAM
available. The PlanetPress Connect Server with PlanetPress Workflow 8, by default, requires 8
GB of RAM but if you intend on using the new PlanetPress Connect Designer on the same
computer, you should consider having at least 12 GB of RAM available. See System
requirements.
Distributed installation or not
You can decide to install PlanetPress Connect modules all on the same computer or have each
module on a different computer. Reasons for this could be:
l
l
There is insufficient memory in the computer currently running PlanetPress Workflow 8 to
also run PlanetPress Connect Server.
You want to use a more powerful computer with more RAM and more cores to run the
Server to achieve maximum performance.
Page 44
What do I gain by upgrading to PlanetPress Connect?
PlanetPress Watch users
When upgrading to PlanetPress Connect, you receive key features of PlanetPress Office such
as the following:
l
l
l
l
Ability to input data from PDF
Ability to print your PlanetPress Suite documents on any Windows printer (no need for
printer licenses)
Ability to create standard PDF output from your PlanetPress Suite documents
Even if you don’t recreate your existing PlanetPress Suite documents, you can easily
change your workflow to convert your output to PDF, then output them in PCL to any
device supporting it.
NOTE: If you were a PlanetPress Production user, you retain all functionalities within
PlanetPress Workflow 8. These are automatically imported during the activation (see below).
Re-purpose your existing documents
IMPORTANT: PlanetPress Suite users covered by a valid OL Care contract receive a “Print
only” version of PlanetPress Connect which can produce printed output. If you also own
PlanetPress Imaging, which can produce PDF, Tiff and other archive formats, you will also
receive a new version.
The full version of PlanetPress Connect can open your company to the digital world by
enabling you to send HTML responsive emails as well as creating dynamic responses and
interactive web pages. All that for a minimal fee. For more information on the full version of
PlanetPress Connect, contact your reseller or your Objectif Lune Account Manager.
Upgrade to the full multi-channel version and expand onto the Web
If you choose to take the optional “multi-channel” upgrade, you can start right away to reuse the
content of your existing documents and map it onto responsive documents that can be sent by
email in full HTML glory and/or make them available as native HTML web pages using the
latest CSS/JavaScript features.
IMPORTANT: If you owned them, you must also upgrade your Imaging modules to use the new
PReS version.
Page 45
Create new documents and integrate them into your workflow at your own pace
You can start benefiting from the innovative technology of the new PlanetPress Connect
Designer right away by designing new documents, or re-doing existing ones at your own pace.
With PlanetPress Connect Print-Only, you can now:
l
l
l
Use the new Data Mapper to easily map any input data into a clean data model that any
designer person can use
Easily create documents with tables that spread over multiple print pages, respecting
widow and orphan rules, displaying sub-totals and totals properly
Have text that wrap around images
Upgrade steps
1. To upgrade to PlanetPress Connect, the first step is to stop your PlanetPress Workflow
services. You can do so from the PlanetPress Workflow configuration tool or from the
Windows Service Management console.
2. Then, using the PlanetPress Connect setup, install the Designer and/or Server on the
appropriate computers. Then, using the PlanetPress Workflow 8 setup, install
PlanetPress Workflow and/or PlanetPress Image on the appropriate computers. (See the
installation and activation document for more details)
3. If you installed PlanetPress Workflow 8 on the same computer where you had
PlanetPress Suite Workflow 6 or 7, you can use the Upgrade Wizard to import your:
l
PlanetPress Workflow:
l
Processes configuration
l
PlanetPress Suite compiled documents
l
Service configuration
l
Access manager configuration
l
Custom plug-ins
l
PlanetPress Fax settings
l
PlanetPress Image settings
l
PlanetPress Search profiles
l
Printer activation codes
l
PlanetPress Capture database
l
PlanetPress Capture pen licenses
Page 46
l
Custom scripts
l
Content of your virtual drive
l
PlanetPress Messenger configuration
If you installed PlanetPress Workflow 8 on a different computer, contact support for
help importing all those settings, if you wish to import them.
4. To launch the Upgrade wizard, open the PlanetPress Workflow 8 configuration tool and,
from the Tools menu, launch the Upgrade Wizard.
IMPORTANT: Before you start this process, make sure you have a backup of your current
installation/computer.
5. Then select your upgrade type:
6. Then select the product from which you wish to upgrade:
7. If you selected to do a Custom upgrade, select the required options:
8. Then finally review the log in the final dialog for details on how it went:
9. After that you will need to get the activation file for your product.
To obtain your activation, download the PlanetPress Connect installer from the Web
Activation Manager, follow the instructions for the installation using the serial number
provided to you. You can activate your license through the Web Activation Manager.
10. From now on, if you need to modify your PlanetPress Design documents, simply open
PlanetPress Design 6 or 7, edit your document and send the updated version to
PlanetPress Workflow 8. In order to do that:
Page 47
l
l
If you have the PlanetPress Design on the same computer as the PlanetPress
Workflow 8, you need to save the documents to PTK by using the “Send to” menu,
then "PlanetPress Workflow”, and there use the “Save to file” button. Then, from the
PlanetPress Workflow 8 configuration tool, in the “Import” menu, select “Import a
PlanetPress Document” and select the previously saved file.
If you have the PlanetPress Design on a computer and the PlanetPress Workflow 8
on another, you can simply use the “Send to” menu in the Designer and select the
PlanetPress Workflow 8 to which you want to send the PlanetPress Design
document.
Server Settings
This chapter describes the different considerations that are important in regards to the use of
PlanetPress Connect Server.
l
"Server Security Settings" below
l
"Server Extension Settings" on the next page
Server Security Settings
This dialog controls the security settings for external applications connecting to the PlanetPress
Connect Server, such as PlanetPress Workflow or scripts communicating through the REST
API.
Warning
It is highly recommended to keep security enabled and change the password on any server that
accessible from the web. If these precautions are not taken, data saved in the server may be
accessible from the outside!
l
l
Enable server security: Enable to add authentication to the REST server. When
disabled, a username and password is not required to make REST request, and tasks in
PlanetPress Workflow does not require them in the Proxy tab.
Administrator's username: Enter the username for the server security. The default
username is ol-admin.
Page 48
l
l
l
Administrator's password: Enter a password for the server security. The default
password is secret.
Confirm password: Re-enter the password for the server security.
Default session length (min): Enter a session time (in minutes) that the authentication
stays valid for the requested process. This can reduce the number of requests to the
server since an authentication request is not necessary during the session.
Server Extension Settings
This dialog controls the different settings for the PlanetPress Connect Server Extension.
The Preferences dialog is separated into individual pages, where each page controls certain
aspects of the software.
The following Preferences pages are available:
l
l
l
"Clean-up Service preferences" on page 575
"Server Extension Scheduling Preferences" on page 52 (these are different in the Server
Extension preferences)
l
Merge Engine Scheduling
l
Weaver Engine Scheduling
"Server Security Settings" on the previous page
Server Clustering
Server Clustering, available in PlanetPress Connect, enhances the processing capabilities of
PlanetPress Connect Server by load-balancing jobs between the main Server module (master)
and one or more Server Extension installations.
Setting up Server Clustering requires two or more installations of PlanetPress Connect on
separate machines. The Master server is setup by installing the PlanetPress Connect Server
module during the Installation Wizard, while the Slave Server is setup by installing the
PlanetPress Connect Server Extension module instead.
Page 49
Quick Howto
1. Install the Master server (PlanetPress Connect Server module), making sure to select the
MySQL module.
2. Set the appropriate bindings in MySQL's my.ini file on the Master server.
3. Grant access to the MySQL root user for the appropriate IP range on the Master server.
4. Restart the MySQL Service on the Master server.
5. Install Slave servers (PlanetPress Connect Server Extension module).
6. Install the license on the Master server (a Performance Pack license is required).
7. Set the preferences for the engines (see Scheduling Preferences) on both the Master and
Slaves
8. Install the license on the Slave servers
9. Restart the Master server then, once restarted, restart the Slave servers.
What if MySQL is not on the Master server?
It is possible to setup clustering with a MySQL instance that is on a Slave server instead of on
the master. In this case, the Slave server must be installed with the Server Extension and
MySQL modules, the MySQL instance configured (steps 2-4 above) then the master and other
slaves can be installed. The remainder of the instructions remain the same.
It is also possible to setup clustering with MySQL being installed completely separately from
PlanetPress Connect, such as using an existing MySQL instance. In this case, the instructions
for the bind address must be followed, but the user does not have to be root. A user for MySQL
must, however, be created and have full access (GRANT ALL PRIVILEGES) to a database
called "objectiflune" that can be created before Connect is installed.
Binding and Root access on the Master server
l
The MySQL server's binding must be set to accept connections from the slave servers. To
do this, open C:\Program Files\Objectif Lune\OL Connect\MySQL Product\MySQL\my.ini
in a text editor and change the line bind-address= 127.0.0.1 to bindaddress=0.0.0.0.
Once the changes have been made and saved you need to restart the OLConnect_
MySQL service from within the Windows Services dialog.
Page 50
l
Access must be granted to the root user on the IPs from which the Slave server will
connect:
l
Open a Command Prompt in the following folder:
C:\Program Files\Objectif Lune\OL Connect\MySQL Product\MySQL\bin
Tip
Navigate to the folder, SHIFT+Right-click, and then select "Open a command
prompt here".
l
l
Type in the following command to connect to the database, where is
your MySQL password (by default it is admin):
mysql --user=root --password= objectiflune
You should see the prompt become mysql>.
Here, type the command to allow the "root" user to be accessed from a specific IP
subnet range.
For example, to accept communication on 192.168.*.*, use:
GRANT ALL PRIVILEGES ON objectiflune.* TO
'root'@'192.168.0.0/255.255.0.0' IDENTIFIED BY 'password';,
where password is the one provided during installation.
( ref: http://dev.mysql.com/doc/mysql-security-excerpt/5.5/en/adding-users.html)
Technical
IP Subnets understanding is beyond the scope of this documentation. If you want to learn more,
please see the Subnetwork article on Wikipedia.
Clustering Preferences and Setup
When server extensions are installed and connected to a Master, the following options and
settings change in availability or behavior:
l
In the Scheduling Preferences of the Slave, both "Maximum Records" are ignored.
Scheduling is handled by the Master.
Page 51
l
The "Expected Remote Merge Engine" and "Expected Remote Weaver Engine" in Merge
Engine Scheduling and Weaver Engine Scheduling respectively, on the Master, should
each equal the total number of engines in all the slaves combined.
l
l
l
l
For example, the Expected Remote Merge Engine on the Master should equal the
total of "Local Engines Launched" for each slave.
If the number of expected remote engines is lower than the actual number,
performance will not be optimal.
If the number of expected remote engines is higher than the actual number, jobs
may fail and not complete.
Cleanup Service requires special configuration on Clustering setups:
l
l
Cleanup service should not run simultaneously on all machines (staggered
cleanup). Doing so may cause jobs not to be processed since all servers are busy.
Only the machine where the MySQL Server product is installed should attempt to
cleanup database items. Essentially server that do not have MySQL should only run
Orphan File Cleanup.
Server Extension Scheduling Preferences
The Server Extension Scheduling Preferences define the PlanetPress Connect Server
connection settings.
l
l
l
l
Location of the master server: Enter the location and port of the main PlanetPress
Connect Server module in the hostname:port format. For example, 192.168.100.123:9340
or connect-master:9340.
Username: Enter the username expected by the PlanetPress Connect Server.
Password: Enter the password expected by the PlanetPress Connect Server for the
selected username.
Note that Maximum records in a small job and Minimum records in a large job are not
used in Server Extensions. All server scheduling is handled by the Master.
Uninstalling
This topic provides some important information about uninstalling (removing) PlanetPress
Connect1.5.
Page 52
To uninstall PlanetPress Connect select the application from within the Add/Remove programs
option under the Control Panel. This will start the PlanetPress Connect Setup Wizard in
uninstall mode.
Note
The PlanetPress Connect Setup Wizard might take some seconds to appear.
Important Note: Stop any Anti-Virus Software before
uninstalling Connect.
Some anti-virus systems are known to block the uninstallation of MySQL datafiles, as well as
blocking the uninstallation of the MySQL database application itself. Therefore it is highly
recommended that any anti-virus application be stopped prior to uninstalling PlanetPress
Connect, as otherwise the Connect uninstallation might not work correctly.
Impacts upon other Applications and Services
l
l
The Uninstall will terminate the installed Server / MySQL service(s)
The following applications / services should be stopped in a controlled fashion, before
running the PlanetPress Connect Uninstall:
1. PlanetPress Connect
2. Any Connect Workflow using PlanetPress Connectplugins which connect to this
server.
3. PlanetPress Connect Server Extensions on remote systems which connect to this
machine as the Master Server.
4. Connect products on remote systems which refer to this MySQL database.
Uninstallation Wizard
The uninstallation is done by running the PlanetPress Connect Setup Wizard in uninstall mode.
The Wizard consists of the following pages:
1. PlanetPress Connect SetupAn information page, listing what will be uninstalled, and
also warning about impacts upon running Applications and Services.
Page 53
2. Data Management: A page that provides options for backing up or deleting Connect
data. Selections are as follows:
l
Delete Connect Workspace Data: Check this box to delete the Workspace data for
the current user, or for selected users (as determined by the "Select Users" button)
l
l
Backup Connect Workspace Data for all specified Users: Check this box
to backup the Workspace data for the specified users (as previously
determined) into a compressed ZIP file (whose location can be customized),
before deletion of the full Workspace data.
Delete MySQL objectlune Data: Check this box to delete the MySQL database
installed with PlanetPress Connect.
l
Backup MySQL Date: If the deletion check box is selected, this option
appears to allow backing up the MySQL database to a customizable location,
prior to uninstallation.
Page 54
The DataMapper Module
The DataMapper is the tool to extract your data and transpose it into a format (a Unified Data
Model or UDM) that will allow it to be shared amongst different layouts and outputs created with
the Connect Designer. This UDM is a generic format with an emphasis on content, free from
any restrictions imposed by the file types or the origin of the data. This UDM also allows a same
layout or output to be populated with data from different sources and formats without the need to
modify it.
The original data, located outside of Connect, whether it’s a file or a database is called a Data
Source. The DataMapper doesn’t use the Data Source directly, rather it uses a copy of that data
called the Data Sample. Although the Data Sample is a copy, it is updated each time the data
mapping configuration is opened or whenever the Data Sample is selected.
The first step in the data extraction process is setting Boundaries for each record inside the
data sample. As an example, “Page 1 of…” in a PDF could be used as a “signal” to indicate the
beginning of a new record. When you define the boundaries, you are actually defining a series
of records inside your data sample file. You can then start working on the logic to extract data
from each of those records (see Configuring the settings for more information). Once you know
where each record begins and ends, you need to identify and extract data from each record. To
achieve this, you will create a process consisting of multiple steps (extraction, loops and
conditions) (see Extracting Data for more information). When this process is complete, the
result is a Data Model.
This Data Model contains all the necessary information to add variable data to Connect
Designer templates. (see Data Model for more information).
Basics
Connect’s DataMapper lets you extract data from a variety of files and creating Data Mapping
Configuration file. The Data Mapping Configuration can then be used to add variable data to
Connect Designer templates.
1. Create a new Data Mapping configuration.
Start creating a Data Mapping configuration by selecting the Data Source. You can do
this manually or using one of the wizards. See Creating a new Data Mapping
configuration.
Page 55
2. Configure settings for the data source.
Configure how the Data Sample is read by the DataMapper so it can delimit each record
in the file (using Delimiters). See Data Source.
3. Configure the data extraction workflow.
Configure the workflow steps that will be required to extract the data from the Data source
to the Data Model. This way, data will be converted and prepared to be used by the
Designer module. To learn more, see Data Extraction.
4. Editing the Data Model.
In this step you can change the data type of fields, add fields, use JavaScript to change
the value of a field and much more. To learn more, see The Data Model Interface.
What's Next?
Use the Designer module to create templates for personalized customer communications. To
learn more, see The Designer Module.
Data Mapping Configuration
A Data Mapping Configuration file can refer to either the current active configuration in the
DataMapper, or a file on disk containing the information necessary for data mapping. It contains
the extraction workflow (steps), Delimiter and Boundary Settings, and any imported Data
Samples.
Creating A New Data Mapping Configuration
You can create a new Data Mapping configuration from a data file by using a wizard or
manually.
From a File
When creating a data mapping configuration from a file, you first select the file you want to
extract the data from. As opposed to using a wizard, you will later need to configure the settings
to extract the data. Please refer to Configuring Settings For The Data Source for more
information.
To create a Data Mapping from a file, use the following steps:
Page 56
From the Welcome screen
1. Open the PlanetPress ConnectWelcome page by clicking the icon at the top right or
select the Help menu and then Welcome.
2. Click Create a New Configuration.
3. From the From a file pane, select the file type (CSV, MS-Access, PDF/VT, Text or XML).
4. Click the Browse button and open the file you want to work with (for a database, you may
have to enter a password).
5. Click Finish.
From the File menu
1. Click the File menu and select New.
2. Click the Data mapping Configuration drop-down and select Files and then the file
(CSV, MS-Access, PDF/VT, Text or XML)..
3. Click Next.
4. Click the Browse button and open the file you want to work with.
5. Click Finish.
Note
PCL and PostScript (PS) files are automatically converted to PDF format before showing that PDF
in the Data Viewer. This happens once when opening the file, but in the Workflow it happens for
every file. Depending on the processing power available, this may influence the processing speed.
Using a Wizard
The DataMapper module wizards are basically shortcuts to help get started and quickly create
a data mapping configuration. The data mapping wizards are only available for CSV and
database tabular files as well as PDF/VT, because these files contain metadata that can be
used to automatically set boundaries.
When using a wizard to create a new data mapping configuration, you select the file you want
to extract the data from, and the wizard automatically selects the appropriate settings for
extracting the data. All fields are automatically extracted.
Page 57
For A CSV File
The DataMapper Wizard will guide you through setting the data mapping configuration in three
steps. The first step, is to select the data file. The Data Mapper will allow you to verify that the
right data file is being used by giving you a preview of the raw data inside the file. The second
will then display the different settings it has detected and allow you to change them. A preview
window of the extracted data helps you with choosing the settings. For the third step, click
Finish to extract all the fields inside your file.
To create a Data Mapping from a CSV file using the wizard, use the following steps:
From the Welcome screen
1. Open the PlanetPress ConnectWelcome page by clicking the
select the Help menu and then Welcome.
icon at the top right or
2. Click Create a New Configuration.
3. From the Using a wizard pane, select CSV.
4. Click the Browse button and open the CSV file you want to work with.
l
l
Take a look at the Preview box content to ensure that the file is the right one and the
encoding correctly reads the data.
Click Next.
5. From the Select a CSV Configuration dialog, choose the proper settings:
Note
These settings are generally detected automatically.
l
Encoding: Choose the correct encoding to read the file.
l
Separator: Defines what character separates each fields in the file.
l
Comment Delimiter: Defines what character starts a comment line.
l
Text Delimiter: Defines what character surrounds text fields in the file, preventing
the Field Delimiter from being interpreted within those text delimiters.
Page 58
l
l
Ignore unparseable lines: Ignores any line that does not correspond to the settings
above.
First row contains field names: Uses the first line of the CSV as headers, which
automatically names all extracted fields.
6. Verify that the data is read properly and click Finish.
From the File menu
1. Click the File menu and select New.Click the Data mapping Data mapping Wizards
drop-down and select From CSV File.
2. Click Next.
3. Click the Browse button and open the CSV file you want to work with.
l
l
Take a look at the Preview box content to ensure that the file is the right one and the
encoding correctly reads the data.
Click Next.
4. From the Select a CSV Configuration dialog, choose the proper settings:
Note
These settings are generally detected automatically.
l
Encoding: Choose the correct encoding to read the file.
l
Separator: Defines what character separates each fields in the file.
l
Comment Delimiter: Defines what character starts a comment line.
l
l
l
Text Delimiter: Defines what character surrounds text fields in the file, preventing
the Field Delimiter from being interpreted within those text delimiters.
Ignore unparseable lines: Ignores any line that does not correspond to the settings
above.
First row contains field names: Uses the first line of the CSV as headers, which
automatically names all extracted fields.
5. Verify that the data is read properly and click Finish.
Page 59
For a Database File
To create a Data Mapping from a Database file using the wizard, use the following steps:
From the Welcome screen
1. Open the PlanetPress ConnectWelcome page by clicking the
select the Help menu and then Welcome.
icon at the top right or
2. Click Create a New Configuration.
3. From the Using a wizard pane, select Database.
4. Use the drop-down to select the Database type.
5. Click Next.
From the File menu
1. Click the File menu and select New.Click the Data mapping Data mapping Wizards
drop-down and select From databases.
2. Click Next.
3. Use the drop-down to select the Database type.
4. Click Next.
Now set the following properties according to the selected database:
MySQL
l
Server: Enter the server address for the MySQL database.
l
Port: Enter the port to communicate with the MySQL server. The default port is 3306.
l
l
l
l
Database name: Enter the exact name of the database from where the data should be
extracted.
User name: Enter a user name that has access to the MySQL server and specified
database. The user only requires Readaccess to the database.
Password: Enter the password that matches the user name above.
Table name: The selected database is a set of related tables composed of rows and
columns corresponding respectively to source records and fields. Select a table from
which you want to extract data.
Page 60
l
Encoding: Choose the correct encoding to read the file.
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
Microsoft Access
l
Click the Browse button and open the database file you want to work with.
l
Password: Enter a password if one is required.
l
Click Next.
l
Table name: The selected database is a set of related tables composed of rows and
columns corresponding respectively to source records and fields. Select a table from
which you want to extract data.
l
Encoding: Choose the correct encoding to read the file.
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
SQL Server
l
Server: Enter the server address for the SQL Server database.
l
Port: Enter the port to communicate with the SQL Server server. The default port is 3306.
l
l
l
l
Database name: Enter the exact name of the database from where the data should be
extracted.
User name: Enter a user name that has access to the SQL Server server and specified
database. The user only requires Readaccess to the database.
Password: Enter the password that matches the user name above.
Table name: The selected database is a set of related tables composed of rows and
columns corresponding respectively to source records and fields. Select a table from
which you want to extract data.
l
Encoding: Choose the correct encoding to read the file.
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
ODBC DataSource
l
ODBC Source: Use the drop-down to select an ODBC System Data Source. This must
be a data source that has been configured in the 64-bit ODBC Data Source Administrator,
as PlanetPress Connect is a 64-bit application and thus cannot access 32-bit data
Page 61
sources.
l
This ODBC source is MSSQL: Check this option if the ODBC source is MSSQL (SQL
Server). The options below appear under MSSQL-ODBC advanced configuration:
l
l
Windows authentication: Select to use the Windows User name and Password
that are used by the Connect Service.
SQL Server authentication: Select to use the User name and Password set below
to connect to the SQL Server:
l
User name: Enter the SQL Server user name.
l
Password: Enter the password for the above user name.
l
Click Next.
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
JDBC
Note
Since JDBC can connect to multiple types of databases, a specific database driver and path to
this driver's JAR file must be specified.
l
l
l
l
l
l
l
l
JDBC Driver: Use the drop-down to select which JDBC Driver to use for the database
connection.
JAR file path: Enter a path to the JAR file that contains the appropriate driver for the
database below.
Server: Enter the server address for the database server.
Database name: Enter the exact name of the database from where the data should be
extracted.
User name: Enter a user name that has access to the server and specified database. The
user only requires Readaccess to the database.
Password: Enter the password that matches the user name above.
Advanced mode: Check to enable the Connection String field to manually enter the
database connection string.
Connection string: Type or copy in your connection string.
Page 62
l
Click Next
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
Oracle
l
Server: Enter the server address for the Oracle database.
l
Port: Enter the port to communicate with the Oracle server. The default port is 3306.
l
l
l
l
Database name: Enter the exact name of the database from where the data should be
extracted.
User name: Enter a user name that has access to the Oracle server and specified
database. The user only requires Readaccess to the database.
Password: Enter the password that matches the user name above.
Table name: The selected database is a set of related tables composed of rows and
columns corresponding respectively to source records and fields. Select a table from
which you want to extract data.
l
Encoding: Choose the correct encoding to read the file.
l
Click Finish to close the dialog and open the actual Data Mapping configuration.
For a PDF File
When you open a PDF/VT within the Wizard, it actually gives you the options to set the
boundaries directly. Then you need to select the record or the level at which you have a new
Source Record. We also need to select what we want to extract. What the PDF Wizard will do
is extract the fields that were selected and set the boundaries automatically On metadata as
we can see in the boundary settings. Of course as with any PDF data file, you do have the
ability to extract more information afterwards.
To create a PDF/VT file data mapping configuration using the wizard, use the following steps:
From the Welcome screen
1. Open the PlanetPress ConnectWelcome page by clicking the
select the Help menu and then Welcome.
icon at the top right or
2. Click Create a New Configuration.
3. From the Using a wizard pane, select PDF/VT.
4. Click the Browse button and open the PDF/VT file you want to work with. Click Next.
Page 63
5. In the Metadata page, select the following options:
l
l
Metadata record levels: Use the drop-down to select what level in the metadata
defines a Source Record.
Field List: This list displays all fields in all levels of the PDF/VT metadata.
l
Checkmark: Check any field to add it to the extraction.
l
Record Level: Displays the level on which the field is located.
l
Property name: Displays the field names to extract.
6. Click Finish to close the dialog and open the actual Data Mapping configuration).
From the File menu
1. Click the File menu and select New.
2. Click the Data mapping Wizards drop-down and select From PDF/VT or AFP.
3. Click Next.
4. Click the Browse button and open the PDF/VT file you want to work with. Click Next.
5. In the Metadata page, select the following options:
l
l
Metadata record levels: Use the drop-down to select what level in the metadata
defines a Source Record.
Field List: This list displays all fields in all levels of the PDF/VT metadata.
l
Checkmark: Check any field to add it to the extraction.
l
Record Level: Displays the level on which the field is located.
l
Property name: Displays the field names to extract.
6. Click Finish to close the dialog and open the actual Data Mapping configuration).
From a XML File
To create a XML file data mapping configuration, use the following steps:
From the Welcome screen
1. Open the PlanetPress ConnectWelcome page by clicking the
select the Help menu and then Welcome.
icon at the top right or
Page 64
2. Click Create a New Configuration.
3. From the Using a wizard pane, select XML.
4. Click the Browse button and open the XML file you want to work with. Click Next.
5. In the Select split level and trigger type page, select the following options:
l
l
XML Elements: A list of node elements that have children nodes. Select the level in
the data that will define the Source Record (for example Invoice, Customer ID,
Item...etc as opposed to Last name, Due date...etc).
Trigger: According to the node element path selected in the XML Elements field,
select On element to create a record in the Data mapping for each occurrence of
the element. Or you can select On change to create a record each time the element
is different.
6. Click Finish to close the dialog and open the Data Mapping configuration.
From the File menu
1. Click the File menu and select New.Click the Data mapping Wizards drop-down and
select From XML File.
2. Click Next.
3. Click the Browse button and open the XML file you want to work with. Click Next.
4. In the Select split level and trigger type page, select the following options:
l
l
XML Elements: A list of node elements that have children nodes. Select the level in
the data that will define the Source Record (for example Invoice, Customer ID,
Item...etc as opposed to Last name, Due date...etc).
Trigger: According to the node element path selected in the XML Elements field,
select On element to create a record in the Data mapping for each occurrence of
the element. Or you can select On change to create a record each time the element
is different.
5. Click Finish to close the dialog and open the Data Mapping configuration.
To Generate Counter
Generate counters is basically a way to create a series of sequential numbers. If, for instance,
you need to create sequential tickets or anything that has an ID that changes on each record,
Page 65
you can set all the parameters here. Enter the starting number, how it should be incremented,
the amount required, a suffix, a prefix or if padding is needed.
Note
You can’t join this configuration to another data file. It is just a counter to be applied on a static
template.
l
l
l
l
l
l
l
Starting Value: The starting number for the counter. Defaults to 1.
Increment Value: The value by which to increment the counter for each record. For
example, an increment value of 3 and starting value of 1 would give the counter values of
1, 4, 7, 10, [...]
Number of records: The total number of counter records to generate. This is not the end
value but rather the total number of actual records to generate.
Padding character: Which character to add if the counter's value is smaller than the
width.
Width: The number of digits the counter will have. If the width is larger than the current
counter value, the padding character will be used on the left of the counter value, until the
width is equal to the set value. For example for a counter value of "15", a width of "4" and
padding character of "0", the value will become "0015".
Prefix: String to add before the counter, for example, adding # to get #00001. The prefix
length is not counted in the width.
Suffix: String to add after the counter. The suffix length is not counted in the width.
Opening a Data Mapping Configuration
There are two ways you can open a data mapping configuration:
l
l
In the Menus, click on File, Open, ensure that the file type is either DataMapper files or
Connect files. Browse to the configuration file to open, select it and click Open.
In the Menus, click onFile, Open Recent, and select one of the recently opened
configuration files.
Saving a Data Mapping Configuration
To save a data mapping configuration:
Page 66
1. In the Menus, click on File, thenSave, orclick theSave button in theToolbars.
2. If the data mapping configuration has never been saved, browse to the location where the
data mapping configuration should be saved and type a name, then click Save.
To save a copy of a data mapping configuration under a different name:
1. In the Menus, click on File, thenSave As.
2. Browse to the location where the data mapping configuration should be saved and type a
name, then click Save.
Data Mapping Workflow
A data mapping workflow is a series of steps used to process and extract the data from Source
Records and store them into Records (see Data Model). Together with the data model, it is
what makes a data mapping configuration (See Data Mapping Configuration).
A data mapping workflow always starts with the Preprocessor step and ends with the
Postprocessor step. It can contains as many steps as needed for extracting the required data.
When working with a data mapping workflow, you need to consider the following:
l
l
Promotional versus transactional data: Depending on the type of data, whether it is
promotional or transactional, you will use different extraction workflows. See About
Promotional and Transactional Data for more information.
Steps: To extract data from the data sample, different steps are used that make up the
extraction process. See Steps for more information.
Selecting Data
In order to extract the data, it is necessary to first define the data to be extracted by selecting it.
The following topics contain information about how to create and manipulate a data selection,
and also how to create steps from it.
From a Text File
The Text data viewer displays the text-based contents of the Data Sample that is currently
active within the data mapping configuration in a grid-like fashion, with each character in the file
Page 67
being in a separate grid position.
To select data, click on a starting character within the grid, keeping the mouse button down,
dragging to the end character and releasing the button. This creates a data selection that can
contain multiple lines.
From a PDF File
The PDF data viewer displays the PDF file contents of the Data Sample that is currently active
within the data mapping configuration as pages.
To select data, click on a starting point, keeping the mouse button down, dragging to the end
location and releasing the button. This creates a data selection that can contain multiple lines.
Page 68
From a CSV or a Database File
The CSV/Database data viewer displays the field-based contents of the Data Sample that is
currently active within the data mapping configuration in a grid-like fashion, with each field
being in a separate grid position.
To select data, click on a starting point, keeping the mouse button down, dragging to the end
location and releasing the button. This creates a data selection that can contain multiple lines.
Page 69
From a XML File
The XML data viewer displays the XML-based contents of the Data Sample that is currently
active within the data mapping configuration in a tree view, with XML fields displayed at each
level of the Sample Record.
To select data, click on a starting point, keeping the mouse button down, dragging to the end
location and releasing the button. This creates a data selection that can contain multiple lines.
Page 70
Manipulating a Data Selection
From a Text File
The Text data viewer displays the text-based contents of the Data Sample that is currently
active within the data mapping configuration in a grid-like fashion, with each character in the file
being in a separate grid position.
Once created, data selections can be modified and moved in order to change or extend the
data included in the selection. You can also modify a data selection that is attached to a field
extraction in an Extract step by double-clicking on the data selection in the Data Viewer and
then modifying the data selection.
Moving a Data Selection
To move a data selection, click and hold anywhere on the data selection, move it to its new
desired location and release the mouses.
Page 71
Resizing a Data Selection
To resize a data selection, click and hold on one of the resize handles on the borders or
corners, move them to the new size and release the mouse.
Page 72
From a PDF File
The PDF data viewer displays the PDF file contents of the Data Sample that is currently active
within the data mapping configuration as pages.
Once created, data selections can be modified and moved in order to change or extend the
data included in the extraction. Moving a new data selection can be done directly if the data
selection is new. Data selections that are attached to a field extraction in an Extract step can
also be modified by double-clicking on the data selection in the Data Viewer and then
modifying the data selection.
Moving a Data Selection
To move a data selection, click and hold anywhere on the data selection, move it to its new
desired location and release the mouse.
Resizing a Data Selection
To resize a data selection, click and hold on one of the resize handles on the borders or
corners, move them to the new size and release the mouse.
Page 73
From a CSV or a Database File
The CSV/Database data viewer displays the field-based contents of the Data Sample that is
currently active within the data mapping configuration in a grid-like fashion, with each field
being in a separate grid position.
Once created, data selections can be modified. Modifying a new data selection can be done
directly if the data selection is new.
Modifying a Data Selection
To modify a data selection, press and hold the CTRL key click, and click on a field to add it or
remove it from the selection (the blue color indicates that the field is part of the current
selection).
Page 74
From a XML File
The XML data viewer displays the XML-based contents of the Data Sample that is currently
active within the data mapping configuration in a tree view, with XML fields displayed at each
level of the Sample Record.
Once created, data selections can be modified. Modifying a new data selection can be done
directly if the data selection is new.
Modifying a Data Selection
To modify a data selection, press and hold the CTRL key click, and click on a field to add it or
remove it from the selection (the blue color indicates that the field is part of the current
selection).
Page 75
Extracting Data
The following example explains in detail how to perform a data extraction for each different data
source file types and the Steps used to achieve it. Delimiters and Boundaries must be properly
configured beforehand (see Configuring Settings for more information).
The Preprocessor and the Postprocessor
Data processors allow the application to perform actions on the data file itself before it is
handed over to the Data Mapping workflow (preprocessors) and after the Data Mapping
workflow has completed (Postprocessors).
For more information about the Preprocessor step, see Preprocessor Step Properties.
For more information about the Postprocessor step, see Postprocessor Step Properties.
The Extraction Step
The Extract step is the heart of the DataMapper software. It takes information from the Data
Sample and places it in the Extracted Record within the Record Set.
Page 76
To configure the settings for the extraction step such as the list of fields included in the
extraction, how to change a field name, the data format of each field or if the information is
extracted from a position on the page or to using a script, see Extract Step Properties.
From a CSV file or a Database
Extracting Promotional Data
For more information about Promotional and Transactional data, please refer to About
Promotional and Transactional Data.
1. From the Viewer pane, select the fields that contain the customer and invoice information.
For more information about how to select data in a CSV file, please refer to Data
Selection/From a CSV File.
2. Drag & drop the selected fields into the Data Model pane.
Note
Alternatively, you can simply right click on the selected fields and select Add
Extraction. Please refer to Menus, Toolbar and Shortcut Keys for more information
about the available toolbar buttons, menus and keyboard shortcuts.
Extracting Transactional Data
The Transactional Data (line items information) appears on multiple lines. You must create a
loop on these lines to extract the items information. The line items are extracted in a detail
table.
Page 77
1. Select the fields that contain the first line item information.
2. Right click on this data selection and select Add Repeat . For more information about
what a Repeat step is and why it should be used, please refer to Step_types.htm.
3. Right click again on this data selection and select Add Extraction. A new extraction step
will be placed between the Repeat and the Goto steps.
Page 78
Note
Please refer to Menus, Toolbar and Shortcut Keys for more information about the
available toolbar buttons, menus and keyboard shortcuts.
From a XML file
Extracting Promotional Data
Page 79
The Promotional Data (the customer and invoice information) is normally located at the top of
the Source Record, before the ITEM information. It generally includes the name, the address,
reference numbers, invoice information, etc.
1. Select the child leaf elements of the CUSTOMER() node.
2. Right click on the selected elements and select Add Extraction.
Note
Alternatively, you can simply drag & drop the selected elements into the Data Model
pane.
Page 80
3. In this case, the invoice information is also part of the promotional data. Select the child
leaf elements of the INVOICE() node.
4. Right click on the selected nodes and select Add Extraction.
Extracting Transactional Data
The Transactional Data (line items information) appears in repeated elements. In the example
below, this information appears under the parent node ITEM(). Each ITEM() node gives
information about one item. Create a loop on the ITEM() nodes to extract the items information.
Page 81
1. Select the ITEM() node.
2. Right click on the selected node and select Add Repeat.
Note
By default, when you click on the Repeat step in the Steps pane, the For Each option is
selected in the Repeat type option as shown in theStep Properties pane. The loop will
include each ITEM() node. In the Collection field, you will find the corresponding ITEM()
node path. Please refer to Repeat Step Properties.
3. Select the children leaf nodes of the ITEM() node.
Page 82
4. Right click on the selected nodes and select Add Extraction.
Note
Please refer to Menus, Toolbar and Shortcut Keys for more information about the
available toolbar buttons, menus and keyboard shortcuts.
From a Text or a PDF file
Extracting Promotional Data
The Promotional Data (customer and the invoice information) is repeated for each item and
normally located at the top of the Source Record. It generally includes the name, the address,
reference numbers, invoice information, etc.
1. From the Viewer pane, select the customer and invoice information. Note that you can
select multiple lines. For more information on how to select text, please refer to Selecting
Data.
2. Right click on the selection data and select Add Extraction .
Page 83
Note
Alternatively, you can simply drag & drop the selected fields into the Data Model pane.
Extracting Transactional Data
The Transactional Data (line items in an invoice) appears on multiple lines and pages. A loop
has to be created on these lines to extract the item's information. The line items are extracted in
a detail table as described below:
1. Select a simple data in the first line item. For example the product number.
2. Right-click on the selection and select Add Goto. That moves the cursor to the beginning
of the first line item.
Page 84
3. Add a loop to extract each item until the end of the line items. To stop the loop at the right
place, you can use a text located at the end each record. For example, it can be a text
string like SUBTOTALS, TOTAL or AMOUNT. Now you can use that text as a condition to
stop the loop at the end of the line items list. In that case:
1. Select the text (SUBTOTALS for example) in the Viewer.
2. Right click on the selection and select Add Repeat.
The Repeat step loops on all lines until the selected text is found. Since a record can
extend on more than one page, lines that are not item lines must be excluded form the
extraction. You can use any exclusive information like a "." or "," in prices or totals for
example.
4. Select the "." or the "," in the total or in the price of the first line item.
5. Right click on the selected dot and select Add Conditional. In the Viewer pane, you will
see a green check mark besides each included line or X for other lines.
Page 85
6. From the Viewer pane, select the first field on the left for the first line item.
7. Right click on the selection and select Add Extraction.
8. Select the second field.
Page 86
9. Right click on the selection and select Add Extract Field.
10. Do the same for the rest of the fields along that same line item.
Note
The Add Extract Field step allows to add a field to an existing extract step while the Add
Extract Step creates a new step in the Steps pane. For optimization purposes, it is better to
use Add Extract Field than to have a succession of extraction steps.
Note
Please refer to Menus, Toolbar and Shortcut Keys for more information about the
available toolbar buttons, menus and keyboard shortcuts.
Totals Information
After the loop step, the cursor position is at the end of line items. If the record contains sums or
totals at the end of the line items list:
Page 87
1. Select the amounts.
2. Click the Repeat step in the Steps panel.
3. Right click on the selection and select Add a Step/Add Extraction.
Also Note That...
Note
l
l
l
l
l
Dragging a data selection or fields into a specific level of the Data Model (record or
detail tables) will add the fields to that level.
When dragging data into a detail table (in the Data Model pane), the Extract step
must be located within the appropriate Repeat step, otherwise the extract will not
function properly.
Data can be extracted conditionally. Please refer to Condition step
If a Data Model is loaded into the Data Model pane and if a field of the same name
already exists in that level, dragging a named field into it (CSV, XML, Database) will
extract the data to that field. Otherwise a new one with will be created.
Action steps could be added to the process described above in order to set the
value for a Source Record property or execute a JavaScript code.
Page 88
Note
To add an Extract step, you can also use JavaScript (select JavaScript from the Mode drop-down
in the Step Properties pane). Please refer to DataMapper API for more information.
About Promotional and Transactional Data
Promotional data, like its name suggests it, is used for promotional communications. It usually
contains personal information like addresses, names and phone numbers used to identify the
recipient of these communications. Each recipient represents one record and records for
promotional data are fixed length. These communications are aimed to promote a product or
service, create a bond or establish a relationship with the customer.
Transactional data is used in the communication of transactions between a company and their
customers or suppliers. Examples of such communications are invoices, statements or
purchase orders. Because of the nature of transactions, records lengths vary from record to
record.
Steps
l
l
l
Steps are executed sequentially, from top to bottom in a workflow.
Inside conditions, some steps may be skipped altogether when they are on a particular
branch, whereas in loops several steps may be repeated a number of times.
The Preprocessor and Postprocessor steps are special in that the former can be used to
modify the incoming data prior to executing the rest of the workflow while the latter can be
used to further process the Data Set after the entire workflow has been executed.
You will find below a list of different steps that can be added to a Data Mapping Workflow.
Note
For more details about operations that can be performed on steps, please refer to The
Steps Pane Interface.
Page 89
Preprocessor and Postprocessor
Preprocessors
Data preprocessors allow the application to perform actions on the data file itself before it is
handed over to the Data Mapping workflow.
Using a JavaScript a Preprocessor step could be used add a new field in each record set. A
unique ID could be created to be added to the output for integrity checks latter on. A time stamp
could be added to create reports. A tag could be added to process certain records differently. Or
Certain records could be removed altogether.
Any number of preprocessing tasks can be added to a workflow and run in sequence before the
data is sent to the Data Mapping workflow. Click the
button to add a Preprocessor to the list.
Page 90
Postprocessors
Data postprocessors allow the application to extract data that was stored in the data model
once the workflow is completed. For example, the postprocessor can export all or parts of the
data to a CSV file which can then used to generate daily reports of the Workflow processes.
Page 91
Any number of postprocessing tasks can be added to a workflow and be executed after the
Data Mapping workflow is complete. Click the
button to add a Postprocessor to the list.
Page 92
Extract
The Extract step is the heart of the DataMapper software. It takes information from the Data
Sample and places it in the Extracted Record within the Record Set.
Please refer to Data Extraction for an animated example.
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Note
To add an Extract step, you can also use JavaScript (select JavaScript from the Mode drop-down
in the Step Properties pane). Please refer to DataMapper API for more information.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Page 93
Goto
The cursor position determines how data is extracted from the Source Record. The cursor in a
Source Record is always at a specific position.
In a Source Record, the cursor position starts off at the top-left corner of the Sample Data. When
the Goto step is used, that cursor position is moved to the location (either relative or absolute)
set by the Goto step. In the case of a Goto step within a Repeat step, the cursor position will
gradually be moved with each loop of the repeat step.
Since data extracted by the Extract step is always relative to the current cursor position, this
becomes useful when extracting data at the end of the loop. For instance, when a "Totals" line
appears at the end of line items in an invoice, the Extract step can find the appropriate position
of the "Totals" simply by looking at an certain distance (or offset) from the last line item and
always find the "Totals" at the same place.
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Condition
A Condition step splits the extraction workflow into two separate branches, one that is
executed when the condition is True, the other when it is False. In the Viewer on the left side of
the window, an icon is displayed indicating the result of the evaluation: when true and
when false.
Page 94
A Condition step is used when the data extraction must be made based on specific criteria. In
the following example, the transactional data must be extracted according to two main criteria.
First, the line item must include an amount of money and secondly, the lines that include a
Description field on two lines have to be extracted as a single record.
Page 95
1. Since the extraction is for transactional data, a Repeat step is first added.
2. A first condition is added to determine whether the line should be considered for the
extraction.
Page 96
3. The extraction is performed if the condition is true.
4. Under the true branch of the first condition, a second condition is added for Description
fields on two lines.
Page 97
5. The extraction performed under the true branch of the second condition.
6. The extraction performed under the false branch of the second condition.
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Page 98
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Repeat
The Repeat step is a loop that may run 0 or more times, depending on the condition specified.
It is generally used for the extraction of transactional data. Repeat steps do not automatically
move the pointer in the file. In order to avoid infinite loops, a Goto step must be present within
the loop itself.
The following picture shows an example of a Repeat step. The Repeat step is a loop that
includes both Goto and Extract steps. The extraction result for transactional data is placed in a
Detail table.
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Page 99
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Note
By default, if an Extract step is added within a Repeat step, its extraction is made in a detail
table.
Note
If an XML node that has children is selected, and the pointer is currently at this node, creating a
repeat step will loop on that node.
Extract Field
The Add Extract Field function adds the selected data to a selected Extract step in the Steps
pane. If multiple lines, nodes or fields are selected, multiple extract fields are added
simultaneously (see also About Records and Fields for more information).
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Multiple Conditions
The Multiple Conditions step is useful to avoid the use of too many nested Conditions as
shown in the following picture:
Page 100
Instead of these nested conditions, it is more convenient to use the Multiple Conditions step.
If, for example, we take the case of a condition which, when true, is extracting following the
values of Mr, Mrs or Miss, we have:
Page 101
Each Case condition led to an extraction that occurs when the condition is True. The resulting
process has a structure easier to understand and manage. Cases are executed from left to right.
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Action
The Action step can set the value for a Source Record property or execute a JavaScript code.
The Action Step can run multiple specific actions one after the other in order.
The following picture shows a usage example of an Action step...
Page 102
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface area.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
The Data Model
The Data Model is basically the structure into which the records are extracted. It is the structure
of all the fields and tables of an extracted record. The Data Model contains all the necessary
information to be used in the creation of a template in the Designer module. The group of
records generated from the Data Sample is called the Record Set and it is stored in the Unified
Data Model (UDM) format.
The main advantage of the Data Model is that it is reusable, meaning that it be shared amongst
different layouts and outputs created with the Connect Designer. This UDM also allows a same
layout or output to be populated of data from different sources and formats without the need to
modify it. This would be impossible without the universality of the UDM.
Page 103
How to Use a Data Model?
The Data Model is simply a file containing that structure and all you need to do is to import that
Data Model file into your data mapping configuration in order to be able to use it. When you
import the Data Model, it appears in the Data Model pane where you can see all the fields and
their types.
Once imported a Data Model can be modified. You can delete or add fields, or change their
type. Once the data model is imported and all the fields properly set, all you need to do is
extract the information. That is done simply via drag & drop.
Note
The order in which these panes are displayed corresponds to the order in which they are normally
used to create a data mapping configuration.
XML and Tabular Data
Multiple fields can be extracted by using a database or an XML file. To extract multiple fields
inside a tabular data type or an XML, simply select all the fields and drag & drop them.
Depending on where they are dropped, they will react a bit differently. When you drag & drop
fields directly from the Viewer to the first field ID in the Data Model pane, it takes the number of
fields and it overwrites the values inside the Data Model one after the other. If you have small
corrections to make, like inverting the first and last names, simply override the individual fields.
It will not create duplicate extractions; it will simply fix the current extraction.
If your Data Sample has fields that are named the same way as the imported Data Model, the
simpler thing to do is to drag & drop them inside the record table itself, not directly on a field.
When you do this, the DataMapper module automatically matches all the fields with the same
name and adds any field that is not already there.
The Data Model can also contain detailed tables and nested tables. These are used in the
same way: you can simply drag & drop your selection into the detail table to extract the data.
However, as in a normal data mapping, a loop is needed before extracting detail lines. Once a
loop has been created, you can select everything and drag & drop it into the detail table (see
the Repeat step for more information about loops).
Page 104
You can edit a Data Model directly from the Data Model pane. Right-click anywhere and a
contextual menu will appear, depending on the location. If you right-click inside the record itself,
you can add a field or a table. A field will simply be added at the end with no extraction, while a
table will be added with no fields inside.
The Data Model pane acts as a Data Model editor. If you create a new data mapping
configuration with nothing in it and your Data Model pane is empty, you can create it here and
then export it. Remember that the Data Model has nothing to do with the type of data. It does not
matter whether you do it from an XML, CSV or PDF.
TXT and PDF
Because PDF and text files do not have field names, but only areas from which data is
extracted, it is a bit more useful to have a Data Model, especially with the right field names.
When extracting data from a PDF or text file, you do have to go one line at a time or one field at
a time because For example, if you select a whole address block from the Viewer and try to
extract it into the data model address fields on the right, it is only going to map one field. If you
split it, it will create different fields using that address.
For more information about the operations that can be performed on the Data Model, please
refer to The Data Model Interface.
About Records and Fields
A record is defined as a block of information that refers to a single document for a single
recipient. A document can be anything, such as an invoice, a letter, a postcard, a report, a
contract. When defining records in the Data Sample (called Source Records), the concept of a
single documents and recipients is important. For instance, a Record should not contain
multiple invoices for a single client, nor should it contain multiple client addresses for
postcards.
While the record is a more general term, there are two more specific places where record is
used:
The Source Record is the piece of information as it is found in Sample Data. Source Records
are defined by Boundaries in the Settings Pane.
The Extracted Record, on the other hand, is a combination of data extracted from the Source
Record using the Extractor and data coming from other sources. Each Extracted Record is used
Page 105
in the Designer module to generate a single documentfor a singlerecipient, and is part of
theRecord Set, the complete information being generated by a data mapping configuration and
later merged with a template created in Designer.
A Field is part of a record and contains a single piece of data from that record.
Data Model File Structure
The Data Model file is a XML file that contains the structure of the data model, including each
field's name, data type, and any number of detail tables and nested tables.
Example for promotional data, including a simple name and address:
Example with transactional details, a simple invoice format
Example of Nested Tables (one table into another)
Example of Default Values that can be added to any field with the defaultValue attribute:
Data Source (Settings)
A data source is simply the source of the data. It can be a file (CSV, PDF, TXT, XML) or a
particular database. The data might be located on the same computer as the program, or on
another computer somewhere on a network.
Input Data (Delimiters)
Delimiter are borders that naturally separate blocks of data in the Data Sample and are different
for each data type. For example, a text file can be delimited by the number of lines and PDF
files are delimited naturally by pages.
Please refer to The Settings Pane Interface for more information about each field and buttons.
Boundaries
Boundaries are the division between source records. They can be set using different types of
rules such as text, pages or even custom JavaScript rules.
Page 108
Boundaries differ from Delimiters. When defining boundaries , multiple delimiters can be
included between boundaries - many pages per invoice, many CSV rows per transaction, etc.
To set a boundary, a specific trigger must be found. The trigger is something that is either static
("Page 1 of" on text or PDF files) or something that changes on each source record (a customer
ID at a specific location, a username, etc).
Please refer to The Settings Pane Interface for more information about each field and buttons.
Data Samples
The Data Samples are the data sources that have been imported into the data mapping
configuration.
Please refer to The Settings Pane Interface for more information about each field and buttons.
External JS Libraries
You can use the External JS libraries to add more JavaScript functionality to your data mapping
configuration. Any functions included in the JS library will be available in Preprocessor scripts,
as well as Action tasks, Post Functions and JavaScript -based extraction steps.
For example let's take the following JavaScript file, for example:
function myAddFunction(p1, p2) {
return p1 + p2;
};
If this is saved as myFunction.js and imported, then the following would work anywhere in the
configuration:
var result = myAddFunction(25, 12); // returns 37!
The External JS Libraries box displays all the libraries that have been imported into the data
mapping configuration.
Please refer to The Settings Pane Interface for more information about each field and buttons.
Page 109
DataMapper User Interface
The DataMapper's user interface gives you several options to work with.
Page 110
See:
l
Menus
l
Toolbars
l
Steps Pane
l
Step Properties Pane
l
Data Model Pane
l
Data Viewer
l
Messages Pane
l
Settings Pane
Menus
The following menu items are shown in the DataMapper Module's menu:
Page 111
File Menu
l
l
l
l
l
l
l
l
l
l
New...: Opens the Creating a New Data Mapping Configuration dialog.
Open: Opens a standard File Open dialog. This dialog can be used to open Templates
and data mapping configurations.
Open Recent: List the most recently opened Templates and configurations. Clicking on a
template will open it in the Designer module, clicking on a data mapping configuration will
open it in the DataMapper module.
Close: Close the currently open data mapping configuration or Template. If the file needs
to be saved, the appropriate Save dialog will open.
Close All: Close any open data mapping configuration or Template. If any of the files
need to be saved, the Save Resources dialog opens.
Save: Saves the current data mapping configuration or Template to its current location on
disk. If the file is a data mapping configuration and has never been saved, the Save As
dialog appears instead.
Save As...: Saves the current data mapping configuration or Template to a new location
on disk. In the case of Templates, it is saved to a location that can be different than the
local repository.
Save All: Saves all open files. If any of the open files have never been saved, the Save
As dialog opens for each new unsaved file.
Revert: Appears only in the Designer module. Reverts all changes to the state in which
the file was opened or created.
Add Data: Adds data either to the current data mapping configuration or to the open
template. In data mapping configuration
l
l
l
l
From File...: Opens the dialog to add a new data file to the currently loaded data
mapping configuration. Not available if the currently loaded data mapping
configuration connects to a database source.
From Database...: Opens the Edit Database Configuration dialog. Not available if
the currently loaded data mapping configuration is file-based.
Send to Workflow: Opens theSend to Workflow dialog to send files to a local
PlanetPress Workflow software installation.
Exit:Closes the software. If any of the files need to be saved, the Save Resources dialog
opens.
Page 112
Edit Menu
l
Undo: Undoes the previous action.
l
Redo: Redoes the last action that was undone.
l
l
l
l
Cut Step: Removes the currently selected step and places it in the clipboard. If the step is
a Repeat or a Condition, all steps under it are also placed in the clipboard. If there is
already a step in the clipboard, it will be overwritten.
Copy Step: Places a copy of the currently selected step in the clipboard. The same
details as the Cut step applies.
Paste Step: Takes the step or steps in the clipboard and places them in the Steps after
the currently selected step.
Delete Step: Deletes the currently selected step. If the step is a Repeat or Condition, all
steps under it are also deleted.
l
Cut: Click to remove the currently selected step, or steps, and place them in the clipboard.
l
Copy: Click to place a copy of the currently selected step, or steps, in the clipboard.
l
Paste: Click to place any step, or steps, from the clipboard before the currently selected
step in the Steps Pane.
Data Menu
l
l
l
Hide/Show datamap: Click to show or hide the icons to the left of the Data Viewer that
displays how the steps affect the line.
Hide/Show extracted data: Click to show or hide the extraction selections indicating that
data is extracted. This simplifies making data selections in the same areas and is useful
to display the original data.
Validate All Records: Runs the Steps on all records and verifies that no errors are
present in any of the records. Errors are displayed in the Messages Pane.
Steps
l
l
Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps do not run
when in DataMapper and do not execute when the data mapping configuration is
executed in Workflow. However, they can still be modified normally.
Add Extract Step: Adds an Extract Step with one or more extract fields. If more than one
line or field is selected in the Data Viewer, each line or field will have an extract field.
Page 113
l
l
l
l
l
l
Add Goto Step: Adds a Goto step that moves the selection pointer to the beginning of the
data selection. For instance if an XML node is selected, the pointer moves to where that
node is located.
Add Condition Step: Adds a condition based on the current data selection. The "True"
branch gets run when the text is found on the page. Other conditions are available in the
step properties once it has been added.
Add Repeat Step: Adds a loop that is based on the current data selection, and
depending on the type of data. XML data will loop on the currently selected node, CSV
loops for all rows in the record. In Text and PDF data, if the data selection is on the same
line as the cursor position, the loop will be for each line until the end of the record. If the
data selection is on a lower line, the loop will be for each line until the text in the data
selection is found at the specified position on the line (e.g. until "TOTAL" is found).
Add Extract Field: Adds the data selection to the selected Extract step, if an extract step
is currently selected. If multiple lines, nodes or fields are selected, multiple extract fields
are added simultaneously.
Add Multiple Conditions: Adds a condition that splits into multiple case conditions.
Add Action Step: Adds a step to run one or more specific actions such as running a
JavaScript expression or setting the value of a Source Record Property.
View Menu
l
Zoom In: Click to zoom in the Steps Pane.
l
Zoom Out: Click to zoom out the Steps Pane.
Window Menu
l
Show View
l
Messages: Shows the Messages Pane.
l
Steps: Shows the Steps Pane.
l
Settings: Shows the Settings Pane.
l
Record: Shows the Record Pane.
l
l
Detail tables : Each detail table and nested table is listed here. Click on one to
show it in the Data Model Pane.
Step Properties: Shows the Step Properties Pane.
Page 114
l
l
Reset Perspective: Resets all toolbars and panes to the initial configuration of the
module.
Preferences: Click to open the Preferences dialog.
Help Menu
l
l
l
Software Activation: Displays the Software Activation dialog. See Activating your
license.
Help Topics: Click to open this documentation.
Contact Support: Click to open the Objectif Lune Contact Page in the default system
Web browser.
l
About PlanetPress Connect Designer: Displays the software's About dialog.
l
Welcome Screen: Click to re-open the Welcome Screen.
Panes
The following topics explain in detail the different panes of the DataMapper Interface.
Data Model Pane
The Data Model pane displays the result of all the preparation and extraction done by the
process. The pane displays the content of a single record within the Record Set.
Note
The order in which these panes were presented corresponds to the order in which they are normally
used to create a data mapping configuration.
Data is displayed as a tree view, with the root level being the Record table, levels below it
being detail tables, and any level below being called Nested Tables.
The Data Model is also used as a navigation tool between records and all tables.
Adding Data
Beyond the methods for adding data described in the Steps Pane and the Data Viewer, there is
a specific way to add an Extract step directly into the Data Model pane, which is drag & drop:
Page 115
Dragging a data selection (text and PDF) or a field (CSV, XML and Database) into the Data
Model pane will automatically add the appropriate extraction method into a specific location.
There are some specific tricks and limitations, however:
l
l
l
l
l
If no Extract step is currently selected in the Steps Pane, a new Extract step is created. If
an Extract step is selected, new Extract Fields are added to this existing step.
Dragging a data selection or fields into a specific level of the Data Model (Record or detail
tables) will add the fields to that level.
When dragging data into a detail table, the Extract Step must be located within the
appropriate Repeat Step, otherwise the extract will not function properly.
If a Data Model is loaded into the Data Model Pane, when dragging named fields (CSV,
XML, Database), if a field of the same name exists in that level, the extract field extract the
data to that field, otherwise it creates a new one.
Dragging a single field onto a Data Model field will extract to that field regardless of name.
Modifying the Data Model
It is possible to modify the fields within the Data Model pane, effectively generating data
models, even if no data is present in the pane. To do this, use the contextual menu within the
pane itself. The following options appear depending on the selected line when right-clicking:
Page 116
l
l
l
l
l
l
Add a field: Click to add a new field at the current level (record or table). Enter the field
name in the dialog and click OK to add it.
Add a table: Click to add a new table at the current level (record or existing table). Enter
the table name in the dialog and click OK to add it.
Rename: Click to rename the selected table or field. Enter the new name and click OK to
rename. Only available for empty Data Model Fields (see below) tables that only contain
them.
Delete: Click to delete the selected table or field. Only available for empty Data Model
Fields or tables that only contain them.
Set Type: Use the list to select which the field type (see Data Types). Only available for
empty Data Model Fields or tables that only contain them.
Default Value: Click to set the default value for empty Data Model Fields. This value is
used if no extraction is present, or if an extraction attached to this field returns no value.
Field Display
Fields in the Data Model pane are displayed in specific ways to simplify comprehension of the
display data:
l
l
l
l
l
l
l
l
Value: The current value of the extracted field, based on the current Source Record.
The column on the left displays the name of the field. The column on the right displays
the extracted data if it exists.
The column on the right displays the current valueof the extracted field based on the
current Source Record, when anExtract Step has an extraction for this field.
The icon to the left of the name indicates the Data Type of the field (see Data Types).
A field name with an asterisk to the right indicates that this field is part of an imported
Data Model file (called a Data Model Field).
A field with a grey background indicates this Data Model Field does not have any
attached extracted data.
A field with a white background indicates that the field has attached extracted data but
the step extracting the data is not currently selected.
A field with a blue background indicates that the field has attached extracted data and
the step extracting the data is currently selected.
Page 117
Record Navigation
Records can be navigated directly from the Data Model Pane. The default Record level
navigates between records both in the Data Model pane and the Data Viewer, while each table
has a similar navigation that influence that table and each under it.
l
l
l
l
l
l
l
l
Expand/Contract: Click to hide or show any fields or tables under the current table level.
Table Name: Displays the name of the table as well as the number of records at that level
(in [brackets]). At the Record level this is the number of Source records (affected by the
Boundary settings, Preprocessor and the Record Limit setting). In other levels it
represents the number of entries in a table.
Number of Records: The number of available records in the Data Sample. Affected by
the Boundary settings, Preprocessor and the Record Limit setting.
First Record: Jumps to the first record in the Data Sample. Disabled if the first record is
already shown.
Previous Record: Moves to the previous record in the Data Sample. Disabled if the first
record is already shown.
Current Record: Displays the current record or table entry. Type in a record number and
press the Enter key to display that record. The number has to be within the number of
available records in the Data Sample.
Next Record: Moves to the next record in the Data Sample. Disabled if the last record is
already shown.
Last Record: Jumps to the last record in the Data Sample. Disabled if the last record is
already shown. If a Record Limit is set in the Settings Pane, the last record will be within
that limit.
Importing/Exporting Data Models
Within the Data Model pane, data model files can be exported using the current structure, or
imported in order to simplify the extraction process.
Importing and Exporting Data Models is done from within the Data model Pane, using the topright icons
and
.
Page 118
Rules for importing:
l
l
Imported Data Model fields always overwrite existing field properties when the field name
is the same. Non-existent fields are created automatically with the appropriate field
settings. The import is case-insensitive, so fields with a different case will be ignored.
All data model fields are tagged with the Asterisk (*). If overwriting an existing data model,
existing data model fields that are not in the imported data model file will have their
asterisks removed.
Dynamically Added Fields
There are a number of instances where data needs to be added to the data model after the
initial data mapping operation has been performed. For instance, you might need to add a
cleansed postal address next to the original address. Or use a Workflow process to retrieve a
value from a Database and add it to the data record. However, the data model is not extensible.
Once a data record has been created, the contents of its fields can be updated but not its
structure.
A new Extradata field is automatically created at every level of each data record. That means
the record itself gets an Extradata field, and each detail table also gets one.
This is what it looks like from the Designer interface:
Page 119
The field is not visible in the DataMapper because no data can be extracted into it during the
data mapping process. But it will be visible in the Designer, even for existing data models.
The only way to add a value to the Extradata field is by using a PlanetPress Connect Workflow
process. For example, It could basically include the following steps (2 and 3 are optional):
1. Start the data mapping process.
2. Save the Metadata.
3. Create a database with the Metadata.
4. Add a value to the Extradata field of this database.
Note
Steps 2, 3 and 4 can also be replaced by the Update Data Record plugin or by using a REST call.
Please refer to PlanetPress Connect Workflow documentation for more information.
Page 120
Detail Tables
Detail tables contain transactional data that is created when an Extract step is added within a
Repeat step.
In the most basic of transactional systems, a single detail table is used. However, it is possible
to create multiple detail tables, as well as nested tables. When detail and nested tables are
present in the record, they are displayed as separate levels in the Data Model (see The Data
Model Interface for more information).
Multiple detail tables
Multiple detail tables are useful when more than one type of transactional data is necessary, for
instance if two different type of fields are used for different types of data. One example of this
would be invoice data containing purchases (items with a set price, quantity, item number) as
well as services (service with a price, frequency, contract end date, etc).
Creating more than one detail table is simple. Click the Extract steps and change the name of
tables from record.details to something else. In the following example, we will create two
tables called record.purchases and record.services.
Page 121
Example
1. Data Overview.
Page 122
Page 123
2. Extracting Customer and Invoice information.
Page 124
3. Extracting Transactional Data.
Page 125
4. Renaming Tables.
Nested Tables
Nested detail tables are used to create transactional data that is relative to other data. An
example of this would be an invoice for a multi-service provider. In this example, a first table
contains services (Internet, Cable, Home Phone, Mobile), while one or more nested tables
giving details for charges and rebates on each of those services.
Nested tables are created in a similar fashion to multiple detail tables, with the difference that
the dot notation contains multiple levels. In the example above, tables could be called
record.services , record.services.charges, record.services.details , where "charges" includes all
service prices and rebates, and "details" includes extra items such as movie rentals or long
distance calls.
For the tables to be actually nested, the Repeat and its Extract step that extract the "charges"
and "details" information must be located within the Repeat step that extracts data to
"record.services". In such a setup, "record.services.charges" is a child table of
"record.services", and one "charges" table is created for each row in the "services" table.
Page 126
Example
1. Data Overview.
Page 127
Page 128
2. Extracting Customer and Invoice information.
Page 129
3. Extracting Transactional Data for the First Table.
Page 130
4. Extracting Transactional Data for Nested Tables.
Page 131
5. Renaming Tables.
Note
Creating nested tables is currently an advanced feature, and using these nested tables in the
Designer module requires some amount of coding.
Note
For more information about operations that can be performed on tables, please refer to The Data
Model Interface
The Data Viewer
The Data Viewer is a central part of the module, as the most important aspect of the
DataMapper is obviously the data. It displays the content of the Data Source that is currently
loaded in the DataMapper in a way that is easy to view and interact with. What is seen in the
Page 132
Data Viewer, however, is not simply the raw Data Source. It is formatted to fit your screen and
can be modified through the use of a Preprocessor. The Data Viewer itself is surrounded by two
different areas: the toolbar at the top and the data map on the left. The toolbar is used to control
a few options in the viewer. For example, with a text file Data Source, the font displaying the
text can be changed. A button can also hide the data map, and zoom controls are also
available. Some of the toolbar features may be unavailable, depending on the Data Source
type. The data map on the left gives you precise indications on how the cursor moves within the
DataMapper. The cursor defines where data extraction starts. It starts at the top left of the
screen and moves down as you go through the data. Data is always extracted using an offset or
a relative position from the current cursor location. This is how totals can be extracted at the
end of an invoice with a variable number of lines, since the total is always from the same
distance to the last line of the invoice. The offset is always the same. The data map can
therefore indicate loops, gotos as well as condition results for each line.
When the Delimiter and Boundary options are set in the Settings Pane, the Data Viewer reflects
those changes and can display more than one unit of the data sample (page, XML node, CSV
line, etc.), depending on these options.
Data Selection
There are three different ways to create a data selection inside the Data Viewer, depending on
the Data Source type that is currently loaded. Data selections can be used for Condition,
Repeat and Extraction steps.
Tabular Data
Tabular data is displayed in a table where multiple fields appear for each line or row in the
original data. Selections can only be done on each line, meaning you cannot select data from
multiple rows at the same time. You can select multiple fields at once in the same row using
features you would expect. Click & drag to select multiple fields or use CTRL-click and SHIFTclick combinations.
PDF and Text
PDF and text are both handled in basically the same way. You can select any area of one or
more lines on the page. These selections can be moved and resized simply by dragging them
and using the respective resize handles. As long as data selections exist, any step you add
does not remove that data selection.
Page 133
Here is a small trick to extract multiple lines. Make a selection for the first line, click on Add
Extract Step, move the selection to the next line, then click Add Extract Field and so on until
the end of the data you want to extract. To actually use the data selection instead of moving it,
use the drag icon at the right of the selection and drag it into the Data Model pane to create an
extraction.
PDF and text Data Sources are unique in the sense that, if you select any extracted field in the
Data Model pane or an extract step, you can change the data selection for that extracted field in
the same way you move and resize data selections. This will modify the extraction properties
for that field.
XML
XML data is displayed as a tree view inside the Data Viewer. You can select multiple fields
inside an XML file using SHIFT-click and CTRL-click even if those fields are on different levels.
So if you start with the full name and end at the Total field, you can select all of them and drag
them into the Data Model pane for a quick extract step. You can also collapse any XML level if
you are not using it or do not need to see its content. Note that specifically for XML files, in most
cases it is not necessary to use a Goto step. For example, if a Repeat step is added, you can
see that a Goto is not added before or within th loop. This is because XML has its own method
of moving through the file, "Xpath", and we take advantage of this in the software. Once data is
extracted from the Data Source, it is possible to see exactly where all the data comes from.
Clicking on any Extract step highlights any area from which it extracts data. You can also click
on the Preprocessor step to select all the steps in the workflow to show a complete map of all
the data extracted from the Data Source. As you may have already realized, there are multiple
ways to interact with the Data Viewer, especially when creating data selections and using them
to create steps. Dragging a data selection into the Data Model pane will extract the data to the
selected location, either the record itself or the detail table. If any extract step is already
selected, fields are added to it. Dragging a data selection into an existing extract step forces
new fields to be added. A new extract step is never created. Right-clicking on a data selection
displays the actions (contextual menu) that can be done with that selection or the steps that can
be added to them. That menu also displays the keyboard shortcuts.
Window Controls
The following controls appear at the top of the Data Viewer:
l
Font (Text file only): Use the drop-down to change the font used to display text. Useful for
double-byte data. It is recommended that monospace fonts be used.
Page 134
l
l
l
l
Hide/Show line numbers
the left of the Data Viewer.
(Text file only): Click to show or hide the line numbers on
Hide/Show datamap : Click to show or hide the icons to the left of the Data Viewer
which displays how the steps affect the line.
Hide/Show extracted data : Click to show or hide the extraction selections indicating
that data is extracted. This simplifies making data selections in the same areas and is
useful to display the original data.
Lock/Unlock extracted data : Click to lock existing extraction selections so they
cannot be moved or resized. This simplifies making data selections in the same area.
l
Zoom Level: Use the arrows to adjust the zoom level, or type in the zoom percentage.
l
Zoom In (CTRL +)
l
Zoom Out (CTRL -)
: Click to zoom in by increments of 10%
: Click to zoom out by increments of 10%
Additional Keyboard Shortcuts for XML Files:
l
l
+ (while on an XML node with children): Expand the XML Node
- (while on an XML node with children): Collapse the XML node, hiding all its children
nodes.
Contextual Menu
You can access the contextual menu using a right-click anywhere inside the Viewer window:
Note
The Add Extract Field item is available only after an Extract step has been added to the
workflow.
Page 135
For more information about the different steps that can be added to a Data Mapping workflow,
please refer to Steps.
Operations
In the following example, clicking on the Repeat step shows in which lines the loop takes
place. Click on the Goto within the loop to show which lines are skipped. Clicking on a
Condition shows whether that condition is true or false for each line.
Drag and drops from the Viewer window to the Data Model pane can be performed to extract
data.
Page 136
Messages Pane
The Messages pane is shared between the DataMapper and Designer modules and displays
any warnings and errors from the data mapping configuration or template.
At the top of the Message pane are control buttons:
l
Export Log: Click to open a Save As dialog where the log file (.log) can be saved on
disk.
l
Clear Log Viewer: Click to remove all entries in the log viewer.
l
Filters: Displays the Log Filter .
l
Activate on new events: Click to disable or enable the automatic display of this dialog
when a new event is added to the pane.
l
Time: The date and time when the error occurred.
l
Type: Whether the entry is a warning or an error.
l
l
Source: The source of the error. This indicates the name of the step as defined in its step
properties.
Message: The contents of the message, indicating the actual error.
Page 137
Log Filter
The log filter determines what kind of events are show in the Messages Pane.
l
l
Event Types group:
l
OK: Uncheck to hide OK-level entries.
l
Information: Uncheck to hide information-level entries.
l
Warning: Uncheck to hide any warnings.
l
Error: Uncheck to hide any critical errors.
Limit visible events to: Enter the maximum number of events to show in the Messages
Pane. Default is 50.
The Settings Pane
The Delimiter, Boundary setting, and a list of Data Samples used in the current data mapping
configuration can be found under the Settings tab. The available options depend on the type of
data sample that is loaded. For more information about Delimiters and Boundaries, see
Configuring The Data Source (Settings).
The Input Data (Delimiters)
Delimiters are borders that naturally separate blocks of data in the Data Sample and they differ
for each data type. For example, a CSV is delimited by record, and PDF files are delimited
naturally by pages.
For a CSV File
In a CSV file, data is read line by line, where each line can contain multiple fields. Even though
CSV stands for comma-separated values, CSV can actually refer to files where fields are
separated using a number of separators, including commas, tabs, semicolons, pipes or any
other character. The input data selection is required so you can specify to the DataMapper
module how the fields are separated. This is done using the field Separator. The other
important option is the Text delimiter, which is used to wrap around each field just in case the
field values contain the field separator. This ensures that, for example, the field “Smith John” is
not interpreted as two fields, even if the field delimiter is the semicolon.
Page 138
l
l
l
l
l
l
l
l
Field separator: Defines what character separates each fields in the file.
Text delimiter: Defines what character surrounds text fields in the file, preventing the
Field separator from being interpreted within those text delimiters.
Comment delimiter: Defines what character starts a comment line.
Encoding: Defines what encoding is used to read the Data Source ( US-ASCII, ISO8859-1, UTF-8, UTF-16, UTF-16BE or UTF-16LE ).
Lines to skip: Defines a number of lines in the CSV that will be skipped and not used as
Source Records.
Set tabs as a field separator: Overwrites the Field separator option and sets the Tab
character instead for tab-delimited files.
First row contains field names: Uses the first line of the CSV as headers, which
automatically names all extracted fields.
Ignore unparseable lines: Ignores any line that does not correspond to the settings
above.
For a PDF File
PDF files already have a clear and unmovable delimiter: pages. So the settings in the input
area are not used to set delimiters of PDF files. Instead, this opportunity can be taken to add
some options on how text is read from the PDF when creating data selections. These options
determine how PDF words, lines and paragraphs are detected. For instance, the line spacing
option determines the spacing between lines of text. The default value is "1", meaning the
space between the top of each line must be equal to at least the average character height.
Note
PDF Files have a natural, static delimiter in the form of Pages, so the options here are interpretation
settings for text in the PDF file. Each value represents a fraction of the average font size of text in a
data selection, meaning "0.3" represents 30% of the height or width.
l
Word spacing: Determines the spacing between words. As PDF text spacing is
somehow done through positioning instead of actual text spaces, text position is what is
used to find new words. This option determines what percentage of the average width of a
single character needs to be empty to consider a new word has started. Default value is
"0.3", meaning a space is assumed if there is a blank area of 30% of the width of the
Page 139
average character in the font.
l
l
l
l
Line spacing: Determines the spacing between lines of text. The default value is 1,
meaning the space between lines must be equal to at least the average character height.
Paragraph spacing: Determines the spacing between paragraphs. The default value is
1.5, meaning the space between paragraphs must be equal to at least "1.5" times the
average character height to start a new paragraph.
Magic number: Determines the tolerance factor for all of the above values. The tolerance
is meant to avoid rounding errors. If two values are more than 70% away from each other,
they are considered distinct; otherwise they are the same. For example, if two characters
have a space of exactly one times the width of the average character, any space of
between "0.7" and "1.43" of this average width is considered one space. A space of
"1.44" is considered to be 2 spaces.
PDF file color space: Determines if the PDF if displayed in Color or Monochrome in the
Data Viewer. Monochrome display is faster in the Data Viewer, but this has no influence
on actual data extraction or the data mapping performance.
For Databases
Since data is being taken from a database instead of a data file, the input data option refers
more to the database itself rather than how to interpret the data. After all, databases all return
the same type of information. Because a database generally contains multiple tables, they can
all be listed here. Clicking on any of the tables shows the first line of the data in that table. If you
need more power, click on the Custom SQL button and work on your database using whatever
language the database supports. If it supports stored procedures, including inner joins,
grouping and sorting, it will work perfectly.
The following settings apply to any database or ODBC Data Sample.
l
l
l
l
Connection String: Displays the connection string used to access the Data Source.
Table: Displays the tables and stored procedures available in the database. The selected
table is the one the data is extracted from.
Encoding: Defines what encoding is used to read the Data Source ( US-ASCII, ISO8859-1, UTF-8, UTF-16, UTF-16BE or UTF-16LE ).
Browse button : Opens the Edit Database configuration dialog, which can replace
the existing database data source with a new one. This is the same as using the Replace
feature in the Data Samples window.
Page 140
l
Custom SQL button
query.
: Click to open the SQL Query Designer and type in a custom SQL
For a Text File
Because text files have many different shapes and sizes, there are a lot more options for the
input data in these files. You can add or remove characters in lines if you have a big header
you want to get rid of, or really weird characters at the beginning of your file. Set a line width if
you are still working with old line printer data and so on. It is still important, however, that pages
are defined properly. This can be done either by using a set number of lines or using the “P”
character - or if your data is a bit more complex, to detect text on the page. Be careful that these
are not Boundary settings but rather page settings in order to make sure you are configuring
these options to detect each new page and not each new Source Record.
l
l
l
l
l
l
Encoding: Defines what encoding is used to read the Data Source ( US-ASCII, ISO8859-1, UTF-8, UTF-16, UTF-16BE or UTF-16LE ).
Selection/Text is based on bytes: Check for text files that use double-bytes characters
(resolves width issues in some text files).
Add/Remove characters: Defines the number of characters to add to, or remove from,
the head of the data stream. The spin buttons can also increment or decrement the value.
Positive values add blank characters while negative values remove characters.
Add/Remove lines: Defines the number of lines to add to, or remove from, the head of
the data stream. The spin buttons can also increment or decrement the value. Positive
values add blank lines while negative values remove lines.
Maximum line length: Defines the number of columns on a data page. The spin buttons
can also increment or decrement the value. The maximum value for this option is 65,535
characters. The default value is 80 characters. You should tune this value to the longest
line in your input data. Setting a maximum data line length that greatly exceeds the length
of the longest line in your input data may increase execution time.
Page delimiter type: Defines the delimiter between each page of data. Multiples of such
pages can be part of a Source Record, as defined by the Boundaries.
l
l
On lines: Triggers a new page in the Data Sample after a static number of lines
(called Lines per Page), or using a Form Feed character.
On text: Triggers a new page in the Data Sample when a specific string is found in
a certain location.
l
Word to find: Compares the text value with the value in the Source Record.
l
Match case: Activates a case-sensitive text comparison.
Page 141
l
l
l
Location: Choose Selected area or Entire width to use the value of the
current data selection as the text value.
Left/Right: Use the spin buttons to set the start and stop columns to the
current data selection (Selected area) in the Source Record.
Lines before/after: Defines the delimiter a certain number of lines before or
after the current line. This is useful if the text triggering the delimiter is not on
the first line of each page.
For a XML File
XML is a special file format because these file types can have theoretically an unlimited
number of structure types. The input data has two simple options that basically determine at
which node level a new record is created. Use root node uses the complete XML file as a
single Source Record. The XML nodes option list all the node. Choosing one creates a new
delimiter every time that a node is encountered.
Note
The information contained in all of the selected parent nodes will be copied for each instance of that
node. For example, if a client node contains multiple invoice nodes, the information for the client
node can be duplicated for each invoice.
l
l
Use root element: Locks the XML Elements option to the top-level element. If there is
only one top-level element, there will only be one record before the Boundaries are set.
XML elements: Displays a list containing all the elements in the XML file. Selecting an
element causes a new page of data to be created every time an instance of this element
is encountered.
The Boundaries
When the Data Source is received by the DataMapper, it has no boundaries to tell the
DataMapper if it contains different records or where each of those records begins and ends.
This is because boundaries are not actual bits of data (like a character or a field would be).
Boundaries are a logical structure outside the Data Source (note that some formats like
PDF/VT actually include structured information, but those are the exception rather than the
rule). Boundaries are therefore a form of metadata. You could very well use the exact same
data with a different boundary structure in order to extract different information. Think, for
instance, of an Invoice Run stored in a PDF. You can use a structure where each invoice is a
Page 142
single record or you could group all invoices for one customer into a single record. So the
boundaries for each record can be completely dependent on how you want to use the data.
With no actual boundary markers inside the data, there needs to be a way to identify specific
locations in the input stream and mark those locations as record boundaries. Fortunately, every
single file format has intrinsic, natural delimiters that are used to identify chunks of related data.
These delimiters are key in helping us identify boundaries, so it is important to understand what
they are as well as when and why they occur in the Data Source.
Let's start with a seemingly arbitrary assumption: a boundary can only occur on a natural
delimiter. That is to say, a record boundary never occurs between delimiters; it only occurs on a
delimiter. The actual information we need to determine whether a delimiter can be a boundary
is very likely to be found between delimiters.
For a CSV or Database File
The natural delimiter for a CSV file is a data record, or to put it more visually, each line in a
spreadsheet or in a SQL data grid is a delimiter. Several such delimiters can be included in a
record, but you would never expect to find the end of one particular record right in the middle of
one of these lines in the grid. So the record occurs with a new line in the grid, but not on each
new line.
Since database data sources are structured the same way as CSV files, the options are
identical to these files. Boundaries will define how many lines appear for each Source Record.
This can be a static number of lines or it can be determined based on a field change that will
create a new record. For example, this can happen when the customer ID changes. There is
also an advanced scripting option to determine boundaries (see Javascript for Boundaries for
details).
l
l
l
Record limit: Defines how many Source Records are displayed in the Data Viewer. This
does not affect output production, as generating output ignores this option. To disable the
limit, use the value "0".
Line limit: Defines the limit of detail lines in any detail table. This is useful for files with a
high number of detail lines, which in the DataMapper interface can slow down things.
This does not affect output production, as generating output ignores this option. To
disable the limit, use the value "0".
Trigger: Defines the type of rule that controls when a boundary is created, establishing a
new record in the Data Sample (called a Source Record).
Page 143
l
Record(s) per page: Defines a fixed number of lines in the file that go in each
Source Record.
l
l
On change: Defines a new Source Record when a specific field (Field name) has a
new value.
l
l
l
Records: The number of records to show in each Source Records.
Field name: Displays the fields in the top line. The selected value determines
new boundaries.
On script: Defines the boundaries using a custom user-defined JavaScript. For
more information see Boundaries Using javaScript.
On field value: Defines the boundary for the contents of a specific field value.
l
l
l
Field name: Displays the fields in the top line. The selected value is
compared with the Expression below to create a new boundary.
Expression: Enter the value or Regular Expression that triggers a new
boundary when it is the field value.
Use Regular Expression: Treats the Expression as a regular expression
instead of static text. For more information on using Regular Expressions
(regex), see the Regular-Expressions.info Tutorial.
For a PDF File
Boundaries will determine how many pages are included in each of the Source Records. You
can set this up in one of three ways: by giving it a static number of pages; by checking a
specific area on each page for text changes, specific text, or the absence of text; or by using an
advanced script. For example, you could check if “Page 1 of” appears at the top left of the page,
which means it is the first page of each Source Record, regardless of how many pages are
actually in the document.
Note
While a record boundary always occurs on a new page, the opposite is not true: a new page is not
always a record boundary.
l
Record limit: Defines how many Source Records are displayed in the Data Viewer. To
disable the limit, use the value "0".
Page 144
l
Trigger: Defines the type of rule that defines when a boundary is created, establishing a
new record in the Data Sample (called a Source Record).
l
On page: Defines a boundary on a static number of pages.
l
l
Number of pages: Defines how many pages are in each Source Record.
On text: Defines a boundary on a specific text comparison in the Source Record.
l
l
l
Start coordinates (x,y): Defines the left and top coordinates of the data
selection to compare with the text value.
Stop coordinates (x,y): Defines the right and bottom coordinates.
Use Selection: Select an area in the Data Viewer and click the Use selection
button to set the start and stop coordinates to the current data selection in the
Source Record.
Note
In a PDF file, all coordinates are in millimeters.
l
l
Times condition found: When the boundaries are based on the presence of
specific text, you can specify after how many instances of this text the
boundary can be effectively defined. For example, if a string is always found
on the first and on the last page of a document, you could specify a number of
occurrences of 2. In this way, no need to inspect other items for whether it is
on the first page or the last page. you know you have found the string two
times, which is enough to fix the boundary.
Pages before/after: Defines the boundary a certain number of pages before
or after the current page. This is useful if the text triggering the document is not
located on the first page of each Source Record.
l
Operator: Selects the type of comparison (for example, "contains").
l
Word to find: Compares the text value with the value in the Source Record.
l
Match case: Makes the text comparison case-sensitive.
For a Text File
For a Text file, the natural delimiter is also a Page, but contrary to PDF, the Page delimiter can
either be explicit (say, when a Form Feed character is encountered in the Data Source) or
implicit (when a certain number of lines has been reached, usually around 66). Once more, the
Page 145
end of a record would not be found in the middle of a line. Note also that it is possible with this
format to set the DataMapper's Input Data settings to 1 line per page. That essentially allows
you to set the natural delimiter on each and every line in the file.
If you select the wrong page at the top, for example, making a new selection and clicking on
Select the area will redefine the location. The other option is Use selected text, which simply
copies the text in the current selection as the one to compare to it.
l
l
Record limit: Defines how many Source Records are displayed in the Data Viewer. To
disable the limit, use the value "0".
Trigger: Defines the type of rule that defines when a boundary is created, establishing a
new record in the Data Sample (called a Source Record).
l
On delimiter: Defines a boundary on a static number of pages.
l
l
Occurrences: The number of times that the delimiter is encountered before
fixing the boundary. For example, if you know that your documents always
have four pages delimited by the FF character, you can set the boundaries
whenever you counted four delimiters.
On text: Defines a boundary on a specific text comparison in the Source Record.
l
Location:
l
Selected area:
l
l
l
l
l
l
l
Select the area button: Uses the value of the current data
selection as the text value.
Left/Right: Defines where to find the text value in the row.
Top/Bottom: Defines the start and end row of the data selection to
compare with the text value.
Entire width: Ignores the column values and compares using the whole
line.
Entire height: Ignores the row values and compares using the whole
column.
Entire page: Compares the text value on the whole page. Only available
with contains, not contains, is empty and is not empty operators.
Times condition found: When the boundaries are based on the presence of
specific text, you can specify after how many instances of this text the
boundary can be effectively defined. For example, if a string is always found
Page 146
on the first and on the last page of a document, you could specify a number of
occurrences of 2. In this way, no need to inspect other items for whether it is
on the first page or the last page. you know you have found the string two
times, which is enough to fix the boundary.
l
l
Delimiters before/after: Defines the boundary a certain number of pages
before or after the current page. This is useful if the text triggering the
document is not located on the first page of each Source Record.
l
Operator: Selects the type of comparison (for example, "contains").
l
Word to find: Compares the text value with the value in the Source Record.
l
Match case: Makes the text comparison case-sensitive.
On script: Defines the boundaries using a custom user-defined JavaScript. For
more information see Boundaries Using javaScript.
For a XML File
Since we know the delimiter for an XML file is a node, all we need to set for the Boundaries is
how many of those nodes we want to use. A specific number can be used, like when we have
one invoice node per Source Record─or be determined when the content of a specific field
within that node changes (e.g. when the invoice_number field changes in the invoice node).
l
l
Record limit: Defines how many Source Records are displayed in the Data Viewer. To
disable the limit, use the value "0".
Trigger: Defines the type of rule for when a boundary is created, establishing a new
record in the Data Sample (called a Source Record).
l
On Element: Defines a new Source Record on each new instance of the XML level
selected in the XML elements.
l
l
Occurrences: The number of times that the delimiter is encountered before
fixing the boundary. For example, if you know that your documents always
have four pages delimited by the FF character, you can set the boundaries
whenever you counted four delimiters.
On Change: Defines a new Source Record when a specific field under the XML
level has a new value.
l
Field: Displays the fields that are under the XML level. The value of the
selected fields determines the new boundaries.
Page 147
The Data Samples
The Data Sample area displays a list of all the imported Data Samples that are available now
in the data mapping configuration. As many Data Samples as necessary can be imported to
properly test the configuration.
Instead of buttons listed below, you can also right-click to bring up the context menu, which
offers the same options.
l
l
l
l
l
Add
: Adds a new Data Sample from an external Data Source. The new Data Sample
will need to be of the same data type as the current one. For example, you can only add
PDF files to a PDF data mapping configuration. In version 1.3 and higher, multiple files
can be added simultaneously through the Add dialog.
Delete
: Removes the current Data Sample from the data mapping configuration.
Replace : Opens a new Data Sample and replaces it with the contents of a different
data source.
Reload : Reloads the currently selected Data Sample and any changes that have been
made to it.
Set as Active
: Activates the selected Data Sample. The active data sample is shown
in the Data Viewer after it has gone through the Preprocessor step as well as the Input
Data and Boundary settings.
The External JS Libraries
Right-clicking in the box brings up a control menu, also available through the buttons on the
right:
l
Add
: Adds a new external library. Opens the standard Open dialog to browse and
open the .js file.
l
Delete
l
Replace
l
Reload
to it.
: Removes the currently selected library from the data mapping configuration.
: Opens a new library and replaces it with the contents of a different js file.
: Reloads the currently selected library and any changes that have been made
Page 148
Default Data Format
Default Format Settings can also be defined at the DataMapper configuration level (see
DataMapper Default Data Format for more information).
SQL Query Designer
The SQL Query Designer is used to design a custom SQL query to pull information from a
database.
l
l
l
l
Tables: Lists all tables and stored queries in the database.
Custom Query: Displays the query that retries information from a database. Each
database type has their own version of the SQL query language. To learn how to build
your own query, please refer to your database's user manual.
Test Query button : Click to test the custom query to ensure it will retrieve the
appropriate information.
Results: Displays the result of the SQL query when clicking on Test Query.
The Steps Pane Interface
The Steps tab displays the process that prepares and extracts data. The process contains
multiple distinct steps and is run for each of the Source Records in our Data Sample.
Window Controls
The following controls appear at the top of the Steps pane:
l
Zoom In (CTRL +) : Click to zoom in by increments of 10%
l
Zoom Out (CTRL -) : Click to zoom out by increments of 10%
Contextual Menu
You can access the contextual menu using a right-click anywhere inside the Steps pane:
Page 149
l
Add a Step: Adds a step to the process. Right click anywhere in the Steps pane and
select Add a Step from the contextual menu. For more information about the steps and
how to use them, please refer to Steps. More options are available when a Repeat or a
Condition step is selected:
l
Add Step in Repeat: To add a step into the Repeat loop, right-click on the step and
select Add a Step in Repeat.
Page 150
l
Add Step in True: To add a step under the true branch of a condition step, rightclick on the condition and select Add a Step in True.
Page 151
l
l
l
Add Step in False: To add a step under the false branch of a condition step, rightclick on the condition and select Add a Step in False.
Add Multiple Conditions Step: To add a Multiple Conditions step.
Add Case Step: Add a case condition under the selected Multiple Conditions
step.
Page 152
l
l
Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps are grayed
and do not run when in DataMapper and do not execute when the data mapping
configuration is executed in Workflow. However, they can still be modified normally.
Moving: To move a step, right-click on it and select Cut Step or use the
button in the
Toolbar. If the step is Repeat or Condition, all steps under it will also be placed in the
clipboard. If there is already a step in the clipboard, it will be overwritten. To place the
step at its destination, right-click the step in the position before the desired location and
click Paste Step, or use the
button in the toolbar.
Page 153
Note
You can also use a drag & drop to move steps.
l
Delete Step: To remove a step, right-click on it and select Delete step from the contextual
menu or use the
button in the Toolbar. If the step to be deleted is Repeat or
Condition, all steps under it will also be deleted.
Warning
Currently there is no Undo and Redo feature in the DataMapper module. Deleting
a step is permanent!
Page 154
l
l
Copy Step: To copy a step, right-click on it and select Copy Step or use the
button in
the Toolbar. If the step is Repeat or Condition, all steps under it will also be placed in the
clipboard. If there is already a step in the clipboard, it will be overwritten. To place a copy
of the step at its destination, right-click the step in the position before the desired location
and select Paste Step, or use the
button in the Toolbar.
Viewing step details: To see details for the step, click on the step to show its properties
in the Step Properties pane. Hovering over the task shows a tooltip that displays some of
the details as well as the property name and comment.
Step Properties
The Step Properties pane is used to adjust the properties of each step in the process. The pane
is divided in a few subsections depending on the step and the data type. It always contains a
subsection to name and document the selected steps however.
Note
Step properties may also depend on the Data Sample's file type.
Preprocessor Step
Extract Step
Action Step
Repeat Step
Condition Step
Multiple Conditions Step
Goto Step
Postprocessor Step
Preprocessor Step Properties
The Preprocessor step does not run for every Source Record in the Data Sample. It runs once,
at the beginning of the Steps, before anything else.
Fixed Automation Properties
The Fixed automation properties subsection lists all the fixed properties available from the
PlanetPress Workflow automation module. These properties are equivalent to data available
Page 155
within the PlanetPress Workflow process. For each property, the following is available:
l
Name: A read-only field displaying the name of the property.
l
Scope: A read-only field indicating that the scope of the property is Automation.
l
Type: A read-only field indicating the data type for each property.
l
Default Value: Enter a default value for the property. This value is overwritten by the
actual value coming from PlanetPress Workflow when the data mapping configuration is
run using the Execute Data Mapping task.
There are currently the following automation properties available:
l
l
l
l
JobInfoX: These properties are the equivalent of the JobInfo values available in the
PlanetPress Workflow process. They can be set using the Set Job Info and Variables
task. To access these properties inside of any JavaScript code within the Data Mapping
Configuration, use the automation.jobInfos.JobInfoX (where X is the job info number, from
0 to 9).
OriginalFilename: This property contains the original file name that was captured by the
PlanetPress Workflow process and is equivalent to the %o variable in the process. To
access these property inside of any JavaScript code within the Data Mapping
Configuration, use automation.properties.OriginalFilename.
ProcessName: This property contains the name of the process that is currently executing
the data mapping configuration and is equivalent to the %w variable in the process. To
access this property inside of any JavaScript code within the Data Mapping
Configuration, use automation.properties.ProcessName.
TaskIndex: This property contains the index (position) of the task inside the process that
is currently executing the data mapping configuration but it has no equivalent in
PlanetPress Workflow. To access this property inside of any JavaScript code within the
Data Mapping Configuration, use automation.properties.ProcessName.
Properties
The Properties subsection is used to create specific properties that are used throughout the
workflow. Properties can be accessed through some of the interface elements such as the
Condition and Repeat step properties, or through the DataMapper API.
Page 156
Note
Properties are evaluated in the order they are placed in the list, so properties can use the
values of previously defined properties in their expression.
l
Name: The name of the property used to refer to its value.
l
Scope: What this property applies to:
l
l
l
l
l
Entire Data: These properties are static properties that cannot be changed once
they have been set, in other words they are Global constants.
Each Record: These properties are evaluated and set at the beginning of each
Source Record. These properties can be modified once they have been set, but are
always reset at the beginning of each Source Record.
Automation variable: These properties initialize variables coming from the
PlanetPress Workflow automation tool. The name of the property needs to be the
same as the variable name in Workflow, and they can be either a Local variable or a
Global variable. For either one, only the actual name is to be used, so for %
{MyLocalVar} use only MyLocalVar , and for %{global.MyGlobalVar} use
MyGlobalVar. If a global and a local variable have the same name ( %{myvar} and
%{global.myvar} ), the local variable's value is used and the global one is ignored.
To access a workflow variable inside of any JavaScript code within the Data
Mapping Configuration, use automation.variables.variablename
Type: The data type of the property. For more information see Data Types.
Default Value: The initial value of the property. This is a JavaScript expression. See
DataMapper API.
Technical
Entire Data Properties are evaluated before anything else, such as Preprocessors,
Delimiters and Boundaries in the Settings Pane. This means these properties cannot
read information from the Data Sample or from any records. They are mostly useful for
static information such as folder locations or server addresses.
Page 157
Preprocessor
The Preprocessor subsection defines what preprocessors run on the Data Sample before it is
sent to the extraction. Preprocessors modify the Data Sample in many ways, and each
Preprocessor runs in turn, using the result of the previous one as an input.
l
Name: The name to identify the Preprocessor.
l
Type: The type of Preprocessor. Currently there is only one type available.
Preprocessor definition
l
Expression: The JavaScript expression that will run on the Data Sample. See
DataMapper API.
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Extract Step Properties
The Extract step takes information from the Data Sample and places it in the Extracted Record
within the Record Set.
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Page 158
Extraction Definition
l
l
Data Table: Defines where the data will be placed in the Extracted Record. The root
table is record, any other table becomes a detail table. For more information see detail
tables.
Append values to current record: When the Extract Step is within a loop, check this to
ensure that the extraction will be done in the same detail line as any previous extractions
within the same loop. This ensures that, if multiple extracts are present, only one detail
line is created.
Field Definition
This sub-section explains how the currently selected Extract Field in the Field List is defined.
Text File
l
l
l
Field List: The Field List displays each of the single fields that are being extracted in a
drop-down. Fields can be re-ordered and re-named within the Ordering and Renaming
Fields dialog.
Add Unique ID to extraction field: Check to add a unique numerical set of characters to
the end of the extracted value. This ensures no two values are identical in the Record Set.
Mode: Determines the origin of the extracted data.
l
Location: The contents of the data selection set below will determine the value of
the extracted field.
l
Left: Defines the start of the data selection to extract.
l
Right: Defines the end of the data selection to extract.
l
l
l
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Height: The height of the selection box.
Use selection: Click to use the value (Left, Right and Height) of the current
data selection (in the Viewer) for the extraction.
Page 159
Note
If the selection contains multiple lines, only the first line is selected.
l
Post Function: Enter a JavaScript expression to be run after the extraction.
For example replace("-","") would replace a single dash character inside the
extracted string.
l
l
Trim: Select to trim empty characters at the beginning or the end of the field.
l
Concatenation string:
l
l
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Split: Separate the selection into individual fields based on the
Concatenation string defined above.
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
Type: The data type of the selected data. Please refer to ...(link to come) for more
information.
PDF File
l
Field List: The Field List displays each of the single fields that are being extracted in a
drop-down. Fields can be re-ordered and re-named within the Ordering and Renaming
Fields dialog.
l
l
l
Add JavaScript Field: Click to add a new extract field. By default, the field will be a
JavaScript -defined field rather than a data extraction, of String data type.
l
Remove Extract Field: Click to delete the selected extract field from the list.
l
Order and rename fields: Click to openOrdering and Renaming Fields.
Add Unique ID to extraction field: Check to add a unique numerical set of characters to
the end of the extracted value. This ensures no two values are identical in the Record Set.
Mode: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
Page 160
l
Left: Defines the start of the data selection to extract.
l
Right: Defines the end of the data selection to extract.
l
l
l
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Height: The height of the selection box.
Use selection: Click to use the value (Left, Right and Height) of the current
data selection for the extraction.
Note
If the selection contains multiple lines, only the first line is selected.
l
l
l
l
l
l
l
Post Function: Enter a JavaScript expression to be run after the extraction.
For example replace("-","") would replace a single dash character inside the
extracted string.
Trim: Select to trim empty characters at the beginning or the end of the field.
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
Concatenation string:
Split: Separate the selection into individual fields based on the
Concatenation string defined above.
Sub-Fields:
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
l
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Use selection: Click to use the value of the current data selection for the
extraction.
Page 161
Note
If the selection contains multiple lines, only the first line is selected.
l
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
CSV and Database Files
l
Field List: The Field List displays each of the single fields that are being extracted in a
drop-down. Fields can be re-ordered and re-named within the Ordering and Renaming
Fields dialog.
l
l
l
Add JavaScript Field: Click to add a new extract field. By default, the field will be a
JavaScript -defined field rather than a data extraction, of String data type.
l
Remove Extract Field: Click to delete the selected extract field from the list.
l
Order and rename fields: Click to openOrdering and Renaming Fields.
Add Unique ID to extraction field: Check to add a unique numerical set of characters to
the end of the extracted value. This ensures no two values are identical in the Record Set.
Mode: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
l
l
Column: Drop-down listing all fields in the Data Sample, of which the value
will be used.
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
l
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is
selected.
Page 162
l
Post Function: Enter a JavaScript expression to be run after the extraction.
For example replace("-","") would replace a single dash character inside the
extracted string.
l
l
l
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Trim: Select to trim empty characters at the beginning or the end of the field.
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
Expression:
l
l
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only
the first one is used.
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is
selected.
l
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
XML File
l
Field List: The Field List displays each of the single fields that are being extracted in a
drop-down. Fields can be re-ordered and re-named within the Ordering and Renaming
Fields dialog.
l
Add JavaScript Field: Click to add a new extract field. By default, the field will be a
JavaScript -defined field rather than a data extraction, of String data type.
Page 163
l
l
l
Remove Extract Field: Click to delete the selected extract field from the list.
l
Order and rename fields: Click to openOrdering and Renaming Fields.
Add Unique ID to extraction field: Check to add a unique numerical set of characters to
the end of the extracted value. This ensures no two values are identical in the Record Set.
Based on: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
l
XPath: The path to the XML field that is extracted.
l
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is
selected.
l
Post Function: Enter a JavaScript expression to be run after the extraction.
For example replace("-","") would replace a single dash character inside the
extracted string.
l
l
l
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Trim: Select to trim empty characters at the beginning or the end of the field.
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
Expression:
l
Use JavaScript Editor: Click to display the Script Editor dialog.
Page 164
l
l
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only
the first one is used.
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is
selected.
l
Type: The data type of the selected data. Please refer to ...(link to come) for
more information.
Data Format
The data format defines the precise format for some of the variable types, such as dates and
currencies.
l
Boolean
l
String
l
HTML String
l
Integer
l
l
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Float
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values, generally
a dot (.).
Page 165
l
l
l
Treat empty as 0: Considers empty spaces as 0.
Currency
l
l
l
l
l
l
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values, generally
a dot (.).
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Currency Sign: Determines the character to add before the value in the Extracted
Record.
Treat empty as 0: Considers empty spaces as 0.
Date
l
l
Date/Time Format: Determines how the date is read. The format written here needs
to correspond with the format in the data selection.
Language: The language in which the date is written, when relevant. Useful when
months or days are written alphabetically.
Note
Default Format Settings can be defined at the user level, at the Datamapper configuration level
and/or at the field level. (see Datamapper Default Data Format for more information).
Ordering and Renaming Fields
The Order and rename fields dialog appears from the Extract step by clicking on the Rename
Fields button
next to the field list. This dialog displays the extracted fields in the currently
selected Extract step. Field extractions are executed from top to bottom. Using JavaScript
fields, it is possible to refer to previously extracted fields if they are extracted higher in this list or
in previous Extract steps in the extraction workflow.
l
Name: The name of the field. Click the field name and enter a new name to rename the
field.
Page 166
If you intend to use the field names as metadata in a PlanetPress Workflow process, do
not add spaces to field names, as they are not permitted in metadata field names.
l
Value: Displays the value of the extract field in the current Record.
l
Remove button
: Click to remove the currently selected field.
l
Move Up button
: Click to move the selected field up one position.
l
Move Down button
: Click to move the selected field down one position.
Action Step Properties
The Action step can run multiple specific actions one after the other in order. More actions will
be available in the future.
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Actions
This subsection lists all actions executed by the step, and their types:
l
Name: A name by which to refer to the action. This name has no impact on functionality.
l
Type:
l
l
Set property: Sets the value of a Source Record property which was created in the
Preprocessor Step.
Run JavaScript : Runs a JavaScript expression, giving much more flexibility over
the extraction process.
Set Property
Text and PDF Files
Page 167
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
l
Type: Displays the type of the Source Record property. Read only field.
l
Based on: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
l
Left: Defines the start of the data selection to extract
l
Right: Defines the end of the data selection to extract
l
l
l
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Height: The height of the selection box.
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is selected.
l
l
Trim: Select to trim empty characters at the beginning or the end of the field
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
Expression: The JavaScript expression to run.
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
l
l
Setting Properties and Record Field values using advanced
expressions
Do complex mathematical operations and calculations
Page 168
l
l
l
More features to come in future versions. For more information,
see JavaScript in DataMapper.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is selected.
l
Data Format
The data format defines the precise format for some of the variable types, such as dates
and currencies.
l
Boolean
l
String
l
HTML String
l
Integer
l
l
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Float
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Page 169
l
l
l
Treat empty as 0: Considers empty spaces as 0.
Currency
l
l
l
l
l
l
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Currency Sign: Determines the character to add before the value in the
Extracted Record.
Treat empty as 0: Considers empty spaces as 0.
Date
l
l
Date/Time Format: Determines how the date is read. The format written here
needs to correspond with the format in the data selection.
Language: The language in which the date is written, when relevant. Useful
when months or days are written alphabetically.
Note
Default Format Settings can be defined at the user level, at the Datamapper configuration
level and/or at the field level. (see Datamapper Default Data Format for more
information).
CSV and Database Files
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
l
Type: Displays the type of the Source Record property. Read only field.
l
Based on: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
Page 170
l
l
l
Column: Drop-down listing all fields in the Data Sample, of which the value
will be used.
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is selected.
l
l
Trim: Select to trim empty characters at the beginning or the end of the field
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
Expression: The JavaScript expression to run.
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
l
l
l
l
Setting Properties and Record Field values using advanced
expressions
Do complex mathematical operations and calculations
More features to come in future versions. For more information,
see JavaScript in DataMapper.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Page 171
l
Use selection: Click to use the value of the current data selection for the
extraction.
Note
If the selection contains multiple lines, only the first line is selected.
l
Data Format
The data format defines the precise format for some of the variable types, such as dates
and currencies.
l
Boolean
l
String
l
HTML String
l
Integer
l
l
l
l
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Float
l
l
l
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Currency
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Page 172
l
l
l
l
l
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Currency Sign: Determines the character to add before the value in the
Extracted Record.
Treat empty as 0: Considers empty spaces as 0.
Date
l
l
Date/Time Format: Determines how the date is read. The format written here
needs to correspond with the format in the data selection.
Language: The language in which the date is written, when relevant. Useful
when months or days are written alphabetically.
Note
Default Format Settings can be defined at the user level, at the Datamapper configuration
level and/or at the field level. (see Datamapper Default Data Format for more
information).
XML File
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
l
Type: Displays the type of the Source Record property. Read only field.
l
Based on: Determines the origin of the data.
l
Location: The contents of the data selection set below will be the value of the
extracted field. The data selection settings are different depending on the data
sample type.
l
XPath: The path to the XML field that is extracted.
l
Use selection: Click to use the value of the current data selection for the
extraction.
Page 173
Note
If the selection contains multiple lines, only the first line is
selected.
l
l
Trim: Select to trim empty characters at the beginning or the end of the
field
JavaScript : The result of the JavaScript Expression written below the drop-down
will be the value of the extracted field. If the expression contains multiple lines, the
last value attribution (variable = "value";) will be the value. See DataMapper API.
l
Expression: The JavaScript expression to run.
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
l
l
l
l
l
Setting Properties and Record Field values using advanced
expressions
Do complex mathematical operations and calculations
More features to come in future versions. For more information,
see JavaScript in DataMapper.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Use selection: Click to use the value of the current data selection for the
extraction.
Page 174
Note
If the selection contains multiple lines, only the first line is selected.
l
Data Format
The data format defines the precise format for some of the variable types, such as dates
and currencies.
l
Boolean
l
String
l
HTML String
l
Integer
l
l
l
l
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Float
l
l
l
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Treat empty as 0: Considers empty spaces as 0.
Currency
l
l
Negative Sign Before: Adds a negative (-) sign before negative values in the
Extracted Record.
Decimal Separator: Determines the character to use for decimal values,
generally a dot (.).
Page 175
l
l
l
l
Thousand Separator: Adds the selected character between each thousand
position (for example, "1,000,000")
Currency Sign: Determines the character to add before the value in the
Extracted Record.
Treat empty as 0: Considers empty spaces as 0.
Date
l
l
Date/Time Format: Determines how the date is read. The format written here
needs to correspond with the format in the data selection.
Language: The language in which the date is written, when relevant. Useful
when months or days are written alphabetically.
Note
Default Format Settings can be defined at the user level, at the Datamapper configuration
level and/or at the field level. (see Datamapper Default Data Format for more
information).
Run JavaScript
l
Expression: The JavaScript expression to run.
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
l
Setting Properties and Record Field values using advanced expressions
l
Do complex mathematical operations and calculations
l
l
l
More features to come in future versions. For more information, see JavaScript
in DataMapper.
Use selected text: Inserts the text in the current data selection in the JavaScript
Expression. If multiple lines or elements are selected, only the first one is used.
Use selection: Click to use the value of the current data selection for the extraction.
Page 176
Note
If the selection contains multiple lines, only the first line is selected.
Repeat Step Properties
The Repeat step is a loop that runs more than once. There are multiple types of repeat steps
used for different actions. Repeat steps do not automatically move the pointer in the file. In
order to avoid infinite loops, a Goto step must be present within the loop itself.
By default, if an Extract step is added within a Repeat step, its extraction is made in a Details
Table.
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Repeat Definition
l
Repeat type:
l
l
l
l
While statement is true: The loop executes while the statement below is true. The
statement is evaluated after the loop so the loop will always run at least once.
Until statement is true: The loop executes until the statement below is true. The
statement is evaluated before the loop so the loop may not run at all.
Until no more elements (for Text, CSV, Database and PDF files only): The loop
executes as long as there are elements left as selected below.
For Each (for XML files only): The loop executes for all nodes on a specified level.
Page 177
Note
When using an XML For Each loop, it is not necessary to skip to the
repeating node or to have a Gotostep to jump to each sibling, as this loop
takes care of it automatically.
l
Maximum iterations on each line: Defines the maximum number of iterations occurring
at the same position. This expression is evaluated once when entering the loop. The
value returned by the expression must be an integer higher than 0.
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
l
l
l
Setting Properties and Record Field values using advanced
expressions
Do complex mathematical operations and calculations
More features to come in future versions. For more information, see
JavaScript in DataMapper.
Rule Tree
The Rule tree subsection displays the full combination rules (defined below under Condition)
as a tree, which gives an overview of how the conditions work together as well as the result for
each of these conditions for the current record or iteration.
Condition
First, the Condition List displays the conditions in list form, instead of the tree form above.
Three buttons are available next to the list:
l
Add condition: Click to create a new condition in the list. This will always branch the
current condition as an "AND" operator.
Page 178
l
Delete condition: Delete the currently selected condition.
l
To rename a Condition, double click on its name from the Rule tree subsection .
Conditions are made by comparison of two operands using a specific Operator.
Technical
Both the Left and Right operands have the same properties.
Text and PDF Files
l
Based On:
l
Position: The data in the specified position for the comparison.
l
l
l
l
l
l
l
l
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Height: The height of the selection box.
Use Selection: Click to use the value of the current data selection for the
extraction.
Trim: Select to trim empty characters at the beginning or the end of the field.
Value: The text value to use in the comparison.
Use selected text: Uses the text in the current data selection as the Value. If
multiple lines or elements are selected, only the first one is used.
Field: The contents of a specific field in the Extracted Record.
l
l
Right: The end position for the data selection.
Value: A specified static text value.
l
l
Left: The start position for the data selection. Note that conditions are done on
the current line, either the current cursor position, or the current line in a
Repeat step.
Field: The Extracted Record field to use in the comparison.
JavaScript : The result of a JavaScript Expression.
l
Expression: The JavaScript line that is evaluated. Note that the last value
attribution to a variable is the one used as a result of the expression.
Page 179
l
l
l
l
l
l
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Data Property: The value of a data-level property set in the Preprocessor Step.
Record Property: One of the local variables that you can create and that are reset
for each document as opposed to data variables that are global because they are
initialized only once at the beginning of each job.
Automation Property: The current value of a Document-level property set in the
Preprocessor Step.
Extractor Property: The value of an internal extractor variable:
l
l
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Counter: The value of the current counter iteration in a Repeat step.
Vertical Position: The current vertical position on the page, either in Measure
(PDF) or Line (Text and CSV).
Operators:
l
l
l
l
l
l
is equal to: The two specified value are identical for the condition to be True.
contains: The first specified value contains the second one for the condition to be
True.
is less than: The first specified value is smaller, numerically, than the second value
for the condition to be True.
is greater than: The first specified value is larger, numerically, than the second
value for the condition to be True.
is empty: The first specified value is empty. With this operator, there is no second
value.
Invert condition: Inverts the result of the condition. For instance, is empty becomes
is not empty.
CSV and Database Files
l
Based On:
Page 180
l
Position: The data in the specified position for the comparison.
l
l
l
l
l
l
l
l
l
l
Trim: Select to trim empty characters at the beginning or the end of the field.
Value: The text value to use in the comparison.
Use selected text: Uses the text in the current data selection as the Value. If
multiple lines or elements are selected, only the first one is used.
Field: The Extracted Record field to use in the comparison.
JavaScript : The result of a JavaScript Expression.
l
l
Use Selection: Click to use the value of the current data selection for the
extraction.
Field: The contents of a specific field in the Extracted Record.
l
l
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Value: A specified static text value.
l
l
Column: Drop-down listing all fields in the Data Sample, of which the value
will be used.
Expression: The JavaScript line that is evaluated. Note that the last value
attribution to a variable is the one used as a result of the expression.
Use JavaScript Editor: Click to display the Edit Script dialog.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Data Property: The value of a data-level property set in the Preprocessor step.
Record Property: One of the local variables that you can create and that are reset
for each document as opposed to data variables that are global because they are
initialized only once at the beginning of each job.
Automation Property: The current value of a Document-level property set in the
Preprocessor step.
Page 181
l
Extractor Property: The value of an internal extractor variable:
l
l
l
Counter: The value of the current counter iteration in a Repeat step.
Vertical Position: The current vertical position on the page, either in Measure
(PDF) or Line (Text and CSV).
Operators:
l
l
l
l
l
l
is equal to: The two specified value are identical for the condition to be True.
contains: The first specified value contains the second one for the condition to be
True.
is less than: The first specified value is smaller, numerically, than the second value
for the condition to be True.
is greater than: The first specified value is larger, numerically, than the second
value for the condition to be True.
is empty: The first specified value is empty. With this operator, there is no second
value.
Invert condition: Inverts the result of the condition. For instance, is empty becomes
is not empty.
XML Files
l
Based On:
l
Position: The data in the specified position for the comparison.
l
l
l
l
Use Selection: Click to use the value of the current data selection for the
extraction.
Trim: Select to trim empty characters at the beginning or the end of the field.
Value: A specified static text value.
l
l
l
XPath: The path to the XML field that is extracted.
Value: The text value to use in the comparison.
Use selected text: Uses the text in the current data selection as the Value. If
multiple lines or elements are selected, only the first one is used.
Field: The contents of a specific field in the Extracted Record.
l
Field: The Extracted Record field to use in the comparison.
Page 182
l
JavaScript : The result of a JavaScript Expression.
l
l
l
l
l
l
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Data Property: The value of a data-level property set in the Preprocessor step.
Record Property: One of the local variables that you can create and that are reset
for each document as opposed to data variables that are global because they are
initialized only once at the beginning of each job.
Automation Property: The current value of a Document-level property set in the
Preprocessor step.
Extractor Property: The value of an internal extractor variable:
l
l
l
Expression: The JavaScript line that is evaluated. Note that the last value
attribution to a variable is the one used as a result of the expression.
Counter: The value of the current counter iteration in a Repeat step.
Vertical Position: The current vertical position on the page, either in Measure
(PDF) or Line (Text and CSV).
Operators:
l
l
l
l
l
l
is equal to: The two specified value are identical for the condition to be True.
contains: The first specified value contains the second one for the condition to be
True.
is less than: The first specified value is smaller, numerically, than the second value
for the condition to be True.
is greater than: The first specified value is larger, numerically, than the second
value for the condition to be True.
is empty: The first specified value is empty. With this operator, there is no second
value.
Invert condition: Inverts the result of the condition. For instance, is empty becomes
is not empty.
Page 183
Multiple Conditions Step Properties
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Condition
Left Operand
The Left operand indicates the criterion that every case will be compared to. It can be Based
on:
l
Position: The data in the specified position for the comparison.
l
Left (Txt and PDF only): The start position for the data selection. Note that
conditions are done on the current line, either the current cursor position, or the
current line in a Repeat step.
l
Right (Txt and PDF only): The end position for the data selection.
l
Height (Txt and PDF only): The height of the selection box.
l
l
l
Column (CSV and Database only): Drop-down listing all fields in the Data Sample,
of which the value will be used.
XPath (XML only): The path to the XML field that is extracted.
Top offset: The vertical offset from the current pointer location in the Data Sample
(Viewer).
l
Use Selection: Click to use the value of the current data selection for the extraction.
l
Trim: Select to trim empty characters at the beginning or the end of the field.
Page 184
l
Value: A specified static text value.
l
l
l
l
l
l
l
l
Field: The Extracted Record field to use in the comparison.
JavaScript : The result of a JavaScript Expression.
l
l
Use selected text: Uses the text in the current data selection as the Value. If
multiple lines or elements are selected, only the first one is used.
Field: The contents of a specific field in the Extracted Record.
l
l
Value: The text value to use in the comparison.
Expression: The JavaScript line that is evaluated. Note that the last value
attribution to a variable is the one used as a result of the expression.
Use JavaScript Editor: Click to display the Edit Script dialog.
Use selected text: Inserts the text in the current data selection in the JavaScript
Expression. If multiple lines or elements are selected, only the first one is used.
Data Property: The value of a data-level property set in the Preprocessor Step.
Record Property: One of the local variables that you can create and that are reset for
each document as opposed to data variables that are global because they are initialized
only once at the beginning of each job.
Automation Property: The current value of a Document-level property set in the
Preprocessor Step.
Extractor Property: The value of an internal extractor variable:
l
l
Counter: The value of the current counter iteration in a Repeat step.
Vertical Position: The current vertical position on the page, either in Measure
(PDF) or Line (Text and CSV).
Condition
The Condition drop-down displays the conditions in list form. Three buttons are available next
to the list:
l
l
Add condition: Click to create a new condition in the list. This will always branch the
current condition as an "AND" operator.
Delete condition: Delete the currently selected condition.
Page 185
l
Order Multiple Conditions: Under the Name column, select a case then click one of the
buttons on the right (Delete, Move Up, Move Down) to delete or change the order of a
case in the list.
Operators
Case conditions are made by comparison of the two operands, left and right, using a specific
Operator.
l
is equal to: The two specified value are identical for the condition to be True.
l
contains: The first specified value contains the second one for the condition to be True.
l
l
l
l
is less than: The first specified value is smaller, numerically, than the second value for
the condition to be True.
is greater than: The first specified value is larger, numerically, than the second value for
the condition to be True.
is empty: The first specified value is empty. With this operator, there is no second value.
Invert condition: Inverts the result of the condition. For instance, is empty becomes is
not empty.
Condition Step Properties
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Rule Tree
The Rule tree subsection displays the full combination rules (defined below under Condition)
as a tree, which gives an overview of how the conditions work together as well as the result for
each of these conditions for the current record or iteration.
Page 186
Condition
First, the Condition List displays the conditions in list form, instead of the tree form above.
Three buttons are available next to the list:
l
Add condition: Click to create a new condition in the list. This will always branch the
current condition as an "AND" operator.
l
Delete condition: Delete the currently selected condition.
l
To rename a Condition, double click on its name from the Rule tree subsection .
Conditions are made by comparison of two operands using a specific Operator.
Technical
Both the Left and Right operands have the same properties.
l
Based On:
l
Position: The data in the specified position for the comparison.
l
Left (Txt and PDF only): The start position for the data selection. Note that
conditions are done on the current line, either the current cursor position, or
the current line in a Repeat step.
l
Right (Txt and PDF only): The end position for the data selection.
l
Height (Txt and PDF only): The height of the selection box.
l
l
l
l
l
Column (CSV and Database only): Drop-down listing all fields in the Data
Sample, of which the value will be used.
XPath (XML only): The path to the XML field that is extracted.
Top offset: The vertical offset from the current pointer location in the Data
Sample (Viewer).
Use Selection: Click to use the value of the current data selection for the
extraction.
Trim: Select to trim empty characters at the beginning or the end of the field.
Page 187
l
Value: A specified static text value.
l
l
l
l
l
l
l
l
Expression: The JavaScript line that is evaluated. Note that the last value
attribution to a variable is the one used as a result of the expression.
Use JavaScript Editor: Click to display the Edit Script dialog.
Use selected text: Inserts the text in the current data selection in the
JavaScript Expression. If multiple lines or elements are selected, only the first
one is used.
Data Property: The value of a data-level property set in the Preprocessor Step.
Record Property: One of the local variables that you can create and that are reset
for each document as opposed to data variables that are global because they are
initialized only once at the beginning of each job.
Automation Property: The current value of a Document-level property set in the
Preprocessor Step.
Extractor Property: The value of an internal extractor variable:
l
l
l
Field: The Extracted Record field to use in the comparison.
JavaScript : The result of a JavaScript Expression.
l
l
Use selected text: Uses the text in the current data selection as the Value. If
multiple lines or elements are selected, only the first one is used.
Field: The contents of a specific field in the Extracted Record.
l
l
Value: The text value to use in the comparison.
Counter: The value of the current counter iteration in a Repeat step.
Vertical Position: The current vertical position on the page, either in Measure
(PDF) or Line (Text and CSV).
Operators:
l
l
l
l
is equal to: The two specified value are identical for the condition to be True.
contains: The first specified value contains the second one for the condition to be
True.
is less than: The first specified value is smaller, numerically, than the second value
for the condition to be True.
is greater than: The first specified value is larger, numerically, than the second
value for the condition to be True.
Page 188
l
l
is empty: The first specified value is empty. With this operator, there is no second
value.
Invert condition: Inverts the result of the condition. For instance, is empty becomes
is not empty.
Goto Step Properties
The Goto step moves the pointer within the data sample to a specific position or one that is
relative to the current position.
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Goto Definition
Text File
l
Target Type: Defines the type of jump .
l
Line: Jumps a certain number of lines or to a specific line.
l
l
l
From: Defines where the jump begins:
l
Current Position: The Goto begins at the current cursor position.
l
Top of record: The Gotobegins at line 1 of the source record.
Move by: Enter the number of lines or pages to jump.
Page: Jumps between pages or to a specific page.
l
From: Defines where the jump begins:
l
Current Position: The Gotobegins at the current cursor position.
l
Top of record: The Gotobegins at line 1 of the source record.
Page 189
l
l
Move by: Enter the number of lines or pages to jump.
Next line with content: Jumps to the next line that has contents, either anywhere
on the line or in specific columns.
l
Inspect entire page width: When checked, the Next line with content and
Next occurrence of options will look anywhere on the line. If unchecked,
options appear below to specify in which area of each line the Gotostep
checks in:
l
Left: The starting column, inclusively.
l
Right: The end column, inclusively.
l
l
Use selection: Click while a selection is made in the Data Viewer to
automatically set the left and right values to the left and right edges of the
selection.
Next occurrence of: Jumps to the next occurrence of specific text or a text pattern,
either anywhere on the line or in specific columns.
l
Inspect entire page width: When checked, the Next line with content and
Next occurrence of options will look anywhere on the line. If unchecked,
options appear below to specify in which area of each line the Gotostep
checks in:
l
Left: The starting column, inclusively.
l
Right: The end column, inclusively.
l
l
l
l
Use selection: Click while a selection is made in the Data Viewer to
automatically set the left and right values to the left and right edges of the
selection.
Expression: Enter the text or Regex expression to look for on the page.
Use selection: Click while a selection is made in the Data Viewer to copy the
contents of the first line of the selection into the Expression box.
Use regular expression: Check so that the Expression box is treated as a
regular expression instead of static text. For more information on using
Regular Expressions (regex), see the Regular-Expressions.info Tutorial.
PDF File
l
Target Type: Defines the type of jump .
Page 190
l
Physical distance:
l
l
l
l
Current Position: The Goto begins at the current cursor position.
l
Top of record: The Gotobegins at line 1 of the source record.
Move by: Enter distance to jump.
Page: Jumps between pages or to a specific page.
l
l
l
From: Defines where the jump begins:
From: Defines where the jump begins:
l
Current Position: The Gotobegins at the current cursor position.
l
Top of record: The Gotobegins at line 1 of the source record.
Move by: Enter the number pages to jump.
Next line with content: Jumps to the next line that has contents, either anywhere
on the line or in specific columns.
l
Inspect entire page width: When checked, the Next line with content and
Next occurrence of options will look anywhere on the line. If unchecked,
options appear below to specify in which area of each line the Gotostep
checks in:
l
Left: The starting column, inclusively.
l
Right: The end column, inclusively.
l
l
Use selection: Click while a selection is made in the Data Viewer to
automatically set the left and right values to the left and right edges of the
selection.
Next occurrence of: Jumps to the next occurrence of specific text or a text pattern,
either anywhere on the line or in specific columns.
l
Inspect entire page width: When checked, the Next line with content and
Next occurrence of options will look anywhere on the line. If unchecked,
options appear below to specify in which area of each line the Gotostep
checks in:
l
Left: The starting column, inclusively.
l
Right: The end column, inclusively.
Page 191
l
l
l
l
Use selection: Click while a selection is made in the Data Viewer to
automatically set the left and right values to the left and right edges of the
selection.
Expression: Enter the text or Regex expression to look for on the page.
Use selection: Click while a selection is made in the Data Viewer to copy the
contents of the first line of the selection into the Expression box.
Use regular expression: Check so that the Expression box is treated as a
regular expression instead of static text. For more information on using
Regular Expressions (regex), see the Regular-Expressions.info Tutorial.
CSV File
l
From (CSV files): Defines where the jump begins:
l
Current Position: The Goto begins at the current cursor position.
l
l
Move by: Enter the number of lines or pages to jump.
Top of record: The Gotobegins at line 1 of the source record.
l
Move to: Enter the number of lines or pages to jump.
XML File
l
Destination (XML files): Defines what type of jump to make:
l
l
l
l
l
Sibling element: Jumps the number of siblings (nodes at the same level) defined in
the Move byoption.
Sibling element with same name: Jumps the number of same name siblings
(nodes at the same level of which the node is the same name) defined in the Move
byoption.
Element, from top of record: Jumps to the specified node. The XPATH in the
Absolute XPATHoption starts from the root node defined by /.
Element from current position: Jumps to a position relative to the current position
of the cursor. The XPATH in the Relative XPATHoption defines where to go,../goes
up a level,./refers to the current level.
Level Up/Down: Jumps up or down one node level (up to the parent, down to a
child). The number of levels to change is defined in the Move byoption.
Page 192
Postprocessor Properties
The Postprocessor step does not run for every Source Record in the Data Sample. It runs once,
at the end of the Steps, after all records have been processed.
Postprocessor
The Postprocessor subsection defines what postprocessors run on the Data Sample at the end
of the data mapping workflow. Each Postprocessor runs in turn, using the result of the previous
one as an input.
l
Name: The name to identify the Postprocessor.
l
Type: The type of Postprocessor. Currently there is a single type available.
l
JavaScript : Runs a JavaScript Expression to modify the Data Sample. See
DataMapper API.
l
l
Use JavaScript Editor: Click to display the Edit Script dialog.
Add Postprocessor: Click to add a new Postprocessor. Its settings can be modified
once it is added.
l
Remove Postprocessor: Click to remove the currently selected Postprocessor.
l
Move Up: Click to move the Postprocessor up one position.
l
Move Down: Click to move the Postprocessor down one position.
l
Export: Click to export the current Postprocessor configuration and content to a file.
l
Import: Click to import a Postprocessor configuration and content from an external file.
Postprocessor definition
JavaScript
l
l
l
Expression: The JavaScript expression that will run on the Data Sample. See
DataMapper API.
Use JavaScript Editor: Click to display the Script Editor dialog.
Use selected text: Uses the text in the current data selection as the Value. If multiple
lines or elements are selected, only the first one is used.
Page 193
Description
This subsection is collapsed by default in the interface, to allow more screen space be given to
other important parts.
Name: The name of the step. This name will be displayed on top of the step's icon in the Steps
pane.
Comments: The text entered here gives more details on the step and will be displayed in the
tooltip appearing when hovering over the step in the Steps pane.
Data Types
Looking at the Data Model pane, you will see that the fields are either string or HTML string,
depending on how they were extracted. Basically, it is all just text. But inside the DataMapper
module, which is very useful when we’re actually working with the data in a template, you can
change the actual type of data that is being extracted so that it can be evaluated differently.
How can it be changed? Simply by clicking on any field where you want to modify the data
type. You then go to the bottom of the Step Properties pane and click the Type drop-down.
Changing the type does not only determine the data type inside your record. It also sets the way
it will be read into the Data Source. In the following example, if you select a date type, it actually
causes an error because the format inside the Source Record is not recognized. The format is
"year year year year month month day day" but the default format, in this case, adds the time. If
you remove that, it will actually apply the change. So, visually speaking, only two things have
been changed in the record: a little calendar icon now appears, indicating that it is a date type,
and you can see that a time stamp was added..
Page 194
When you select a specific data type, it converts it into a native type. If the date inside the Data
Source was in a different format (Canadian format, Japanese format, etc.), the source shows
that different format. But inside the Data Model, it will always be shown as "year month day"
and the time.
Here are the data types available in all modules of PlanetPress Connect.
l
Boolean
l
String
l
HTMLString
l
Integer
l
Float
l
Currency
l
Date
l
Object
Page 195
Note
The Object data type is only available in the DataMapper module. It is created in the Properties
subsection in the Preprocessor step, and can be used throughout the data mapping configuration.
Boolean Data Type
Booleans are a simple True/False data type often used in conditions and comparisons.
Defining Boolean Values
l
l
l
Pre-Processor: Specify the "Type" as "Boolean" and set a default value of either true; or
false;
Extraction: Specify the "Type" as "Boolean". The field value must betrueorfalse.
JavaScript Expression: Set the desired value to either true; or false;
Example: record.fields["isCanadian"] = true;
Note
The value must be true , all in lowercase. Any variation in case (True, TRUE) will not work.
Boolean Expressions
Boolean values can also be set using an expression of which the result is true or false. This is
done using operators and comparisons.
Example: record.fields["isCanadian"] = (extract("Country") == "CA");
For more information on JavaScript comparison and logical operators, please see
w3schools.com or developer.mozilla.org.
Page 196
String Data Type
Strings contain textual data. Strings do not have any specific meaning, which is to say that their
contents are never interpreted in any way.
Defining String Values
l
l
l
Pre-Processor: Specify the "Type" as "String" and set a default value as any text
between quotes, such as "This is my text";
Extraction: Specify the "Type" as "String". The field value will be extracted and treated
as a string.
JavaScript Expression: Set the desired value to any string between quotes.
Example: record.fields["countryOfOrigin"] = "Canada";
Building String Values
Strings values can be made up of more than just a series of characters between quotes. Here
are a few tips and tricks to build strings:
l
l
l
Both single and double quotes can be used to surround strings and they will act in
precisely the same manner. So, "this is a string" and 'this is a string' mean the same
thing. However, it's useful to have both in order to remove the need for escaping
characters. For instance, "I'm fine!" works, but 'I'm fine!' does not since only 'I' is
properly interpreted. 'I\'m fine!' works (escaping the ' with a \).
It is possible to put more than one string, as well as variables containing strings, by
concatenating them with the +operator. For example,"Hello " +
sourceRecord.property.FirstName + ", nice to meet you!".
Adding more data to an existing string variable or field is possible using a combination of
concatenation and assignment. For example, if var myVar = "Is this the real life";,
andmyVar += " or is this just fantasy?";, the value ofmyVarwill be, obviously,"Is this
the real life or is this just fantasy?".
For more information on string variables, see quicksmode.org.
Page 197
HTML String Data Type
HTML Strings contain textual data that includes HTML Markup. They are essentially the same
as String values except in cases where HTML can be treated differently. For instance, when
using a script to place an HTML String field into a template, the contents will be HTML instead
of plain text.
Example: Assuming a value of "He said WOW!"; , if the data type is String and placed
on the page, it will display exactly as "He said WOW!" (without the quotes). If the data
type is HTMLString, it will display as "He said WOW!" (again, without the quotes).
Considering this is the only difference, for more information on how to create and use HTML
String values, see String values.
Integer Data Type
Integers are signed, numeric, whole 64bit numbers whose value ranges from -(2^63) to
(2^63). Integers are the numerals with the highest precision (and the fastest processing speed)
of all since they are never rounded.
Defining Integer Values
l
l
l
Pre-Processor: Specify the "Type" as "Integer" and set a default value as a number,
such as 42;
Extraction: Specify the "Type" as "Integer". The field value will be extracted and treated
as an integer.
JavaScript Expression: Set the desired value to any integer value.
Example: record.fields["AnswerToEverything"] = 42;
Building Integer Values
Integers can be set through a few methods, all of which result into an actual integer result.
l
Direct attribution: Assign an integer value directly, such as
42,99593463712ordata.extract("TotalOrdered").
Page 198
l
Mathematical operations: Assign the result of any mathematical operation. For
example:22 + 51,3*6,10/5orsourceRecord.property.SubTotal. For more information on
mathematics in JavaScript , see w3Schools - Mathematical Operators. For more
advanced mathematical functions, see w3schools - Math Object.
Note
When adding numbers that are not integers, for instance 4.5 + 1.2 , a round towards zero
rounding is applied after the operation was made. In the previous example, the result, 5.7, is
rounded to 5. In another example, -1.5 - 1 results in -2
Float Data Type
Floats are signed, numeric, floating-point numbers whose value has 15-16 significant digits.
Routinely used for calculations. Note that floats are inherently imprecise: their accuracy varies
according to the number of significant digits being requested.
Defining Float Values
l
l
l
Pre-Processor: Specify the "Type" as "Float" and set a default value as a number with
decimal points, such as 546513.8798463;
Extraction: Specify the "Type" as "Float". The field value will be extracted and treated as
a float.
JavaScript Expression: Set the desired value to any float value.
Example: record.fields["PreciseTaxSubtotal"] = 27.13465;
Building Float Values
Float values can be the result of direct attribution or mathematical operations just like Integer
values.
Currency Data Types
A signed, numeric, fixed-point 64-bit number with 4 decimals. Values range from -922 337 203
685 477.5808 to 922 337 203 685 477.5808. This data type is routinely used for financial
Page 199
calculations: it is as precise as integers.
Defining Currency Values
l
l
l
Pre-Processor: In the step properties selection under Properties specify the "Type" as
"Currency" and set a default value as a number with up to 4 decimal points, such as
546513.8798
Extraction: In the step properties under Field Definition specify "Type" as "Currency"
and configure how the value will be read from the Source Record (see Extract Step). The
field value will be extracted and treated as a float.
JavaScript Expression: Set the desired value to any float value.
Example: record.fields["PreciseTaxSubtotal"] = 27.13465;
While currency values can be set to up to 4 significant digits, only 2 are displayed on screen.
Building Currency Values
Currency values can be the result of direct attribution or mathematical operations just like
Integer and Float values.
Date Data Type
Dates are values that represent a specific point in time, precise up to the second. They can also
be referred to as datetime values. While dates are shown visually under the system's regional
settings, in reality they are stored unformatted.
Note
The Date property is stored in Connect database with zero time zone offset, which makes it
possible to convert the time correctly in any location. PlanetPress Workflow, however, shows the
date/time as it is stored database (with 0 time zone offset). This is expected behavior for the moment
and the zone offset must be calculated manually in PlanetPress Workflow.
Page 200
Extracting dates
To extract data and have that data interpreted as a Date, set the type of the respective field to
Date:
1. Select the field in the data model.
2. On the Step properties pane, under Field Definition, specify the Type as Date.
3. Next, under Data Format, specify the Date/Time Format. This format must match the way
the date is formatted in the source data; otherwise the data cannot be interpreted as a
Date.
Defining a date/time format
A date format is a mask representing the order and meaning of each digit in the raw data, as
well as the date/time separators. The mask uses several predefined markers to parse the
contents of the raw data. Here is a list of markers that are available in the DataMapper:
l
yy: Numeric representation of the Year when it is written out with only 2 digits (i.e. 13)
l
yyyy: Numeric representation of the Year when it is written out with 4 digits (i.e. 2013)
l
l
l
l
l
M: Short version of the month name ( i.e. Jan, Aug). These values are based on the
current regional settings.
MM: Long version of the month name (i.e. January, August). These values are based on
the current regional settings.
mm: Numeric representation of the month (i.e. 1, 09, 12)
D: Short version of the weekday name ( i.e. Mon, Wed). These values are based on the
current regional settings.
DD: Long version of the weekday name (i.e. Monday, Wednesday). These values are
based on the current regional settings.
l
dd: Numeric representation of the day of the month (i.e. 1, 09, 22)
l
hh: Numeric representation of the hours
l
nn: Numeric representation of the minutes
l
ss: Numeric representation of the seconds
l
ms: Numeric representation of the milliseconds.
Page 201
l
l
ap: AM/PM string.
In addition, any constant character can be included in the mask, usually to indicate
date/time separators (i.e. / - :) . If one of those characters happens to be one of the
reserved characters listed above, it must be escaped using the \ symbol.
Note
The markers that can be used when extracting dates are different from those that are used to
display dates in a template (see "Date and time patterns" on page 751).
Examples of masks
Value in raw data
Mask to use
June 25, 2013
MM dd, YYYY
06/25/13
mm/dd/yy
2013.06.25
yyyy.mm.dd
2013-06-25 07:31 PM
yyyy-mm-dd hh:nn ap
2013-06-25 19:31:14.1206
yyyy-mm-dd hh:nn:ss.ms
Tuesday, June 25, 2013 @ 7h31PM
DD, MM dd, yyyy @ hh\hnnap
Entering a date using JavaScript
In several places in the DataMapper, Date values can be set through a JavaScript. For
example:
l
In a field in the Data Model. To do this, go to the Steps pane and select an Extract step.
Then, on the Step properties pane, under Field Definition click the Add JavaScript Field
button (next to the Field List drop-down). Type the JavaScript in the Expression field. (To
rename the field, click the Order and rename fields button.)
Page 202
l
In a Preprocessor property. To do this, go to the Steps pane and select the
Preprocessor step. Then, on the Step properties pane, under Properties add a property,
specify its Type as Date and put the JavaScript in the Default Value field.
The use of the JavaScript Date() object is necessary when creating dates through a JavaScript
expression. For more information, see w3schools - JavaScript Dates and w3schools - Date
Object.
Example
The following script creates a date that is the current date + 30 days:
function addDays(date, days) {
var result = new Date(date);
result.setDate(result.getDate() + days);
return result;
}
addDays(new Date(), 30);
Object Data Type
Objects holds addresses that refer to objects. You can assign any reference type (string, array,
class, or interface) to an Object variable. An Object variable can also refer to data of any value
type (numeric, Boolean, Char, Date, structure, or enumeration).
Defining Object Values
l
Pre-Processor: Specify the "Type" as "Object" and set a default value as a semi-colon.
Toolbar
In the DataMapper module, the following buttons are available in the top toolbar:
File Manipulation Buttons
l
l
New : Displays the New wizard where a new data mapping configuration or a new
template can be created.
Open
: Displays the Open dialog to open an existing data mapping configuration.
Page 203
l
Save : Saves the current data mapping configuration. If the configuration has never
been saved, the Save As... dialog is displayed.
Step Manipulation
Note
All steps except JavaScript require an active data selection in the Data Viewer.
l
l
l
l
l
l
l
l
l
Add Extract Step : Adds an Extract Step with one or more extract fields. If more than
one line or field is selected in the Data Viewer, each line or field will have an extract field.
Add Goto Step
: Adds a Goto step that moves the selection pointer to the beginning of
the data selection. For instance if an XML node is selected, the pointer moves to where
that node is located.
Add Condition Step
: Adds a condition based on the current data selection. The
"True" branch gets run when the text is found on the page. Other conditions are available
in the step properties once it has been added.
Add Repeat Step : Adds a loop that is based on the current data selection, and
depending on the type of data. XML data will loop on the currently selected node, CSV
loops for all rows in the record. In Text and PDF data, if the data selection is on the same
line as the cursor position, the loop will be for each line until the end of the record. If the
data selection is on a lower line, the loop will be for each line until the text in the data
selection is found at the specified position on the line (e.g. until "TOTAL" is found).
Add Extract Field : Adds the data selection to the selected Extract step, if an extract
step is currently selected. If multiple lines, nodes or fields are selected, multiple extract
fields are added simultaneously.
Add Multiple Conditions
: Adds a condition that splits into multiple case conditions.
Add Action Step : Adds a step to create a custom JavaScript snippet. See the
DataMapper API for more details.
Cut Step : Removes the currently selected step and places it in the clipboard. If the
step is a Repeat or a Condition, all steps under it are also placed in the clipboard. If there
is already a step in the clipboard, it will be overwritten.
Copy Step : Places a copy of the currently selected step in the clipboard. The same
details as the Cut step applies.
Page 204
l
l
l
l
l
Paste Step : Takes the step or steps in the clipboard and places them after the
currently selected step.
Delete Step : Deletes the currently selected step. If the step is a Repeat or Condition,
all steps under it are also deleted.
Ignore Step : Click to set the step to be ignored (aka disabled). Disabled steps do not
run when in DataMapper and do not execute when the data mapping configuration is
executed in Workflow. However, they can still be modified normally.
Validate All Records : Runs the process on all records and verifies that no errors are
present in any of the records. Errors are displayed in the Messages Pane.
Add Data Sample : Displays a dialog to open a new Data Source to add it as a Data
Sample in the data mapping configuration. Data Samples are visible in the Settings Pane.
Shortcut Keys
You can add a step by pressing a specific key on the keyboard:
Extract: F6
Goto: F7
Conditional: F8
Repeat: F9
Action: F11
test
Welcome Screen
The Welcome Screen appears when first starting up PlanetPress Connect. It offers some
useful shortcuts to resources and to recent documents and data mapping configurations.
The Welcome Screen can be brought back in two ways:
Page 205
l
The Welcome Screen button in the Toolbars.
l
From the Menus in Help, Welcome Screen.
Contents
l
Activation: Click to open the Objectif Lune Web Activation Manager.
l
Release Notes: Opens the current Release Notes for PlanetPress Connect.
l
Website: Opens the PlanetPress Connect website.
l
Take A Tour: Click to open the YouTube Playlist giving you a tour of the software.
l
Use the DataMapper to...:
l
l
l
l
Open an Existing Configuration: Click to open the standard Browse dialog to
open an existing data mapping configuration.
Recent Configurations: Lists recently used configurations. Click any configuration
to open it in the DataMapper module.
Use the Designer to...:
l
l
l
l
l
Create a New Configuration: Opens the Creating a New Configuration screen.
Create a New Template: Opens the Creating a new Template wizard.
Browse Template Wizards: Displays a list of available template wizards,
producing pre-made templates with existing demo content. These are the same that
are found at the bottom of the Creating a new Template wizard.
Open an Existing Template: Click to open the standard Browse dialog to open an
existing template.
Recent Templates: Lists recently used templates. Click any template to open it in
the Designer module.
Other Resources:
l
Documentation: Opens this documentation.
l
Courses (OL Learn): Opens the Objectif Lune e-Learning Center.
l
User Forums: Opens the Questions & Answer forums.
Page 206
DataMapper Scripts API
This page describes the different features available in scripts created inside DataMapper. See
"Write Your Own Scripts" on page 214.
Objects
Name
Description
Available In
automation
Returns a ScriptableAutomation
object encapsulating the properties of
the PlanetPress Workflow process that
triggered the current operation.
Boundaries, all Steps except
Goto
boundaries
Returns a boundaries object
encapsulating properties and methods
allowing to define the boundaries of
each document in the job.
Boundaries
data
Returns a data object encapsulating
properties and methods pertaining to
the original data stream.
Boundaries, all Steps except
Goto
db
Returns a db object allowing you to
connect to a database.
Boundaries, all Steps except
Goto
logger
Allows to log messages as error,
warning or informational message.
Boundaries, all Steps except
Goto
record
The current record in the main data set.
Extract, Condition, Repeat
and Multiple Conditions
Steps
region
The region object defines a subsection
of the input data.
Boundaries
Page 207
Name
Description
Available In
sourceRecord
Returns a source record object
containing properties specific to the
current source record being processed.
Boundaries, all Steps except
Goto and Postprocessor
steps
Returns a steps object encapsulating
properties and methods pertaining to
the current DataMapper process.
Extract, Condition, Repeat
and Multiple Conditions
Steps
Functions
Name
Description
Available In
copyFile()
Copies a file to the target file path,
replacing it if it already exists.
Boundaries, Steps
createTmpFile()
Creates a file with a unique name
in the temporary work folder and
returns a file object.
Boundaries, Steps
deleteFile()
Deletes a file.
Boundaries, Steps
execute()
Calls an external program and
wait for its end.
Boundaries, Steps
newByteArray()
Returns a new byte array.
Boundaries, Steps
newCharArray()
Returns a character array.
Boundaries, Steps
newDoubleArray()
Returns a double array.
Boundaries, Steps
newFloatArray()
Returns a float array.
Boundaries, Steps
newIntArray()
Returns an integer array.
Boundaries, Steps
Page 208
Name
Description
Available In
newLongArray()
Returns a long array.
Boundaries, Steps
newStringArray()
Returns a string array.
Boundaries, Steps
openBinaryReader
()
Opens a file as a binary file for
reading purposes.
Boundaries, Steps
openBinaryWriter()
Opens a file as a binary file for
writing purposes.
Boundaries, Steps
openTextReader()
Opens a file as a text file for
reading purposes.
Boundaries, Steps
openTextWriter()
Opens a file as a text file for
writing purposes.
Boundaries, Steps
Methods
Name
Description
Object
Related
connect()
Method that
returns a new
database
connection
object.
db
Read-only
object
containing the
physical
coordinates of
the region.
region
createRegion()
Available In
Boundaries settings
File Type
all
Proprocessor,
Extract, Condition,
Repeat, Action, and
Postprocessor
steps
Boundaries
all
Page 209
Name
Description
Object
Related
Available In
File Type
currentPosition()
Returns the
current position
of the pointer in
the data.
steps
Extract,
Condition,
Repeat, and
Action steps
all
currentLoopCounter
()
Returns an
integer value
representing
the current
iteration of the
containing loop.
steps
Extract,
Condition,
Repeat, and
Action steps
all
currentPage()
Returns an
integer value
representing
the current
page where the
current position
is located,
inside the
current record.
steps
Extract,
Condition,
Repeat, and
Action steps
Text and
PDF
currentPageHeight()
Returns the
height of the
current page in
millimeters.
steps
Extract,
Condition,
Repeat, and
Action steps
PDF
currentPageWidth()
Returns the
height of the
current page in
millimeters.
steps
Extract,
Condition,
Repeat, and
Action steps
PDF
extract()
Extracts the text
value from a
rectangular
region.
data
Extract,
Condition,
Repeat, and
Action steps
all
Page 210
Name
Description
Object
Related
Available In
File Type
extractMeta()
Method that
extracts the
value of a
metadata field.
data
Extract,
Condition,
Repeat, and
Action steps
all
fieldExists()
Method that
returns True if
metadata field
exists.
data
Finds the first
occurrence of a
string starting
from the current
position.
data and
boundaries
found()
Method that
returns a
Boolean value
indicating
whether the last
call to find()
was successful.
region
Boundaries
all
get()
Retrieves an
array of strings.
automation
and
boundaries
Boundaries
all
getVariable()
Method that
retrieves the
value currently
stored in a
variable.
automation
and
boundaries
Boundaries
all
find()
Boundaries
all
Preprocessor,
Extract, Condition,
Repeat, Action and
Postprocessor
steps
Boundaries
all
Extract, Condition,
Repeat, and Action
steps
Page 211
Name
Description
Object
Related
Available In
File Type
moveLines()
Scope constant
that can be
used as a
parameter to
moveTo() and
moveToNext()
methods.
steps
Extract,
Condition,
Repeat, and
Action steps
Text
moveDelimiters()
Scope constant
that can be
used as a
parameter to
moveTo() and
moveToNext()
methods.
steps
Extract,
Condition,
Repeat, and
Action steps
Text
moveMeasure()
Scope constant
that can be
used as a
parameter to
moveTo() and
moveToNext()
methods.
steps
Extract,
Condition,
Repeat, and
Action steps
PDF
moveNode()
Scope constant
that can be
used as a
parameter to
moveTo() and
moveToNext()
methods.
steps
Extract,
Condition,
Repeat, and
Action steps
XML
movePage()
Scope constant
that can be
used as a
parameter to
steps
Extract,
Condition,
Repeat, and
Action steps
PDF
Page 212
Name
Description
Object
Related
Available In
File Type
moveTo() and
moveToNext()
methods.
moveSibling()
Scope constant
that can be
used as a
parameter to
moveTo() and
moveToNext()
methods.
steps
Extract,
Condition,
Repeat and
Multiple
Conditions Steps
XML
moveTo()
Moves the
current position
to a number.
steps
Extract,
Condition,
Repeat and
Action steps
all
moveToNext()
Moves the
current position
to the next
instance of a
number.
steps
Extract,
Condition,
Repeat and
Action steps
all
range()
Read-only
object
containing the
physical
coordinates of
the region.
region
Boundaries
all
set()
Sets a new
DataMapper
record
boundary.
automation
and
boundaries
Boundaries
all
Page 213
Name
Description
Object
Related
Available In
File Type
setVariable()
Method that
sets a variable
to the specified
value,
automatically
creating the
variable if it
doesn't exist
yet.
automation
and
boundaries
Boundaries
all
totalPages()
Returns an
integer value
representing
the total
number of
pages inside
the current
record.
steps
Extract,
Condition,
Repeat, and
Action steps
Text and
PDF
Write Your Own Scripts
Data mapping can be taken a lot further than just performing basic extractions. Every part of
your extraction process can be customized using scripts. This topic explains how scripts work
and how you can create and write a script.
How Scripts Work
A script is a small set of instructions, written in JavaScript. When Connect generates the actual
extraction process, it takes each step, one by one, and runs all scripts for it.
Creating a New Script
In DataMapper, you can use scripts to set Boundaries (see Boundaries Using JavaScript) or in
the Step Properties for steps such as:
Page 214
l
l
l
Extraction step where the data selection is based on JavaScript or you can enter a post
function script.
Action step using the set properties based on JavaScript or you can use JavaScript run
script.
Condition step where the left and right operands are based on JavaScript.
See Step Properties for more information.
From the Settings or from the Step Properties pane, click the Use JavaScript Editor button.
The Edit script dialog appears:
Tip
In the Edit script dialog, press Ctrl-Space to bring up the list of available JavaScript objects and
functions (see Datamapper API). Use the arrow keys to select a function or object and press enter
to insert it. Type a dot after the name of the function or object to see which features are
subsequently available.
Page 215
Syntax Rules
Every script in the DataMapper must follow JavaScript syntax rules. For example, each
statement should end with ; and the keywords that can be used, such as var to declare a
variable, are JavaScript keywords. There are countless tutorials available on the Internet to
familiarize yourself with the JavaScript syntax. For a simple script all that you need to know can
be found on the following web pages: https://developer.mozilla.org/enUS/docs/Web/JavaScript.
Tip
For more examples of using conditions, see this how-to: Combining record-based conditions.
DataMapper API
Certain features do not exist in the native JavaScript library. These are additional JavaScript
features, designed for use in Connect only. All features designed for use in the DataMapper are
listed in the DataMapper's API (see DataMapper API).
Boundaries Using JavaScript
As soon as you select the On Script option as the trigger for establishing record boundaries,
you are instructing the DataMapper to read the file sequentially and to trigger an event each
and every time it hits a delimiter. In other words, the script that you'll be writing will be executed
- by default - as many times as there are delimiters in your input data.
If you know, for instance, that your PDF file only contains documents that are 3-pages, your
script could keep count of the number of times it's been called since the last boundary was set
(i.e. the count of delimiters it encountered) and each time the count is a multiple of 3, it could set
a new record boundary. You would basically have recreated the same functionality that is
already available through the GUI when setting the trigger to On Page and specifying 3 as the
Number of Pages.
Note
Remember that your script is being called on each new delimiter encountered by the DataMapper
parsing algorithm. If you are dealing with a DB Query that returns a million record, the script will
Page 216
be executed a million times! So you have to craft your script in such a way that it doesn't waste too
much time examining all possible conditions. Instead, it should terminate as soon as any condition
it's evaluating is false.
Data available inside each event
Every time the event is triggered, it has access to the entire data between the current location
and the next delimiter. So if you are just beginning the process for a PDF or text file, you have
access to the first page only. For CSV/DB, it means you have access to the one record line at
the current location.
What this means?
You can:
l
Examine the data found in between delimiters for specific conditions.
l
Examine specific regions of that data, or the available data as a whole.
l
Compare the contents of one region with another.
In fact, make all the comparisons you want as long as it's all located in the data between the
current location and the next delimiter.
What happens when the record boundaries depend on data found on different pages,
within the same record?
The API allows your script to "remember", across delimiters, the values that were evaluated in
previous pages so you can easily set record boundaries that span over hundreds of delimiters
(or more).
Examples
Basic example using a CSV file
Note
In this first example, don't focus on the actual syntax being used. You can take a look at the API
Page 217
reference later on for more information.
Imagine you are a classic rock fan and you want to extract the data from a CSV listing of all the
albums in your collection. Your goal is to extract records that change whenever the artist OR
the release year changes.
Here's what the CSV looks like:
"Artist","Album","Released"
"Beatles","Abbey Road",1969
"Beatles","Yellow Submarine",1969
"Led Zeppelin","Led Zeppelin 1",1969
"Led Zeppelin","Led Zeppelin 2",1969
"Beatles","Let it be",1969
"Rolling Stones","Let it bleed",1969
"Led Zeppelin","Led Zeppelin 3",1970
"Led Zeppelin","Led Zeppelin 4",1971
"Rolling Stones","Sticky Fingers",1971
Note
The first line is just the header with the names of the CSV columns. Obviously, the data is already
sorted per year, per artist, and per album.
Your goal is to examine two values in each CSV record and to act when either changes. The
DataMapper GUI allows you to specify a On Change trigger, but you can only specify a single
field. So for instance, if you were to set the record boundary when the "Released" field
Page 218
changes, then you'd get the first four lines together inside a single record, but that's not what
you want since that would include albums from several different artists. And if you were to set it
when the "Artist" field changes, then the first few records would be OK but near the end, you'd
get both the Led Zeppelin 3 and led Zeppelin 4 albums inside the same record, even though
they were released on different years. So that's no good either.
Essentially, we need to combine both these conditions and set the record boundary when
EITHER the year OR the artist changes.
Here's what the script would look like:
// Read the values of both columns we want to check
var zeBand = boundaries.get(region.createRegion("Artist"));
var zeYear = boundaries.get(region.createRegion("Released"));
// Check that at least one of our variables holding previous values
have been initialized already, before attempting to compare the
values
if (boundaries.getVariable("lastBand")!=null) {
if ( zeBand[0]!=boundaries.getVariable("lastBand")
|| zeYear[0]!=boundaries.getVariable("lastYear") )
{
boundaries.set();
}
}
boundaries.setVariable("lastBand",zeBand[0]);
boundaries.setVariable("lastYear",zeYear[0]);
l
l
l
The script first reads the two values from the input data, using the createRegion() API
method. For a CSV/DB data type, the parameter it expects is simply the column name.
The region is then passed as a parameter to the get() method, which reads its contents
and converts it into an array of strings (because any region, even a CSV field, may
contain several lines).
To "remember" the values that were processed the last time the event was triggered, we
use variables that remain available in between events. Note that these variables are
specific to the Boundary context and not available in any other scripting context in the
DataMapper.
The script first checks if those values were initialized. If they weren't, it means this is the
first iteration so there's no need to compare the current values with previous values since
Page 219
there have been none yet. But if they have already been initialized, then a condition
checks if either field has changed since last time. If that's the case, then a boundary is
created through the set() method.
l
Finally, the script stores the values it just read in the variables using the setVariables()
method. They will therefore become the "last values encountered" until the next event
gets fired. When called, setVariables() creates the specified variable if it doesn't already
exist and then sets the value to the second parameter passed to the function.
You can try it yourself. Paste the data into the text editor of your choice and save the file to
Albums.csv. Then create a new DataMapper configuration and load this CSV as your data file.
In the Data Input Settings, make sure you specify the first row contains field names and set the
Trigger to On script. Then paste the above JavaScript code in the Expression field and click
the Apply button to see the result.
Same basic example using a text file
So let's say we want to do the exact same thing, but this time around the Data Source is a plain
text file that looks like this:
Beatles
Abbey Road
1969
Beatles
Yellow Submarine
1968
Led Zeppelin
Led Zeppelin 1
1969
Led Zeppelin
Led Zeppelin 2
1969
Beatles
Let it be
1970
Rolling Stones
Let it bleed
1969
Led Zeppelin
Led Zeppelin 3
1970
Led Zeppelin
Led Zeppelin 4
1971
Rolling Stones
Sticky Fingers
1971
Then our script would look like this:
// Read the values of both columns we want to check
var zeBand = boundaries.get(region.createRegion(1,1,30,1));
var zeYear = boundaries.get(region.createRegion(61,1,65,1));
// Check that at least one of our variables holding previous values
have been initialized already, before attempting to compare the
Page 220
values
if (boundaries.getVariable("lastBand")!=null) {
if (
zeBand[0]!=boundaries.getVariable("lastBand")
|| zeYear[0]!=boundaries.getVariable("lastYear") )
{
boundaries.set();
}
}
boundaries.setVariable("lastBand",zeBand[0]);
boundaries.setVariable("lastYear",zeYear[0]);
Note
We're using the exact same code we as used for CSV files, with the exception of parameters
expected by the createRegion() method. The API methods adapts to their context and therefore
expect different parameters to be passed in order to achieve the same thing. Since a text file does not
contain column names as a CSV does, the API expects the text regions to be defined using physical
coordinates. In this instance: (Left, Top, Right, Bottom).
You can try this code as well. Paste the data into the text editor of your choice and save the file
to Albums.txt. Then create a new DataMapper configuration and load this TXT as your data file.
In the Data Input Settings, specify On lines as the Page delimiter type with the number of lines
set to 1 so you can process the file line per line (i.e. triggering the event on each line). Then, set
the boundary Trigger to On script and paste the above code in the JavaScript expression and
click the Apply button to see the result.
Note
The PDF context also expects physical coordinates, just like the Text context does, but since PDF
pages do not have a grid concept of lines and columns, the above parameters would instead be
specified in millimeters relative to the upper left corner of each page. So for instance, to create a
region for the Year, the code might look like this:
region.createRegion(190,20,210,25)
which would create a region located near the upper right corner of the page.
That's the only similarity, though, since the script for a PDF would have to look through the entire
Page 221
page and probably make multiple extractions on each one since it isn't dealing with single lines like
the TXT example given here.
For more information on the API syntax, please refer to DataMapper API.
Objects
Automation Object
Returns a ScriptableAutomation object encapsulating the properties of the PlanetPress
Workflow process that triggered the current operation.
Properties
The following table lists the properties of the Automation object.
Property
Type
Description
JobInfo
ScriptableAutomationProperty
Returns a ScriptableAutomation object
containing JobInfo 1 to 9 values from
PlanetPress Workflow
Properties
ScriptableAutomationProperty
Returns a ScriptableAutomation object
containing additional information (file
name, process name and task ID) from
PlanetPress Workflow
Variables
ScriptableAutomationProperty
Returns a ScriptableAutomation object
containing the list of local and global
variables defined by the user in
PlanetPress Workflow to the
DataMapper. Note that there is no way to
distinguish local variables from global
ones (local variables take precedence
over global variables). To be used in the
DataMapper, variables must have
Page 222
Property
Type
Description
already been defined in the
Preprocessor step as Automation
variables. The Preprocessor step
attempts to match variable names
passed by the Workflow process to
those defined inside the step.
Example
The variable used from Workflow must first be declared in the Preprocessor step:
See The Preprocessor Step Properties for more information.
Note
The Type of the variable must be the same as the variable from Workflow.
Accessing Automation Properties
To access JobInfo 1 to 9 from Workflow:
automation.jobInfo.JobInfo1;
To access ProcessName, OriginalFilename or TaskIndex from Workflow:
Page 223
automation.properties.OriginalFilename;
To access variables declared in the Preprocessor properties (see picture above):
automation.variables.Same_as_workflow;
Boundaries Object
Returns a boundaries object encapsulating properties and methods allowing to define the
boundaries of each document in the job.
Properties
The following table lists the properties of the Boundaries object.
Property
Return Type
CurrentDelim
A read-only 1-based index (number) of the current delimiter in the file. In
other words, the Beginning Of File (BOF) delimiter equals 1. It indicates the
position of the current delimiter relative to the last document boundary
Methods
The following table describes the functions of the Boundaries object.
Method
find()
get()
getVariable()
set()
setVariable()
Page 224
Data Object
Returns a data object encapsulating properties and methods pertaining to the original data
stream.
Properties
The following table lists the properties of the data object.
Property
Description
Return Type
filename
The path of the input file.
Returns the fully qualified
file name of the temporary
work file being processed.
properties
Contains properties declared in the
preprocessor step (see Preprocessor Step
Properties for details).
Returns an array of
properties defined in the
Preprocessor step with
the data scope (i.e.
statically set at the start of
the job).
Methods
The following table describes the methods of the data object.
Method
extract()
extractMeta ()
fieldExists ()
find()
Db Object
Returns a db object allowing you to connect to a database.
Page 225
Method
The following table describes the methods of the db object.
Method
connect()
Logger Object
Global object that allows logging messages such as error, warning or informational messages.
Methods
The following table describes the methods of the logger object.
Method
Parameters
Description
error()
message: string
Logs an error message
info()
message: string
Logs an informational message
warn()
message: string
Logs a warning message
Record Object
The current record in the main data set.
Properties
Property
Return Type
fields
The field values that belong to this record. You can access a specific
field value using either a numeric index or the field name,
index
The one-based index of this record, or zero if no data is available.
tables
The details table that belong to this record. You can access a
specific table using a numeric index or the table name.
Page 226
Example
Region Object
The region object defines a sub-section of the input data. Its properties vary according to the
type of data.
Methods
The following table describes the methods of the region object.
Method
Description
Return Type
found()
Contains a Boolean value indicating if
the last call to find() was successful.
Returns a region.
range()
Read-only object containing the
physical coordinates of the region.
Physical location of the
region.
createRegion()
Creates a region.
The region object returns
an array of all strings
found in the region
SourceRecord Object
Returns a SourceRecord object containing properties specific to the current source record
being processed.
Properties
sourceRecord.properties.property;
Property
Return Type
properties
Returns an array of properties defined in the Preprocessor step with
the Record Scope (i.e. dynamically reset with each new record).
Page 227
Example
The property, used by the object Source Record, must first be declared in a Preprocessor
step:
1. Enter the property Name.
2. Select Each record from the Scope drop-down list.
3. Select a Type for the Property.
Steps Object
Returns a steps object encapsulating properties and methods pertaining to the current
DataMapper process.
Methods
The following table lists the methods of the steps object.
Page 228
Method
currentPosition()
currentLoopCounter()
currentPage()
currentPageHeight()
currentPageWidth()
moveLines()
moveDelimiters()
moveMeasure()
moveNode()
movePage()
moveSibling()
moveTo()
moveToNext()
totalPages()
Functions
copyFile()
Function that copies a file to the target file path, replacing it if it already exists.
copyFile(source, target)
Copies a file to the target file path, replacing it if it already exists.
Page 229
source
String that specifies source file path and name.
target
String that specifies target file path and name.
target
String that specifies destination path and file name.
Example
In this script, the file test.txt included in c:\Content, will be copied into the c:\out folder.
copyFile("c:\Content\test.txt","c:\out\")
CreateTempFile()
Creates a file with a unique name in the temporary work folder and returns a file object. This file
stores data temporarily in memory or in a buffer. It is used to prevent multiple input/output
access to a physical file when writing. In the end, the contents is transferred into a physical file
for which only a single input/output access will occur.
Examples
In the following script, a file is read in a temporary file:
try{
// Create a temporary file
var tmpFile = createTmpFile();
// Open a writer on the temporary file
var writer = openTextWriter(tmpFile.getPath());
try{
var line = null; // Current line
// read line by line and readLine will return null at the
end of the file.
while( (line = reader.readLine()) != null ){
// Edit the line
line = line.toUpperCase();
// Write the result in the temporary file
writer.write(line);
// add a new line
writer.newLine();
}
Page 230
}
finally{
// Close the writer or the temporary file
writer.close();
}
}
finally{
// Close the reader
reader.close();
}
DeleteFile()
Function used to delete a file.
DeleteFile(filename)
Deletes a file.
filename
String that specifies the path and file name of the file to be deleted.
Examples
1. You can delete the data file used in the DataMapper:
DeleteFile(data.filename);
2. You can delete a file in a local folder
DeleteFile("c:\Content\test.txt");
execute()
Function that calls an external program and waits for it to end.
execute(command)
Calls an external program and waits for it to end.
command
String that specifies the path and file name of the program to execute.
Page 231
Examples
NewByteArray()
Function that returns a new byte array.
NewByteArray(size)
Returns a new byte array of size elements.
size
Integer that represents the number of elements in the new array.
Examples
NewCharArray()
Function that returns a new character array.
NewCharArray(size)
Returns a new character array of size elements.
size
Integer that represents the number of elements in the new array.
Examples
NewDoubleArray()
Function that returns a new double array.
NewDoubleArray(size)
Returns a new double array of size elements.
size
Integer that represents the number of elements in the new array.
Page 232
Examples
NewFloatArray()
Function that returns a new float array.
NewFloatArray(size)
Returns a new float array of size elements.
size
Integer that represents the number of elements in the new array.
Examples
NewIntArray()
Function that returns a new integer array of size elements.
NewIntArray(size)
Returns a new integer array of size elements.
size
Integer that represents the number of elements in the new array.
Examples
NewLongArray()
Function that returns a new long array.
NewLongArray(size)
Returns a new long array of size elements.
size
Integer that represents the number of elements in the new array.
Page 233
Examples
NewStringArray()
Function that returns a new string array.
NewStringArray(size)
Returns a new string array of size elements.
size
Integer that represents the number of elements in the new array.
Examples
OpenBinaryReader()
Function that opens a file as a binary file for reading purposes.
OpenBinaryReader(filename)
Opens filename as a binary file for reading purposes. The function returns a BinaryReader
object.
filename
String that represents the name of the file to open.
Examples
OpenBinaryWriter()
Function that opens a file as a binary file for writing purposes.
OpenBinaryWriter(filename, append)
Opens filename as a binary file for writing purposes. The append Boolean parameter specifies
whether the file pointer should initially be positioned at the end of the existing file (append
mode) or at the beginning of the file (overwrite mode). The function returns a BinaryWriter
object.
filename
String that represents the name of the file to open.
Page 234
append
Boolean parameter that specifies whether the file pointer should initially be positioned at the
end of the existing file (append mode) or at the beginning of the file (overwrite mode).
Examples
OpenTextReader()
Function that opens a file as a text file for reading purposes.
OpenTextReader(filename,encoding)
Opens filename as a text file for reading purposes, using the encoding specified as a string
(UTF-8, ISO-8859-1, etc.). The function returns a TextReader object.
filename
String that represents the name of the file to open.
Examples
OpenTextWriter()
Function that opens a file as a text file for writing purposes.
OpenTextWriter(filename, encoding, append)
Opens filename as a text file for writing purposes, using the encoding specified as a string
(UTF-8, ISO-8859-1, etc.).
The function returns a TextWriter object.
filename
String that represents the name of the file to open.
append
Boolean parameter that specifies whether the file pointer should initially be positioned at the
end of the existing file (append mode) or at the beginning of the file (overwrite mode).
Page 235
Examples
Methods
connect()
Method that returns a new database connection object
Related Object: db.
connect(url, user, password)
Returns a new database connection object after connecting to the url and authenticating the
connection with the provided user and password information.
url
String that represents the url to connect to.
user
String that represents the user name for the authentication.
password
String that represents the password for the authentication.
Examples
createRegion()
Read-only object containing the physical coordinates of the region.
Related Object: Region.
createRegion(x1, y1, x2, y2)
Creates a region from the data, using the specified x1 (left), y1 (top), x2 (width), y2 (height)
parameters, expressed in characters for a Text file or in millimeters for a PDF file.
x1
Double that represents the left edge of the region.
y1
Double that represents the top edge of the region.
Page 236
x2
Double that represents the width of the region.
y2
Double that represents the height of the region.
createRegion(columnName)
Creates a region from the data in a CSV file, using the specified columnName parameter.
columnName
Double that represents the column to be used to create the region.
Examples
currentLoopCounter()
Returns an integer value representing the current iteration of the containing loop. When loops
are nested, you have access to the iteration for the current loop but not to any of the parent
loops.
Related Object: Steps.
Example
currentLoopPosition()
currentPage()
Returns an integer value representing the current page where the current position is located,
inside the current record.
Related Object: Steps.
Example
currentPageHeight()
Returns the height of the current page in millimeters.
Page 237
Related Object: Steps.
Example
currentPageHeight()
Returns the height of the current page in millimeters.
Related Object: Steps.
Example
currentPosition()
Returns the current position of the pointer in the data. Depending on the type of data being
processed, the return value may be a string (e.g. XPath value in XML), an integer (e.g. line
numbers in text ot tabular data), or a measure in millimeters(e.g. PDF data).
Related Object: Steps.
Example
extract()
Extracts the text value from a rectangular region. All coordinates are expressed as characters.
The extract method always returns a String data type.
Related Object: Data.
extract(left, right, verticalOffset, regionHeight, separator)
Extracts a value from a position in a text file.
left
Number that represents the distance from the left edge of the page to the left edge of the
rectangular region.
right
Number that represents the distance from the left edge of the page to the right edge of the
rectangular region.
verticalOffset
Page 238
Number that represents the distance from the current vertical position.
regionHeight
Number that represents the total height of the region.
separator
String inserted between all lines returned from the region. An empty string can be specified.
Examples
Example 1:
In this example you have the script command data.extract(1,22,8,1,"
");. It means that the
left position of the extracted information is located at 1, the right position at 22, the offset
position is 8 (since the line number is 9) and the regionHeight is 1 (only 1 line selected).
Finally, the "
" string is used for concatenation.
Page 239
Example 2:
In this example you have the script command data.extract(1,22,9,6,"
");. It means that the
left position of the extracted information is located at 1, the right position at 22, the offset
position is 9 (since the first line number is 10) and the regionHeight is 6 (6 lines are selected).
Finally, the "
" string is used for concatenation.
extract(xPath)
Extracts the text value of the specified node.
xPath
String that can be relative to the current location or absolute from the start of the record.
Page 240
Example
In this example you have the script command data.extract('./CUSTOMER/FirstName');. It
means that the extraction is made on the FirstName node under Customer.
extract(columnName, rowOffset)
Extracts the text value for the specified fieldName.
fieldName
String that represents the column name.
rowOffset
Number that represents the row index relative to the current position. To extract the current
row, specify 0 as the rowOffset.
Page 241
Example
In this example you have the script command data.extract('ID',0);. It means that the extraction
is made on the ID field in column 0 (the first from the left).
extract(left, right, verticalOffset, lineHeight, separator)
Extracts the text value from a rectangular region. All coordinates are expressed in millimeters.
left
Double that represents the distance from the left edge of the page to the left edge of the
rectangular region.
right
Page 242
Double that represents the distance from the left edge of the page to the right edge of the
rectangular region.
verticalOffset
Double that represents the distance from the current vertical position.
lineHeight
Double that represents the total height of the region.
separator
String inserted between all lines returned from the region. An empty string can be specified.
Example
In this example you have the script command data.extract
(4.572,51.815998,37.761333,3.7253342,"
");. It means that the left position of the
extracted information is located at 4.572mm, the right position at 51.815998mm, the vertical
offset position is 37.761333mm and the lineHeight is 3.7253342mm. Finally, the "
" string
is used for concatenation.
Page 243
extractMeta()
Method that extracts the value of a metadata field.
Related Object: Data.
extractMeta(levelName String, propertyName String)
Extracts the value of metadata field propertyName from a PDF/VT's levelName level. Note
that names are case-sensitive.
The extractMeta method always return a string data type.
levelName
String.
propertyName
String.
Examples
fieldExists()
Method that returns True if a metadata field exists.
Related Object: Data.
fieldExists(levelName, propertyName)
In a PDF file, that method that returns True if metadata field propertyName exists at the
levelName level or False otherwise.
levelName
String.
propertyName
String.
Page 244
fieldExists(fieldName)
In a CSV file, that method returns True if the specified fieldName exists in the current record.
Otherwise, it returns False.
fieldName
String that represents a field name (column) in a CSV file.
fieldExists(xPath
In a XML file, that method returns True if the specified xPath exists in the current record.
Otherwise, it returns False.
xPath
String.
Examples
find()
Finds the first occurrence of a string starting from the current position. The search can be
constrained to the series of characters in a text file or to a vertical strip in a PDF file located
between leftConstraint and rightConstraint, expressed in characters (or in millimeters for a
PDF file). The method returns null if stringToFind cannot be found, otherwise it returns a
RectValueText object.
The RectValueText contains the relative Left, Top, Right and Bottom coordinates of the
smallest possible rectangle that completely encloses stringToFind.
Note that partial matches are not allowed, i.e. the entire stringToFind must be found between
the leftConstraint and rightConstraint parameters. Also, calling this method does not move
the current position to the location where stringToFind was found, allowing you to use the
method as a look-ahead function without disrupting the rest of the workflow.
Related Objects: Boundaries and Data.
find (stringToFind, leftConstraint, rightConstraint)
Finds the first occurrence of a string starting from the current position.
stringToFind
Page 245
String to find.
leftConstraint
Number indicating the left limit from which the search is performed.
rightConstraint
Number indicating the right limit from which the search is performed.
Examples
To search the word "text" on a 8 1/2 x 11 page, the syntax is:
data.find("text", 0, 216);
Numbers 0 and 216 are in millimeters and indicate the left and right limits (constraints) within
which the search should be. Values (0, 216) in this example represent the entire width of a
page. Note that the smaller the area is, the faster the search is. So if you know that the word
"text" is within 3 inches from the left edge of the page, provide the following:
data.find("text", 0, 76.2); 76.2mm =
3*25.4 mm
The return value of the function is:
[Left=26,76, Top=149.77, Right=40,700001, Bottom=154.840302]
Which represents the size of the imaginary rectangle that encloses the string in full, in
millimeters relative to the upper left corner of the current page. This also means that the
data.find () function only works on the current page. If the record contains several pages, you
must create a loop that will perform a jump from one page to another by making a find () on
each page.
found()
Method that returns a Boolean value indicating whether the last call to find() was successful.
Related Object: Region.
found()
Method that returns a Boolean value indicating whether the last call to find() was successful.
Since the find() method always returns a region, regardless of the search results, it is
Page 246
necessary to examine the value of found() to determine the actual result of the operation.
Examples
get()
Related Object: Boundaries.
get(in_Region)
Retrieves an array of strings from the region defined by the in_Region object. in_Region
object can be created with a call to region.createRegion().
in_Region
ScriptRegion tabular Object.
Example
boundaries.get(region.createRegion("Email_Address"));
get(number)
get(object)
get(string)
getVariable()
Method that retrieves the value currently stored in a variable.
Related Object: Boundaries.
getVariable(varName)
Retrieves the value currently stored in variable varName. If the variable does not exist, the
value null is returned. It is considered good practice (almost mandatory, even!) to always check
whether a variable is defined before attempting to access its value.
varName
String name of the variable from which the value is to be retrieved.
Page 247
Example
moveDelimiters()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps.
Example
moveLines()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps.
Example
moveMeasure()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps.
Example
moveNode()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps.
Example
movePage()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Page 248
Related Object: Steps.
Example
moveSibling()
Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps.
Example
moveTo()
Moves the current position to a number.
Related Object: Steps.
moveTo(scope, verticalPosition)
Moves the current position in a Text file to verticalPosition where the meaning of
verticalPosition changes according to the value specified for scope.
scope
Number (from 0-2) that represents:
0 - Lines: verticalPosition represents the index of the line to move to from the top of the
record.
1 - Delimiters: verticalPosition represents the index of the delimiter (as defined in the Input
Data settings) to move to from the top of the record.
2 - Next line with content: verticalPosition is not used, the position is moved to the next line
after the current position that contains any text.
moveTo(scope, verticalOffset)
Moves the current position in a PDF file to verticalOffset where the meaning of verticalOffset
changes according to the value specified for scope.
scope
Number (from 0-1) that represents:
Page 249
0 - millimeters: verticalOffset represents the number of millimeters to move the current
position, relative to the top of the record (NOT the top of the current page).
1 - pages: verticalOffset represents the index of the target page, relative to the top of the
record.
moveTo(xPath)
Moves the current position in a XML file to the first instance of xPath, relative to the top of the
record.
moveTo(row)
Moves the current position in a CSV file to the row index, relative to the top of the record.
Example
moveToNext()
Moves the current position to the next instance of a number.
Related Object: Steps.
moveToNext(scope)
Moves the current position in a text file to the next instance of scope.
scope
Number (from 0-3) that represents:
0 - Lines: current position is set to the next line.
1 - Delimiters: current position is set to the next delimiter (as defined in the Input Data
settings).
2 - Next line with content: current position is set to the next line that contains any text.
Page 250
moveToNext(left, right)
Moves the current position in a PDF file to the next line that contains any text, the search for text
being contained within the left and right parameters, expressed in millimeters.
left
Double that represents the left edge of the text to find.
right
Double that represents the right edge of the text to find.
moveToNext(scope)
Moves the current position in a XML file to the next node in the XML hierarchy, based on the
specified scope.
scope
Number that may be set to steps.MOVENODE (0) or steps.MOVESIBLING (1).
moveToNext()
Moves the current position in a CSV file to the next row, relative to the current position.
Example
range()
Read-only object containing the physical coordinates of the region.
Related Object: Region.
range()
For a Text file, the range() method contains the physical coordinates of the region: x1 (left), y1
(top), x2 (width), y2 (height), expressed in characters.
For a PDF file, the range() method contains the physical coordinates of the region: x1 (left), y1
(top), x2 (width), y2 (height), expressed in millimeters.
For a CSV file, the range() method contains the name of the column that defines the region.
Page 251
Examples
Set()
Sets a new DataMapper record boundary.
Related Object: Boundaries.
Set(delimiters)
Sets a new DataMapper record boundary.
Delimiters
Sets a new record boundary. The delimiters parameter is an integer number representing an
offset from the current delimiter. If this parameter is not specified, then a value of 0 is
assumed.
A value of 0 indicates the record boundary occurs on the current delimiter.
A negative value of -n indicates that the Record boundary occurred -n delimiters before the
current delimiter.
A positive value of n indicates that the Record boundary occurred +n delimiters after the
current delimiter.
IMPORTANT NOTE
Specifying a positive value not only sets the DataMapper record boundary but it also advances
the current delimiter to the specified delimiter. That's where process resumes. This allows you
to skip over the processing of some pages/records when you know they do not warrant being
examined. Negative (or 0) values simply set the boundary without changing the current
location.
For instance, if you want to set DataMapper record boundaries whenever the phrase "Invoice
Total" appears in a specific region of the page. However, the PDF file has already been
padded with blank pages for duplexing purposes. The boundary should therefore be placed at
the end of the page where the match is found if that match occurs on an even page, or at the
end of the next blank page, if the match occurs on an odd page. Recall that for PDF files, the
natural delimiter is a PDF page. The JavaScript code would look something like the following:
var myRegion = region.createRegion(150,220,200,240);
if(boundaries.find("Invoice Total",myRegion).found) {
Page 252
if(boundaries.find("Invoice Total",myRegion).found) {
// a match was found. Check if we are on a odd or even page
and set the Boundary accordingly
if( (boundaries.currentDelim % 2) !=0 ) {
// Total is on odd page, let's set the document Boundary
one delimiter further, thereby skipping the next blank page
boundaries.set(1);
} else {
// Total is on an even page, set the document Boundary to
the current delimiter
boundaries.set();
}
}
}
Note
The above code could be completely rewritten as:
if(boundaries.find("Invoice Total",region.createRegion(150,220,200,240).found) {
(boundaries.currentDelim % 2) !=0 ? boundaries.set(1): boundaries.set();
}
setVariable()
Method that sets a variable to the specified value, automatically creating the variable if it
doesn't exist yet.
Related Object: Boundaries.
setVariable(varName, varValue)
Sets variable varName to value varValue.
varName
String name of the variable from which the value is to be set.
varValue
Object
Page 253
Example
totalPages()
Returns an integer value representing the total number of pages inside the current record.
Related Object: Steps.
Example
Page 254
The Designer
The Designer is a WYSIWYG (what you see is what you get) editor that lets you create
templates for various output channels: Print, Email and Web. A template may contain designs
for multiple output channels: a letter intended for print and an e-mail variant of the same
message, for example. Content, like the body of the message or letter, can be shared across
these contexts. Templates are personalized using scripts and variable data extracted via the
DataMapper.More advanced users may use native HTML, CSS and JavaScript.
The following topics will help to quickly familiarize yourself with the Designer.
l
"Basic Steps" below. These are the basic steps for creating and developing a template.
l
"Features" on page 274. These are some of the key features in the Designer.
l
"Designer User Interface" on page 546. This part gives an overview of all elements in the
Designer User Interface, like menus, dialogs and panes.
More help can be found here:
l
l
l
Tutorials On Video: watch an introductory video, overview tutorials or practical how-to
videos.
Forum: Browse the forum and feel free to ask questions about the use of Connect
software
Demo site. Download demonstrations of OL products.
Basic Steps
With the Designer you can create templates for personalized letters, emails and web pages,
and generate output from them.
These are the basic steps for creating and developing a template:
1. Create a template
Create a template, using one of the Template Wizards. See "Creating a template" on the
facing page.
Page 255
2. Fill the template
Add text, images and other elements to the template and style them. See "Content
elements" on page 373 and "Styling and formatting" on page 453.
3. Personalize the content
Personalize the content using variable data. See "Personalizing content" on page 485.
4. Generate output
Adjust the settings, test the template and generate output: letters, emails, and/or web
pages. See "Generating output" on page 798.
5. What's next
Use Workflow to automate your customer communications.
Note
Steps 2 and 3 are not necessarily to be followed in this order. For example, as you add
elements to a template, you may start personalizing them right away, before adding other
elements to the template.
Templates
The Designer is a WYSIWYG (what you see is what you get) tool to create templates. This topic
gets you started. It explains how to create a template, what is found in a template file, and how
output can be generated.
Creating a template
In the Welcome screen that appears after startup, get off to a flying start choosing Browse
Template Wizards. Scroll down to see all the Template Wizards. After deciding which output
channel – print, email or web – will be prevalent in your template, select a template.
The Template Wizards can also be accessed from the menu: click File, click New, expand the
Template folder, and then expand one of the templates folders.
There are Wizards for the three types of output channels, or contexts as they are called in the
Designer: Print, Email and Web.
See:
Page 256
l
l
l
"Creating an Email template with a Wizard" on page 311
"Creating a Print template with a Wizard" on page 277
"Creating a Web template with a Wizard" on page 327
After creating a template you can add the other contexts (see "Contexts" on page 269), as well
as extra sections (see "Sections" on page 271), to the template.
It is, however, not possible to use a Template Wizard when adding a context or section to an
existing template.
Tip
If an Email context is going to be part of the template, it is recommended to start with an
Email Template Wizard; see "Creating an Email template with a Wizard" on page 311.
After creating a template, contexts can be added to it, but that can not be done with a
wizard.
Saving a template
A Designer template file has the extension .OL-template. It is a zip file that includes up to 3
contexts, all the related resources and scripts, and (optionally) a link to a Data Mapping
Configuration.
To save a template for the first time, select File > Save as. After that you can save the template
by selecting File > Save or pressing Ctrl+S.
When more than one resource (template or data mapping configuration) is open and the
Designer software is closed, the Save Resources dialog appears. This dialog displays a list of
all open resources with their names and file location. Selected resources will be saved,
deselected resources will have all their changes since they were last saved dismissed.
Auto Save
After a template has been saved for the first time, Connect Designer can auto save the
template with a regular interval. To configure Auto Save:
1. Select the menu option Window > Preferences > Save.
2. Under Auto save, check the option Enable to activate the Auto Save function.
Page 257
3. Change how often it saves the template by typing a number of minutes.
Auto Backup
Connect Designer can automatically create a backup file when you manually save a template.
To configure Auto Backup:
1. Select the menu option Window > Preferences > Save.
2. Under Auto backup, check the option Enable to activate the Auto Backup function.
3. Type the number of revisions to keep.
4. Select the directory in which the backups should be stored.
Backup files have the same name as the original template with two underscores and a
progressive number (without leading zeros) at the end: originalname__1.OL-template,
originalname__2.OL-template, etc.
Note
The Auto Save function does not cause backup files to be created.
Sharing a template
To share a template, you can send the template file itself, or save the template to a package file,
optionally together with a Data Mapping Configuration, a Job Creation Preset and an Output
Creation Preset. (See "Job Creation Presets" on page 701 and "Output Creation Settings" on
page 710 for more details.)
To create a package file, select File > Send to Workflow and choose File in the Destination
box. For the other options, see "Sending files to Workflow" on the next page. The package file
has the extension .OL-package.
Generating output from the Designer
Output can be generated directly from the Designer; see "Generating Print output" on page 801,
"Generating Email output" on page 815 and "Generating Web output" on page 825.
Page 258
To test a template first, select Context > Preflight. Preflights executes the template without
actually producing output and it displays any issues once it's done (see also: "Testing scripts"
on page 523).
Sending files to Workflow
Workflow can generate output from a template as well. For this, the template has to be sent to
Workflow.
The Send to Workflow dialog sends templates, Data Mapping Configurations and print presets
to the Workflow server, or saves them as a package file. Print presets make it possible to do
such things as filtering and sorting records, grouping documents and splitting the print jobs into
smaller print jobs, as well as the more standard selection of printing options, such as binding,
OMR markings and the like. See "Job Creation Presets" on page 701 and "Output Creation
Settings" on page 710 for more details.
To send one or more templates to Workflow:
1. Select File > Send to Workflow.
2. Select the template to send. By default the currently active template is listed. Click
Browse to select another template. You may select more than one template in the
Browse dialog, and each of them is sent to Workflow (or added to a package file). A
template file has the extension .OL-template.
3. Select the Data Mapping Configuration to send. By default the current configuration is
listed. Click Browse to select another configuration. You may select more than one
configuration file in the Browse dialog, and each of them is sent to Workflow (or added to
a package file). A Data Mapping Configuration file has the extension .OL-datamapper.
4. Use the drop-down to select a Job Creation Preset to send. Click Browse to select a
preset that is not in the default location for presets. A Job Creation Preset file has the
extension .OL-jobpreset.
5. Use the drop-down to select an Output Creation Preset. Click Browse to select a preset
that is not in the default location for presets. An Output Creation Preset file has the
extension .OL-outputpreset.
6. Finally, choose the Destination: use the drop-down to select where to send the files. The
option Workflow machines lists all the PlanetPress Workflow installations detected on
the network. Select File to save the files as a package that can be loaded within the
Workflow tool.
Page 259
Resources
This page clarifies the difference between Internal, External and Web resources that may be
used in a template, and explains how to refer to them in HTML and in scripts.
Internal resources
Internal resources are files that are added to and saved with the template. To add images, fonts,
style sheets, and snippets to your template, you can drag or copy/paste them into the
Resources Pane. See also: "Images" on page 440, "Snippets" on page 451, "Styling templates
with CSS files" on page 454 and "Fonts" on page 476.
Resource files can also be dragged or copy/pasted out of the the application to save them on a
local hard drive.
Once imported, internal resources are accessed using a relative path, depending where they're
called from. Resources can be located in the following folders:
l
images/ contains the files in the Images folder.
l
fonts/ contains the files in the Fonts folder.
l
css/ contains the files in the StyleSheets folder.
l
js/ contains the files in the JavaScripts folder.
l
snippets/ contains the files in the Snippets folder.
When refering to them, normally you would simply use the path directly with the file name. The
structure within those folders is maintained, so if you create a "signatures" folder within the
"Images" folder, you need to use that structure, for example in HTML: 
. In scripts, you can refer to them in the same way, for
example:
results.loadhtml("snippets/en/navbar.html");
See also: "Loading a snippet via a script" on page 530 and "Writing your own scripts" on
page 515.
Note
When referring to images or fonts from a CSS file, you need to remember that the current path is
css/, meaning you can't just call images/image.jpg. Use a relative path, for example: #header {
background-image: url('../images/image.jpg'); }
Page 260
External resources
External resources are not stored in the template, but on the local hard drive or on a network
drive. They are accessed using a path. The path must have forward slashes, for example 
or var json_variables = loadjson
("file:///d:/jsondata/variables.json");. The complete syntax is: file:///. If the
host is "localhost", it can be omitted, as it is in the example, resulting in file:///. The
empty string is interpreted as `the machine from which the URL is being interpreted'.
Network paths are similar: results.loadhtml
("file://servername/sharename/folder/snippet.html"); (note that in this case file is
followed by 2 slashes only).
Some limitations
l
l
Style sheets cannot refer to external resources.
The Connect Server user needs access to whichever network path is used. If the network
path is on a domain, the Connect Server must be identified with domain credentials that
have access to the domain resources.
For more information on network paths, please see this Wikipedia entry: file URI scheme.
Web resources
Web resources are simply accessed using a full URL. This URL needs to be publicly
accessible: if you type in that URL in a browser on the server, it needs to be visible.
Authentication is possible only through URL Parameters
(http://www.example.com/data.json?user=username&password=password) or through HTTP
Basic Auth (http://username:password@www.example.com/data.json).
Resources can also be called from a PlanetPress Workflow instance:
l
l
"Static Resources", as set in the preferences, are accessed using the resource path, by
default something like http://servername:8080/_iRes/images/image.jpg. (For guidance on
setting the preferences, search for 'HTTP Server Input 2' in the PlanetPress Workflow
help files on OL Help).
Resources can also be served by processes: http://servername:8080/my_
process?filename=image.jpg (assuming "my_process" is the action in the HTTP Server
Input).
Page 261
Creating a Web template with a Wizard
With the Designer you can design Web templates and output them through Workflow or as an
attachment to an email when generating Email output.
Capture On The Go templates are a special kind of Web templates; see "Capture OnTheGo
template wizards" on page 358.
A Web Template Wizard helps you create a Web page that looks good on virtually any browser,
device and screen size.
Foundation
All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end
framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build
upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first
approach, so that websites built upon Foundation look good and function well on multiple
devices including desktop and laptop computers, tablets, and mobile phones. Foundation is
tested across many browsers and devices, and works back as far as IE9 and Android 2. See
http://foundation.zurb.com/learn/about.html and "Using Foundation" on page 362.
After creating a Web template, the other contexts can be added, as well as other sections (see
"Adding a context" on page 270 and "Adding a Web page" on page 332).
To create a Web template with a Template Wizard:
1.
l
l
In the Welcome screen that appears after startup, choose Browse Template
Wizards.
Scroll down until you see the Foundation Web Page Starter Template Wizards.
Alternatively, on the File menu, click New, expand the Template folder, and then
expand the Foundation Web Page Starter folder.
2. Select a template. There are 4 types of Web Template Wizards :
l
Blank
l
Contact Us
l
Jumbotron
l
Thank You
Page 262
If you don't know what template to choose, see "Web Template Wizards" on the facing
page further down in this topic, where the characteristics of each kind of template are
described.
3. Click Next and make adjustments to the initial settings.
l
Section:
l
l
l
Description: Enter the description of the page. This is the contents of a HTML tag.
Top bar group:
l
l
l
l
Name: Enter the name of the Section in the Web context. This has no effect on
output.
Set width to Grid: Check this option to limit the width of the top bar contents to
the Foundation Grid, instead of using the full width of the page.
Stick to the top of the browser window: Check to lock the top menu bar to
the top of the page, even if the page has scroll bars. This means the menu bar
will always be visible in the browser.
Background color: Enter a valid hexadecimal color code for the page
background color (see w3school's color picker) , or click the colored circle to
the right to open the Color Picker.
Colors group: Enter a valid hexadecimal color code (see w3school's color picker)
or click the colored circle to open the Color Picker, and pick a color for the following
elements:
l
Primary: links on the page.
l
Secondary: secondary links on the page.
l
Text: text on the page contained in paragraphs ().
l
Headings: all headings (
through ) including the heading section's
subhead.
4. Click Finish to create the template.
The Wizard creates:
l
A Web context with one web page template (also called a section) in it. The web page
contains a Header, a Section and a Footer element with dummy text, and depending on
the type of web page, a navigation bar, button and/or Form elements.
Page 263
l
l
l
Resources related to the Foundation framework (see "Web Template Wizards" below):
style sheets and JavaScript files. The style sheets can be found in the Stylesheets folder
on the Resources pane. The JavaScript files are located in the JavaScript folder on the
Resources pane, in a Foundation folder.
A collection of Snippets in the Snippets folder on the Resources pane. The Snippets
contain ready-to-use parts to build the web page. Double-click to open them. See
"Snippets" on page 451 for information about using Snippets.
Images: icons, one picture and one thumbnail picture. Hover your mouse over the names
of the images in the Images folder on the Resources pane to get a preview.
The Wizard opens the Web section, so that you can fill it with text and other elements; see
"Content elements" on page 373, "Web Context" on page 331 and "Web pages" on page 332.
Web pages can be personalized just like any other type of template; see "Variable Data" on
page 497 and "Personalizing content" on page 485.
Tip
Use the Outline pane at the left to see which elements are present in the template and to
select an element.
Use the Attributes pane at the right to see the current element's ID, class and some other
properties.
Use the Styles pane next to the Attributes pane to see which styles are applied to the
currently selected element.
Tip
Click the Edges button on the toolbar to make borders of elements visible on the Design
tab. The borders will not be visible on the Preview tab.
Page 264
Web Template Wizards
Foundation
All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end
framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build
upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first
approach, so that websites built upon Foundation look good and function well on multiple
devices including desktop and laptop computers, tablets, and mobile phones. Foundation is
tested across many browsers and devices, and works back as far as IE9 and Android 2. See
http://foundation.zurb.com/learn/about.html and "Using Foundation" on page 362.
Jumbotron
The name of the Jumbotron template is derived from the large screens in sports stadiums. It is
mostly useful for informative or marketing-based websites. Its large banner at the top can
display important text and its "call to action" button invites a visitor to click on to more
information or an order form.
Contact Us
The Contact Us template is a contact form that can be used on a website to receive user
feedback or requests. It's great to use in conjunction with the Thank You template, which can
recap the form information and thank the user for feedback.
Thank You
The Thank You template displays a thank you message with some text and media links.
Blank web page
The Blank Web Page template is a very simple Foundation template that contains a top bar
menu and some basic contents to get you started.
Capture OnTheGo template wizards
With the Designer you can create Capture OnTheGo (COTG) templates. COTG templates are
used to generate forms for the Capture OnTheGo mobile application. For more information
about this application, see the website: Capture OnTheGo.
Page 265
A Capture OnTheGo Form is actually just a Web Form, that you could add without a wizard, but
the COTG Template Wizards include the appropriate JavaScript files for the Capture OnTheGo
app, and styles to create user-friendly, responsive forms. They are built upon the Foundation
framework.
Foundation
All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end
framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build
upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first
approach, so that websites built upon Foundation look good and function well on multiple
devices including desktop and laptop computers, tablets, and mobile phones. Foundation is
tested across many browsers and devices, and works back as far as IE9 and Android 2. See
http://foundation.zurb.com/learn/about.html and "Using Foundation" on page 362.
After creating a COTG template, the other contexts can be added, as well as other sections
(see "Adding a context" on page 270 and "Adding a Web page" on page 332).
Tip
If the COTG Form replaces a paper form, it can be tempting to stick to the original layout. Although
that may increase the recognizability, it is better to give priority to the user-friendliness of the form.
Keep in mind that the COTG form will be used on a device and don't miss the chance to make it as
user-friendly as possible.
Creating a COTG template using a Wizard
To create a COTG template with a Template Wizard:
1.
l
l
In the Welcome screen that appears after startup and when you click the Home icon
at the top right, choose Browse Template Wizards. Scroll down until you see the
Capture OnTheGo Starter Template Wizards.
Alternatively, on the File menu, click New, expand the Template folder, and then
expand the Capture OnTheGo Starter folder.
2. Select a template. There are 8 types of Web Template Wizards:
l
Blank. The Blank COTG Template has some basic design and the appropriate
form, but no actual form or COTG elements.
Page 266
l
l
l
l
l
l
l
Bill of Lading. The Bill of Lading Template is a transactional template that includes
a detail table with a checkmark on each line, along with Signature and Date COTG
elements. Use this wizard as a way to quickly start any new Zurb Foundation based
form for Capture OnTheGo.
Event Registration. The Event Registration Template is a generic registration form
asking for name, phone, email, etc.
Event Feedback. The Event Feedback Template is a questionnaire containing
different questions used to rate an experience.
Membership Application. The Membership Application Template is a signed
generic request form that can be used for memberships such as gyms, clubs, etc.
Patient Intake. The Patient Intake Template is a generic medical questionnaire that
could potentially be used as a base for insurance or clinic form.
Kitchen Sink. The Kitchen Sink Template includes a wide range of basic form and
COTG form elements demonstrating various possibilities of the software.
Time Sheet. The Time Sheet Template is a single page application used to add
time entries to a list. This template demonstrates the dynamic addition of lines within
a COTG template, as the Add button creates a new time entry. There is no limit to
the number of entries in a single page.
3. Click Next and make adjustments to the initial settings.
l
l
l
l
l
Create Off-Canvas navigation menu: an Off-Canvas menu is a Foundation
component that lets you navigate between level 4 headings () in the form.
Check this option to add the menu automatically.
Submit URL: enter the URL where the form data should be sent. The URL should
be a server-side script that can accept COTG Form data.
The Title and the Logo that you choose will be displayed at the top of the Form.
Background color: Enter a valid hexadecimal color code for the page background
color (see w3school's color picker).
Enter a valid hexadecimal color code (see w3school's color picker) for the
background color of the navigation bar at the top and another for the buttons on the
Form.
4. Click Next to go to the next settings page if there is one.
5. Click Finish to create the template.
The Wizard creates:
Page 267
l
l
l
A Web context with one web page template (also called a section) in it. The web page
contains an 'off-canvas' Div element, Header, a Section and a Footer element with
dummy text, and depending on the type of web page, a navigation bar, button and/or
Form elements.
Style sheets and JavaScript files related to the COTG form itself and others related to
the Foundation framework (see above). The style sheets can be found in the Stylesheets
folder on the Resources pane. The JavaScript files are located in the JavaScript folder on
the Resources pane.
A collection of snippets in the Snippets folder on the Resources pane. The snippets
contain ready-to-use parts to build the web form. Double-click to open them. See
"Snippets" on page 451 and "Loading a snippet via a script" on page 530 for information
about using Snippets.
The Wizard opens the Web section, so that you can fill the Capture OnTheGo form.
6. Make sure to set the action and method of the form: select the form and then enter the
action and method on the Attributes pane.
The action of a Capture OnTheGo form should specify the Workflow HTTP Server Input task
that receives and handles the submitted data. The action will look like this:
http://127.0.0.1:8080/action (8080 is Workflow's default port number; 'action' should be
replaced by the HTTP action of that particular HTTP Server Input task).
The method of a Capture OnTheGo form should be POST to ensure that it doesn't hit a data
limit when submitting the form. The GET method adds the data to the URL, and the length of a
URL is limited to 2048 characters. Especially forms containing one or more Camera inputs may
produce a voluminous data stream that doesn't fit in the URL. GET also leaves data trails in log
files, which raises privacy concerns. Therefore POST is the preferred method to use.
Filling a COTG template
Before inserting elements in a COTG Form, have the design ready; see "Designing a COTG
Template" on page 355.
In a Capture OnTheGo form, you can use special Capture OnTheGo Form elements, such as a
Signature and a Barcode Scanner element; see "COTG Elements" on page 424 and "Using
COTG Elements" on page 365.
Page 268
Foundation, the framework added by the COTG template wizards, comes with a series of
features that can be very useful in COTG forms; see "Using Foundation" on page 362.
Naturally, Web Form elements can also be used on COTG Forms (see "Forms" on page 430
and "Form Elements" on page 435) as well as text, images and other elements (see "Content
elements" on page 373).
Capture OnTheGo templates can be personalized just like any other type of template; see
"Variable Data" on page 497 and "Personalizing content" on page 485.
Tip
Use the Outline pane at the left to see which elements are present in the template and to
select an element.
Use the Attributes pane at the right to see the current element's ID, class and some other
properties.
Use the Styles pane next to the Attributes pane to see which styles are applied to the
currently selected element.
Tip
Click the Edges button on the toolbar to make borders of elements visible on the Design
tab. The borders will not be visible on the Preview tab.
Contexts
Contexts are parts of a template that are each used to generate a specific type of output: Web,
Email or Print.
l
l
l
The Print context outputs documents to either a physical printer a PDF file; see "Print
context" on page 281.
The Email context outputs HTML email, composed of HTML code with embedded CSS.
See "Email context" on page 315.
The Web context outputs an HTML web page. See "Web Context" on page 331.
Page 269
When a new template is made, the Context appropriate to that new template is automatically
created, including one section. After a template has been created, the other two contexts can be
added to it; see "Adding a context" on the facing page.
Tip
If an Email context is going to be part of the template, it is recommended to start with an
Email Template Wizard; see "Creating an Email template with a Wizard" on page 311.
After creating a template, contexts can be added to it, but that can not be done with a
wizard.
Outputting and combining contexts
All three contexts can be present in any template and they can all be used to output documents;
see "Generating Email output" on page 815, "Generating Print output" on page 801 and
"Generating Web output" on page 825.
They can even be combined in output.
If present in the same template, a Print context and a Web context can be attached to an Email
context.
Outputting other combinations of contexts, and selecting sections based on a value in the data,
can be done via a Control Script; see "Control Scripts" on page 532.
Adding a context
To add a context, right-click the Contexts folder on the Resources pane and click New print
context, New email context or New web context. Only one context of each type can be
present in a template. Each context, however, can hold more than one section; see "Sections"
on the next page.
Deleting a context
To delete a context, right-click the context on the Resources pane and click Delete.
Page 270
Warning
No backup files are maintained in the template. The only way to recover a deleted
section, is to click Undo on the Edit menu, until the deleted section is restored. After
closing and reopening the template it is no longer possible to restore the deleted context
this way.
To prevent losing any work, it is recommended to configure the auto-save and autobackup functions in the preferences (see "Saving Preferences" on page 587).
Sections
Sections are parts of one of the contexts in a template: Print, Email or Web. They contain the
main text flow for the contents. In each of the contexts there can be multiple sections. A Print
context, for example, may consist of two sections: a covering letter and a policy.
Adding a section
To add a section to a context, right-click the context (Email, Print or Web) on the Resources
pane, and then click New section.
It is not possible to use a Template Wizard when adding a section to an existing template.
Tip
If an Email context is going to be part of the template, it is recommended to start with an
Email Template Wizard; see "Creating an Email template with a Wizard" on page 311.
After creating a template, contexts can be added to it, but that can not be done with a
wizard.
Editing a section
To open a section, expand the Contexts folder on the Resources pane, expand the respective
context (Print, Email or Web) and double-click a section to open it.
Each section can contain text, images and many other elements (see "Content elements" on
page 373), including variable data and other dynamic elements (see "Personalizing content" on
page 485).
Page 271
Copying a section
Copying a section, either within the same template or from another template, can only be done
manually. You have to copy the source of the HTML file:
1. Open the section that you want to copy and go to the Source tab in the workspace.
2. Copy the contents of the Source tab (press Ctrl+A to select everything and then Ctrl+C to
copy the selection).
3. Add a new section (see Adding a section).
4. Go to the Source tab and paste the contents of the other section here (press Ctrl+V).
5. When copying a section to another template, add the related source files, such as images,
to the other template as well.
Deleting a section
To delete a section:
l
On the Resources pane, expand the Contexts folder, expand the folder of the respective
context, right-click the name of the section, and then click Delete.
Warning
No backup files are maintained in the template. The only way to recover a deleted
section, is to click Undo on the Edit menu, until the deleted section is restored. After
closing and reopening the template it is no longer possible to restore the deleted context
this way.
Renaming a section
To rename a section:
l
On the Resources pane, expand the Contexts folder, expand the folder of the respective
context, right-click the name of the section, and then click Rename.
Note
Sections cannot have an integer as name. The name should always include alphanumeric characters.
Page 272
Section properties
Which properties apply to a section, depends on the context it is part of. See also: "Print
sections" on page 284, "Email templates" on page 317, and "Web pages" on page 332.
To change the properties for a section:
l
On the Resources pane, expand the Contexts folder, expand the folder of the respective
context, right-click the name of the section, and then click one of the options.
Applying a style sheet to a section
In order for a style sheet to be applied to a specific section, it needs to be included in that
section. There are two ways to do this.
Drag & drop a style sheet
1. Click and hold the mouse button on the style sheet on the Resources pane.
2. Move the mouse cursor within the Resources pane to the section to which the style sheet
should be applied.
3. Release the mouse button.
Using the Includes dialog
1. On the Resources pane, right-click the section, then click Includes.
2. Choose which CSS files should be applied to this section. You can also change the order
in which the CSS files are read. This can have an effect on which CSS rule is applied in
the end.
Arranging sections
Changing the order of the sections in a context can have an effect on how they are outputted;
see: "Print sections" on page 284, "Email templates" on page 317 and "Web pages" on
page 332.
To rearrange sections in a context:
l
On the Resources pane, expand the Contexts folder, expand the folder of the respective
context, and then drag and drop sections to change the order they are in.
Alternatively, right-click a section and click Arrange. In the Arrange Sections dialog you
Page 273
can change the order of the sections in the same context by clicking the name of a section
and moving it using the Up and Down buttons.
Outputting sections
Which sections are added to the output, depends on the type of context they are in.
When generating output from the Print context, each of the Print sections is added to the output
document, one after the other in sequence, for each record. The sections are added to the
output in the order in which they appear on the Resources pane. See "Generating Print output"
on page 801.
In email and web output, only one section can be executed at a time. The section that will be
output is the section that has been set as the 'default'. See "Generating Web output" on
page 825 and "Web pages" on page 332 and "Generating Email output" on page 815 and
"Email templates" on page 317. The 'default' section is always executed when the template is
run using the Create Email Content task in Workflow (see Workflow Help: Create Email
Content).
It is, however, possible to include or exclude sections when the output is generated, or to set
another section as the 'default', depending on a value in the data. A Control Script can do this;
see "Control Scripts" on page 532.
See "Generating output" on page 798 to learn how to generate Print documents, Web pages or
Email.
Features
The Designer is Connect's module to create templates for personalized customer
communications. These are some of the key features in the Designer:
"Templates" on page 256. Start creating, using and sharing templates.
"Contexts" on page 269. A context contains one or more designs for one output channel:
l
"Print" on the next page. This topic helps you design and fill sections in the Print context.
l
"Email" on page 307. This topics helps you design an email template.
l
"Web" on page 326. This topic helps you design a web page.
"Sections" on page 271. Sections in one context are designed for the same output channel.
Page 274
"Content elements" on page 373. Elements make up the biggest part of the content of each
design.
"Snippets" on page 451. Snippets help share content between contexts, or insert content
conditionally.
"Styling and formatting" on page 453. Make your Designer templates look pretty and give them
the same look and feel with style sheets.
"Personalizing content" on page 485. Personalize your customer communications using
variable data.
"Writing your own scripts" on page 515. Scripting can take personalization much further. Learn
how to script via this topic.
"Generating output" on page 798. Learn the ins and outs of generating output from each of the
contexts.
Print
With the Designer you can create one or more Print templates and merge the template with a
data set to generate personal letters, invoices, policies etc.
The Print context is the folder in the Designer that can contain one or more Print sections.
Print templates, also called Print sections, are part of the Print context. They are meant to be
printed to a printer or printer stream, or to a PDF file (see "Generating Print output" on
page 801).
The Print context can also be added to Email output as a PDF attachment; see "Generating
Email output" on page 815. When generating output from the Print context, each of the Print
sections is added to the output document, one after the other in sequence, for each record.
When a Print template is created (see "Creating a Print template with a Wizard" on page 277),
or when a Print context is added to an existing template (see "Adding a context" on page 270)
the Print context folder is created along with other folders and files that are specific to a Print
context (see "Print context" on page 281).
Page 275
Only one Print section is created at the start, but you can add as many Print sections as you
need; see "Print sections" on page 284.
Pages
Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally
limited by their size and margins. If the content of a section doesn't fit on one page, the overflow
goes to the next page. This happens automatically, based on the section's page size and
margins; see "Page settings: size, margins and bleed" on page 292.
Although generally the same content elements can be used in all three contexts (see "Content
elements" on page 373), the specific characteristics of pages make it possible to use special
elements, such as page numbers; see "Page numbers" on page 294.
See "Pages" on page 291 for an overview of settings and elements that are specific for pages.
Headers, footers, tear-offs and repeated elements (Master
page)
In Print sections, there are often elements that need to be repeated across pages, like headers,
footers and logos. In addition, some elements should appear on each first page, or only on
pages in between the first and the last page, or only on the last page. Examples are a different
header on the first page, and a tear-off slip that should show up on the last page.
This is what Master Pages are used for. Master Pages can only be used in the Print context.
See "Master Pages" on page 299 for an explanation of how to fill them and how to apply them
to different pages.
Stationery (Media)
When the output of a Print context is meant to be printed on paper that already has graphical
and text elements on it (called stationery, or preprinted sheets), you can add a copy of this
media, in the form of a PDF file, to the Media folder.
Media can be applied to pages in a Print section, to make them appear as a background to
those pages. This ensures that elements added to the Print context will correspond to their
correct location on the preprinted media.
Page 276
When both Media and a Master Page are used on a certain page, they will both be displayed
on the Preview tab of the workspace, the Master Page being 'in front' of the Media and the Print
section on top. To open the Preview tab, click it at the bottom of the Workspace or select View >
Preview View on the menu.
The Media will not be printed, unless this is specifically requested through the printer settings in
the Print Wizard; see "Generating Print output" on page 801.
See "Media" on page 302 for further explanation about how to add Media and how to apply
them to different pages.
Creating a Print template with a Wizard
A Print template may consist of various parts, such as a covering letter and a policy. Start with
one of the Template Wizards for the first part; other parts can be added later.
To create a Print template with a Template Wizard:
1.
l
In the Welcome screen that appears after startup:
l
l
l
Choose Browse Template Wizards and scroll down until you see the Print
Template wizards and select the Postcard or Formal Letter wizard.
Or choose Create a New Template and select the PDF-based Print wizard.
Alternatively, on the File menu, click New, expand the Template folder, and then:
l
l
Select the PDF-based Print wizard.
Or expand the Basic Print templates folder, select Postcard or Formal Letter
and click Next.
See "Print Template Wizards" on the facing page for information about the various types
of Template wizards.
2. Make adjustments to the initial settings (the options for each type of template are listed
below). Click Next to go to the next settings page if there is one.
3. Click Finish to create the template.
See "Print context" on page 281 and "Print sections" on page 284 for more information about
Print templates.
Page 277
Tip
Use the Outline pane at the left to see which elements are present in the template and to
select an element.
Use the Attributes pane at the right to see the current element's ID, class and some other
properties.
Use the Styles pane next to the Attributes pane to see which styles are applied to the
currently selected element.
Print Template Wizards
There are three Print Template wizards: one for a formal letter, one for a postcard and one for a
Print template based on a PDF that you provide.
Postcard
The Postcard Wizard lets you choose a page size and two background images, one for the front
and one for the back of the postcard.
When you click Finish, the Wizard creates:
l
l
l
l
l
A Print context with one section in it, that has duplex printing (printing on both sides)
enabled. See "Printing on both sides" on page 283.
Two Master Pages that each contain a background image. The first Master Page is
applied to the front of every page in the Print section. The second Master Page is applied
to the back of every page in the Print section. See "Master Pages" on page 299.
Scripts and selectors for variable data. The Scripts pane shows, for example, a script
called "first_name". This script replaces the text "@first_name@" on the front of the
postcard by the value of a field called "first_name" when you open a data set that has a
field with that name. See "Variable Data" on page 497.
A script called Dynamic Front Image Sample. This script shows how to toggle the image
on the front page dynamically. See also "Writing your own scripts" on page 515.
One empty Media. Media, also called Virtual Stationery, can be applied to all pages in the
Print section. See "Media" on page 302.
Page 278
The Wizard opens the Print section, so that you can fill it with text and other elements; see
"Content elements" on page 373. It already has two Positoned Boxes on it: one on the front, for
text, and one on the back, for the address.
See "Print context" on page 281 and "Print sections" on page 284 for more information about
Print templates.
Formal letter
The Formal Letter Wizard first lets you select the page settings, see "Page settings: size,
margins and bleed" on page 292.
These settings are fairly self-explanatory, except perhaps these:
l
l
l
l
Duplex means double-sided printing.
The margins define where your text flow will go. The actual printable space on a page
depends on your printer.
The bleed is the printable space around a page. It can be used on some printers to
ensure that no unprinted edges occur in the final trimmed document. Printers that can’t
print a bleed, will misinterpret this setting. Set the bleed to zero to avoid this.
The number of sections is the number of parts in the Print context. Although this Template
wizard can add multiple Print sections to the Print context, it will only add content to the
first section.
On the next settings page (click Next to go there), you can type a subject, the sender's name
and the sender's title. These will appear in the letter. You can also:
l
l
Click the Browse button to select a signature image. This image will appear above the
sender's name and title.
Select Virtual Stationery: a PDF file with the letterhead stationery. Also see Media.
When you click Finish, the Wizard creates:
l
l
A Print context with one section in it; see "Print context" on page 281 and "Print sections"
on page 284.
One empty Master Page. Master Pages are used for headers and footers, for images and
other elements that have to appear on more than one page, and for special elements like
tear-offs. See "Master Pages" on page 299.
Page 279
l
l
One Media. You can see this on the Resources pane: expand the Media folder. Media 1
is the Virtual Stationery that you have selected in the Wizard. It is applied to all pages in
the Print section, as can be seen in the Sheet Configuration dialog. (To open this dialog,
expand the Contexts folder on the Resources pane; expand the Print folder and rightclick "Section 1"; then select Sheet Configuration.) See "Media" on page 302.
Selectors for variable data, for example: @Recipient@. You will want to replace these by
the names of fields in your data. See "Variable Data" on page 497.
The Wizard opens the Print section. You can add text and other elements; see "Content
elements" on page 373.
The formal letter template already has an address on it. The address lines are paragraphs,
located in one cell in a table with the ID address-block-table. As the table has no borders, it is
initially invisible. The address lines will stick to the bottom of that cell, even when the address
has fewer lines. See "Styling and formatting" on page 453 to learn how to style elements.
Tip
Click the Edges button on the toolbar to make borders of elements visible on the Design
tab. The borders will not be visible on the Preview tab.
PDF-based Print template
The PDF-based Print template wizard creates a document from an existing PDF file: a
brochure, voucher, letter, etc. The PDF is used as the background image of the Print section
(see "Using a PDF file as background image" on page 288). Variable and personalized
elements, like a reseller address, voucher codes and so on, can be added in front of it (see
"Personalizing content" on page 485 and "Variable Data" on page 497).
By default, the PDF itself is added to the Image folder located in the Resources pane.
Uncheck the option Save with template if the PDF should not be imported in the template. If
not saved with the template, the image will remain external. Note that external images need to
be available when the template is merged with a record set to generate output, and that their
location should be accessible from the machine on which the template's output is produced.
External images are updated (retrieved) at the time the output is generated.
After clicking Next, you can change the settings for the page. The initial page size and bleed
area are taken from the selected PDF.
Page 280
When you click Finish, the Wizard creates:
l
l
l
A Print context with one section in it; see "Print context" below and "Print sections" on
page 284. The selected PDF is used as the background of the Print section; see "Using a
PDF file as background image" on page 288. For each page in the PDF one page is
created in the Print section.
One empty Master Page. Master Pages are used for headers, footers, images and other
elements that have to appear on more than one page, and for special elements like tearoffs. See "Master Pages" on page 299.
One empty Media. Media, also called Virtual Stationery, can be applied to all pages in the
Print section. See "Media" on page 302.
Print context
The Print context is the folder in the Designer that can contain one or more Print templates.
Print templates, also called Print sections, are part of the Print context. They are meant to be
printed to a printer or printer stream, or to a PDF file (see "Generating Print output" on
page 801).
The Print context can also be added to Email output as a PDF attachment; see "Generating
Email output" on page 815. When generating output from the Print context, each of the Print
sections is added to the output document, one after the other in sequence, for each record.
Creating the Print context
You can start creating a Print template with a Wizard (see "Creating a Print template with a
Wizard" on page 277), or add the Print context to an existing template (see "Adding a context"
on page 270).
Tip
Editing PDF files in the Designer is not possible, but when they're used as a section's
background, you can add text and other elements, such as a barcode, to them. To create
a new Print template from a PDF file, use the PDF-based Print template (see "Creating a
Print template with a Wizard" on page 277). To use a PDF file as background image for
an existing section, see "Using a PDF file as background image" on page 288.
When a Print template is created, the following happens:
Page 281
l
l
The Print context is created and one Print section is added to it. You can see this on the
Resources pane: expand the Contexts folder, and then expand the Print folder.
The Print context can contain multiple sections: a covering letter and a policy, for
example, or one section that is meant to be attached to an email as a PDF file and
another one that is going to be printed out on paper. Only one Print section is added to it
at the beginning, but you can add as many print sections as you need; see "Print context"
on the previous page.
See "Print sections" on page 284 to learn how to fill a Print section.
One Master Page is added to the template, as can be seen on the Resources pane, in
the Master Page folder.
In Print sections, there are often elements that need to be repeated across pages, like
headers, footers and logos. In addition, some elements should appear on each first page,
or only on pages in between the first and the last page, or only on the last page.
Examples are a different header on the first page, and a tear-off slip that should show up
on the last page.
This is what Master Pages are used for. Master Pages can only be used in the Print
context.
See "Master Pages" on page 299.
Initially, the (empty) master page that has been created with the Print context will be
applied to all pages in the Print section, but more Master Pages can be added and
applied to different pages.
l
l
One Media is added to the template, as is visible on the Resources pane, in the Media
folder. This folder can hold the company's stationery in the form of PDF files. When
applied to a page in a Print section, Media can help prevent the contents of a Print section
from colliding with the contents of the stationery. See "Media" on page 302 to learn how to
add Media and, optionally, print them.
Initially, the (empty) media that has been created with the Print context, is applied to all
pages in the Print section. You can add more Media and apply them each to different
pages.
One Stylesheet, named context_print_styles.css, is added to the template, as you can
see on the Resources pane, in the Stylesheets folder. This stylesheet is meant to be
used for styles that are only applied to elements in the Print context. See also "Styling
templates with CSS files" on page 454.
Page 282
Print settings in the Print context and sections
The following settings in the Print context and Print sections have an impact on how the Print
context is printed.
Arranging and selecting sections
The Print context can contain one or more Print sections. When generating output from the Print
context, each of the Print sections is added to the output document, one after the other in
sequence, for each record. The sections are added to the output in the order in which they
appear on the Resources pane. This order can be changed; see "Print sections" on the facing
page.
It is also possible to exclude sections from the output, or to include a section only on a certain
condition that depends on a value in the data. This can be done using a Control Script; see
"Control Scripts" on page 532.
Printing on both sides
To print a Print section on both sides of the paper, that Print section needs to have the Duplex
printing option to be enabled; see "Enabling double-sided printing" on page 290. This setting
can not be changed in a Job Creation Preset or an Output Creation Preset.
Note
Your printer must support duplex for this option to work.
Setting the binding style for the Print context
The Print context , as well as each of the Print sections, can have its own Finishing settings. In
printing, Finishing is the way pages are bound together after they have been printed. Which
binding styles can be applied depends on the type of printer that you are using.
To set the binding style of the Print context:
1. On the Resources pane, expand the Contexts folder, and right-click the Print context.
2. Click Properties.
3. Choose a Binding style and, if applicable, the number of holes.
Page 283
To set the binding style of a Print section, see "Setting the binding style for a Print section" on
page 290.
Overriding binding styles in a job creation preset
A Job Creation Preset can override the binding styles set for the Print sections and for the Print
context as a whole. To bind output in another way than defined in the template’s settings:
1. Create a Job Creation Preset that overrides the settings of one or more sections: select
File > Presets and see "Job Creation Presets" on page 701 for more details.
2. Select that Job Creation Preset in the Print wizard; see "Generating Print output" on
page 801.
Setting the bleed
The bleed is the printable space around a page. It can be used on some printers to ensure that
no unprinted edges occur in the final trimmed document. The bleed is one of the settings for a
section. See "Page settings: size, margins and bleed" on page 292.
Print sections
Print templates, also called Print sections, are part of the Print context. They are meant to be
printed to a printer or printer stream, or to a PDF file (see "Generating Print output" on
page 801).
The Print context can also be added to Email output as a PDF attachment; see "Generating
Email output" on page 815. When generating output from the Print context, each of the Print
sections is added to the output document, one after the other in sequence, for each record.
Pages
Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally
limited by their size and margins. If the content of a section doesn't fit on one page, the overflow
goes to the next page. This happens automatically, based on the section's page size and
margins; see "Page settings: size, margins and bleed" on page 292.
Although generally the same content elements can be used in all three contexts (see "Content
elements" on page 373), the specific characteristics of pages make it possible to use special
elements, such as page numbers; see "Page numbers" on page 294.
See "Pages" on page 291 for an overview of settings and elements that are specific for pages.
Page 284
Using headers, footers, tear-offs and repeated elements
In Print sections, there are often elements that need to be repeated across pages, like headers,
footers and logos. In addition, some elements should appear on each first page, or only on
pages in between the first and the last page, or only on the last page. Examples are a different
header on the first page, and a tear-off slip that should show up on the last page.
This is what Master Pages are used for. Master Pages can only be used in the Print context.
See "Master Pages" on page 299 for an explanation of how to fill them and how to apply them
to different pages.
Using stationery (Media)
When the output of a Print context is meant to be printed on paper that already has graphical
and text elements on it (called stationery, or preprinted sheets), you can add a copy of this
media, in the form of a PDF file, to the Media folder.
Media can be applied to pages in a Print section, to make them appear as a background to
those pages. This ensures that elements added to the Print context will correspond to their
correct location on the preprinted media.
Note
When both Media and a Master Page are used on a certain page, they will both be
displayed on the Preview tab of the workspace, the Master Page being 'in front' of the
Media and the Print section on top. To open the Preview tab, click it at the bottom of the
Workspace or select View > Preview View on the menu.
See "Media" on page 302 for a further explanation about how to add Media and how to apply
them to different pages.
Note: The Media will not be printed, unless this is specifically requested through the printer
settings; see "Generating Print output" on page 801.
Adding a Print section
The Print context can contain multiple sections: a covering letter and a policy, for example, or
one section that is meant to be attached to an email as a PDF file and another one that is meant
Page 285
to be printed out on paper. When a Print template is created (see "Creating a Print template
with a Wizard" on page 277 and "Print context" on page 281), only one Print section is added to
it, but you can add as many print sections as you need.
To add a section to a context:
l
On the Resources pane, expand the Contexts folder, right-click the Print context , and
then click New section.
The first Master Page (see "Master Pages" on page 299) and Media (see "Media" on page 302)
will automatically be applied to all pages in the new section, but this can be changed, see
"Applying a Master Page to a page in a Print section" on page 301 and "Applying Media to a
page in a Print section" on page 305.
Tip
Editing PDF files in the Designer is not possible, but when they're used as a section's
background, you can add text and other elements, such as a barcode, to them. To create
a new Print template from a PDF file, use the PDF-based Print template (see "Creating a
Print template with a Wizard" on page 277). To use a PDF file as background image for
an existing section, see "Using a PDF file as background image" on page 288.
Note
Via a Control Script, sections can be added to a Print context dynamically; see "Control Scripts" on
page 532.
Deleting a Print section
To delete a Print section:
l
On the Resources pane, expand the Contexts folder, expand the Print context, rightclick the name of the section, and then click Delete.
Page 286
Warning
No backup files are maintained in the template. The only way to recover a deleted
section, is to click Undo on the Edit menu, until the deleted section is restored. After
closing and reopening the template it is no longer possible to restore the deleted context
this way.
To prevent losing any work, it is recommended to configure the auto-save and autobackup functions in the preferences (see "Saving Preferences" on page 587).
Arranging Print sections
When generating output from the Print context, each of the Print sections is added to the output
document, one after the other in sequence, for each record. The sections are added to the
output in the order in which they appear on the Resources pane, so changing the order of the
sections in the Print context changes the order in which they are outputted to the final
document.
To rearrange sections in a context:
l
l
On the Resources pane, expand the Print context and drag and drop sections to change
the order they are in.
Alternatively, on the Resources pane, right-click a section in the Print context and click
Arrange. In the Arrange Sections dialog you can change the order of the sections by
clicking the name of a section and moving it using the Up and Down buttons.
Styling and formatting a Print section
The contents of a Print section can be formatted directly, or styled with Cascading Style Sheets
(CSS). See "Styling and formatting" on page 453.
In order for a style sheet to be applied to a specific section, it needs to be included in that
section. There are two ways to do this.
Drag & drop a style sheet
1. Click and hold the mouse button on the style sheet on the Resources pane.
2. Move the mouse cursor within the Resources pane to the section to which the style sheet
Page 287
should be applied.
3. Release the mouse button.
Using the Includes dialog
1. On the Resources pane, right-click the section, then click Includes.
2. Choose which CSS files should be applied to this section. You can also change the order
in which the CSS files are read. This can have an effect on which CSS rule is applied in
the end.
Using a PDF file as background image
In the Print context, a PDF file can be used as a section's background. It is different from the
Media in that the section considers the PDF to be content, so the number of pages in the
section will be the same as the number of pages taken from the PDF file.
With this feature it is possible to create a Print template from an arbitrary PDF file or from a PDF
file provided by the DataMapper. Of course, the PDF file itself can't be edited in a Designer
template, but when it is used as a section's background, text and other elements, such as a
barcode, can be added to it.
To use a PDF file as background image:
1. On the Resources pane, expand the Print context, right-click the print section and click
Background.
2. Click the downward pointing arrow after Image and select either From Datamapper
input or From PDF resource.
From Datamapper input uses the active Data Mapping Configuration to retrieve the PDF
file that was used as input file, or another type of input file, converted to a PDF file. With
this option you don't need to make any other settings; click OK to close the dialog.
3. For a PDF resource, you have to specify where it is located. Click the Select Image
button.
Click Resources, Disk or Url, depending on where the image is located.
l
l
Resources lists the images that are present in the Images folder on the Resources
pane.
Disk lets you choose an image file that resides in a folder on a hard drive that is
accessible from your computer. Click the Browse button to select an image.
As an alternative it is possible to enter the path manually. The complete syntax
Page 288
is: file:///. Note: if the host is "localhost", it can be omitted, resulting
in file:///, for example: file:///c:/resources/images/image.jpg.
Check the option Save with template to insert the image into the Images folder on
the Resources pane.
l
Url allows you to choose an image from a specific web address. Select the protocol
(http or https), and then enter the web address (for example,
http://www.mysite.com/images/image.jpg).
Note
It is not possible to use a remotely stored PDF file as a section's background,
because the number of pages in a PDF file can not be determined via the http
and http protocols. Therefor, with an external image, the option Save with
template is always checked.
4. Select the PDF's position:
l
Fit to page stretches the PDF to fit the page size.
l
Centered centers the PDF on the page, vertically and horizontally.
l
Absolute places the PDF at a specific location on the page. Use the Top field to
specify the distance between the top side of the page and the top side of the PDF,
and the Left field to specify the distance between the left side of the page and the
left side of the PDF.
5. Optionally, if the PDF has more than one page, you can set the range of pages that
should be used.
Note
The number of pages in the Print section is automatically adjusted to the number of
pages in the PDF file that are being used as the section's background image.
6. Finally, click OK.
Page 289
Note
To set the background of a section in script, you need a Control Script; see "Control Script API" on
page 782.
Setting the binding style for a Print section
In printing, Finishing is the binding style, or the way pages are bound together. Each Print
section can have its own Finishing settings, as well as the Print context as a whole; see
"Setting the binding style for the Print context" on page 283.
To set the binding style of a Print section:
1. On the Resources pane, expand the Contexts folder, expand the Print context and rightclick the Print section.
2. Click Finishing.
3. Choose a Binding style and, if applicable, the number of holes.
To set the binding style of the Print context, see "Setting the binding style for the Print context"
on page 283.
Overriding binding styles in a job creation preset
A Job Creation Preset can override the binding styles set for the Print sections and for the Print
context as a whole. To bind output in another way than defined in the template’s settings:
1. Create a Job Creation Preset that overrides the settings of one or more sections: select
File > Presets and see "Job Creation Presets" on page 701 for more details.
2. Select that Job Creation Preset in the Print wizard; see "Generating Print output" on
page 801.
Enabling double-sided printing
To print a Print section on both sides of the paper, that Print section needs to have the Duplex
printing option to be enabled. This is an option in the Sheet Configuration dialog. (See "Sheet
Configuration dialog" on page 606.)
Page 290
Note
Your printer must support duplex for this option to work.
To enable duplex printing:
1. On the Resources pane, expand the Print context, right-click the print section and click
Sheet configuration.
2. Check Duplex to enable content to be printed on the back of each sheet.
3. When duplex printing is enabled, further options become available.
l
l
l
Check Tumble to duplex pages as in a calendar.
Check Facing pages to have the side margins switched alternately, so that after
printing and binding the pages, they look like in a magazine or book. See "Pages"
below to find out how to set a left and right margin on a page.
If an odd page count is generated, the last page (which is a duplex backside) has
only the master page. To suppress the master page on this last page and exclude
this page from page counting, check the option Omit Master Page Back in case of
an empty back page.
Pages
Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally
limited by their size and margins. If the content of a section doesn't fit on one page, the overflow
goes to the next page. This happens automatically, based on the section's page size and
margins; see "Page settings: size, margins and bleed" on the facing page.
Although generally the same content elements can be used in all three contexts (see "Content
elements" on page 373), the specific characteristics of pages make it possible to use special
elements, such as page numbers; see "Page numbers" on page 294.
The widow/orphan setting lets you control how many lines of a paragraph stick together, when
content has to move to another page; see "Preventing widows and orphans" on page 296. You
can also avoid or force a page break before or after an entire element, see "Page breaks" on
page 297.
Page 291
Each page in a print section has a natural position: it is the first page, the last page, a 'middle'
page (a page between the first and the last page) or a single page. For each of those positions,
a different Master Page and Media can be set. A Master Page functions as a page's
background, with for example a header and footer. A Media represents preprinted paper that a
page can be printed on. See "Master Pages" on page 299 and "Media" on page 302.
Page specific content elements
The specific characteristics of pages make it possible to use these special elements:
l
l
l
Page numbers can only be used in a Print context. See "Page numbers" on page 294 to
learn how to add and change them.
Conditional content and dynamic tables, when used in a Print section, may or may not
leave an empty space at the bottom of the last page. To fill that space, if there is any, an
image or advert can be used as a whitespace element; see "Whitespace elements:
using optional space at the end of the last page" on the next page.
Dynamic tables can be used in all contexts, but transport lines are only useful in a Print
context; see "Dynamic table" on page 510.
Positioning and aligning elements
Sometimes, in a Print template, you don't want content to move up or down with the text flow.
To prevent that, put that content in a Positioned Box. See "Content elements" on page 373.
When it comes to positioning elements on a page, Guides can be useful, as well as Tables.
See "How to position elements" on page 462.
Page settings: size, margins and bleed
On paper, whether it is real or virtual, content is naturally limited by the page size and margins.
These, as well as the bleed, are set per Print section, as follows:
l
On the Resources pane, right-click a section in the Print context and click Properties.
For the page size, click the drop-down to select a page size from a list of common paper sizes.
Changing the width or height automatically sets the page size to Custom.
Page 292
Margins define where your text flow will go. Static elements can go everywhere on a page, that
is to say, within the printable space on a page that depends on the printer.
The bleed is the printable space around a page. It can be used on some printers to ensure that
no unprinted edges occur in the final trimmed document. Note: Printers that can’t print a bleed,
will misinterpret this setting. Set the bleed to zero to avoid this.
Tip
By default, measurements settings are in inches (in). You could also type measures in
centimeters (add 'cm' to the measurement, for example: 20cm) or in millimeters (for
example: 150mm).
To change the default unit for measurement settings to centimeters or millimeters: on the
Window menu, click Preferences, click Print, and then click Measurements.
Whitespace elements: using optional space at the end of the last page
Print sections with conditional content and dynamic tables (see "Personalizing content" on
page 485) can have a variable amount of space at the bottom of the last page. It is useful to fill
the empty space at the bottom with transpromotional material, but of course you don’t want
extra pages created just for promotional data. 'Whitespace elements' are elements that will only
appear on the page if there is enough space for them.
To convert an element into a whitespace element:
1. Import the promotional image or snippet; see "Images" on page 440 and "Snippets" on
page 451.
2. Insert the promotional image or snippet in the content.
Note
l
Only a top-level element (for example, a paragraph that is not inside a table or
div) can function as a whitespace element.
Page 293
l
Do not place the promotional image or snippet inside an absolute positioned
box. Whitespacing only works for elements that are part of the text flow, not for
absolute-positioned boxes.
3. Select the image or the element that holds the promotional content: click it, or use the
breadcrumbs, or select it on the Outline tab; see "Selecting an element" on page 377.
4. On the Attributes pane, check the option Whitespace element.
5. (Optional.) Add extra space at the top of the element: on the menu Format, click the
option relevant to the selected element (Image for an image, Paragraph for a paragraph,
etc.) and adjust the spacing (padding and/or margins).
Do not add an empty paragraph to provide space between the whitespace element and
the variable content. The extra paragraph would be considered content and could end up
on a separate page, together with the whitespace element.
Page numbers
Inserting page numbers
Page numbers can be added to a Print section, but they are usually added to a Master Page,
because headers and footers are designed on Master Pages; see also: "Master Pages" on
page 299.
To insert a page number, select Insert > Special character > Markers on the menu, and then
click one of the options to decide with what kind of page number the marker will be replaced:
l
l
l
l
Page number: The current page number in the document. If a page is empty or does not
display a page number, it is still added to the page count.
Page count: The total number of pages in the document, including pages with no
contents or without a page number.
Content page number: The current page number in the document, counting only pages
with contents that are supplied by the Print section. A page that has a Master Page (as set
in the Sheet Configuration dialog, see "Applying a Master Page to a page in a Print
section" on page 301) but no contents, is not included in the Content page count.
Content page count: This is the total number of pages in the current document that have
contents, supplied by the Print section. A page that has a Master Page but no contents, is
not included in the Content page count.
Page 294
l
l
Sheet number: The current sheet number in the document. A sheet is a physical piece of
paper, with two sides (or pages). This is equivalent to half the page number, for example if
there are 10 pages, there will be 5 sheets.
Sheet count: This marker is replaced by the total number of sheets in the document,
whether or not they have contents.
Note
When a marker is inserted, a class is added to the element in which the marker is inserted. Do not
delete that class. It enables the software to quickly find and replace the marker when generating
output. The respective classes are: pagenumber, pagecount, contentpagenumber,
contentpagecount, sheetnumber, and sheetcount.
Creating a table of contents
A table of contents can only be created in a template script. The script should make use of the
pageRef() function. For an example, see "pageRef()" on page 768. If you don't know how to
write a script, see "Writing your own scripts" on page 515.
Configuring page numbers
By default the page numbers are Arabic numerals (1, 2, 3, etc.) without leading zeros nor prefix,
and page numbering starts with page 1 for each section. But this can be changed. To do that:
1. On the Resources pane, right-click a section in the Print context and click Numbering.
2. Uncheck Restart Numbering if you want the page numbers to get consecutive page
numbers, instead of restarting the page numbering with this section.
Note
Even if a section is disabled, so it doesn't produce any output, this setting is still
taken into account for the other sections. This means that if Restart Numbering is
checked on a disabled section, the page numbering will be restarted on the next
section.
Disabling a section can only be done in a Control Script (see "Control Scripts" on
page 532). Control Scripts can also change where page numbers restart.
Page 295
3. Use the Format drop-down to select uppercase or lowercase letters or Roman numerals
instead of Arabic numerals.
4. In Leading Zeros, type zeros to indicate how many digits the page numbers should have.
Any page number that has fewer digits will be preceded by leading zeros.
5. Type the Number prefix. Optionally, check Add Prefix to Page Counts, to add the prefix
to the total number of pages, too.
6. Close the dialog.
Preventing widows and orphans
Widows and orphans are lines at the beginning or at the end of a paragraph respectively,
dangling at the bottom or at the top of a page, separated from the rest of the paragraph.
By default, to prevent orphans and widows, lines are moved to the next page as soon as two
lines get separated from the rest of the paragraph.
This setting can be changed for the entire Print context, per paragraph and in tables.
Note
Widows and orphans are ignored if the page-break-inside property of the paragraph is
set to avoid.
In the entire Print context
To prevent widows and orphans in the entire Print context:
1. On the menu, select Edit > Stylesheets.
2. Select the Print context.
3. Click New (or, when there are already CSS rules for paragraphs, click the selector p and
click Edit).
4. Click Format.
5. After Widows and Orphans, type the number of lines that should be considered a widow
or orphan (this amounts to the minimum number of lines that may be separated from a
paragraph, minus one).
Alternatively, manually set the set the widows and orphans properties in a style sheet:
Page 296
1. Open the style sheet for the Print context: on the Resources pane, expand the Styles
folder and double-click context_print_styles.css.
2. Add a CSS rule, like the following:
p { widows: 4; orphans: 3 }
Per paragraph
To change the widow or orphan setting for one paragraph only:
1. Select the paragraph, using the breadcrumbs or the Outline pane (next to the Resources
pane).
2. Select Format > Paragraph, on the menu.
3. After Widows and Orphans, type the number of lines to be considered a widow or orphan
(this amounts to the minimum number of lines that may be separated from a paragraph,
minus one).
In tables
The CSS properties widows and orphans can be used in tables. They are not available in the
Table Formatting dialog, however, so they must be added manually, either directly in the style
attribute of the element (on the Source tab in the Workspace) or in a style sheet rule, as
follows:
1. On the menu, select Edit > Stylesheets.
2. Select the Print context.
3. Click New (or, when there are already CSS rules for tables, click the selector table and
click Edit).
4. Click the Advanced button.
5. Add a rule for widows and/or orphans, typing the name of the CSS property in the left
column and the value in the right column.
6. Close the dialogs.
Page breaks
A page break occurs automatically when the contents of a section don't fit on one page.
Page 297
Inserting a page break
To insert a page break before or after a certain element, set the page-break-before property or
the page-break-after property of that element (a paragraph for example; see also "Styling text
and paragraphs" on page 464):
1. Select the element (see "Selecting an element" on page 377).
2. On the Format menu select the respective element to open the Formatting dialog.
3. In the Breaks group, set the before or after property.
l
l
Before: Sets whether a page break should occur before the element. This is
equivalent to the page-break-before property in CSS; see CSS page-break-before
property for an explanation of the available options.
After: Sets whether a page break should occur after the element. Equivalent to the
page-break-after property in CSS; see CSS page-break-after property for an
explanation of the available options.
Click the button Advanced to add CSS properties and values to the inline style tag directly.
Note
You cannot use these properties on an empty or on absolutely positioned elements.
Preventing a page break
To prevent a page break inside a certain element, set the page-break-inside property of that
element to avoid:
l
Select the element (see "Selecting an element" on page 377).
l
On the Format menu, select the respective element to open the Formatting dialog.
l
In the Breaks group, set the inside property to avoid, to prevent a page break inside the
element. This is equivalent to the page-break-inside property in CSS; see CSS pagebreak-inside property for an explanation of all available options.
Adding blank pages to a section
How to add a blank page to a section is described in a how-to: Create blank page on field
value.
Page 298
Master Pages
In Print sections, there are often elements that need to be repeated across pages, like headers,
footers and logos. In addition, some elements should appear only on specific pages, such as
only the first page, or the last page, or only on pages in-between. Examples are a different
header on the first page, and a tear-off slip that shows up on the last page.
This is what Master Pages are used for. Master Pages can only be used in the Print context
(see "Print context" on page 281).
Master Pages resemble Print sections, and they are edited in much the same way (see "Editing
a Master Page" on the facing page) but they contain a single page and do not have any text
flow. Only one Master Page can be applied per page in printed output. Then a Print template is
created, one master page is added to it automatically. You can add more Master Pages; see
"Adding a Master Page" below. Initially, the original Master Page will be applied to all pages,
but different Master Pages can be applied to different pages; see "Applying a Master Page to a
page in a Print section" on page 301.
Examples
This how-to demonstrates the use of Master Pages to show terms and conditions on the back of
the first page of a Print section only:
l
Showing a Terms and Conditions on the back of the first page only.
How to use Master Pages to add a tear-off slip to the first page of an invoice is explained in the
following how-to :
l
A tear-off section on the first page of an invoice.
Adding a Master Page
When a Print template is created, one master page is added to it automatically. Adding more
Master Pages can be done as follows:
l
On the Resources pane, right-click the Master pages folder and click New Master Page.
l
Type a name for the master page.
l
Optionally, set the margin for the header and footer. See "Master Pages" above.
l
Click OK.
Page 299
Initially, the master page that has been created together with the Print context will be applied to
all pages in the Print section. After adding more Master Pages, different Master Pages can be
applied to different pages; see "Applying a Master Page to a page in a Print section" on the
next page.
Editing a Master Page
Master Pages are edited just like sections, in the workspace. To open a Master Page, expand
the Master pages folder on the Resources pane, and double-click the Master Page to open it.
A Master Page can contain text, images and other elements (see "Content elements" on
page 373), including variable data and dynamic images (see "Personalizing content" on
page 485). All elements on a Master Page should have an absolute position or be inside an
element that has an absolute position. It is good practice to position elements on a Master Page
by placing them in a Positioned Box (see "Content elements" on page 373).
Keep in mind that a Master Page always remains a single page. Its content cannot overflow to a
next page. Content that doesn't fit, will not be displayed.
Note
Editing the Master Page is optional. One Master Page must always exist in a Print
template, but if you don't need it, you can leave it empty.
Adding a header and footer
Headers and footers are not designed as part of the contents of a Print section, but as part of a
Master Page, which is then applied to a page in a print section.
To create a header and footer:
1. First insert elements that form the header or footer, such as the company logo and
address, on the Master Page; see "Editing a Master Page" above.
2. Next, define the margins for the header and footer. The margins for a header and footer
are set in the Master Page properties. This does not change the content placement within
the Master Page itself; in Master Pages, elements can go everywhere on the page.
Instead, the header and footer of the Master Page limit the text flow on pages in the Print
sections to which this Master Page is applied. Pages in a Print section that use this
Page 300
Master Page cannot display content in the space that is reserved by the Master Page for
the header and footer, so that content in the Print section does not collide with the content
of the header and footer. To set a margin for the header and/or footer:
1. On the Resources pane, expand the Master pages folder, right-click the master
page, and click Properties.
2. Fill out the height of the header and/or the footer. The contents of a print section will
not appear in the space reserved for the header and/or footer on the corresponding
master page.
3. Finally, apply the master page to a specific page in a print section. See "Applying a
Master Page to a page in a Print section" below.
Applying a Master Page to a page in a Print section
Every page in a print section has a natural position: it can be the first page, the last page, one of
the pages in between (a 'middle page'), or a single page. For each of those positions, you can
set a different Master Page and Media (see "Media" on the facing page). It can even have two
master pages, if printing is done on both sides (called duplex printing).
To apply Master Pages to specific page positions in a Print section:
1. On the Resources pane, expand the Print context; right-click the Print section, and click
Sheet configuration.
2. Optionally, check Duplex to enable content to be printed on the back of each sheet. Your
printer must support duplex for this option to work. If Duplex is enabled, you can also
check Tumble to duplex pages as in a calendar, and Facing pages to have the margins
of the section switch alternately, so that pages are printed as if in a magazine or book.
3. If the option Same for all positions is checked, the same Master Page will be applied to
every page in the print section (and to both the front and the back side of the page if
duplex printing is enabled). Uncheck this option.
4. Decide which Master Page should be linked to which sheet (position): click the downward
pointing arrow after Master Page Front and select a Master Page. If Duplex is enabled,
you can also select a Master Page for the back of the sheet and consequently, check
Omit Master Page Back in case of an empty back page to omit the specified Master
Page on the last backside of a section if that page is empty and to skip that page from the
page count.
5. Optionally, decide which Media should be linked to each sheet.
6. Click OK to save the settings and close the dialog.
Page 301
Deleting a Master Page
To delete a Master Page, expand the Master pages folder on the Resources pane, right-click
the master page, and click Delete.
Note that one Master Page as well as one Media must always exist in a Print template. Just
leave it empty if you don't need it.
Media
When the output of a Print context is meant to be printed on paper that already has graphical
and text elements on it (called stationery, or preprinted sheets), you can add a copy of this
media, in the form of a PDF file, to the Media folder.
Media can be applied to pages in a Print section, to make them appear as a background to
those pages. This ensures that elements added to the Print context will correspond to their
correct location on the preprinted media.
For further explanation about how to apply Media to different pages, see "Applying Media to a
page in a Print section" on page 305.
Media will not be printed, unless you want them to; see below.
Per Media, a front and back can be specified and you can specify on what kind of paper the
output is meant to be printed on. This includes paper weight, quality, coating and finishing; see
"Adding Media" below.
Adding Media
To add a Media, right-click the Media folder on the Resources pane and select New Media.
The new Media is of course empty. You can specify two PDF files for the Media: one for the
front, and, optionally, another for the back.
Specifying and positioning Media
Specifying a PDF for the front: the fast way
To quickly select a PDF file for the front of a Media, import the PDF file by dragging it from the
Windows Explorer to the Images folder on the Resources pane.
Page 302
Then drag that the PDF file from the Images folder and drop it on one of the Media in the Media
folder. With this method you can not set any options.
To be able to specify a PDF file for both the front and the back of the Media, and to specify a
position for the Media's PDF files, you have edit the properties of the Media.
Setting Media properties
Media have a number of properties that you can set, as described below. What you cannot set
are a Media's page size and margins. The page size and margins are derived from the section
to which the Media is applied.
You can, however, specify a PDF file (or any other type of image file) for both the front and the
back of the Media, and specify how the virtual stationery should be positioned on the page.
This is done as follows:
1. On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Virtual Stationery.
2. Click the Select Image button to select a PDF image file.
3. Click Resources, Disk or Url, depending on where the image is located.
l
l
l
Resources lists the PDF files that are present in the Images folder on the
Resources pane.
Disk lets you choose an image file that resides in a folder on a hard drive that is
accessible from your computer. Click the Browse button to select an image.
As an alternative it is possible to enter the path manually. The complete syntax
is: file://
/. Note: if the host is "localhost", it can be omitted, resulting
in file:///, for example: file:///c:/resources/images/image.jpg.
Check the option Save with template to insert the image into the Images folder on
the Resources pane.
Url allows you to choose an image from a specific web address. Select the protocol
(http or https), and then enter the web address (for example,
http://www.mysite.com/images/image.jpg).
Note
It is not possible to use a remotely stored PDF file as virtual stationery,
Page 303
because the number of pages in a PDF file can not be determined via the http
and http protocols. Therefor, with an external image, the option Save with
template is always checked.
4. Select a PDF file.
5. If the PDF file consists of more than one page, select the desired page.
6. Click Finish.
7. For each of the PDF files, select a position:
l
Fit to page stretches the PDF to fit the page size.
l
Centered centers the PDF on the page, vertically and horizontally.
l
Absolute places the PDF at a specific location on the page. Use the Top field to
specify the distance between the top side of the page and the top side of the PDF,
and the Left field to specify the distance between the left side of the page and the
left side of the PDF.
8. Finally, click OK.
Setting the paper's characteristics
To set a Media's paper characteristics:
1. On the Resources pane, expand the Contexts folder, expand the Media folder, and
right-click the Media. Click Characteristics.
2. Specify the paper's characteristics:
l
l
l
l
l
l
Media Type: The type of paper, such as Plain, Continuous, Envelope, Labels,
Stationery, etc.
Weight: The intended weight of the media in grammage (g/m2).
Front Coating: The pre-process coating applied to the front surface of the media,
such as Glossy, High Gloss, Matte, Satin, etc.
Back Coating: The pre-process coating applied to the back surface of the media.
Texture: The intended texture of the media, such as Antique, Calenared, Linen,
Stipple or Vellum.
Grade: The intended grade of the media, such as Gloss-coated paper, Uncoated
white paper, etc.
Page 304
l
Hole Name: A predefined hole pattern that specifies the pre-punched holes in the
media, such as R2-generic, R2m-MIB, R4i-US, etc.
3. Click OK.
Rename Media
To rename Media:
l
l
On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Rename. Type the new name and click OK.
Alternatively, on the Resources pane, expand the Contexts folder, expand the Media
folder, right-click the Media and click Properties. Type the new name in the Name field
and click OK.
Applying Media to a page in a Print section
Every page in a print section has a natural position: it can be the first page, the last page, one of
the pages in between (a 'middle page'), or a single page. For each of those positions, you can
set different Media.
To apply Media to specific page positions in a Print section:
1. On the Resources pane, expand the Print context; right-click the Print section, and click
Sheet configuration.
2. Optionally, check Duplex to enable content to be printed on the back of each sheet. Your
printer must support duplex for this option to work. If Duplex is enabled, you can also
check Tumble to duplex pages as in a calendar, and Facing pages to have the margins
of the section switch alternately, so that pages are printed as if in a magazine or book.
3. If the option Same for all positions is checked, the same Media will be applied to every
page in the print section. Uncheck this option.
4. Decide which Media should be linked to each sheet position: click the downward pointing
arrow after Media and select a Media.
5. Optionally, decide which Master Page should be linked to each sheet; see "Master
Pages" on page 299.
Page 305
Note
When both Media and a Master Page are used on a certain page, they will both be
displayed on the Preview tab of the workspace, the Master Page being 'in front' of the
Media and the Print section on top. To open the Preview tab, click it at the bottom of the
Workspace or select View > Preview View on the menu.
Dynamically changing the Media
In addition to applying Media to sheets via the settings, it is possible to change Media
dynamically, based on a value in a data field, in a script. The script has already been made;
you only have to change the name of the Media and the section in the script, and write the
condition on which the Media has to be replaced.
1. On the Resources pane, expand the Contexts folder, expand the Print context, rightclick the print section and click Sheet configuration.
2. Decide which pages should have dynamically switching media: every first page in the
Print section, every last page, one of the pages in between (a 'middle page'), or a single
page. (Uncheck the option Same for all positions, to see all page positions.)
3. In the area for the respective sheet position, click the Edit script button next to Media.
The Script Wizard appears with a standard script:
results.attr("content","Media 1");
Media 1 will have been replaced with the name of the media selected for the chosen
sheet position.
The field Selector in the Script Wizard contains the name of the section and the sheet
position that you have chosen.
4. Change the script so that on a certain condition, another media will be selected for the
content. For instance:
if(record.fields.GENDER === 'M') {
results.attr("content","Media 2");
}
This script changes the media to Media 2 for male customers.
See "Writing your own scripts" on page 515 if you are not familiar with how scripts are
written.
5. Click Apply, open the tab Preview and browse through the records to see if the script
Page 306
functions as expected.
6. When you click OK, the script will be added to the Scripts pane.
Printing virtual stationery
Media are not printed, unless you want them to. Printing the virtual stationery is one of the
settings in a Job Creation Preset. To have the virtual stationery printed as part of the Print
output:
1. Create a job creation preset that indicates that Media has to be printed: select File >
Presets and see "Job Creation Presets" on page 701 for more details.
2. Select that job creation preset in the Print Wizard; see "Generating Print output" on
page 801.
Email
With the Designer you can create one or more Email templates and merge the template with a
data set to generate personalized emails.
The Email context is the folder in the Designer that can contain one or more Email templates,
also called Email sections. The HTML generated by this context is meant to be compatible
with as many clients and as many devices as possible.
Email template
It is strongly recommended to start creating an Email template with a Wizard; see "Creating an
Email template with a Wizard" on page 311. Designing HTML email that displays properly on a
variety of devices and screen sizes is challenging. Building an email is not like building for the
web. While web browsers comply with standards (to a significant extent), email clients do not.
Different email clients interpret the same HTML and CSS styles in totally different ways.
When an Email template is created, either with a Wizard or by adding an Email context to an
existing template (see "Adding a context" on page 270), the Email context folder is created
along with other files that are specific to an Email context; see "Email context" on page 315.
Only one Email section is created at the start, but you can add as many Email sections as you
need; see "Email templates" on page 317. However, when the Designer merges a data set to
generate output from the Email context, it can merge only one of the templates with each
record; see "Generating Email output" on page 815.
Page 307
Email templates are personalized just like any other template; see "Variable Data" on
page 497.
Sending email
When the template is ready, you can change the email settings (see "Email header settings" on
page 320) and send the email directly from the Designer or via Workflow. To test a template,
you can send a test email first.
Output, generated from an Email template, can have the following attachments:
l
The contents of the Print context, in the form of a single PDF attachment.
l
The output of the Web context, as an integral HTML file.
l
Other files, an image or a PDF leaflet for example.
Attaching the Print context and/or the Web context is one of the options in the Send (Test)
Email dialog.
See "Email attachments" on page 819 and "Generating Email output" on page 815.
Designing an Email template
With the Designer you can design Email templates. It is strongly recommended to start creating
an Email template with an Email Template Wizard, because it is challenging to design HTML
email that looks good on all email clients, devices and screen sizes that customers use when
they are reading their email.
This topic explains why designing HTML email design is as challenging as it is, which
solutions are used in the Email Template Wizards and it lists good practices, for example
regarding the use of images in HTML email. It will help you to create the best possible Email
templates in the Designer.
HTML email challenges
Creating HTML email isn't like designing for the Web. That's because email clients aren't like
web browsers. Email clients pass HTML email through a preprocessor to remove anything that
could be dangerous, introduce privacy concerns or cause the email client to behave
unexpectedly. This includes removing javascript, object and embed tags, and unrecognized
tags. Most preprocessors are overly restrictive and remove anything with the slightest potential
to affect the layout of their email client. Next, the HTML has to be rendered so that it is safe to
Page 308
show within the email client. Unfortunately, desktop, webmail, and mobile clients all use
different rendering engines, which support different subsets of HTML and CSS. More often than
not, the result of these operations is that they completely break the HTML email's layout.
Designing HTML email in PlanetPressDesigner
The problem of HTML email is that preprocessing and rendering engines break the HTML
email's layout. HTML tables, however, are mostly left untroubled. As they are supported by
every major email client, they are pretty much the only way to design HTML emails that are
universally supported. That's why Tables are heavily used to position text and images in HTML
email.
Nesting tables (putting tables in table cells) and applying CSS styles to each table cell to make
the email look good on all screen sizes is a precision work that can be a tedious and
demanding. Connect's Designer offers the following tools to make designing HTML email
easier.
Email templates: Slate and others
The most obvious solution offered in the Designer is to use one of the templates provided with
the Designer; see "Creating an Email template with a Wizard" on page 311. The layout of these
templates has been tested and proven to look good in any email client, on any device and
screen size. The Tables in these templates are nested (put inside another table) and they have
no visible borders, so readers won't notice them.
Tip
Click the Edges button on the toolbar to make borders of elements visible on the Design
tab. The borders will not be visible on the Preview tab or in the output.
Emmet
Emmet is a plugin that enables the lightning-fast creation of HTML code though the use of a
simple and effective shortcut language. The Emmet functionality is available in the HTML and
CSS source editors of Connect Designer. Emmet transforms abbreviations for HTML elements
and CSS properties to the respective source code. The expansion of abbreviations is invoked
with the Tab key.
Page 309
In the Source tab of the Workspace, you could for example type div.row. This is the
abbreviation for a element with the class row. On pressing the Tab key, this abbreviation
is transformed to:
To quickly enter a table with the ID 'green', one row, and two cells in that row, type:
table#green>tr>td*2
On pressing the Tab key, this is transformed to:
All standard abbreviations can be found in Emmet's documentation: Abbreviations.
To learn more about Emmet, please see their website: Emmet.io and the Emmet.io
documentation: http://docs.emmet.io/.
Preferences
To change the way Emmet works in the Designer, select Window > Preferences, and in the
Preferences dialog, select Emmet; see "Emmet Preferences" on page 583.
Using CSS files with HTML email
Email clients do not read CSS files and some even remove a