PlanetPress Connect User Guide Planet Press 1.4 Operating Instructions 14 EN
User Manual: Pdf PlanetPress Connect - 1.4 - Operating Instructions User Guide for Objectif Lune PlanetPress Software, Free Instruction Manual
Open the PDF directly: View PDF 
.
Page Count: 606
| Download | |
| Open PDF In Browser | View PDF |
User Guide
Version: 1.4.2
User Guide
Version 1.4.2
Last Revision: 2016-06-30
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-2016. 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. Inc. Objectif Lune Inc. 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. Inc reserves the right to alter the information contained in this documentation
without notice.
Table of Contents
Table of Contents
4
Welcome to PlanetPress Connect 1.4.2
7
Icons used in this guide
8
Setup And Configuration
9
System and Hardware Considerations
9
Installation and Activation
16
Server Settings
37
DataMapper Module
41
Basics
41
Features
41
DataMapper User Interface
92
Defining Boolean Values
166
Defining String Values
166
Building String Values
167
Defining Integer Values
168
Building Integer Values
168
Defining Float Values
169
Page 4
Building Float Values
169
Defining Currency Values
169
Building Currency Values
170
Defining Date Values
170
Defining Object Values
171
The Designer
174
API
174
Basic Steps
218
Features
220
Designer User Interface
452
Mark Position Options
538
Additional Text
543
Additional Images
543
Additional Barcodes
544
Additional OMR Marks
544
Additional Text Settings
546
Additional Image Settings
547
Barcode Options
548
Standard Barcode Settings
548
Page 5
Codabar Settings
550
Code 128 Settings
552
Code 39 Settings
554
Additional Datamatrix Settings
556
Additional EAN 128 Settings
558
Additional EAN 13 Settings
559
Additional EAN 8 Settings
561
Additional Interleave 2 of 5 Settings
563
Additional PDF417 Settings
565
Additional QR Code Settings
567
Additional UPC A Settings
569
Additional UPC E Settings
571
Additional OMR Mark Settings
573
Keystore
578
PDF Signature
580
Copyright Information
601
Legal Notices and Acknowledgements
602
Page 6
Welcome to PlanetPress Connect
1.4.2
Note
In our continuous effort to facilitate your PlanetPress Connect experience, our entire
documentation is being overhauled. Since we are still in the process of restructuring all
this information, expect to see our online help evolve frequently over the next few weeks.
We apologize for any inconvenience, but know we are working hard to improve your
experience as quickly as possible.
Since we are always looking for new ways to make your life easier, we welcome your
questions and comments about our products and documentation. A feedback tool will
soon be at the bottom of each page. In the meantime, shoot us an email at
doc@ca.objectiflune.com.
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.
Page 7
This online documentation covers PlanetPress Connect version 1.4.2.
Icons used in this guide
Icons are used throughout this guide to point your attention to certain information.
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 8
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
l
l
"System and Hardware Considerations" below
"Installation and Activation" on page 16
"Server Settings" on page 37
System and Hardware Considerations
There are a variety of considerations to be aware of. These are documented in the following
pages:
l
l
l
l
l
l
"System Requirements" below
"Environment considerations" on the facing page
"Database Considerations" on page 12
"Network considerations" on page 12
"Language and Encoding considerations" on page 13
"Performance Considerations" on page 13
System Requirements
These are the system requirements for PlanetPress Connect 1.4.2
Operating System (64-bit only)
l
l
l
l
l
l
Microsoft Windows 2008/2008 R2 Server
Microsoft Windows 2012/2012 R2 Server
Microsoft Windows Vista
Microsoft Windows 7
Microsoft Windows 8.1
Microsoft Windows 10
Note
Windows XP, Windows 2003 and older versions of Windows are not supported by
Page 9
PlanetPress Connect.
Minimum Hardware Requirements
l
l
l
l
NTFS Filesystem (FAT32 is not supported)
CPU Intel Core i7-4770 Haswell (4 Core)
8GB RAM (16GB Recommended)
Disk Space: At least 10GB (20GB recommended)
Note
For tips and tricks on performance, see "Performance Considerations" on page 13.
Environment considerations
Virtual Machine Support
PlanetPress Connect supports VMWare Workstation, VMWare Server, VMWare Player,
VMWare ESX, Microsoft Hyper-V and Microsoft Hyper-V/Azure infrastructure environments as
software installed on the Guest operating system. PlanetPress Connect does not officially
support VMotion under ESX at the moment.
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 VMWare (from VMWare, Inc.) and Microsoft virtual machine environments
are supported, other virtual environments (such as Parallels, Xen and others) are not
supported at this time.
Page 10
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
l
l
l
l
l
Click on Start, Run.
Type in services.msc and click OK.
Locate the Windows Search service and double-click on it.
Change the Startup Type to Disable, and click Stop to stop the service.
Try the installation again.
Once completely, you may re-enable the service and start it.
Page 11
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
l
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.
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" above section.
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.
Network considerations
The following should be taken into consideration in regards to network settings and
communications
Page 12
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
l
l
l
l
l
l
l
l
English
French
German
Spanish
Italian
Portuguese
Chinese (Simplified)
Chinese (Traditional)
Japanese.
The default language is English.
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
Page 13
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
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
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
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.
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 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:
Page 14
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 Librairies: 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
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
A physical, non-virtualized server. ESX and 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.
Page 15
l
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 section provides detailed information about the installation and activation of PlanetPress
Connect 1.4.2.
Note
A PDF version of this guide is available for use in offline installations. Click here to
download it.
PlanetPress Connect 1.4.2 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.4.2 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
Make sure your system meets the System requirements.
PlanetPress Version 1.4.2 can be installed under a regular user account with
Administrator privileges.
You must install on an NTFS file system.
Page 16
l
l
l
PlanetPress requires Microsoft .NET Framework 3.5 already be installed on the target
system.
In order to use the automation feature in Version 1.4.2, you need to install PlanetPress
Workflow 8. 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).
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.4.2 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.4.2. 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.4.2
If you are updating manually you must first upgrade to Version 1.1 before installing 1.4.2. If you
attempt go directly from Version 1.0 to Version 1.4.2 the installation will fail.
Page 17
Also see "Users of Connect 1.1" on the previous page for extra information about updating from
that version.
Installing PlanetPress Connect on Machines without Internet Access
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 you must first
ensure that all Windows updates have been installed on the host machine. You then need to
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
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)
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.
Page 18
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.
Selection Confirmation
The next page confirms the installation selections made. Click Next to start the installation
itself.
Page 19
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
l
l
l
a lower case character (a, b, c ... )
an upper case character (A, B, C ...)
a numeric digit (1, 2, 3 ...)
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
l
l
Confirm 'root' Password: Re-enter to confirm the password. Both passwords must
match for installation to continue.
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.
Allow MySQL Server to accept non-local TCP connections: Click to enable external
access to the MySQL server. This is required if MySQL Server will need to be accessed
Page 20
from any other machine. It is also required if MySQL is on a separate machine than
PlanetPress Connect.
Note
The last option may represent a security risk if the machine is open to the internet. It is
recommended to ensure your firewall blocks 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
l
l
l
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
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.
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.
PlanetPress Connect Server Configuration
The Server Configuration page is where the Server component is configured.
l
Run Server as: Defines the machine username and password that thePlanetPress
Connect Server module's service uses. This account should be administrator on the
local machine. Note that the "Server Security Settings" on page 37 dialog can only be
executed from the user specified here.
Page 21
l
l
l
l
Username: The username the service uses to login. If the machine is on a domain,
use the format domain\username.
Password: The password associated with the username.
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.
l
Note that the Product Update Manager can also be called from the “Objectif Lune Update
Client” option in the Start menu.
Page 22
l
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
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.
The file needs to be a properties file with the following line types:
l
l
Comment Lines, starting with # (e.g. # The options to configure an external database)
Key=Value pairs (e.g. install.product.0 = Connect Designer)
For supported keys, please refer to the next paragraph.
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
Page 23
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.
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
l
install.product.0 = Connect Designer
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
l
server.runas.username
server.runas.password
Additionally for the Server Extension, some properties to define the Master Server are required:
Page 24
l
l
l
l
l
server.master.host
server.master.port
server.master.authenticate = true_or_false
server.master.username
server.master.password
Database configuration
If the MySQL Product is part of the installation, the following properties should be defined:
l
l
l
database.type = mysql (required)
database.password (required, needs to match the security rules)
database.port (optional, the default is 3306. The defined port needs to be available.)
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
l
database.host
database.username
Optionally, the "schema" name can be defined (the default is objectiflune):
database.schema
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 25
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.
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
l
l
Open the Start Menu
Click on All Programs, then Objectif Lune, then PlanetPress Connect
Open the PlanetPress Connect Designer [version] shortcut.
Page 26
l
When the application opens, if it has never been activated or the activation has expired,
the Software Activation dialog appears:
l
License Information section:
l
l
l
Licensed Products section:
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
Magic Number: Displays the PlanetPress Connect Magic Number.
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.
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.
Requesting a license
After getting the Magic Number, a license request must be done for bothPlanetPress Connect
and Workflow 8:
Page 27
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 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
l
l
l
l
Open the Start Menu
Click on All Programs, then Objectif Lune, then PlanetPress Connect
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).
Click the Load License File button.
Read the EULA and click I agree option to accept it.
Page 28
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.
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.
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
Configuration section 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.
Page 29
The Importance of User Credentials on Installation and
Running
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.
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
Page 30
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.
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.
Upgrading from PlanetPress Suite 7.6
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”.
Page 31
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.
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
Imaging for PlanetPress Connect is available as an option. It contains:
l
l
l
o
l
l
PlanetPress Fax
PlanetPress Image
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 32
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 33
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 34
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
l
l
l
l
l
l
l
l
l
l
l
l
l
Processes configuration
PlanetPress Suite compiled documents
Service configuration
Access manager configuration
Custom plug-ins
PlanetPress Fax settings
PlanetPress Image settings
PlanetPress Search profiles
Printer activation codes
PlanetPress Capture database
PlanetPress Capture pen licenses
Custom scripts
Content of your virtual drive
PlanetPress Messenger configuration
If you installed PlanetPress Workflow 8 on a different computer, contact support for
Page 35
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:
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
Page 36
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
l
"Server Security Settings" below
"Server Extension Settings" below
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
l
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.
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.
Page 37
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
"Cleanup Service preferences" on page 460
"Server Extension Scheduling Preferences" on page 40 (these are different in the Server
Extension preferences)
l
l
l
Merge Engine Scheduling
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.
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
Page 38
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.
l
l
Once the changes have been made and saved you need to restart the MySQL
services.
Access must be granted to the root user on the IPs from which the Slave server will
connect:
l
l
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 select "Open a command prompt here!).
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)
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:
Page 39
l
l
In the Scheduling Preferences of the Slave, both "Maximum Records" are ignored.
Scheduling is handled by the Master.
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 connection settings for the server
extension (slave) and the main Server module (master).
l
l
l
l
Location of the master server: Enter the location and port of the main 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 OL Connect Server.
Password: Enter the password expected by the OL Connect Server for the above
username.
Note that Maximum records in a small job and Minimum records in a large job:are
note used in Server Extensions. All server scheduling is handled by the Master.
Page 40
DataMapper Module
The DataMapper Module is a tool that helps in the preparation of data for a unified data model.
You can then use that Data Model in the Designer module.
The tool does this through the use of a data mapping workflow consisting of multiple steps
which extract data from each Source Record of a Data Source and places this data in a Data
Model. This Data Model contains all the necessary information for the creation of a template in
the Designer module. (see Data Model for more information)
Basics
Here is the procedure for a Data Mapping configuration that includes the steps required for a
data extraction from a data source:
1. Create a new Data Mapping configuration.
First, you create a new Data Mapping configuration manually from a file or by
automatically using a wizard. In this first step, you select a Data Source. See Creating a
new Data Mapping configuration.
2. Configure settings for the data source.
In this step, you 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.
Here you 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. Save the Data Mapping configuration.
Now it's time to save a copy of a data mapping configuration under the name of your
choice. To learn more, see Saving A Data Mapping configuration.
Features
The DataMapper Module is a tool that extract data and prepares it for use in the Designer
module. The tool does this through the use of a Data Mapping Workflow consisting of multiple
Steps which process and extract data from each Source Record of a Data Source and stores it
in a Record Set.
Page 41
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.
Data Mapping Workflow
The data mapping workflow is a series of Steps inside of a data mapping configuration that
extract the appropriate data from the Source Record and places it into the Record (see Data
Model).
The data mapping workflow always starts with the Preprocessor step and ends with the
Postprocessor step and can contain as many of the different steps available in the
DataMapper.
Data Model
A Data Model is the format into which Records are saved. It is also a file format that can be
exchanged between different parts of the PlanetPress Connect solution.
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.
The first step to do before creating a Data Mapping configuration is to set up Input Data (setting
the delimiters) and Boundaries (setting the trigger) in the Settings pane.
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.
Page 42
From a File
You can create a new data mapping configuration manually under the From a file section. As
opposed to using a wizard, you must configure all settings in the Settings pane of the
DataMapper interface. Please refer to Configuring Settings For The Data Source for more
information.
A CSV File
To create a Data Mapping from a CSV file, use the following steps:
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 section, select CSV.
4. Click the Browse button and open the CSV file you want to work with.
5. Click Finish.
From the File menu
1.
2.
3.
4.
5.
Click the File menu and select New.
Click the Data mapping Configuration drop-down and select Files and then CSV File.
Click Next.
Click the Browse button and open the CSV file you want to work with.
Click Finish.
A MS-Access File
To create a Data Mapping from a Microsoft Access database file, use the following steps:
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 section, select MS Access.
4. Click the Browse button and open the database file you want to work with.
5. Enter the password if needed and click Next.
Page 43
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 Microsoft
Access.
3. Click Next.
4. Click the Browse button and open the database file you want to work with.
5. Enter the password if needed and click Next.
A PDF File
To create a PDF/VT file data mapping configuration, use the following steps:
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 section, select PDF/VT.
4. Click the Browse button and open the PDF/VT file you want to work with.
5. 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 Configuration drop-down and select Files and then
PDF/PS/PCL/AFP File.
3. Click Next.
4. Click the Browse button and open the PDF/VT file you want to work with.
5. Click Finish to close the dialog and open the actual Data Mapping configuration).
Note
PCL and PostScript (PS) files are automatically converted to PDF files before showing that PDF in
the Data Viewer. This happens once when opening the file, but in automation happens for every
file. Depending on the processing power available, this may influence the processing speed.
A Text File
To create a TXT file data mapping configuration, use the following steps:
Page 44
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 section, select Text.
4. Click the Browse button and open the text file you want to work with.
5. Click Finish to close the dialog and open the actual Data Mapping configuration).
From the File menu
1.
2.
3.
4.
5.
Click the File menu and select New
Click the Data mapping Configuration drop-down and select Files and then Text File.
Click Next.
Click the Browse button and open the text file you want to work with.
Click Finish to close the dialog and open the actual Data Mapping configuration).
A XML File
To create a XML File data mapping configuration, use the following steps:
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 section, select XML.
4. Click the Browse button and open the XML file you want to work with.
5. Click Finish to close the dialog and open the Data Mapping configuration.
From the File menu
1.
2.
3.
4.
5.
Click the File menu and select New.
Click the Data mapping Configuration drop-down and select Files and then XML File.
Click Next.
Click the Browse button and open the XML file you want to work with.
Click Finish to close the dialog and open the Data Mapping configuration.
Page 45
Using a Wizard
The Data Mapping Wizard simplifies extracting records. When using a Data Mapping Wizard,
all the fields are automatically extracted inside the record. The Data Mapping Wizard also preconfigure the settings and boundaries of the data source using common values.
For A CSV 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 Connect Welcome 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 Using a wizard section, 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
l
l
l
l
l
Encoding: Choose the correct encoding to read the file.
Separator: Defines what character separates each fields in the file.
Comment Delimiter: Defines what character starts a comment line.
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.
6. Verify that the data is read properly and click Finish.
Page 46
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
l
l
l
l
l
Encoding: Choose the correct encoding to read the file.
Separator: Defines what character separates each fields in the file.
Comment Delimiter: Defines what character starts a comment line.
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.
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 Connect Welcome page by clicking the
select the Help menu and then Welcome.
2. Click Create a New Configuration.
3. From the Using a wizard section, select Database.
icon at the top right or
Page 47
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
l
l
l
l
l
l
l
Server: Enter the server address for the MySQL database.
Port: Enter the port to communicate with the MySQL server. The default port is 3306.
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.
Encoding: Choose the correct encoding to read the file.
Click Finish to close the dialog and open the actual Data Mapping configuration.
Microsoft Access
l
l
l
l
l
l
Click the Browse button and open the database file you want to work with.
Password: Enter a password if one is required.
Click Next.
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.
Encoding: Choose the correct encoding to read the file.
Click Finish to close the dialog and open the actual Data Mapping configuration.
SQL Server
Page 48
l
l
l
l
l
l
l
l
Server: Enter the server address for the SQL Server database.
Port: Enter the port to communicate with the SQL Server server. The default port is 3306.
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.
Encoding: Choose the correct encoding to read the file.
Click Finish to close the dialog and open the actual Data Mapping configuration.
ODBC DataSource
l
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
sources.
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
l
l
l
User name: Enter the SQL Server user name.
Password: Enter the password for the above user name.
Click Next.
Click Finish to close the dialog and open the actual Data Mapping configuration.
JDBC
Note
Page 49
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
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.
Click Next
Click Finish to close the dialog and open the actual Data Mapping configuration.
Oracle
l
l
l
l
l
l
l
l
Server: Enter the server address for the Oracle database.
Port: Enter the port to communicate with the Oracle server. The default port is 3306.
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.
Encoding: Choose the correct encoding to read the file.
Click Finish to close the dialog and open the actual Data Mapping configuration.
For a PDF File
To create a PDF/VT file data mapping configuration using the wizard, use the following steps:
Page 50
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 Using a wizard section, select PDF/VT.
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
l
l
Checkmark: Check any field to add it to the extraction.
Record Level: Displays the level on which the field is located.
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 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
l
l
Checkmark: Check any field to add it to the extraction.
Record Level: Displays the level on which the field is located.
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:
Page 51
From the Welcome screen
1. Open the PlanetPress Connect Welcome 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 Using a wizard section, 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 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
The Generate Counter wizard creates a record set where each record contains a "counter" field
contains the current counter value for each record, starting and stopping at set values and
Page 52
incremented by a set value also. It is useful for numbered tickets or any other template requiring
sequential numbers.
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:
1. In the Menus, click on File, then Save, or click the Save 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:
Page 53
1. In the Menus, click on File, then Save 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 appropriate data
from the Source Record and store it into the Record (see Data Model). 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 contain 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 a different extraction workflow. See About
Promotional and Transactional Data for more information.
Steps: To extract data from the data sample, you use different steps that make up the
extraction process. See Steps for more information.
About Promotional and Transactional Data
Promotional Data is traditionally defined as the unique fields found in each record. For
instance, a postal address, a date, or customer number could all be elements of promotional
data found in each record.
Transactional data is usually defined as promotional data plus a varying number of fields that
represent the elements of a transaction. While the structure is identical for each record, the
number of repeated elements varies from one record to the next. For instance, lines of items on
an invoice or monthly usage of electricity would be part of the transactional data.
Data Extraction
The following example explains in details how to perform a data extraction for each different
data source file types and the Steps that you can use to reach that goal. Delimiters and
Boundaries must be properly configured beforehand (see Configuring Settings for more
information).
Page 54
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).
To configure settings for the Preprocessor step, see Preprocessor Step Properties.
To configure settings for the Postprocessor step, see Postprocessor Step Properties.
The Extraction
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.
To configure settings for the Extract step, see Extract Step Properties.
For more information about Promotional and Transactional data, please refer to About
Promotional and Transactional Data.
From a CSV file or a Database
Extracting Promotional 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.
Page 55
Note
Alternatively, you can simply right click on the selected fields and select Add
Extraction.
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.
1. Select the fields that contain the first line item information.
2. Right click on this data selection and select Add Repeat .
3. Right click again on this data selection and select Add Extraction. A new extraction step
will be placed between the Repeat and theGoto steps.
Page 56
Note
You can also use the toolbar buttons instead of contextual menus, See Toolbars for more
details.
From a XML file
Extracting Promotional Data
The Promotional Data (customer and the invoice information) is repeated for each item
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.
Page 57
1. Select the children leaf nodes of the CUSTOMER() node.
2. Right click on the selected nodes and select Add Extraction.
Note
Alternatively, you can simply drag & drop the selected fields into the Data Model
pane.
Page 58
3. Select the children leaf nodes 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 on multiple lines. In the example
below, this information appears under the parent node ITEM(). Each ITEM() node give
information about one item. Create a loop on the ITEM() nodes to extract the items information.
1. Select the ITEM() node.
2. Right click on the selected node and select Add Repeat.
Page 59
Note
By default, the For Each option is selected in the Repeat type option as shown in
theStep Properties pane. It means that the loop will include each ITEM() node. In the
Collection field, you will find the corresponding ITEM() node path.
3. Select the children leaf nodes of the ITEM() node.
Page 60
4. Right click on the selected nodes and select Add Extraction.
Note
You can also use the toolbar buttons instead of contextual menus, See Toolbars for more
details.
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.
2. Right click on the selection data and select Add Extraction .
Note
Alternatively, you can simply drag & drop the selected fields into the Data Model pane.
Page 61
Extracting Transactional Data
The Transactional Data (line items information) appears on multiple lines and pages. A loop
has to be created on these lines to extract the items information. The line items are extracted in
a detail table as 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 at the beginning
of the first line item.
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, AMOUNT, ...etc. Now you can use that text as a
condition to stop the loop at the end of the line items list. In that case:
Page 62
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.
6. From the Viewer pane, select the first field on the left for the first line item.
Page 63
7. Right click on the selection and select Add Extraction.
8. Select the second field.
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
Page 64
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 Add Extract steps.
Note
You can also use the toolbar buttons instead of contextual menus, See Toolbars for more
details.
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:
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.
Page 65
Also Note That...
Note
l
l
l
l
l
l
If no Extract step is currently selected in the Steps pane, a new Extraction step is
created. If an Extract step is selected, new Extract Fields will be 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 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.
Dragging a single field onto a Data Model field will extract it to that field regardless
of its name.
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. For more
information about the Action step, see The Action Step.
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 toJavaScript _in_DataMapper.htmfor more
information.
Data Selection
The following topics contain information about how to create and manipulate a data selection,
and also how to create steps from it.
Selecting Data
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.
Page 66
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 67
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 68
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 69
Adding an Extraction Step from a Data Selection
To add a new step from the Data Viewer:
1. Create your data selection (refer to Creating a Data Selection for more information).
2. Right-clicking on the data selection and select the appropriate step.
See Type of Steps for more information on available steps.
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.
Page 70
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.
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 71
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.
Page 72
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).
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.
Page 74
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).
Steps
Steps are executed sequentially, from top to bottom. 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 75
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
Some preprocessors might for instance, using a JavaScript expression, convert all characters
of a text file from lowercase to uppercase prior to running Data Mapping workflow :
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 76
Postprocessors
Data postprocessors allow the application to extract data that was stored in the data model
once the workflow is complete. For example, the post processor can export all data or only
addresses, to a CSV file which can then be given directly to a postal addresses verification
application.
Some postprocessors might for instance, using a JavaScript expression, create a CSV file from
the Record set:
Page 77
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 78
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 section.
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 toJavaScript _in_DataMapper.htmfor more
information.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Page 79
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, for example when extracting
transactional data.
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 a 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 section.
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 80
A Condition step is used when the data extraction must be made based on specific criteria. In
the example shown in the following figure, 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 81
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 82
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 83
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 section.
Page 84
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. A 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 a usage example of a Repeat step. As you can see, 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 section.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Page 85
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 section.
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 86
For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys
under the Interface section.
Properties
You can also further customize the step properties. Please refer to The Step Properties
Interface for more information.
Data Model
A Data Model is the format into which Records are saved. It is also a file format that can be
exchanged between different parts of the PlanetPress Connect solution.
Data Model Principle
The idea behind the Data Model is that the structure of a Record can be separated from the
actual data. It can be shared between multiple templates, data mapping configurations, job
presets and output presets. These files are deemed compatible if their data model is identical
or if one data model is an exact subset of another.
Data Models can be used directly in the Designer module, even if no data is attached to it, to
create the template.
Page 87
They can be imported to, and exported from, the Data Model Pane in the Designer and
DataMapper Modules.
For more information about the operations you can perform on the Data Model, please refer to
The Data Model Interface.
About Records and Fields
A Record is a collection of fields and contains all the data about one particular person,
company, or item in a database that is required for creating a single document for a single
recipient (see Record for more information).
A Field is part of a record and contains a single piece of data for the subject of the record. If the
record is an employee, a field would be Firstname, Lastname, or City or State.
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:
Page 88
Example with transactional details, a simple invoice format
Page 89
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.
The first step to do before creating a Data Mapping configuration is to set up Input Data (setting
the delimiters) and Boundaries (setting the trigger) in the Settings pane.
Input Data (Delimiters)
Delimiters defines the separation within the source file. For example, in a CSV file the
delimiters are between each row whereas in a PDF file, delimiters separate pages.
Please refer to The Settings Pane Interface for more information about each fields and buttons.
Page 90
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.
Boundaries differ from Delimiters. When defining boundaries , multiple delimiters can be
included between boundaries - many pages per invoice, many CSV row 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 fields 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 fields 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 fields and buttons.
Page 91
DataMapper User Interface
Interface Sections and Panels
A.
B.
C.
D.
Menus
Toolbars
Steps Pane
Step Properties Pane
Page 92
E.
F.
G.
H.
Data Model Pane
Data Viewer
Messages Pane
Settings Pane
Menus
The following menu items are shown in the DataMapper Module's menu:
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
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.
Page 93
l
l
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.
Edit Menu
l
l
l
l
l
l
l
l
l
Undo: Undoes the previous action.
Redo: Redoes the last action that was undone.
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.
Cut: Click to remove the currently selected step, or steps, and place them in the clipboard.
Copy: Click to place a copy of the currently selected step, or steps, in the clipboard.
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 94
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 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
l
Zoom In: Click to zoom in the Steps Pane.
Zoom Out: Click to zoom out the Steps Pane.
Window Menu
l
Show View
l
l
l
l
l
l
l
Messages: Shows the Messages Pane.
Steps: Shows the Steps Pane.
Settings: Shows the Settings Pane.
Record: Shows the Record Pane.
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.
Reset Perspective: Resets all toolbars and panes to the initial configuration of the
module.
Page 95
Help Menu
l
l
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.
About PlanetPress Connect Designer: Displays the software's About dialog.
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 Extracted Record, all its fields as well as any detail tables
present in the Extracted Record. The information shown is the extracted information for the
current record within the Record Set. It is also used as a navigation tool between records and
all tables.
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.
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:
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.
Page 96
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:
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.
Page 97
l
l
l
l
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.
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
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
Page 98
l
l
l
l
l
l
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
.
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.
Detail Tables
Detail tables contain transactional data that is created when an Extract step is added within a
Repeat step.
Page 99
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 100
Example
1. Data Overview.
Page 101
Page 102
2. Extracting Customer and Invoice information.
Page 103
3. Extracting Transactional Data.
Page 104
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 105
Example
1. Data Overview.
Page 106
Page 107
2. Extracting Customer and Invoice information.
Page 108
3. Extracting Transactional Data for the First Table.
Page 109
4. Extracting Transactional Data for Nested Tables.
Page 110
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 Interface
The Data Viewer displays the contents of the Data Sample that is currently active within the
data mapping configuration. This data is never raw, meaning it has to be interpreted in some
Page 111
way to be displayed on the screen. For example, XML is displayed in a tree view rather than the
XML code. Similarly, PDFs are displayed as pages.
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. The Data Viewer's display is also affected by the
Preprocessor Step and displays the data after it has gone through all enabled preprocessors.
Window Controls
The following controls appear at the top of the Data Viewer:
l
l
l
l
l
l
l
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.
Hide/Show line numbers
(Text file only): Click to show or hide the line numbers on
the left of the Data Viewer.
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.
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.
Zoom Level: Use the arrows to adjust the zoom level, or type in the zoom percentage.
Zoom In (CTRL +) : Click to zoom in by increments of 10%
Zoom Out (CTRL -) : 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:
Page 112
Note
The Add Extract Field item is available only after an Extract step has been added to the
workflow.
For more information about the different steps that can be added to a Data Mapping workflow,
please refer to Steps.
Operations
Drag & drops from the Viewer window to the Data Model pane can be performed to extract data.
Page 113
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
l
l
l
l
l
l
l
Export Log: Click to open a Save As dialog where the log file (.log) can be saved on
disk.
Clear Log Viewer: Click to remove all entries in the log viewer.
Filters: Displays the Log Filter .
Activate on new events: Click to disable or enable the automatic display of this dialog
when a new event is added to the pane.
Time: The date and time when the error occurred.
Type: Whether the entry is a warning or an error.
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.
Log Filter
The log filter determines what kind of events are show in the Messages Pane.
l
Event Types group:
l
l
l
l
l
OK: Uncheck to hide OK-level entries.
Information: Uncheck to hide information-level entries.
Warning: Uncheck to hide any warnings.
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 Settings Pane is used to configure the Data Sample. The two main components that are
configured are Delimiters and Boundaries. 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).
Page 114
The Input Data Section
For a CSV File
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 be 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
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 ".3" represents 30% of the height or width.
l
l
Word spacing: Determines the spacing between words. As PDF text spacing is
somehow done via positioning instead of actual text spaces, position of text 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 .3
, meaning a space is assumed if a blank area of 30% of width of the average character in
the font.
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 height of the average
character height.
Page 115
l
l
l
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
height of the average character height to start a new paragraph.
Magic number: Determines the tolerance factor for all 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, we actually
consider any space of between ".7" and "1.43" this average width equals to 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
The following settings apply to any database and ODBC Data Sample.
l
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.
Custom SQL button : Click to open the SQL Query Designer and type in a custom SQL
query.
For a Text File
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 ).
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 in 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
Page 116
l
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. Multiple 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
l
l
l
l
Word to find: Compares the text value with the value in the Source Record.
Match case: Activates case-sensitive text comparison.
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
Delimiters for XML files are related to XML Elements, or locations in its hierarchy.
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 Section
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.
That's because boundaries are not actual bits of data (like a character or a field would be);
boundaries are a logical structure that exists outside the Data Source (note that some formats
like PDF/VT actually include structured information, but those are the exception rather than the
norm). Boundaries are therefore a form of metadata. You could very well use the same exacted
data with a different boundary structure, in order to extract different information. Think, for
instance, of an Invoice Run stored in a PDF. You could very well be using a structure where
each invoice is a single record or you could group all invoices for one customer into a single
Page 117
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, we have to figure out a way to identify specific
locations in the input stream and mark those locations as record boundaries. Fortunately for us,
it turns out that every single file format possesses intrinsic, natural delimiters that are used to
identify chunks of related data. These delimiters are key in helping us identify boundaries, so
it's 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 is a candidate for
being a boundary is very likely to be found between delimiters.
To do that, we'll take a closer look at the various input data types.
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 those lines on the grid. So here, the record occurs with a new line in the grid, but not on
each new line.
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 control when a boundary is created, establishing a
new record in the Data Sample (called a Source Record).
l
Record(s) per page: Defines a set number of lines in the file that go in each Source
Record.
l
l
Records: The number of records to show in each Source Records.
On change: Defines a new Source Record when a specific field (Field name) has a
new value.
Page 118
l
l
l
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 when 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
For a PDF file, the natural delimiter is a Page. A record boundary always occurs on a new
page, never in the middle of a page. Each record may very well include one or more pages (i.e.
delimiters).
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
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 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.
Page 119
l
l
l
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.
Operator: Selects the type of comparison that is done (for example,
"contains").
Word to find: Compares the text value with the value in the Source Record.
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,
you wouldn't find the end of a record in the middle of a line. Note also that with this format, it's
possible 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.
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
Select the area button: Uses the value of the current data
selection as the text value.
Page 120
l
l
l
l
l
l
l
l
l
l
l
Left/Right: Defines the location, in the row, where to find the text
value.
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
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.
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.
Operator: Selects the type of comparison that is done (for example,
"contains").
Word to find: Compares the text value with the value in the Source Record.
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
For a XML file, the natural delimiter is an XML 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 that defines 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.
Page 121
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 selected one's
value determines new boundaries.
The Data Samples Section
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 Section
Right-clicking in the box brings up a control menu, also available through the buttons on the
right:
l
l
l
l
Add
: Adds a new external library. Opens the standard Open dialog to browse and
open the .js file.
Delete : Removes the currently selected library from the data mapping configuration.
Replace : Opens a new library and replaces it with the contents of a different js file.
Reload : Reloads the currently selected library and any changes that have been made
to it.
Page 122
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 Pane displays each step of the workflow of which the primary goal is to extract data
from the data sample.
Window Controls
The following controls appear at the top of the Steps pane:
l
l
Zoom In (CTRL +) : Click to zoom in by increments of 10%
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 123
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 124
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 125
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.
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 126
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 127
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 displays the properties for any step selected in the Steps Pane.
Note
Step properties may also depend on the Data Sample's file type.
Preprocessor Step
Extract Step
Action Step
Repeat Step
Condition 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 section lists all the fixed properties available from the
PlanetPress Workflow automation module. These properties are equivalent to data available
within the PlanetPress Workflow process. For each property, the following is available:
Page 128
l
l
l
l
Name: A read-only field displaying the name of the property.
Scope: A read-only field indicating that the scope of the property is Automation.
Type: A read-only field indicating the data type for each property.
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 section 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 JavaScript API.
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.
Page 129
l
l
Name: The name of the property used to refer to its value.
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
JavaScript 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.
Preprocessor
The Preprocessor section 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
l
Name: The name to identify the Preprocessor.
Type: The type of Preprocessor. Currently there is only one type available.
Page 130
Preprocessor definition
l
Expression: The JavaScript expression that will run on the Data Sample. See JavaScript
API.
Description
This section is collapsed by default in the interface in order to give more screen space to
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 section is collapsed by default in the interface in order to give more screen space to
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.
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.
Page 131
Field Definition
This 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
l
l
l
l
Left: Defines the start of the data selection to extract.
Right: Defines the end of the data selection to extract.
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.
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.
Concatenation string:
Split: Separate the selection into individual fields based on the
Concatenation string defined above.
Page 132
l
l
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 JavaScript 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
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.
Remove Extract Field: Click to delete the selected extract field from the list.
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
l
l
l
Left: Defines the start of the data selection to extract.
Right: Defines the end of the data selection to extract.
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.
Page 133
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 JavaScript 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.
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.
Remove Extract Field: Click to delete the selected extract field from the list.
Order and rename fields: Click to openOrdering and Renaming Fields.
Page 134
l
l
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.
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 JavaScript API.
l
Expression:
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.
Page 135
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
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
l
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.
Remove Extract Field: Click to delete the selected extract field from the list.
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.
Page 136
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 JavaScript 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.
Data Format
The data format defines the precise format for some of the variable types, such as dates and
currencies.
l
l
l
Boolean
String
HTML String
Page 137
l
Integer
l
l
l
l
Float
l
l
l
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 (.).
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
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.
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).
Page 138
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
l
l
l
l
Name: The name of the field. Click the field name and enter a new name to rename the
field.
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.
Value: Displays the value of the extract field in the current Record.
Remove button : Click to remove the currently selected field.
Move Up button : Click to move the selected field up one position.
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 section is collapsed by default in the interface in order to give more screen space to
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 section lists all actions executed by the step, and their types:
l
l
Name: A name by which to refer to the action. This name has no impact on functionality.
Type:
l
Set property: Sets the value of a Source Record property which was created in the
Preprocessor Step.
Page 139
l
Run JavaScript : Runs a JavaScript expression, giving much more flexibility over
the extraction process.
Set Property
Text and PDF Files
l
l
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
Type: Displays the type of the Source Record property. Read only field.
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
l
l
l
l
Left: Defines the start of the data selection to extract
Right: Defines the end of the data selection to extract
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 JavaScript API.
l
l
Expression: The JavaScript expression to run.
Use JavaScript Editor: Click to display the Edit Script dialog.
Note
Running a JavaScript expression offers many possibilities, for example:
Page 140
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 the JavaScript in DataMapper section.
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
l
l
l
Boolean
String
HTML String
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 141
l
l
l
Currency
l
l
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.
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
l
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
Type: Displays the type of the Source Record property. Read only field.
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
Column: Drop-down listing all fields in the Data Sample, of which the value
will be used.
Page 142
l
l
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 JavaScript API.
l
l
Expression: The JavaScript expression to run.
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 the JavaScript in DataMapper section.
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 143
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
l
l
l
Boolean
String
HTML String
Integer
l
l
l
l
Float
l
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.
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
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 (.).
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
Page 144
l
l
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
l
l
Property: Displays a list of Source Record properties set in the Preprocessor Step.
Type: Displays the type of the Source Record property. Read only field.
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
Trim: Select to trim empty characters at the beginning or the end of the
field
Page 145
l
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 JavaScript API.
l
l
Expression: The JavaScript expression to run.
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 the JavaScript in DataMapper section.
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
l
l
Boolean
String
HTML String
Page 146
l
Integer
l
l
l
l
Float
l
l
l
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 (.).
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
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.
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
Page 147
information).
Run JavaScript
l
l
Expression: The JavaScript expression to run.
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 the
JavaScript in DataMapper section.
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.
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.
Page 148
Description
This section is collapsed by default in the interface in order to give more screen space to
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.
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.
Page 149
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 the
JavaScript in DataMapper section.
Rule Tree
The Rule tree section displays the full combination rules (defined below under the Condition
section) 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
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.
To rename a Condition, double click on its name from the Rule tree section.
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
Page 150
l
Based On:
l
Position: The data in the specified position for the comparison.
l
l
l
l
l
l
l
Value: A specified static text value.
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
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
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.
Right: The end position for the data selection.
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.
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 151
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.
CSV and Database Files
l
Based On:
l
Position: The data in the specified position for the comparison.
l
l
l
l
l
Value: A specified static text value.
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.
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
Field: The Extracted Record field to use in the comparison.
Page 152
l
JavaScript : The result of a JavaScript Expression.
l
l
l
l
l
l
l
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.
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.
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:
Page 153
l
Position: The data in the specified position for the comparison.
l
l
l
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
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
XPath: The path to the XML field that is extracted.
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.
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
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.
Page 154
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 section is collapsed by default in the interface in order to give more screen space to
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 section displays the full combination rules (defined below under the Condition
section) 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
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.
To rename a Condition, double click on its name from the Rule tree section.
Conditions are made by comparison of two operands using a specific Operator.
Page 155
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
Value: A specified static text value.
l
l
l
Field: The Extracted Record field to use in the comparison.
JavaScript : The result of a JavaScript Expression.
l
l
l
l
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
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.
Right: The end position for the data selection.
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.
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.
Page 156
l
l
l
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
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:
l
Position: The data in the specified position for the comparison.
l
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.
Trim: Select to trim empty characters at the beginning or the end of the field.
Page 157
l
Value: A specified static text value.
l
l
l
Field: The contents of a specific field in the Extracted Record.
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
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.
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
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.
Page 158
l
Invert condition: Inverts the result of the condition. For instance, is empty becomes
is not empty.
XML File
l
Based On:
l
Position: The data in the specified position for the comparison.
l
l
l
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
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
XPath: The path to the XML field that is extracted.
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.
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).
Page 159
l
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.
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 section is collapsed by default in the interface in order to give more screen space to
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
From: Defines where the jump begins:
l
l
Current Position: The Goto begins at the current cursor position.
Top of record: The Gotobegins at line 1 of the source record.
Page 160
l
l
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
l
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
l
l
l
Current Position: The Gotobegins at the current cursor position.
Top of record: The Gotobegins at line 1 of the source record.
Left: The starting column, inclusively.
Right: The end column, inclusively.
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
l
l
l
l
Left: The starting column, inclusively.
Right: The end column, inclusively.
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.
Page 161
l
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 .
l
Physical distance:
l
From: Defines where the jump begins:
l
l
l
l
Move by: Enter distance to jump.
Page: Jumps between pages or to a specific page.
l
From: Defines where the jump begins:
l
l
l
l
Current Position: The Gotobegins at the current cursor position.
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
l
l
l
Current Position: The Goto begins at the current cursor position.
Top of record: The Gotobegins at line 1 of the source record.
Left: The starting column, inclusively.
Right: The end column, inclusively.
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
Page 162
checks in:
l
l
l
l
l
l
Left: The starting column, inclusively.
Right: The end column, inclusively.
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
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.
Page 163
l
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.
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 section 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
l
Name: The name to identify the Postprocessor.
Type: The type of Postprocessor. Currently there is a single type available.
l
JavaScript : Runs a JavaScript Expression to modify the Data Sample. See
JavaScript API.
l
l
l
l
l
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.
Remove Postprocessor: Click to remove the currently selected Postprocessor.
Move Up: Click to move the Postprocessor up one position.
Move Down: Click to move the Postprocessor down one position.
Export: Click to export the current Postprocessor configuration and content to a file.
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 JavaScript
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.
Description
This section is collapsed by default in the interface in order to give more screen space to
important parts.
Page 164
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
Each piece of data in PlanetPress Connect, once it has been extracted from the Source
Record, will always be handled using Data Types. Data types determine how the data is
handled when reading and writing values in properties and extracted record fields, as well as
when comparing values. For example, if a Date field is compared with a Date source record
property, the comparison will be done on dates (latest date being a "higher" value).
Here are the data types available in all modules of PlanetPress Connect.
l
l
l
l
l
l
l
l
Boolean
String
HTMLString
Integer
Float
Currency
Date
Object
Note
The Object data type is only available in the DataMapper module. It is created in the Properties
section of 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.
Page 165
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.
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";
Page 166
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.
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.
Page 167
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
l
Direct attribution: Assign an integer value directly, such as
42,99593463712ordata.extract("TotalOrdered").
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.
Page 168
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
calculations: it is as precise as integers.
Defining Currency Values
l
l
l
Pre-Processor: Specify the "Type" as "Currency" and set a default value as a number
with up to 4 decimal points, such as 546513.8798
Extraction: Specify the "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.
Page 169
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 variable is stored in Connect database with zero time zone offset, which makes it
possible to convert the time correctly in any location. PlanetPress Worfklow, 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.
Defining Date Values
Because dates can be in many different formats and variations, the use of the JavaScript Date()
object is necessary when creating dates through a JavaScript expression. For more
information, see w3schools - Date Object.
l
l
l
Pre-Processor: Specify the "Type" as "Date" and set a default value as a date value in
any desired format, such as "[TBD]";
Extraction: Specify the "Type" as "Date" and set the Data Format, especially the
"DateTime Format" that defines how the date is read. The field value will be extracted and
treated as a Date.
JavaScript Expression: Set the desired value to any date value.
Example: record.fields["InvoiceDate"] = "[TBD]";
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).
Page 170
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
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.
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
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
Page 171
l
l
l
l
l
l
l
l
l
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 Action Step : Adds a step to create a custom JavaScript snippet. See the
JavaScript 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.
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
Page 172
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:
l
l
The Welcome Screen button in the Toolbars.
From the Menus in Help, Welcome Screen.
Contents
l
l
l
l
l
Activation: Click to open the Objectif Lune Web Activation Manager.
Release Notes: Opens the current Release Notes for PlanetPress Connect.
Website: Opens the PlanetPress Connect website.
Take A Tour: Click to open the YouTube Playlist giving you a tour of the software.
Use the DataMapper to...:
l
l
l
l
Use the Designer to...:
l
l
l
l
l
Create a New Configuration: Opens the Creating a New Configuration screen.
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.
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
l
l
Documentation: Opens this documentation.
Courses (OL Learn): Opens the Objectif Lune e-Learning Center.
User Forums: Opens the Questions & Answer forums.
Page 173
The Designer
The Designer is a WYSIWIG (what you 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
l
l
"Basic Steps" on page 218. These are the basic steps for creating and developing a
template.
"Features" on page 220. These are some of the key features in the Designer.
"Designer User Interface" on page 452. This section 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.
...
API
Designer Scripts API
This page describes the different features available in scripts created inside the Scripts pane.
See "Write your own scripts" on page 376.
Features that are only available in Control Scripts are listed in the Control Script API. See
"Control Script API" on page 211.
Page 174
Objects
results
The HTML element or set of HTML elements that match the selector
specified in the script editor.
record
The current record in the main data set.
logger
Global object that allows you to log messages.
locale
Defines which locale to use.
"formatter" on
page 200
Global object that allows you to format values.
automation
Automation properties
merge
Merge properties
Global functions
Skin/Formats/CrossReferencePrintFormat("loadhtml() Global function
that replaces the content (inner html) of each matched element in the result
set, alternatively load the data into a variable. The location should be an URL
or a relative file path. loadhtml(location)loadhtml(location, selector) Loadhtml()
is cached per batch run (based on the URL) in print/email. loadhtml(location)
Loads all HTML from the HTML file. locationString containing a path that can
be absolute or relative to the section/context. Use: snippets/ to
retrieve the content from a HTML file residing in the Snippets folder on the
Resources panel.ExamplesThis script loads a local HTML snippet (from the
Resources panel) directly into the matched elementsresults.loadhtml
("snippets/snippet.html");The following script loads a local HTML snippet
(Resources panel) into a variableThe replaceWith() command is used to
replace the element(s) matched by the script's selector with the contents of the
snippet.var mysnippet = loadhtml('snippets/snippet.html'); results.replaceWith
(mysnippet);Same result as the previous script, but a different
notation:results.replaceWith(loadhtml('snippets/snippet.html'));The following
script loads a snippet into a variable and finds/replaces text in the variable
Loads
HTML
data from
a HTML
(snippet).
The
returned
HTML can
be placed
into a
variable
or into a
set of
HTML
elements.
Page 175
before inserting the content into the page. The second find command also
adds formatting to the replacing text.var mysnippet = loadhtml
('snippets/snippet.html'); mysnippet.find('@var1@').text('OL Connect 1');
mysnippet.find('@var2@').html('OL Connect 2').css('textdecoration','underline'); results.replaceWith(mysnippet); This last script loads
a snippet into a variable and retrieves an element from the snippet using
query().var mysnippet = loadhtml('snippets/text-root-wrapped.html'); var
subject = query("#subject", mysnippet).text(); results.append("" + subject + "
");loadhtml(location, selector) Retrieve
specific content from the filename. location String; the location can be
absolute or relative to the section/context. Use: snippets/ to
retrieve the content from a HTML file residing in snippets folder of the
Resources panel.selectorString. The supplied selector should conform to
CSS selector syntax and allows you to retrieve only the content of matching
elements.ExamplesThis script loads a specific element from the snippet.var
mysnippet = loadhtml('snippets/snippet-selectors.html','#item3');
results.replaceWith(mysnippet);This script loads the children of the selected
element.var snippet = loadhtml('snippets/snippet.html','foobar').children();
results.replaceWith(snippet);Another example is given in the following how-to:
Using a selector to load part of a snippet." on page 1)
"loadjson()" on page 203
Loads
json data
from an
url. This is
an simple
way to
retrieve
content
from
external
systems.
"query()" on page 209
Performs
a query in
the
Page 176
template's
contents
and
creates a
new result
set
containing
the HTML
elements
that match
the given
CSS
selector.
Functions
All these functions can be used with an HTML element or a set of HTML, such as the results
(the HTML element or set of HTML elements that match the selector specified in the script
editor) or the result set returned by a query (see "query()" on page 209).
"add()" on
page 179
Adds elements to a set of HTML elements.
"addClass()"
on page 180
Adds the specified class to each element in a set of HTML elements. Has
no effect if the class is already present.
"after()" on
page 181
Inserts content after each element in a set of HTML elements..
"append()" on
page 183
Inserts content at the end of each element in a set of HTML elements.
"attr()" on
page 186
Change the given attribute of the element or set of HTML elements with
the given value.
"before()" on
page 187
Inserts content before an element or before each element in a set of HTML
elements.
Page 177
"css()" on
page 191
Gets the value of a style property for the first element in set of HTML
elements or sets one or more CSS properties for every element in a set of
HTML elements.
"children()"
on page 189
Returns the immediate children of an HTML element.
"clone()" on
page 189
Returns a new result set containing a copy of each element in a set of
HTML elements.
filter()
Returns a subset of the current result set.
find()
Performs a search for a text in the children of each element in a set of
HTML elements, and returns a new result set with elements that surround
the occurrences.
hasClass()
Returns true if the first element in this result set has the specified class.
hide()
Hides the HTML element or set of HTML elements.
html()
Replaces the inner HTML of the element or of each element in a set of
HTML elements with the supplied value, or returns the HTML of the first
element if no value is supplied.
is(selector)
Returns true if at least one of the elements in a set of HTML elements
matches the supplied CSS selector.
parent()
Returns the parents of the elements in a set of HTML elements.
"prepend()"
on page 206
Inserts content at the beginning of an HTML element or of each element in
a set of HTML elements.
"CopyFile()"
on page 210
Removes an HTML element or a set of HTML elements from the
document.
removeAttr()
Removes the specified attribute from each element in this result set.
"removeClass
Removes the specified class from an element or from each element in a
Page 178
()" on page
210
set of HTML elements. Has no effect if the class is not present.
"replaceWith
()" on page
211
Replaces an HTML element or a set of HTML elements (with a snippet, for
example). Returns the result set.
show()
Shows the HTML element or a set of HTML elements.
text()
Replaces the text content of an HTML element or of each element in a set
of HTML elements with the supplied value, or returns the text content of
the first element if no value is supplied.
Examples of iterator functions
"Each" on
page 197
A generic iterator function, to iterate over the elements in the result set
"For...in" on
page 199
Iterates over the enumerable properties of an object, in arbitrary order. For
each distinct property, statements can be executed.
add()
The add() function allows you to add elements to a set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 209).
add(content)
Returns the union of this result or result set and other content.
content
A query result. This can be an HTML string or a result set.
Examples
Add one result set to another
This script adds one query result to another and sets the background color to yellow.
query("#test1").add(query("#test2")).css("background", "yellow");
Page 179
Note: the way the functions add() and css() are used in this script is called 'chaining'. Chaining
is optional; the same could be achieved by storing the results of the queries in a variable:
var myResult = query("#test1");
myResult.add(query("#test2");
myResult.css("background", "yellow");
Creating an empty result set and adding elements to it
The following script loads snippets in an iteration and adds their elements to an empty result
set (using query()). Then it replaces a placeholder in the template with the new result.
var chapters = query();
for ( var i = 1; i <= 4; i++) {
chapters = chapters.add(loadhtml('snippets/Chapter' + i +
'.html'));
}
results.replaceWith(chapters);
Selector
Matched element
Matched element after script execution
#chapters
{{chapters}}
Chapter 1
Lorem ipsum...
Chapter 2
Lorem ipsum...
Chapter 3
Lorem ipsum...
Chapter 4
Lorem ipsum...
addClass()
Adds the specified class(es) to each element in a set of HTML elements that match the selector
of the script or of another query in the template (see "query()" on page 209). This has no effect if
the class is already present.
addClass(classname)
Adds the specified class(es) to each element in a result set. Has no effect if the class is already
present.
classname
Page 180
String, space separated list of class names.
Examples
This script adds a class name to a paragraph.
results.addClass("foo");
Selector
Matched element
Matched element after script execution
p
Hello world
The following script adds two class names to a paragraph.
results.addClass("foo bar");
Selector
Matched element
Matched element after script execution
p
Hello world
after()
Insert content after each element in the set of HTML elements that match the selector of the
script or of another query in the template (see "query()" on page 209). See also: "before()" on
page 187.
after(content)
Insert content after each element in the set of HTML elements that match the selector of the
script, or of another query in the template (see "query()" on page 209). After creates a new
result set.
content
String, HTML string or result set to insert after the matched elements. In case a plain text
string is provided, it is automatically wrapped in a element to avoid orphan text nodes
to appear in the element.
Examples
This script looks up an element with the ID #salesrep and inserts a paragraph after it.
query("#salesrep").after("Lorem ipsum
");
Page 181
Matched element
Matched element after script execution
Peter Parker
Peter Parker
Lorem ipsum
This script looks up an element with the ID #salesrep, sets its text color to red and inserts a
paragraph after it.
query("#salesrep").after("Lorem ipsum
").css("color","red");
Matched element
Matched element after script execution
Peter Parker
Peter Parker
Lorem ipsum
Note: the way the functions after() and css() are used in this script is called 'chaining'. Chaining
is optional; the same could be achieved by storing the result of the query in a variable:
var salesrep = query("#salesrep");
salesrep.after("Lorem ipsum
");
salesrep.css("color","red");
The following script inserts a paragraph after the elements in the results (the set of HTML
elements that match the selector of the script).
results.after("Lorem Ipsum
");
Matched element
Matched element after script execution
Peter Parker
Peter Parker
Lorem ipsum
This script looks for the string "Lorem " in the results (the set of HTML elements that match the
selector of the script).and inserts the string "ipsum" right after that text. The string is
automatically enclosed in a span.
results.find("Lorem ").after("ipsum");
Matched element
Matched element after script execution
Page 182
Lorem dolor sit amet,
consectetur adipiscing elit.
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
This script looks up an element with the ID #salesrep and inserts a string after it. The string is
automatically enclosed in a span.
query("#salesrep").after("Lorem Ipsum");
Matched element
Matched element after script execution
Peter Parker
Peter Parker
Lorem Ipsum
append()
Insert content at the end of each element in the set of each element in a set of HTML elements
that match the selector of the script or of another query in the template (see "query()" on page
209). See also: "prepend()" on page 206.
append(content)
Insert content as the last element to each element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 209). Append
creates a new result set.
content
String, HTML string or result set to insert after the elements. In case a plain text string is
provided, it is automatically wrapped in a element to avoid orphan text nodes to
appear in the element.
Examples
This script appends a paragraph to the results (the set of HTML elements that match the
selector of the script).
results.append("Peter Parker
");
Page 183
Selector
Matched element
Matched element after script execution
#box
Personal information
Personal information
Peter Parker
This script appends a string to the results (the HTML elements that match the selector of the
script). The string is added to the end of the matched element(s) and wrapped in a Span
element.
results.append("Peter Parker");
Selector
Matched element
Matched element after script execution
.name
Personal
information
Name:
Personal information
Name: Peter
Parker
This script's selector is , so the script appends a paragraph to all Div elements in the
template.
results.append("Peter Parker
");
Selector
Matched element
Matched element after script execution
div
Personal information
Personal information
Personal information
Peter Parker
Personal information
Peter Parker
Page 184
The following script appends a snippet to a Div element with the ID box.
var a = loadhtml('snippets/snippet_name.html');
results.append(a);
Selector
Matched element
Matched element after script execution
#box
Personal information
Personal information
Peter Parker
This script looks for an element with the ID box and appends a paragraph to it.
query("#box").append("Peter Parker
");
Matched element
Matched element after script execution
Personal information
Personal information
Peter Parker
This script looks for an element with the ID box, appends a paragraph to it and colors all text
inside the box red.
query("#box").append("Peter Parker
").css("color","red");
Matched element
Matched element after script execution
Personal information
Personal information
Peter Parker
Note: the way the functions append() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:
Page 185
var box = query("#box");
box.append("Peter Parker
");
box.css("color","red");
attr()
Returns the value of the specified attribute of the first element in a result set, or sets the value of
the specified attribute of each element in a result set.
l
l
attr(attributeName)
attr(attributeName, value)
attr(attributeName)
Returns the value of the specified attribute of the first element in a result set.
attributeName
String; the name of the attribute.
Examples
This script - with the selector img - stores the source of the first image in a variable.
var src = results.attr("src");
The following script looks up an element with the ID #table1 and stores its background color in
a variable.
var backgroundcolor = query("#table1").attr("bgcolor");
attr(attributeName, value)
Sets the value of the specified attribute of each element in a result set.
attributeName
String; the name of the attribute.
value
String; value for the attribute.
Page 186
Examples
This script looks up a table cell in an element with the ID #calloutbox and sets its text color to
red.
query("#callout td").attr('bgcolor' , 'red');
The following script sets the background color of a specific table cell to red if the value of the
field TOTAL has a negative value in the current record.
if(record.fields.TOTAL<0) {
query("#total").attr("bgcolor","red");
}
before()
Insert content before each element in the set of HTML elements that match the selector of the
script or of another query in the template (see "query()" on page 209). See also: "after()" on
page 181.
before(content)
Before(content) inserts content before each element in the set of elements that match the
script's selector. Before() creates a new result set.
content
String, HTML string or result set to insert after the elements. In case a plain text string is
provided, it is automatically wrapped in a element to avoid orphan text nodes to
appear in the element.
Examples
This script looks for an element with the ID salesrepand inserts a paragraph before that
element.
results.before("Lorem Ipsum
");
Selector
Matched element
Matched element after script
execution
#salesrep
Peter
Parker
Lorem ipsum
Peter Parker
This script does the same, but it uses the query() function to look up the element.
Page 187
query("#salesrep").before("Lorem ipsum
");
Matched element
Matched element after script execution
Peter Parker
Lorem ipsum
Peter Parker
The following script looks for an element with the ID salesrep, inserts a paragraph before that
element and colors that element red.
query("#salesrep").before("Lorem ipsum
").css("color","red");
Matched element
Matched element after script execution
Peter Parker
Lorem ipsum
Peter Parker
Note: the way the functions before() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:
var salesrep = query("#salesrep");
salesrep.before("Lorem ipsum
");
salesrep.css("color","red");
The following script searches the results for the string "ipsum" and puts "Lorem " before it.
"Lorem " is automatically wrapped in a Span element.
results.find("ipsum").before("Lorem ");
Matched element
Matched element after script execution
ipsum dolor sit amet, consectetur
adipiscing elit.
Lorem ipsum dolor sit amet,
consectetur adipiscing elit.
The following script looks for an element with the ID salesrep and inserts the text "Lorem
Ipsum" before that element. "Lorem Ipsum" is automatically wrapped in a Span element.
query("#salesrep").before("Lorem Ipsum");
Matched element
Matched element after script
Page 188
execution
ipsum dolor sit amet, consectetur adipiscing
elit.
Lorem Ipsum
Peter Parker
children()
Returns the immediate children (inner HTML) of the elements in a result set.
Examples
This script retrieves the inner HTML of an element selected from a snippet.
var snippet = loadhtml('snippets/snippet.html','#foobar').children
();
results.append(snippet);
The following script retrieves the inner HTML of the elements and then performs a find/replace.
var snippet = loadhtml('snippets/snippet.html','#foobar').children
();
snippet.find('@firstname@').text('foobar');
results.append(snippet);
clone()
Returns a new result set containing a deep copy of each element in a result set. To duplicate
an existing DOM element, clone it before calling append(); see "append()" on page 183.
Examples
This script performs an iteration over the elements in the results
var row = query("tbody tr", results).clone();
query("tbody", results).append(row);
The following script clones an existing table row to match the number of rows in a detail table.
Afterwards it iterates over the rows to populate the fields.
// Create the number of rows based on the records in the detail
table
// We start at 1 so the boilerplate row is used too and there is no
need to delete that row
for(var r = 1; r < record.tables['detail'].length; r++) {
results.parent().append(results.clone());
Page 189
}
// Iterate over the rows and populate them with the data from the
accompanying data row
query("#table_2 > tbody > tr").each(function(i) {
this.find('@ItemNumber@').text( record.tables['detail'][i].fields
["ItemNumber"]);
this.find('@ItemOrdered@').text( record.tables['detail'][i].fields
["ItemOrdered"]);
this.find('@ItemTotal@').text( record.tables['detail'][i].fields
["ItemTotal"]);
this.find('@ItemDesc@').text( record.tables['detail'][i].fields
["ItemDesc"]);
this.find('@nr@').text(i);
});
The following script clones and populates a boilerplate row. Once completed you will need to
hide the boilerplate row.
for(var i = 0; i < record.tables['detail'].length; i++) {
var row = results.clone(); //Clone our boilerplate row
row.find('@ItemNumber@').text( record.tables['detail'][i].fields
["ItemNumber"]);
row.find('@ItemOrdered@').text( record.tables['detail'][i].fields
["ItemOrdered"]);
row.find('@ItemTotal@').text( record.tables['detail'][i].fields
["ItemTotal"]);
row.find('@ItemDesc@').text( record.tables['detail'][i].fields
["ItemDesc"]);
row.find('@nr@').text( i );
results.parent().append(row);
}
// Hide our boilerplate row (note that this doesn't really delete
the row).
results.hide();
Page 190
css()
Get the value of a style property for the first element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 209), or set one
or more CSS properties for every element in the set.
l
l
l
css(propertyName)
css(propertyName, value)
css(properties
css(propertyName)
Returns the value of the specified CSS property.
propertyName
String; the name of the CSS property.
Examples
This script stores the text color of the results (the HTML elements that match the selector of the
script) in a variable.
var textcolor = results.css("color");
The following script looks up an element with the ID #calloutbox and stores its background
color in a variable.
var backgroundcolor = query("#calloutbox").css("background-color");
css(propertyName, value)
Function to set a CSS property.
propertyName
String; the name of the CSS property.
value
String; value for the CSS property or a map of property-value pairs to set.
Examples
This script looks up an element with the ID #calloutbox and sets its text color to red.
Page 191
query("#callout p").css('color' , 'red');
The following script does the same, but it only sets the text color to red if in the current record
the value of the field 'accounttype' is 'PRO'.
if(record.fields.accounttype == "PRO") {
query("#callout p").css("color","red");
}
This script sets the text color of the results to a hexadecimal color code.
results.css('color' , '#669900');
This script loads a snippet into a variable. Then it finds/replaces text in the snippet and applies
a css property to the replacing text.
ar mysnippet = loadhtml('snippets/snippet vars.html');
v
mysnippet.find('@var@').text('OL Connect').css('textdecoration','underline');
results.replaceWith(mysnippet);
css(properties)
Function to set one or multiple CSS properties.
properties
Array; map of property-value pairs to set.
Examples
This script colors the text of the results (the set of HTML elements that match the selector of
the script) red and makes it bold.
results.css({'color' : 'red', 'font-weight' : 'bold'});
Date, date/time and time functions
l
l
l
l
l
l
l
date()
dateLong()
dateMedium()
dateShort()
dateTime()
dateTimeLong()
dateTimeMedium()
Page 192
l
l
l
l
l
dateTimeShort()
time()
timeLong()
timeMedium()
timeShort()
Note
The locale also influences the output of the different Date functions; see "Locale" on page 421.
Tip
To format a date from a date field in the record set, you can enter a formatting pattern directly in
the Text Script Wizard; see "Using the Text Script Wizard" on page 338, "Formatting variable
data" on page 341 and Date and time patterns).
date(value, pattern)
Formats a date object using a custom pattern.
value
A Date object. A Date can contain a date and time.
pattern
String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "MMMM dd, yyyy"; see Date and time patterns. Note that the repetition of pattern
letters determines the exact presentation.
dateLong(value)
Formats a date as long string representation, for example April 1, 2016.
value
A Date object. A Date can contain a date and time.
dateMedium(value)
Formats a date as medium string representation, for example 01/04/16.
Page 193
value
A Date object. A Date can contain a date and time.
dateShort(value)
Formats a date as short string representation, for example 1-Apr-2016.
value
A Date object. A Date can contain a date and time.
dateTime(value, pattern)
Formats a date and time object using a custom pattern.
value
A Date object. A Date can contain a date and time.
pattern
String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "yyyy.MM.dd G 'at' HH:mm:ss z"; see Date and time patterns. Note that the
repetition of pattern letters determines the exact presentation.
dateTimeLong(value)
Formats a date and time as long string representation, for example April 1, 2016 12:00:00 EDT
AM.
value
A Date object. A Date can contain a date and time.
dateTimeMedium(value)
Formats a date and time as medium string representation, for example 1-Apr-2016 12:00:00
AM.
value
A Date object. A Date can contain a date and time.
dateTimeShort(value)
Formats a date and time as short string representation, for example 01/04/16 12:00 AM.
Page 194
value
A Date object. A Date can contain a date and time.
time(value, pattern)
Formats a time using a custom pattern.
value
A Date object. A Date can contain a date and time.
pattern
String. The custom pattern may consist of pattern letters, separating symbols and quoted text,
for example: "'at' HH:mm:ss z"; see Date and time patterns. Note that the repetition of pattern
letters determines the exact presentation.
timeLong(value)
Formats a time as long string representation, for example 12:00:00 EDT AM.
value
A Date object. A Date can contain a date and time.
timeMedium(value)
Formats a time as medium string representation, for example 12:00:00 AM.
value
A Date object. A Date can contain a date and time.
timeShort(value)
Formats a time as short string representation, for example 12:00 AM.
value
A Date object. A Date can contain a date and time.
Examples
The following script passes the value of a field in the record set to the date() function. This will
only work if the type of the field has been set to Date in the Data Mapping Configuration and if
the field contains a valid date.
Page 195
var myDate = formatter.date(records.fields.DATE, "MM/dd/yyyy");
The custom pattern that the script provides, outputs the month and day in two digits each and
the year in four digits: 05/21/2016. For more examples of formatting patterns, see Date and time
patterns.
Creating a Date object from a string
In a Data Mapping Configuration you can set the type of a field to Date, but when you open a
data file or database in the Designer without a Data Mapping Configuration, all fields are text
fields (fields of the type string). The formatter cannot be used to format a string with a
particular date format. The solution is to store the string in a variable as a Date object, and use
the formatter with that variable.
The following sample script demonstrates this solution. It splits a string into parts and then
creates a new Date object with the parts in the correct order. To construct a Date, the parts of
the date must be put in the following order: year, month, day, and optionally hours, minutes,
seconds, milliseconds (see http://www.w3schools.com/js/js_dates.asp and
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date.)
When the time is omitted, it defaults to 12:00:00 AM.
/* Convert
var
var
var
[0]);
the string 21-12-1997 into a valid JavaScript date */
strDate = record.fields["date"];
dateParts = strDate.split("-");
date = new Date(dateParts[2], (dateParts[1] - 1), dateParts
Note
JavaScript counts months from 0 to 11. January is 0. December is 11.
Another way to put a string in a Date is to use the Date.parse function; see
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_
Objects/Date/parse.
The date variable can be used as the value in the date, dateTime or time functions of the
formatter.
var myDate = formatter.date(date, "MM/dd/yyyy");
Page 196
Each
A generic iterator function, to iterate over the elements in the result set.
each(callback)
Iterates over the elements in a set, such as the enumerable properties of an object, in arbitrary
order. For each distinct property, statements can be executed.
callback
A function. The callback function is passed the iteration index and the current element. In the
scope of the callback function, this refers to the current element.
Examples
The following two scripts demonstrate a simple iteration over the elements in the results (the
set of HTML elements that match the selector of the script).
This script sets the background color of each of the elements to red. (This is just to demonstrate
how this function works. It is easier to change the style of a set of HTML elements using the css
() function; see "css()" on page 191.)
results.each(function(index){
results[index].css('background-color','red');
});
The following script adds a random integer to each element in the result set.
results.each(function(index){
var test = Math.floor((Math.random() * 10) + 1);
this.html(test);
});
Selector
Matched
element
Matched element after script
execution
p
3
1
7
This script gets the row index (of the current element in the set) and puts it in a paragraph.
Page 197
results.each(function(index){
this.text(index);
}
Selector
Matched
element
Matched element after script
execution
p
0
1
2
Using each() in a translation script
The following script first loads a snippet containing translation strings, depending on the value
of a field. Then it inserts translations by iterating over elements in the results (the set of HTML
elements that match the selector of the script) and setting the HTML of each element with a
value from the array of translation strings.
var strings = loadjson('snippets/' + record.fields.locale +
'.html');
results.each(function(index){
if( strings[this.attr('data-translate')])
this.html(strings[this.attr('data-translate')]);
});
Note: for documentation on the data-* attribute, see http://www.w3schools.com/tags/att_
global_data.asp.
Selector
Matched element
Matched element after script
execution
p
primero
último
dirección de correo
electrónico
Page 198
For...in
Can be used to iterate over fields in a data set or rows in detail table. Also see
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...in.
for(variable in object) { ... }
Iterates over the enumerable properties of an object, in arbitrary order. For each distinct
property, statements can be executed.
Examples
This script iterates over field names in the current record and adds them to a paragraph.
for(var i in record.fields){
results.after("" + i + "
");
}
Selector
Matched element
Matched element after script execution
#test
Fields
Fields
first
last
email
This script iterates over fields in the current record, retrieving their values. Then it adds the
values to a paragraph.
for(var i in record.fields){
results.after("" + record.fields[i] + "
");
}
Selector
Matched element
Matched element after script execution
#test
Fields
Fields
Peter
Parker
pparker@localhost.com
This script iterates over rows in a detail table and adds the contents of the 'country' field to a
paragraph.
Page 199
for(var i in record.tables['countries']) {
results.after("" + record.tables['countries'][i].fields
['country'] + "
");
}
Selector
Matched element
Matched element after script
execution
#countries
Countries
Countries
The Netherlands
Canada
Australia
This script iterates over rows in a detail table and adds the contents of the 'ItemID2' field to an
option. The ");
}
formatter
The formatter is a global object that allows you to format values in a script.
The Text Script Wizard also allows you to format variable data; see "Using the Text Script
Wizard" on page 338 and "Formatting variable data" on page 341.
Note
The TextFormatter object is now deprecated and will eventually be removed.
Functions
l
l
l
currency()
currencyNoSymbol
()
grouped()
The currency, grouped, integer and number functions allow you
to format a number, possibly with a custom pattern. See
Page 200
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
l
integer()
integerUngrouped
()
number()
numberUngrouped
()
"Number functions" on page 205.
date()
dateLong()
dateMedium()
dateShort()
dateTime()
dateTimeLong()
dateTimeMedium()
dateTimeShort()
timeLong()
timeMedium()
timeShort()
The date, dateTime and time functions allow you to format a
date and/or time. See "Date, date/time and time functions" on
page 192.
lowerCase()
upperCase()
properCase()
The text formatting functions transform all characters to
lowercase (lowerCase) or uppercase (upperCase) or transforms
the first character of each word to uppercase and all other
characters to lowercase (properCase).
loadhtml()
Global function that replaces the content (inner html) of each matched element in the result set,
alternatively load the data into a variable. The location should be an URL or a relative file path.
l
l
loadhtml(location)
loadhtml(location, selector)
Note
Loadhtml() is cached per batch run (based on the URL) in print/email.
loadhtml(location)
Loads all HTML from the HTML file.
Page 201
location
String containing a path that can be absolute or relative to the section/context. Use:
snippets/ to retrieve the content from a HTML file residing in the Snippets
folder on the Resources panel.
Examples
This script loads a local HTML snippet (from the Resources panel) directly into the matched
elements
results.loadhtml("snippets/snippet.html");
The following script loads a local HTML snippet (Resources panel) into a variable
The replaceWith() command is used to replace the element(s) matched by the script's selector
with the contents of the snippet.
var mysnippet = loadhtml('snippets/snippet.html');
results.replaceWith(mysnippet);
Same result as the previous script, but a different notation:
results.replaceWith(loadhtml('snippets/snippet.html'));
The following script loads a snippet into a variable and finds/replaces text in the variable before
inserting the content into the page. The second find command also adds formatting to the
replacing text.
var mysnippet = loadhtml('snippets/snippet.html');
mysnippet.find('@var1@').text('OL Connect 1');
mysnippet.find('@var2@').html('OL Connect 2').css('textdecoration','underline');
results.replaceWith(mysnippet);
This last script loads a snippet into a variable and retrieves an element from the snippet using
query().
var mysnippet = loadhtml('snippets/text-root-wrapped.html');
var subject = query("#subject", mysnippet).text();
results.append("" + subject +
"
");
loadhtml(location, selector)
Retrieve specific content from the filename.
Page 202
location
String; the location can be absolute or relative to the section/context. Use: snippets/ to retrieve the content from a HTML file residing in snippets folder of the Resources
panel.
selector
String. The supplied selector should conform to CSS selector syntax and allows you to
retrieve only the content of matching elements.
Examples
This script loads a specific element from the snippet.
var mysnippet = loadhtml('snippets/snippetselectors.html','#item3');
results.replaceWith(mysnippet);
This script loads the children of the selected element.
var snippet = loadhtml('snippets/snippet.html','foobar').children
();
results.replaceWith(snippet);
Another example is given in the following how-to: Using a selector to load part of a snippet.
loadjson()
Creates a JSON object based on the text retrieved from the supplied location. The function lets
you retrieve content from an JSON enabled server using a standard HTTP request. Popular
content management systems, like WordPress (requires JSON API plug-in) and Drupal provide
a JSON service/API to retrieve content.
l
loadjson(location)
Note
Loadjson() is cached per batch run (based on the URL) in print/email.
This online JSON viewer is handy to debug JSON data: http://jsonviewer.stack.hu
Page 203
loadjson(location)
Loads json data from a remote location.
location
String; the supplied location should be either a URL or a relative file path.
Examples
This sample script retrieves JSON data from a snippet.
var localJSON = loadjson('snippets/jsonsnippet.html');
if(localJSON.post){
results.html("" + localJSON.post.title + "
" +
localJSON.post.modified + "
");
}
This script retrieves a post from a WordPress site.
var wpPost = loadjson('http://192.168.101.58/2013/06/leave-thethird-dimension-behind-and-focus-on-real-printinginnovation/?json=1');
if(wpPost.post){
results.html("" + wpPost.post.title + "
"
+ wpPost.post.content);
}
This script retrieves multiple posts from a WordPress site.
var numPosts = 3;
var wpPost = '';
var wpRecentPosts = loadjson('http://192.168.101.58/?json=get_
recent_posts&count=' + numPosts);
if(wpRecentPosts.posts){
for (var i = 0; i < numPosts ; i++) {
wpPost += "" + wpRecentPosts.posts[i].title + "
";
}
}
results.after(wpPost)
Page 204
Number functions
l
l
l
l
l
l
l
currency()
currencyNoSymbol()
grouped()
integer()
integerUngrouped()
number()
numberUngrouped()
Note
The locale also influences the output of some Number functions; see "Locale" on page 421.
Tip
For fields that contain a number, you can also enter a formatting pattern directly in the Text Script
Wizard; see "Using the Text Script Wizard" on page 338, "Formatting variable data" on page 341
and Number patterns).
currency(value)
Formats a number as an amount of money. Which currency symbol and which thousands
separator are used depends on the Locale; see "Locale" on page 421.
value
A number. This can be a value from a field that contains a SmallInteger, BigInteger, Float,
SmallCurrency or LargeCurrency.
currency(value, pattern)
Formats a number as an amount of money using a custom pattern. Which currency symbol and
which thousands separator are used depends on the Locale; see "Locale" on page 421. For
available patterns, see see Number patterns.
value
A number. This can be a value from a field that contains a SmallInteger, BigInteger, Float,
SmallCurrency or LargeCurrency.
Page 205
pattern
A custom pattern that may consist of symbols; see Number patterns. Note that the repetition of
pattern letters plays a part in determining the exact presentation.
currencyNoSymbol(value)
Formats a number as a currency whilst omitting the currency symbol.
value
A number. This can be a value from a field that contains a SmallInteger, BigInteger, Float,
SmallCurrency or LargeCurrency.
grouped(value)
Formats a number using a thousands separator. Which separator is used depends on the
Locale, see "Locale" on page 421.
value
A number. This can be a value from a field that contains a SmallInteger, BigInteger, Float,
SmallCurrency or LargeCurrency.
prepend()
Insert content at the beginning of each element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 209). See also:
"append()" on page 183.
prepend(content)
Insert content as the first element to each element in the set of HTML elements that match the
selector of the script or of another query in the template (see "query()" on page 209). Append
creates a new result set.
content
HTML string, string or HTML string to insert after the matched elements. In case a plain text
string is provided, it is automatically wrapped in a element to avoid orphan text nodes
to appear in the element.
Examples
This script inserts a heading as the first element in an element that has the ID #box.
results.prepend("Personal information
");
Page 206
Selector
Matched element
Matched element after script execution
#box
Peter Parker
Personal information
Peter Parker
This script inserts a heading as the first element in an element that has the class name.
results.prepend("Name: ");
Selector
Matched element
Matched element after script execution
.name
Personal
information
Peter
Parker
Personal information
Name: Peter
Parker
This script inserts content in multiple elements at the same time.
results.prepend("Personal information
");
Selector
Matched element
Matched element after script execution
div
Peter Parker
Peter Parker
Personal information
Peter Parker
Personal information
Peter Parker
This script prepends a snippet that contains the text "Personal information
".
var a = loadhtml('snippets/snippet.html');
results.prepend(a);
Page 207
Selector
Matched element
Matched element after script execution
div
Peter Parker
Personal information
Peter Parker
This script uses the function query() to find a box. Then it inserts a heading as the first element
in that box.
query("#box").prepend("Personal information
");
Matched element
Matched element after script execution
Peter Parker
Personal information
Peter Parker
This script uses the function query() to find a box, prepends a heading and sets the text color of
the entire box to red.
query("#box").prepend("Personal information
").css
("color","red");
Matched element
Matched element after script execution
Peter Parker
Personal information
Peter Parker
Note: the way the functions prepend() and css() are used in this script is called 'chaining'.
Chaining is optional; the same could be achieved by storing the result of the query in a
variable:
Page 208
var box = query("#box");
box.prepend("Peter Parker
");
box.css("color","red");
query()
Creates a new result set containing the HTML elements that match the supplied CSS selector.
The context (optional) allows you to restrict the search to descendants of one or more context
elements.
l
l
query(selector)
query(selector, context)
query(selector)
Creates a new result set containing the HTML elements in the template that match the supplied
CSS selector.
selector
A String containing a CSS selector. See http://www.w3schools.com/cssref/css_selectors.asp
for CSS selectors and combinations of CSS selectors.
query(selector, context)
Creates a new result set containing the HTML elements that match the supplied CSS selector.
The context (optional) allows you to restrict the search to descendants of one or more context
elements.
selector
A String containing a CSS selector. See http://www.w3schools.com/cssref/css_selectors.asp
for CSS selectors and combinations of CSS selectors.
context
A result set or an HTML string. If the passed context is not a result set of HTML string it will be
coerced to a String and interpreted as HTML.
Examples
Look for an element with a certain ID
This scripts applies a style rule to the queried elements.
Page 209
query("#test1").css("color", "yellow");
Matched element
Matched element after script execution
foo
foo
Look for an element in a snippet
The following script loads a snippet. Then it looks up an element in a snippet and sets its text.
Finally, it replaces the elements matched by the script's selector by the snippet.
var snippet = loadhtml('snippets/mysnippet.html');
query("#foo", snippet).text("bar");
results.replaceWith(snippet);
CopyFile()
Examples
removeClass()
Removes the specified class from each element in this result set. Has no effect if the class is
not present.
removeClass(classname)
classname
String, space separated list of class names.
Examples
This script removes the class name "foo" from all elements in the results that have this class.
results.addClass("foo");
Selector
Matched element
Matched element after script execution
p
Hello world
Hello world
Page 210
replaceWith()
Replaces each element in a set of HTML elements.
replaceWith(content)
Replaces each element in a set of HTML elements. Returns the result set.
content
A query result. This can be an HTML string or a result set.
Examples
Replace elements with a snippet
The following script loads a snippet and then replaces the elements matched by the script's
selector with the snippet.
var snippet = loadhtml('snippets/mysnippet.html');
results.replaceWith(snippet);
Replace elements with a set of snippets
The following script loads snippets and adds their elements to a new, empty result set (using
query()). Then it replaces a placeholder in the template with the set of snippets.
var chapters = query();
for ( var i = 1; i <= 4; i++) {
chapters = chapters.add(loadhtml('snippets/Chapter' + i +
'.html'));
}
results.replaceWith(chapters);
Control Script API
When output is generated from a template, Control Scripts run before all other scripts. This topic
lists features that can only be used in Control Scripts and provides some sample scripts. See
"Control Scripts" on page 388 for more information about how to use this kind of scripts.
Objects available to pre-merge scripts
Channel
This is an enumeration for the output channels. The active output channel is registered in
merge.channel.
Page 211
Value
Description
EMAIL
The merge request is for output to Email
PRINT
The merge request is for output to Print
WEB
The merge request is for output to Web
THUMBNAIL
The merge request is for generating a template preview
ContextType
This is an enumeration for the context types.
Value
Description
HTML_EMAIL
The context is the Email context
PRINT
The context is the Print context
WEB
The context is the Web context
Merge
The root level instance of the object merge is the entry point in Control Scripts for the objects
and references required to query and modify various aspects.
Field
Type
Description
context
Context
The context rendered by this merge pass.
channel
Channel
The channel for which this merge pass is requested.
section
Section
The section being merged. Only available from non-control
template scripts AND when the output channel is WEB
(merge.channel == Channel.WEB) where it defines the requested
page.
template
Template
Template containing the context. This field can be used to find out
Page 212
which contexts are available in the template.
Context
Context is an object representing the respective context in the template. Which contexts are
available in the template can be queried using merge.template.contexts. The context being
merged can be queried using merge.context.
Field
Type
Description
sections
Array
Array of sections inside this context defined in the template.
type
ContextType
The context type.
Template
Template is an object representing the template. Which contexts are available in the template
can be queried using merge.template.contexts. The context being merged can be queried
using merge.context.
Field
Type
Description
contexts
Array
Array of contexts available in the template.
Section
A section object relating to a section in the template. This type can be used to query and modify
the output behavior for when the related context/section is merged.
Field
Type
Description
enabled
boolean
Enables or disables this section for output. Note
that even if a section is disabled the part and
restartPageNumber fields are still effective to
define the parts division and page numbering over
multiple sections when applicable.
The default enabled state for sections (before any
control script runs) is as follows (to emulate the
Page 213
behavior of previous versions):
For Web channel requests the requested web
section is enabled by default. It is possible to
redirect to another section by disabling the
requested section and enabling another section.
For Email channel requests on the Web context
only the default section is enabled by default. It is
possible to enable different or multiple sections, to
control which sections will be attached to the
email.
For Email channel requests on the Print context
all Print sections are enabled by default. It is
possible to enable different or multiple sections to
control which sections will be attached to the
email.
For Print channel requests on the Print context all
sections are enabled by default.
name
[READONLY]
String
The name of the section as shown in the
resources view. Note that sections cannot have an
integer as name. The name should always
include alphanumeric characters. See "
Renaming a section" on page 393.
part
String
Name for the part. This is used for channels that
can output separate and/or named parts. The
Email output, for example, can attach 3 PDF's
generated from the Print context. Part is used to
specify where a new part starts and the title for the
part. When used for Email attachments, the part
title is used as the file name for the attachment.
restartPageNumber
boolean
Enables or disables a restart of the page
numbering. When generating Print output this can
be used to let page numbering continue over
multiple sections.
The default value is false, meaning that each
Page 214
section will start with page 1 (to emulate behavior
of previous versions).
BackgroundResource
This is an enumeration for the types of background resources for a Print section.
Field
Description
DATAMAPPER_
PDF
A PDF file retrieved via the active Data Mapping Configuration. This
can be the PDF file that was used as input file, or another type of input
file, converted to PDF.
NONE
No PDF background.
RESOURCE_
PDF
A PDF file stored in the template or on the network. Note that it isn't
possible to use a remotely stored PDF file as a section's background.
MediaPositon
This is an enumeration for the position of background resources (background.position) for a
Print section.
Field
Description
ABSOLUTE
Places the PDF at a specific location on the page. Set the background's top
(background.top) and left (background.left) measured from the top
and left side of the section.
CENTERED
Centers the PDF on the page, vertically and horizontally.
FIT_TO_
MEDIA
Stretches the PDF to fit the page size.
Pitfalls to avoid
When using merge.context or merge.section make sure to check for the appropriate
conditions.
Page 215
l
l
merge.section is only defined when when the output channel is Web. To make sure
that it is defined, use the following if statement: if (merge.channel ==
Channel.WEB && merge.context.type == ContextType.WEB) { ... }.
When using merge.context.sections keep in mind that for example 'Section X'
might only exist in your Print context, so using merge.context.sections
['Section X'] without enclosing it in the if statement if
(merge.context.type == ContextType.PRINT) {} will yield an error when
the script runs for other contexts. Instead of enclosing it in an if statement, you can use
the template object to access a specific context:
merge.template.contexts.PRINT.sections['Section X'] .
Sample scripts
Conditionally skipping or printing Print sections
var printSections = merge.template.contexts.PRINT.sections;
printSections['Section EN'].enabled = false;
printSections['Section FR'].enabled = false;
if(record.fields.Language === 'FR'){
printSections['Section FR'].enabled = true;
} else {
printSections['Section EN'].enabled = true;
}
Selecting different sections for Print output and Email PDF attachment
var printSections = merge.template.contexts.PRINT.sections;
if(merge.channel === Channel.EMAIL){
printSections['Section 1'].enabled = false;
printSections['Section 2'].enabled = true;
}
if(merge.channel === Channel.PRINT){
printSections['Section 1'].enabled = true;
printSections['Section 2'].enabled = false;
}
Setting the name of Email PDF attachments
var section = merge.template.contexts.PRINT.sections['Section 1'];
section.part = 'Invoice ' + record.fields['InvoiceNo'];
Page 216
Controlling multiple Email attachments
The following script attaches the following sections to an email:
l
l
l
Print section 3 + 4 as attachment with continued page numbers
Print section 6 as separate attachment
Web sections A and B as separate attachment
if (channel == Channel.EMAIL) { // only when generating Email
output
if (merge.context.type == ContextType.PRINT) {
merge.context.sections['Section 1'].enabled = false;
merge.context.sections['Section 2'].enabled = false;
merge.context.sections['Section 3'].enabled = true;
merge.context.sections['Section 3'].part = "PDFAttach1";
merge.context.sections['Section 4'].enabled = true;
merge.context.sections['Section 4'].restartPageNumber = false;
merge.context.sections['Section 5'].enabled = false;
merge.context.sections['Section 6'].enabled = true;
merge.context.sections['Section 6'].part = "PDFAttach2";
} else if (merge.context.type == ContextType.WEB) {
merge.context.sections['default Section'].enabled = false; //
disable whatever is the default section
merge.context.sections['Section A'].enabled = true;
merge.context.sections['Section A'].part = "WebPartA";
merge.context.sections['Section B'].enabled = true;
merge.context.sections['Section B'].part = "WebPartB";
}
}
Note
For another example, see this how-to: Output sections conditionally.
Setting the background of a Print section
The following script sets the background for a section called 'Policy' to RESOURCE_PDF and
specifies a path for it, using a data value:
// Enable the section background and specify that the PDF should be
read
Page 217
// from a resource file rather than using a PDF DataMapper
background
merge.template.contexts.PRINT.sections['Policy'].background.source
= BackgroundResource.RESOURCE_PDF;
// Specify the path
var resourceUrl = 'images/policy-' + record.fields.policy + '.pdf';
merge.template.contexts.PRINT.sections['Policy'].background.url =
resourceUrl;
Positioning the background of a Print section
Using abolute positioning
var activeSection = merge.template.contexts.PRINT.sections['Section
1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.ABSOLUTE;
activeSection.background.left = "10mm";
activeSection.background.top = "10mm";
activeSection.background.url = "images/somepage.pdf";
Scaling to Media size
var activeSection = merge.template.contexts.PRINT.sections['Section
1'];
activeSection.background.source = BackgroundResource.RESOURCE_PDF;
activeSection.background.position = MediaPosition.FIT_TO_MEDIA;
activeSection.background.url = "images/somepage.pdf";
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
page 423.
2. Fill the template
Add text, images and other elements to the template and style them. See "Content
elements" on page 223 and "Styling and formatting" on page 398.
Page 218
3. Personalize the content
Personalize the content using variable data. See "Personalizing Content" on page 325.
4. Generate output
Adjust the settings, test the template and generate output: letters, emails, and/or web
pages. See Skin/Formats/CrossReferencePrintFormat("Generating outputWhen merged
with a record set, the templates made in the Designer can generate three types of output:
Print, Email and Web.Print outputPrint 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 Generate Print output). The Print context can also be added to Email output as a
PDF attachment; see Generating Email output. 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. To dynamically select a section for output, use a Control
Script; see Control Scripts.There is a number of settings in the Print context and Print
sections that have an impact on how the Print context is printed; see Print settings in the
Print context and sections.To split the Print output into several files, see Splitting printing
into more than one file.Email outputThe Email context outputs HTML email with
embedded formatting to an email client through the use of an email server. The HTML
generated by this context is meant to be compatible with as many clients and as many
devices as possible.Although the Email context can contain multiple Email templates,
only one of them can be merged with each record. Which one is used, depends on a
setting; see Email output settings in the Email context and sections.Email Output can be
generated in two different ways: from the Designer or via Workflow. In both cases, email is
sent in a single batch for the whole record set. To test a template, you can send a test
email first. Output, generated from an Email template, can have the following
attachments:The contents of the Print context, in the form of a single PDF attachment. The
output of the Web context, as an integral HTML file.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 Generating Email output. To learn how to attach other files,
see Email attachments.Web output The Web context outputs an HTML web page that
contains the HTML text and all the resources necessary to display it.Web output can be
generated in two different ways: it can be attached to an Email template when generating
Email output (see above), or it can be generated using Workflow; see Generating Web
output.Although the Web context can contain multiple Web pages, only one of them can
be merged with each record. Which one is used, depends on a setting; see Web output
settings in the Web context and sections." on page 1).
5. What's next
Use Workflow to automate your customer communications.
Page 219
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.
Features
The Designer is Connect's module to create templates for personalized customer
communications. These are some of the key features in the Designer:
"Contexts" on the next page. A context contains one or more designs for one output channel.
"Content elements" on page 223. Elements make up the biggest part of the content of each
design.
"Email" on page 297. Email is one of the intended output channels. This topics helps you
design an email template.
Skin/Formats/CrossReferencePrintFormat("Generating outputWhen merged with a record set,
the templates made in the Designer can generate three types of output: Print, Email and
Web.Print outputPrint 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 Generate Print
output). The Print context can also be added to Email output as a PDF attachment; see
Generating Email output. 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. To
dynamically select a section for output, use a Control Script; see Control Scripts.There is a
number of settings in the Print context and Print sections that have an impact on how the Print
context is printed; see Print settings in the Print context and sections.To split the Print output
into several files, see Splitting printing into more than one file.Email outputThe Email context
outputs HTML email with embedded formatting to an email client through the use of an email
server. The HTML generated by this context is meant to be compatible with as many clients and
as many devices as possible.Although the Email context can contain multiple Email templates,
only one of them can be merged with each record. Which one is used, depends on a setting;
see Email output settings in the Email context and sections.Email Output can be generated in
two different ways: from the Designer or via Workflow. In both cases, email is sent in a single
batch for the whole record set. To test a template, you can send a test email first. Output,
Page 220
generated from an Email template, can have the following attachments:The contents of the Print
context, in the form of a single PDF attachment. The output of the Web context, as an integral
HTML file.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 Generating Email
output. To learn how to attach other files, see Email attachments.Web output The Web context
outputs an HTML web page that contains the HTML text and all the resources necessary to
display it.Web output can be generated in two different ways: it can be attached to an Email
template when generating Email output (see above), or it can be generated using Workflow;
see Generating Web output.Although the Web context can contain multiple Web pages, only
one of them can be merged with each record. Which one is used, depends on a setting; see
Web output settings in the Web context and sections." on page 1). Learn the ins and outs of
generating output from each of the contexts.
"Personalizing Content" on page 325. Personalize your customer communications using
variable data.
"Print" on page 351. Print is one of the intended output channels. This topic helps you design
and fill sections in the Print context.
"Sections" on page 392. Sections in one context are designed for the same output channel.
"Snippets" on page 396. Snippets help share content between contexts, or insert content
conditionally.
"Styling and formatting" on page 398. Make your Designer templates look pretty and give them
the same look and feel with style sheets.
"Templates" on page 423. Start creating, using and sharing templates.
"Web" on page 444. Web is one of the intended output channels. This topic helps you design a
web page.
"Write your own scripts" on page 376. Scripting can take personalization much further. Learn
how to script via this topic.
Contexts
Contexts are parts of a template that are each used to generate a specific type of output: Web,
Email or Print.
Page 221
l
l
l
The Print context outputs documents to either a physical printer a PDF file; see "Print
context" on page 352.
The Email context outputs HTML email, composed of HTML code with embedded CSS.
See "Email context" on page 298.
The Web context outputs an HTML web page. See "Web Context" on page 444.
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" below.
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 428.
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 320, "Generating Print output" on page 309 and
"Generating Web output" on page 323.
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 388.
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 page 392.
Page 222
Deleting a context
To delete a context, right-click the context on the Resources pane and 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.
Content elements
Once you have created template, it can be filled with all kinds of elements, from text to barcodes
and from tables to fields on a web form. All types of elements are listed on this page; see below.
There are several ways to insert elements, see "Inserting an element" on page 226.
Each element can have an ID and a class, as well as a number of other properties, depending
on the element's type. When an element is selected, its properties can be changed; see
"Selecting an element" on page 227, "Attributes" on page 225 and "Styling and formatting an
element" on page 227.
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
the Designer; see "Editing HTML" on the facing page.
Element types
The following types of content can be added to the content of a template:
l
l
l
l
l
"Images" on page 279 and "Dynamic Images" on page 346
"Text and special characters" on page 285
"Date" on page 267
"Table" on page 283and "Dynamic table" on page 347
"Boxes" on page 265: Positioned Box, Inline Box, Div and Span
Page 223
Tip
Wrapping elements in a box (see "Boxes" on page 265) or in a semantic HTML
element makes it easier to target them in a script or a style sheet. Place the cursor
in the element or select multiple elements. Then, on the menu, click Insert > Wrap
in Box. You can now use the wrapper element as a script's or style's selector; see
"Using the Text Script Wizard" on page 338 and "Styling and formatting" on page
398.
l
l
l
l
l
l
l
l
l
l
"Hyperlink and mailto link" on page 277
"Barcode" on page 228
Web "Forms" on page 269 and Web "Form Elements" on page 272
"COTG Elements" on page 293
"Whitespace elements: using optional space at the end of the last page" on page 364
(Print context only)
"Page numbers" on page 365 (Print context only)
Article, Section, Header, Footer, Nav and Aside are HTML5 semantic elements; see
http://www.w3schools.com/html/html5_semantic_elements.asp
Other HTML elements: Heading, Address and Pre
"Snippets" on page 396: a Snippet is a small, ready-to-use piece of content in a file
Business graphics
Most elements are suitable for use in all contexts. There are a few exceptions, however. Forms
and Form elements can be used on web pages only, whereas Whitespace elements and Page
numbers can only be used in a Print context. Positioned boxes are well suited for Print
sections, but are to be avoided in the Email and Web context.
Whether it is best to use a Table or Box to position text, images and other elements, depends
on the context in which they are used; see "How to position elements" on page 410 for more
information.
Editing HTML
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file.
To see this, toggle to the Design tab in the workspace. Click anywhere in the content. Take a
look at the breadcrumbs at the top of the workspace. The breadcrumbs show the HTML tag of
Page 224
the clicked element, as well as the HTML tags of other elements to which the clicked element
belongs. The clicked element is at the end of the line.
To edit the HTML text directly:
l
In the workspace, toggle to the Source tab.
On this tab you can view and edit the content of the template in the form of plain text with HTML
tags (note the angle brackets: <>). You may add and edit the text and the HTML tags, classes,
ID’s and other attributes.
To learn more about HTML, see for example https://developer.mozilla.org/enUS/docs/Web/Guide/HTML/Introduction and http://www.w3schools.com/html/default.asp.
Many video courses and hands-on courses about HTML (and CSS) are offered on the Internet
as well, some for free. Go, for example, to www.codeschool.com or www.codeacademy.com
and look for HTML (and CSS) courses.
Attributes
ID and class
Every element in the content of a template can have an ID and a class. ID's and classes are
particularly useful with regard to variable data (see "Personalizing Content" on page 325) and
styling (see "Styling templates with CSS files" on page 399).
You can specify an ID and/or class when you add the element to the content.
To add an ID and/or class to an element that has already been added to a template, select the
element (see "Selecting an element" on page 227) and type an ID and/or a class in the
respective fields on the Attributes pane at the top right.
Other attributes
Apart from the ID and class, elements can have a varying number of properties, or 'attributes' as
they're called in HTML (see "Editing HTML" on the previous page). Which properties an
element has, depends on the element itself. An image, for example, has at least four attributes:
src (the image's URL), alt (alternate text), width and height. These attributes are visible on the
Attributes pane when you click an image in the content.
Page 225
For each type of element, a small selection of attributes is visible on the Attributes pane at the
top right.
Changing attributes via script
Many attributes can be changed via the user interface. Another way to change attributes is by
using a script.
Any of the Script Wizards can produce a script that changes an attribute of an HTML element.
Set the Options in the Script Wizard to Attribute, to output the script's results to the value of a
specific attribute. See "Using the Text Script Wizard" on page 338.
In code, you can change an element's attribute using the function attr(); see "Write your own
scripts" on page 376 and "API" on page 174.
Inserting an element
To insert an element in the content of a template:
1. Click the respective toolbar button. Alternatively, click the element on the Insert menu.
2. Add an ID and/or a class. ID's and classes are particularly useful with regard to variable
data (see "Personalizing Content" on page 325) and styling (see "Styling templates with
CSS files" on page 399).
3. Use the Location drop-down to select where to insert the element.
l
l
l
l
l
At cursor position: The element is inserted where the cursor is located in the
template.
Before element: The element is inserted before the current HTML element where
the cursor is located. For example if the cursor is within a paragraph, insertion
occurs before the tag.*
After start tag: The element is inserted within the current HTML element, at the
beginning, just after the start tag.*
Before end tag: The element is inserted within the current HTML element, at the
end, just before the end tag.*
After element: The element is inserted after the current element where the cursor is
located. For example if the cursor is within a paragraph, insertion occurs after the
end tag of the paragraph (
).*
* If the current element is located inside another element, use the Elements drop-down to
select which element is used for the insertion location. The list displays every element in
the breadcrumbs, from the current selection point until the root of the body.
Page 226
Selecting an element
When an element is selected, the Attributes pane shows the attributes of that element, and the
Styles pane, next to the Attributes pane, shows which styles are applied to it.
To select an element in the content, you can of course click on it, but this isn't always as easy
as it seems, especially when the element has elements inside it.
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.
There are two more ways to select an element in the content:
l
l
Use the Breadcrumbs at the top of the workspace.
Breadcrumbs show the HTML tag of the clicked element, as well as the HTML tags of
'parent elements': elements inside of which the clicked element is located. The clicked
element is at the end of the line.
Elements with classes or IDs show these details next to them, for instance div
#contents > ol.salesitems > li. Click any of the elements in the Breadcrumbs
to select that element.
If an element is selected in the Breadcrumbs and the Backspace key is pressed, that
element is deleted.
Use the Outline pane. You can find this pane next to the Resources pane. It displays a
tree view of the elements in the file. Click an element in the tree view to select it.
Styling and formatting an element
Format elements directly
Images and other graphical elements can be resized by clicking on them and dragging the
resize handles. There are toolbar buttons to color, indent or style text. Other toolbar buttons can
Page 227
left-align, right-align, or rotate graphical elements.
The toolbar buttons only represent a selection of the formatting options for each element. There
are no toolbar buttons to change an element's margins, or to add a border to it, for example. To
access all formatting properties of an element, you have to open the Formatting dialog. There
are two ways to do this:
l
l
Right-click the element and select the type of element on the shortcut menu.
Select the element (see "Selecting an element" on the previous page) and select the type
of element on the Format menu.
See "Styling and formatting" on page 398 for more information about the formatting options.
Format elements via Cascading Style Sheets (CSS)
It is recommended to use style sheets in your templates right from the start, even more so if your
communications are going to be output to different output channels, or if they consist out of
different sections (for example, a covering letter and a policy). With CSS you can give your
templates one look and feel. A style sheet can change the look of multiple elements, making it
unnecessary to format each and every element in the template, time and again, when the
company's layout preferences change, for example. See "Styling templates with CSS files" on
page 399.
Barcode
In PlanetPress Connect Designer, you can add a variety of barcodes to your template. The
supported Barcode types include 1d barcodes (the striped ones) and 2d barcodes (encoded
horizontally and vertically).
Adding a Barcode
Note
When generating Print output, you can add extra barcodes and OMR marks. The reason why you
would do this, is that at merge time more information is available about the actual output document.
The page count, for example, is not available at design time.
To add barcodes and OMR marks on the fly when generating Print output, select File > Print and
check the option Add additional content (see "Additional Text" on page 543) in the Print
Wizard. To have this done automatically, save this and other output options in an Output Creation
Page 228
Preset: select File > Print presets > Output Creation Settings (see "Output Creation
Settings" on page 587) and send the preset to Workflow.
Before adding a Barcode, load data or at least a Data Model; see "Loading data" on page 327.
You will need the field names when adding the Barcode. Then, to add a Barcode to a section,
Master Page or snippet:
1.
2.
3.
4.
Select Insert > Barcode on the menu or click the Barcode toolbar button
Choose the desired barcode type. The list is divided between 1d and 2d barcodes.
An ID is required. You can change the given ID and, optionally, add a class.
Use the Location drop-down to select where to insert the Barcode.
l
l
l
l
l
l
At cursor position inserts the Barcode where the cursor is located in the template.
Before element inserts it before the HTML element in which the cursor is currently
located. For example if the cursor is within a paragraph, the Barcode is inserted
before the tag.*
After start tag inserts it within the current HTML element, at the beginning, just after
the start tag.*
Before end tag inserts it within the current HTML element, at the end, just before
the end tag.*
After element inserts it after the element in which the cursor is currently located. For
example if the cursor is within a paragraph, the Barcode is inserted after the end tag
of the paragraph (
).*
Absolute on body inserts the Barcode in an absolute-positioned box inside the
of the HTML, but outside other elements.
* If the current element is located inside another element, use the Elements drop-down to
select which element is used for the insertion location. The list displays every element in
the breadcrumbs, from the current selection point until the root of the body.
5. Under Script, select the field that contains the barcode value, or select the fields that
together compose the barcode value. When you select more than one field, the script puts
the values of the selected fields in one string and passes that to the barcode generator.
The barcode type dictates the length and exact format of the required value.
For barcodes that require a Checksum, the Designer can calculate a Checksum if that
isn't provided by your data. Then script result should be the required value minus the
Checksum. Edit the barcode properties to include the calculated Checksum with the
barcode value, after adding the barcode to the template; see below.
Page 229
Note
For a detailed description or for background information on a specific barcode,
please refer to the documentation provided by the individual barcode supplier. Note
that some barcode readers may require specific parameters as well.
6. Click OK to close the dialog.
In the template the barcode shows up as a gray box. The barcode script is added to the Scripts
pane. To see the barcode script working, toggle to the Preview tab in the Workspace.
Changing a barcode
Barcode script
The barcode script determines which value is fed to the barcode generator. Double-click the
script on the Scripts pane to change which field(s) are added to the barcode value.
Barcode properties
A barcode is always added with the barcode type's default properties. To change those
properties, such as the scale and color, open the Barcode properties dialog: right-click the
barcode (on the Design tab in the Workspace) and select the respective barcode on the
shortcut menu.
Click the barcode type below for information about its properties.
l
l
l
l
l
l
l
l
l
l
l
l
l
"Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5"
on page 251
"Code 39, Code 39 extended" on page 237
"UPC-A, UPC-E, EAN-8, EAN-13" on page 263
"OneCode, KIX Code, Royal Mail, Australia Post" on page 261
"Code 128" on page 240
"GS1-128" on page 245
"Codabar" on page 234
"MSI" on page 253
"IMPB" on page 247
"Postnet" on page 257
"QR Code" on page 259
"Data Matrix" on page 241
"Royal Mail Mailmark" on page 262
Page 230
l
l
l
"PDF417" on page 255
"Aztec Code" on the facing page
"MaxiCode" on page 252
Tip
As of version 1.5 it will be possible to change the type of a barcode in the template as well, when
changing the properties of a barcode.
OneCode, KIX Code, Royal Mail, Australia Post
OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on the
previous page.
Height, width and spacing
The height, width and spacing of the barcode are all measured in pixels (38 dpi).
l
l
l
l
Bar height: the height of the (shorter) bars
Extended bar height: the total height of the extended bars
Bar width: the width of the bars
Spacing: the distance between the bars
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
Page 231
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Aztec Code
Aztec is one of the types of barcodes that can be added to a template; see "Barcode" on page
228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type Aztec. For the properties of other barcode
types, see "Barcode properties" on page 230.
Module size
Enter the size of the square modules in pixels
Page 232
Configuration type
Use the drop-down to select the format type used when creating the barcode: only full range
format, only compact formats, or any format.
Preferred configuration
Use the drop-down to select the preferred format for the barcode. Note that the barcode
generator may choose a different format if the data cannot be represented by the preferred
format.
Encoding
Use the drop-down to select the encoding type:
l
l
Normal can encode any character but is not very efficient for encoding binary values
(above 128)
Binary is to be used only if the data contains many bytes/characters above 128.
Error Correction Level
This option reserves a percentage of the symbol capacity for error correction. The
recommended percentage for this type of barcode is 23.
Rune
When set to a value between 0 and 255, an Aztec Rune corresponding to the selected value is
created. Set the Rune to -1 to disable this feature.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Page 233
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Codabar
Codabar is one of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the Codabar barcode. For the properties of other barcode types,
see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Start Char and Stop Char
Use the drop-down to select the start and stop character for the barcode, which defines the
encoding mode. Available characters are A, B, C.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Page 234
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the following barcode types :
Page 235
l
l
l
l
l
l
Code 11
Code 93
Code 93 extended
Industrial 2 of 5
Interleaved 2 of 5
Matrix 2 of 5
For the properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 236
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 39, Code 39 extended
Code 39 and Code 39 extended are two of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode types Code 39 and Code 39 extended. For the
properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Inter Character Gap
Two adjacent characters are separated by an inter-character gap. A value of 1 means that the
separator will have the same length as the width of the narrow bars (in centimeters).
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
Page 237
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the following barcode types :
l
l
l
l
Code 11
Code 93
Code 93 extended
Industrial 2 of 5
Page 238
l
l
Interleaved 2 of 5
Matrix 2 of 5
For the properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 239
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 128
Code 128 is one of the types of barcodes that can be added to a template; see "Barcode" on
page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type Code 128. For the properties of other barcode
types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Code set
Set of characters to be used:
l
l
l
A: ASCII characters 00 to 95 (0–9, A–Z and control codes), special characters, and FNC
1–4
B: ASCII characters 32 to 127 (0–9, A–Z, a–z), special characters, and FNC 1–4
C: 00–99 (encodes each two digits with one code) and FNC 1
In Auto mode, the barcode generator will automatically select the correct encoding mode (set A,
B or C) according to the input data.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
Page 240
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Data Matrix
Data Matrix is one of the types of barcodes that can be added to a template; see "Barcode" on
page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Page 241
Barcode properties
This topic lists the properties of the QR barcode. For the properties of other barcode types, see
"Barcode properties" on page 230.
Dots per pixel
Type the number of dots per pixel. To optimize barcode quality a Data Matrix symbol should not
be printed with dots smaller than 4 pixels.
Encoding
The data represented in the symbol can be compressed using of the following algorithms.
l
l
l
l
l
l
ASCII is used to encode data that mainly contains ascii characters (0-127)
C40 is used to encode data that mainly contains numbers and uppercase characters.
Text is used to encode data that mainly contains numbers and lowercase
Base256 is used to encode 8 bit values
Auto Detect automatically detects the data content and encodes using the most
appropriate method.
None does not use any encoding.
Preferred format
Use the drop-down to select the size of the Data Matrix.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 242
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
UPC-A, UPC-E, EAN-8, EAN-13
UPC-A, UPC-E, EAN-8 and EAN-13 are a few of the barcode types that can be added to a
template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode types UPC-A, UPC-E, EAN-8 and EAN-13. For the
properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Show guardbars
Checking this option adds guardbars to the barcode. Guardbars are bars at the start, in the
middle and at the end that help the barcode scanner to scan the barcode correctly.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Page 243
Supplement
UPC-A, UPC-E, EAN-13, and EAN-8 may all include an additional barcode to the right of the
main barcode.
l
Type: The supplement type can be 2-digit (originally used to indicate the edition of a
magazine or periodical) or 5-digit (used to indicate the suggested retail price for books). In
case this option is set to None, and the data includes digits for the 2 or 5 supplement, the
supplement data will be skipped and the additional barcode will not be rendered.
Note
When the chosen supplement type doesn't match the data, the supplement data will
be skipped and the additional barcode will not be rendered.
l
l
Height Factor: This is the relative height of the supplement's bars compared to the
normal bars.
Space Before : Defines the space between the main symbol and the supplement, in cm.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Page 244
GS1-128
GS1-128 is one of the types of barcodes that can be added to a template; see "Barcode" on
page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type GS1-128. For the properties of other barcode
types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Page 245
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
OneCode, KIX Code, Royal Mail, Australia Post
OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on page
230.
Height, width and spacing
The height, width and spacing of the barcode are all measured in pixels (38 dpi).
l
l
l
l
Bar height: the height of the (shorter) bars
Extended bar height: the total height of the extended bars
Bar width: the width of the bars
Spacing: the distance between the bars
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
Page 246
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
IMPB
IMPB is one of the barcode types that can be added to a template; see "Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type IMPB. For the properties of other barcode
types, see "Barcode properties" on page 230.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 247
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the following barcode types :
l
l
l
l
l
l
Code 11
Code 93
Code 93 extended
Industrial 2 of 5
Interleaved 2 of 5
Matrix 2 of 5
For the properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Page 248
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the following barcode types :
Page 249
l
l
l
l
l
l
Code 11
Code 93
Code 93 extended
Industrial 2 of 5
Interleaved 2 of 5
Matrix 2 of 5
For the properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 250
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5
Code 11, Code 93, Code 93 extended, Industrial 2 of 5, Interleaved 2 of 5, and Matrix 2 of 5 are
a few of the barcode types that can be added to a template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the following barcode types :
l
l
l
l
l
l
Code 11
Code 93
Code 93 extended
Industrial 2 of 5
Interleaved 2 of 5
Matrix 2 of 5
For the properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Page 251
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
MaxiCode
MaxiCode is one of the barcode types that can be added to a template; see "Barcode" on page
228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the MaxiCode barcode. For the properties of other barcode
types, see "Barcode properties" on page 230.
Page 252
Resolution
Select the printer output definition for the barcode (200, 300, 400, 500 or 600 dpi).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
MSI
MSI is one of the types of barcodes that can be added to a template; see "Barcode" on page
228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type MSI. For the properties of other barcode types,
see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Page 253
Add Checksum
When checked, PlanetPress Connect will calculate a Checksum character and add that to the
result of the Barcode script. If the value to be encoded is longer than 10 digits, a second check
character will be calculated.
Checksum Type
The Checksum type can be MSI10, MSI11, MSI1010 or MSI1110; see
https://en.wikipedia.org/wiki/MSI_Barcode.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
OneCode, KIX Code, Royal Mail, Australia Post
OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Page 254
Barcode properties
This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on page
230.
Height, width and spacing
The height, width and spacing of the barcode are all measured in pixels (38 dpi).
l
l
l
l
Bar height: the height of the (shorter) bars
Extended bar height: the total height of the extended bars
Bar width: the width of the bars
Spacing: the distance between the bars
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
PDF417
PDF417 is one of the types of barcodes that can be added to a template; see "Barcode" on
page 228.
Page 255
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type PDF417. For the properties of other barcode
types, see "Barcode properties" on page 230.
Mode
Use the drop-down to set the compaction mode:
l
l
l
Binary: allows any byte value to be encoded
Text: allows all printable ASCII characters to be encoded (values from 32 to 126 and
some additional control characters)
Numeric: a more efficient mode for encoding numeric data
Error Correction Level
Use the drop-down to select the built-in error correction method based on Reed-Solomon
algorithms. The error correction level is adjustable between level 0 (just error detection) and
level 8 (maximum error correction). Recommended error correction levels are between level 2
and 5, but the optimal value depends on the amount of data, printing quality of the PDF417
symbol and decoding capabilities of the scanner.
Nr. of Columns
The number of data columns can vary from 3 to 30.
Nr. of Rows
A PDF417 bar code can have anywhere from 3 to 90 rows.
Bar height
Defines the height of the bars for a single row measured in pixels drawn.
Page 256
Compact
Check this option to use Compact PDF417 instead of the PDF417 barcode. This shortened
form of the PDF417 barcode is useful where the space for the symbol is restricted.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Postnet
Postnet is one of the barcode types that can be added to a template; see "Barcode" on page
228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Page 257
Barcode properties
This topic lists the properties of the barcode type Postnet. For the properties of other barcode
types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Bar height
You can set the height (in cm) of the short bars and the tall bars in the Postnet barcode.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Page 258
QR Code
A QR Code is one of the types of barcodes that can be added to a template; see "Barcode" on
page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the QR barcode. For the properties of other barcode types, see
"Barcode properties" on page 230.
Module size
Enter the size of the square modules in pixels.
Auto configure
When this option is checked, the barcode generator overwrites the selected Preferred version
(see below) and defines the barcode version based on the supplied data.
Preferred version
There are 40 sizes of QR codes. Select the preferred version for the QR code.
Encoding
This option defines the encoding of the barcode. When Auto is selected, the barcode generator
determines the encoding based on the supplied string. The other options are:
l
l
l
l
Numeric: 10 bits per 3 digits, with a maximum of 7089 numerical characters.
Alphanumeric: 11 bits per 2 characters, with a maximum of 4296 alphanumerical
characters.
Byte: 8 bits per character, with a maximum of 2953 characters.
Kanji: 13 bits per character, with a maximum of 1817 characters.
Page 259
Extended Channel Interpretation (ECI)
This setting enables data using character sets other than the default set. Select Latin-1, Shift
JIS or UTF-8, or select None to disable extended channel interpretation.
Correction level
Part of the robustness of QR codes in the physical environment is their ability to sustain
'damage' and continue to function even when a part of the QR code image is obscured,
defaced or removed. A higher correction level duplicates data within the QR Code to that effect,
making it larger.
FNC
Use the drop-down to either disable FNC or select a FNC option:
l
l
First: This mode indicator identifies symbols encoding data formatted according to the
UCC/EAN Application Identifiers
Second: This mode indicator identifies symbols formatted in accordance with specific
industry or application specifications previously agreed with AIM International. You must
then set a value for the Application Indicator property.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
Page 260
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Barcode Data
QR Codes can have many different types of data, which determines how the code will be
generated. On top of just straightforward data, special data structures are used to trigger actions
on the device that reads them. This can include contact cards, phone numbers, URLs, emails,
etc.
To learn more about the specifications of the different QR code types, see the ZXing Project
barcode contents page.
OneCode, KIX Code, Royal Mail, Australia Post
OneCode, KIX Code, Royal Mail and Australia Post are some of the types of barcodes that can
be added to a template; see "Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode types OneCode, KIX Code, Royal Mail and
Australia Post. For the properties of other barcode types, see "Barcode properties" on page
230.
Height, width and spacing
The height, width and spacing of the barcode are all measured in pixels (38 dpi).
l
l
l
l
Bar height: the height of the (shorter) bars
Extended bar height: the total height of the extended bars
Bar width: the width of the bars
Spacing: the distance between the bars
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
Page 261
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Royal Mail Mailmark
Royal Mail Mailmark is one of the types of barcodes that can be added to a template; see
"Barcode" on page 228.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Barcode properties
This topic lists the properties of the barcode type Royal Mail Mailmark. For the properties of
other barcode types, see "Barcode properties" on page 230.
Module width
The recommendation is to print these barcodes with a module size of 0.5 mm, which equates to
6 dots when printed at 300dpi. The maximum module size for printing is 0.7 mm.
Page 262
Preferred version
Use the drop-down to select the size of the barcode, in a number of modules. The actual size of
the barcode can be 12 mm x 12 mm up to 22.4 mm x 22.4 mm, depending on the preferred
version and the module width.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
UPC-A, UPC-E, EAN-8, EAN-13
UPC-A, UPC-E, EAN-8 and EAN-13 are a few of the barcode types that can be added to a
template.
The barcode can be added either using the Barcode toolbar button or through selecting Insert
> Barcode on the menu; see " Adding a Barcode" on page 228.
Initially the barcode will have the barcode type's default properties. To change those properties,
such as the scale and color, open the Barcode properties dialog: right-click the barcode (on the
Design tab in the Workspace) and select the barcode type on the shortcut menu.
Page 263
Barcode properties
This topic lists the properties of the barcode types UPC-A, UPC-E, EAN-8 and EAN-13. For the
properties of other barcode types, see "Barcode properties" on page 230.
Module width
Specifies the width of the narrow bars in centimeters. Changing this value to a higher value will
make the barcode bigger when Scale is set to None.
Show guardbars
Checking this option adds guardbars to the barcode. Guardbars are bars at the start, in the
middle and at the end that help the barcode scanner to scan the barcode correctly.
Scale
Defines if and how the rendered barcode is scaled in relation to the parent element:
l
l
l
None: The barcode is rendered based on the module width.
Fit to box: The barcode is stretched to fit the parent box in both width and height.
Proportionally: The barcode is stretched up to where it fits either the width or height of
the parent box, whichever requires the less stretching.
Supplement
UPC-A, UPC-E, EAN-13, and EAN-8 may all include an additional barcode to the right of the
main barcode.
l
Type: The supplement type can be 2-digit (originally used to indicate the edition of a
magazine or periodical) or 5-digit (used to indicate the suggested retail price for books). In
case this option is set to None, and the data includes digits for the 2 or 5 supplement, the
supplement data will be skipped and the additional barcode will not be rendered.
Note
When the chosen supplement type doesn't match the data, the supplement data will
be skipped and the additional barcode will not be rendered.
l
Height Factor: This is the relative height of the supplement's bars compared to the
Page 264
l
normal bars.
Space Before : Defines the space between the main symbol and the supplement, in cm.
Human Readable Message
When this option is checked, PlanetPress Connect shows a human readable text below or
above the barcode, as defined using the Text Position, using the specified font and font size.
The font size is given in points (pt).
Color
The Color property allows you to choose a different Barcode color (instead of black) and
Background color (instead of white), by typing a hexadecimal color value (see for example
w3school's color picker).
Output format
Defines how the barcode is output on the page. There are two possible formats:
l
l
SVG: Vector format. This is smaller in size, but not compatible with Email output.
PNG: Binary rasterized format. This is slightly larger than SVG but will display properly in
Email output.
Boxes
Boxes are elements that are used to surround other elements, either to style them or to place
them in specific locations.
Tip
Wrapping elements in a box (see "Boxes" above) or in a semantic HTML element makes
it easier to target them in a script or a style sheet. Place the cursor in the element or select
multiple elements. Then, on the menu, click Insert > Wrap in Box. You can now use the
wrapper element as a script's or style's selector; see "Using the Text Script Wizard" on
page 338 and "Styling and formatting" on page 398.
Positioned Box
A Positioned Box is one that can be freely moved around the page and does not depend on the
position of other elements. A positioned box is actually a element that has an absolute
position; in other words, it has its CSS property position set to absolute.
Page 265
Positioned Boxes are suitable for use in Print templates only.
Adding a Positioned Box
To insert a Positioned Box, use the
icon on the toolbar. Positioned Boxes can be moved by
dragging the borders, and resized using the handles on the sides and the corners. They can be
styled using the Format > Box menu item, through the CTRL+M keyboard shortcut or through
the CSS files; see "Styling and formatting" on page 398 and "Styling templates with CSS files"
on page 399.
Inline Box
An Inline Box is one that is placed within the text flow, where other elements (including text)
can wrap around it. An inline box is actually a element that is floating; in other words, it
has its CSS property float set to left, right or no float.
Inline Boxes can be used in Print context and in Web pages. It is common to do entire web
layouts using the float property. In Email templates, it is best to use Tables to position elements.
Adding an Inline Box
To insert an inline box, use the
icon on the toolbar. Inline Boxes can be resized using the
handles on the sides and corner. They can be styled using the Format > Box menu item,
through the CTRL+M keyboard shortcut or through the CSS files; see "Styling and formatting"
on page 398 and "Styling templates with CSS files" on page 399.
Positioning an Inline Box
Initially an Inline Box will float to the left. Use the (Float left), (No float) and
icons on the toolbar to change the position of an Inline Box within the text.
l
l
l
(Float right)
The Float leftbutton aligns the Inline Box to the left. The text is positioned to the right of it
and is wrapped around the box.
The Float rightbutton aligns the Inline Box to the right, with the text wrapped around it to
the left.
The No float button positions the Inline Box where it occurs in the text.
It is not possible to move an Inline Box using drag and drop. To move the Inline Box to another
position in the text, you have to edit the HTML on the Source tab in the Workspace, moving the
element using cut and paste. To open the Source tab, click it (at the bottom of the
Workspace) or select View > Source View.
Page 266
Span
The Span element ( in HTML code) is used to group inline elements, such as text in a
paragraph. A Span doesn't provide any visual change by itself, but it provides a way to target its
content in a script or in a style sheet.
To wrap content in a span, select the text and other inline elements and click Insert > Wrap in
Span on the menu.
Give the span an ID, if you are going to add a style rule or script for it that is unique to this span;
or give the span a class, if this span can be targeted by a style or script along with other pieces
of content. Now you can use the wrapper's ID or class as a script's or style's selector; see
"Using the Text Script Wizard" on page 338 and "Styling and formatting" on page 398.
Div
The Div is the element used to create both Positioned Boxes and Inline Boxes. By default, a
Div element reacts pretty much like a paragraph () or an inline box set to 'no float' except
that it can be resized directly. Just like Positioned Boxes and Inline Boxes, Div elements can be
styled using the Format > Box menu item, through the CTRL+M keyboard shortcut or through
the CSS files; see "Styling and formatting" on page 398 and "Styling templates with CSS files"
on page 399.
Adding a Div element
To add a Div, select Insert > Structural Elements > Div on the menu. For an explanation of
the options, see "Inserting an element" on page 226.
HTML tag: div, span
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
the Designer; see "Editing HTML" on page 224.
In HTML, boxes are
elements. Spans are elements. To learn how to change the
attributes of elements, see "Attributes" on page 225.
Date
The Date element inserts the current system date, optionally making it dynamic so that it
updates whenever the template is viewed or produces output.
Page 267
Adding a date
To add a date, use the Insert > Date option in the "Menus" on page 482. A dialog appears with
the following controls:
l
l
l
Language: Use the drop-down to select which language the date should be displayed in.
Update Automatically: Check to update the date automatically when the template is
viewed or produces output. When this option is checked, a placeholder is inserted in the
template and a script is created to update it automatically, otherwise a static text with the
date is inserted.
Available Formats: Select the date/time format in which to display the date.
Click OK to insert the date or Cancel to close the dialog.
Changing the date
Once inserted, a date can be modified directly in the template (if it does not update
automatically) or through the date script (if it does update automatically). To modify the date in
the script:
1. Double-click the date script in the Scripts pane.
2. Between the round brackets after Date, enter the desired date in the following order: year,
month, day, and optionally hours, minutes, seconds, milliseconds (see
http://www.w3schools.com/js/js_dates.asp and https://developer.mozilla.org/enUS/docs/Web/JavaScript/Reference/Global_Objects/Date.) When the time is omitted, it
defaults to 12:00:00 AM.
Formatting an automatically updating date
The script added to automatically update the date uses the short date format. To change this:
1. Double-click the date script in the Scripts pane.
2. Delete the first line of the script.
3. On the second line, delete what comes after format and change format to
formatter (see "formatter" on page 200).
4. Now type a dot after formatter, press Ctrl + space and choose one of the functions to
format a date and time; see "Date, date/time and time functions" on page 192.
Note
The Locale, set in the Edit > Locale dialog, has an influence on the formatting of a date. The
Page 268
Locale can be the system's locale, a specific locale, or it can depend on the value of a data field; see
"Locale" on page 421.
Forms
Web templates can contain Form elements. Capture OnTheGo templates always contain a
Form element.
Tip
To create a Capture OnTheGo template, preferably use a Template Wizard; see "Capture OnTheGo
(COTG) templates" on page 436. The Wizard not only adds the form, but also the necessary
Capture OnTheGo form elements, styles and JavaScript files.
Adding a Form
1. On the Resources pane, expand the Web context and double-click a Web page to open
it.
2. To use the Form Wizard, select the Insert > Form Wizard menu option. The Form Wizard
adds a Form to the Web page including the specified fields.
Alternatively, you can select Insert > Form on the menu to open a dialog that lets you set
the Form's properties, validation method and location, but doesn't allow you to specify
fields. If you choose this method, skip step 8 and 9 of this procedure and add fields after
inserting the Form (see "Forms" above).
3. Add an ID and/or a class. ID's and classes are particularly useful with regard to variable
data (see "Personalizing Content" on page 325) and styling (see "Styling templates with
CSS files" on page 399).
4. In the Action field, enter the URL where the form data should be sent. The URL should
be a server-side script that can accept form data. 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.
Page 269
5. Using the the Method drop-down, select whether the form should be sent using the GET
or POST method.
6. Using the next drop-down, select the form's Encryption Type (enctype):
l
l
l
application/x-www-form-urlencoded: Default. All characters are encoded before
they are sent. Spaces are converted to "+" symbols, and special characters are
converted to ASCII HEX values.
multipart/form-data: No characters are encoded. This value is required when you
are using forms that have a file upload control.
text/plain: Spaces are converted to "+" symbols, but no special characters are
encoded.
7. Select a validation method:
l
l
The Browser validation method leaves it up to the browser to validate the user
input. When adding fields to the Form (see the next step) you can only make fields
required and set the maximum length as an additional requirement for some fields.
Select JQuery Validation to validate using JQuery scripts. This allows you to
specify stricter requirements per field and type a different message for each field to
display to the user if the input is not valid. This method ensures a more consistent
validation as it is browser independent. The necessary JQuery files will be added to
the JavaScript folder on the Resources pane when the form is inserted.
8. Under Fields, click the Add button and click on the desired field type to add a field of that
type; see "Form Elements" on page 272.
Note
A Fieldset is not available in the Form Wizard, because a Fieldset itself can contain
multiple different fields. Add the Fieldset after inserting the Form; see "Forms" on
the previous page.
9. Double-click each field in the Fields list and change its settings. For an explanation of the
settings, see "Forms" on the previous page.
10. The order of the elements in the list under Fields determines in which order the elements
will be added to the Form. Use the Move Up and Move Down buttons to change the
order of the elements in the list.
Page 270
11. Use the Location drop-down to select where to insert the element.
l
l
l
l
l
At cursor position: The element is inserted where the cursor is located in the
template.
Before element: The element is inserted before the current HTML element where
the cursor is located. For example if the cursor is within a paragraph, insertion
occurs before the tag.*
After start tag: The element is inserted within the current HTML element, at the
beginning, just after the start tag.*
Before end tag: The element is inserted within the current HTML element, at the
end, just before the end tag.*
After element: The element is inserted after the current element where the cursor is
located. For example if the cursor is within a paragraph, insertion occurs after the
end tag of the paragraph (
).*
* If the current element is located inside another element, use the Elements drop-down to
select which element is used for the insertion location. The list displays every element in
the Breadcrumbs (at the top of the Workspace), from the current selection point until the
root of the body.
12. Close the dialog.
Modifying a Form
To modify a Form, you can of course edit the HTML code directly in the Source view of the
Workspace. Apart from that, there are a number of dialogs to change a Form's properties,
validation settings and the elements inside the Form.
Changing a Form's properties
1. Select the form (see "Selecting an element" on page 227).
2. On the Attributes pane you can change:
l
l
l
l
The ID and/or class. ID's and classes are particularly useful with regard to variable
data (see "Personalizing Content" on page 325) and styling (see "Styling templates
with CSS files" on page 399).
An Action: the URL where the form data should be sent. The URL should be a
server-side script that can accept form data.
A Method: this defines whether the form should be sent using the GET or POST
method.
An Encryption Type (enctype):
l
application/x-www-form-urlencoded: Default. All characters are encoded
before they are sent. Spaces are converted to "+" symbols, and special
Page 271
l
l
characters are converted to ASCII HEX values.
multipart/form-data: No characters are encoded. This value is required when
you are using forms that have a file upload control.
text/plain: Spaces are converted to "+" symbols, but no special characters are
encoded.
Changing a Form's validation method
In Connect PlanetPress Connect, there are two ways in which a Form's input can be validated:
l
l
The Browser validation method leaves it up to the browser to validate the user input.
When adding fields to the Form (see the next step) you can only make fields required and
set the maximum length as an additional requirement for some fields.
Select JQuery Validation to validate using JQuery scripts. This allows you to specify
stricter requirements per field and type a different message for each field to display to the
user if the input is not valid. This method ensures a more consistent validation as it is
browser independent. The necessary JQuery files will be added to the JavaScript folder
on the Resources pane when the form is inserted.
To change a Form's validation method:
1. Right-click on the Form element and choose Validation settings.
2. Choose a validation type (see above).
3. Double-click each field in the list to edit their validation settings:
Required: Check if the field is required to submit the form. If a field is required but
contains no data, a message will be shown to the user.
l Minimum length: Enter a numerical value for the minimum character length
required for this field.
l Maximum length: Enter a numerical value for the minimum character length
accepted for this field.
l Equal to: Use the drop-down to select another field that is already added to the
same Form. The contents of both fields must match for the data to be validated. This
is useful for confirmation fields such as for passwords, email addresses etc.
Which of these options are available depends on the validation method of the form: with
Browser validation you can only make a field required and set a maximum length.
l
Form Elements
This topic lists the elements that can be added to a form in a Web page or in a Capture
OnTheGo template and explains how to add them to a Form, set a default value or change their
Page 272
validation. For more information about Forms, see "Forms" on page 269. For more information
about elements in Forms, see http://www.w3schools.com/html/html_forms.asp.
Types of Form Elements
Fieldset
A fieldset is a group of related elements in a form. The elements don't have to be of the same
type. After inserting and selecting the Fieldset (see "Selecting an element" on page 227) you
can add elements to it in the same way you add elements to a Form; see "Adding elements to a
Form" on page 275.
Text
The Text element is a simple element with the type text. It accepts any alphanumerical
characters, including special characters. The string is HTML-encoded before it is submitted to
the server.
Email
The Email element is a text input field that accepts only email addresses in a valid format.
URL
The URL element is a text input field that accepts only URLs (a web page address) in a valid
format.
Password
The Password element is a password field that accepts any alphanumerical characters. When
the user types in this field, characters are shown as asterisks only.
Number
The Number element is a text field accepting only numbers.
Date
The Date element is a text field accepting only dates in a valid format.
Text area
The Text area element is a text field accepting multiple paragraphs. You can set a number of
rows when adding the Text Area to the Form, and change it on the Attributes pane.
Hidden field
A hidden field can contain specific data used by the server-side script. It is not visible to the
user. When adding a Hidden Field you can set the value that will be sent on submit.
Page 273
Label
A Label element is a text displaying informative text within the form. Labels are non-interactive.
Note that this type of label is not tied to an input element. At the same time you add an input
element, you can add a label to that element; see "Adding elements to a Form" on the next
page below. To change a label after inserting the Form, simply click it and start typing.
Checkbox
A Checkbox element sends information to the server whether it is checked (true) or not (false).
When adding a Checkbox you can set its initial state and its value. The contents of the value
property do not appear in the user interface. If a Checkbox is in checked state when the form is
submitted, the name of the checkbox is sent along with its value (if the Checkbox is not checked,
no information is sent).
Radio Button Group
A Radio Button Group is not an input element itself. Rather it is a group of Radio Buttons that
have the same submit name, indicating that they belong to the same group. Multiple Radio
Buttons in the same group only accept one option to be selected. Only the value of the selected
Radio Button will be sent to the server on submitting the form. If more options are to be allowed
at the same time you should use Checkboxes instead.
The option to add a Radio Button Group is only available in the Form Wizard; see "Forms" on
page 269. You could also create a Radio Button Group by specifying the same submit name for
a number of Radio Buttons when adding them to a Form.
Radio Button
A radio button sends information to the server whether it is selected (true) or not (false). When
adding a Radio Button you can set its initial state and its value. The contents of the value
property do not appear in the user interface. If a Radio Button is in selected state when the form
is submitted, the name of the Radio Button is sent along with its value (if it is not selected, no
information is sent).
The submit name of a Radio Button indicates to which Radio Button Group the Radio Button
belongs.
Select
A Select element is a drop-down list with multiple entries from which the user can select only
one option. When adding a Select to a Form you can type the options to be given in the dropdown list and the values related to them. Only the value of the selected option will be sent to the
server on submitting the form.
Page 274
Button
The Button element is an element that can be clicked. When adding a Button to a Form you can
set the button's type:
A submit button will validate the form data and if validation is successful, send the data to
the provided URL (by the Action specified for the Form; see "Changing a Form's
properties" on page 271).
l A reset button will reset the form to its original configuration, erasing any information
entered and options provided. Note: This cannot be undone!
The button's type can also be changed on the Attributes pane.
l
There may be multiple submit buttons on a Form. If there are, specify a different name and/or
value for each of the buttons. When adding a Button to a Form, you can specify a value, but no
name. The Button's ID will be copied to the element's name attribute. However, after inserting
the Button you can change the name on the Attributes pane.
Adding elements to a Form
To add an element to a Form or Fieldset, click inside the Form or Fieldset, select Insert > Form
elements, and choose the respective element on the menu. Now you can change the element's
settings:
1. Add an ID (required) and, optionally, a class.
Note
The ID will be copied to the name attribute of the element. The name attribute is
what identifies the field to the receiving server-side script. To change the name,
select the element after inserting it and type the new name on the Attributes pane.
ID's and classes are also useful with regard to variable data (see "Personalizing Content"
on page 325) and styling (see "Styling templates with CSS files" on page 399).
2. Type a label, or choose No label under Style, to omit the label. (For Label elements there
are no other options to be set.)
3. If applicable, choose a style for the label (for the label of a Checkbox, for example, you
can't set a style).
Page 275
l
l
l
l
Wrap input with label places the input element inside the Label element.
Attach label to input ties the label to the input element using the for attribute of
the Label element.
Use label as placeholder inserts the given label text in the placeholder attribute of
the field.
No style omits the label altogether.
Note
The first two label styles ensure that when the user clicks the label, the input
element gets the focus.
4. The following options are only available for specific elements:
l
l
l
For a Text Area you can specify a number of rows.
For a Radio Button, the submit name indicates to which Radio Button Group the
Radio Button belongs.
For a Button, Checkbox, Hidden Field, and Radio Button you can set the value.
The value is associated with the input and will be sent on submitting the Form.
Tip
For other Form elements, you can set the default value to be the value of a
field in the record set; see "Specifying a default value" on the next page.
l
l
For a Checkbox or Radio Button you can check checked or selected respectively
for the element to initially be checked/selected when the web page is shown.
For a Button, you can set the button type:
l
l
Submit: The button will validate the form data and if validation is successful,
send the data to the provided URL (the action specified for the Form; see
"Changing a Form's properties" on page 271).
Reset: The button will reset the form to its original configuration, erasing any
information entered and options provided. Note: This cannot be undone!
5. Depending on the validation method of the form (see "Form Elements" on page 272) and
the type of element there are a number of options to set under Validation. With Browser
validation you can only make a field required and set a maximum length.
Page 276
l
l
l
Required: Check if the field is required to submit the form. If a field is required but
contains no data, a message will be shown to the user.
Minimum and maximum length: Enter a numerical value for the minimum and
maximum character length required for this field.
Equal to: Use the drop-down to select another field that is already added to the
same Form. The contents of both fields must match for the data to be validated. This
is useful for confirmation fields such as for passwords, email addresses etc.
6. Under Warnings, type the message that will be displayed to the user if the input is not
valid.
When adding an element to a Form or Fieldset, you cannot specify a name; the ID will be copied
to the element's name attribute. After adding the element to the Form or Fieldset you can change
the name on the Attributes pane. The name attribute of Form elements is sent to the server after
the form has been submitted.
Specifying a default value
Attribute a default value to a Text, Textarea and other Form elements by dragging a field from
the Data Model pane directly onto the field, once it has been created. This also works when
dragging a field from a detail table in a record set into a Form element that is contained within a
Dynamic Table.
Note that the default value doesn't disappear when the user clicks the field, as placeholders do.
To insert a placeholder in a field, type a label and choose Use label as placeholder as its style
when adding the element to the form; see "Forms" on page 269.
Changing the validation
To change the validation of a Form element, right-click the element and choose Validation
settings. Now you can change the Form's validation method and set the requirements per field;
see "Changing a Form's validation method" on page 272.
Hyperlink and mailto link
Links can be added to any template but they only work in electronic output (web pages, email
and PDF files). They can be a regular hyperlink pointing to a web page or a mailto link that will
open the default email client when clicked.
HTML element: a
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
Page 277
the Designer; see "Editing HTML" on page 224.
The HTML tag of a hyperlink or mailto-link is . This is sometimes called an anchor tag. For
a list of attributes, see http://www.w3schools.com/tags/tag_a.asp.
Adding a hyperlink or mailto link
1. Select text or an image.
Note
Although it is possible, it is not advisable to add a Hyperlink to other elements, such
as a Paragraph or Div. HTML 4 specifies that hyperlinks and mailto-links may only
contain inline elements. Block elements, such as a Div, may not appear inside a
link. HTML 5 states that the link "may be wrapped around entire paragraphs, lists,
tables, and so forth, even entire sections, so long as there is no interactive content
within (e.g. buttons or other links)"; see https://www.w3.org/TR/html5/text-levelsemantics.html.
2. Click the Insert hyperlink button on the toolbar, or on the menu, select Format >
Hyperlink > Insert.
3. Select URL to create a regular hyperlink pointing to a web page, or select Email to create
a mailto-link that will open the default email client when clicked.
4. For a URL:
URL: enter a valid, well-formed URL to link to. It must start with the protocol, such as
http:// or https://.
l Target: use the drop-down or type in the target for the link.When the target is _
blank the link will open in a new browser window or tab.
For a mailto link:
l
Email: enter a valid email address that appears by default in the To: field of the
email client.
l Subject: type a default subject that appears in the Subject: field of the email client.
l Message: type a message that appears by default in the Message field of the email
client.
Note that all these can be changed within the email client once the link is clicked.
l
Page 278
Dynamically inserting or modifying a hyperlink
You may wish to adjust a hyperlink depending on a value in a record that is merged to the
template when generating output, for example, to provide a different mailto link for different
customers.
How to add or modify a hyperlink is described in a how-to; see How to dynamically insert a
hyperlink. This implies writing a script. For information about scripts, see "Write your own
scripts" on page 376.
Adding a personalized link
Personalized URLs (pURLs) are links that are tailor-made for a specific purpose, generally for
individual clients. Typically, a pURL in a Connect template takes the user to a personalized
landing page, for example, to download an invoice or get access to specific products or
services. For more information, see "Personalized URL" on page 350.
Images
Images are a powerful ingredient in all of your templates. This topic explains how to add and
use them.
Ways to use images
In templates, both imported images and external images can be used (see "Adding images"
on the facing page and "Resources" on page 442). Once added to the content of a template, an
image can be resized (see "Styling an image" on page 281) and alternate text can be linked to
it (see "Setting an alternate text" on page 282).
Dynamic image
Images can be switched dynamically, so that a letter, email or web page can include one image
or another, depending on a value in the data set. Read "Dynamic Images" on page 346 to find
out how to add such switching images.
Background image
Several parts of templates can have a background image. See "Background color and/or
image" on page 412 and "Using a PDF file as background image" on page 359.
Page 279
Tip
To create a Print section from an existing PDF file, use a PDF file as a Print section's
background. 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.
See "Using a PDF file as background image" on page 359.
Optional filler for whitespace
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, use an image or
advert as a 'whitespace element'; see "Images" on the previous page.
HTML tag: img
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
the Designer; see "Editing HTML" on page 224.
In HTML, images are ![]()
elements. The ![]()
tag has at least four attributes: src, alt, width
and height. Src specifies the URL of the image. Alt contains the alternate text; see "Setting an
alternate text" on page 282.
The value of the attributes can be changed via a script; see "Attributes" on page 225.
Adding images
To add an image to a template:
1. Select Insert > Image > From file, or click the Insert Image button on the toolbar. A
standard Open File dialog appears.
2. Browse to the file and click Open.
3. Check the option Save with template to import the image. Imported images are saved
within the template file, so they are always available and don't depend on external paths,
servers or URLs. If this option is checked, the image file will be inserted in the Images
folder on the Resources pane at the top left.
Uncheck this option if the image should be used as an external image (see also: "Using
external images" on the next page).
4. Click Finish. The image will be inserted at the position of the cursor.
Alternatively:
Page 280
1. Look up the image file on your computer and drag the image file from the Explorer to the
Images folder on the Resources pane at the top left.
2. To place the image in the content, drag it from the Images folder on the Resources pane
to the content and drop it.
To import a remotely stored image, see "Using external images" below.
Using external images
An external image is an image that is not saved within the template file. It is located either on a
specific website (URL) or on a hard drive that is accessible from the machine on which the
template's output is produced.
When external images are used, they are updated (retrieved) when the template is merged with
a record set to generate output.
To use an external image:
1. Position the cursor in the template where you want the image to be inserted.
2. On the menu, select Insert > Image > From address, or on the toolbar, click the Insert
Image from address button. The Insert Image from Address dialog appears.
3. Enter the URL. This can either be
l
l
a web address (http://www.mysite.com/images/image.jpg), or
a local path, for example: file:///c:/resources/images/image.jpg. 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'.
4. Enter an alternate text. This text will be shown in emails and on web pages at the
position of the image while the image is loading and when the image is not found. On
web pages, alternate texts are also used for accessibility.
5. Click Finish. The image will be inserted at the current position of the cursor in the
template.
For information about referring to images in HTML or in a script, see "Resources" on page 442.
Styling an image
Images can be styled using the Format > Image menu item. They have a border, margin and
padding; see "Border" on page 413 and "Spacing" on page 422. Images can also be leftaligned or right-aligned, just like boxes.
Page 281
Resizing an image
There are three ways to resize an image after inserting it in the content of a template.
l
l
l
Click the image and drag the handles to resize it. Press the Shift key while dragging, to
scale the image proportionally.
Select the image (see "Selecting an element" on page 227) and type the desired width
and height in the respective fields on the Attributes pane.
Select the image and select Format > Image, on the menu. On the Image tab, change the
width and height of the image.
Positioning an image
Initially an image will float to the left. Select the image (see "Selecting an element" on page
227) and use the (Float left), (No float) and (Float right) icons on the toolbar to change
the position of an image within the text.
l
l
l
The Float left button aligns the image to the left. The text is positioned to the right of it and
is wrapped around the box.
The Float right button aligns the image to the right, with the text wrapped around it to the
left.
The No float button positions the image where it occurs in the text.
To position an image using the menu, select the image and then select one of the options in
Format > Float.
Alternatively, select the image and on the menu, select Format > Image and on the Image tab,
set the Float property. This is equivalent to the float property in CSS.
Rotating an image
To rotate an image, select the image (see "Selecting an element" on page 227) and select
Format > Image, on the menu. On the Image tab, set the rotation angle of the image in
clockwise degrees. This is equivalent to the transform:rotate property in CSS.
Setting an alternate text
Once an image has been inserted in the content of a template, it can have an alternate text. The
alternate text will be shown in emails and on web pages at the position of the image while the
image is loading and when the image is not found. On web pages, alternate texts are also used
for accessibility.
Page 282
To set an alternative text, click the image and enter the alternate text in the Alternate text field
on the Attributes pane at the top right.
Table
Tables serve two different purposes: they are a way to display data in a tabular format, and they
are also a way to position elements on a page.
In HTML email, Tables are the most reliable way to position text and images; see "Designing
an Email template" on page 439. In web pages, on the other hand, Inline Boxes are the
preferred way to position elements. Tables should only be used to display data in a tabular
format, not to position text and images. Tables used in web pages to position elements make
those pages less accessible to users with disabilities and to viewers using smaller devices.
In print, Tables can be used for both purposes.
There are two types of tables: standard tables which are static in nature, and Dynamic Tables
which have a variable number of rows depending on a detail table in the record; see "Dynamic
table" on page 347.
HTML element: table
When you add elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file. It is possible to edit the source of the HTML file directly in
the Designer; see "Editing HTML" on page 224.
The HTML tag of a Table is . Tables are divided into table rows with the tag. Table
rows are divided into table data with the tag. A table row can also be divided into table
headings with the tag.
The tags , and can be used to group the header, body, or footer content
in a table, respectively.
For information about HTML tables and a list of attributes, see
http://www.w3schools.com/html/html_tables.asp.
Inserting a Table
1. On the toolbar, click the Insert table button, or on the menu select Insert > Table >
Standard.
Page 283
2. Enter the table's desired attributes:
l
l
l
l
l
ID: a unique identifier for the table. IDs are used to access the Table from scripts
and as CSS selectors for style rules.
Class: A class identifier for the table. Classes can be shared between elements and
are used to access the table from scripts and as CSS selectors for style rules.
The number of rows for the header, body and footer of the table.
The number of columns
The width of the table.
3. Use the Location drop-down to select where to insert the element:
l
l
l
l
l
4.
5.
6.
7.
At cursor position: The table is inserted where the cursor is located in the
template.
Before element: The table is inserted before the current HTML element where the
cursor is located. For example if the cursor is within a paragraph, insertion occurs
before the tag.*
After start tag: The table is inserted within the current HTML element, at the
beginning, just after the start tag.*
Before end tag: The table is inserted within the current HTML element, at the end,
just before the end tag.*
After element: The table is inserted after the current element where the cursor is
located. For example if the cursor is within a paragraph, insertion occurs after the
end tag of the paragraph (
).*
* If the current element is located inside another element, use the Elements drop-down to
select which element is used for the insertion location. The list displays every element in
the breadcrumbs, from the current selection point until the root of the body.
Click Next and select which fields should show up in the Dynamic Table.
The order of the fields indicates in which order columns are displayed in the dynamic
table, from left to right. Select a line and then use the Up and Down buttons to change the
order of the columns.
You could change the placeholder for each data field as well; just click a placeholder to
edit it.
Click Next and use the drop-down to select the desired table style.
Uncheck the box Resizable columns if the columns should not be resizable from the
Design and Preview modes in the workspace. This is useful if the column size is
determined in the Source mode or in a style sheet.
Click Finish to add the table to the section.
Page 284
Header and footer
Adding a header or footer
To add a header or footer to an existing table, right-click the table and then select Table >
Insert thead or Insert tfoot, on the shortcut menu.
Alternatively, click in one of the cells and select Insert > Table > Insert thead or Insert tfoot,
on the menu.
Deleting a header or footer
To delete a header or footer, simply right-click the header or footer and select Row > Delete on
the shortcut menu.
Rows and columns
Adding a row or column
To add a row or column to an existing table, click in a cell. Then click the black triangle next to
the Insert Row Above button on the toolbar, and click one of the Insert buttons, or select one
of the options in the Insert > Table Elements menu.
Alternatively, right-click the table and on the shortcut menu, select Row > Insert Above or
Insert Below, or select Column > Insert Before or Insert After.
Deleting a row or column
To delete a row or column, simply right-click the row or column and select Row > Delete or
Column > Delete on the shortcut menu.
Styling a Table
Tables can be styled using the Format > Table menu item, while individual selected cells can
be styled using the Format > Table Cell menu item.
Hiding the border
When using a Table to position other elements, you will want to hide the borders of the table.
To do this, set the width of the border to 0; see "Border" on page 413.
Text and special characters
The vast majority of templates for personalized customer communications contain, of course,
text. While the most common text element is a or paragraph, other elements such as
Page 285
Headings (
through ) are also considered text elements. Text elements can be
present within other types of elements such as table cells (), boxes (), etc.
Adding text
To add text, simply type in the workspace in the middle.
l
l
Press Enter to insert a new paragraph.
Press Shift+Enter to insert a line break.
Alternatively, copy-paste text into a template, or use the Insert Lorem Ipsum toolbar button to
insert dummy text.
Text that precedes or follows the value of a data field can be added by the Text Script Wizard;
see "Using the Text Script Wizard" on page 338.
Note: it is not possible to open a Word file in the Designer. When you copy text from a Word
document, however, basic style characteristics travel with the content to PlanetPress
ConnectDesigner. Formatting options like bold, italic and formats like Heading 1, Heading 2
are maintained.
Adding special characters
To add special characters:
1. Position the cursor where the character should be inserted.
2. On the Insert menu, point to Special Characters click Symbols, Dashes and Spaces,
Arrows, or Geometric Shapes, and click one of the available special characters.
Adding page numbers
Page numbers can only be used in the Print context. See "Page numbers" on page 365.
HTML element: p, h, li and others
When adding elements, such as text, images or a table, to the content of a template, you are
actually constructing an HTML file; see "Editing HTML" on page 224.
In HTML text can be contained in many different elements: paragraphs, span elements, line
items and table cells, for example.
The HTML tag of a paragraph is . The paragraph should be followed by a closing tag:
.
Page 286
A line break looks like this in HTML:
.
Formatting text
Text can be styled, colored, centered, indented etc. It can even be displayed so that it reads
from right to left. See "Styling text and paragraphs" on page 407.
In all templates you can use the fonts that are provided with the Designer, as well as imported
fonts; see "Fonts" on page 419.
Capture OnTheGo
With the Designer you can create Capture OnTheGo templates. COTG templates are used to
generate forms for the Capture OnTheGo mobile application. For more information about the
application see this website: Capture OnTheGo.
COTG Forms
A Capture OnTheGo form is actually just a Web form, that you could add without a Form wizard,
but the COTG Template Wizards include the appropriate JavaScript and styles to create userfriendly, responsive forms; see "Capture OnTheGo (COTG) templates" on page 436.
The action of the Capture OnTheGo Form element should specify a Workflow HTTP Server
Input task that receives and handles the submitted data. The action will look similiar to this:
http://192.168.175.1:8080/actionname (where actionname is the HTTP action of the HTTP
Server Input task). For more information about specifying an action, see "Adding a Form" on
page 269.
COTG Elements
There is a number of special Capture OnTheGo (COTG) elements. They can be used in a Web
context within a Form element; for a description of all COTG elements, see "COTG Elements"
on page 293.
Adding elements to a COTG Form
To add a COTG element to a Form or Fieldset, click inside the Form or Fieldset, select Insert >
COTG elements, and choose the respective element on the menu. Now you can change the
element's settings:
Page 287
1. Add an ID (required) and, optionally, a class.
Note
The ID will be copied to the name attribute of the element. The name attribute is
what identifies the field to the receiving server-side script. To change the name,
select the element after inserting it and type the new name on the Attributes pane.
ID's and classes are also useful with regard to variable data (see "Personalizing Content"
on page 325) and styling (see "Styling templates with CSS files" on page 399).
2. Type a label, or choose No label under Style, to omit the label. (For Label elements there
are no other options to be set.)
3. If applicable, choose a style for the label (for the label of a Checkbox, for example, you
can't set a style).
l
l
l
l
Wrap input with label places the input element inside the Label element.
Attach label to input ties the label to the input element using the for attribute of
the Label element.
Use label as placeholder inserts the given label text in the placeholder attribute of
the field.
No style omits the label altogether.
Note
The first two label styles ensure that when the user clicks the label, the input
element gets the focus.
Note
When adding an element to a Form or Fieldset, you cannot specify a name; the ID will be copied
to the element's name attribute. After adding the element to the Form or Fieldset you can change
the name on the Attributes pane. The name attribute of Form elements is sent to the server after
the form has been submitted.
Page 288
Note
When you add a COTG element to a template that you didn't start with a COTG template wizard,
the Designer will automatically add the jQuery library and the JavaScript file cotg.js, so that the
element works well. The Foundation style sheets will not be added. You only get those when you
start creating a COTG template with a template wizard.
How to make COTG elements required
To make a COTG element required, or to change the validation of a COTG Form, right-click the
element and choose Validation settings. Now you can change the Form's validation method
and set the requirements and a message per field. For an explanation of the settings, see
"Changing a Form's validation method" on page 272.
Testing a COTG template
For information about testing a COTG template, see this how-to: Testing a COTG template, and
Send COTG Test.
Using JavaScript
JavaScript files, libraries and frameworks can be added to a template, to add widgets and other
functionality to your Capture OnTheGo Forms; see "Using JavaScript" on page 450.
How to use COTG data in a template
When a user submits a Capture OnTheGo Form, the data are received by a Workflow HTTP
Server Input task that receives and handles the submitted data. Even when no other tasks are
present in that Workflow configuration, Workflow will output an XML file that contains the
submitted data, in a location specified for the Send To Folder plugin in Workflow.
To be able to use that data in a template, you have to create a Data Mapping Configuration that
extracts the data from the resulting XML file. Next, you can create a Designer template that uses
this Data Mapping Configuration. Strings, base64-encoded strings and SVG data stored in data
fields using the DataMapper can be used in a Designer template as they are.
Capture OnTheGo (COTG) templates
With the Designer you can create Capture OnTheGo 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 289
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 and styles to create userfriendly, responsive forms. They are built upon the Foundation framework.
Foundation
All Web Template Wizards 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.
After creating a COTG template, the other contexts can be added, as well as other sections
(see "Adding a context" on page 222 and "Adding a Web page" on page 446).
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
l
l
l
l
Blank. The Blank COTG Template has some basic design and the appropriate
form, but no actual form or COTG elements.
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.
Page 290
l
l
l
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
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:
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 page. Double-click to open them. See
"Snippets" on page 396 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. The action of a Capture OnTheGo
form should specify the Workflow HTTP Server Input task that receives and handles the
Page 291
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.
Adding elements to a COTG template
To fill a Capture OnTheGo form, you can use special Capture OnTheGo Form elements, such
as a Signature and a Barcode Scanner element. To insert an element, select Insert > Capture
OnTheGo Form elementsand click the respective element; see "COTG Elements" on the next
page. Web Form elements can also be used on COTG Forms (see "Forms" on page 269 and
"Form Elements" on page 272) as well as text, images and other elements (see "Content
elements" on page 223).
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.
Capture OnTheGo templates can be personalized just like any other type of template; see
"Variable Data" on page 336 and "Personalizing Content" on page 325.
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.
Page 292
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.
COTG Elements
With the Designer you can create Capture OnTheGo templates. COTG templates are used to
generate forms for the Capture OnTheGo mobile application. This topic is about Capture
OnTheGo form elements. For more information about the application see this website: Capture
OnTheGo.
Capture OnTheGo (COTG) elements can only be added within a Form element in a Web
context; see "COTG Forms" on page 287 and "Adding elements to a COTG Form" on page
287.
Barcode Scanner
The Barcode Scanner element adds a button to trigger the device to scan a barcode. A very
large variety of barcode types are supported. Once the barcode has been scanned, the data
from the barcode will be added to the COTG Form and submitted along with it.
Note
Using the Barcode Scanner element requires the installation of the ZXing Barcode Scanner
application on Android devices. The application returns the barcode data after scanning.
Camera
The Camera element adds a group of buttons to capture or select an image. Once the image is
selected via the camera or the device's library (aka "gallery"), it is saved within the Form data.
When the form is submitted, the image is sent in a base64-encoded string format.
Buttons
By default, the Camera element adds three buttons to the form:
l
Take now: Opens the device's default Camera application to take a picture using the
device's camera. Capture OnTheGo has no impact on the device's applications, so the
Page 293
l
l
features available (quality, orientation, filters) are dependent on the device itself. You can,
however, set the format, quality and scaling for images that are submitted by the Camera
element, as explained below.
Library: Opens the device's default library or gallery application to select a single image
that is then saved in the form data. The accessible images and navigation depend on the
device itself.
Clear: Removes any existing image data from the Camera element.
To omit the Take now or Library button, edit the Camera element's properties: right-click the
Camera element after adding it to the form, select Camera properties and then use the Source
drop-down to select which buttons will be available: Take, Pick from library, or both.
Annotations
Annotations can make a picture much more informative: an arrow, showing in which direction a
car was driving; a circle, where the car has been damaged... To allow the user to make
annotations, right-click the Camera element after adding it to the form, select Camera
properties, and then check Allow annotations.
Clicking (or rather, touching) the image will bring up the annotation dialog. Annotations can be
made in a Marker (semi-transparent) or Pencil (solid) style, in different colors and with different
widths.
Annotations are submitted in SVG format by a hidden input added to the Camera element. The
name of that input is the ID of the Camera element, followed by "-note-data", for example
camera1-note-data.
Cropping/editing
To allow the user to crop or edit the image after taking or selecting it, select Camera
properties, and then check Edit Images. Which editing options the user actually gets depends
on the operating system of the device. On an Android device for example, the user may be able
only to crop the image, while the user of an iOS device may select part of the image and rotate
that selection.
Image format
You can set the format, quality and scaling for images that are submitted by the Camera
element. Right-click the Camera element after adding it to the form, select Camera properties
and edit the Image properties:
l
l
Format: The image format can be PNG or JPG.
Quality: Set the compression in a percentage.
Page 294
l
Scale Image: Check this option to enable image scaling. Then set the maximum width
and height of images before they are sent to the server. Note that only the smallest of
these is applied and the size ratio is always maintained.
How to use the captured or selected image in a template
When the user has submitted the form, you may want to use the captured or selected image in a
Designer template, for example in a letter or on a web page. To do this, insert a dummy image
in the template, right-click it and select Dynamic Image. The Text Script Wizard appears.
Under Field select the field that contains the base64-encoded string. The script puts the given
string in the source (src) attribute of the image (![]()
).
Instead of using the Text Script Wizard, you could also write a script yourself; see "Write your
own scripts" on page 376.
Date and Formatted Date
The Date element and the Formatted Date element display the current date on the device when
the form is first opened. When the element is touched, a date selector appears so the user can
modify this date. The Formatted Date element displays dates in a format that depends on the
locale of the device on which the user is viewing the form. A Date Element displays dates in the
ISO 8601 format: YYYY-MM-DD.
When the form is submitted, the date data is sent as plain text. A Formatted Date element
submits the date in two formats: in the format that depends on the device's regional and
language settings and in the ISO format mentioned above (using a hidden field). A Date
element sends the date in the ISO format only.
Device Info
The Device Info Element adds a field that contains some information about the device (phone
or tablet) that is submitting the COTG Form. This includes the device's type (Android or iOS),
operating system version, device model and its UUID (Universally Unique Identifier). This
information can be useful for both troubleshooting, if errors occur on specific device types for
example, as well as for security validation: it is possible to maintain a list of device UUIDs that
are allowed access, to prevent unauthorized use even if someone has a user name and
password to a repository.
Fields Table
The Fields Table element adds a table with two rows, a delete button at the end of the first row
and an add button at the end of the second row. Inside the rows you can put whatever elements
you need. The user can click (or rather, touch) the Add button to add a row to the table. The
Page 295
new row will contain the same elements as the first row. The names of all elements in the first
row will be extended with __0, while the names of the elements in the second row will be
extended with __1, etc.
Geolocation
The Geolocation Element adds a button to read the device's current GPS coordinates and save
them in a form field. When the button is pressed, the GPS coordinates are requested and
saved. When the form is submitted, the Geolocation data is sent in plain text.
Image & Annotation
The Image & Annotation element is meant to be used with an image that needs input from the
user. When inserting an Image & Annotation element you have to select the image. The user
can simply click (or rather, touch) the image to bring up the annotation dialog. Annotations can
be made in a Marker (semi-transparent) or Pencil (solid) style, in different colors and with
different widths.
Annotations are submitted in SVG format by a hidden input. The name of that input is the ID of
the Image & Annotation element, followed by "-note-data", for example image_annotation1note-data.
Locale
The Locale Element does not have a UI element in the form. Inserting it adds a hidden input
field that will contain the device's set locale when the form is submitted. This data is sent in
plain text format and is available when processing the form data. The format is defined by the
device.
Signature
The Signature Element adds a signature box to a COTG form. These signatures are filled in via
touch input, either with a finger or capacitive pen. Touching the signature box opens up a
fullscreen box used to sign (generally more useful in Landscape mode depending on the
device); after confirming, the dialog saves the data into the Form.
Signature data is transmitted in SVG plain text format. To insert the signature data in a
template, store the data in a field in a Data Mapping Configuration as is, and drag that field from
the Data Model into a template to create a text script. The signature data can be inserted in the
template's HTML directly, because the Designer (as well as web browsers) knows how to
display this kind of data.
Page 296
Time and Formatted Time
The Time element and the Formatted Time element display the current time on the device
when the form is first opened. When the element is touched, a time selector appears so the user
can modify this time. The Formatted Time element displays times in a format that depends on
the locale of the device on which the user is viewing the form. A Time Element displays dates
in the ISO 8601 format: HH:MM.
When the form is submitted, the time data is sent as plain text. A Formatted Time element
submits the time in both the ISO format mentioned above and in the format that depends on the
device's regional and language settings. A Time element sends the time in the ISO format only.
User Account
The User Account Element adds a hidden field which contains the Capture OnTheGo user
account that was used to submit the form to the server. This is useful if a form is available to
many different users, to detect who submitted it.
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 428. 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 222), the Email context folder is created
along with other files that are specific to an Email context; see "Email context" on the facing
page.
Page 297
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 300. 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 320.
Email templates are personalized just like any other template; see "Variable Data" on page
336.
Sending email
When the template is ready, you can change the email settings (see "Email header settings" on
page 303) and send the email directly from the Designer or via Workflow. To test a template,
you can send a test email first.
Email output can have the following attachments:
l
l
l
The contents of the Print context, in the form of a PDF attachment
The output of the Web context, as an integral HTML file
Other files, an image, or a PDF leaflet for example.
See "Email attachments" on page 306 and "Generating Email output" on page 320.
Email context
In the Designer the Email context is the folder that contains Email templates. From the Email
context, output can be generated in the form of email (see below).
When an Email template is created (see "Creating an Email template with a Wizard" on page
428) or when an Email context is added to a template (see "Adding a context" on page 222) the
following happens:
l
l
The Email context is created and one Email section is added to it. You can see this on
the Resources pane: expand the Contexts folder, and then expand the Email folder.
See "Email templates" on page 300 to learn how to fill an Email section.
Although only one email can be sent per record when generating Email output, the Email
context can contain multiple sections. One Email section is created at the start, but you
can add more; see "Adding an Email template" on page 300.
A style sheet, named context_htmlemail_styles.css, is added to the template. Depending
on which Template Wizard was used to create the template, another style sheet can be
added as well. Style sheets are located in the folder Stylesheets on the Resources
Page 298
pane. These style sheets are meant to be used for styles that are only applied to elements
in the Email context.
The Wizard opens the Email section, so that you can fill it with text and other elements; see
"Content elements" on page 223 and "Email templates" on the facing page.
Sending email
When the template is ready, you can generate Email output; See "Generating Email output" on
page 320. To test a template, you can send a test email first. Email output can have the
following attachments:
l
l
l
The contents of the Print context, in the form of one PDF attachment.
The default section of the Web context, as an integral HTML file.
Other files.
Note
To split the Print context into multiple attachments, or to attach multiple Web sections as separate
attachments, you need to create a Control Script that specifies parts; see "Control Script API" on
page 211 and "Control Scripts" on page 388.
See "Email attachments" on page 306.
Email output settings
The following settings in an Email context influence how the Email output is generated.
Compressing PDF attachments
For PDF attachments, generated from the Print context, you can set the Print Context Image
Compression to determine the quality of the files, and with that, the size of the files.
To set the Print Context Image Compression:
1. On the Resources pane, expand the Contexts folder, and right-click the Email context.
2. Click Properties.
3. Change the properties of the PDF file that will be attached when the Print context is
attached to the email.
Page 299
Lossless is the maximum quality. Note that this will produce a larger PDF file. Uncheck
this option to be able to set a lower quality.
The quality is set in a percentage of the maximum quality.
Tile Size is the size of the files in which the image that is being compressed is divided. (If
the image height or width is not an even multiple of the tile size, partial tiles are used on
the edges.) Image data for each tile is individually compressed and can be individually
decompressed. When low Quality values are used to optimize images smaller than 1024
x 1024 pixels, using the largest tile size will produce better results.
Setting a default section for output
When generating output from the Email context, only one of the Email templates can be merged
with each record. One of the Email sections is the 'default'; see "Setting a default Email
template for output" on page 302.
Email templates
Email templates (also called Email sections) are part of the Email context in a template. The
Email context outputs HTML email with embedded formatting to an email client through the use
of an email server. Since email clients are numerous and do not support same features, the
HTML generated by this context is not optimized for any specific client - rather, it's meant to be
compatible with as many clients and as many devices as possible.
In Email templates, many content elements can be used; see "Content elements" on page 223.
However, special attention must be paid to the way elements are positioned. In Email sections,
it is advisable to position elements using Tables and to put text in table cells.
Email templates are personalized just like any other template; see "Variable Data" on page
336.
The subject, recipients (To, CC and BCC), sender and reply-to address are specified with
Email Script Wizards; see "Email header settings" on page 303.
An Email context can contain multiple templates. When generating output from the Email
context, however, only one of the Email templates can be merged with each record. Set the
'default' Email section (see below) before generating Email output; see also "Generating Email
output" on page 320.
Page 300
Adding an Email template
When an Email template is created (see "Creating an Email template with a Wizard" on page
428), only one Email section is added to it. An Email context may contain various templates, but
per record only one of those can be sent when you generate Email output.
It is not possible to add an Email section to an existing Email context with the help of a
Template Wizard.
To provide alternative content for your email, you could use Conditional Content (see "Showing
content conditionally" on page 344), or Snippets and a script (see "Snippets" on page 396 and
"Loading a snippet via a script" on page 386).
If you would like to start with a template that is identical to the one you already have, consider
copying it (see "Copying a section" on page 393).
To add a section to the Email context:
l
On the Resources pane, expand the Contexts folder, right-click the Email folder, and
then click New Email.
Deleting an Email template
To delete an Email section:
l
On the Resources pane, expand the Contexts folder, expand the Email context, rightclick 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.
Styling and formatting an Email template
The contents of an Email section can be formatted directly, or styled with Cascading Style
Sheets (CSS). See "Styling and formatting" on page 398.
Page 301
Email clients do not read CSS files and some even remove a