2020.2

Manuals Brands Objectif Lune Manuals Applications PlanetPress Connect

Table Of Contents

Summary of content (1766 pages)

PAGE 1
PAGE 2
PAGE 3

User Guide Version 2020.2.1 Last Revision: 2021-02-04 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-2021. All rights reserved. No part of this documentation may be reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever without the express written permission of Objectif Lune Inc. Objectif Lune Inc.
PAGE 4

Table of Contents Table of Contents 4 Welcome to PlanetPress Connect 2020.
PAGE 5

The Connect server The Connect database The File Store The engines The REST API Log files Location Name Format Connect file types OL Connect projects 129 130 130 131 131 132 132 133 133 134 136 Automation with Workflow Using the REST API Project Wizards Project wizard: Basic Email Project Wizard: COTG Timesheets Project Wizard: Print Promotional Jobs Project Wizard: Print Transactional Jobs Project Wizard: Submitting Data with Web Forms Project Wizard: Serving a Web Page Workflow processes in OL Connect p
PAGE 6

Using the wizard for databases Using the wizard for PDF/VT or AFP files Using the wizard for XML files Advanced PCL to PDF options Data mapping workflow Creating a data mapping workflow Testing the extraction workflow Data source settings Properties and runtime parameters Extracting data Steps The Data Model About records Creating a Data Model Editing the Data Model Using the Data Model Fields Detail tables Data types Data Model file structure DataMapper User Interface Keyboard shortcuts Menus Panes Toolbar
PAGE 7

Sections Print Creating a Print template with a Wizard Print context Print sections Pages Master Pages Media Email Designing an Email template Creating an Email template with a Wizard Email context Email templates Email header settings Email attachments Web Creating a Web template with a Wizard Web Context Web pages Forms Using Form elements Using JavaScript Capture OnTheGo COTG Forms Creating a COTG Form Filling a COTG template Sending the template to the Workflow tool Using COTG data in a template Designi
PAGE 8

Using submitted COTG data in a template Capture OnTheGo API Content elements Element types Editing HTML Attributes Inserting an element Selecting an element Deleting an element Styling and formatting an element Barcode Boxes Business graphics COTG Elements Date Forms Form Elements Hyperlink and mailto link Images Table Text and special characters Snippets Adding a snippet to the Resources Adding a snippet to a section Creating a snippet Editing a snippet Renaming a snippet Translating a snippet Styling and
PAGE 9

Background color and/or image Border Colors Fonts Locale Spacing Personalizing content Variable data Conditional content Dynamic images and Print section backgrounds Dynamic tables Snippets Scripts Loading data Variable Data Formatting variable data Showing content conditionally Conditional Print sections Dynamic images Dynamic Table Dynamic Print section backgrounds Personalized URL Preferences General preferences Clean-up Service preferences DataMapper preferences Database Connection preferences Editing p
PAGE 10

Save preferences Scripting preferences Servers preferences Web preferences Writing your own scripts Script types Creating a new Standard Script Writing a script Setting the scope of a script Managing scripts Testing scripts Optimizing scripts The script flow: when scripts run Selectors in Connect Loading a snippet via a script Loading content using a server's API Using scripts in Dynamic Tables Control Scripts Post Pagination Scripts Translating templates Translating a template Tagging elements for translat
PAGE 11

Post Pagination Script API Generating output 1415 1440 Print output Fax output Email output Web output Generating Print output Generating Print output from the Designer Generating Print output from Workflow Print settings in a template Aborting content creation Print using standard print output settings Print Presets Print using Advanced Printer Wizard Adding print output Models to the Print Wizard Splitting printing into more than one file Print output variables Generating Fax output Generating Tags for
PAGE 12

OL PlanetPress ConnectRelease Notes 2020.2.1 License Update Required for Upgrade to Connect 2020.x Backup before Upgrading Overview OL Connect 2020.2.1 Enhancements OL Connect 2020.2 Enhancements Connect 2020.2 Designer Improvements Connect 2020.2 DataMapper Improvements Connect 2020.2 Output Improvements Workflow 2020.2 Improvements OL Connect Send Improvements Known Issues Previous Releases OL PlanetPress Connect Release Notes 2020.1 License Update Required for Upgrade to Connect 2019.
PAGE 13

Connect 2018.2 Server Enhancements Connect 2018.2 Output updates Print Wizard and Preset Wizard Improvements Workflow 2018.2 Updates Known Issues Overview Connect 2018.1.6 Enhancements/Fixes Connect 2018.1.5 Enhancements/Fixes Connect 2018.1.4 Enhancements/Fixes Connect 2018.1.3 Enhancements/Fixes Connect 2018.1.2 Enhancements/Fixes Connect 2018.1.1 Enhancements/Fixes Connect 2018.1 General Enhancements Connect 2018.1 Designer Enhancements/Fixes Connect 2018.1 DataMapping Enhancements/Fixes Connect 2018.
PAGE 14

Connect 1.6.1 Designer Enhancements and Fixes Connect 1.6.1 DataMapping Enhancements and Fixes Connect 1.6.1 Output Enhancements and Fixes Connect Workflow 8.6 Enhancements and Fixes Known Issues Overview Connect 1.5 Designer Enhancements and Fixes Connect 1.5 DataMapping Enhancements and Fixes Connect 1.5 Output Enhancements and Fixes Connect 1.5 General Enhancements and Fixes Connect 8.5 Workflow Enhancements and Fixes Known Issues Overview Connect 1.4.2 Enhancements and Fixes Connect 1.4.
PAGE 15

Welcome to PlanetPress Connect 2020.2 Note Since we are always looking for new ways to make your life easier, we welcome your questions and comments about our products and documentation. Use the feedback tool at the bottom of the page or shoot us an email at doc@ca.objectiflune.com. PlanetPress Connect is a series of tools designed to optimize and automate customer communications management. They work together to improve the creation, distribution, interaction and maintenance of your communications.
PAGE 16

Setup And Configuration This chapter describes the PlanetPress Connect installation and the different considerations that are important in regards to the installation and use of PlanetPress Connect. l "System and Hardware Considerations" below l "Installation and Activation" on page 34 l "Known Issues" on page 113 l "Server Configuration Settings" on page 91 l "Uninstalling" on page 124 System and Hardware Considerations There are a variety of considerations to be aware of.
PAGE 17

Directories and folders All Connect applications are installed under an arbitrarily selectable main folder. If the default installation folder options were used, this installation folder would be %PROGRAMFILES%\Objectif Lune\OL Connect. The installation folder will hold all the executable files and other files and folders required for the operation of the whole product suite. All these files and folders remain static after installation.
PAGE 18

Working folders Working folders for Connect are created and used on a per-user-basis under the respective user's profile folder, accessible on Windows with the standardized system variable %USERPROFILE% in the subfolder "Connect". Working folders are: l l l l %USERPROFILE%\Connect\filestore: This folder will hold non-intermediate files for the operation of Connect. Files in this folder will be used frequently, but not with a high frequency.
PAGE 19

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 (external) instance. Using the MySQL Instance from the Installer The MySQL Instance provided in the "Installation Wizard" on page 39is already pre-configured with options to provide the most stable back-end setup.
PAGE 20

Warning If you chose not to install the supplied MySQL database, and instead opt for using a preexisting (External) database then you yourself must ensure that the External database is accessible to Connect. Objectif Lune Inc. will take no responsibility for database connections to any but the supplied MySQL database. Options available within the installer: l l l The Configuration page for the local MySQL is displayed.
PAGE 21

Server is SQL Server 2012. l l l When MS SQL is selected, the default values for root user are sa and 1433 for the port. If database settings from a previous OL Connect installation are found, the pre-exising settings will be displayed for the matching database type. For MS SQL settings, this will only work if they were created with Server Config Tool 1.5.0 or later, or the Installer for OL Connect 1.6.0 or later.
PAGE 22

supplied MySQL service. Note The Microsoft SQL selection capability will be available only with 1.6 version and upwards. To remove this dependency the user needs to do the following 1. Have a foreign Microsoft SQL running, ready for use with Connect Server. 2. Use the Server Configuration Tool "Database Connection preferences" on page 830 to switch the database to Microsoft SQL. 3. Re-start the Connect Server Service, so that the modifications become active. 4.
PAGE 23

l It is not possible to uninstall the supplied MySQL hereafter, when running the Connect 1.5 Installer in Modify mode. Important If a Server Product and a MySQL Product were selected to be installed on Connect 1.5.0, and then the Server Configuration Tool is used to switch the database used by the Server to an external Microsoft SQL, then the Update to 1.6 requires an extra step. The procedure is as follows: 1. Run the Update to Connect 1.6.
PAGE 24

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. Virtual Machine Support PlanetPress Connect supports the following virtual environments: l l l VMWare Environments. This includes VMWare Player, VMWare Workstation as well as VMWare ESX Server. VMWare VMotion.
PAGE 25

PlanetPress Connect 1.3 and later have been certified under Remote Desktop. 32-bit or 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 "Antivirus Exclusions" on page 16 for more information.
PAGE 26

entries and command-line switches are accepted, when one of Connect components is started and run. Please be therefore advised, that any non-whitelisted ini entry or command-line switch will be accepted and will - if tried to be used - lead to the respective application’s “sudden death”. If you should encounter such a behaviour then please double-check your Connect log file/s for respective entries.
PAGE 27

l If a local proxy is configured (in the Internet Explorer Options dialog), the option Bypass proxy server for local addresses must be checked, or some features depending on local communication will not work. Firewall/Port considerations The following describes all of the ports that can be used by an OL Connect solution. IT staff may decide the firewall strategy to follow for their internal requirements and needs depending on the statements outlined herein.
PAGE 28

Listens on port # Microsoft SQL Server HyperSQL Destination port # Type 1433 TCP+UDP 9001 TCP Comment l Port numbers in bold type are user configurable. l Port numbers in bold underlined type are based on the type of database used. l Some of the ports listed above may also be used by other modules. l User-configurable modules may use other ports entirely, depending on the settings defined by the end user.
PAGE 29

average output speed. Likewise, the output speed for an Email or Web template can be found by running it with one Merge engine and the maximum target speed per job. In the Merge engine's log file, search for "PPM". If your jobs are not running at the licensed speed, there may be several ways to improve performance, as described below. Make sure to address all issues mentioned in this topic before deciding that you need to invest.
PAGE 30

preferences. Use the Connect Server Configuration tool to change the Connect Server settings and Designer > Windows >Preferences for changing Designer settings. Template optimization When you find that the speed per Merge engine - the Content Creation speed - is low, optimizing a template can make a huge difference. For advice on how to optimize a template see: "Optimizing a template" on page 1485.
PAGE 31

l l l Consider using a physical machine instead of a virtual machine. When running on a Virtual Machine, the machine may report that it has sufficient hardware (cores) available, but in a virtual environment you need to make sure that this hardware is not being shared with lots of other virtual machines. Consider using hardware with more physical cores.
PAGE 32

Virtual Environments l VMWare/VSphere l Hyper-V l Azure l Amazon Web Services (AWS). Note that only EC2 M4 was certified, other instances may not work as expected. Minimum hardware requirements As with any software application, minimum hardware requirements represent the most basic hardware on which the software will run. Note however that settling for the minimum specification is unlikely to produce the performance you expect from the system.
PAGE 33

l Storage Type: Solid State Drive (SSD) l Networking: 10Gb Ethernet *1 This depends on the amount of data you process through OL Connect. For instance, a PostScript file containing several thousands of documents could easily take up several GBs. Requirements for individual Connect modules OL Connect Products comprises multiple modules that can be operated separately on multiple PCs. Each module has its own set of requirements that may differ from the other modules.
PAGE 34

Installation and Activation This topic provides detailed information about the installation and activation of PlanetPress Connect 2020.2. Note A PDF version of this guide is available for use in offline installations. Click here to download it. PlanetPress Connect 2020.2 is comprised of 2 different installers: one for the PlanetPress Connect software and one for PlanetPress Workflow 2020.2. Where to obtain the installers The installers for PlanetPress Connect 2020.2 and PlanetPress Workflow 2020.
PAGE 35

Installation - "How to" guides For information on how to conduct the installation itself, choose from the following topics: l "Installation Wizard" on page 39 l "Running Connect installer in Silent Mode" on page 47 l "Installing PlanetPress Connect on Machines without Internet Access" on page 37 Activation For information on licensing, please see "Activating a License" on page 57. Installation prerequisites l l l l l l Make sure your system meets the "System requirements" on page 31.
PAGE 36

User accounts and security Windows user account Connect requires local Windows Administrator rights when installing the software and activating the software license. This is to allow read/write access to protected Windows folders and registry entries. Once installed Connect requires only standard Windows user credentials to run.
PAGE 37

The account must have administrative access on the machine. It should also correspond to the user account set up in PlanetPress Worfklow. OL Connect Server user accounts By default, authentication is enabled on the Connect Server. During a new installation the OL Connect Server's default authentication must be configured by specifying a user name and password. The default username for new installations is olc-user.
PAGE 38

will fail because the verification cannot be performed. To solve this problem one must first ensure that all Windows updates have been installed on the host machine. Once the Windows updates are confirmed as being up to date, then complete the following steps: 1. Go to https://certs.godaddy.com/repository and download the following two certificates to copy to the offline machine: l l GoDaddy Class 2 Certification Authority Root Certificate - G2 - the file is gdrootg2.
PAGE 39

1. Open the “Internet Options” via the Control Panel 2. Select the “Advanced” tab and scroll down to “Security” node. 3. Uncheck the entry “Check for publisher’s certificate revocation” under that node. 4. Click the OK button to close the dialog. 5. Re-start the computer. Installation Wizard Updating from Connect versions predating 2019.1 In order to update PlanetPress Connect to 2020.2 from Connect versions prior to 2019.1 it is first necessary to update the Connect License.
PAGE 40

l PlanetPress_Connect_Setup_x64.exe --verbose This adds extra debugging style logging to the installation process. l PlanetPress_Connect_Setup_x64.exe --trace This adds full trace style logging to the installation process. The log file this produces will be very large, as this option logs everything. 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.
PAGE 41

See "Database Considerations" on page 19 for more information about setting up external databases. l Installation Path: This is the location where modules are to be installed. Note To cater for MySQL requirements, the installation path cannot contain any non ASCII characters (such as Asian language Unicode characters). Nor can it contain characters that Windows disallows in filenames (such as '?', ''>' or trailing spaces).
PAGE 42

for the MySQL server as well as which port it uses for communication. The installer will automatically configure the Connect Server to use the supplied password and port. l MySQL user 'root' Password: Enter the password for the 'root', or administration account, for the MySQL server. The password must be at least 8 characters long and contain at least one of each of the following: l a lower case character (a, b, c ... ) l an upper case character (A, B, C ...) l a numeric digit (1, 2, 3 ...
PAGE 43

l Allow MySQL Server to accept non-local TCP connections checkbox: Click to enable external access to the MySQL server. Note This option is required if MySQL Server will need to be accessed from any other machine. It will also be required if the MySQL database is on a separate machine to this PlanetPress Connect installation. Tip This option may represent a security risk if the machine is open to the internet.
PAGE 44

l l l TCP/IP Port Number: Enter the port on which the database server expects connections. For MySQL, this is 3306 by default. For Microsoft SQL Server it is 1433 by default. Server Schema/Table: Enter the name of the MySQL database into which the tables will be created. The Connect standard name is "objectiflune". Administrator Username: Enter the user account of a user with database administrative rights.
PAGE 45

Note This test does not check whether the remote user has READ and WRITE permissions to the tables under the objectiflune schema. It is solely a test of database connectivity. PlanetPress Connect Server Configuration The Server Configuration page is where the Connect Server component is configured. Connect Server settings The Connect Server settings will be available if Connect Server rather than Connect Server Extension was selected for installation.
PAGE 46

Note This button must be clicked and the user validated before the Next button becomes available. l Default OL Connect Server authentication: Defines the username and password to connect to the Connect Server. l Username: Enter the username for connection to OL Connect Server. The default username for new installations is olc-user. l Password: Enter the password to be associated with the selected user. l Confirm Password: Re-enter the password, to confirm password selection.
PAGE 47

l 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, a message will be displayed after clicking “Finish” in the setup. The message details the information that needs to be sent back to Objectif Lune Inc. in order to determine when/if the software needs updating.
PAGE 48

first necessary to update the Connect License. For details on how to upgrade the Connect License see "Users of Connect prior to 2019.1" on page 69 Required and optional properties PlanetPress Connect can be installed in a so called "silent mode" to allow an automated setup during a company wide roll-out or comparable situations. The trigger for the Connect Installer to run in silent mode is a text file with the fixed name install.
PAGE 49

# Verbose logging logging.verbose = true # Product selection install.product.0 = Connect Designer install.product.1 = Connect Server # Server settings server.runas.username = Localadmin server.runas.password = admin # Database configuration database.type = mysql database.host = 192.168.116.10 database.port = 3308 database.username = root database.password = admin database.schema = my_ol Verbose logging (optional) By default, the Silent Installer will log the same way as the GUI installer.
PAGE 50

The values of install.product properties must contain the exact product names. Installation folder (optional) To select an installation folder other than the default during a silent installation: install.directory=C:/Program Files/Preferred/Directory Note This file is a Java properties file. You must use either use forward slashes as shown above, or double backslashes. Using only a single backslash will result in failed installations. If the property is not set, the default path will be used.
PAGE 51

Database configuration Case 1: MySQL is among the selected Connect products to be installed (new MySQL installation) If MySQL is selected and there is no previous MySQL configuration on the machine, the following properties should be defined: database.password = (required and must meet the rules) database.port = (3306 is the default port value) database.
PAGE 52

Case 2: The Connect Server is selected and MySQL is not selected In this case, an external database must be configured for the Server (and other Connect products included in the Silent installation) to be used. 2a: Configuring an external MySQL database To configure an external MySQL database, the following properties should be defined: database.type = mysql (required) database.host = (default value is localhost, otherwise required) database.
PAGE 53

database.usessl = true/false (select whether to deploy using a secure database connection (SSL)or not) Note As of PlanetPress Connect 2020.2 the silent installer no longer requires a valid connection to a database in order to complete. This allows a system administrator to adjust the database connection post-installation, rather than at installation time. The installation log records whether the installer tested the database connection or not, allowing verification post-installation.
PAGE 54

Locale definition It is possible to define the Locale which affects the installation language and installed locale for Connect products by using the following properties in the install.properties file: user.language user.country Locales supported by Connect The Connect Setup supports a dedicated list of Locales, which is saved in the preinstall.ini file.
PAGE 55

Locale selection by defining only user.language If only user.language is defined in the install.properties file, the Installer will attempt to find a Locale in the list which starts with the given language code. The first match is selected for installation. If no match is found, the Installer will exit with an error. For example: user.language = zh, will result in an installation with the Locale zh-CN user.language = no, will result in an error Default Locale selection If neither user.language nor user.
PAGE 56

installation can be started and the exit code can be evaluated. See the sample batch file below. Exit codes 0 = Success 1 = General Error in preinstall (e.g. not supported settings for user.language / user.country, for reason see preinstall_err.log) 2 = Unknown Error in preinstall 10 = General Error in Installer application (for reason see OL_Install_.log) Sample batch file @echo off preinstall.
PAGE 57

Activating a License PlanetPress Connect and PlanetPress Workflow both come with individual 30 day trial license periods during which time it is not necessary to have a commercial license to run the applications. This allows time for reviewing the applications and for organizing a commercial license. If a modification to the trail license is required, such as to allow an extension to the trial period, or for extra functionality, then a new activation code will need to be requested.
PAGE 58

l l End-User License Agreement - Appears only when loading a license file: l l l l l l Expiration Date: Displays the date when the activation will expire, or the current date if the product is not activated. 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.
PAGE 59

Activating PlanetPress Workflow PlanetPress Workflow uses the same licensing scheme as PlanetPress Connect. There are two ways of activating the license for Workflow after saving it to a suitable location: l l If only PlanetPress Workflow is installed, double-click on the license for the PlanetPress Workflow License Activation dialog to open. Applying the license here activates all of the Workflow components.
PAGE 60

Migrating to a new workstation The purpose of this document is to provide a strategy for transferring a Connect installation to a new workstation. The following guide applies to OLConnect v1.x / 201x.x / 202x.x and Workflow v8.x / 201x.x / 202x.x. Before installing the software Before upgrading to a new version, even on a new workstation, consult the product's release note to find out about new features, bug fixes, system requirements, known issues and much more.
PAGE 61

the documents to the version installedand then re-send them to the Workflow Tools. Backing up Workflow files To save all Workflow-related files, backup the entire working directory: C:\ProgramData\Objectif Lune\PlanetPress Workflow 8 Here are a few important points when transferring these files: l l l l If you are upgrading to the latest version of Connect, it is recommended to open each template in Designer, produce a proof making sure the output is correct.
PAGE 62

l l l l l Reconfigure local ODBC connections (i.e. create local copies of databases or recreate required DSN entries). Backup and import other custom configuration files, Microsoft Excel Lookup files, making sure they reflect the same paths as previously. Reinstall required external printer drivers and recreate all Windows printer queues and TCPIP ports.
PAGE 63

Backing up Connect Resources The following resources are used by Connect and can be backed up from their respective folders: l l l l l Job Presets (.OL-jobpreset): C:\Users\ [UserName]\Connect\workspace\configurations\JobCreationConfig Output Presets (.OL-outputpreset): C:\Users\ [UserName]\Connect\workspace\configurations\PrinterDefinitionCo nfig OL Connect Print Manager Configuration files (.OL-ipdsprinter): C:\Users\ [UserName]\Connect\workspace\configurations\PrinterConfig OL Printer Definition Fil
PAGE 64

l l l All PostScript, TrueType, Open Type and other host based fonts used in templates must be reinstalled on the new workstation. Import all dynamic images and make sure their paths match those in the old server. Make sure the new workstation can also access network or remote images, JavaScript, CSS, JSON, and HTML resources referenced in the Connect templates.
PAGE 65

6. Start the Messenger 8 service on new server from the Workflow menu bar: Tools > Service Console > Messenger > right-click and select Start. OL Connect Send l l l As of version 8.6 the Connect Send plugins are installed automatically with Workflow. If you are using an older version, run the OL Connect Send Plug-in Installer on the new Workstation to re-install the Connect Send plugins. Reconfigure the Server URL and port during the OL Connect Send Printer Driver setup.
PAGE 66

l C:\Program Files\Objectif Lune\OL Connect\Connect Merge Engine\MergeEngine.ini l C:\Program Files\Objectif Lune\OL Connect\Connect Weaver Engine\WeaverEngine.ini 4. Now start the OLConnect_Server service Configuring the Server Extensions In the case where the OLConnect MySQL is installed on the new Master Server, it is important to reconnect all Server Extension systems to the new Master Server. Perform the following action on each Server Extension: 1.
PAGE 67

l Upgrades cannot be activated using the automated Activation Manager. Contact your local Customer Care department. To apply the license file received from the Activation Team: 1. Ensure that all services are stopped on your old machine before activating and starting the services on the new machine. Attempting to run the software with the same license simultaneously will not only run into errors but it is a breach of our EULA. 2.
PAGE 68

Information about PlanetPress Workflow If you wish to use PlanetPress Workflow (automation) in conjunction with PlanetPress Connect, you will need to install PlanetPress Workflow 2020.2 as well. Workflow 2020.2 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.
PAGE 69

Upgrading This page provides information about Upgrading to PlanetPress Connect version 2020.2.
PAGE 70

Users of all other Connect versions prior to 2019.1 should note that Update Client 1.2.40 is a prerequisite for both OL Connect 2019.1 and Connect Workflow 2019.1 installations. Only Update Client 1.2.40 has the capacity to upgrade the OL Connect license to the newer format that is required by the installers of those products. If you do not have Update Client version 1.2.40 installed already, then the next time you run your Update Client it will show that there is an update available of itself to Version 1.
PAGE 71

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 Connect version 1.0 cannot upgrade directly to Version 2020.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 2020.2 If you are updating manually you must first upgrade to Version 1.1 before installing 2020.2.
PAGE 72

current Scheduling settings for reference before proceeding with an upgrade. Backup these folders l C:\ProgramData\Objectif Lune\OL Connect\.settings\ConnectHostScope l C:\Users\[UserName]\Connect\filestore l C:\Users\[UserName]\Connect\workspace\configurations l C:\Users\ [UserName]\Connect\workspace\Designer\.metadata\.plugins\org.ec lipse.core.runtime\.settings l C:\Users\ [UserName]\Connect\workspace\Server\.metadata\.plugins\org.ecli pse.core.runtime\.
PAGE 73

Upgrading from PReS Classic PReS Classic and PlanetPress Connect are very different products. Whilst PlanetPress Connect provides considerably more options for email and web output, one need not abandon existing PReS Classic print jobs. They can still be run through Connect Workflow, via the PReS Print Controls task in the Online Help of Workflow (see http://help.objectiflune.com/en/PlanetPress-workflow-userguide/2020.2/#Workflow/TasksProperties/PReS_Print_Control.html).
PAGE 74

l PlanetPress Search IMPORTANT: If you owned them, you must also upgrade your Imaging modules to use the new version. l l l PlanetPress Capture is still supported in PlanetPress Workflow 2020.2 but only with documents created with the PlanetPress Suite Design 7. PlanetPress Connect Designer. This is a design tool based on completely new technology. It is not backwards compatible and therefore cannot open PlanetPress Suite Design 7 documents.
PAGE 75

computer, you should consider having at least 16GB of RAM available. See "System requirements" on page 31. 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 2020.2 to also run PlanetPress Connect Server.
PAGE 76

(see below). 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. You can also now: l l l Use the new DataMapper to easily map any input data into a clean data model that any designer person can use.
PAGE 77

4. If you installed PlanetPress Workflow 2020.
PAGE 78

7.
PAGE 79

8. Then select the product from which you wish to upgrade: 9.
PAGE 80

10.
PAGE 81

11. 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 (http://www.objectiflune.com/webactivationmanager/), follow the instructions for the installation using the serial number provided to you. You can activate your license through the Web Activation Manager. 12.
PAGE 82

PlanetPress Workflow tool to which you want to send the PlanetPress Design document. How to perform a Workflow migration What do you need to consider when upgrading from PlanetPress Suite 7 to PlanetPress Connect Workflow 2020.2 on a new computer? Installing and Activating Workflow 2020.2 on a new computer Points to consider: l l l l Before installing, be sure to read "Installation and Activation" on page 34.
PAGE 83

from the PlanetPress Suite Designer Help > Printer Activation menu option. When the "Activate a printer" dialog is launched, right click within it and select the Export context menu option, then save the file on the new computer. Double clicking on the .pac file will then activate all of your printers on the new computer. l l Login to our Web Activation Manager (www.objectiflune.com/activations) using your customer number and password to get your Printer Activation Codes.
PAGE 84

computer: "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\Documents" 2. Copy all the PlanetPress Suite 7 Documents and Compiled forms (*.ptk and *.ptz) from the Documents folder on the PlanetPress Suite computer and paste them into the equivalent folder on the Connect Workflow Computer. The PlanetPress Suite 7 folder would be "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\Documents". The PlanetPress Connect Workflow 8 folder will be "C:\ProgramData\Objectif Lune\Plan
PAGE 85

Make sure that you copy only the custom plug-ins. Alternatively, you can download custom plug-ins from http://planetpress.objectiflune.com/en/suite/resources/support onto the new computer. Once you've copied your PlanetPress Suite Workflow configurations to Connect Workflow, you can confirm their availability through the Plug-in Bar Uncategorized category. There you will find all the Custom plug-ins that have been installed.
PAGE 86

l l l l l Manually install all external executables that will be referenced by the Connect Workflow processes in the configuration file. If possible, retain the local path structure as used on the older installation. If the Windows "TCP/IP Print Server" service is running on the new computer, it is recommended that you disable the Server so that it does not interfere with the PlanetPress LPD/LPR services. If you are using images from a virtual drive, copy the entire contents of "C:\ProgramData\Objectif
PAGE 87

How to perform a Capture migration This page provides information on how to conduct a proper migration of a Capture solution. For information about Capture see: http://capture.objectiflune.com/en/howitworks. These steps must be executed after a proper Workflow Migration has been completed. Instructions on how to do such can be found here: "How to perform a Workflow migration" on page 82. Failure to do so will result in unexpected problems.
PAGE 88

"C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\capture" and overwrite the existing database. Note Prior to PlanetPress Suite 7.6, all Capture patterns, documents and several other details were contained within the one single database. As of PlanetPress Suite 7.6 a separate database has been used for the patterns alone (PPCaptureDefault.mdb). 5. Copy the contents of this folder: "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\DocumentManager" to this folder: "C:\
PAGE 89

to the old computer will be lost unless the steps to migrate are reproduce again. Once a Pen has been docked and the data transfer done, its memory is wiped, thus rending the parallel mode very hard to produce. It is not impossible, but describing how it can be done is beyond the scope of this migration article. Steps to migrate: 1. Update existing installation to PlanetPress Suite version 7.6 if not already done. 2. Install PlanetPress Connect Workflow 2020.2 on new computer. 3.
PAGE 90

2. Select Messenger in the tree list, right click and select Stop from the context menu. Note These steps must be done for both PlanetPress Suite Workflow 7 and PlanetPress Connect Workflow 8. 5. Copy the file PPCaptureDefault.mdb from this folder on the PlanetPress Suite 7.6 computer: "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\capture" to this folder on the new PlanetPress Connect Workflow 2020.2 computer: "C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\c
PAGE 91

> Service Console). 2. Select Messenger in the tree list, right click and select Start from the context menu options. 9. Contact your local Objectif Lune activation team and transfer any Pen(s) licenses across. Server Configuration Settings This chapter describes configuring the PlanetPress Connect Server. The Connect Server settings are maintained by the Connect Server Configuration utility tool which is installed alongside PlanetPress Connect.
PAGE 92

l Engines preferences l "Automatic Restart Settings" on page 102 l "Hardware for Digital Signing preferences" on page 842 l "Language preferences" on page 103 l "Logging preferences" on page 844 l "Parallel Processing preferences" on page 103 Connection preferences Background The Connection preferences are a way to control precisely how to connect to the PlanetPress Connect Connect Server. This preference page was added in Connect 2018.2 to simplify management of HTTP communication with Connect.
PAGE 93

Note This does not limit the number of requests that can be received, just how many are processed in parallel. Additional requests are buffered and are processed as capabilities allow. The default setting is twice the number of processing cores available to the computer. This can be expanded, if the limitation is deemed a bottleneck. l Dedicated Internal Connection checkbox: Set the internal connection HTTP communication setting values. These settings are purely for Connect inter-engine communication.
PAGE 94

Settings for these engines are made in the Connect Server Configuration tool (see "Server Configuration Settings" on page 91). Connect allows for the parallelization of jobs. This means you can allocate 1 or more engines to process jobs. The number of each type of engine is configurable, as well as the amount of Merge engines than can work together on the same job (determined by job size: small, medium or large) and at what maximum speed.
PAGE 95

l l The processing power of your machine. How many cores it has determines how many engines can be launched (see "Launching multiple engines" on the facing page). The size and number of jobs of one kind that need to be handled, sequentially or simultaneously. In other words, your use case. By allocating processing power to jobs of different sizes you can make the setup match your usage situation (see "Allocating processing power to jobs" on page 98).
PAGE 96

In situations where Print and Email and/or Web output are created at the same time, only the Merge engines that create Email/Web output count towards the maximum number of Licensed tasks for that type of output. Spare speed units are distributed proportionally Since the number of engines is configurable, and jobs may run concurrently, the number of engines in use may not match the exact number of available Licensed tasks.
PAGE 97

1. Open the Connect Server Configuration utility tool (see "Server Configuration Settings" on page 91). 2. Under Parallel Processing, go to the Content Creation tab and set the number of Merge engines for the various tasks. 3. Go to the Output Creation tab and set the Reserved Weaver (Output) engines. See "Deciding how many engines of each type to launch" below. 4. Click Apply or Apply and Close. It is advised that you do not configure more engines than can be backed by actual processing power.
PAGE 98

When the database is installed on a system with a slow hard drive, adding a DataMapper engine may not increase the overall performance. Weaver engine Adding extra Weaver (Output) engine(s) might be useful when large Print jobs are to be run simultaneously with smaller Print jobs. Memory per engine By default, each engine is set to use up to a predetermined amount of RAM. To make optimum use of a machine's capabilities it might be useful to increase the amount of memory that the various engines can use.
PAGE 99

The first step in this process is to define the size of small, medium and large jobs. Job size Connect lets you define job sizes by setting the maximum number of pages a job can have and still be considered a small job, and what the minimum number of pages a job can have in order to be considered large. Jobs that fall between the small and large jobs are medium jobs.
PAGE 100

handled at the same time by that kind of engine, because there are only so many engines (and speed units) available. Note When each individual record in a job is composed of a very large number of pages, the Memory per engine setting and the machine's hard drive speed are probably more important than the number of Merge engines, since one record cannot be split over multiple cores (see "Memory per engine" on page 98).
PAGE 101

may have to wait (or wait longer). However, if the server receives many web requests then having engines reserved for HTML output can help performance. l l By reserving a number of parallel engines for Print jobs of a certain size (see "Number of parallel engines per Print job" on page 99). More parallel engines will make them run faster, but they will have to wait (longer) if the required number of engines isn't available when they come in.
PAGE 102

Batch processing. In a batch processing situation, jobs don't have to be handled simultaneously. All jobs - whether they are big and small - are processed one after another. Every job should be handled as quickly as possible. It is therefor recommended to assign the maximum number of engines and target speeds to all jobs. Do not reserve engines for certain jobs. Web requests. In online communication, response times are critical.
PAGE 103

l l Daily restart period begin: Only available if Daily restart in period selected. Enter the daily start time for the time window in which automatic restarts will be scheduled to occur. Daily restart period end: Only available if Daily restart in period selected. The end of the daily time window in which the automatic restarts are scheduled to occur. Memory limit Enter the memory limit for individual Engines.
PAGE 104

Parallel Processing properties (Designer Preferences) Preset selection (Designer Preferences) Only the Custom setting is applicable to the Designer Preferences, so this option is always selected and the field made read-only. Content Creation Tab (Designer Preferences) A Tab with data that relates solely to Content Creation. The options are: l l Total Merge engines configured read only display: This is a read only entry that shows the total number of Merge engines available.
PAGE 105

l Additional engine every (records) entry: This controls how many Merge engines are used for a Content Creation task. It means that for every additional 'x' records in the task, an additional Merge engine will be used. For example, with the default 100 record threshold, tasks with 1-100 records will be assigned 1 Merge engine, tasks with 101-200 get assigned 2 merge engines, tasks with 201-300 get assigned 3 merge engines, and so on. Note These entries aren't applied instantaneously. There is often a lag.
PAGE 106

l l l l l l l Default - Basic settings that are good for running most things. Single jobs have preference over multi-tasking, however. Batch Print - Best settings for processing jobs, one by one, in a sequential, first in first out (FIFO) order. On demand Print - Best settings for processing many small print jobs simultaneously. On demand - Use when serving web pages, sending emails, and printing many on demand jobs simultaneously. Connect Send - Settings optimized for use with Connect Send.
PAGE 107

l Multi tasking group: When starting a new Content Creation task, the task will immediately commence if there is a Merge engine available. How many Merge engines to use is based on the number of records in the input data. Select from the following options: l Optimize per task: This runs each task with as many Merge engines as needed (until engines are exhausted). Using this option means that Merge engines will not be reassigned when new tasks come in. This option is better suited for batch processing.
PAGE 108

number, not because it has been proven to have any significant value. It means that on an average system (i.e., less than 10 Merge engines) any decently sized task is allowed to use all Merge engines. It also assumes that using more than one Merge engine for less than 100 records will probably not make a big enough difference to throughput speed. Obviously, there are situations where these assumptions will not apply.
PAGE 109

If only the single Weaver Engine is configured in the Engines preferences page, then this whole tab will be disabled. l l Licensed speed limit (pages per minute): This read only entry shows the current license speed limitations, in pages per minute. The speed limitations are determined by your Connect license. This information is to help you choose what settings would make sense when assigning the “Target speed” values later in the Tab.
PAGE 110

l l l Small job (engines): Optionally enter the number of Weaver engines you wish to reserve for Small jobs. To make sure large batch jobs get sufficient speed during Output Creation, set a lower target speed for small jobs, this will automatically allow more for the large and medium jobs. Medium job (engines): Optionally enter the number of Weaver engines to reserve for Medium jobs. Total Weaver engines configured: This read only entry shows the number of Weaver engines still available.
PAGE 111

The entire licensed speed limit will always be distributed among jobs when running jobs simultaneously. After assigning a target speed, any remaining licensed speed will be distributed throughout any simultaneous jobs by a ration of the target speed. Some general rules of thumb to apply when distributing target speed: n Do you need to change speeds? In many cases there will likely be no need to change the target speed.
PAGE 112

server accessible from the web. If these precautions are not taken, data saved in the server may be accessible from the outside! l l l Enable server security: Enable to add authentication to the REST server. - When enabled, the username and password (which cannot be blank) of an authorized user must be entered in any remote Connect Designer that links to this Server. See the "Connect Servers preferences" on page 851 sub-section of the Designer Preferences dialog.
PAGE 113

Known Issues This page lists important information about issues that apply to PlanetPress Connect 2020.2. Changed Omit Master Page Back behaviour In versions of Connect prior to 2020.2, if a page had no content except for a linked DataMapper background, then Connect would consider it an "empty" page when determining whether or not to "Omit Master Page Back in case of an empty back page" (available as an option in the sheet configuration of a section). This has now been fixed in Connect 2020.
PAGE 114

l MSVC++ 2017 v14.14.26405.0 l MSVC++ 2017 v14.14.26429.4 To workaround this issue, we recommend downloading and manually installing the latest Visual C++ Redistributable from https://support.microsoft.com/en-ca/help/2977003/the-latestsupported-visual-c-downloads then re-running the Connect installation. Issues associating PDF files with Connect Under certain circumstances, Connect Setups prior to 2019.2 would fail when attempting to add the "Enhance with Connect" association with PDF files.
PAGE 115

Page break changes in 2019.1 Improved page breaking in Connect 2019.1 might impact upon some existing templates. It is recommended that you check page breaking in existing jobs, where page breaks at a specific location are a known criteria.
PAGE 116

EXECUTE `bd`; DEALLOCATE PREPARE `bd`; set @a:=concat('optimize table ',@a); PREPARE `sql` FROM @a; EXECUTE `sql`; DEALLOCATE PREPARE `sql`; set @a=null,@b=null,@c=null; If using MySQL, the following script should be run in a query window: sp_updatestats Windows 10 Search service impacting Connect The Windows 10 Search service runs as a background task, indexing files and folders.
PAGE 117

Engine Preferences: Backward Compatibility Issues introduced in 2018.2 l Prior to version 2018.2 Connect allowed a mixture of internal and external engines. As of PlanetPress Connect 2018.2 this is no longer allowed. When upgrading to PlanetPress Connect 2018.2 from such installations, the pre-existing settings will not only no longer apply, but can cause scheduling preference conflicts for the Merge and Weaver engines.
PAGE 118

(see "Preparing a data table" on page 685 in the Online Help: https://help.objectiflune.com/en/PlanetPress-connect-user-guide/2020.2.). Otherwise the data needs to be transposed via script. l NOTE: Expanded custom chart scripts cannot be converted. Pie charts l Default colors: The default colors (used when no pie chart colors are specified) have changed.
PAGE 119

Please note, however, that the Objectif Lune Inc. Update Client application might be blocked by the enhanced security settings in Windows Server 2016. To fix this, add http://updates.ca.objectiflune.com to the list of trusted web sites on that machine, or lower the internet access rules. Limit of 100MB of image files within a single job The browser component (Mozilla Gecko) used in the WYSIWYG editor of the Designer was updated for Connect 2018.1. This allows use of new CSS properties, such as flexbox.
PAGE 120

Installation paths with multi-byte characters When installing the Chinese (Traditional or Simplified) or Japanese versions of Connect, if the user specifies an alternative installation path containing multi-byte/wide-char characters it can break some of the links to the Connect-related shortcuts in the Start Menu and cause an error to appear at the end of the installer. The workaround for the moment is to use the default installation path. The problem will be addressed in a later release.
PAGE 121

MySQL Compatibility After installing Connect 2020.2 a downgrade to a Connect version earlier than Connect 1.3 or to a MySQL version earlier than 5.6.25 is not seamlessly possible. This is because the database model used in Connect 1.3 and later (MySQL 5.6) is different to that used in earlier versions. If you need to switch to an older version of Connect / MySQL, it is first necessary to remove the Connect MySQL Database folder from "%ProgramData%\Connect\MySQL\data" before installing the older version.
PAGE 122

External resources in Connect There are certain limitations on how external resources can be used in Connect. For example if you want to link a file (e.g., CSS, image, JavaScript etc.) from a location on the network but you do not want to have a copy of the file saved with the template you need to do the following: 1. The resource must be located where it can be accessed by all Servers/Slaves run as users.
PAGE 123

Color Model in Style Sheets The color model of colors defined in a style sheet can sometimes change after editing the style sheet. This is a known issue and will be addressed in a subsequent release.
PAGE 124

model. Fields of other types will not be updated in the database and no error will be raised. This will be fixed in a later release. Print Limitations when the Output Server is located on a different machine The following limitation may occur when using the Print options from a Designer located on a different machine to the Output Server: l l l The file path for the prompt and directory output modes is evaluated on both the client AND server side.
PAGE 125

To uninstall PlanetPress Connect select the application from within the Add/Remove programs option under the Control Panel. This will start the PlanetPress Connect Setup Wizard in uninstall mode. Note The PlanetPress Connect Setup Wizard might take some seconds to appear. Important: Stop any active Anti-Virus software before uninstalling Connect.
PAGE 126

l Delete Connect Workspace Data: Check this box to delete the Workspace data for the current user, or for selected users (as determined by the "Select Users" button) l l Backup Connect Workspace Data for all specified Users: Check this box to backup the Workspace data for the specified users (as previously determined) into a compressed ZIP file (whose location can be customized), before deletion of the full Workspace data.
PAGE 127

General information Connect consists of visible and invisible parts. The invisible parts process the Connect job to provide the actual output. They are introduced to you in the topic: "Connect: a peek under the hood" below. For information about Connect logging, see "Log files" on page 132. For a list of all file types used in Connect, see: "Connect file types" on page 134.
PAGE 128

The Workflow server The Workflow server (also referred to as the 'Watch service') executes processes independently, after a Workflow configuration has been uploaded and the services have been started. The Workflow server can run only one configuration at a time. There are a number of services related to Workflow.
PAGE 129

tool. The Workflow Service Console lets you start and stop the different services, except the Connect server, and see their log files (see Workflow Service Console). Note that Workflow isn't limited to Connect functionality. It was originally developed as part of the PlanetPress Suite. Many of the plugins in the Workflow configuration tool are older than Connect. They were left in for compatibility reasons, even though they aren't all useful or usable within Connect.
PAGE 130

The Connect Server Configuration tool lets you change the settings for the Connect server, the engines and the service that cleans up the database and the file store. These settings can also be made in the preferences of the Designer. The Connect database The Connect database is the database back-end used by Connect itself when processing jobs. It can be either the MySQL instance provided by the Connect installer, or a pre-existing (external) instance (see "Database Considerations" on page 19).
PAGE 131

The engines DataMapper engine/s. A DataMapper engine extracts data from a data file. The number of DataMapper engines is configurable (Engines preferences). Merge engine/s. A merge engine merges data with a template using the scripts in the template, in order to create (Print,Email or Web) content items. The number of merge engines is configurable (see Engines preferences): it can be increased depending on the capacity of the machine that runs the solution (see "Performance considerations" on page 28).
PAGE 132

Printing and emailing from the Designer To print or send email from within the Designer, the PlanetPress Connect service has to be running. The service is started automatically when the Designer starts, but it may not be running if the Connect Server and the Designer are installed on different computers. The PlanetPress Connect service can be found on the Services tab in the Task Manager. For a proof print the Connect server is not used. Proof printing is always done locally, by the Designer.
PAGE 133

Every time output is generated, the Designer and/or Connect Server and any engines involved in the operation produce their own log files. Each component writes its log files to a dedicated subfolder of the Log folder. Merge engines write to the logs/Mergeengine folder, Weaver engines to the logs/Weaverengine folder, DataMapper engines to the logs/Datamapperengine folder, Server to the logs/Server folder, and so forth. Note that actions of the Cleanup service are only logged in the Server's log file.
PAGE 134

l l The Designer's logging preferences are set via the Designer; see: "Logging preferences" on page 844. The Connect Server's settings are maintained by the Connect Server Configuration utility tool; see "Server Configuration Settings" on page 91. The logging level that is set applies to the Server as well as the engines. The Designer's log messages are also displayed in the Messages pane (see "Preflight Results and Messages" on page 1045).
PAGE 135

l l l l .OL-package: A transfer file used to package one or many of the above files (the data model being part of both the template and the data mapping configuration). Created by using the File > Package dialog. (See "Package dialog" on page 967.) .OL-script: One or more Designer scripts. Scripts personalize the output of a template. They are either added via wizards (see "Personalizing content" on page 770) or selfwritten (see "Writing your own scripts" on page 853).
PAGE 136

OL Connect projects An OL Connect project is an automated process, or combination of processes, in which the Connect Server and Database are used. (For an overview of the architecture of the OL Connect software, see "Connect: a peek under the hood" on page 127). Typically, an OL Connect project aims at automating (part of) a company's communication with its customers, suppliers, or other parties.
PAGE 137

Tip Project Wizards The OL Connect software comes with a number of Project Wizards that generate a Workflow configuration, and any Connect templates, data mapping configurations, and Print Presets required to make the project work. For more information, see "Project Wizards" on page 981 in the online help or the Project Wizards overview video on the OL Learn website.
PAGE 138

Tip The Designer can send templates, data mapping configurations and print presets to a Connect Server; see "Sending files to Connect Server" on page 434. Project Wizards A Project Wizard generates a small Connect solution that is ready to be tested and deployed. The solution contains a specific Workflow configuration, as well as the Connect templates, data mapping configurations, and any Job Presets and Output Presets that are used in that configuration.
PAGE 139

o A single PDF for the entire job (in which the invoices are grouped per customer). o One PDF per customer. One PDF per invoice. (See: "Project Wizard: Print Transactional Jobs" on page 161.) The Workflow process implements the typical Print plugins (see "Print processes with OL Connect tasks" on page 186). o l l l l Basic web page. This project serves a simple web page, personalized via URL parameters. (See: "Project Wizard: Serving a Web Page" on page 174.) Submitting data with webforms.
PAGE 140

Note In order to use the project, OL Connect Server and OL Connect Workflow must be installed on the local machine. The wizard lets you select the folder in which you want the solution to be installed. In the selected folder, the Project Wizard will create two subfolders: Configurations and Workspace. The project's resource files are saved to the Configurations folder. The Workspace folder is used for debugging or running the solution.
PAGE 141

Running the project Having tested the project, you will be ready to send it to Workflow; see Saving and sending a Workflow Configuration in Workflow's Online Help. The project will run when you copy the Sample Data.xml file from the Configurations\Data folder to the Workspace\In folder. By default the project will still send all the emails to the sender's address. To change this: 1. Open the Create Email Content task and select the Email Info tab; then uncheck the Send emails to sender (test mode) option.
PAGE 142

Two attachments are added to the email, in different ways. l l The Return and Refund Policy PDF is stored in the template (in the Images folder). Rightclick the Email section and select Attachments to see how this is attached to the email. The delivery note is a dynamic attachment, based on a data field. It is attached to the email by the Attachment script. To learn how to create dynamic attachments, see "Dynamic attachments: creating file names based on data fields" on page 519.
PAGE 143

Double-click on a task to see its properties. l l l l The Folder Capture task reads the project's Workspace path from a global variable. The value of that variable is set by the project wizard when it installs the project. The Execute Data Mapping task extracts data from the sample data file and outputs them in the Metadata. The Create Email Content task creates the emails, using the Metadata as data source. Note that it sends the emails in test mode, which means it will send the emails to the sender.
PAGE 144

Using a Workflow variable The path to the delivery note is constructed via JavaScript: automation.variables.em_basic_workspace + '\\Delivery Notes\\' + record.fields.OrderNumber + '.pdf'; The script uses a property: automation.variables.em_basic_workspace, which is defined in the Preprocessor step. (See also: "Properties and runtime parameters" on page 250.) In this case, the variable holds the project's path. The order number in the path is extracted from the sample data.
PAGE 145

Workflow" on page 433). Then open the Workflow configuration, double-click the Execute Data Mapping task to open it and select the new data mapping configuration. To capture input data from a different source: 1. Replace the Folder Capture Input task by the appropriate Input task. See: Input tasks in Workflow's Online Help. 2. Add a Send to Folder task directly after the new Input task and set its output folder to the Workspace\Debug folder (%{global.pr_prom_workspace}\Debug).
PAGE 146

In order to further personalize the email, open your data mapping configuration (or JSON data, if the input data will be in that format; see "Adding JSON data from a JSON file" on page 783) and use the data fields to personalize the email. (See: "Personalizing content" on page 770.) Tip The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two.
PAGE 147

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

1. If the templates and data mapping configurations haven't been sent to Workflow yet, do that first (see "Sending files to Workflow" on page 433). This requires that the Workflow service is running (see Starting the Workflow service in Workflow's Online Help). 2. Send the Workflow configuration to the Workflow service; see Saving and sending a Workflow Configuration in Workflow's Online Help. 3. Open the Workflow configuration from the project's Resources\Workflow folder. 4.
PAGE 149

Project details The templates The form The COTG Timesheet Form template contains a Web context with one Web section: Section 1 (see "Web pages" on page 528 and "Forms" on page 697). The form has regular Form elements as well as COTG elements (see "Form Elements" on page 702 and "COTG Elements" on page 689). The template was started with the Time Sheet Wizard (see "Capture OnTheGo template wizards" on page 560), which also provides the necessary JavaScript files and style sheets.
PAGE 150

The template also contains a dynamic table which is filled and expanded dynamically by the scripts in the Table folder. To learn how to insert and edit such a table, see "Dynamic Table" on page 801. Note that this table does not use one of the default table styles, and that the style sheet with the default table styles is not present in the template. To add that style sheet to the template, insert a table using the Dynamic Table wizard.
PAGE 151

processes with OL Connect tasks" on page 188 and "Print processes with OL Connect tasks" on page 186). Creating the forms The cotg_ts_deploy_form process is triggered when any file enters the Workspace\In folder, but its Execute Data Mapping task expects an XML file that is structured exactly like the Sample Data.xml file (in the Resources\Data folder). The Execute Data Mapping task outputs records in the Metadata.
PAGE 152

the app. This way there is no need for the COTG user to wait while output is being generated. The response to the app can be sent right away. The cotg_ts_generate_report process picks up the XML file from the Temp folder, converts it to JSON and saves it to a JSON file. Note how the Branch task keeps a backup of the job file. It is the backup file - the XML - that is handed down to the next Branch, where it is saved as an XML file.
PAGE 153

Saving input as sample data Testing a process in Debug mode is only possible with a sample data file. The process is preconfigured to use the Sample Data.xml file located in the Configurations\Data folder. To create your own sample data file: 1. Locate the Workflow configuration in the Configurations\Workflow folder and open it in Connect Workflow. 2. Select the process. 3. Enable the Send to Folder step (step 2 in the process). 4.
PAGE 154

l Add text, images and other elements (see "Content elements" on page 612) l Change the layout (see "Styling and formatting" on page 726) l Change the "Media" on page 488. If you have an image of the stationery the PDF will be printed upon, add it to the Media to make designing the template little easier.
PAGE 155

Project Wizard: Print Promotional Jobs The Print Promotional Jobs Project Wizard creates a simple, yet complete OL Connect project that produces promotional print output. The project extracts data from an XML file and uses that data to personalize a promotional letter. The output is a single file containing all the letters, in the format that was selected in the wizard (PDF, PCL or PostScript Level 3).
PAGE 156

stationery (stored in the OL Connect template) in the output. This is a setting in the Output Creation Preset (see "Print settings" on page 158). Testing and running the project Once the Project Wizard has finished the installation, the project is ready to be tested. 1. Locate the Workflow configuration in the Configurations\Workflow folder and open it in OL Connect Workflow. 2. Select the pr_prom_generate_output process. 3. Open the Debug ribbon and click Run.
PAGE 157

Personalization is mostly done via simple text scripts. Such scripts look for a text surrounded by @ (e.g. @city@) and replace that by the correct data. To add a text script you just drag-anddrop data onto the template. (See: "Variable Data" on page 785.) A few scripts are a little bit more sophisticated. l l l l l The sales_rep script combines some data fields and adds a line break. Double-click the script to open the Text Script Wizard with which this script was made.
PAGE 158

Configurations\Resources folder and select the data mapping configuration: PR_PROM Data XML. Print settings The Print context and Print sections can have their own print settings, such as Duplex printing or binding style (see "Print settings in the Print context and sections" on page 463). But in this template, they don't have any. The way the letter is outputted is determined (mostly) by an Output Creation Preset. The Project Wizard installs six Output Creation Presets; two for each type of output.
PAGE 159

plugin is set to handle the output 'Through Workflow'. This means that the task will return the output file to the Workflow process. l The Send to Folder Output task. This task writes the output file to a subfoler in the Workspace\Out folder. It makes use of system variables (see Standard variables) to dynamically create a subfolder based on the current month and year (%M_%y). The name of the file consists of the original file name (%O), the current time (%h%n%s) and the file extension.
PAGE 160

Note If the input data is JSON, you don't need a data mapping configuration: JSON data can be used in a template as is. See: "Adding JSON data from a JSON file" on page 783. However, if you want the data to be saved in the Connect database, let the XML/JSON Conversion plugin convert the JSON to XML and create an XML data mapping configuration to extract the data. Template There are countless ways to customize the template to meet your exact requirements.
PAGE 161

Print output To save the output to another kind of file, you could use one of the other Output Creation Presets. To do that, adjust the process in Workflow: double-click the All In One task to open it, and select the Output Creation Preset of your choice on the Output Creation tab. To change the settings in an Output Creation Preset, open it in the Designer: 1. Select File > Output Creation Presets from the menu 2. Click the Import button and browse to the Configurations\Resources\Output presets folder to s
PAGE 162

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

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

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

Print settings A Print context and Print sections can have their own print settings (see "Print settings in the Print context and sections" on page 463). The only print setting that the Print section has in this template, is the Duplex setting. (Right-click the section and select Sheet Configuration. See also: "Sheet Configuration dialog" on page 1004.) All other print settings are in the three Output Creation Presets. These are used by the Create Output tasks in the Workflow process.
PAGE 166

Workflow configuration Whenever new input data appears in the Workspace\In folder, the invoices are automatically merged with the data and printed to one file, one file per customer, and one file per invoice. That is, if the Workflow server is running with the Workflow configuration installed by the Project Wizard. (See "Running the project" on page 163.) This project's Workflow configuration contains just one process.
PAGE 167

4. Double-click the Folder Capture Input task and change the file mask, or replace the task by the appropriate Input task. See: Input tasks in Workflow's Online Help. 5. Double-click the All In One task and select the new data mapping configuration on the Data Mapper tab. Note If the input data is JSON, you don't need a data mapping configuration: JSON data can be used in a template as is. See: "Adding JSON data from a JSON file" on page 783.
PAGE 168

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

handles the submitted data, saving them to the Data Repository. For an introduction to this Project Wizard, see Project Wizards overview video on the OL Learn website (start at 16:50) or on Youtube: Submitting Data with Web Forms. Installing the project From the menu, select File > New > Project Wizards > Submitting Data with Web Forms to start the wizard. See also: "Submitting Data with Web Forms - Project Wizard" on page 987.
PAGE 170

4. Fill in some data and submit the form. You will now be presented with a Thank You web page. Saving input as sample data Testing a process in Debug mode is only possible with a sample data file. The process is preconfigured to use the Sample Data.xml file located in the Configurations\Data folder. To create your own sample data file: 1. Locate the Workflow configuration in the Configurations\Workflow folder and open it in Connect Workflow. 2. Select the process. 3.
PAGE 171

Dynamic content is inserted by scripts, which are listed on the Scripts pane. You can doubleclick a script to open it. The scripts in the Thank you folder only affect the thank_you Web page; on the form Web page, nothing matches their selectors. Tip Hover over the name of a script in the Scripts pane to highlight parts of the template that are affected by the script.
PAGE 172

The Delete task is an Output task that does nothing, actually; it doesn't even remove anything. However, this step is useful when running the project step by step in Debug mode. When it is followed by another task, the Create Web Content task returns its output to the Workflow process, where it can be viewed (click View as HTML). The data mapping configuration To extract the submitted data from the job file (the request XML), the process uses the data mapping configuration: WEB_FORM Data.
PAGE 173

3. Upload the Workflow configuration to the server (see Saving and sending a Workflow Configuration in Workflow's Online Help) and let the process save the input data to a file (see "Saving input as sample data" on page 170). 4. Use the saved file to add the new data to the data mapping configuration (see "Opening a data mapping configuration" on page 202). Send the data mapping configuration to Workflow. 5.
PAGE 174

Wizard" on page 523. Workflow configuration Serving the two web pages could also be achieved using separate processes, but in fact it is more efficient to have a single process, as activity needs to be monitored for each process. In real life the submitted data will probably not be stored in the Data Repository, but used differently. This means that the Push to Repository task will need to be replaced by the appropriate tasks, but that won't change the way the submitted data is retrieved.
PAGE 175

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

1. Locate the Workflow configuration in the Configurations\Workflow folder and open it in Connect Workflow. 2. Select the process. 3. Enable the Send to Folder step (step 2 in the process). 4. Send the Workflow configuration to PlanetPress Workflow service (see Saving and sending a Workflow Configuration) and run it again, with a custom name value. The Send to Folder step will now write the input data - the job file - to a file in the Workspace\Debug folder.
PAGE 177

l l The My name is script looks for an element that has the ID: hero. Inside that element it looks for the text: @name@ and replaces that with either the default name ("John Doe") or the name given in the URL. The Year script puts the current year in the footer. For more information about writing scripts, see: "Writing your own scripts" on page 853. Tip You don't have to write a script yourself if you just want to insert some data directly into the template.
PAGE 178

To create the data mapping configuration, the input data needed to be saved to a file first (see "Saving input as sample data" on page 175). The sample data file is located in the Configurations\Data folder, but you will also see it when you open the data mapping configuration itself: For more information about data mapping configurations see "The DataMapper" on page 196. Customizing the project A project is a great starting point for building an OL Connect solution.
PAGE 179

Web page There are countless ways to modify the template. You could add text, images and other elements (see "Content elements" on page 612) and change the layout (see "Styling and formatting" on page 726). In order to further personalize the web page, open your data mapping configuration (or JSON data, if the input data will be in that format; see "Adding JSON data from a JSON file" on page 783) and use the data fields to personalize the page. (See: "Personalizing content" on page 770.
PAGE 180

For general information about processes in Workflow see About Processes and Subprocesses, in the Online Help of Workflow. Workflow processes in OL Connect projects About Workflow processes A Workflow configuration consists of one or more processes. Each of these processes waits until it is time to run or until it receives the necessary input, and then does its job. A process is made up of tasks (also referred to as plugins). In the Workflow configuration tool they are divided into groups.
PAGE 181

These are the most common Workflow processes in Connect solutions. l l l l Print process. A process that results in print output implements either the typical OL Connect Print plugins, or the All in One plugin which combines the Print plugins; see "Print processes with OL Connect tasks" on page 186. Email process. An email process outputs one or more emails; see "Email processes with OL Connect tasks" on page 184. Web process. A web process serves one or more web pages.
PAGE 182

This topic describes the available OL Connect tasks, which are commonly used in Workflow processes in OL Connect projects (see "Workflow processes in OL Connect projects" on page 180). Data extraction The Execute Data Mapping task is likely to appear in a lot of OL Connect Workflow processes. It generates a record set in the OL Connect database by executing a data mapping configuration on a data source. Output creation Merging the records with a template is the job of one of the following tasks.
PAGE 183

The Create Preview PDF task generates a PDF preview for a single record as fast as possible. This preview is typically used for PDF previews embedded in web pages. PlanetPress Suite Documents The Create PDF/VT task creates PDF/VT files from a PlanetPress Suite Document (created with PlanetPress Design). This PDF/VT is compatible with the Create Print Content task directly, without the use of an OL Connect template (PDF/VT mode).
PAGE 184

configuration tool has three tasks to that end: the File Store - Upload File task, File Store Download File task, and File Store - Delete File task. Capture OnTheGo Workflow processes A Capture OnTheGo solution requires no less than three basic processes in a Workflow configuration: l l l One process that generates a document (most often, a form), stores it and notifies the COTG app of the document's existence. Note that this process doesn't send the actual document.
PAGE 185

Tip An easy way to create a Connect email project, including the Workflow configuration and the files that it needs, is to use a Project Wizard. See "Project wizard: Basic Email" on page 139. The structure of an OL Connect email process In an OL Connect Email process only one plugin is essential: the Create Email Content plugin. The Create Email Content task creates a set of emails, using the Email context in a Connect template, and sends them to the email server.
PAGE 186

l l A template with an Email context. (See "Creating a template" on page 428.) If the email should contain variable data, you might need to make a data mapping configuration (see "Creating a new data mapping configuration" on page 198). If the input is going to be JSON data, you could add them to the design using a JSON file (see "Adding JSON data from a JSON file" on page 783).
PAGE 187

l l l l The Execute Data Mapping task, or the Retrieve Items task. The Execute Data Mapping task extracts data from the job data file and puts them in a record set. This task works according to the instructions in a data mapping configuration, made with the DataMapper (see "Data mapping configurations" on page 197). The Retrieve Items task retrieves records from the OL Connect database. The Create Print Content task. This task merges data with a template, resulting in Print Content Items.
PAGE 188

In addition, the process may use: l l l A data mapping configuration, or a data model at the very least, if the documents should contain variable data. (See "Creating a new data mapping configuration" on page 198.) A Job Creation Preset. (See "Job Creation Presets Wizard" on page 1151.) A Job Creation Preset defines where the output goes and makes it possible to filter and sort records, group documents, and add metadata. An Output Creation Preset. (See "Output Creation Presets Wizard" on page 1168.
PAGE 189

The structure of a web process In a web process two plugins are essential: l An Input task. l The Create Web Content plugin. If the Input task is a Server Input task, that task will return the output of the process - the web page - to the caller. The HTTP Action of the Server Input task determines how the process is triggered. If, for example, the HTTP Action is /hello, the process will be invoked when the Workflow server receives a request for a resource called hello.
PAGE 190

The Create Web Content task can be found on the OL Connect tab of the Plug-In Bar in Workflow. For a description of all mentioned OL Connect tasks, see "OL Connect tasks" on page 181. Files used in a web process Before creating the web process in the Workflow configuration tool, you will need to create: l l A template with a Web context. (See "Creating a template" on page 428.
PAGE 191

The Workflow tasks mentioned here can all be found on the OL Connect tab of the Plug-In Bar in Workflow. For descriptions of the tasks, see "OL Connect tasks" on page 181. Batching Batching refers to creating print jobs from print content items that were created earlier. A batching print process is split up in 2 phases: l l Phase 1: Content is created by merging a print template with data. Newly created print content items are always automatically saved in the Connect database1.
PAGE 192

l l From a performance perspective, working with content sets is better. Retrieving content sets is faster than retrieving content items and thus can improve performance. Also, working with Job Creation presets is more efficient than working with individual content items in Workflow.
PAGE 193

l Through a Post Pagination script in the template. (See "Post Pagination Scripts" on page 906 and "contentitem" on page 1416.) In order to retrieve (sets of) items by data values, you may have to adjust the data mapping configuration (see "Data mapping configurations" on page 197). Note that a property can only be used to retrieve entities on the level on which the property was explicitly set.
PAGE 194

l l Values: Print content items and sets don't contain data fields, but they do have a link to the data record with which they were created, so selecting and sorting them by value is still a possibility. Properties are key/value pairs that can be set on entities in the Connect database. There are two ways to do that: l l Using the Set Properties task. Ideally, the Set Properties task directly follows the Create Print Content task in a Workflow process.
PAGE 195

A Job Creation Preset can only take content sets as input. So, if you want to use a Job Creation Preset, the Retrieve Items task must retrieve content sets from the Connect database, not content items. This also means that if you want to use properties in conditions to retrieve the correct items, those properties must be set on the content set level. However, any properties that you want to be used for filtering, grouping or sorting must be set on the content items.
PAGE 196

The DataMapper The DataMapper is the tool to create a data mapping configuration. Data mapping configurations are used to extract data and transpose that data into a format that can be shared amongst different layouts and outputs created with the OL Connect Designer and Workflow. The original data, located in a file or database outside of OL Connect, is called a data source.
PAGE 197

3. Build the data mapping workflow. A data mapping workflow always starts with the Preprocessor step and ends with the Postprocessor step. You can add as many steps as you like and edit the Data Model of the extracted data as required. See "Data mapping workflow" on page 219 and "The Data Model" on page 261. What's next? Use the data mapping configuration in the Designer module to create templates for personalized customer communications. To learn more, see "The Designer" on page 426.
PAGE 198

Creating a new data mapping configuration A new data mapping configuration can be made with or without a wizard. When you open a data file with a DataMapper wizard, the wizard automatically detects a number of settings. You can adjust these settings. Next, the wizard automatically extracts as many data fields (or metadata, in case of a PDF/VT or AFP file) as it can, in one extraction step. Without a wizard you have to make the settings yourself, and configure the extraction workflow manually.
PAGE 199

l From the File menu 1. Click the File menu and select New. 2. Click the Data mapping Configuration drop-down and select Files and then the file type: l Comma Separated Values or Excel (CSV/XLSX/XLS), l Microsoft Access l PDF, PS, PCL or AFP l Text l XML. For a JSON file, select XML. 3. Click Next. 4. Click the Browse button and open the file you want to work with. 5. Click Finish.
PAGE 200

process) the conversion to PDF may influence the processing speed, depending on the available processing power. l l l Some advanced PCL to PDF options are available by calling LincPDF (PlanetPress Connect's PCL to PDF converter) command line module; see "Advanced PCL to PDF options" on page 212. Extracting data from a PDF that comes from a Windows printer queue (a PDF converted to PostScript, converted back to PDF by an Input task in Workflow) might not work.
PAGE 201

l From the Welcome screen 1. Open the PlanetPress Connect Welcome page by clicking the or select the Help menu and then Welcome. icon at the top right 2. Click New DataMapper Configuration. 3. From the Using a wizard pane, select the appropriate file type. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select the appropriate file type. The steps to take with the wizard depend on the file type.
PAGE 202

2. Click New DataMapper Configuration. 3. From the Using a wizard pane, select Generate counters. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select Generate counters. You can set the following parameters: 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.
PAGE 203

Saving a data mapping configuration A data mapping configuration file has the extension .OL-datamapper. The file contains the settings, the extraction workflow ('Steps'), the Data Model and the imported Data Samples (excluding database source files such as mySQL, oracle, etc). To save a data mapping configuration: l l In the "Menus" on page 297, click on File > Save, or click on Save As to save a copy of a data mapping configuration under a different name.
PAGE 204

4. Click the Browse button and open the file you want to work with. 5. Click Next. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select From CSV/XLSX/XLS File. 3. Click Next. 4. Click the Browse button and open the file you want to work with. 5. Click Next. Note Excel files saved in "Strict Open XML" format are not supported yet.
PAGE 205

l l l l Text Delimiter: Defines which character surrounds text fields in the file. Separators and comment delimiters within text are not interpreted as separator or delimiter; they are seen as text. 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.
PAGE 206

l From the Welcome screen 1. Open the PlanetPress Connect Welcome page by clicking the or select Help > Welcome on the menu. icon at the top right 2. Click New DataMapper Configuration. 3. From the Using a wizard pane, select Database. 4. Use the drop-down to select the database type. 5. Click Next. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select From databases. 3. Click Next. 4. Use the drop-down to select the database type. 5. Click Next.
PAGE 207

MySQL, SQL Server or Oracle l Server: Enter the server address for the database. l Port: Enter the port to communicate with the server. The default port is 3306. l l l l l Database name: Enter the exact name of the database from where the data should be extracted. User name: Enter a user name that has access to the server and specified database. The user only requires Readaccess to the database. Password: Enter the password that matches the user name above.
PAGE 208

l This ODBC source is MSSQL: Check this option if the ODBC source is MSSQL (SQL Server). The options below appear under MSSQL-ODBC advanced configuration: l l l Windows authentication: Select to use the Windows user name and password that are used by the Connect Service. SQL Server authentication: Select to use the User name and Password set below to connect to the SQL Server: l User name: Enter the SQL Server user name. l Password: Enter the password for the above user name.
PAGE 209

l Sort on: Select a field on which to sort the data, in ascending (A-Z) or descending (Z-A) order. Note that sorting is always textual. Even if the selected column has numbers, it will be sorted as a text. Using the wizard for PDF/VT or AFP files The pages in PDF/VT and AFP files can be grouped on several levels. Additional information can be attached to each level in the structure. The structure and additional information are stored in the file's metadata.
PAGE 210

3. Click Next. 4. Click the Browse button and open the PDF/VT or AFP file you want to work with. Click Next. After selecting the file, select the following options in the Metadata page: Metadata record levels: Use the drop-down to select what level in the metadata defines a record.Field List: This list displays all fields on the chosen level and higher levels in the PDF/VT or AFP metadata. The right column shows the field name. The left column displays the level on which it is located.
PAGE 211

If there is no root element in the JSON it will be added and each object without a named parent element is called an 'item'. Note that in addition to being valid, the JSON should follow naming rules for XML elements. For example, "adress_line_1:" is a valid key name in JSON, but it cannot be converted to a valid element name in XML because the colon is reserved for namespaces. For XML naming rules and best naming practices, see: XML elements on W3Schools. The wizard cannot create detail tables.
PAGE 212

record each time the element is different. (Check the option to include attributes in the list of content items that can trigger a boundary.) Note The DataMapper only extracts elements for which at least one value is defined in the file. Attribute values are not taken into account. Attribute values (prefixed with an @ sign in the Data Viewer) are not extracted automatically. Click Finish to close the dialog and open the data mapping configuration.
PAGE 213

1. Open the Connect Software Activation module. 2. Click on the "i" icon next to the PlanetPress Connect Server product. 3. When the License File Details window opens, expand the PlanetPress Connect Server, then expand the DataMapper node. If the Inputs.PCL entry is present in that node, you have a PCL Input license.
PAGE 214

Watch.SetVariable("lincPDFOptions","-z:1 -*e -*f -u3 -s pXOff:-0.155 -pYOff:0.15 -dAuthor:\"OL Connect\" -dTitle:\"" + Watch.ExpandString("%O") + "\""); This example sets the following options or parameters: Key Name Argument Value Type Description EdgeToEdgePrinting -z 0 or 1 Set the flag of “Allows edge-to-edge printing”(default: FALSE). Constant Alpha -n:num 0-1 Specify constant alpha value defined in PDF 1.4 (default: 0.5).
PAGE 215

l l l As a minimum, LincPDFC requires an input file, which is set here via the parameter –i to which we are assigning the current job file path and name “%F”, and an output file path and name set here using the –o parameter with a dynamic value of "% {workingDir}\Temp\%O.pdf". Select the "Run minimized" option to run the program in the background You may select to Log the program output for additional troubleshooting.
PAGE 216

Once you have the PDF as job file, you may pass it to the Execute Data Mapping plugin for further processing. LincPDFC Options To view the available options that can be set in LincPDF, run the executable (LincPDFC.exe) in a command prompt window. It will display a help message with available options.
PAGE 217

/*Open Windows Command Prompt Change directory cd C:\Program Files\Objectif Lune\OL Connect\LPDFConv\Bin C:\Program Files\Objectif Lune\OL Connect\LPDFConv\Bin\LincPDFC.exe LincPDF for Command-Line, Version 2.6.6.14 Copyright (c) 2001-2007 Lincoln & Co., a division of Biscom, Inc. Usage: LincPDF -iInput.PCL [-oOutput.
PAGE 218

-dTitle:$s : PDF Title -dSubject:$s : PDF Subject -dAuthor:$s : PDF Author -dKeywords:$s : PDF Keywords -dVersion:num : PDF Version (multiply by 10) Page Setup: -pWidth:num : Page Width (required only if Page Type is Custom) -pHeight:num : Page Height (required only if Page Type is Custom) -pXOff:num : Page X Offset (see also Measurement) -pYOff:num : Page Y Offset (see also Measurement) -pMeasure:num : Page Measurement (0-inch, 1-mm, 2-point) -pOrient:num : Page Orientation (0-Portrait, 1-Landscape) -pTyp
PAGE 219

-yCopyContents : Enable Copying Text and Graphics from Document -yUse128Bit : Use 128-bit Encryption -yAssembleDocument : Enable Assemble Document (128-bit encryption only) -yExtractText : Enable Text and Graphics Extraction (128-bit encryption only) -yLowResolutionPrint : Enable Lower-level Resolution Printing (128-bit encryption only) Tips ---------------------------------------------------. using quotation mark for complicated string, for example, -dKeywords:"key1, key2" .
PAGE 220

after the Data Mapping workflow has completed ("Postprocessor step" on page 259). When you create a new data mapping configuration, these steps are added automatically, but they don't actually do anything until you configure them. In between the Preprocessor and Postprocessor step, the workflow can contain as many steps as needed to extract the required data.
PAGE 221

Editing steps The properties of each step in the extraction workflow become visible in the Step properties pane when you select that step in the Steps pane. The name of each step is shown in the Steps pane. You can change it under Description in the Step properties pane. The other properties are different per step type; see "Steps" on page 249. Rearranging steps To rearrange steps, simply drag & drop them somewhere else on the colored line in the Steps pane.
PAGE 222

If any errors are encountered in one or more records, an error message will be displayed. Errors encountered while performing the extraction workflow on the current record will also be visible on the Messages tab. Note How many records are displayed in the Data Viewer (200, by default) is specified in the Record limit on the Settings pane. Data source settings After opening a data file you have to make a number of settings to make sure that the source data is interpreted and grouped the way you want.
PAGE 223

field separator. This ensures that, for example, the field “Smith; John” is not interpreted as two fields, even if the field delimiter is the semicolon. For an explanation of all the options, see: "CSV file Input Data settings" on page 316. Settings for an Excel File For an Excel file you have to specify which sheet to use. You can also set how many lines should be skipped, if the first row contains field names or not, and how the data should be sorted. See: "Excel file Input Data settings" on page 317.
PAGE 224

of, or unwanted characters at the beginning of your file, for example; you can also set a line width if you are still working with old line printer data; etc. It is important that pages be defined properly. This can be done either by using a set number of lines or using a string of text (for example, the character “P”), to detect on the page. Be aware that this is not a Boundary setting; it detects each new page, not each new record.
PAGE 225

page in a PDF file. It can also be something in the data that is either static (for example, the text "Page 1 of" in a PDF file) or changing (a customer ID, a user name, etc). To define a more complex trigger, you can write a script (see "Setting boundaries using JavaScript" on page 377). A new record cannot start in the middle of a data field, so if the trigger is something in the data, the boundary will be set on the nearest preceding natural delimiter.
PAGE 226

source. They don't determine how these data are formatted in the Data Model or in a template. In the Data Model, data are converted to the native data type. Dates, for example, are converted to a DateTime object. How they are displayed in the Data Model depends on the current operating system's regional settings.
PAGE 227

Defining custom properties and runtime parameters Defining properties You can define custom properties properties under Properties in the "Preprocessor step" on page 249 (see "Preprocessor step properties" on page 333). To add a property: 1. Select the Preprocessor step on the Steps pane. 2. On the Step properties pane, under Properties, click the Add button . See "Properties" on page 335 for an explanation of the settings for properties.
PAGE 228

1. Click the Add button. The Add Parameter dialog opens. 2. Give the runtime parameter a name. The name is needed to access the parameter in a script and to set its source in the automation tool. 3. Optionally, set a default value. Note that the default value is never actually used outside of the DataMapper. Its only purpose is to make it easier to design and test the data mapping configuration. The actual value of a runtime parameter comes from the automation tool, e.g.
PAGE 229

l l The data object has a properties array that lets you access custom properties of the data as a whole, i.e. the scope of the property is set to Entire data. (See: "data" on page 390.) These are read-only. To access a runtime parameter inside of any JavaScript code within the data mapping configuration, use automation.parameters.runtimeparametername. (See: "Objects" on page 383.) Runtime parameters are read-only. Tip Runtime parameters in a data mapping configuration are always of the type String.
PAGE 230

These properties may be used throughout the extraction workflow. For more information, see "Preprocessor step" on page 249. Adding an extraction In an extraction workflow, Extract steps are the pieces that take care of the actual data extractions. To add an Extract step: 1. In the Data Viewer pane, select the data that needs to be extracted. (See "Selecting data" on page 233.) 2. Choose one of two ways to extract the selected data.
PAGE 231

Special conditions The Extract step may need to be combined with another type of step to get the desired result. l l l Data can be extracted conditionally with a Condition step or Multiple Conditions step; see "Condition step" on page 254 or "Multiple Conditions step" on page 257. Normally the same extraction workflow is automatically applied to all records in the source data. It is however possible to skip records, entirely or partially, or to stop data mapping using an Action step.
PAGE 232

Adding fields to an existing Extract step For optimization purposes, it is better to add fields to an existing Extract step than to have a succession of extraction steps. To add fields to an existing Extract step: 1. In the Data Viewer pane, select the data that needs to be extracted. (See "Selecting data" on the next page.) 2. Select an Extract step on the Steps pane. 3. Right-click on the data and select Add Extract Field, or drag & drop the data on the Data Model.
PAGE 233

l Click the Validate All Records toolbar button. l Select Data > Validate Records in the menu. If any errors are encountered in one or more records, an error message will be displayed. Errors encountered while performing the extraction workflow on the current record will also be visible on the Messages tab. Note How many records are displayed in the Data Viewer (200, by default) is specified in the Record limit on the Settings pane.
PAGE 234

Note In a Text or PDF file, when you move the selection rectangle directly after extracting data, you can use it to select data for the next extraction. However, moving the selection rectangle that appears after clicking on a field in the Data Model actually changes which data is extracted into that field. CSV/XLS/XLSX file or database recordset Tabular data is displayed in the Data Viewer in a table where multiple fields appear for each line and row in the original data.
PAGE 235

Extracting transactional data Promotional data are data about customers, such as addresses, names and phone numbers. In Connect, each record in the extracted record set represents one recipient. The number of fields that contain promotional data is the same in each record. These data are stored on the root level of the extracted record.
PAGE 236

From a CSV file or a Database The transactional data (also called line items) appear in multiple rows. 1. Select a field in the column that contains the first line item information. 2. Right-click this data selection and select Add Repeat. This adds a Repeat step with a GoTo step inside it. The GoTo step moves the cursor down to the next line, until there are no more lines (see "Goto step" on page 253). 3. (Optional.
PAGE 237

The extraction step is placed inside the Repeat step, just before the GoTo step. From an XML file The transactional data appears in repeated elements.
PAGE 238

1. Right-click one of the repeating elements and select Add Repeat. This adds a Repeat step to the data mapping configuration. By default, the Repeat type of this step is set to For Each, so that each of the repeated elements is iterated over. You can see this on the Step properties pane, as long as the Repeat step is selected on the Steps pane. In the Collection field, you will find the corresponding node path.
PAGE 239

2. (Optional.) Add an empty detail table via the Data Model pane: right-click the Data Model and select Add a table. Give the detail table a name. 3. Select the Repeat step on the Steps pane. 4. Extract the data: inside a repeating element, select the data that you want to extract. Then right-click the selected nodes and select Add Extraction, or drag & drop them in the Data Model. When you drag & drop data on the name of a detail table in the Data Model pane, the data are added to that detail table.
PAGE 240

1. Select an element in the first line item. 2. Right-click on the selection and select Add Goto. The Goto step will move the cursor to the start of the first line item. 2. Add a Repeat step where the loop must stop. 1. In the line under the last line item, look for a text that can be used as a condition to stop the loop, for example "Subtotals", Total" or "Amount". 2. Select that text, right-click on it and select Add Repeat. The Repeat step loops over all lines until the selected text is found. 3.
PAGE 241

1. Select the start of the Repeat step on the Steps pane. 2. Look for something in the data that distinguishes lines with a line item from other lines (or the other way around). Often, a "." or "," appears in prices or totals at the same place in every line item, but not on other lines. 3. Select that data, right-click on it and select Add Conditional. Selecting data - especially something as small as a dot - can be difficult in a PDF file.
PAGE 242

4. (Optional.) Add an empty detail table to the Data Model: right-click the Data Model and select Add a table. Give the detail table a name.
PAGE 243

5. Extract the data (see "Adding an extraction" on page 230). When you drag & drop data on the name of a detail table in the Data Model pane, the data are added to that detail table. Dropping the data somewhere else on the Data Model pane, or using the contextual menu in the Data Viewer, creates a new detail table, with a default name that you can change later on (see "Renaming a detail table" on page 306).
PAGE 244

Note In a PDF or Text file, pieces of data often have a variable size: a product description, for example, may be short and fit on one line, or be long and cover two lines. To learn how to handle this, see "Extracting data of variable length" on the next page. 6. Extract the sum or totals. If the record contains sums or totals at the end of the line items list, the end of the Repeat step is a good place to add an Extract step for these data.
PAGE 245

Extracting data of variable length In PDF and Text files, transactional data isn't structured uniformly, as in a CSV, database or XML file. Data can be located anywhere on a page. Therefore, data are extracted from a certain region on the page. However, the data can be spread over multiple lines and multiple pages: l l Line items may continue on the next page, separated from the line items on the first page by a page break, a number of empty lines and a letterhead.
PAGE 246

Using a Condition step or Multiple Conditions step Using a Condition step ("Condition step" on page 254) or a Multiple Conditions step ("Multiple Conditions step" on page 257) one could determine how big the region is that contains the data that needs to be extracted. In each of the branches under the Condition or Multiple Conditions step, an Extract step could be added to extract the data from a particular region. The Extract steps could write their data to the same field.
PAGE 247

Page 247
PAGE 248

Using a script A script could also provide a solution when data needs to be extracted from a variable region. This requires using a Javascript-based field. 1. Add a field to an Extract step, preferably by extracting data from one of the possible regions; see "Extracting data" on page 229. To add a field without extracting data, see "JavaScript-based field" on page 267. 2. On the Step properties pane, under Field Definition, select the field and change its Mode to Javascript.
PAGE 249

Note that this script replicates exactly what can be done in a Condition step. In cases like this, it is recommended to use a Condition step. Only use a script when no steps are sufficient to give the expected result, or when the extraction can be better optimized in a script. Steps In the DataMapper, steps are part of an extraction workflow (see "Data mapping workflow" on page 219). They contain a specific instruction for the DataMapper, for example to extract data, create a loop, or apply a condition.
PAGE 250

also lets you define properties and runtime parameters that can be used throughout the data mapping workflow. For a complete overview of the settings for a Preprocessor step, see: "Preprocessor step properties" on page 333. Properties and runtime parameters A data mapping configuration's properties hold data that can be used throughout the data mapping workflow to compare against in conditions or to complement the existing data.
PAGE 251

Extract step The Extract step is essential in each and every data mapping configuration. It extracts data from the data source, based on their location (a row and column in CSV or tabular data, an XPath in XML, or a region of the page in PDF and Text) or on JavaScript code. The data is stored in the record set that is the result of the extraction workflow. Fields always belong to an Extract step, but they don't necessarily all contain extracted data.
PAGE 252

see: "Extracting data" on page 229. l Alternatively, right-click the Steps pane and select Add a Step > Add Extraction. Make the required settings on the Step properties pane. If an Extract step is added within a Repeat step, the extracted data are added to a detail table by default; see "Extracting transactional data" on page 235 and "Detail tables" on page 306.
PAGE 253

1. On the Steps pane, select the step after which to insert the Condition step. 2. Make sure that the cursor is located where the extraction loop must start. By default the cursor is located at the top of the page or record, but previous steps in the extraction workflow may have moved it down. If necessary, add a Goto step (see "Goto step" below). This step can be skipped when the data source is an XML file. 3.
PAGE 254

l l On the Steps pane, select the step after which to insert the Goto step. In the Data Viewer, select some data, right-click that data and choose Add Goto, to add a Goto step that moves the cursor to that data. Alternatively, right-click the Steps pane and select Add a Step > Add Goto. Make the required settings on the Step properties pane. Configuring a Goto step For information about how to configure the Goto step, see "Goto step properties" on page 363.
PAGE 255

Adding a Condition step To add a Condition step: l On the Steps pane, select the step after which to insert the Condition step; then, in the Data Viewer, select some data, right-click that data and choose Add Conditional. In the Step properties pane, you will see that the newly added Condition step checks if the selected position (the left operand) contains the selected value (the right operand). Both operands and the operator can be adjusted.
PAGE 256

(in the Step properties pane).Make a selection in the Data Viewer and click the Use selected text button in the Right Operand section. You will now be able to see whether or not the proper text is extracted by the current selection. Repeat this until you are satisfied that the proper data is being extracted.Click on the Use selection button in the Left Operand section to fill out the coordinates.The point of origin of each character is at the bottom left of each of them and extends up and to the right.
PAGE 257

Rules are by default combined with AND. To change the way rules are combined, right-click "AND" in the Rule Tree, on the Step properties pane, and select OR or XOR instead. (XOR means one or the other, but not both.) Renaming a rule To rename a rule, double-click its name in the Rule Tree and type a new name. Multiple Conditions step The Multiple Conditions step is useful to avoid the use of nested Condition steps: Condition steps inside other Condition steps.
PAGE 258

Adding a Multiple Conditions step To add a Multiple Conditions step, right-click the Steps pane and select Add a Step > Add Multiple Conditions. To add a case, click the Add case button to the right of the Condition field in the Step properties pane. Configuring a Multiple Conditions step For information about how to configure the Multiple Conditions step, see "Multiple Conditions step properties" on page 360.
PAGE 259

l l l l Execute JavaScript code. Set the value for a record property. Record properties are defined in the Preprocessor step; see "Preprocessor step" on page 249. Stop the processing of the current record and move on to the next one. Normally an extraction workflow is automatically executed on all records in the source data. By stopping the processing of the current record, you can filter out some records or skip records partially.
PAGE 260

l Select the Postprocessor step on the Steps pane. l On the Step properties pane, under Postprocessor, click the Add button l . Under Postprocessor definition, add the script. Postprocessor tasks must be written in JavaScript (see "Using scripts in the DataMapper" on page 375 and "DataMapper Scripts API" on page 372). Configuring the Postprocessor step For an explanation of the settings for post-processors, see "Postprocessor step properties" on page 367.
PAGE 261

mapping workflow. In order to test post-processors you must execute them manually by clicking the Apply button in the Post-processor step properties (see "Postprocessor step properties" on page 367). Note that in the DataMapper and Designer, only one data record is active at any given time. Therefore, the changes made by the post-processes are only visible on the current data record (i.e. the one currently displayed).
PAGE 262

About records A record is a block of information that may be merged with a template to generate a single document (invoice, email, web page...) for a single recipient. It is part of the record set that is generated by a data mapping configuration. In each record, data from the data source can be combined with data coming from other sources. Records can be duplicated by setting the number of copies in a script (see "record" on page 405). Duplicates are not shown in the Data Model.
PAGE 263

Note l l Imported Data Model fields always overwrite existing field properties when the field name is the same (although they will still be part of the same Extract step). Nonexistent fields are created automatically with the appropriate field settings. The import is case-insensitive. All imported data model fields are marked as required in the Data Model (indicated with an asterisk (*) next to their names).
PAGE 264

To change the order in which data are extracted, see "Renaming and reordering fields in an extraction step" on page 269. Moving fields To move a field, a group of fields or a detail table, you can simply drag and drop it to some other place in the Data Model. Alternatively, you can right-click the field, group or detail table and select one of the options in the Move menu, to move it up or down within the list or group. Fields cannot be moved into another table.
PAGE 265

In Workflow, when a data mapping configuration is used to extract data from a data source (see "Data mapping configurations" on page 197), the extracted data is stored in a record set in the OL Connect database. Adding fields and data via Workflow The Data Model is not extensible outside of the DataMapper. When it is used in Workflow - as part of a data mapping configuration - the contents of its fields can be updated but not its structure.
PAGE 266

l Select Metadata as the data source in the Create Preview PDF plugin. Note Many of these actions can also be performed using REST calls. Please refer to PlanetPress Connect Workflow documentation for more information about the plugins involved. Fields Extracted data are stored in fields in the Data Model (see "The Data Model" on page 261). Fields can be present on different levels: on the record level or in a detail table (see "Detail tables" on page 306).
PAGE 267

JavaScript-based field JavaScript-based fields are filled by a script: the script provides a value. Note that the last value attribution to a variable is the one used as the result of the expression. There is a number of ways to add a Javascript based field. Via the Steps pane 1. Make sure there is no data selection in the Data Viewer. 2. Right-click on an Extract step on the Steps pane and select Add a Step > Add Extract Field. (To add a new Extract step, select Add a Step > Add Extraction first.) 3.
PAGE 268

Property-based field A property-based field is filled with the value of a property (see "Properties and runtime parameters" on page 226). Custom properties can be added via the Preprocessor step; see "Preprocessor step" on page 249. A property-based field cannot be added directly. To fill a field with the value of a property, you have to change an existing field's Mode to Properties. 1. Select the field in the Data Model. 2. On the Step properties pane, under Field Definition, change its Mode to Properties.
PAGE 269

Renaming and reordering fields in an extraction step The names of fields, as well as the order of fields in an extraction step, can be changed via the properties of the Extract step that they belong to. 1. Select the Extract step that contains the fields that you want to rename. To do this you could click on one of those fields in the Data Model, or on the step in the Steps pane. 2. On the Step properties pane, under Field Definition, click the Order and rename fields button. 3.
PAGE 270

Setting the data type Fields store extracted data as a String by default. The data type of a field can be changed via the properties of the Extract step that the field belongs to. 1. Select the Extract step that contains the field. You can do this by clicking on the field in the Data Model, or on the step in the Steps pane that contains the field. 2. On the Step properties pane, under Field Definition, set the Type to the desired data type. See "Data types" on page 279 for a list of available types.
PAGE 271

Post function On the Step properties pane, under Field Definition, you can enter a script in the Post function field to be run after the extraction. (Click the Use JavaScript Editor button to open the "boundaries" on page 384 dialog if you need more space.) A Post function script operates directly on the extracted data. Its results replace the extracted data. For example, the Post function script replace("-", ""); replaces the first dash character that occurs inside the extracted string.
PAGE 272

2. In the Step properties pane, under Field Definition, click the Remove Extract Field button next to the Field List drop-down. Detail tables A detail table is a field in the Data Model that contains a record set instead of a single value. Detail tables contain transactional data. They are created when an Extract step is added within a Repeat step; see "Extracting transactional data" on page 235. In the most basic of transactional communications, a single detail table is sufficient.
PAGE 273

3. Click somewhere else on the Step Properties pane to update the Data Model. You will see the new name appear. Creating multiple detail tables Multiple detail tables are useful when more than one type of transactional data is present in the source data, for example purchases (items with a set price, quantity, item number) and services (with a price, frequency, contract end date, etc).
PAGE 274

and you will have to rename the detail table created in each Extract step to pull the detail tables apart (see "Renaming a detail table" on page 272).
PAGE 275

Nested detail tables Nested detail tables are used to extract transactional data that are relative to other data. They are created just like multiple detail tables, with two differences: l l For the tables to be actually nested, the Repeat step and its Extract step that extract the nested transactional data must be located within the Repeat step that extracts data to a detail table. In their name, the dot notation (record.services) must contain one extra level (record.services.charges).
PAGE 276

a number of "details" such as movie rentals or long distance calls.
PAGE 277

The services can be extracted to a detail table called record.services. The "charges" and "details" can be extracted to two nested detail tables.
PAGE 278

The nested tables can be called record.services.charges and record.services.details.
PAGE 279

Now one "charges" table and one "details" table are created for each row in the "services" table. Data types By default the data type of extracted data is a String, but each field in the Data Model can be set to contain another data type. To do this: 1. In the Data Model, select a field. 2. On the Step properties pane, under Field Definition choose a data type from the Type drop-down. Changing the type does not only set the data type inside the record.
PAGE 280

The following data types are available in PlanetPress Connect. l "Boolean" below l "String" on page 287 l "HTMLString" on page 286 l "Integer" on page 286 l "Float" on page 285 l "Currency" on the next page l "Date" on page 282 l "Object" on page 287 Note The Object data type is only available in the DataMapper module. It can be used for properties in the Preprocessor step, but not for fields in the Data Model.
PAGE 281

Note The value must be all in lowercase: true, false. Any variation in case (True, TRUE) will not work. Boolean expressions Boolean values can be set using an expression of which the result is true or false. This is done using operators and comparisons. Example: record.fields["isCanadian"] = (extract("Country") == "CA"); For more information on JavaScript comparison and logical operators, please see w3schools.com or developer.mozilla.org.
PAGE 282

Note While Currency values can be set to up to 4 significant digits, only 2 are displayed on screen. Building Currency values Currency values can be the result of direct attribution or mathematical operations just like Integer values (see "Integer" on page 286). Date 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 displayed using the system's regional settings, in reality they are stored unformatted.
PAGE 283

l In the user preferences ("DataMapper preferences" on page 829). l In the data source settings ("Data source settings" on page 222). l In the field properties: on the Step properties pane, under Data Format, specify the Date/Time Format. 4. For the letters and patterns that you can use in a date format, see "Defining a date/time format" below. Data format settings tell the DataMapper how to read and parse data from the data source.
PAGE 284

l l ap: AM/PM string. In addition, any constant character can be included in the mask, usually to indicate date/time separators (i.e. / - :) . If one of those characters happens to be one of the reserved characters listed above, it must be escaped using the \ symbol. Note The markers that can be used when extracting dates are different from those that are used to display dates in a template (see the Designer's "Date and time patterns" on page 1280).
PAGE 285

l In a Preprocessor property. To do this, go to the Steps pane and select the Preprocessor step. Then, on the Step properties pane, under Properties add a property, specify its Type as Date and put the JavaScript in the Default Value field. The use of the JavaScript Date() object is necessary when creating dates through a JavaScript expression. For more information, see w3schools - JavaScript Dates and w3schools - Date Object.
PAGE 286

Building Float values Float values can be the result of direct attribution or mathematical operations just like Integer values (see "Integer" below). HTMLString HTMLStrings contain textual data that includes HTML markup. They are essentially the same as String values except in cases where the HTML markup can be interpreted. Example: Assume that a field has the value He said WOW!.
PAGE 287

l l Direct attribution: Assign an integer value directly, such as 42, 99593463712 or data.extract("TotalOrdered");. Mathematical operations: Assign the result of any mathematical operation. For example: 22+51, 3*6, 10/5 or sourceRecord.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.
PAGE 288

l Extraction: l In the Data Model, select a field. On the Step properties pane, under Field Definition set the Type to String. The field value will be extracted and treated as a string. l l JavaScript Expression: Set the desired value to any string between quotes. Example: record.fields["countryOfOrigin"] = "Canada"; Building String values String values can be made up of more than just a series of characters between quotes.
PAGE 289

xsi:schemaLocation="http://www.objectiflune.com/connectschemas/Data ModelConfig http://www.objectiflune.com/connectschemas/DataModelConfig/1_0_0_ 3.xsd" xmlns:xsi="http://www.w3.
PAGE 290

Example: transactional details, in a simple invoice format PAGE 291
Example: nested tables (one table into another) PAGE 292
Keyboard shortcuts This topic gives an overview of keyboard shortcuts that can be used in the DataMapper. Keyboard shortcuts available in the Designer for menu items, script editors and the data model pane can also be used in the DataMapper; see "Keyboard shortcuts" on page 1019. Although some of the keyboard shortcuts are the same, this isn't a complete list of Windows keyboard shortcuts. Please refer to Windows documentation for a complete list of Windows keyboard shortcuts.
PAGE 293

Key combination Function displays the corresponding menu.) The menu can then be browsed using the Enter key, arrow up and arrow down buttons.
PAGE 294

Key combination Function Ctrl + Shift + S Save all Ctrl + Shift + W or Ctrl + Shift + F4 Close all Ctrl + F5 Revert Ctrl + F7 Next view Ctrl + Shift + F7 Previous view Ctrl + F8 Next perspective Ctrl + Shift + F8 Previous perspective Ctrl + F10 Save as Ctrl + F12 Send to Workflow / Package files F4 Ignore step/Reactivate step F6 Add an Extract step F7 Add a Goto step F8 Add a Condition step F9 Add a Repeat step Page 294
PAGE 295

Key combination Function F10 Add an Extract field F11 Add an Action step F12 Add a Multiple Conditions step Alt + F12 Add a Case step (under a Multiple Conditions step) Home Go to the first step in the workflow End Go to the last step in the workflow Alt + V Validate records Shift + F10 or Ctrl + Shift + F10 Open context menu Viewer pane The following key combinations activate a function in the Viewer.
PAGE 296

Key combination Function Ctrl + + Zoom in Ctrl + Shift + E Switch to Editor Ctrl + F6 Next editor (when there is more than one file open in the Workspace) Ctrl + Shift + F6 Previous editor (when there is more than one file open in the Workspace) Data Model pane Key combination Function PageUp Go to previous record PageDown Go to next record Alt + CR Property page Alt + PageDown Scroll down to the last field Alt + PageUp Scroll up to the first field Steps tab Key combination Function
PAGE 297

Edit Script and Expression windows The following key combinations have a special function in the Expression and in the Edit Script windows (expanded view). Key combination Function Ctrl + space Content assist (auto-complete) Ctrl + A Select all Ctrl + D Duplicate line Ctrl + I Indent (Tab) Ctrl + J Line break Ctrl + L Go to line; a prompt opens to enter a line number.
PAGE 298

File Menu l l l l l l l l l l New...: Opens the dialog to create a new data mapping configuration; see "Creating a new data mapping configuration" on page 198. 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.
PAGE 299

Edit Menu l Undo: Undoes the previous action. l Redo: Redoes the last action that was undone. l l l l Cut Step: Removes the currently selected step and places it in the clipboard. If the step is a Repeat or a Condition, all steps under it are also placed in the clipboard. If there is already a step in the clipboard, it will be overwritten. Copy Step: Places a copy of the currently selected step in the clipboard. The same details as the Cut step applies.
PAGE 300

l l l l l l Add Goto Step: Adds a Goto step that moves the selection pointer to the beginning of the data selection. For instance if an XML node is selected, the pointer moves to where that node is located. Add Condition Step: Adds a condition based on the current data selection. The "True" branch gets run when the text is found on the page. Other conditions are available in the step properties once it has been added.
PAGE 301

l l Reset Perspective: Resets all toolbars and panes to the initial configuration of the module. Preferences: Click to open the "Preferences" on page 825 dialog. Help Menu l l l Software Activation: Displays the Software Activation dialog. See "Activating a License" on page 57. Help Topics: Click to open this documentation. Contact Support: Click to open the Objectif Lune Contact Page in the default system Web browser. l About PlanetPress Connect Designer: Displays the software's About dialog.
PAGE 302

Filter To find a certain table, group or field in a large Data Model, start typing characters in the Filter box. This immediately narrows down the list of displayed items to all tables, groups and fields whose name contains the characters that were typed. Note that the filtering is case-insensitive. Data Model toolbar buttons : Import Data Model: Click to browse to a file that contains a Data Model. This may l be: l A Data Model file (*.OL-datamodel). l A JSON file (*.json; see the note below).
PAGE 303

l l l l : Synchronize Fields and Structure: Click to synchronize the Data Model fields and structure in the currently loaded template and data mapping configuration. If you click this button when working on the data mapping configuration, the Data Model gets updated to the one in the template. If you click it when working on the template, the Data Model gets updated to the one in the data mapping configuration. : Show the ExtraData field. Note that this field is not meant to be filled via an extraction.
PAGE 304

Note Rename, Delete and Set Type are only available for Data Model fields or detail tables that are not filled via an extraction. Fields and detail tables that are filled via an Extract step are to be changed (renamed, deleted etc.) via the properties of that Extract step; see: "Editing fields" on page 268 and "Renaming a detail table" on page 306. l l Rename: Click to rename the selected table, field or group. Enter the new name and click OK to rename.
PAGE 305

l l l l l l l l The column on the left displays the name of the field. The column on the right displays the current value of the extracted field based on the record shown in the Data Viewer, if an Extract step has an extraction for this field (see "Extracting data" on page 229). The icon to the left of the name indicates the data type of the field (see "Data types" on page 279). A field name with an asterisk to the right indicates that this field is required.
PAGE 306

l l l l Previous Record: Go to the previous record in the data sample. This button is disabled if the first record is shown. Current Record: Displays the current record or table entry. Type 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: Go to the next record in the data sample. This button is disabled if the last record is shown. Last Record: Go to the last record in the data sample.
PAGE 307

Note A detail table’s name should always begin with ‘record.’. 3. Click somewhere else on the Step Properties pane to update the Data Model. You will see the new name appear. Creating multiple detail tables Multiple detail tables are useful when more than one type of transactional data is present in the source data, for example purchases (items with a set price, quantity, item number) and services (with a price, frequency, contract end date, etc).
PAGE 308

To create more than one detail table, simply extract transactional data in different Repeat steps (see "Extracting transactional data" on page 235). The best way to do this is to add an empty detail table (right-click the Data Model, select Add a table and give the detail table a name) and drop the data on the name of that detail table.
PAGE 309

Nested detail tables Nested detail tables are used to extract transactional data that are relative to other data. They are created just like multiple detail tables, with two differences: l l For the tables to be actually nested, the Repeat step and its Extract step that extract the nested transactional data must be located within the Repeat step that extracts data to a detail table. In their name, the dot notation (record.services) must contain one extra level (record.services.charges).
PAGE 310

a number of "details" such as movie rentals or long distance calls.
PAGE 311

The services can be extracted to a detail table called record.services. The "charges" and "details" can be extracted to two nested detail tables.
PAGE 312

The nested tables can be called record.services.charges and record.services.details.
PAGE 313

Now one "charges" table and one "details" table are created for each row in the "services" table. The Data Viewer The Data Viewer is located in the middle on the upper half of the DataMapper screen. It displays the data source that is currently loaded in the DataMapper, specifically one record in that data. Where one record ends and the next starts is determined in the Data Source settings (see "Record boundaries" on page 224).
PAGE 314

l l l Hide/Show datamap : Click to show or hide the icons to the left of the Data Viewer which displays how the steps affect the line. Hide/Show extracted data : Click to show or hide the extraction selections indicating that data is extracted. This simplifies making data selections in the same areas and is useful to display the original data. Lock/Unlock extracted data : Click to lock existing extraction selections so they cannot be moved or resized.
PAGE 315

Messages pane The Messages pane is shared between the DataMapper and Designer modules and displays any warnings and errors from the data mapping configuration or template. At the top of the Message pane are control buttons: l Export Log: Click to open a Save As dialog where the log file (.log) can be saved on disk. l Clear Log Viewer: Click to remove all entries in the log viewer. l Filters: Displays the Log filter (see "Log filter" below).
PAGE 316

Settings pane Settings for the data source and a list of Data Samples and JavaScript files used in the current data mapping configuration, can be found on the Settings tab at the left. The available options depend on the type of data sample that is loaded. The Input Data settings (especially Delimiters) and Boundaries are essential to obtain the data and eventually, the output that you need. For more explanation, see "Data source settings" on page 222.
PAGE 317

l l l l l Lines to skip: Defines a number of lines in the CSV that will be skipped and not used as 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. Skip empty lines: Ignore any line that has no content.
PAGE 318

Each value represents a fraction of the average font size of text in a data selection, meaning "0.3" represents 30% of the height or width. l l l l l l Word spacing: Determines the spacing between words. As PDF text spacing is somehow done through positioning instead of actual text spaces, text position is what is used to find new words. This option determines what percentage of the average width of a single character needs to be empty to consider a new word has started. The default value is 0.
PAGE 319

l l l l l l l Connection String: Displays the connection string used to access the Data Source. 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. Table: Displays the tables and stored procedures available in the database. The selected table is the one the data is extracted from.
PAGE 320

l l l 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: Any line that is longer than the given maximum line length will be split at the maximum line length, as often as necessary. This option is used to cut (and wrap) long lines into logical blocks of data.
PAGE 321

XML File Input Data settings For an XML file you can either choose to use the root node, or select an element type, to create a new delimiter every time that element is encountered. Note The settings for XML files also apply when extracting data from a JSON file, because JSON files are automatically converted to XML. l l l Use root element: Selects the top-level element. No other boundaries can be set. If there is only one top-level element, there will only be one record.
PAGE 322

l Show all elements: When the delimiter is set to a specific element or XPath, checking this option allows to extract information from higher-level nodes, including those that follow the element or path. This might slow down the processing, so if you don't need any information from the higher-level nodes that follow that specific element, it is recommended to leave this option unchecked.
PAGE 323

l l 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; when generating output, this option is ignored. To disable the limit, use the value 0 (zero). Trigger: Defines the type of rule that controls when a boundary is set, creating a new record. l Record(s) per page: Defines a fixed number of lines in the file that go in each record.
PAGE 324

l On page: Defines a boundary on a static number of pages. l l Number of pages: Defines how many pages go in each record. On text: Defines a boundary on a specific text comparison. l l 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.
PAGE 325

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 after every four delimiters. On text: Defines a boundary on a specific text comparison.
PAGE 326

l l l Use selected text button: copies the text in the current selection as the one to compare to it. Match case: Makes the text comparison case sensitive. On script: Defines the boundaries using a custom JavaScript. For more information see "Setting boundaries using JavaScript" on page 377. XML file boundaries The delimiter for an XML file is a node. The Boundaries determine how many of those nodes go in one record.
PAGE 327

Data samples The Data Sample area displays a list of all the imported Data Samples that are available in the current data mapping configuration. As many Data Samples as necessary can be imported to properly test the configuration. Only one of the data samples - the active data sample - is shown in the Data Viewer. A number of buttons let you manage the Data Samples.
PAGE 328

Editor Data Format The Editor Data Format setting is only available for Excel files. l Date Display Format: This setting specifies how dates must be displayed in the Data Viewer. Note that extracting a Date value will only be successful if the expected date format matches the actual format of a date in the Data Viewer (see: "Data format settings" on page 225.) l l l Excel Default Format: Displays dates and times the way they would be displayed in Excel, using the specified locale.
PAGE 329

l Reload to it. : Reload the currently selected library and any changes that have been made Default Data Format The Default Data Format settings defined here apply to any new extraction in made in the current data mapping configuration. Any format already defined for an existing field remains untouched. It is also possible to set a default format for dates and currencies in the user preferences ("DataMapper preferences" on page 829).
PAGE 330

l l l l Tables: Lists all tables and stored queries in the database. Custom Query: Displays the query that retrieves information from a database. You may use variables and properties in the query, to make the selection dynamic. See "Using variables and properties in an SQL query" below. 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.
PAGE 331

Example = SELECT {automation.variables.FieldList} FROM {automation.jobInfo.JobInfo9} If the Workflow variable defined as FieldList contains the value "id,name" and Job Info 9 contains the value "MyTable", then this custom query, once parsed, yields the following SQL statement: SELECT id,name FROM MyTable which is then executed. Steps pane The Steps tab displays the data mapping workflow: the process that prepares and extracts data.
PAGE 332

You can also click on the Preprocessor step to select all the steps in the workflow to show a complete map of all the extracted data. Window controls The following controls appear at the top of the Steps pane: l Zoom In (CTRL +) l Zoom Out (CTRL -) : Click to zoom in by increments of 10% : 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. l Add a Step: Adds a step to the process.
PAGE 333

Step properties pane The Step Properties pane is used to adjust the properties of each Step in the process (see "Steps" on page 249). The pane is divided in a few subsections depending on the Step and the data type. It always contains a subsection to name and document the selected Step. Other subsections allow you to edit or delete fields that belong to the Step (see "Fields" on page 266) or change the expected data format (see "Data Format" on page 342), for example.
PAGE 334

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 will be displayed in the tooltip that appears when hovering over the step in the Steps pane. Fixed automation properties The Fixed automation properties subsection lists all the fixed runtime parameters available from PlanetPress Workflow. These properties are equivalent to data within the PlanetPress Workflow process in which the data mapping configuration is applied.
PAGE 335

access this property inside of any JavaScript code within the data mapping configuration, use automation.properties.ProcessName. l 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.
PAGE 336

l l l Each Record: These properties are evaluated and set at the beginning of each source record. Once they have been set, these properties can be modified via an Action step (see "Action step" on page 258), but they are always reset at the beginning of each source record. Type: The data type of the property. For more information see "Data types" on page 279. Default Value: The initial value of the property. This is a JavaScript expression. See "DataMapper Scripts API" on page 372.
PAGE 337

Extract step properties The Extract step takes information from the data source and places it in the record set that is the result of the extraction workflow. For more information see "Extract step" on page 251 and "Extracting data" on page 229. Description This subsection is collapsed by default in the interface, to give more screen space to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane.
PAGE 338

Tip To change the name of a field quickly, right-click it in the Data Model and select Rename. 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 this field in the record set. Mode: Determines the origin of the data. Fields always belong to an Extract step, but they don't necessarily contain extracted data. See "Fields" on page 266 for more information.
PAGE 339

l Properties: The value of the property selected below will be the value of the selected field. l l l Property: This drop-down lists all the currently defined properties (including system properties). Custom properties can be defined in the Preprocessor step; see "Preprocessor step" on page 249. For an explanation of the objects to which the properties belong, see "DataMapper Scripts API" on page 372.
PAGE 340

A Post function script operates directly on the extracted data, and its results replace the extracted data. For example, the Post function script replace("-", ""); would replace the first dash character that occurs inside the extracted string. l Use JavaScript Editor: Click to display the "boundaries" on page 384 dialog. l Trim: Select to trim empty characters at the beginning or the end of the field.
PAGE 341

the data format that the DataMapper expects matches the actual format of the data in the data source; see "Data Format" on the facing page. l Split: l l l Split lines: Separate a multi-line selection into individual fields . Join lines: Join the lines in the selection with the Concatenation string defined below. Concatenation string: The (HTML) string used to concatenate lines when they are joined.
PAGE 342

l XPath: The path to the XML field that is extracted. l Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Post Function: Enter a JavaScript expression to be run after the extraction. For example replace("-","") would replace a single dash character inside the extracted string. l l Use JavaScript Editor: Click to display the "boundaries" on page 384 dialog.
PAGE 343

l l Date Language: Set the date language for a date value (ex: If English is selected, the term May will be identified as the month of May). Treat empty as 0: A numerical empty value is treated as a 0 value. Order and rename fields dialog The Order and rename fields dialog displays the extracted fields in the currently selected Extract step. To open it, first select an Extract step on the Steps pane.
PAGE 344

Note The order of fields in an extraction step isn't necessarily the same as the order of those fields in the Data Model; see "Ordering and grouping fields in the Data Model" on page 263. Action step properties The Action step can run multiple specific actions one after the other in order; see "Action step" on page 258 for more information. The properties of an Action step become visible in the Step properties pane when the Action step is selected on the Steps pane.
PAGE 345

visible, but with its data model pane greyed out, when it is being skipped as a visual clue to determine to which records the "Stop Processing Record" action is being applied. If fields were already extracted prior to encountering the Action step, then those fields are stored as usual. If no fields were extracted prior to encountering the Action step, then no trace of the record is saved in the database at run time. l Stop data mapping: The extraction workflow stops processing the data.
PAGE 346

l l Trim: Select to trim empty characters at the beginning or the end of the field JavaScript : The result of the JavaScript Expression written below the drop-down will be the value of the extracted field. If the expression contains multiple lines, the last value attribution (variable = "value";) will be the value. See "DataMapper Scripts API" on page 372. l l l l Expression: The JavaScript expression to run.
PAGE 347

CSV and Database Files l Property: Displays a list of record properties set in the Preprocessor step (see "Preprocessor step" on page 249). l Type: Displays the type of the property. Read only field. l Based on: Determines the origin of the data. l Location: The contents of the data selection set below will be the value of the extracted field. The data selection settings are different depending on the data sample type.
PAGE 348

l Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Data Format: Data format settings tell the DataMapper how certain types of data are formatted in the data source. Make sure that this format matches the actual format of the data in the data source. l Negative Sign Before: Any value in a numeric field that has a "-" sign before or after it is interpreted as a negative value.
PAGE 349

Note If the selection contains multiple lines, only the first line is selected. l l Trim: Select to trim empty characters at the beginning or the end of the field JavaScript : The result of the JavaScript Expression written below the drop-down will be the value of the extracted field. If the expression contains multiple lines, the last value attribution (variable = "value";) will be the value. See "DataMapper Scripts API" on page 372. l l l l Expression: The JavaScript expression to run.
PAGE 350

l Thousand Separator: Set the thousand separator for a numerical value. l Currency Sign: Set the currency sign for a currency value. l Date Format: Set the date format for a date value. l l Date Language: Set the date language for a date value (ex: If English is selected, the term May will be identified as the month of May). Treat empty as 0: A numerical empty value is treated as a 0 value. Run JavaScript Running a JavaScript expression offers many possibilities.
PAGE 351

Description This subsection is collapsed by default in the interface, to give more screen space to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here will be displayed in the tooltip that appears 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.
PAGE 352

l l Use JavaScript Editor: Click to display the Edit Script dialog. Collection (only with For Each): The XPath that specifies the level and (optionally) elements to select on that level. To select elements you can either use static values, e.g. ./user[@lastname="Smith"] or JavaScript statements, for example: =./user [@lastname="{automation.jobInfo.JobInfo1}"]. In order to use JavaScript: l The XPath must start with = l The JavaScript statement must be enclosed in curly brackets: { ...
PAGE 353

Text and PDF Files Note The Repeat Step expects lines of text in a PDF file to be horizontal (regardless of the orientation of the page). Vertical text will cause an error. l Based On: l Position: The data in the specified position for the comparison. l l l l l l l l Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Height: The height of the selection box. Use Selection: Click to use the value of the current data selection for the extraction.
PAGE 354

l l l l l Data Property: The value of a data-level property set in the Preprocessor step (see "Preprocessor step" on page 249). 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 (see "Preprocessor step" on page 249).
PAGE 355

l l l l l l 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 Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression. l l Trim: Select to trim empty characters at the beginning or the end of the field. Field: The contents of a specific field in the Extracted Record.
PAGE 356

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.
PAGE 357

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.
PAGE 358

Description This subsection is collapsed by default in the interface, to give more screen space to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here will be displayed in the tooltip that appears when hovering over the step in the Steps pane.
PAGE 359

l Based On: l Position: The data in the specified position for the comparison. l l Right (Txt and PDF only): The end position for the data selection. l Height (Txt and PDF only): The height of the selection box. l l l l l l 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. Trim: Select to trim empty characters at the beginning or the end of the field.
PAGE 360

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 (see "Preprocessor step" on page 249). Extractor Property: The value of an internal extractor variable: l l l Counter: The value of the current counter iteration in a Repeat step.
PAGE 361

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 will be displayed in the tooltip that appears when hovering over the step in the Steps pane. Condition Left operand, Right operand The Left and right operand can be Based on: l Position: The data in the specified position for the comparison. l l Right (Txt and PDF only): The end position for the data selection.
PAGE 362

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. See also: "DataMapper Scripts API" on page 372. Use JavaScript Editor: Click to display the Edit Script dialog (see "Using scripts in the DataMapper" on page 375). 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 363

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.
PAGE 364

Text file l Target Type: Defines the type of jump. l Line: Jumps a certain number of lines or to a specific line. l l l l Current Position: The Goto begins at the current cursor position. l Top of record: The Goto begins at line 1 of the source record. Move by: Enter the number of lines or pages to jump. Page: Jumps between pages or to a specific page.
PAGE 365

l Left: The starting column, inclusively. l Right: The end column, inclusively. l l l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Expression: Enter the text or Regex expression to look for on the page. Use selection: Click while a selection is made in the Data Viewer to copy the contents of the first line of the selection into the Expression box.
PAGE 366

options appear below to specify in which area of each line the Gotostep checks in: l Left: The starting column, inclusively. l Right: The end column, inclusively. l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Next occurrence of: Jumps to the next occurrence of specific text or a text pattern, either anywhere on the line or in specific columns.
PAGE 367

XML File l Destination (XML files): Defines what type of jump to make: l l l l l Sibling element: Jumps the number of siblings (nodes at the same level) defined in the Move byoption. Sibling element with same name: Jumps the number of same name siblings (nodes at the same level of which the node is the same name) defined in the Move byoption. Element, from top of record: Jumps to the specified node. The XPATH in the Absolute XPATHoption starts from the root node defined by /.
PAGE 368

Postprocessor The Postprocessor subsection defines what postprocessors run on the Data Sample at the end of the data mapping workflow. Each Postprocessor runs in turn, using the result of the previous one as an input. l Name: The name to identify the Postprocessor. l Type: The type of Postprocessor. Currently there is a single type available. l JavaScript: Runs a JavaScript Expression to modify the Data Sample. See "DataMapper Scripts API" on page 372.
PAGE 369

Toolbar In the DataMapper module, the following buttons are available in the top toolbar. File manipulation 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. l l Save: Saves the current data mapping configuration. If the configuration has never been saved, the Save As... dialog is displayed.
PAGE 370

l l l l l l l l Add Extract Field: Adds the data selection to the selected Extract step, if an extract step is currently selected. If multiple lines, nodes or fields are selected, multiple extract fields are added simultaneously. Add Multiple Conditions: Adds a condition that splits into multiple case conditions. Add Action Step: Adds a step to create a custom JavaScript snippet. See "DataMapper Scripts API" on page 372 for more details.
PAGE 371

If you are new to PlanetPress Connect and you don't know where to start, see "Welcome to PlanetPress Connect 2020.2" on page 15. The Welcome Screen can be reopened in two ways: l The Welcome Screen button in the "Toolbars" on page 1062. l From the Menus in Help, Welcome Screen. To go back from the Welcome Screen to the template or data mapping configuration that you were working on: l Close the Welcome Screen by clicking the cross next to the text 'Welcome' at the top.
PAGE 372

l Create/Open: l l l l l Open File: Lets you open an existing template or data mapping configuration. New template: Lets you choose a Context to create a new template without a Wizard. Template Wizards: Displays a list of available Template Wizards, producing premade templates with existing demo content; see "Creating a template" on page 428. Project Wizards: Displays a list of available Project Wizards, producing a complete Connect project; see "Project Wizards" on page 981.
PAGE 373

Name Description Available in scripts of type "db" on page 403 An object that allows to connect to a database. Boundaries, all steps except Goto "logger" on page 405 An object that allows to log error, warning or informational messages. Boundaries, all steps except Goto "record" on page 405 The current record in the main data set. Extract, Condition, Repeat and Multiple Conditions steps "region" on page 406 An object that defines a subsection of the input data.
PAGE 374

Functions These functions are available in Boundaries and Steps scripts. Name Description "Functions" on page 415 Copies a file to the target file path, replacing it if it already exists. "createGUID()" on page 415 Returns a unique 36-character string consisting of 32 alphanumeric, lower case characters and four hyphens (format: 84-4-4-12). Example: 123e4567-e89b-12d3-a456-426655440000. "createHTTPRequest ()" on page 415 Creates a new HTTP Request Object.
PAGE 375

Name Description "newIntArray()" on page 420 Returns an integer array. "newLongArray()" on page 421 Returns a long array. "newStringArray()" on page 421 Returns a string array. "openBinaryReader ()" on page 421 Opens a file as a binary file for reading purposes. "openBinaryWriter()" on page 421 Opens a file as a binary file for writing purposes. "openTextReader()" on page 422 Opens a file as a text file for reading purposes.
PAGE 376

l l l l Enter a script in a JavaScript-based field (see "JavaScript-based field" on page 267). Note that the last value attribution to a variable is the one used as the result of the expression. 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. Let an Action step run a JavaScript, for example to add a value to a custom property defined in the Preprocessor step.
PAGE 377

DataMapper API Certain features that can be used in a DataMapper script do not exist in the native JavaScript library. These are additional JavaScript features, designed for use in Connect only. All features designed for use in the DataMapper are listed in the DataMapper API (see "DataMapper Scripts API" on page 372).
PAGE 378

(that is, the count of delimiters that have been encountered). Each time the count is a multiple of 3, it could set a new record boundary. This is basically what happens when setting the trigger to On Page and specifying 3 as the Number of Pages. Note Remember that a boundary script is being called on each new delimiter encountered by the DataMapper parsing algorithm.
PAGE 379

This way the script can access values that were evaluated in previous pages or rows, across delimiters, so you can easily set record boundaries that span over multiple delimiters. For more information on the syntax, please refer to "DataMapper Scripts API" on page 372. Examples Basic example using a CSV file Imagine you are a classic rock fan and you want to extract the data from a CSV listing of all the albums in your collection.
PAGE 380

Essentially, we need to combine both these conditions and set the record boundary when EITHER the year OR the artist changes. Here's what the script would look like: /* Read the values of both columns we want to check */ var zeBand = boundaries.get(region.createRegion("Artist")); var zeYear = boundaries.get(region.createRegion("Released")); /* Check that at least one of our variables holding previous values has been initialized already, before attempting to compare the values */ if (boundaries.
PAGE 381

gets fired. When called, setVariables() creates the specified variable if it doesn't already exist and then sets the value to the second parameter passed to the function. You can try it yourself. Paste the data into the text editor of your choice and save the file to Albums.csv. Then create a new DataMapper configuration and load this CSV as your data file. In the Data Input Settings, make sure you specify the first row contains field names and set the Trigger to On script.
PAGE 382

[0]!=boundaries.getVariable("lastYear")) { boundaries.set(); } } boundaries.setVariable("lastBand",zeBand[0]); boundaries.setVariable("lastYear",zeYear[0]); This script uses the exact same code as used for CSV files, with the exception of parameters expected by the createRegion() method. The get method adapts to the context (the data source file) and therefore expects different parameters to be passed in order to achieve the same thing.
PAGE 383

Objects automation Returns a ScriptableAutomation object encapsulating the properties of the PlanetPress Workflow process that triggered the current operation. This automation object is available in all script types and with all file types. Note The automation object available in Designer scripts is not of the same type. It has different properties. Properties The following table lists the properties of the automation object. All properties are read-only.
PAGE 384

Property Description contain the same list of elements, but the variables property is kept for backward compatibility and may eventually be removed. Examples To access JobInfo 1 to 9 defined in Workflow (see Job Info variables): automation.jobInfo.JobInfo1; To access ProcessName, OriginalFilename or TaskIndex from Workflow: automation.properties.OriginalFilename; To access Workflow variables (see "Properties and runtime parameters" on page 226): automation.parameters.
PAGE 385

Methods The following table describes the functions of the boundaries object. They are available with all file types. Method Description Script type "find()" below Finds the first occurrence of a string starting from the current position. Boundaries Preprocessor, Extract, Condition, Repeat, Action, and Postprocessor steps "get()" on page 387 Retrieves an array of strings. Boundaries "getVariable ()" on page 387 Retrieves a value of a variable stored in the boundaries object.
PAGE 386

Note In PlanetPress Connect 1.8 and previous versions, the DataMapper's boundaries.find() function returned the region searched within PDF files, whereas for text files it returned the exact region where the text was found. In 2018.1 this was changed so that boundaries.find() on PDFs would return the exact region where the text was found, the same as for text files. However, it was subsequently found that this could cause issues with previously created templates using the function on PDF files.
PAGE 387

boundaries.set(1); } get() The get() method reads the contents of a region object and converts it into an array of strings (because any region may contain several lines). How the region is defined, depends on the type of source data; see "region" on page 406 and "createRegion()" on page 407. get(in_Region) in_Region A region object. What type of object this is depends on the type of source data, however in any case the region object can be created with a call to region.
PAGE 388

set() Sets a new DataMapper record boundary. set(delimiters) delimiters Sets a new record boundary. The delimiters parameter is an offset from the current delimiter, expressed in an integer that represents a number of delimiters. If this parameter is not specified, then a value of 0 is assumed. A value of 0 indicates the record boundary occurs on the current delimiter. A negative value of -n indicates that the record boundary occurred -n delimiters before the current delimiter.
PAGE 389

match occurs on an odd page. Recall that for PDF files, the natural delimiter is a PDF page. The JavaScript code would look something like the following: var myRegion = region.createRegion(150,220,200,240); if(boundaries.find("TOTAL", myRegion).found) { /* a match was found. Check if we are on an odd or even page and set the Boundary accordingly */ if((boundaries.
PAGE 390

Example This script examines a specific region and stores its contents in a variable in the boundaries. var addressRegion = region.createRegion(10, 30, 100, 50); var addressLines = boundaries.get(addressRegion); boundaries.setVariable("previousLines",addressLines); data Returns a data object encapsulating properties and methods pertaining to the original data stream. Properties The following table lists the properties of the data object.
PAGE 391

Method Description Script type ()" on page 398 field. and Action steps "fieldExists ()" on page 398 Method that returns true if the specified metadata field, column or node exists. Boundaries "find()" on page 399 Finds the first occurrence of a string starting from the current position. Boundaries Finds the first match for a regular expression pattern starting from the current position.
PAGE 392

Number that represents the distance, measured in characters, from the left edge of the page to the right edge of the rectangular region. verticalOffset Number that represents the current vertical position, measured in lines. regionHeight Number that represents the total height of the region, measured in lines. Setting the regionHeight to 0 instructs the DataMapper to extract all lines starting from the given position until the end of the record.
PAGE 393

Example 2: The script command data.extract(1,22,9,6,"
"); means that the left position of the extracted information is located at 1, the right position at 22, the offset position is 9 (since the first line number is 10) and the regionHeight is 6 (6 lines are selected). Finally, the "
" string is used for concatenation.
PAGE 394

extract(xPath) Extracts the text value of the specified node in an XML file. xPath String that can be relative to the current location or absolute from the start of the record. Example The script command data.extract('./CUSTOMER/FirstName'); means that the extraction is made on the FirstName node under Customer.
PAGE 395

extract(columnName, rowOffset) Extracts the text value from the specified column and row. columnName String that represents the column name. rowOffset Number that represents the row index (zero-based), relative to the current position. To extract the current row, specify 0 as the rowOffset. Use moveTo() to move the pointer in the source data file (see "moveTo()" on page 411). Example The script command data.extract('ID',0); means that the extraction is made on the ID column in the first row.
PAGE 396

extract(left, right, verticalOffset, lineHeight, separator) Extracts the text value from a rectangular region in a PDF file. All coordinates are expressed in millimeters. left Double that represents the distance from the left edge of the page to the left edge of the rectangular region. right Double that represents the distance from the left edge of the page to the right edge of the rectangular region. verticalOffset Double that represents the distance from the current vertical position.
PAGE 397

lineHeight Double that represents the total height of the region. separator String inserted between all lines returned from the region. If you don't want anything to be inserted between the lines, specify an empty string (""). Tip "
" is a very handy string to use as a separator. When the extracted data is inserted in a Designer template, it will be interpreted as a line break, because
is a line break in HTML and Designer templates are actually HTML files. Example The script command data.
PAGE 398

extractMeta() Method that extracts the value of a metadata field on a certain level in a PDF/VT. This method always return a String. extractMeta(levelName String, propertyName String) levelName String, specifying the PDF/VT's level. Case sensitive. propertyName String, specifying the metadata field. fieldExists() Method of the data object that returns true if a certain metadata field, column or node exists. (See "data" on page 390.
PAGE 399

fieldExists(levelName, propertyName) This method returns true if the given metadata field exists at the given level in a PDF file. levelName String that specifies the metadata field. propertyName String that specifies the level. fieldExists(fieldName) This method returns true if the specified column exists in the current record in a CSV file. fieldName String that represents a field name (column) in a CSV file.
PAGE 400

Partial matches are not allowed. The entire string must be found between the two constraint parameters. The data.find() function only works on the current page. If the record contains several pages, you must create a loop that will perform a jump from one page to another to do a find() on each page. Note Calling this method does not move the current position to the location where the string was found.
PAGE 401

Left=26,76, Top=149.77, Right=40,700001, Bottom=154.840302 These values represent the size of the rectangle that encloses the string in full, in millimeters relative to the upper left corner of the current page. findRegExp() Finds the first occurrence of a string that matches the given regular expression pattern, starting from the current position.
PAGE 402

matching can be enabled by specifying the UNICODE_CASE flag (u) in conjunction with this flag. s: Enables dotall mode. In dotall mode, the expression . matches any character, including a line terminator. By default this expression does not match line terminators. L: Enables literal parsing of the pattern. When this flag is specified, then the input string that specifies the pattern is treated as a sequence of literal characters.
PAGE 403

Examples data.findRegExp(/\d{3}-[A-Z]{3}/,"gi",50,100); or data.findRegExp("\\d{3}-[A-Z]{3}","gi",50,100);}} Both expressions would match the following strings: 001-ABC, 678-xYz. Note how in the second version, where the regular expression is specified as a string, some characters have to be escaped with an additional backslash, which is standard in JavaScript. db Object that allows to connect to a database. Methods The following table describes the methods of the db object.
PAGE 404

java.lang.String-java.lang.String-java.lang.String-. In the returned Connection object normally any public method should be available. The returned Connection object is described here: https://docs.oracle.com/javase/8/docs/api/java/sql/Connection.html. Note Make sure to close any Connection object created by connect() and any other closable resources created from the Connection instance (ResultSet, etc.). url String that represents a database url of the form jdbc:subprotocol:subname, e.g.
PAGE 405

else 'nothing'; values.close(); statement.close(); con.close(); logger Global object that allows logging messages such as error, warning or informational messages. Methods The following table describes the methods of the logger object. Method Parameters Description error() message: String Logs an error message info() message: String Logs an informational message warn() message: String Logs a warning message record The current record in the main data set.
PAGE 406

Property Description tables The details table that belong to this record. You can access a specific table using a numeric index or the table name. Example See this How-to for an example of how the current record index, and/or the total number of records in the record set, can be displayed in a document: How to get the record index and count. region The region object defines a sub-section of the input data. Its properties vary according to the type of data.
PAGE 407

Property/method Description Return Type (right), y2 (bottom), expressed in characters for a text file or in millimeters for a PDF file. For a CSV file, it is the name of the column that defines the region. "createRegion()" below Creates a region by setting the physical coordinates of the region object. A region that has the specified coordinates. createRegion() This method sets the physical coordinates of the region object.
PAGE 408

Example The following script attempts to match ((n,m)) or ((n)) against any of the strings in the specified region and if it does, a document boundary is set. var myRegion = region.createRegion(170,25,210,35); var regionStrings=boundaries.get(myRegion); if (regionStrings) { for (var i=0;i
PAGE 409

l l For a PDF file, the range() method contains the physical coordinates of the region: x1 (left), y1 (top), x2 (right), y2 (bottom), expressed in millimeters. For a CSV file, the range contains the name of the column that defines the region. sourceRecord Returns a sourceRecord object containing custom properties specific to the current source record being processed. These are the custom properties defined in the Preprocessor step that have their Scope set to "Each record".
PAGE 410

Method Description File type millimeters(e.g. PDF data). currentLoopCounter An integer value representing the current iteration of the containing loop. When loops are nested, you have access to the iteration for the current loop but not to any of the parent loops. Note: This variable is a counter so it starts at 1 as opposed to an index which usually starts at 0.
PAGE 411

the data */ curPage++; } else if(curLine.startsWith("LOAD FACTOR")) { /* Extracts data to the curLine variable until the string "LOAD FACTOR" is encountered */ break; } else { lineArray.push(curLine); /* Adds the current line value (extraction) to the array */ } currentPage Property of the steps object (see "steps" on page 409) containing an integer value that represents the page where the pointer is located, inside the current record.
PAGE 412

l 2: next line with content verticalPosition Number. What it represents depends on the value specified for scope. With the scope set to 0 or steps.MOVELINES, verticalPosition represents the index of the line to move to from the top of the record. With the scope set to 1 or steps.MOVEDELIMITERS, verticalPosition represents the index of the delimiter (as defined in the Input Data settings) to move to from the top of the record. With the scope set to 2, verticalPosition is not used.
PAGE 413

With the scope set to 0 or steps.MOVEMEASURE, verticalOffset represents the number of millimeters to move the current position, relative to the top of the record (NOT the top of the current page). With the scope set to 1 or steps.MOVEPAGES, verticalOffsetrepresents the index of the target page, relative to the top of the record. moveTo(xPath) Moves the current position in a XML file to the first instance of the given node, relative to the top of the record. xPath String that defines a node in the XML file.
PAGE 414

Text scope Number that may be set to: l l l 0 or steps.MOVELINES: the current position is set to the next line. 1 or steps.MOVEDELIMITERS: the current position is set to the next delimiter (as defined in the Input Data settings). 2 (next line with content): the current position is set to the next line that contains any text. Example The following line of code moves the current position to the next line that contains any text. steps.moveToNext(2); XML scope Number that may be set to: l l 0 or steps.
PAGE 415

Functions copyFile() Function that copies a file to the target file path, replacing it if it already exists. copyFile(source, target) source String that specifies the source file path and name. target String that specifies the target file path and name. Example This script copies the file test.txt from c:\Content into the c:\out folder. copyFile("c:\Content\test.txt","c:\out\") createGUID() This function returns a unique 36-character string consisting of 32 alphanumeric, lower case characters and four hyphe
PAGE 416

The returned ScriptableHTTPRequest has a selection of the properties and methods of the standard JavaScript XMLHTTPRequest object (see https://developer.mozilla.org/enUS/docs/Web/API/XMLHttpRequest). Supported properties and methods are listed below. Note It is not possible to use the async mode, which can be set via the open() function of the ScriptableHTTPRequest (see https://developer.mozilla.org/enUS/docs/Web/API/XMLHttpRequest/open) in a data mapping configuration.
PAGE 417

l send() l send(String requestBody) Sends an HTTP request and returns the HTTP status code. Blocked call. getResponseHeader(String header) Gets the ResponseHeader by name. getResponseHeaders() Returns the full response headers of the last HTTP request. getRequestBody() Gets the HTTP request body (for POST and PUT). setRequestHeader(String requestHeader, String value) Adds an additional HTTP request header. getResponseBody() Returns the full response body of the last HTTP request.
PAGE 418

authentication abort() Aborts the request. createTmpFile() Function that creates a file with a unique name in the temporary work folder and returns a file object. This file stores data temporarily in memory or in a buffer. It is used to prevent multiple input/output access to a physical file when writing. In the end, the contents are transferred to a physical file for which only a single input/output access will occur.
PAGE 419

reader.close(); } deleteFile(data.filename); tmpFile.move(data.filename); deleteFile() Function that is used to delete a file. deleteFile(filename) filename String that specifies the path and file name of the file to be deleted. Examples 1. Deleting a file in a local folder: deleteFile("c:\Content\test.txt"); 2. Deleting the sample data file used in the DataMapper: deleteFile(data.filename); execute() Function that calls an external program and waits for it to end.
PAGE 420

newCharArray() Function that returns a new Char array. newCharArray(size) Returns a new Char array of the specified number of elements. size Integer that represents the number of elements in the new array. newDoubleArray() Function that returns a new double array. newDoubleArray(size) Returns a new Double array of the specified number of elements. size Integer that represents the number of elements in the new array. newFloatArray() Function that returns a new float array.
PAGE 421

Integer that represents the number of elements in the new array. newLongArray() Function that returns a new long array. newLongArray(size) Returns a new Long array of the specified number of elements. size Integer that represents the number of elements in the new array. newStringArray() Function that returns a new string array. newStringArray(size) Returns a new String array of the specified number of elements. size Integer that represents the number of elements in the new array.
PAGE 422

String that represents the name of the file to open. append Boolean parameter that specifies whether the file pointer should initially be positioned at the end of the existing file (append mode) or at the beginning of the file (overwrite mode). openTextReader() Function that opens a file as a text file for reading purposes. The function returns a "TextReader" on the next page object. Please note that the temporary file must be closed at the end.
PAGE 423

TextReader The TextReader object, returned by the openTextReader() function, allows to open, parse, read and close a text file. (See: "openTextReader()" on the previous page.) Methods The following table describes the methods of the TextReader object. Method Description close() Closes the stream and releases resources. open(inStream, inEncoding) Creates a reader from an input stream.
PAGE 424

Method Description l offset: the number of characters to skip openTextWriter() This function opens a file as a text file for writing purposes. The function returns a "TextWriter" on the next page object. This must be closed at the end. openTextWriter(filename, encoding, append) filename String that represents the name of the file to open. encoding String specifying the encoding to use (UTF-8, ISO-8859-1, etc.)..
PAGE 425

TextWriter The TextWriter object, returned by the openTextWriter() function, allows to open a text file, write to it and close it. Methods The following table describes the methods of the TextWriter object. Method Description close() Close the stream. newLine() Creates a new line in the file. open(filename) Creates a new writer on a file to write at the beginning of the file. Parameters: l open(inFilename, inEncoding, append) filename: the path of the file to open Creates a new writer on a file.
PAGE 426

The Designer The Designer is a WYSIWYG (what you see is what you get) editor that lets you create templates for various output channels: Print, Email and Web. A template may contain designs for multiple output channels: a letter intended for print and an e-mail variant of the same message, for example. Content, like the body of the message or letter, can be shared across these contexts. Templates are personalized using scripts and variable data extracted via the DataMapper.
PAGE 427

page 428. 2. Fill the template Add text, images and other elements to the template and style them. See "Content elements" on page 612 and "Styling and formatting" on page 726. 3. Personalize the content Personalize the content using variable data. See "Personalizing content" on page 770. 4. Generate output Adjust the settings, test the template and generate output: letters, emails, and/or web pages. See "Generating output" on page 1440.
PAGE 428

l "Print" on page 453. This topic helps you design and fill sections in the Print context. l "Email" on page 495. This topics helps you design an email template. l "Web" on page 522. This topic helps you design a web page. "Sections" on page 449. Sections in one context are designed for the same output channel. "Content elements" on page 612. Elements make up the biggest part of the content of each design. "Snippets" on page 722.
PAGE 429

There are Wizards for the three types of output channels, or contexts as they are called in the Designer: Print, Email and Web. See: l "Creating an Email template with a Wizard" on page 500 l "Creating a Print template with a Wizard" on page 456 l "Creating a Web template with a Wizard" on page 523 Tip The quickest way to create a Print template based on a PDF file is to right-click the PDF file in the Windows Explorer and select Enhance with Connect.
PAGE 430

Warning A template created in an older version of the software can be opened in a newer version. However, opening and saving it in a newer version of the software will convert the template to the newest file format. The converted template can't be opened in older versions of the software. Opening a package file Templates can also be stored in a package file (see "Creating package files" on page 432). To open a package file, switch the file type to Package files (*.OL-package) in the Open File dialog.
PAGE 431

Saving older templates Saving a template in a newer version of the software will convert the template to the newest file format. This makes it unreadable to older versions of the software. The warning message that is displayed in this case can be disabled. To re-enable this message (and all other warning dialogs), go to Window > Preferences > General, and click the Reset All Warning Dialogs button at the bottom.
PAGE 432

Backup files have the same name as the original template with two underscores and a progressive number (without leading zeros) at the end: originalname__1.OL-template, originalname__2.OL-template, etc. Note The Auto Save function does not cause backup files to be created. File properties On the menu, select File > Properties to view and complement the file properties. See "File Properties dialog" on page 943. The file properties can also be used in scripts; see "template" on page 1409.
PAGE 433

selection of printing options, such as binding, OMR markings and the like. See "Print Presets" on page 1447 for more details. Package files can be imported into Workflow, sent to the Connect Server, or opened by other Connect users. To open the Package dialog, select File > Package.... For an explanation of the options in the Package dialog, see "Package dialog" on page 967.
PAGE 434

Sending files to Connect Server When OL Connect plugins in a Workflow process need templates and other configuration files, Workflow sends the necessary resources to the Connect Server. The Send files to Connect Server dialog provides a way to send templates, data mapping configurations and print presets to the Connect Server directly.
PAGE 435

Creating a Web template with a Wizard With the Designer you can design Web templates and output them through Workflow or as an attachment to an email when generating Email output. Capture On The Go templates are a special kind of Web templates; see "Capture OnTheGo template wizards" on page 560. A Web Template Wizard helps you create a Web page that looks good on virtually any browser, device and screen size.
PAGE 436

l Jumbotron l Thank You If you don't know what template to choose, see "Web Template Wizards" on page 438 further down in this topic, where the characteristics of each kind of template are described. 3. Click Next and make adjustments to the settings. The wizard remembers the settings that were last used for a Foundation Web template. l Section: l l l Description: Enter the description of the page. This is the contents of a HTML tag.
PAGE 437

l l l l A Web context with one web page template (also called a section) in it. The web page contains a Header, a Section and a Footer element with dummy text, and depending on the type of web page, a navigation bar, button and/or Form elements. Resources related to the Foundation framework (see "Web Template Wizards" on the facing page): style sheets and JavaScript files. The style sheets can be found in the Stylesheets folder on the Resources pane.
PAGE 438

Web Template Wizards Foundation With the exception of the most basic one, all Web Template Wizards in the Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first approach, so that websites built upon Foundation look good and function well on multiple devices including desktop and laptop computers, tablets, and mobile phones.
PAGE 439

A Capture OnTheGo Form is actually just a Web Form, that you could add without a wizard, but the COTG Template Wizards include the appropriate JavaScript files for the Capture OnTheGo app, and styles to create user-friendly, responsive forms. They are built upon the Foundation framework. Foundation With the exception of the most basic one, all Web Template Wizards in the Designer make use of the Zurb Foundation front-end framework.
PAGE 440

l 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 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 Dynamic Table with a checkmark on each line, along with Signature and Date COTG elements.
PAGE 441

l Colors: Click the colored square to open the Color Picker dialog (see "Color Picker" on page 938) and pick a color, or enter a valid hexadecimal color code (see w3school's color picker) for the page background color. Do the same for the background color of the navigation bar at the top and 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.
PAGE 442

Filling a COTG template Before inserting elements in a COTG Form, have the design ready; see "Designing a COTG Template" on page 557. In a Capture OnTheGo form, you can use special Capture OnTheGo Form elements, such as a Signature and a Barcode Scanner element. For a description of all COTG elements, see: "COTG Elements" on page 689. To learn how to use them, see "Using COTG Elements" on page 574.
PAGE 443

Tip Click the Edges button on the toolbar t emporarily adds a frame to certain elements on the Design tab. These will not .Print or output. Tip If you have started creating your Capture OnTheGo template using a COTG Template Wizard, you can find ready-made elements in the Snippets folder on the Resources pane. Resources This page clarifies the difference between Internal, External and Web resources that may be used in a template, and explains how to refer to them in HTML and in scripts.
PAGE 444

When refering to them, normally you would simply use the path directly with the file name. The structure within those folders is maintained, so if you create a "signatures" folder within the "Images" folder, you need to use that structure, for example in HTML: . In scripts, you can refer to them in the same way, for example: results.loadhtml("snippets/en/navbar.
PAGE 445

Web resources Web resources are simply accessed using a full URL. This URL needs to be publicly accessible: if you type in that URL in a browser on the server, it needs to be visible. Authentication is possible only through URL Parameters (http://www.example.com/data.json?user=username&password=password) or through HTTP Basic Auth (http://username:password@www.example.com/data.json).
PAGE 446

To add a parameter, start by opening the template to which the parameter should be added. Make sure the template is visible in the workspace; then open the Parameters pane. Note Runtime parameters are always added to the file currently visible in the workspace. To add a single parameter: 1. Click the Add button ( ). 2. Give the parameter a name. 3. Select the data type.
PAGE 447

Editing a runtime parameter To edit a runtime parameter, either: l Double-click the parameter; or right-click and choose Edit; or select the parameter and click the Edit button ( l ), and modify it in the Edit Parameter dialog. Click the Set Values button ( ) and edit the JSON. Note that this method cannot be used to change the name of a runtime parameter. You can only change the values and add new runtime parameters this way.
PAGE 448

Tip When you add an Email context to an existing template you get a 'basic action email'. This is one of the 4 types of email that you can choose from when you start a template with an Email Template Wizard; see "Creating an Email template with a Wizard" on page 500.
PAGE 449

Warning If you don't have a backup of 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. In the Saving Preferences you can set whether a backup file should be created when you save the template; see "Save preferences" on page 848. Sections Sections are parts of one of the contexts in a template: Print, Emailor Web.
PAGE 450

Editing a section To open a section, expand the Contexts folder on the Resources pane, expand the respective context (Print, Emailor Web) and double-click a section to open it. Each section can contain text, images and many other elements (see "Content elements" on page 612), including variable data and other dynamic elements (see "Personalizing content" on page 770). To preview a section, open the Preview tab in the Workspace (see "Workspace" on page 1059). Copying a section To copy a section: 1.
PAGE 451

Tip The easiest way to copy a section to another template, is to use the Import Resources dialog in the other template. See: "Import Resources dialog" on page 949. Deleting a section To delete a section: l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, right-click the name of the section, and then click Delete. Warning No backup files are maintained in the template.
PAGE 452

Applying a style sheet to a section In order for a style sheet to be applied to a specific section, it needs to be included in that section. There are two ways to do this. Drag & drop a style sheet 1. Click and hold the mouse button on the style sheet on the Resources pane. 2. Move the mouse cursor within the Resources pane to the section to which the style sheet should be applied. 3. Release the mouse button. Using the Includes dialog 1. On the Resources pane, right-click the section, then click Includes.
PAGE 453

Arranging sections Changing the order of the sections in a context can have an effect on how they are outputted; see: "Print sections" on page 466, "Email templates" on page 506 and "Web pages" on page 528. To rearrange sections in a context: l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, and then drag and drop sections to change the order they are in. Alternatively, right-click a section and click Arrange.
PAGE 454

l PCL l PDF l PostScript (including the PPML, VIPP and VPS variants) With the Designer you can create one or more Print templates and merge the template with a data set to generate personal letters, invoices, policies, or any other type of letter you can think of. The Print context is the folder in the Designer that can contain one or more Print sections. Print templates (also called Print sections), are part of the Print context.
PAGE 455

See "Pages" on page 477 for an overview of settings and elements that are specific for pages. Headers, footers, tear-offs and repeated elements (Master page) In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear on each first page, or only on pages in between the first and the last page, or only on the last page.
PAGE 456

Copy Fit Copy Fit is a feature to automatically adjust the font size of text to make it fit the available space. It could be used for the name of a person on a greeting card, for instance, or for the name of a product on a shelf talker. This feature is only available with Box and Div elements in Print sections. For more information about this feature see "Copy Fit" on page 743. Creating a Print template with a Wizard A Print template may consist of various parts, such as a covering letter and a policy.
PAGE 457

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. Basic Print template wizards There are two 'basic' Print Template wizards: one for a formal letter, and one for a postcard.
PAGE 458

See "Print context" on page 461 and "Print sections" on page 466 for more information about Print templates. Formal letter The Formal Letter Wizard first lets you select the page settings, see "Page settings: size, margins and bleed" on page 478. These settings are fairly self-explanatory, except perhaps these: l l l l Duplex means double-sided printing. The margins define where your text flow will go. The actual printable space on a page depends on your printer.
PAGE 459

expand the Contexts folder on the Resources pane; expand the Print folder and rightclick "Section 1"; then select Sheet Configuration.) See "Media" on page 488. l Selectors for variable data, for example: @Recipient@. You will want to replace these by the names of fields in your data. See "Variable Data" on page 785. The Wizard opens the Print section. You can add text and other elements; see "Content elements" on page 612. The formal letter template already has an address on it.
PAGE 460

location should be accessible from the machine on which the template's output is produced. External images are updated (retrieved) at the time the output is generated. After clicking Next, you can change the settings for the page. The initial page size and bleed area are taken from the selected PDF. When you click Finish, the Wizard creates: l l l A Print context with one section in it; see "Print context" on the next page and "Print sections" on page 466.
PAGE 461

l Choose the desired type of business document from the General drop-down. l Select a color for the colored parts of the document; see "Color Picker" on page 938. l Enter your contact details. l l Click the Browse button to select a logo, or select to use a placeholder logo or no logo at all. Select a PDF file with the letterhead stationery. Also see "Media" on page 488. Tip Nice to know: your info and preferences are saved and will be reused the next time you create an ERP template.
PAGE 462

Print templates (also called Print sections), are part of the Print context. They are meant to be printed directly to a printer or a printer stream/spool file, or to a PDF file (see "Generating Print output" on page 1442). The Print context can also be added to Email output as a PDF attachment; see "Generating Email output" on page 1470. 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.
PAGE 463

In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear on each first page, or only on pages in between the first and the last page, or only on the last page. Examples are a different header on the first page, and a tear-off slip that should show up on the last page. This is what Master Pages are used for. Master Pages can only be used in the Print context. See "Master Pages" on page 485.
PAGE 464

Printing on both sides To print a Print section on both sides of the paper, that Print section needs to have the Duplex printing option to be enabled; see "Enabling double-sided printing (Duplex, Mixplex)" on page 474. This setting can not be changed in a Job Creation Preset or an Output Creation Preset. Note Your printer must support duplex for this option to work.
PAGE 465

Setting the bleed The bleed is the printable space around a page. It can be used on some printers to ensure that no unprinted edges occur in the final trimmed document. The bleed is one of the settings for a section. See "Page settings: size, margins and bleed" on page 478. Overprint and black overprint Normally, when two colors overlap in Print output, the underlying color is not printed.
PAGE 466

1. Right-click the Print context in the Resources pane and select Color Output. 2. Enable the Keep RGB black in output option. In Connect versions prior to 2018.2, RGB black was not automatically converted to CMYK black. Therefore, this option is by default enabled in templates made with an earlier version. In new templates, this option is disabled by default. Print sections Print templates (also called Print sections), are part of the Print context.
PAGE 467

See "Master Pages" on page 485 for an explanation of how to fill them and how to apply them to different pages. Using stationery (Media) When the output of a Print context is meant to be printed on paper that already has graphical and text elements on it (called stationery, or preprinted sheets), you can add a copy of this media, in the form of a PDF file, to the Media folder. Media can be applied to pages in a Print section, to make them appear as a background to those pages.
PAGE 468

to be printed out on paper. When a Print template is created (see "Creating a Print template with a Wizard" on page 456 and "Print context" on page 461), only one Print section is added to it, but you can add as many print sections as you need. To add a section to a context: l On the Resources pane, expand the Contexts folder, right-click the Print context , and then click New section. Note that the new section automatically gets the same properties as the first section.
PAGE 469

Tip If you need a whole Print section to be visible in the output only under certain conditions, consider using the Conditional Print Section script wizard; see "Conditional Print sections" on page 798. You can use the Conditional Content script wizard to hide parts of the content of a section; see "Showing content conditionally" on page 795. Importing a Print section To import a section from another template, click File > Import Resources... in the menu. See: "Import Resources dialog" on page 949.
PAGE 470

output in the order in which they appear on the Resources pane, so changing the order of the sections in the Print context changes the order in which they are outputted to the final document. To rearrange sections in a context: l l On the Resources pane, expand the Print context and drag and drop sections to change the order they are in. Alternatively, on the Resources pane, right-click a section in the Print context and click Arrange.
PAGE 471

gives it less weight. In case of conflicting rules, style sheets read later will override previous ones. Note Style sheets are applied in the order in which they are included in a section. The styles in each following style sheet add up to the styles found in previously read style sheets. When style sheets have a conflicting rule for the same element, class or ID, the last style sheet ‘wins’ and overrides the rule found in the previous style sheet. Note Style sheets that are linked to (i.e.
PAGE 472

this option you don't need to make any other settings; click OK to close the dialog. 3. For a PDF resource, you have to specify the path. Clicking the Select Image button opens the Select Image dialog (see "Select Image dialog" on page 1003). 4. l Click Resources, Disk or Url, depending on where the image is located. l l l Resources lists the images that are present in the Images folder on the Resources pane.
PAGE 473

generate output, and that their location should be accessible from the machine on which the template's output is produced. External images are updated (retrieved) at the time the output is generated. 5. Select the PDF's position: l Fit to page stretches the PDF to fit the page size. l Centered centers the PDF on the page, vertically and horizontally. l Absolute places the PDF at a specific location on the page.
PAGE 474

Dynamic backgrounds To make the background change based on the value of a data field, you may use the Dynamic Background Script Wizard; see "Dynamic Print section backgrounds" on page 820. Alternatively you could write your own Control Script to set the background; see "Control Script: Setting a Print section's background" on page 899. The settings in a script take precedence over the settings made in the Print Section Properties dialog.
PAGE 475

Note Your printer must support Duplex for this option to work. To enable Duplex or Mixplex printing: 1. On the Resources pane, expand the Print context, right-click the print section and click Sheet configuration. 2. Check Duplex to enable content to be printed on the back of each sheet. 3. When Duplex printing is enabled, further options become available. l Check Omit empty back side for Last or Single sheet to reset a page to Simplex if it has an empty back side.
PAGE 476

"Control Scripts" on page 890 and "Control Script API" on page 1379). This is especially useful when you need identical sections with different settings. The consequences of empty back sides for printing and page numbering In a Duplex job, the last page of a section may be empty since each new section starts on a new sheet. You may wonder what this means for the number of 'print clicks' and for the page numbering. Note that an empty page is defined as a page that has no content and no Master Page.
PAGE 477

Pages Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally limited by their size and margins. If the content of a section doesn't fit on one page, the overflow goes to the next page. This happens automatically, based on the section's page size and margins; see "Page settings: size, margins and bleed" on the facing page. The minimum number of pages can be set via the Print section properties; see "Print section properties" on page 996.
PAGE 478

Positioning and aligning elements Sometimes, in a Print template, you don't want content to move up or down with the text flow. To prevent that, put that content in a Positioned Box. See "Content elements" on page 612. When it comes to positioning elements on a page, Guides can be useful, as well as Tables. See "How to position elements" on page 744. Page settings: size, margins and bleed On paper, whether it is real or virtual, content is naturally limited by the page size and margins.
PAGE 479

extra pages created just for promotional data. 'Whitespace elements' are elements that will only appear on the page if there is enough space for them. To convert an element into a whitespace element: 1. Import the promotional image or snippet; see "Images" on page 708 and "Snippets" on page 722. 2. Insert the promotional image or snippet in the content. Note l l Only a top-level element (for example, a paragraph that is not inside a table or div) can function as a whitespace element.
PAGE 480

l l l l l l Page number: The current page number in the document. If a page is empty or does not display a page number, it is still added to the page count. Page count: The total number of pages in the document, including pages with no contents or without a page number. Content page number: The current page number in the document, counting only pages with contents that are supplied by the Print section.
PAGE 481

page 1366. For a multi-page, cross-section table of contents you must use a Post Pagination Script; see "Creating a Table Of Contents" on page 908. The basics of script-writing in the Designer are explained in the following topic: "Writing your own scripts" on page 853. Configuring page numbers By default the page numbers are Arabic numerals (1, 2, 3, etc.) without leading zeros nor prefix, and page numbering starts with page 1 for each section. But this can be changed. To do that: 1.
PAGE 482

lines get separated from the rest of the paragraph. The same applies to list items (in unordered, numbered and description lists). The number of lines that should be considered a widow or orphan can be changed for the entire Print context, per paragraph and in tables. Note Widows and orphans are ignored if the page-break-inside property of the paragraph is set to avoid; see "Preventing a page break" on page 484. In the entire Print context To prevent widows and orphans in the entire Print context: 1.
PAGE 483

l Right-click the paragraph and select Paragraph... from the contextual menu. 2. After Widows and Orphans, type the minimum number of lines that should be kept together. In tables The CSS properties widows and orphans can be used in tables to prevent a number of rows from being separated from the rest of the table. Dynamic Tables are automatically divided over several pages when needed. A Standard Table doesn't flow over multiple pages by default.
PAGE 484

and paragraphs" on page 739): 1. Select the element (see "Selecting an element" on page 616). 2. On the Format menu select the respective element to open the Formatting dialog. 3. In the Breaks group, set the before or after property. l l Before: Sets whether a page break should occur before the element. This is equivalent to the page-break-before property in CSS; see CSS page-break-before property for an explanation of the available options.
PAGE 485

Adding blank pages to a section How to add a blank page to a section is described in a how-to: Create blank page on field value. Master Pages In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear only on specific pages, such as only the first page, or the last page, or only on pages in-between. Examples are a different header on the first page, and a tear-off slip that shows up on the last page.
PAGE 486

the facing page. l Click OK. Initially, the master page that has been created together with the Print context will be applied to all pages in the Print section. After adding more Master Pages, different Master Pages can be applied to different pages; see "Applying a Master Page to a page in a Print section" on the next page. Importing a Master Page To import one or more Master Pages from another template, click File > Import Resources... in the menu. See: "Import Resources dialog" on page 949.
PAGE 487

1. First insert elements that form the header or footer, such as the company logo and address, on the Master Page; see "Editing a Master Page" on the previous page. 2. Next, define the margins for the header and footer. The margins for a header and footer are set in the Master Page properties. This does not change the content placement within the Master Page itself; in Master Pages, elements can go everywhere on the page.
PAGE 488

pointing arrow after Master Page Front and select a Master Page. If Duplex is enabled, you can also select a Master Page for the back of the sheet and consequently, check Omit Master Page Back in case of an empty back page to omit the specified Master Page on the last backside of a section if that page is empty. That page will then also be skipped from the page count unless the page numbers continue on the next section (see "Configuring page numbers" on page 481).
PAGE 489

For further explanation about how to apply Media to different pages, see "Applying Media to a page in a Print section" on page 493. Media will not be printed, unless you want them to; see below. Per Media, a front and back can be specified and you can specify on what kind of paper the output is meant to be printed on. This includes paper weight, quality, coating and finishing; see "Setting Media properties" below.
PAGE 490

type of image file) for both the front and the back of the Media, and you can determine how the virtual stationery should be positioned on the page. This is done as follows: 1. On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Properties. 2. Now you can change the name and page size of the Media. Note that it isn't possible to change the page size once the Media is applied to a section. Media can only be applied to sections that have the same size. 3.
PAGE 491

Note If a URL doesn't have a file extension, and the option Save with template is not selected, the Select Image dialog automatically adds the filetype parameter with the file extension as its value (for example: ?filetype=pdf (if it is the first parameter) or &filetype=pdf). The filetype, page and nopreview parameters are not sent to the host; they are used internally. Therefore, URLs that rely on one of these parameters cannot be used.
PAGE 492

and the Left field to specify the distance between the left side of the page and the left side of the PDF. 7. Finally, click OK. Setting the paper's characteristics To set a Media's paper characteristics: 1. On the Resources pane, expand the Contexts folder, expand the Media folder, and right-click the Media. Click Characteristics. 2. Specify the paper's characteristics: l l l l l l l Media Type: The type of paper, such as Plain, Continuous, Envelope, Labels, Stationery, etc.
PAGE 493

Applying Media to a page in a Print section Every page in a print section has a natural position: it can be the first page, the last page, one of the pages in between (a 'middle page'), or a single page. For each of those positions, you can set different Media. To apply Media to specific page positions in a Print section: 1. On the Resources pane, expand the Print context; right-click the Print section, and click Sheet configuration. 2.
PAGE 494

Dynamically switching the Media In addition to applying Media to sheets via the settings, it is possible to change Media dynamically, based on a value in a data field, in a script. The script has already been made; you only have to change the name of the Media and the section in the script, and write the condition on which the Media has to be replaced. 1. On the Resources pane, expand the Contexts folder, expand the Print context, rightclick the print section and click Sheet configuration. 2.
PAGE 495

l l On the Resources pane, expand the Print context; right-click the Print section, and click Sheet configuration. Click one of the options next to Media rotation. The Media will be rotated accordingly in the entire section. Note l l Any Virtual Stationery settings made for the Media also influence how the Media is displayed in each section (see "Setting Media properties" on page 489). Section backgrounds are rotated separately (see "Using a PDF file or other image as background" on page 471).
PAGE 496

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 500. Also see "Designing an Email template" on the next page for guidelines on the design.
PAGE 497

Attaching the Print context and/or the Web context is one of the options in the "Send (Test) Email" on page 999 dialog. These options are also available in the Create Email Content task in Workflow. See "Email attachments" on page 518 and "Generating Email output" on page 1470. Designing an Email template With the Designer you can design Email templates.
PAGE 498

Nesting tables (putting tables in table cells) and applying CSS styles to each table cell to make the email look good on all screen sizes is a precision work that can be a tedious and demanding. Connect's Designer offers the following tools to make designing HTML email easier. Email templates: Slate and others The most obvious solution offered in the Designer is to use one of the templates provided with the Designer; see "Creating an Email template with a Wizard" on page 500.
PAGE 499

All standard abbreviations can be found in Emmet's documentation: Abbreviations. To learn more about Emmet, please see their website: Emmet.io and the Emmet.io documentation: http://docs.emmet.io/. Preferences To change the way Emmet works in the Designer, select Window > Preferences, and in the Preferences dialog, select Emmet; see "Emmet preferences" on page 839.
PAGE 500

images and track open rates) or a reputable image hosting service, like photobucket.com. Don't forget to set the Alternate Text for your images on the Attributes pane. Do not capture your email in one big image Most e-mail clients do not automatically download images, so do not capture your email in one big image. The recipient initially sees a blank message and probably deletes it right away.
PAGE 501

1. In the Welcome screen that appears after startup: l l Choose Browse Template Wizards. Scroll down until you see the Email Template Wizards. There are three types of Email Template Wizards: l Basic Email templates l Banded Email templates l Slate: Responsive Email templates by Litmus. Or choose Create a New Template and select the Email template. This starts the Basic Action Email wizard. Alternatively, on the File menu, click New, and: l l Select Email Template.
PAGE 502

called "email-to". After loading dataor a data mapping configuration, you can change the script so that it uses the actual field in your data that holds the customer's email address. See "Email header settings" on page 510 l A style sheet, named context_htmlemail_styles.css, and another style sheet depending on which Template Wizard was used. The style sheets can be found in the Stylesheets folder on the Resources pane.
PAGE 503

Slate: Responsive Email Templates by Litmus Scroll past the Web Template Wizards to see the Slate: Responsive Email templates, created by Litmus (see https://litmus.com/resources/free-responsive-email-templates). More than 50% of emails are opened on mobile. These five responsive HTML email templates are optimized for small screens and they look great in any inbox. They’ve been tested in Litmus and are completely bulletproof.
PAGE 504

l l l The text for the header. The header is the colored part at the top. The text can be edited later. The color of the header and the color of the button. Click the small colored square, right next to the field that holds the default color value, to open the Color dialog and pick a color (see "Color Picker" on page 938). The color can be changed later; see "Colors" on page 760. The web address where the recipient of the email will be taken after clicking the button in the email.
PAGE 505

The Wizard opens the Email section, so that you can fill it with text and other elements; see "Content elements" on page 612 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 1470. To test a template, you can send a test email first. This allows you to override the recipient address.
PAGE 506

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; then right-click the Email context and select PDF Attachments. Alternatively, select Context > PDF Attachments on the main menu. This option is only available when editing an Email section in the Workspace.
PAGE 507

it is advisable to position elements using Tables and to put text in table cells (see "Designing an Email template" on page 497). Email templates are personalized just like any other template; see "Variable Data" on page 785. The subject, recipients (To, CC and BCC), sender and reply-to address are specified with Email Script Wizards; see "Email header settings" on page 510. An Email context can contain multiple templates.
PAGE 508

Importing an Email template To import an Email section from another template, click File > Import Resources... in the menu. See: "Import Resources dialog" on page 949. Remember also to add or import any related source files, such as images. Note that when the imported Email section replaces an Email section in your template, the PDF attachments settings are imported as well. (See: "Compressing PDF attachments" on page 506.
PAGE 509

Tip Before you can style an element, you have to select it. In an Email context it can be difficult to select an element by clicking on it. Use the breadcrumbs at the top and the Outline pane at the left, to select an element. See "Selecting an element" on page 616. In order for a style sheet to be applied to a specific section, it needs to be included in that section. There are two ways to do this. Drag & drop a style sheet 1. Click and hold the mouse button on the style sheet on the Resources pane. 2.
PAGE 510

Note Style sheets that are linked to (i.e. included in) a section show a chain icon in the Resources pane (see "Resources pane" on page 1047). Setting a default Email template for output 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.
PAGE 511

Email Fields The subject, the recipients (To, Cc and Bcc), the sender and the Reply to address can be entered in the Email Fields at the top of the workspace. If the fields are not visible, click the words 'Email Fields' (or the small plus before them) to expand the Email Fields area. To use a variable email address in any of the fields, simply drag and drop a data field into the email field. The specified subject and addresses will be visible when viewing the email in the workspace in Preview mode.
PAGE 512

Other header fields At some point you may need to define a header field that isn't available in the Preferences or in the Email Fields. This can be done in a Control Script. For a few examples of such scripts, see "Adding custom ESP handling instructions" on page 1477. To get started with Control Scripts, refer to "Control Scripts" on page 890. Email SMTP settings Simple Mail Transfer Protocol (SMTP) is the standard protocol for sending emails across the Internet.
PAGE 513

l l Use authentication: Check this option and fill in the user name if a user name and password are needed to send emails through the host. (The password has to be specified in the Send Email or Send Test Email dialog.) Send STARTTLS: This option is enabled if authentication is checked. With STARTTLS the client negotiates with the mail server to use some form of encryption, usually a version of Transport Layer Security (TLS).
PAGE 514

You can add as many data fields to the subject as you like. When you do add more than one data field, the existing Subject script will be modified to include all data fields that are added to the subject. The result of the script will be visible in the Subject field in Preview mode: click the Preview tab at the bottom of the workspace. Note By default, the Subject script targets one email section specifically. You can see this when you double-click the script on the Scripts pane.
PAGE 515

added to the Scripts pane. Note that you can add only one data field to the email field this way. When you drag another data field into the email field the existing script will be replaced.. Email addresses can be added to the Cc and Bcc fields in the same manner, but it is also possible to type an email address directly in the Cc or Bcc field (as long as no script is present for that field). Multiple email addresses should be separated by a semicolon.
PAGE 516

Note When sending emails with a variable From address through PlanetPress Workflow, check the option Precedence to template address in the Create Email Content task properties to make sure that the dynamic address gets precedence over the email address specified in the task properties (see Create Email Content task). Reply To address The Reply To address is used by mail clients, when the recipient clicks the Reply To (or Reply All) button.
PAGE 517

For more information on tags, see W3Schools - HTML meta tag. Email PDF password The Email PDF Password Script Wizard defines a password with which to protect the PDF generated when using the Print context as PDF Attachment option in the Send Email or Send Test Email dialogs (see "Generating Email output" on page 1470). The result of the script will be the password necessary to open the PDF when it is received by email. To define a password to protect the generated PDF attachment: 1.
PAGE 518

Email attachments Output, generated from an Email template, can have the following attachments: l The contents of the Print context, in the form of a single PDF attachment. (Compression options for PDF attachments can be specified in the Email context's properties; see "Compressing PDF attachments" on page 506.) l The output of the Web context, as a self-contained HTML file. l Other files, an image or a PDF leaflet for example.
PAGE 519

Email section's properties (see "Properties tab" on page 995). With new templates this is always the case. Attaching files Selecting and adding files as attachments If you want all recipients to get the same attachments with their email, you can add the attachments to the Email section(s). The easiest way is to drag and drop the desired file on the Email section. If the file is an image, you will be presented with the option to import it into the template's Resources folder.
PAGE 520

4. Fill in the different parts of which the file name is composed: l l l Prefix. The first prefix contains the base path (or at least the first, static part of the path). For example:C:\Attachments\, C:/Attachments/, or file:///C:/Attachments/. Data field/s. The selected data field/s will be evaluated. If a data field is empty, the entire row is skipped. Otherwise the prefix, data field value and suffix are added to the path/file name. Suffix.
PAGE 521

Note that even a space character is invalid in a URL. Spaces in a URL are supported for backward compatibility, but it is recommended to percent-encode a space character as %20. 5. The attachment's name in the email will be the part of the path that comes after the last '/'. When there are no forward slashes in the path, the full path is used. You may want to use a custom attachment name. To learn how to do that, see "Renaming attachments" below. 6. Click OK or Apply to save your changes.
PAGE 522

Note For attachment names, it is recommended to use only US-ASCII characters. Other characters may not be supported by all email servers and clients. Web With the Designer you can create one or more Web templates and merge the template with a data set to generate personal web pages. The Web context is the Web output channel and the folder in the Designer that can contain one or more Web templates.
PAGE 523

When a Web template is created, either with a Wizard or by adding the Web context to an existing template (see "Adding a context" on page 448), the Web context folder is created along with other files that are specific to a Web context; see "Web Context" on page 527. Many of the content elements that are available for all three contexts are particularly suitable for web pages; see "Content elements" on page 612. Web templates are personalized just like any other template; see "Variable Data" on page 785.
PAGE 524

1. l l In the Welcome screen that appears after startup, choose Browse Template Wizards. Scroll down until you see the Foundation Web Page Starter Template Wizards. Alternatively, on the File menu, click New, expand the Template folder, and then expand the Foundation Web Page Starter folder. 2. Select a template.
PAGE 525

l Primary: links on the page. l Secondary: secondary links on the page. l Text: text on the page contained in paragraphs (
). l Headings: all headings (
through
) including the heading section's subhead. 4. Click Finish to create the template. The Wizard creates: l l l l A Web context with one web page template (also called a section) in it.
PAGE 526

Use the Styles pane next to the Attributes pane to see which styles are applied to the currently selected element. Tip Click the Edges button on the toolbar t emporarily adds a frame to certain elements on the Design tab. These will not .Print or output. Web Template Wizards Foundation With the exception of the most basic one, all Web Template Wizards in the Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon.
PAGE 527

Blank web page The Blank Web Page template is a very simple Foundation template that contains a top bar menu and some basic contents to get you started. Web Context In the Designer the Web context is the folder that contains Web page templates. Creating the Web context You can start creating a Web template with a Wizard (see "Creating a Web template with a Wizard" on page 523), or add the Web context to an existing template (see "Adding a context" on page 448).
PAGE 528

l Output the Web context in an automated Workflow using the Create Web Content task (see Workflow Help: Create Web Content). See "Generating Web output" on page 1481. Includes The Web context outputs one HTML web page. In addition to the HTML text it contains either the resources or references to the resources necessary to display it. JavaScript files are added to the in the generated HTML file.
PAGE 529

section (see "Setting a default Web page for output" on page 532) before generating Web output; also see "Generating Web output" on page 1481. Creating a Web page When creating a Web page, it is advisable to follow design guidelines for web pages, so that they are likely to look good in different browsers and on different devices and screen sizes.
PAGE 530

Importing a Web page To import a Web page from another template, click File > Import Resources... in the menu. See: "Import Resources dialog" on page 949. The Web page's Includes settings get imported automatically (see "Includes" on page 528). Remember to add or import any related source files, such as style sheets and images. Deleting a Web page To delete a Web section: l On the Resources pane, expand the Contexts folder, expand the Web context, rightclick the name of the section, and then click Delete.
PAGE 531

Using Variable Data in Form elements Variable data may be used in form elements, such as a drop-down list (a Select element). How to do that, is described in this how-to: Dynamically add options to a dropdown. Passing Variable Data to client-side JavaScript When serving Web pages using Workflow, the HTML is first personalized and then served to the web browser by a Workflow process. At that stage custom JavaScripts do not have access to the information stored in the Data Model.
PAGE 532

CSS files and use the Up and Down buttons. Note that moving a style sheet up in the list gives it less weight. In case of conflicting rules, style sheets read later will override previous ones. Note Style sheets are applied in the order in which they are included in a section. The styles in each following style sheet add up to the styles found in previously read style sheets.
PAGE 533

value of a data field. See "Control Scripts" on page 890. Including JavaScript files Which JavaScript files are included in the a Web section, depends on a setting for that section. To change this: 1. On the Resources pane, right-click a section in the Web context and click Includes. 2. From the File types dropdown, select JavaScripts. 3. Choose which JavaScript files should be included in this section. The list at the left displays the JavaScript files that are present in the template's resources.
PAGE 534

Tip If a valid favicon image is dragged to the Web section, it will automatically be set as a shortcut icon. 4. The Meta Information Group lists all tags that will be added to the header of the HTML file generated in the output. Click the Add button to add a new tag to the list. Then you can select the type of tag, which is either name or http-equiv, and enter the value (for a name-type meta tag) or the content. For more information on tags, see W3Schools - HTML meta tag.
PAGE 535

Forms Web templates can contain Forms. Capture OnTheGo templates always contain a Form. Tip To create a Capture OnTheGo template, preferably use a Template Wizard (see "Capture OnTheGo template wizards" on page 560). The Wizard doesn't just add the form, it also adds the necessary Capture OnTheGo form elements (see "COTG Elements" on page 689), style sheets and JavaScript files, and extra pre-made elements. Adding a Form This procedure describes how to add a Form element to an existing Web context. 1.
PAGE 536

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.
PAGE 537

11. Use the Location drop-down to select where to insert the element. l l l l l l At cursor position inserts it 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 insertion point will be before the
tag.* After start tag inserts it within the current HTML element, at the beginning, just after the start tag.
PAGE 538

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 770) and styling (see "Styling templates with CSS files" on page 727). 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 Workflow process that starts with a Server Input task, for example). A Method: this defines whether the form should be sent using the GET or POST method.
PAGE 539

l 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 length: Enter a numerical value for the minimum character length required for this field. Maximum length: Enter a numerical value for the minimum character length accepted 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.
PAGE 540

Using Form elements Web Form elements can be used in a Web Form or in a Capture OnTheGo Form (see "Forms" on page 697 and "Capture OnTheGo" on page 550). This topic explains how to add these elements to a Form and how to prepare them so that when the Form is submitted, they provide valid data that can be handled easily. For a list of Form elements, see "Form Elements" on page 702. For a list of the extra elements that can be used in a Capture OnTheGo form, see "COTG Elements" on page 689.
PAGE 541

l 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.
PAGE 542

settings (see "Changing a Form's validation method" on page 700). It isn't always useful to make a field required; after all, if it has a default value it will never be empty. l l 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.
PAGE 543

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 "Adding elements to a Form" on page 540. Making elements required To change the validation of a COTG or 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 700.
PAGE 544

With the Use PHP arrays option enabled in Workflow, the above HTML results in the following XML: pparker@eu.objectiflune.
PAGE 545

This option makes it easier to select all elements on the same level in a data mapping configuration, and to convert the XML to a JSON object. You can try out this feature with the COTG Time Sheet template, as explained in this how-to: Using The PHP Array Option. The COTG Fields Table element (see "Fields Table" on page 693) in that template has an Add button to add rows to a table, and groups data following this approach.
PAGE 546

Some JavaScript files are added automatically: When you create a template with a COTG Template Wizard (see "Capture OnTheGo template wizards" on page 560), the Designer automatically adds the jQuery library and the COTG library: cotg-2.0.0.js. This also happens when you add a Capture OnTheGo (COTG) element to a template that you didn't start with a COTG template wizard. For more information about this plugin, see "Using the COTG plugin: cotg-2.0.0.js" on page 587.
PAGE 547

Now the JavaScript file is ready to be used in your Web templates; see "Including a JavaScript file in a Web context" on the facing page. Adding a remote JavaScript file A Remote JavaScript Resource is a file that is not located within your template but is hosted on an external web server , generally called a CDN.
PAGE 548

(while the page continues the parsing). When neither option is checked, the script is fetched and executed immediately, while the parsing of the page is paused. 5. Optionally, for a Capture OnTheGo Form, you can check Use cached Capture OnTheGo resource, to prevent downloading a remote JavaScript file again if it has been downloaded before.
PAGE 549

4. The available JavaScript files are listed at the left. Use the arrow buttons or double-click to move the JavaScript files that should be included to the right-hand list. Using the Up and Down buttons or drag-and-drop you can change the order of the files, too. 5. Click OK. Note JavaScript files that are linked to (i.e. included in) a section show a chain icon in the Resources pane (see "Resources pane" on page 1047).
PAGE 550

JavaScript resources included in a Print section are executed on the Preview tab. (The editor for a Print section does not have a Live tab.) Note The internal browser engine which is used as of version 2018.2, Gecko 38, is compliant with the ECMAScript 5 language specification. This means that scripts using features described in ECMAScript 2015 (aka ES6) - such as the keyword let - will fail in the Preview and Livetab of the Designer.
PAGE 551

l It may be reusable. This depends on a setting in the Output to Capture OnTheGo plug-in (found on the Connectors tab) in Workflow (see the Workflow Help: Output to CaptureOnTheGo). A reusable COTG Form is not deleted from the app's form library when it is submitted, so it can be used again. Creating a COTG Form A Capture OnTheGo Form is actually just a Web Form, so you could add a Form element to a Web page in the Web context without the use of a Template Wizard.
PAGE 552

Note For testing purposes, it is possible to use another URL for the Form's action or not to specify an action at all; see "Testing a Capture OnTheGo Template" on page 580. Filling a COTG template Before inserting elements in a COTG Form, have the design ready; see "Designing a COTG Template" on page 557. In a Capture OnTheGo form, you can use special Capture OnTheGo Form elements, such as a Signature and a Barcode Scanner element. For a description of all COTG elements, see: "COTG Elements" on page 689.
PAGE 553

Use the Attributes pane at the right to see the current element's ID, class and some other properties. Use the Styles pane next to the Attributes pane to see which styles are applied to the currently selected element. Tip Click the Edges button on the toolbar t emporarily adds a frame to certain elements on the Design tab. These will not .Print or output. Using JavaScript COTG plugin Capture OnTheGo widgets do not function without the COTG plugin: cotg-2.0.0.js.
PAGE 554

to preview the form, how to submit data and how to preview the submitted data is described in another topic: "Testing a Capture OnTheGo Template" on page 580. Sending the template to the Workflow tool After testing the template (see "Testing a Capture OnTheGo Template" on page 580) the template must be sent to the Workflow module. Templates sent to the Workflow module can be used in any process within it.
PAGE 555

Note When a COTG Form is submitted, by clicking or touching the Submit button, the name and value of form elements are submitted. If a Checkbox or Radio Button is not checked, its name and value are not sent when the form is submitted. Fortunately, there is a workaround for this; see "Using COTG Elements" on page 574. The Form's validation should ensure that the data that the user submits is valid (see "Changing a Form's validation method" on page 700 and "How to make COTG elements required" on page 577).
PAGE 556

and Windows 6.0) is formatted so that the signature will automatically be scaled to fit in the containing box in a template. With previous versions of the app the format of returned signatures could vary. Adding Camera data to the template The Camera widget submits a base64-encoded string, which can be put in a data field using the DataMapper. When this data field is dragged into a template, the string will show up in the content, instead of the image.
PAGE 557

should be resized as well. If the inline box isn't visible, click the Show Edges button in the toolbar. Designing a COTG Template Designing a Capture OnTheGo template is more than adding elements to a Web form. This topic shares some insights regarding the design process and principles. Design process Ideally, the design process consists of the following steps. 1. Gathering information.
PAGE 558

4. Creating the form. Create the form in accordance with web design principles; see "Form design" below. 5. Testing the form. Even if you did proper research and showed a mockup, customers or users will likely come up with new requirements once they've seen the initial live version. Be prepared and plan for this, too. Form design Paper forms and web forms are very different in nature. For example, paper forms have a fixed size: the size of the paper they are printed on.
PAGE 559

responsive (see "Using Foundation" on page 564 and http://foundation.zurb.com/learn/about.html). Tip In the Designer, you can test the responsiveness of a form using the Responsive Design button at the top right of the workspace. Some browsers also let you test the responsiveness of a form. In Firefox, for example, select Developer > Responsive Design to view a form in different sizes. Usability Usability defines the ease of use of a form.
PAGE 560

Provide feedback. Show what input data is expected, clearly identify which fields are required and show errors when the entered data doesn’t meet the required format. Capture OnTheGo form characteristics Reusable forms Capture OnTheGo forms can be single-use or reusable. This doesn't depend on the design (although, of course, this should be reflected in the design). What makes a form reusable is a setting in the Output to Capture OnTheGo plugin in Workflow; see Output to CaptureOnTheGo.
PAGE 561

For more information about the use of Foundation in the Designer, see "Using Foundation" on page 564. After creating a COTG template, the other contexts can be added, as well as other sections (see "Adding a context" on page 448 and "Adding a Web page" on page 529). 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 userfriendliness of the form.
PAGE 562

l l l l Membership Application. The Membership Application Template is a signed generic request form that can be used for memberships such as gyms, clubs, etc. Patient Intake. The Patient Intake Template is a generic medical questionnaire that could potentially be used as a base for insurance or clinic form. Kitchen Sink. The Kitchen Sink Template includes a wide range of basic form and COTG form elements demonstrating various possibilities of the software. Time Sheet.
PAGE 563

folder on the Resources pane. The JavaScript files are located in the JavaScript folder on the Resources pane. l A collection of snippets in the Snippets folder on the Resources pane. The snippets contain ready-to-use parts to build the web form. Double-click to open them. See "Snippets" on page 722 and "Loading a snippet via a script" on page 881 for information about using Snippets. The Wizard opens the Web section, so that you can fill the Capture OnTheGo form. 6.
PAGE 564

Foundation, the framework added by the COTG template wizards, comes with a series of features that can be very useful in COTG forms; see "Using Foundation" below. Naturally, Web Form elements can also be used on COTG Forms (see "Forms" on page 697 and "Form Elements" on page 702) as well as text, images and other elements (see "Content elements" on page 612).
PAGE 565

Foundation With the exception of the most basic one, all Web Template Wizards in the Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first approach, so that websites built upon Foundation look good and function well on multiple devices including desktop and laptop computers, tablets, and mobile phones.
PAGE 566

l l l row: This class identifies a Div as a horizontal block (a row) that can contain up to 12 columns. columns: This class should be used for a Div inside a Div with the class row. It identifies a Div as part of a row Div. small-n, medium-n, large-n: These classes indicate the number of columns that this Div occupies within in the row, on a small, medium or large screen, respectively. Replace n with a number, for example: small-2, large-4.
PAGE 567

There's more that you can do with the Grid, for example, you could center columns, or switch columns depending on the screen size they are viewed on. For information about all these possibilities, see this website: http://foundation.zurb.com/sites/docs/v/5.5.3/components/grid.html. Adding Divs and classes to a Connect Form template To insert a Div, select Insert > Structural Elements > Div on the menu.
PAGE 568

They make use of checkbox inputs (or radio buttons) and require no javascript. Their size can be adapted, to make them easy to use on a touch screen. For a full overview and explanation of all Foundation components (v. 5), see this web page: http://foundation.zurb.com/sites/docs/v/5.5.3/. 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.
PAGE 569

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. To learn how to add Camera data to a template, see "Adding Camera data to the template" on page 556. The Camera element has a number of options, of which most can be set in the Design view. These options are described below.
PAGE 570

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/deskewing To allow the user to crop, edit and deskew the image after taking or selecting it, select Camera properties, and then check Edit Image and/or Allow Deskew.
PAGE 571

How to use the captured or selected image in a template After a user has submitted the form and the data has been extracted, you may want to display the captured or selected image in a Designer template, for example in a letter or on a web page. To do this: 1. Load the data mapping configuration (or at least the data model). 2. Insert a dummy image in the template. 3. Right-click the dummy image and select Dynamic Image. The Text Script Wizard appears. 4.
PAGE 572

Document ID The Document ID element retrieves the Document ID of the form currently viewed by the app. You could put the Document ID in a hidden input, so that when the form is submitted, the Document ID is submitted as well. A Document ID can be used on the server side to check (in the Connect database) if the data has already been submitted. 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.
PAGE 573

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.
PAGE 574

containing box in a template. With previous versions of the app, the format of returned signatures could vary. 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.
PAGE 575

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 770) and styling (see "Styling templates with CSS files" on page 727). 2.
PAGE 576

The Foundation JavaScript files and style sheets will not be added. You only get those automatically when you start creating a COTG template with a template wizard. (See: "Using Foundation" on page 564.) Element specific settings After inserting certain COTG elements, such as the Camera element, some important settings have to be made. These will appear when you right-click the element and select it from the short-cut menu.
PAGE 577

Tip Click the Edges button on the toolbar t emporarily adds a frame to certain elements on the Design tab. These will not .Print or output. 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. Set the Form's validation method to jQuery and set the requirements and a message per field. For an explanation see "Changing a Form's validation method" on page 700.
PAGE 578

Grouping data using arrays In a Connect solution, when a Web Form or COTG Form is submitted, there is a Workflow process that receives the data and creates a job data file (which is an XML file). Having arrays in the job data file greatly simplifies creating a data mapping configuration and looping over data in Designer scripts. Here's how to group data in the HTML so that they get submitted as arrays.
PAGE 579

253 dent 361 341 dent With the Use enhanced PHP arrays option, the XML looks similar, but in this case, the value between the first pair of square brackets is expected to consist of two parts, separated by an underscore (e.g. row_0). The first part becomes the element's name. All content after the first underscore (preferably an integer) is given as an attribute of the element (e.g. ).
PAGE 580

Getting the status of unchecked checkboxes and radio buttons Unchecked checkboxes and radio buttons are not submitted (as per standard HTML behavior), so how to get the state of those checkboxes and radio buttons? A common approach to get the state of unchecked checkboxes and radio buttons is to add a hidden field to the Form with the same name as the checkbox or radio button, for example: Whe
PAGE 581

remember that COTG Form elements are only functional in the COTG app, so they won't submit any data. l Within the default browser on your computer. Click the Preview HTML button in the toolbar. This opens your operating system’s default browser and displays the form in that context. Tip In the Designer, you can test the responsiveness of a form using the Responsive Design button at the top right of the workspace. Some browsers also let you test the responsiveness of a form.
PAGE 582

Enter the appropriate information in the Send Test dialog (see "Send COTG Test" on page 998). Click Finish to send the document. It should automatically appear in the app's Repository for 4 days from the moment it is sent. Once downloaded it remains accessible in the app's Library for 2 days. Tip To manually delete a test template from the app's Library, swipe it to the left.
PAGE 583

right-click HTTP/Soap Server and start it. l In the Designer menu Window > Preferences > Web, the Workflow URL has been set to the correct host. The default is http://127.0.0.1:8080/_getSampleFormData_. This points to an internal process of the Workflow component running at that host. If these conditions are met, you can get the XML file as follows: 1. Open the Form in the Designer, toggle to Live mode and fill out the form.
PAGE 584

Standard Form input dummy data values Input Dummy Value Text "Lorem ipsum dolor sit amet" Textarea (multi-line text field) "Lorem ipsum dolor sit amet" Email "pparker@localhost.com" Number random integer Password 1234567890 URL "http://www.localhost.com" Checkbox Checkboxes in Dynamic Tables and in the Fields Table control (time sheet) are checked. Radio button Selects the first radio button that is not disabled in each radio group.
PAGE 585

Input Dummy Value widget Date Picker (format ted and standa rd) Today's date* TimePi cker (format ted and standa rd) Now* Device Info widget " {"available":true,"platform":"Android","version":"9.9.9","uuid":"17206724b807749 1","cordova":"3.6.4","model":"Connect Designer"}" User Accou nt widget "user@localhost.com" Locale widget en-US * Note that the formatted date and time can be different from the values that the COTG app provides.
PAGE 586

Get submitted data via email Getting submitted data via email requires the Form's action to be set to a test URL that contains an API Key. You can obtain an API Key as follows. 1. Go to http://learn.objectiflune.com/. 2. Create an account, or log in to your account. 3. Go to your Profile Page, and click the API Key link. Now, when creating or editing a COTG Form, you can use the API Key in the Form's action: 1. Select the Form (see "Selecting an element" on page 616). 2.
PAGE 587

Using the COTG plugin: cotg-2.0.0.js A Capture OnTheGo (COTG) Form may contain special COTG input elements, like a Signature, Geolocation, or Camera element. These elements do not function without the COTG JavaScript library. It is this library that links the controls with hardware features on the mobile device. As of Connect 1.8, cotg-2.0.0.js replaces the cotg-1.x.js versions of the library. The new COTG plugin introduces options and custom events for COTG widgets.
PAGE 588

If a template contains an earlier version of the COTG library, the newest version will be added to the resources, but you will be asked which version of the library you prefer to use. Your preferred library will be included in the section (see: "Includes dialog" on page 951). When this library is included in a Web template instead of a COTG template, it won't affect the template, except when the user submits a Form.
PAGE 589

Reacting to, or triggering, widget events The new COTG plugin introduces custom events for COTG controls. You can trigger and/or react to them as the user interacts with the Form. l l Use jQuery’s .on() method to attach an event handler to an element (or set of elements). Call this function on the $(document).ready event, which is triggered when the Form is loaded in the app. Use the .trigger() method to trigger an element's event.
PAGE 590

topic explains how to implement this. It is assumed that you have a basic understanding of HTML forms, CSS, JavaScript, and jQuery. Prerequisites Before you can start writing code that adds a widget in response to an action of the user, you need the following: l l l Some element on the Form to trigger the creation of the widget. This could be anything that responds to an action of the user; a button or link, for example. Make sure that this element has an ID.
PAGE 591

Constructing the HTML A widget basically is an HTML element with certain attributes and contents. The HTML structure of a widget can be seen on the Source tab after adding the widget to a Form in the Designer. In code, reconstruct the HTML. Make sure to give the new element an ID. This code constructs the HTML of a Date element: date1 PAGE 592
$('#myCamera').cotgPhotoWidget({ quality: 50, height: 1024, width: 1024 }); The initialization functions and options of all widgets are listed in the Capture OnTheGo API: "Capture OnTheGo API" on page 600. To learn how to set the defaults for one kind of elements, see "Changing default settings for widgets" on page 588.
PAGE 593

function addCameraWidget(cameraID, value) { if(typeof value == 'undefined') { value = ''; } var html = 'Camera' + '
PAGE 594
To latch on to these events, you have to register a olcotgsavestate listener and a olcotgrestorestate listener, respectively, on the window object. The window object represents a window containing a DOM (document object model), in this case the COTG Form. The function callback on its addEventListener method allows you to implement custom code as part of the save and restore processes. (For more information about the addEventListener method see the documentation: Mozilla and w3schools.
PAGE 595

Handling the save and restore events The code inside the function callback of the added event listeners should respond to the event, by saving or retrieving custom information, respectively. When the COTG app saves the Form, you can store extra information in the event.detail.state object as follows: event.detail.state["key"] = value; The key can be any string, as long as that string isn't the same as the ID of one of the widgets on the Form.
PAGE 596

the Designer). Dynamically added widgets don't get restored. To restore dynamically added widgets, you have to: l l l Save information that reveals which widgets were added dynamically, and save the values of their input fields. This code should go in the event handler for the olcotgsavestate event. Add and initialize the widgets again after the Form is reopened. Make sure to put any saved values back in the HTML. This code should go in the event handler for the olcotgrestorestate event.
PAGE 597

var val = $(this).val(); camObj[camera] = val; }); event.detail.state['my-camera-data'] = JSON.stringify(camObj); }); In the olcotgrestorestate event handler the previously stored JSON is read from the event.detail.state and parsed into a JavaScript object. A for ... in l oop is then used to iterate over the keys (the camera names) in that object. Inside this loop the cameras are added by calling the addCamera() function with the ID and value (the path to the picture) of each Camera element.
PAGE 598

$('#cameras').append(html); // add the camera object to the DOM $('#' + cameraID).cotgPhotoWidget(); // init COTG widget Using submitted COTG data in a template When a user submits a Capture OnTheGo Form, the Workflow process that receives the data may store the information in a database and/or push it into other Workflow processes. It could, for example, send a letter or an email receipt that is personalized with the submitted data.
PAGE 599

2. Create a data mapping configuration The next step is to use the sample data - an XML file - to create a data mapping configuration (see "Data mapping configurations" on page 197). 1. Choose File > New > Data mapping Wizards > From XML file. 2. Select the XML data file as its source and click Next. 3. Set the XML Elements option to /request/values. This will automatically add an extraction step for the submitted form fields. 4. Click Finish.
PAGE 600

4. Switch back to the Design tab. You will see a small, empty rectangle inside at the top of the inline box. 5. Right-click the empty rectangle and choose New Script... in the contextual menu. The Edit Script dialog appears. The selector of the script is automatically set to the ID of the selected element (#camera). Alternatively, you could add a new script on the Scripts pane and make sure that the Selector field is set to #camera. 6.
PAGE 601

Events The Barcode Scanner listens for the following events. Event Description clear.cotg Removes the scanned Barcode data. scan.cotg Opens the scanner. The Barcode Scanner broadcasts the following events. Event Description set.cotg This event is fired after Barcode data has been set to the value of the input. Camera cotgPhotoWidget([options]) options Optional. An array containing the desired settings, e.g. {quality: 50, height: 1024, width: 1024}.
PAGE 602

Option Description Type Default encodingtype The returned image's file encoding: jpg or png. String 'jpg' height The maximum height in pixels Number 864 width The maximum width in pixels. Number 1152 source Which buttons are enabled: Take now (take), Library (pick), or both (takeandpick). String 'takeandpick' scaleimage Scales the image to fit the maximum width or height. The aspect ration is maintained.
PAGE 603

Option Description Type Default String 'medium' middle, bottom) and joining them with a vertical bar ('|'). stampFontSize The time stamp's font size: small, medium, or large. Events The Camera listens for the following custom events. Event Description clear.cotg Removes the picture. savestate.cotg Saves the path of the current picture to the local storage of the COTG app. restorestate.
PAGE 604

Note that the difference between a Date and a Formatted Date is laid down in the HTML structure of the element. Events The Date and Formatted Date elements listen for the following custom events. Event Description clear.cotg Removes the date. set.cotg Sets the given date. The date should be given as a Date object, for example: $("#date").trigger("set.cotg", new Date()); // set current date show-datepicker.cotg Opens the Date picker.
PAGE 605

Event Description set.cotg This event is fired during initialization of the element, after setting its info to the current device. Document ID cotgDocumentId() Initializing a new Document ID puts the current Document ID in the hidden input of the element. Example: $('#myDocID').cotgDocumentId(); Events The Document ID element listens for the following event. Event Description clear.cotg Removes the Document ID. The Document ID element broadcasts the following event. Event Description set.
PAGE 606

(){ $(this).closest('tr').cotgDeleteRow(); }); Note that nested tables are not supported. Geolocation cotgGeolocation([options]) options Optional. An array containing the desired settings, e.g. {enableHighAccuracy: true, timeout: 3000}. For any unspecified options the default settings will be used. Call cotgGeolocation([options]) on the new Geolocation element with any settings that you want to be different from the defaults. Example: $('#myGeolocation').
PAGE 607

Event Description clear.cotg Removes the Geolocation data. restorestate.cotg Restores the state of the widget when the form is reopened in the COTG app, after the app has restored previously entered values of static input fields. update.cotg Sets the element to the current geolocation. Image & Annotation cotgNoteOnImage() Initializing a new Image & Annotation element prepares it for user interaction. Example: $('#myNoteOnImage').
PAGE 608

Event Description state.cotg the app has restored previously entered values of static input fields. savestate.cotg Saves the annotations. The Image & Annotation element broadcasts the following events. Event Description set.cotg Fired after an annotation has been made. Locale cotgLocale() Initializing a new Locale element sets it to the device's locale. Example: $('#myLocale').cotgLocale(); Events The Locale element listens for the following event. Event Description clear.
PAGE 609

Repository ID cotgRepositoryId() Initializing a new Repository ID puts the current Repository ID in the hidden input of this element. The Repository ID is based on the currently logged on COTG user. Example: $('#myRepID').cotgRepositoryId(); Events The Repository ID element listens for the following custom events. Event Description clear.cotg Removes the Repositiory ID data. The Repository ID element broadcasts the following event. Event Description set.
PAGE 610

Field Description draw.cotg Draws the signature on the form (e.g. after a set.cotg or restore-state.cotg event). restorestate.cotg Called when the form is reopened in the COTG app, after the app has restored previously entered values of static input fields. savestate.cotg Saves the signature data to the local storage of the COTG app. set.cotg Sets the given signature. The signature should be given as an SVG string, for example: $(“#signature”).trigger(“set.
PAGE 611

Events The Time and Formatted Time elements listen for the following custom events. Event Description set.cotg Stores the given time (specified in a Date object). clear.cotg Removes the set time. show-timepicker.cotg Opens the Time Picker. If no time is provided (specified in a Date object), the current time will be shown. User Account cotgUserAccount() Initializing a new User Account element puts the account of the current user in the hidden input of this element. Example: $('#myUser').
PAGE 612

Content elements Once you have created a 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. There are several ways to insert elements, see "Inserting an element" on page 615. Each element can have an ID and a class, as well as a number of other properties, depending on the element's type.
PAGE 613

see "Using the Text Script Wizard" on page 788 and "Styling and formatting" on page 726. l "Hyperlink and mailto link" on page 705 l "Barcode" on page 618 l Web "Forms" on page 697 and Web "Form Elements" on page 702 l l l l "Whitespace elements: using optional space at the end of the last page" on page 478 (Print context only) "Page numbers " on page 479 (Print context only) Article, Section, Header, Footer, Nav and Aside are HTML5 semantic elements; see https://www.w3schools.
PAGE 614

breadcrumbs show the HTML tag of 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.
PAGE 615

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 page 613). 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 616

Note Do not give an element the ID 'pages' or the class name 'dynamic'. These are reserved words. Using them as an ID or class name leads to undesirable effects. 4. Use the Location drop-down (if available) to select where to insert the element. l l l l l l At cursor position inserts it where the cursor is located in the template. Before element inserts it before the HTML element in which the cursor is currently located.
PAGE 617

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 t emporarily adds a frame to certain elements on the Design tab. These will not .Print or output. There are two more ways to select an element in the content: l Using the Breadcrumbs at the top of the workspace.
PAGE 618

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 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.
PAGE 619

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 Content" on page 1196) in the Print Wizard.
PAGE 620

l l After element inserts it after the element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be after the end tag of the paragraph (
).* Replace inserts it in place of the currently selected element. (This option is not available when inserting content in a Master Page.) * If the current element is located inside another element, use the Elements drop-down to select which element is used for the insertion location.
PAGE 621

A barcode is always added with the barcode type's default properties and dimensions, but they can easily be changed; see "Barcode type and properties" below. 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 or fields are added to the barcode value.
PAGE 622

l Code 11, see "Code 11, Code 93, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5" on page 654 l "Code 39" on page 630 l "Code 39 extended" on page 631 l Code 93, see "Code 11, Code 93, Industrial 2 of 5, Interleaved 2 of 5, Matrix 2 of 5" on page 654 l "Code 93 extended" on page 635 l "Code 128" on page 637 l "Data Matrix" on page 639 l EAN-8, EAN-13, see "UPC-A, UPC-E, EAN-8, EAN-13" on page 671 l "GS1 DataMatrix" on page 643 l "GS1-128" on page 646 l l Industrial 2 of 5, see "C
PAGE 623

Australia Post, Japan Post, KIX, USPS IMb Australia Post, Japan Post, KIX and USPS IMb are some of the types of barcodes that can be added to a template; see "Barcode" on page 618. In PlanetPress Connect versions prior to 2019.2 the USPS IMb barcode was called "OneCode". 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 619. Initially the barcode will have the barcode type's default properties.
PAGE 624

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 625

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.
PAGE 626

Tilde processing Check this option to process tilde characters in the data as special characters. (See the Java4less Barcodes Guide to learn what the tilde character can be used for.) Note that with this option checked, any tilde that needs to be included in the output must be escaped by adding another tilde: ~~.
PAGE 627

Barcode properties This topic lists the properties of the Codabar barcode. For the properties of other barcode types, see "Barcode type and properties" on page 621. 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.
PAGE 628

When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format.
PAGE 629

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 None: The barcode is rendered based on the module width. l Fit to box: The barcode is stretched to fit the parent box in both width and height.
PAGE 630

l PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and will display properly in Email output. Code 39 Code 39 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 619. Initially the barcode will have the barcode type's default properties.
PAGE 631

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 632

Barcode properties This topic lists the properties of the Code 39 extended barcode type. For the properties of other barcode types, see "Barcode type and properties" on page 621. 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.
PAGE 633

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 group 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 634

Barcode properties This topic lists the properties of the following barcode types : l Code 11 l Code 93 l Industrial 2 of 5 l Interleaved 2 of 5 l Matrix 2 of 5 For the properties of other barcode types, see "Barcode type and properties" on page 621. 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.
PAGE 635

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 636

Scale Defines if and how the rendered barcode is scaled in relation to the parent element: l None: The barcode is rendered based on the module width. l Fit to box: The barcode is stretched to fit the parent box in both width and height. 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.
PAGE 637

l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and 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 618.
PAGE 638

Scale Defines if and how the rendered barcode is scaled in relation to the parent element: l None: The barcode is rendered based on the module width. l Fit to box: The barcode is stretched to fit the parent box in both width and height. Tilde processing Check this option to process tilde characters in the data as special characters. (See the Java4less Barcodes Guide to learn what the tilde character can be used for.
PAGE 639

Data Matrix Data Matrix is one of the types of barcodes that can be added to a template; see "Barcode" on page 618. 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 619. Initially the barcode will have the barcode type's default properties.
PAGE 640

Dots Per Pixels 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 ASCII is used to encode data that mainly contains ascii characters (0-127) l C40 is used to encode data that mainly contains numbers and uppercase characters.
PAGE 641

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 642

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 None: The barcode is rendered based on the module width.
PAGE 643

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 group 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 644

l l l The barcode data must start with a leading FNC1 character. Either ~1 or ~d232. The GS1 Application Identifiers (AI) must be used for all data. The function code ~1 must be used as field separator for variable length AI elements. Only ASCII characters should be used. Barcode properties This topic lists the properties of the barcode type GS1 DataMatrix. For the properties of other barcode types, see "Barcode type and properties" on page 621.
PAGE 645

Note The following tilde codes are supported in GS1 DataMatrix barcodes: l ~1 = FNC1 character (for GS1 DataMatrix barcodes) l ~2 = Structure Append l ~3 = Reader programming l ~5 = Macro5 l ~6 = Macro6 l ~7 = ECI expressions 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 646

GS1-128 GS1-128 is one of the types of barcodes that can be added to a template; see "Barcode" on page 618. 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 619. 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...
PAGE 647

Note that with this option checked, any tilde that needs to be included in the output must be escaped by adding another tilde: ~~. 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 648

Note that barcodes of these types process tilde characters (~) in the data as special characters. See the Java4less Barcodes Guide to learn what the tilde character can be used for. Barcode properties This topic lists the properties of the following barcode types : l Code 11 l Code 93 l Industrial 2 of 5 l Interleaved 2 of 5 l Matrix 2 of 5 For the properties of other barcode types, see "Barcode type and properties" on page 621. Module width Specifies the width of the narrow bars in centimeters.
PAGE 649

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 650

l Industrial 2 of 5 l Interleaved 2 of 5 l Matrix 2 of 5 For the properties of other barcode types, see "Barcode type and properties" on page 621. 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 None: The barcode is rendered based on the module width.
PAGE 651

Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and will display properly in Email output.
PAGE 652

l Bar width: The width of the bars. l Spacing: The distance between the bars. Scale Defines if and how the rendered barcode is scaled in relation to the parent element: l l None: The barcode is rendered based on the module width. Proportional: The barcode is stretched up to where it fits either the width or height of the parent box, whichever requires the less stretching.
PAGE 653

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... option in the context menu. Note that barcodes of these types don't process tilde characters (~) in the data as special characters. Barcode properties This topic lists the properties of the barcode types Australia Post, Japan Post, KIX and UPS IMb.
PAGE 654

Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and will display properly in Email output.
PAGE 655

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 None: The barcode is rendered based on the module width. l Fit to box: The barcode is stretched to fit the parent box in both width and height.
PAGE 656

l PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and 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 618. 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 619. Initially the barcode will have the barcode type's default properties.
PAGE 657

w3school's color picker). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. MSI MSI is one of the types of barcodes that can be added to a template; see "Barcode" on page 618. 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 619.
PAGE 658

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.
PAGE 659

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 619. 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... option in the context menu. Barcode properties This topic lists the properties of the barcode type PDF417.
PAGE 660

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 None: The barcode is rendered based on the module width. l Fit to box: The barcode is stretched to fit the parent box in both width and height.
PAGE 661

POSTNET POSTNET is one of the barcode types that can be added to a template; see "Barcode" on page 618. 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 619. 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...
PAGE 662

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 group 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 663

Barcode properties This topic lists the properties of the QR barcode. For the properties of other barcode types, see "Barcode type and properties" on page 621. 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.
PAGE 664

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.
PAGE 665

l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format. This has a slightly lower quality than SVG but is usually generated faster and 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.
PAGE 666

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 None: The barcode is rendered based on the module width.
PAGE 667

Royal Mail 4-State (CBC) Royal Mail 4-State (CBC) is one of the types of barcodes that can be added to a template; see "Barcode" on page 618. In PlanetPress Connect versions prior to 2019.2 this barcode was called "Royal Mail 4 State (RM4SCC)". 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 619. Initially the barcode will have the barcode type's default properties.
PAGE 668

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 669

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... option in the context menu. Barcode properties This topic lists the properties of the barcode types Royal Mail 4-State Mailmark C and Royal Mail 4-State Mailmark L. For the properties of other barcode types, see "Barcode type and properties" on page 621.
PAGE 670

When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format. This is usually of higher quality, but may take longer to generate and is not compatible with Email output. PNG: Binary rasterized format.
PAGE 671

Scale Defines if and how the rendered barcode is scaled in relation to the parent element: l l None: The barcode is rendered based on the module width. Proportional: 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.
PAGE 672

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... option in the context menu. Note that these barcode types process tilde characters in the data as special characters. See the Java4less Barcodes Guide to learn what the tilde character can be used for.
PAGE 673

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.
PAGE 674

In PlanetPress Connect versions prior to 2019.2 the USPS IMb barcode was called "OneCode". 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 619. 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...
PAGE 675

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 676

Color The Color group 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). When black is a composite of CMYK or RGB values, it may incur a color click charge on some printers. Check the Output in Grayscale option to make sure that pure black is used. Output format Defines how the barcode is output on the page. There are two possible formats: l l SVG: Vector format.
PAGE 677

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 (see also: "Using the CSS position property" on page 746). 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.
PAGE 678

results.attr('offset-x','96'); results.attr('offset-y','96'); The measurements are in pixels (e.g. 96px = 1in). Note that you do not need to set the units. Note Do not set the top or left property of a Positioned Box in a style sheet. The position of a Positioned Box in a Print context is handled via its attributes to take the page (or Master Page) and page margins into account. Attributes cannot be overwritten from within a style sheet: style sheets specify style properties, not values of attributes.
PAGE 679

l l l 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.
PAGE 680

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 613. In HTML, boxes are
elements. Spans are elements. To learn how to change the attributes of elements, see "Attributes" on page 614. Business graphics Business graphics are a great way to visualize data in your documents.
PAGE 681

Inserting a business graphic The Connect Designer has wizards for adding three kinds of graphics: Pie Charts, Bar Charts and Line Charts. These wizards insert the chart and its accompanying script, after you select the data that should be displayed, their colors and labels, and a few display options. To insert a business graphic in a template: 1. Place the cursor where the graphic should be added. Also make sure that you have loaded data or a data mapping configuration (see "Loading data" on page 773). 2.
PAGE 682

are block level elements - like a Div or a Table. If inserting content at the selected location would produce invalid HTML the final result may be different than expected. For example, when you insert a Div into a paragraph, the paragraph gets split in two. This means you end up with two paragraphs with the Div in between. 5. Click Next and specify the data for the graph. These settings can also be edited when you open the script, after you've inserted the chart.
PAGE 683

Rasterizing a business graphic Business graphics are output as SVG images, but not all clients may support that format. Before generating output, you may want to 'rasterize' it. This converts the business graph into a JPG or PNG image. To rasterize a business graphic, right-click it and select Rasterize Options. For a JPG image you can set the quality of the resulting image in a percentage.
PAGE 684

How-to: Put one slice per detail record in a Pie Chart. 2. For a Bar or Line Chart based on a detail table, you also have to select a Category: one data field (in the detail table) of which the values will appear under the bars or the line; in other words, on the x axis. 3. Next to Values, select data fields with a numerical value. Tip The Toggle non-numeric fields button filters non-numeric fields from the list. The list will then display only Integer, Float and Currency data fields. 4.
PAGE 685

6. Use the Move Up and Move Down buttons to change the order of the fields, which is reflected in the chart. The Preview shows what the chart looks like with the current settings, whilst the Data Preview shows which data will be passed to the amCharts library. Preparing a data table By default, a chart that is based on a detail table shows one series ("category") of bars/points per record. Each of the bars or points in a series has its own color and label, and represents one data field in that record.
PAGE 686

When creating a data mapping configuration (see "Data mapping workflow" on page 219), it is recommended to arrange data in a detail table in such a way that it matches this 'one series per record, one bar/point per data field' approach. Occasionally you may find that data in a detail table does not match this approach, and that it would be a better fit if the chart had one series of bars/points for each selected detail data field instead, and one bar/point for each record.
PAGE 687

Adding and editing properties manually The last tab menu in the Chart Properties dialog, the Source tab, reflects the choices made in the other tabs. More importantly, this tab gives you the possibility to add any amCharts configuration option that is unavailable via the other tab menus. On the Source tab, all settings are given in JSON.
PAGE 688

The Source tab also lets you change properties that are available in either the Script Wizard or other tabs of the Chart Properties dialog. You could, for example, set the colors of the bars, lines or slices by adding an array of hexadecimal color values, like this: "colors": ["#FF6600", "#FCD202", "#B0DE09", "#0D8ECF"] Note that properties defined on the Source tab override those made in the Script Wizard or on other tabs of the Properties dialog.
PAGE 689

2. The 'light' theme requires no other settings. For the other themes you will have to manually set the background color of the Div element that holds the chart: A. Switch to the Design mode. B. Right-click the chart area and select Box... from the contextual menu. C. On the Background tab, set the Color to: l #282828 for the 'dark' theme and the 'chalk' theme l #222222 for the 'black' theme 3. Finally, the 'chalk' theme requires adding a remote stylesheet with this URL: 'https://fonts.googleapis.
PAGE 690

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. To learn how to add Camera data to a template, see "Adding Camera data to the template" on page 556. The Camera element has a number of options, of which most can be set in the Design view.
PAGE 691

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.
PAGE 692

Note The Time stamp feature doesn't work in versions of the app prior to 10.6. How to use the captured or selected image in a template After a user has submitted the form and the data has been extracted, you may want to display the captured or selected image in a Designer template, for example in a letter or on a web page. To do this: 1. Load the data mapping configuration (or at least the data model). 2. Insert a dummy image in the template. 3. Right-click the dummy image and select Dynamic Image.
PAGE 693

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. Document ID The Document ID element retrieves the Document ID of the form currently viewed by the app.
PAGE 694

interface. All options, including those that cannot be set in Design view, can be set via the data-params attribute in the HTML, or in code; see "Using the COTG plugin: cotg2.0.0.js" on page 587. 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.
PAGE 695

Note The Signature data returned by the COTG app (as of Android 10.6.0, iOS 10.6.0, and Windows 6.0) is formatted so that the signature will automatically be scaled to fit in the containing box in a template. With previous versions of the app, the format of returned signatures could vary. 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.
PAGE 696

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.
PAGE 697

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 1275. Note The Locale, set in the Edit > Locale dialog, has an influence on the formatting of a date. The 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 768. Forms Web templates can contain Forms. Capture OnTheGo templates always contain a Form.
PAGE 698

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).
PAGE 699

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 "Adding elements to a Form" on page 540. 9. Double-click each field in the Fields list and change its settings. For an explanation of the settings, see "Adding elements to a Form" on page 540. 10. The order of the elements in the list under Fields determines in which order the elements will be added to the Form.
PAGE 700

12. Close the dialog. Now you can start adding elements to the Form (see "Using Form elements" on page 540, "Form Elements" on page 702, and "COTG Elements" on page 689). Changing a Form's properties and validation method Once a Form has been added, you can of course edit its 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 and validation settings. Changing a Form's properties 1.
PAGE 701

set the maximum length as an additional requirement for some fields. l JQuery Validation validates input using JQuery scripts. This allows for stricter requirements per field and 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 this option is chosen. To change a Form's validation method: 1.
PAGE 702

to use the new attribute values for the data-validation-method attribute of the
element. The JavaScript file web-form-validation.js will not be migrated: delete that file and then change the Form's validation method to jQuery Validation, as described above. When you click OK, the new version of the web-form-validation.js file will be added.
PAGE 703

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.
PAGE 704

If a Checkbox is not checked, no information is sent when the form is submitted. Fortunately, there is a workaround to submit the status of an unchecked checkbox; see "Using Form elements" on page 540. 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.
PAGE 705

To learn how to dynamically add options to a Select element, see this how-to: to Dynamically add options to a dropdown. 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: l l 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 700).
PAGE 706

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 the Designer; see "Editing HTML" on page 613. The HTML tag of a hyperlink or mailto-link is . This is sometimes called an anchor tag. For a list of attributes, see https://www.w3schools.com/tags/tag_a.asp. Adding a hyperlink or mailto link 1. Select text or an image.

PAGE 707

Note An internal hyperlink may point to an element in another section. Just make sure that there is only one element in the document with the specified ID. 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 l l Email: enter a valid email address that appears by default in the To: field of the email client. Subject: type a default subject that appears in the Subject: field of the email client.
PAGE 708

landing page, for example, to download an invoice or get access to specific products or services. For more information, see "Personalized URL" on page 822. Images Images are a powerful ingredient in all of your templates. This topic explains how to add and use them.
PAGE 709

Tip Using images in an Email template? See "Using images in email campaigns: tips" on page 499. Dynamic images 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 799 to find out how to add such switching images. Background images Several parts of templates, such as sections and media, and elements such as positioned boxes, can have a background image.
PAGE 710

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 613. In the section's source file, 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 714.
PAGE 711

Imported images are images that are saved within the template file. To import images into a template and add them to the content, you can use the drag-and-drop method or the Select Image dialog (both are explained below). External images are either located on a specific website (URL), or in a folder on a hard drive that is accessible from your computer.
PAGE 712

l Click Resources, Disk or Url, depending on where the image is located. l l l Resources lists the images that are present in the Images folder on the Resources pane. Disk lists image files that reside in a folder on a hard drive that is accessible from your computer. Click the Browse button to select a folder (or an image in a folder). As an alternative it is possible to enter the path manually. You can give a local path (e.g. C:\Images\Test.jpg) or use the "file" protocol.
PAGE 713

3. If the image is a PDF file that consists of more than one page, select the desired page. Note The number of pages in a PDF file cannot be determined via the HTTP and HTTPS protocols. If you wish to use a page other than page 1 in a remote PDF, check the option Save with template; then click OK and reopen the dialog. Next, on the Resources tab, select the PDF, and select a page. 4. Click Finish. The image will be inserted at the position of the cursor.
PAGE 714

Moving an image An image that is added to a section behaves like a character and is part of the text flow. To move it, simply click the image and drag and drop it somewhere else in the text flow. To learn how to wrap text around it, see "Wrapping text around an image" on page 754. How to make an image stay at a certain position (like any image added to a Master Page) is explained here: "Pulling an image out of the text flow" on page 755.
PAGE 715

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. Using a CSS gradient to create an image CSS gradients are a new type of image added in the CSS3 Image Module. CSS gradients let you display smooth transitions between two or more specified colors, while repeating gradients let you display patterns. This way, using image files for these effects can be avoided, thereby reducing download time and bandwidth usage.

PAGE 716

the Designer; see "Editing HTML" on page 613. 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 , 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 https://www.w3schools.com/html/html_tables.asp.

PAGE 717

l l After element inserts it after the element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be after the end tag of the paragraph (

).* Replace inserts it in place of the currently selected element. (This option is not available when inserting content in a Master Page.) * If the current element is located inside another element, use the Elements drop-down to select which element is used for the insertion location.

PAGE 718

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. If the deleted element was targeted by a script, you will be asked if you want to delete the script as well. Rows and columns Adding a row or column To add a row or column to an existing Table, click in a cell.

PAGE 719

The default_table_styles.css file is read-only, but of course you could overwrite styles and create your own theme, using your own style sheets. Regardless, you can change the font, font size and color, the borders, the cell padding (the distance between the edge of the cell and its content), and the background color or image of the table and its cells, via the Formatting dialog. Both approaches are explained in the topic: "Styling a table" on page 748.

PAGE 720

l l l Click in the Table and then drag the border to move the Table. Select the Table (see "Selecting an element" on page 616) and type the desired values in the Top and Left fields on the Attributes pane. Select the Table and select Format > Table, on the menu. On the Table tab, change the Positioning values. 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 757.

PAGE 721

Extra spaces When you add spaces in Design or Preview mode the editor automatically preserves any extra spaces by converting them to non-breaking spaces (" " in HTML). It does this because in HTML extra spaces are generally removed. Take this into account when you edit the template in Source mode (i.e. in HTML) or add text via a script. This how-to describes another way to maintain extra spaces in the text: Maintain extra spaces in text. Adding special characters To add special characters: 1.

PAGE 722

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 739. In all templates you can use the fonts that are provided with the Designer, as well as imported fonts; see "Fonts" on page 764. Translating text OL Connect templates can be multilingual. For information about multilingual templates and how to create them, see "Translating templates" on page 913.

PAGE 723

var json_data = loadjson("snippets/snippet.json"); results.html(json_data.field1); See also: "Writing your own scripts" on page 853. For an example in which JSON snippets are being used to localize a template, see this how-to: Localizing templates using json. Adding a snippet to the Resources Before adding a snippet: l l Import the resource files that are related to the snippet, such as image files and CSS files, into the template file.

PAGE 724

resources referred to with a relative path (for example: images/img.gif) or root-relative path (any path starting with a slash, for example: /base/images/img.gif) won't be available in the template. Adding a snippet to a section Drag-and-drop To add the snippet to the content of a section, drag the snippet from the Snippets folder on the Resources pane to the desired location in a section.

PAGE 725

Editing a snippet To edit a snippet, open the snippet file by double-clicking it on the Resources pane. By default, a snippet that is being used as shared content can also be modified in a section where it is used. That way you actually adjust its source. The snippet will be changed at all locations where it is used. The option to modify shared content snippets from within a section can be turned off: l l In the menu, select View > Shared Content Editing to enable or disable editing of all shared content.

PAGE 726

Translating a snippet Snippets in a multilingual template get translated at the moment they are inserted in the output, if the text is tagged for translation. For more information see "Translating templates" on page 913 and "Tagging text in snippets" on page 917. Styling and formatting In the Designer you have everything at hand to make your templates look good: colors, fonts and all the tools to position, align and embellish elements in your designs. This topic informs about the ways to style a template.

PAGE 727

Layout properties Colors and fonts make an important contribution to the look and feel of your template. See "Colors" on page 760 and "Fonts" on page 764. Text and paragraphs have a number of formatting options that are not available for other elements: font styles and line height, for example. See "Styling text and paragraphs" on page 739. Boxes and a number of other elements can have a background color and/or background image; see "Background color and/or image" on page 756.

PAGE 728

Cascading Style Sheets were originally designed for use with web pages, or HTML files. Since every template in the Designer is constructed in HTML, CSS files can also be used in the Designer. Instead of setting the font size, line height, color etc. for each and every paragraph in the template itself, you can define a layout for all paragraphs, and for all output channels, in a CSS file.

PAGE 729

in Print output, obviously. Included Cascading Style Sheets When you create a template, a number of style sheets is automatically included: l l l One style sheet that applies to all document types: context_all_styles.css. One or more style sheets specific to the context (Print, Email, Web). For example, when you create an action email using the Wizard, the files context_htmlemail_styles.ccs and basic_email_action.css are automatically added to the Stylesheets folder on the Resources pane.

PAGE 730

Note The order in which style sheets are executed, can affect the actual output. This sequence can be set per section; see "Applying a style sheet to a section" on page 452. Tip l l To export a CSS file from your template, drag or copy/paste it out of the Stylesheets folder to a folder on the local hard drive. It is possible to open and edit any CSS file in the Designer: select File > Open, select All files (*.*) as the file type and then select a CSS file.

PAGE 731

example: a folder location on a corporate website, hosted by a CDN (Content Delivery Network) or shared via a Workflow process. Tip After adding the remote file, you may right-click it and select Download Resource. This allows you to maintain a central file, from which you can quickly download a copy to your template without having to copy & paste. Note that a local copy of a remote resource is a snapshot; it is not automatically kept in sync with its remote content.

PAGE 732

Styling your templates with CSS files Note Email clients do not read CSS files and some even remove a

tag. A table row can also be divided into table headings with the	tag. The tags