User Guide Version 2020.2.1 Last Revision: 2021-06-03 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.
Table of Contents Table of Contents 4 Welcome to PReS Connect 2021.
General information 134 Connect: a peek under the hood The Workflow server 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 134 135 136 137 137 138 138 139 139 140 140 141 143 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
Opening a data mapping configuration Saving a data mapping configuration Down-saving a data mapping configuration Using the wizard for CSV and Excel files Using the wizard for databases Using the wizard for JSON files 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 C
The Designer Designer basics Features Templates Contexts 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 t
COTG Elements Using COTG Elements Testing a Capture OnTheGo Template Using the COTG plugin Dynamically adding COTG widgets Saving and restoring custom data and widgets 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 charac
Styling templates with CSS files Styling text and paragraphs How to position elements Rotating elements Styling a table Styling an image 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 Perso
Hardware for Digital Signing preferences Language preferences Logging preferences Parallel Processing preferences Print preferences Project Wizards preferences 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
Print options Job Creation Presets Wizard Output Creation Presets Wizard Designer Script API Standard Script API Control Script API Post Pagination Script API Generating output 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 P
Optimizing a template Scripts Images Runtime parameters Print Manager 1503 1503 1504 1505 1506 Print Manager Introduction Video Print Manager usage Print Manager Interface Menu options Printers pane Printer Queue pane Job Queue pane Messages pane Job History pane Printer Capabilities pane Printer Status pane Print Manager Preferences PReS Connect Release Notes 1506 1506 1507 1507 1508 1515 1524 1526 1527 1529 1529 1531 1541 OL PReS Connect Release Notes 2021.
Connect 2019.2 Designer Improvements Connect 2019.2 DataMapping Improvements Connect 2019.2 Output Improvements Print Manager Improvements Workflow 2019.2 Improvements Known Issues License Update Required for Upgrade to Connect 2019.1 Overview OL Connect 2019.1 Enhancements Connect 2019.1 Designer Updates Connect 2019.1 DataMapping Updates Connect 2019.1 Output updates Print Wizard and Preset Wizard Improvements Workflow 2019.1 Updates Known Issues Overview Connect 2018.2.1 Enhancements/Fixes Connect 2018.
Connect 2018.1 Print Manager Enhancements/Fixes Workflow 2018.1 Enhancements/Fixes Known Issues Overview Connect 1.8 General Enhancements and Fixes Connect 1.8 Performance Related Enhancements and Fixes Connect 1.8 Designer Enhancements and Fixes Connect 1.8 DataMapping Enhancements and Fixes Connect 1.8 Output Enhancements and Fixes Connect 1.8 Print Manager Enhancements and Fixes Capture OnTheGo (COTG) Enhancements and Fixes Workflow 8.8 Enhancements and Fixes Known Issues Overview Connect 1.7.
Connect 1.4.1 New Features and Enhancements Connect 1.4.1 Designer Enhancements and Fixes Connect 1.4.1 DataMapping Enhancements and Fixes Connect 1.4.1 Output Enhancements and Fixes Connect 8.4.
Welcome to PReS Connect 2021.1 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. PReS 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.
Setup And Configuration This chapter describes the PReS Connect installation and the different considerations that are important in regards to the installation and use of PReS Connect. l "System and Hardware Considerations" below l "Installation and Activation" on page 35 l "Known Issues" on page 119 l "Server Configuration Settings" on page 93 l "Uninstalling" on page 131 System and Hardware Considerations There are a variety of considerations to be aware of.
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.
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.
Database Considerations This page describes the different considerations and pre-requisites for the database back-end used by PReS Connect, whether using the MySQL instance provided by the installer, or preexisting (external) instance. Using the MySQL Instance from the Installer The MySQL Instance provided in the "Installation Wizard" on page 40is already pre-configured with options to provide the most stable back-end setup. These are the specific options that have been changed in our version of "my.
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 setting up 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.
Note Since PReS Connect version 1.6 the minimum required version of the MS SQL 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.
If the user has installed the Installer Supplied MySQL and then switches to an external Microsoft SQL by using the Server Configuration Tool, the supplied MySQL cannot be switched off. By design the installer adds a service dependency between Connect Server and the 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.
done as outlined above. 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.
on the server where PReS Connect is located, unexpected behaviours may occur and will not be supported by Objectif Lune Inc.. Furthermore, using PReS Connect in a Terminal Service environment is an infringement of our End-User License Agreement. Virtual Machine Support PReS 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.
encountered, please contact OL Support and we will investigate. PReS Connect 1.3 and later have been certified under Remote Desktop. 32-bit or 64-bit Operating Systems? PReS 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 PReS Connect. Please see "Antivirus Exclusions" on page 17 for more information.
The protection of the end user’s system is one of our main goals and therefore we have implemented a very strict verification mechanism, which ensures, that only these whitelisted ini entries and 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”.
Network Considerations The following should be taken into consideration in regards to network settings and communications l If a local proxy is configured (in the Internet Explorer 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.
Listens on port # LPR LPD Telnet FTP Input/Output MySQL Microsoft SQL Server HyperSQL 3306 Destination Type port # 515 TCP TCP TCP 21 TCP TCP+UDP 1433 TCP+UDP 9001 TCP 515 9100 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.
C:\Users\[username]\Connect\logs\WeaverEngine, where [username] is your own Windows user name. Search the log file for "PPM" (pages per minute). Repeat this a few times to determine the 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".
Note Connect Server and Connect Designer each have their own distinct scheduling 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 1503.
Connect Server and the Connect database need 1GB each, and that each engine needs 1GB as well, you can roughly estimate how much memory is needed. 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.
Virtual Environments l VMWare/VSphere l Hyper-V (8.0) 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.
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.
Installation and Activation This topic provides detailed information about the installation and activation of PReS Connect 2021.1. Note A PDF version of this guide is available for use in offline installations. Click here to download it. PReS Connect 2021.1 is comprised of 2 different installers: one for the PReS Connect software and one for PReS Workflow 2021.1. Where to obtain the installers The installers for PReS Connect 2021.1 and PReS Workflow 2021.
Installation - "How to" guides For information on how to conduct the installation itself, choose from the following topics: l "Installation Wizard" on page 40 l "Running Connect installer in Silent Mode" on page 51 l "Installing PReS Connect on Machines without Internet Access" on page 38 Activation For information on licensing, please see "Activating a License" on page 60. Installation prerequisites l l l l l l Make sure your system meets the "System requirements" on page 32.
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.
l In the Connection tab, define the account name and password that the service should use. This can be a local account on the computer or an account on a Windows Domain. The account must have administrative access on the machine. It should also correspond to the user account set up in PReS Worfklow. OL Connect Server user accounts By default, authentication is enabled on the Connect Server.
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.
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 PReS Connect to 2021.1 from Connect versions prior to 2019.1 it is first necessary to update the Connect License.
l PReS_Connect_Setup_x64.exe --verbose This adds extra debugging style logging to the installation process. l PReS_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 PReS Connect can be selected for installation.
this documentation) could be used instead, for the same purposes. The external database could reside on the same computer or on a separate server. If you wish to make use of an external database, please make sure the MySQL option is not selected. Warning If you chose not to install the supplied MySQL database, and instead opt for using a pre-existing (External) database then you yourself must ensure that the External database is accessible to Connect. Objectif Lune Inc.
characters that Windows disallows in filenames (such as '?', ''>' or trailing spaces). If an invalid character is entered, the Installation Path entry box will turn red and a description of the error will be displayed in the information area. The installer can also calculate how much disk space is required for installing the selected components as well as how much space is available: l l l l Disk space required: Displays the amount of space required on the disk by the selected components.
l a numeric digit (1, 2, 3 ...) l a punctuation character (@, $, ~ ...) For example: "This1s@K" Note When updating from an earlier Connect version, the appropriate MySQL password must be entered or the update will fail. If the password is subsequently forgotten, then MySQL must be uninstalled and its database deleted from disk before attempting to reinstall. l l Confirm MySQL user 'root' Password: Re-enter to confirm the password. Both passwords must match for installation to continue.
Tip This option may represent a security risk if the machine is open to the internet. We heavily recommended that your firewall is set to block access to port 3306 from external requests. Configuring External Database Connection The Database Connection page appears if the supplied MySQL module was not selected for installation. This page is for setting up the connection to the existing External database. l l l l l l Database Configuration: Select the database type to use for thePReS Connect Engine.
l l Administrator Password: Enter the password for the above user account. For MySQL the appropriate password must be entered or the Connect installation will fail. Use Encrypted SSL Connection checkbox: Check to enable encrypted connections to MySQL (v5.6.43, v5.7.25, v8.0.x or later) databases using SSL. The secure connection to MySQL is for the "objectiflune" schema. Note It is not in the scope of the Connect installer to configure the MySQL database Server to accept SSL connections.
Connect Server (Master) settings The Connect Server (Master) settings will be available if Connect Server rather than Connect Server Extension was selected for installation. The options available are as follows: l Run Server as: Defines the machine username and password that the Connect Server module's service uses. Note The user account must have access rights to all local and network resources required for production, as well as Windows "Log on as a Service" rights.
Note that prior to PReS Connect version 2020.2, only one user account could be configured on a Connect Server. The default username was ol-admin and the default password was secret. When updating to version 2020.2 this user account is not changed. It is however highly recommended to modify the default password at least.
both servers. l l Password: The password associated with the selected user. Validate User button: Click to confirm that the username/password combination is correct. Note This button must be clicked and the user validated before the Next button becomes available. l Master Server Connection (Default Settings): l Hostname: Enter the machine name or IP Address where the Connect Master Server resides. There is no requirement for the Master and Extension servers to belong to the same IP subnet.
Selection Confirmation This page confirms the installation selections made. Click Next to start the installation itself. This process can take several minutes. Completing the installation This screen describes a summary of the components that have been installed. l l l Configure Update Check checkbox: This option is enabled by default. It causes the Product Update Manager to run after the installation is complete. This allows configuring PReS Connect to regularly check for entitled updates.
l l Note that the Product Update Manager can also be called from the “Objectif Lune Update Manager” option in the Start menu. It can be uninstalled via Control Panel | Programs | Programs and Features. Product Activation After installation, it is necessary to activate the software. See "Activating a License" on page 60 for more information. Before activating the software, please wait 5 minutes for the database to initialize.
l l Comment Lines, starting with # (e.g. # The options to configure an external database) Key = Value pairs (e.g. install.product.0 = Connect Designer) For supported keys, please refer to the next paragraph. Note The install.properties file notation must follow commons configuration rules. Please refer to Properties files for more details. Required and optional properties Required properties depend on the specified product. Only fields related to that specified product must be entered.
Verbose logging (optional) By default, the Silent Installer will log the same way as the GUI installer. That means logging of error and warnings, and certain information during database configuration. A more verbose logging can be switched on by using logging.verbose = true. Product selection (optional) By default, if nothing is entered for the products to be installed (install.product), Silent Installer will install all products which are visible to the user for the respective brand.
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. Server configuration (required if Server is selected for install) For Server, the following properties need to be provided: server.runas.username = server.runas.
Note The unlocked option should only be used when the database requires an external access. If the Silent Installer runs with the default product selection, MySQL is included, and hence the database.unlocked = true property may be optionally set if MySQL on this machine is intended to serve as the central database also for remote machines. If the Silent Installer runs with the explicit installation of a stand-alone (install.product.0 = Connect Server), the database.unlocked property is irrelevant.
database.schema = (default value is objectiflune, optional) database.usessl = true/false (select whether to deploy using a secure database connection (SSL)or not) 2b: Configuring an external Microsoft SQL Server database Note Since PReS Connect version 1.6 the minimum required version of the MS SQL Server is SQL Server 2012. To configure an external Microsoft SQL Server database, the following properties should be defined: database.type = Microsoft SQL Server (required) database.
Repository selection The Connect installation process requires a repository from which the installer copies (locally) or downloads (online installation) all selected Connect products. In Silent Installer mode, the installation process looks for the property product.repository in the install.properties file and then proceeds with the following steps: 1. If the property exists, and its value contains an existing file location with a repository, the installer will attempt to install from that repository. 2.
l en-US (English, US) l de-DE (German, Germany) l fr-FR (French, France) l ja-JP (Japanese, Japan) l zh-CN (Chinese, China) l zh-HK (Chinese, Hongkong) l zh-MO (Chinese, Macau) l zh-TW (Chinese, Taiwan) l it-IT (Italian, Italy) l pt-BR (Portuguese, Brazil) l es-419 (Spanish, Latin America) Locale selection by defining user.language and user.country If both user.language and user.country are defined in the install.
1. If the System Locale is in the list of supported Locales, it will be selected. 2. Otherwise, if there is an entry in the list of supported Locales, which matches the System language, it will be selected (e.g. on a fr-CA system, fr-FR is selected). 3. As last resort, the first Locale in the preinstall.ini is selected (usually that should be enUS). Getting the exit code of a silent installation If getting the exit code of a silent installation is desirable, use the following procedure. 1.
if errorlevel 1 goto err_preinstall echo Success goto:eof :err_installer echo "Installer error - see OL_Install_.log" goto:eof :err_unknown echo "Unknown preinstall error - see preinstall_err.log" goto:eof :err_preinstall echo "Preinstall error - see preinstall_err.log" goto:eof Activating a License PReS Connect and PReS 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.
l License Information subsection: l l l Magic Number: Displays the PReS Connect Magic Number. Copy the magic number to the clipboard: Click to copy the Magic Number to the clipboard. It can then be pasted in the activation request email using the Windows CTRL+V keyboard shortcut. Licensed Products subsection: l Name: Displays the name of the application or module relevant to this activation. The Information button or module license.
team will then send the PReS Connect license file via email. l Resellers can create an evaluation license via the Objectif Lune Partner Portal by following the instructions there: http://extranet.objectiflune.com/ Note that if you do not have a serial number, one will be issued to you by the OL Activations team. Accepting the license will activate it, after which the PReS Connect services will need to be restarted. Note that in some case the service may not restart on its own.
l Click Install License to activate the license. The license will then be registered on the computer and you will be able to start using the software. Warning After installation message will appear warning that the Server services will need to be restarted. Just click OK to proceed. Migrating to a new workstation The purpose of this document is to provide a strategy for transferring a OL Connect (and/or Workflow) installation to a new workstation.
Backing up files from the current workstation The first step in migrating to a new workstation would be to make sure all necessary production files and resources are backed up and copied over to the new system. Note Although it is not necessary to convert all of your documents when upgrading to the latest version, we strongly recommended doing so. It is considered "Best Practice" to convert the documents to the version installed and then re-send them to the Workflow Tools.
3. Click on the down pointing triangle under the Uncategorized group. 4. Select Import Plug-in and select the .dll file. l l l l l l l Import any external scripts used by the Run Script plugin, making sure they reflect the same paths as on the previous workstation Install any external application, executable and configuration files used by the External Program plugin, making sure they reflect the same paths as on the previous workstation Reconfigure local ODBC connections (i.e.
l l Reconfigure each of the plugins, where necessary, under Plug-in as previously. Capture OnTheGo users may want to enable the Use PHP Arrays option under Plug-in > HTTP Server Input 1. Send the configuration to the local Workflow service. 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 (.
l l l l OL Connect Designer Templates, DataMapper or Package files, copied from the folder where they reside. 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.
the PlanetPress Capture options under Behavior >PlanetPress Capture > Use ODBC Database. 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.
1. Stop the OLConnect_ServerExtension service from Control Panel > Administrative Tools > Services > OLConnect_ServerExtension > Stop. 2. Open the Server Extension Configuration from: C:\Program Files\Objectif Lune\OL Connect\Connect Server Extension\ServerExtension.exe 3. Click on Database Connection and configure the JDBC Database connection settings so that the hostname points to the new Master Server. 4. Click on Scheduling and type in the location of the new Master Server. 5.
4. Start the Software Activation module on the Extension servers, where applicable. 5. Click on Load License File to import the above same license.OLConnectLicense. 6. Restart the OLConnect_Server service and restart the OLConnectServer_Extension service on the Extension servers, where applicable. 7. The number of Expected Remote Merge and Weaver engines should now be configurable in the Connect Server Configuration module (C:\Program Files\Objectif Lune\OL Connect\Connect Server Configuration\ServerConfig.
l l l l l If both versions need to be hosted on the same machine, PReS Workflow 2021.1 must always be installed after the legacy PlanetPress® Suite 7.x installation. When uninstalling PReS Workflow 2021.1, you may be prompted to repair your legacy PlanetPress® Suite 7.x installation. If PReS Workflow 2021.1 has been installed alongside PlanetPress® Suite 7, Capture can no longer be used with Workflow 7. The plugins are now registered uniquely to Workflow 2021.
For instructions on how to do so, please see "Backup existing Connect version" on the next page. Note The scheduling settings were changed significantly in version 2019.2. Please make sure to record your current scheduling settings for reference before proceeding with an upgrade. Users of Connect prior to 2019.1 Users of Connect 1.1 should see "Users of Connect 1.1" on the next page first. Users of all other Connect versions prior to 2019.1 should note that Update Client 1.2.
Connect's Knowledge Base (https://help.objectiflune.com/en/kbconnect/#KB/FAQ/OL%20Connect/KB2002.htm). Users of Connect 1.1 In order for users of PReS Connect 1.1 to upgrade to any later version through the Update Manager it is necessary to install a later version (1.1.8 or later) of the Objectif Lune Update Client. If you do not have such a version installed already, the next time you run your Update Client it will show that there is an update available of itself to Version 1.1.8 (or later).
Backing up a real machine Note The scheduling settings in version 2019.2 have totally changed, making it impossible to revert these settings back to the previous version. Please make sure to record your 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\workspa
If the default MySQL database is being used as the Connect back-end database, we would recommend the MySQLDump tool be used for this. See for details on this utility program: mysqldump (https://dev.mysql.com/doc/refman/5.7/en/mysqldump.html). Upgrading from PReS Classic PReS Classic and PReS Connect are very different products. Whilst PReS Connect provides considerably more options for email and web output, one need not abandon existing PReS Classic print jobs.
l Imaging for PReS Connect is available as an option. It contains: l PReS Fax l PReS Image l PReS 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 PReS Workflow 2021.1 but only with documents created with the PlanetPress Suite Design 7. PReS Connect Designer. This is a design tool based on completely new technology.
PReS Connect installation considerations The PlanetPress Suite could run on a computer with a minimum of only 1GB of RAM available. The PReS Connect Server with PReS Workflow 2021.1, by default, requires 8GB of RAM, but if you intend on using the new PReS Connect Designer on the same computer, you should consider having at least 16GB of RAM available. See "System requirements" on page 32.
Note If you were a PlanetPress Production user, you retain all functionalities within PReS Workflow 2021.1. These are automatically imported during the activation (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 PReS Connect Designer right away by designing new documents, or re-doing existing ones at your own pace.
.NET 3.5 is not included in the Workflow setup. 4. If you installed PReS Workflow 2021.
7.
8. Then select the product from which you wish to upgrade: 9.
10.
11. After that you will need to get the activation file for your product. To obtain your activation, download the PReS 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.
How to perform a Workflow migration What do you need to consider when upgrading from PlanetPress Suite 7 to PReS Connect Workflow 2021.1 on a new computer? Installing and Activating Workflow 2021.1 on a new computer Points to consider: l l l l Before installing, be sure to read "Installation and Activation" on page 35. There you will find detailed Connect Workflow installation steps as well as system requirements, notes on license activation and much more.
l l Login to our Web Activation Manager (www.objectiflune.com/activations) using your customer number and password to get your Printer Activation Codes. If you do not have access to the computer in which PlanetPress Suite was previously installed, print a Status Page for each printer from your Connect Workflow 8 Configuration. Do this via the Tools > Printer Utilities menu option. Select “Print Status Page” and then select your printers from the list. Email the Status Page(s) to activations@ca.
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 PReS Connect Workflow 8 folder will be "C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Documents" 3. Use the File > Send To menu option in PlanetPress Suite Designer and select the PReS Connect Workflow 8 to which you want to send the PlanetPress Suite Designer document.
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. Missing plug-ins will be represented in Workflow steps through the use of a "?" icon. Such as in the following image, which shows that the "TelescopingSortPlugin" is not installed.
l l l l 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 Lune\PlanetPress Suite 7\PSRIP" and paste them onto the new computer here: "C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PSRIP". Make sure to set the user who will run the PlanetPress Services.
page 84. Failure to do so will result in unexpected problems. Note It is recommended that you first update your PlanetPress Suite to version 7.6 before cross-grading to PReS Connect. Using PReS Connect Workflow 2021.1 on the same computer as PlanetPress Suite 7.6 Steps to migrate: 1. Update existing installation to PlanetPress Suite version 7.6 if not already done. 2. Install PReS Connect Workflow 2021.1 on the same computer. 3. Do the following for both PlanetPress Suite version 7.
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:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\DocumentManager". 6.
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 PReS Connect Workflow 2021.1 on new computer. 3. The Anoto PenDirector must be installed. It if is not, you can download it from http://www.objectiflune.com/OL/lib/Common/Downloads/PlanetPressCaptureResources/ AnotoPenDirector.
Note These steps must be done for both PlanetPress Suite Workflow 7 and PReS 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 PReS Connect Workflow 2021.1 computer: "C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\capture" and overwrite the existing database. Note Prior to PlanetPress Suite 7.
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 PReS Connect Server. In PReS Connect you can install Servers on multiple machines, in a Master/Slave relationship. To see an overview of these Master/Slave setups, please see the "Server Clustering" on page 116 topic.
l Engines preferences l "Automatic Restart Settings" on page 107 (not available in Server Extension (Slave) installations) Note Automatic Restarts are controlled by the main server. Slaves are treated the same as local engines in regards to restart timing.
Connection settings (standalone/Master) l REST Services group. Use this to adjust the HTTP or HTTPS communication settings for Connect. l l Port: Set the primary HTTP or HTTPS Server connection port number for Connect. Protocol: Select whether to use HTTP or HTTPS. If HTTPS is selected, the following HTTPS specific options become available: l l l l l Root certificate: This is an optional selection. Use the Browse button to locate the appropriate root certificate file, if one is available.
Note Please note that local security settings (including firewalls) must be taken into consideration when setting Port entries. l l l IPC Port: Set the internal connection port number. This cannot be the same at the primary REST Services port number. REST Port: Set the internal REST connection port number. This cannot be the same at the primary REST Services port, or the IPC Port. Advanced group l l l Maximum threads: Sets the maximum number of HTTP threads for processing requests.
l l l l Password: Enter the password associated with selected username. Initial retry interval (secs): The retry interval when initially trying to connect (or reconnect) to the PReS Connect Master server. Prolonged retry interval (secs): The retry interval for trying to connect (or reconnect) to the PReS Connect Master server after the initial retry limit period has been exceeded. Initial retry limit (mins): How long the initial connection (or reconnection) attempts should run for.
user must be entered in any remote Connect Designer that links to this Server. See the "Connect Servers preferences" on page 872 sub-section of the Designer Preferences dialog. - When disabled, a username and password is not required to make REST request, and tasks in PReS Workflow do not require them in the Proxy tab. Nor would a username and password be required on any remote Connect Designer that links to this Server.
Engine configuration The Connect Server cooperates with different engines to handle specific tasks. A DataMapper engine extracts data from a data file. A Merge engine merges the template and the data to create Email and Web output, or to create an intermediary file for Printed output. The intermediary file is in turn used by a Weaver engine to prepare the Print output. (For more information see: "Connect: a peek under the hood" on page 134).
This topic explains all of these settings and the principles behind them, and it provides guidelines for letting the Server manage the workload in such a way as to achieve the highest possible output speeds. Factors to take into account are: l l l Your licence, which imposes a speed quota (see "Speed quota: Pages Per Minute" below). The processing power of your machine. How many cores it has determines how many engines can be launched (see "Launching multiple engines" on the next page).
l l l Weaver engines always require a Licensed task to run. Merge engines only require a Licensed task when creating Email or Web output. Merge engines involved in a Print process don't need a Licensed task in order to run. DataMapper engines don't need Licensed tasks. 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.
cores, Windows Task Manager will show 4 cores and 8 logical processors on its performance tab. On a CPU like this, 5 or 6 engines can be configured to run in parallel. To configure the number of engines: 1. Open the Connect Server Configuration utility tool (see "Server Configuration Settings" on page 93). 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.
The Connect MySQL database needs a fast storage system (SSD or other fast devices) to be able to keep up with two or more DataMapper engines. 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.
Depending on the answers to these questions, you can allocate processing power to jobs in order to run them as fast as possible, and/or in the order of your preference. 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.
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 machines or even cores (see "Memory per engine" on page 103).
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 104). 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. By specifying target speeds for simultaneous Print jobs of a certain size.
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.
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.
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.
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.
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.
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.
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. Note Currently, it’s only the print and PDF content creation tasks that use multiple Merge engines. l Reserve engines for on demand tasks group checkbox: Reassigning engines is not instantaneous when a new task arrives.
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. Licensed tasks limit: This read only entry shows the current license task (or job) limitations. Note The terms "job" and "task" can be used interchangeably.
target speed for small jobs, this will automatically allow more for the large and medium jobs. l l 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. This is the Total engine count, minus the number of engines assigned to both Small and Medium jobs. To change this value, you must update the total amount of Weaver Engines in the Engines preferences page.
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. n The target speed is not a guaranteed actual speed, but a speed limit that the engine is allowed to exceed in order to utilize the licensed speed. n When changing the target speed, don’t be overly precise, you are unlikely to get that exact value anyway.
Quick Howto 1. Install the Master server (PReS Connect Server module), making sure to select the MySQL module. 2. Grant access to the MySQL root user for the appropriate IP range on the Master server. 3. Restart the MySQL Service on the Master server. 4. Install Slave servers (PReS Connect Server Extension module). 5. Install the license on the Master server (a Performance Pack license is required). 6. Set the preferences for the engines (see "Engine configuration" on page 99) on both the Master and Slaves.
Note Navigate to the folder, SHIFT+Right-click and select "Open a command prompt here" l Type in the following command to connect to the database, where is your MySQL password. (This password is the MySQL root password entered as part of Connect installation process. It had to be at least 8 characters long and contain mixed case characters, numeric digits and a punctuation character): mysql --user=root --password= objectiflune You should see the prompt become mysql>.
l Only the machine where the MySQL Server product is installed should attempt to clean-up database items. Essentially servers that do not have MySQL should only run Orphan File Clean-up. Known Issues This page lists important information about issues that apply to PReS Connect 2021.1. Issues running Connect on Hyper-V 9.0 Some customers have reported difficulties running OL Connect on Hyper-V version 9.0.
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.2, and such pages are no longer considered empty. This could impact on the output from existing templates.
The license update introduced in OL Connect 2019.1 does not cater for existing AFP input licenses AFP Input is an add on option for OL Connect licenses. Unfortunately, the update to the 2019.1 version of the OL Connect license does not cater for existing AFP input licenses. If you have an existing AFP input license we ask that you contact your local Customer Care team after the initial license update is complete and have them add the AFP input option back into your license. (See (https://www.objectiflune.
Issue with image placement in 2019.1 when using some customized AFP and IPDS Printer Definitions An issue with image placement in Connect 2019.1 AFP and IPDS output was discovered just prior to the release. The issue is specific to AFP and IPDS 600 DPI Printer Definitions that are not set to "Scale to Fit". As "Scale to Fit" is now switched on by default in all standard Connect 2019.1 AFP and IPDS Printer Definitions, none of those should encounter the issue.
If using MS-SQL, you can run the following command in a query window: set @a=null,@c=null,@b=concat("show tables where",ifnull(concat(" `Tables_in_",database(),"` like '",@c,"' and"),'')," (@a:=concat_ws (',',@a,`Tables_in_",database(),"`))"); Prepare `bd` from @b; 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_upd
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 PReS Connect 2018.2 this is no longer allowed. When upgrading to PReS 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.
Pie charts l Default colors: The default colors (used when no pie chart colors are specified) have changed. Line and Bar charts l Legend label: In previous versions, the name for a values series (needed for the legend) could only be taken from a field outside the detail table. The value of the selected field would be used. Setting a different label required expanding the chart script. After conversion, the name of the field is used instead of the value.
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. However this update also introduced a limit of 100MBs for image files included within a single job.
all Designers, Server and Server Extensions except one, set the clean-up of the database entities to run every 100 months and disable the clean-up for any Designer which also has a Server or Server Extension on that machine. Note that if the Designer is a stand-alone then it is not connected to the central database for clean-up purposes. The Database Petitioning option can be found in the "Clean-up Service preferences" on page 848, see https://help.objectiflune.com/en/PReS-connect-user-guide/2021.
Only one of the above language tags should be selected. Once saved, Connect will appear in the selected language at next start-up. GoDaddy certificates When installing Connect offline, dialogs allow installing the GoDaddy certificates. Most users should use the default settings and click Next. In some cases, however, this may not work correctly.
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.
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.
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.
To uninstall PReS Connect select the application from within the Add/Remove programs option under the Control Panel. This will start the PReS Connect Setup Wizard in uninstall mode. Note The PReS Connect Setup Wizard might take some seconds to appear. Important: Stop any active Anti-Virus software before uninstalling Connect. Some anti-virus systems are known to block the uninstallation of MySQL datafiles, as well as blocking the uninstallation of the MySQL database application itself.
l l Backup Connect Workspace Data for all specified Users: Check this box to backup the Workspace data for the specified users (as previously determined) into a compressed ZIP file (whose location can be customized), before deletion of the full Workspace data. Delete MySQL objectlune Data: Check this box to delete the MySQL database installed with PReS Connect.
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 139. For a list of all file types used in Connect, see: "Connect file types" on page 141.
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.
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.
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 20).
The engines DataMapper engines. 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 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 29). Weaver engines.
Printing and emailing from the Designer To print or send email from within the Designer, the PReS 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 PReS 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.
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.
l l The Designer's logging preferences are set via the Designer; see: "Logging preferences" on page 865. The Connect Server's settings are maintained by the Connect Server Configuration utility tool; see "Server Configuration Settings" on page 93. 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 1064).
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 987.) .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 787) or selfwritten (see "Writing your own scripts" on page 875).
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 134). Typically, an OL Connect project aims at automating (part of) a company's communication with its customers, suppliers, or other parties.
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 1000 in the online help or the Project Wizards overview video on the OL Learn website.
Tip The Designer can send templates, data mapping configurations and print presets to a Connect Server; see "Sending files to Connect Server or to another server" on page 454. 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.
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 168.) The Workflow process implements the typical Print plugins (see "Print processes with OL Connect tasks" on page 193). 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 181.) Submitting data with webforms.
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.
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.
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 539. All scripts are listed on the Scripts pane. You can double-click to open them.
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.
'.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 263.) In this case, the variable holds the project's path. The order number in the path is extracted from the sample data. Note In order to use the value of a Workflow variable - an 'Automation variable' - as a property in the Preprocessor step, the property and the Workflow variable must have the exact same name.
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). This task writes the job file to a file, which can then be used as sample data file when creating a data mapping configuration and debugging the Workflow process. 3.
Tip The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both. Once the template is ready, send it to Workflow (see "Sending files to Workflow" on page 453). Finally, in Workflow, adjust the process: double-click the Create Email Content task to open it, and select the new template.
The Workspace folder is used for debugging or running the solution. It has an In folder that may be used to monitor incoming data and an Out folder to write output files to. The selected folder's path is saved to a global variable in the Workflow configuration (see "The Workflow configuration" on page 157). You also need to enter the host. This address will be used by the COTG app to download forms and submit data to the OL Connect Workflow service.
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. Select the cotg_ts_deploy_form process, open the Debug ribbon and click Run to execute the process. This deploys a number of forms to the COTG account entered in the Wizard.
elements as well as COTG elements (see "Form Elements" on page 719 and "COTG Elements" on page 707). The template was started with the Time Sheet Wizard (see "Capture OnTheGo template wizards" on page 580), which also provides the necessary JavaScript files and style sheets. Most of the scripts are simple Text Scripts (see "Using the Text Script Wizard" on page 807). They put data in one of the form's fields, selecting the field by its ID.
The data mapping configurations This project has two data mapping configurations, made with "The DataMapper" on page 203. To open one of them, select File > Open from the menu in the Designer and browse to the Configurations\Resources folder. COTG Timesheet Form The COTG Timesheet Form data mapping configuration is designed to extract data from the sample data file (Sample Data.xml).
Subsequently, the Metadata Sequencer task creates a loop; the rest of the process is performed as many times as there are records in the Metadata, for one record at a time: l l l l The Set Job Infos and Variables task reads data from the (current record in the) Metadata and puts them into variables. The Create Web Content task merges the record with the COTG Timesheet Form template.
Customizing the project A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project. Do you intend to expand the project into a solution where Workflow runs on a different machine that also has a different regional setting? Then indicate the desired encoding in the Designer preferences (see "Project Wizard deployment settings" on page 869) before installing the project.
The Send to Folder step will now write the input data - the job file - to a file in the Workspace\Debug folder. When you select the file as sample file (on the Debug ribbon), it can be used to debug the process. Tip The saved file can be used to create a data mapping configuration. The report Using different data in the report requires changing the COTG Timesheet Report template (see "Personalizing content" on page 787).
Workflow configuration To transform the project into a real solution, the Workflow configuration has to be adapted in two important respects. l l The timing and manner of the production of forms will need to change. The Input task of the cotg_ts_deploy_form process must be adapted to the actual input data. You will also need to create an appropriate data mapping configuration for that data, which probably means saving the input as sample data first (see "Saving input as sample data" on page 159).
Installing the project Select File > New > Project Wizards > Print Promotional Jobs from the menu to start the Print Promotional Jobs Project Wizard. (See also: "Promotional Print Jobs - Project Wizard" on page 1004.) 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 Debug mode, the first Input task is skipped and the process is executed using a sample data file. This project is pre-configured to use the file: Sample Data.xml. A successful test run results in a subfolder in the Workspace\Out folder, named after the current month and year. The Print output is written to that subfolder. It consists of one file that should have the proper file extension.
l l l The year script changes the year in the conditional paragraph to the current year. This script only has to look for @year@ in an element that has the ID 'promo', instead of in the entire letter, which makes it run faster. The Dynamic Signature script switches the signature, with a file name based on a data field. (See: "Dynamic images" on page 821.) The sender's address is adjusted depending on where the customer lives. The two different sender's addresses are saved in snippets.
Stationery - in the output. The other presets will not print the Media. Only the selected Output Creation Preset is put to use in the Workflow configuration. To see the exact settings, open an Output Creation Preset in the Designer: first select File > Output Creation Presets from the menu; then click the Import button and browse to the Configurations\Resources\Output presets folder to select the preset.
Customizing the project A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project. Do you intend to expand the project into a solution where Workflow runs on a different machine that also has a different regional setting? Then indicate the desired encoding in the Designer preferences (see "Project Wizard deployment settings" on page 869) before installing the project.
l Add text, images and other elements (see "Content elements" on page 631) l Change the layout (see "Styling and formatting" on page 743) l Change the "Media" on page 508 l Change the "Master Pages" on page 505 l Add sections (see "Print context" on page 481) In order to further personalize the letter, you need to open your data mapping configuration. (See: "Personalizing content" on page 787.) Tip The Designer can have one data mapping configuration and one template open at the same time.
All of the presets provided by the wizard save the output to one file. You might want to save the output to a number of files, for instance, one per customer. The Transactional Print Jobs project shows you how to do that. Project Wizard: Print Transactional Jobs The Print Transactional Jobs Project Wizard creates an OL Connect project that produces transactional print output. It prints invoices to: o A single PDF for the entire job (in which the invoices are grouped per customer).
That variable is used in the settings of the Capture Folder task. The path is also copied to the Output Creation Presets which are used in the Create Output tasks. 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_tran_generate_output process. 3. Open the Debug ribbon and click Run.
The Media (virtual stationery) is included in the output - it is printed on the page's background , according to a setting in the Output Creation Presets. Styling is done via style sheets (see "Local formatting versus style sheets" on page 743). The style rules are in the context_print_styles.css file. Note how they combine the HTML tag, ID and class of elements to select them. (See also: "Selectors in Connect" on page 896.) Scripts Scripts personalize content.
Dynamic Table The table in the invoice is a Dynamic Table. It is filled and expanded dynamically by the scripts in the Products folder. To learn how to insert and edit such a table, see "Dynamic Table" on page 823. Note that this table does not use one of the default table styles, and that the style sheet with the default table styles is not present in the template. To add that style sheet to the template, insert a table using the Dynamic Table wizard.
The three Output Creation Presets all create PDF output, add the template's name to the PDF's meta data, and save the file in a certain directory. They all have the Print Virtual Stationery option enabled. So, what are the differences between these presets? Groups and separation The PR_TRAN PDF Full Job preset outputs only one file. The PR_TRAN PDF per Invoice preset outputs one file per invoice, separating the output by document.
The 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. Customizing the project A project is a great starting point for building an OL Connect solution. This part explains how to make changes to the project.
Template There are countless ways to customize the template to meet your exact requirements. You could, for example: l Add text, images and other elements (see "Content elements" on page 631) l Change the layout (see "Styling and formatting" on page 743) l Change the "Media" on page 508 l Change the "Master Pages" on page 505 l Add sections (see "Print context" on page 481) In order to further personalize the invoice, you need to open your data mapping configuration.
1. Select File > Output Creation Presets from the menu. 2. Click the Import button and browse to the Configurations\Resources\Output presets folder to select the preset. 3. Click Next and adjust the Printer and Output options. To separate the output differently, for example, by city in which the customers live, you need to change the Output Creation Preset as well as the Job Creation Preset. 1. Open the Job Creation Preset in the Designer: select File > Job Creation Presets from the menu. 2.
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.
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. When you select the file as sample file (on the Debug ribbon), it can be used to debug the process.
l l l Most of the scripts in the Thank you folder directly insert data that were submitted via the Web form; see "Inserting variable data directly (drag-and-drop)" on page 805. The Snippets script (also in the Thank you folder) loads two snippets, depending on the values of two data fields (see "Loading a snippet via a script" on page 902). Note that it selects the table, in order to insert the snippet after the table (via results.after(); see "after()" on page 1362).
In order to create the data mapping configuration, the input data needed to be saved to a file (see "Saving input as sample data" on page 176). 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 203. Customizing the project A project is a great starting point for building an OL Connect solution.
Tip The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both. 6. Send the Workflow configuration to the server. Web pages Apart from the form, there are lots of ways to modify the template.
look at the task's properties. The xmlget() function, used in the Value fields, is a data selection function (see Data Selections). Data selection functions are available in many plugins, in any field that accepts variables. Try right-clicking a field and select Get Data Location from the contextual menu. (See also: Variable Task Properties.) For general information about processes in Workflow see About Processes and Subprocesses, in the Online Help of Workflow.
Testing and running the project Once the Project Wizard has finished the installation, the project is ready to be tested. If the templates and data mapping configurations haven't been sent to Workflow yet, do that first (see "Sending files to Workflow" on page 453). This requires that the Workflow service is running (see Starting the Workflow service in Workflow's Online Help). To test the project: 1.
Tip The saved file can be used to create a data mapping configuration. Project details The web template The web page is designed in the WEB_HELLO Web Page template. It contains one Web section (see "Web pages" on page 547). Styling is done via style sheets (see "Local formatting versus style sheets" on page 743). The style rules are in the context_web_styles.css file. Note how they combine the HTML tag, ID and class of elements to select them. (See also: "Selectors in Connect" on page 896.
The Workflow configuration The project's Workflow configuration, Serving a Web Page.OL-workflow, contains just one process. It is a simple OL Connect Web process (see "Web processes with OL Connect tasks" on page 195). The NodeJS Server Input task's HTTP action is set to hello. This means that this process will be invoked whenever someone tries to access the Workflow server with this URL: http:// {server's address}/hello.
preferences (see "Project Wizard deployment settings" on page 869) before installing the project. Input data If you want to add other parameters to the URL and use those data in the template, here's how to do that: 1. Run the project, add more parameters to the URL and let the process save the input data to a file (see "Saving input as sample data" on page 182). 2. Use the file to create a new data mapping configuration that extracts the additional data.
Tip The Designer can have one data mapping configuration and one template open at the same time. Use the tabs at the top of the workspace to switch between the two. Click the synchronize button on the Data Model pane to make sure that the Data Models are the same in both. Once the template is ready, send it to Workflow (see "Sending files to Workflow" on page 453). Finally, in Workflow, adjust the process: double-click the Create Web Content task to open it, and select the new template.
made up of tasks (also referred to as plugins). In the Workflow configuration tool they are divided into groups. For example: l l l l l l Input tasks look for certain input data on a certain channel and start a process when they find it. The data that enter the process are handed from one plugin to the next in the form of a file: the 'job file'. Process logic tasks help you to control the process, for example by branching it, creating a loop, or referring to another process or a subprocess.
l l Web process. A web process serves one or more web pages. The output can vary from a plain and simple web page to an extensive web form. See: "Web processes with OL Connect tasks" on page 195. COTG processes. The process that creates a form for the Capture OnTheGo app is in essence a web process, but a COTG solution consists of more than one process. The typical COTG processes are described here: "Capture OnTheGo Workflow processes" on page 190.
Output creation Merging the records with a template is the job of one of the following tasks. Email The Create Email Content task creates email content items and sends them to the recipient. See "Email processes with OL Connect tasks" on page 191. Web The Create Web Content task can handle only one record at a time and returns a web page. See "Web processes with OL Connect tasks" on page 195.
l l The Set Properties task adds properties as tags to items/sets in the OL Connect database. The Retrieve Items task retrieves items (records, or content items, etc.) or sets of items from the OL Connect database, by ID or by property. Note Combined, the Set Properties and Retrieve Items tasks make it possible to batch and commingle Print content items.
l l One process that authenticates and replies to document requests from COTG users. This process returns the actual document directly to the app. It starts with a Server Input task (the NodeJS Server Input task or the older HTTP Server Input task), which returns the final output of the process to the caller. One process that receives and handles the data when a COTG user submits a form. This process starts with a Server Input task as well.
enter an empty JSON string: {}. However, if the template should be merged with data, you will need to add one or more tasks to provide the required data. The Create Email Content task must receive either Metadata containing information regarding a valid Record Set, or JSON data. This can be the output of tasks like: l l An Execute Data Mapping task which retrieves data from the job file (such as the request XML).
Print processes with OL Connect tasks Generating print output from a template via an automated process requires you to design a print process in the PReS Workflow configuration tool. This topic explains which tasks and files are used in a print process. Tip An easy way to setup a print project in OL Connect, including the print process and the files that it needs, is to use a Project Wizard. There are two Project Wizards that create a sample print project. See "Project Wizards" on page 1000.
Nevertheless, the separate plugins would be used in the following situations: l l l The record set, created by the Execute Data Mapping task, is also needed to create another kind of output in the same process. The input is JSON data, which can be used directly. In this case there is no need to use the Execute Data Mapping task or Retrieve Items task. The necessary Print Content Items have already been created, whether in the same or in another Workflow process.
For more information about how to create a process in Workflow, please refer to the Online Help of Workflow. Web processes with OL Connect tasks Serving a web page, made with a template, via an automated process requires you to design a web process in the PReS Workflow configuration tool. This topic explains which tasks and files are used in a web process. Tip An easy way to start an OL Connect web project including the web process and the files that it needs, is to use a Project Wizard.
To trigger the process from a Web Form, set the Action of the Form to the HTTP Action of the Input task. (See "Forms" on page 714.) The Create Web Content task creates an HTML output file from the Web context in a template. Select the Web template in the task's properties. If the Web template doesn't need any data, you can set the Data Source of this task to JSON and enter an empty JSON string: {}, or set it to Record ID and enter 0 (zero).
Templates and data mapping configurations need to be sent from the Designer to PReS Workflow before they can be used in the Workflow process; see "Sending files to Workflow" on page 453. The next step is to create a process in PReS Workflow that generates Web output, using these files. For more information about how to create a process in Workflow, please refer to the Online Help of Workflow.
l Phase 2: Print content items are retrieved from the Connect database using the Retrieve Items task. The Create Job and Create Output tasks transform these items or sets into one or more print jobs. In order to retrieve print content from the Connect database in the second phase, some preparatory work must be done in the first phase. What needs to be done exactly depends on what you want to retrieve, and how.
Retrieving items/sets by ID New print content items are automatically saved in the Connect database when the Create Content task creates them. The task returns the IDs of those items, as well as the ID of the content set, to the Workflow process via Metadata (see About Metadata). In order to retrieve (sets of) items by ID later on, you will have to get the IDs from the Metadata and store them somewhere else.
Note Data field values and properties of items in the Connect database are also used when sorting the output. Make sure to set properties that are necessary for sorting on the content item level. Commingling When documents in one print batch originate from different templates, that is called commingling. Commingling isn't very different from batching in how it's done.
l Through a Post Pagination script in the template. (See "Post Pagination Scripts" on page 927 and "contentitem" on page 1434.) Sorting by property is only possible if the property has been set explicitly on the respective content items (not content sets) in the Connect database. It is also important to note that in order to use a data field or property in a sorting rule, it should be present in all content items.
l l Bundle content items into "documents" (mail pieces) and sort the items within each document. Put documents in "groups", and define how documents are sorted within a group. Note that this tab is only available when the Retrieve Items task is configured to retrieve content items - not content sets. Separating the output Print output in batches can be separated just like all other print output, using an Output Creation Preset in the Create Output task (see "Output Creation Presets" on page 1469).
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.
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 228 and "The Data Model" on page 274. 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 446.
Note AFP input is dependent on a third party library (CDP), which only allows PReS Connect to run up to 4 AFP input processes on a given machine at a given time. 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.
3. Click the Browse button and open the file you want to work with (for a database, you may have to enter a password). 4. Click Finish. 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 l JSON 3. Click Next. 4. Click the Browse button and open the file you want to work with. 5. Click Finish.
l l l l PCL and PostScript (PS) files are automatically converted to PDF format by the Connect Server. To allow for this, the default Connect Server and (if it is secured) an authenticated user must be configured via the Preferences (see "Connect Servers preferences" on page 872). Note that when used in a production environment (e.g. a Connect Workflow process) the conversion to PDF may influence the processing speed, depending on the available processing power.
There are two ways to open a data file with a wizard: from the Welcome screen or from the File menu. l From the Welcome screen 1. Open the PReS Connect Welcome page by clicking the select the Help menu and then Welcome. icon at the top right or 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.
l From the Welcome screen 1. Open the PReS Connect Welcome page by clicking the select the Help menu and then Welcome. icon at the top right or 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.
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 311, click on File > Save, or click on Save As to save a copy of a data mapping configuration under a different name.
Using the wizard for CSV and Excel files The DataMapper wizard for CSV and Excel files helps you create a data mapping configuration for such files. The wizard automatically detects delimiters and extracts all data in one extraction step. The wizard interprets each line in the file as a record. If your data file contains transactional data, you will probably want more lines to go in one record and put the transactional data in detail tables. The wizard cannot create detail tables.
After selecting the file, take a look at the preview to ensure that the file is the right one and the encoding correctly reads the data. Click Next. For an Excel file you can make the following settings: l l l First row contains field names: Uses the first row of the Excel sheet as headers, which automatically names all extracted fields. Sheet: Select the sheet from which the data should be extracted.
Finally click Finish. All data fields are automatically extracted in one extraction step. Using the wizard for databases The DataMapper wizard for database files helps you create a data mapping configuration for a database file. The wizard extracts the data in one extraction step. The wizard cannot create detail tables. If the file contains transactional data, the data mapping configuration is best created without a wizard (see "Creating a new data mapping configuration" on page 205).
Note After creating the initial data mapping configuration you may use a custom SQL query via the Input Data Settings; see "Settings for a database" on page 232. Tip The Sort on option, combined with the Stop data mapping option of the "Action step" on page 271, allows to process only a group of items without having to examine all records. (See also: "Action step properties" on page 359.) MySQL, SQL Server or Oracle l Server: Enter the server address for the database.
l Encoding: Choose the correct encoding to read the file. 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. ODBC Data Source l l ODBC Source: Use the drop-down to select an ODBC System Data Source.
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 Read access to the database. Password: Enter the password that matches the user name above. Advanced mode: Check to enable the Connection String field to manually enter the database connection string. Connection string: Type or copy in your connection string.
After selecting a JSON file, specify if and how the JSON file must be split into multiple records. This is done by selecting an object or array as parent element. Its direct child elements objects and arrays, not key-value pairs - can be seen as individual source records. If the root is selected, there will be only one source record. Whether source records are output as individual records depends on the trigger.
Tip How to extract information from the metadata in the extraction workflow itself is explained in: "Extracting metadata" on page 241. If the data file doesn't contain any metadata, each page is a new record - in other words, a boundary is set at the start of a new page -, which is exactly what happens when you open the file without a wizard. You can open a PDF/VT or AFP file with a wizard using the Welcome screen or the File menu. l From the Welcome screen 1.
Note NOP (No Operation) records in AFP files cannot be extracted. Click Finish to close the dialog and open the actual Data Mapping configuration. On the Settings pane, you will see that the boundary trigger is set to On metadata. The selected metadata fields are added to the Data Model. Note 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 (see the Connect Knowledge Base.
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.
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. Advanced PCL to PDF options The Connect DataMapper uses LincPDF to convert PCL files to PDF files. By default, the only options it passes to LincPDF are the input and output file names.
PCL Input license. Calling LincPDFC via an external program To set advanced conversion parameters, the PCL input file has to pass through an additional Workflow process before entering the process in which the data mapping takes place. The extra Workflow process should call the LincPDF command line module LincPDFC via the External Program plugin with the desired advanced conversion parameters. To create such a Workflow process: 1. Add a local variable to your process and name it lincPDFOptions. 2.
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). 0 or 1 When enabled, Lincoln’s PCL interpreter will output vector graphics in a simpler mode (default: FALSE). 0 or 1 When set (1), LincPDF will convert CMYK as RGB colorspace before writing (default: FALSE).
the Workflow log. 7. Save the output of LincPDFC using the –o folder specifier in the parameter (% {workingDir}\Temp, in this case.) In another Workflow process, import the created PDF with the Folder Capture input plugin, specifying the output folder of the previous process (%{workingDir}\Temp in the example) as input folder, and %O.pdf as the file mask.
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.
/*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.
-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
-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" .
after the Data Mapping workflow has completed ("Postprocessor step" on page 272). 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.
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 262. Rearranging steps To rearrange steps, simply drag & drop them somewhere else on the colored line in the Steps pane.
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.
fields, even if the field delimiter is the semicolon. For an explanation of all the options, see: "CSV file Input Data settings" on page 330. 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 331. Excel has its own way to display dates.
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. For an explanation of all the options, see: "Text file Input Data settings" on page 333.
Record boundaries Boundaries are the division between records: they define where one record ends and the next record begins. Using boundaries, you can organize the data the way you want. You could use the exact same data source with different boundaries in order to extract different information. If, for instance, a PDF file contains multiple invoices, each invoice could be a record, or all invoices for one customer could go into a single record.
Data format settings defined for a data source apply to any new extraction made in the current data mapping configuration. These settings are made on the Settings pane; see "Settings pane" on page 330. Settings for a field that contains extracted data are made via the properties of the Extract step that the field belongs to (see "Setting the data type" on page 283). Any format settings specified per field are always used, regardless of the user preferences or data source settings.
You can also define custom runtime parameters. With those, you could, for example: l l Pass a JSON structure, containing boundary information as well as the name and location of fields to be extracted dynamically from a data stream. This way, a generic data mapping configuration could be used to process several kinds of different files. Define default values that are different from one data mapping instance to the next, even when using the same data mapping configuration.
Note Runtime parameters are always added to the file currently visible in the workspace. To add a parameter: 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.
set to Each record. (See: "sourceRecord" on page 427.) To change the value of such a property you could use an Action step (see "Action step" on page 271). Note that the property's value will be reset at the beginning of each source record. 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 407.) These are read-only.
Preprocessor step The Preprocessor step allows the application to perform actions on the data file itself before it is handed over to the Data Mapping workflow. In addition, properties can be defined in this step. These properties may be used throughout the extraction workflow. For more information, see "Preprocessor step" on page 262. 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.
field name stays the same. Drop data on empty fields or on the record itself to add new fields. 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 267 or "Multiple Conditions step" on page 270. Normally the same extraction workflow is automatically applied to all records in the source data.
1. Select the field in the Data Model that contains the extracted lines. 2. On the Step properties pane, under Field Definition, click the drop-down next to Split and select Split lines. 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 page 243.) 2.
4. Select the Level of the metadata on which the information can be found. 5. Select the Property to extract. Alternatively you could create a JavaScript extraction (see "Using scripts in the DataMapper" on page 392 and "extractMeta()" on page 416). Note NOP (No Operation) records in AFP files cannot be extracted. Editing fields After extracting some data, you may want to: l Change the names of fields that are included in the extraction. l Change the order in which fields are extracted.
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. Selecting data In order to extract the data, it is necessary to first define the data to be extracted, by selecting it.
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.
In this tree view you can select elements just like files in the Windows Explorer. Keep the Ctrl key pressed down while clicking on key-value pairs or brackets to select multiple elements, or keep the Shift key pressed down to select consecutive elements. You can select multiple key-value pairs, arrays and objects even if those are in different elements. To get a better overview you can collapse any JSON level.
fields that contain promotional data is the same in each record. These data are stored on the root level of the extracted record. Transactional data , on the other hand, are used in communications about transactions between a company and their customers or suppliers: invoices, statements, and purchase orders, for example. Naturally these data differ per customer. They are stored in detail tables in the extracted record. The number of detail lines in a detail table can vary from record to record.
Extracting data with a script. The topic: "Extracting data of variable length" on page 257 explains a few ways to extract data from a variable number of lines into one data field. 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 extraction step is placed inside the Repeat step, just before the GoTo step. From an XML file The transactional data appears in repeated elements.
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.
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.
2. Right-click the opening bracket of the first 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. With this setting the Extract step goes through the defined collection of elements, without the need for a Goto step within the loop. (With the other Repeat type settings the loop must contain a Goto step.
Tip The full JsonPath to an element is displayed at the bottom left of the window when you select it. To copy the path, right-click it and select Copy. Note If a key in a JSON file has a name that looks like a function (e.g. "TLIST(A1)"), then the Extract step has to use a JsonPath with bracket notation instead of the default dot notation. For information about the bracket notation see https://goessner.net/articles/JsonPath/.
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. Include/exclude lines. Lines between the start and end of the loop that don't contain a line item must be excluded from the extraction.
Selecting data - especially something as small as a dot - can be difficult in a PDF file. To make sure that a Condition step checks for certain data:Set the Right operand to Value (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.
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. 5. Extract the data (see "Adding an extraction" on page 239). 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.
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.
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. After the loop step, the cursor position is at the end of line items. 1. Select the amount or amounts. 2. Click on the end of the Repeat step ( ) in the Steps panel. 3. Right-click on the selected data and select Add Extraction.
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. Data may vary in length: a product description for example may or may not fit on one line. How to exclude lines from an extraction is explained in another topic: "Extracting transactional data" on page 245 (see From a PDF or Text file).
be added to extract the data from a particular region. The Extract steps could write their data to the same field. Data cannot be extracted more than once in any record, unless the Extract steps are mutually exclusive. This is the case when they are located in different branches of a Condition step or Multiple Conditions step. Inside a Detail table, multiple Extract steps may extract the same data but each of them will create a new child record in the Detail table.
Page 260
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 238. To add a field without extracting data, see "Expression-based field" on page 280. 2. On the Step properties pane, under Field Definition, select the field and change its Mode to Javascript.
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 228). They contain a specific instruction for the DataMapper, for example to extract data, create a loop, or apply a condition.
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 348. 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.
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, a JsonPath in JSON, 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.
see: "Extracting data" on page 238. 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 245 and "Detail tables" on page 319.
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). Generally this step can be skipped when the data source is an XML file or JSON file. 3.
The DataMapper moves through JSON files using JsonPath, a path-like syntax to identify and navigate elements in a JSON document. For an overview of the JsonPath syntax, see https://github.com/json-path/jsonpath. In the DataMapper the JsonPath can be absolute (start with $ which is the root) or relative to the current position (start with . which is the current element). However, going up to a parent element is not possible with a relative JsonPath.
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.
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. l Alternatively, right-click the Steps pane and select Add a Step > Add Conditional.
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. In a Multiple Conditions step, conditions or rather Cases are positioned side by side. Each Case condition can lead to an extraction. Cases are executed from left to right.
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 377.
l l l Set the value for a record property. Record properties are defined in the Preprocessor step; see "Preprocessor step" on page 262. 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.
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 392 and "DataMapper Scripts API" on page 389). Configuring the Postprocessor step For an explanation of the settings for post-processors, see "Postprocessor step properties" on page 384.
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 384). 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).
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 424). Duplicates are not shown in the Data Model.
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).
directly through the record object (see the "Designer Script API" on page 1282 and "DataMapper Scripts API" on page 389). To change the order in which data are extracted, see "Renaming and reordering fields in an extraction step" on page 282. 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.
be populated with data from different sources and formats, without the need to modify the template (see "Importing/exporting a Data Model" on page 275). In Workflow, when a data mapping configuration is used to extract data from a data source (see "Data mapping configurations" on page 204), 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.
l Use the Update Data Records plugin. l Add an Output task and check the option Update records with Metadata. 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 PReS 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 274).
Expression-based field Expression-based fields are filled with the result of a (JavaScript) expression: 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 an expression-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.
Property-based field A property-based field is filled with the value of a property (see "Properties and runtime parameters" on page 235). Custom properties can be added via the Preprocessor step; see "Preprocessor step" on page 262. 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.
to add data to existing fields via Workflow; see "Adding fields and data via Workflow" on page 278. Editing fields The list of fields that are included in the extraction, the order in which fields are extracted and the data format of each field, are all part of the Extract step's properties. These can be edited via the Step properties pane (see "Extract step properties" on page 351). Tip To change the name of a field quickly, right-click it in the Data Model and select Rename.
l It is recommended that you do not use spaces in field names. When a data field is dragged into a template, the data field name is used in the selector of the script that is created, but any spaces will be removed. Also, data fields may be used as Metadata in a Workflow process, and spaces are not permitted in Metadata field names. Note The order of fields in an extraction step may be different from their order in the Data Model.
Setting a default value You may want to set a default value for a field, in case no extraction can be made. Make sure to set the data type of the field via the step properties (see above). Then right-click the field and select Default Value. The default value must match the selected data type. If the data type of the field is set to Integer, for example, you cannot enter a value of 2,3. A default date must be formatted as a DateTime object ("year-month-day" plus the time stamp, for example: 2012-04-11 12.
Note The last value attribution to a variable is the one used as the result of the expression. Deleting a field The list of fields that are included in an extraction is one of the properties of an Extract step. To delete a field: 1. Select the field: click on the field in the Data Model, or select the Extract step that contains the field that you want to delete, and in the Step properties pane, under Field Definition, select the field from the Field List. 2.
1. On the Data Model pane, click one of the fields in the detail table. 2. On the Step Properties pane, under Extraction Definition, in the Data Table field, you can find the name of the detail table: record.detail by default. Change the detail part in that name into something else. 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.
To create more than one detail table, simply extract transactional data in different Repeat steps (see "Extracting transactional data" on page 245). 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 288
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).
a number of "details" such as movie rentals or long distance calls.
The services can be extracted to a detail table called record.services. The "charges" and "details" can be extracted to two nested detail tables.
The nested tables can be called record.services.charges and record.services.details.
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.
l "HTMLString" on page 300 l "Integer" on page 300 l "Float" on page 299 l "Currency" on the next page l "Date" on page 296 l "Object" on page 301 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. Boolean Booleans are a simple true/false data type often used in conditions and comparisons.
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. Currency The Currency data type is a signed, numeric, fixed-point 64-bit number with 4 decimals. Values range from -922 337 203 685 477.5808 to 922 337 203 685 477.5808.
Building Currency values Currency values can be the result of direct attribution or mathematical operations just like Integer values (see "Integer" on page 300). 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.
Data format settings tell the DataMapper how to read and parse data from the data 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..
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 1297). Examples of masks Value in raw data Mask to use June 25, 2013 MM dd, YYYY 06/25/13 mm/dd/yy 2013.06.25 yyyy.mm.dd 2013-06-25 07:31 PM yyyy-mm-dd hh:nn ap 2013-06-25 19:31:14.1206 yyyy-mm-dd hh:nn:ss.ms Tuesday, June 25, 2013 @ 7h31PM DD, MM dd, yyyy @ hh\hnnap Entering a date using JavaScript In several p
The use of the JavaScript Date() object is necessary when creating dates through a JavaScript expression. For more information, see w3schools - JavaScript Dates and w3schools - Date Object. Example The following script creates a date that is the current date + 30 days: function addDays(date, days) { var result = new Date(date); result.setDate(result.getDate() + days); return result; } addDays(new Date(), 30); Float Floats are signed, numeric, floating-point numbers whose value has 15-16 significant digits.
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!.
l l Direct attribution: Assign an integer value directly, such as 42, 99593463712, record.fields.Total; or data.extract("TotalOrdered");. Mathematical operations: Assign the result of any mathematical operation. For example: 22+51, 3*6, 10/5, record.fields["InvTotal"], or sourceRecord.property.SubTotal. For more information on mathematics in JavaScript , see w3Schools - Mathematical Operators. For more advanced mathematical functions, see w3schools - Math Object.
l Extraction: l In the Data Model, select a field. l 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 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.
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.
Example: transactional details, in a simple invoice format PAGE 305Example: nested tables (one table into another) PAGE 306Keyboard 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 1039. 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.
Key combination Function Alt Put the focus on the menu. (Alt + the underlined letter in a menu name displays the corresponding menu.) The menu can then be browsed using the Enter key, arrow up and arrow down buttons.
Key combination Function 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 F10 Add an Extract field F11 Add an Action step F12 Add a Multiple Conditions step Alt +
Key combination Function 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. Key combination Function Alt + - Open system menu Ctrl + - Zoom out Tip You can also use the mouse's scroll wheel in combination with the Ctrl button to gradually zoom in or out.
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 Ctrl + - Zoom out Ctrl + + Zoom in 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 + J Line break Ctrl + L Go to line; a prompt opens to enter a line number. Ctrl + Shift + D Delete line Shift + Tab Shift selected lines left Tab Shift selected lines right Ctrl + / Comment out / uncomment a line in code Ctrl + Shift + / Comment out / uncomment a code block Menus The following menu items are shown in the DataMapper Module's menu: File Menu l l l l l New...
l l l l l Save: Saves the current data mapping configuration or Template to its current location on disk. If the file is a data mapping configuration and has never been saved, the Save As dialog appears instead. Save As...: Saves the current data mapping configuration or Template to a new location on disk. In the case of Templates, it is saved to a location that can be different than the local repository. Save All: Saves all open files.
l l Copy: Click to place a copy of the currently selected step, or steps, in the clipboard. Paste: Click to place any step, or steps, from the clipboard before the currently selected step in the "Steps pane" on page 346. Data Menu l l l Hide/Show datamap: Click to show or hide the icons to the left of the Data Viewer that displays how the steps affect the line. Hide/Show extracted data: Click to show or hide the extraction selections indicating that data is extracted.
l Add Action Step: Adds a step to run one or more specific actions such as running a JavaScript expression or setting the value of a Source Record Property. View Menu l Zoom In: Click to zoom in the "Steps pane" on page 346. l Zoom Out: Click to zoom out the "Steps pane" on page 346. Window Menu l Show View l Messages: Shows the "Messages pane" on page 329 l Data Model: Shows the "Data Model pane" on the next page. l Steps: Shows the "Steps pane" on page 346.
l "Settings pane" on page 330. The Settings pane contains settings for the data source. l "Steps pane" on page 346. The entire extraction workflow is visible in the Steps pane. l "The Data Viewer" on page 327. The Data Viewer shows one record in the data source. l "Step properties pane" on page 347. The Step properties pane contains all settings for the step that is currently selected on the Steps pane. l "Data Model pane" below. The Data Model pane shows one extracted record.
l l l A Data Model file (*.OL-datamodel). A JSON file (*.json): A JSON object or an array of JSON objects representing records. A 'typed' JSON file (*.json). Note Typed JSON follows the structure of a JSON Record Data List (see the REST API Cookbook). Data field types are determined by the schema object in the JSON. Note When a Data Model is exported to a JSON file or typed JSON file, detail tables are exported, but groups are not.
Note Moving and grouping fields in the Data Model has no impact on the order in which data are extracted, or on the final records in the OL Connect database. They only help you organize the Data Model visually. To learn how to change the order in which data are extracted, see "Renaming and reordering fields in an extraction step" on page 282. l l l Add Field: Click to add a new field at the current level (record or detail table).
l l Default Value: Click to set the default value for a field. This value is used if no extraction is present, or if an extraction attached to this field returns no value. Move: Click to move the selected field within the current level or group in the Data Model. (See: "Ordering and grouping fields in the Data Model" on page 276.) l Top: Move the field to the first place. l Up: Move the field one step up. l Down: Move the field one step down. l Bottom: Move the field to the last place.
Record navigation Records can be navigated via the Data Model pane. The default record level navigates between records both in the Data Model pane and the Data Viewer, while each detail table has a similar navigation that influences that table and each detail table under it. l l l l l l l l Expand/Contract: Click to hide or show any fields or tables under the current table level or in the current group (see "Grouping fields" on page 277).
Detail tables can be included in a template via a Dynamic Table ; see "Dynamic Table" on page 823. Renaming a detail table Renaming detail tables is especially useful when there are more detail tables in one record, or when a detail table contains another detail table. For this detail table, ‘products’ would be a better name. 1. On the Data Model pane, click one of the fields in the detail table. 2.
To create more than one detail table, simply extract transactional data in different Repeat steps (see "Extracting transactional data" on page 245). 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 322
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).
a number of "details" such as movie rentals or long distance calls.
The services can be extracted to a detail table called record.services. The "charges" and "details" can be extracted to two nested detail tables.
The nested tables can be called record.services.charges and record.services.details.
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 234).
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.
workflow. 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).
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 231.
l l Skip empty lines: Ignore any line that has no content. Note that spaces are considered content. 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. Excel file Input Data settings There are no settings for field separation in an Excel file, only settings with regards to the file as a whole.
l l l l Paragraph spacing: Determines the spacing between paragraphs. The default value is 1.5, meaning the space between paragraphs must be equal to at least 1.5 times the average character height to start a new paragraph. Magic number: Determines the tolerance factor for all of the above values. The tolerance is meant to avoid rounding errors. If two values are more than 70% away from each other, they are considered distinct; otherwise they are the same.
a selection from the database, using whatever language the database supports. The query may contain variables and properties, so that the selection will be dynamically adjusted each time the data mapping configuration is actually used in a Workflow process; see"Using variables and properties in an SQL query" on page 345. l l l Encoding: Defines what encoding is used to read the Data Source ( US-ASCII, ISO8859-1, UTF-8, UTF-16, UTF-16BE or UTF-16LE ).
l On lines: Triggers a new page in the Data Sample after a number of lines. l l l Cut on number of lines: Triggers a new page after the given number of lines. With this number set to 1, and the Boundaries set to On delimiter, it is possible to create a record for each and every line in the file. Cut on FF: Triggers a new page after a Form Feed character. On text: Triggers a new page in the Data Sample when a specific string is found in a certain location.
l Use XPath: Enter an XPath to create a delimiter based on thenode nameof elements. For example:./*[starts-with(name(),'inv')]sets a delimiter after every element of which the name starts with 'inv'. Note thatstarts-with()is an XPath function. For an overview of XPath functions, see Mozilla: XPath Functions. The XPath may also contain JavaScript code. In order to use JavaScript: l The XPath must start with = l The entire JavaScript statement must be enclosed in curly brackets: {...
Note The information contained in all of the selected parent nodes will be copied for each instance of that node. For example, if a client node contains multiple invoice nodes, the information for the client node can be duplicated for each invoice. The DataMapper only extracts elements for which at least one value or attribute value is defined in the file.
limit, use the value 0 (zero). 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 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.
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.
l l l Use selected textbutton: 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 394. XML file boundaries The delimiter for an XML file is a node. The Boundaries determine how many of those nodes go in one record.
Note Only arrays and objects can be seen as a record. It is not possible to split the JSON between key-value pairs. l l Record limit: Defines how many records are displayed in the Data Viewer. This does not affect output production; when generating output, this option is ignored. To disable the limit, use the value 0 (zero). The default value is 200. Trigger: Defines the type of rule that controls when a boundary is set, creating a new record.
Tip Data samples can be copied and pasted to and from the Settings pane using Windows File Explorer. l Add : Add a new Data Sample from an external data source. The new Data Sample will need to be of the same data type as the current one. For example, you can only add PDF files to a PDF data mapping configuration. Multiple files can be added simultaneously. l Delete l Move up l Move down l l l Replace source. : Remove the current Data Sample from the data mapping configuration.
l l Current Locale Settings: Shows dates and times as formatted by Windows using the current Locale of the system on which Connect runs. All values are shown as a date including a time. ISO 8601 (UTC): Uses the ISO 8601 (UTC) format to display dates and times. All values are shown as a date including a time, taking the time zone into account. Note that when no time was specified with a date in the original file, the default time (12.00 AM) is used and converted; this may influence the displayed date.
l Negative Sign Before: Any value in a numeric field that has a "-" sign is interpreted as a negative value. l Decimal Separator: Set the decimal separator for a numerical value. 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.
Using variables and properties in an SQL query When you use variables and properties in an SQL query, the selection will be dynamically adjusted each time the data mapping configuration is actually used in a Workflow process. To create a dynamic SQL query: l l The query must start with = Any variable or property must be enclosed in curly brackets: { ... }. This effectively inserts a JavaScript statement in the query. Note that all other curly brackets must be escaped with a backslash.
Steps pane The Steps tab displays the data mapping workflow: the process that prepares and extracts data. The process contains multiple distinct steps and is run for each of the records in the source data. For more information about the steps and how to use them, please refer to Steps and "Data mapping workflow" on page 228. Finding a step To find a certain step in a large data mapping workflow, start typing the name of the step in the Find Step field at the top of the Steps pane, and press Enter.
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. More options are available when a Repeat or a Condition step is selected: l Add Step in Repeat: Adds a step to a Repeat loop. l Add Step in True: Adds a step to the True branch of a Condition step. l Add Step in False: Adds a step under the False branch of a Condition step. l Add Multiple Conditions Step: Adds a Multiple Conditions step.
l "Preprocessor step properties" below l "Extract step properties" on page 351 l "Action step properties" on page 359 l "Repeat step properties" on page 366 l "Condition step properties" on page 374 l "Multiple Conditions step properties" on page 377 l "Goto step properties" on page 380 l "Postprocessor step properties" on page 384 Preprocessor step properties The Preprocessor step does not run for every record in the source data.
l Name: A read-only field displaying the name of the property. l Scope: A read-only field indicating that the scope of the property is Runtime parameter. l Type: A read-only field indicating the data type for each property. l Default Value: Enter a default value for the property. This value is overwritten by the actual value coming from PReS Workflow when the data mapping configuration is run using the Execute Data Mapping task.
Properties The Properties subsection is used to create specific properties that are used throughout the workflow. For more information see: "Properties and runtime parameters" on page 235. Note Properties are evaluated in the order they are placed in the list, so properties can use the values of previously defined properties in their expression. l l Name: The name of the property used to refer to its value.
Preprocessor The Preprocessor subsection defines what preprocessor tasks are performed on the data file before it is handed over to the data mapping workflow. Preprocessor tasks can modify the data file in many ways, and each task runs in turn, using the result of the previous one as an input. l l Name: The name to identify the Preprocessor task. Click this field to rename the Preprocessor task. Type: The type of Preprocessor task. Currently there is only one type available: script.
Extraction Definition l l Data Table: Defines where the data will be placed in the extracted record. The root table is record, any other table inside the record is a detail table. For more information see"Extracting transactional data" on page 245. Append values to current record: When theExtractstep is inside a loop, check this to ensure that the extraction will be done in the samedetail tableas any previous extractions within the same loop.
l JavaScript: The result of the JavaScript Expression written below the drop-down will be the value of the extracted field. If the expression contains multiple lines, the last value attribution (variable = "value";) will be the value. See"DataMapper Scripts API" on page 389. l l l Use JavaScript Editor: Click to display the"boundaries" on page 401dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression.
l l l Top offset: The vertical offset (the number of lines) from the current pointer location in the Data Viewer). Height: The height of the selection box, in the number of lines. When set to 0, this instructs the DataMapper to extract all lines starting from the given position until the end of the record and store them in a single field. Use selection: Click to use the value (Left, Right, Top offset and Height) of the current data selection (in the Data Viewer) for the extraction.
Note If the selection contains multiple lines, the lines are by default joined and extracted into one field. To split the lines, select the option Split lines (see below). l l l l Post Function: Enter a JavaScript expression to be run after the extraction. For examplereplace("-","")would replace a single dash character inside the extracted string. Trim: Select to trim empty characters at the beginning or the end of the field. Type: The data type of the selected data; see"Data types" on page 293.
l Post Function: Enter a JavaScript expression to be run after the extraction. For examplereplace("-","")would replace a single dash character inside the extracted string. l l Use JavaScript Editor: Click to display the"boundaries" on page 401dialog. Trim: Select to trim empty characters at the beginning or the end of the field. Settings for location-based fields in an XML file These are the settings for location-based fields in an XML file. l XPath: The path to the XML field that is extracted.
anything in the current element). If more than one item is returned, the Extract step will keep an array of all returned items. The full JsonPath to an element is displayed at the bottom left of the window when you select it. To copy the path, right-click it and select Copy. l Use selection: Click to use the value of the current data selection for the extraction. Note If a key in a JSON file has a name that looks like a function (e.g.
depends on the current operating system's regional settings. l Negative Sign Before: Any value in a numeric field that has a "-" sign is interpreted as a negative value. l Decimal Separator: Set the decimal separator for a numerical value. 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.
Note If you intend to use the field names as Metadata in a PReS Workflow process, do not add spaces to field names, as they are not permitted in Metadata field names. l Value: Displays the value of the extract field in the current Record. l Remove button : Click to remove the currently selected field. l Move Up button : Click to move the selected field up one position. l Move Down button : Click to move the selected field down one position.
Actions This subsection lists all actions executed by the step, and their types. l Name: A name by which to refer to the action. This name has no impact on functionality. l Type: l l l l l Set property: Sets the value of a record property which was created in the Preprocessor step (see "Preprocessor step" on page 262). Run JavaScript : Runs a JavaScript expression, giving much more flexibility over the extraction process.
l Based on: Determines the origin of the data. l Location: The contents of the data selection set below will be the value of the extracted field. The data selection settings are different depending on the data sample type. l Left: Defines the start of the data selection to extract l Right: Defines the end of the data selection to extract l l l Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Height: The height of the selection box.
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 is interpreted as a negative value. l Decimal Separator: Set the decimal separator for a numerical value.
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 389. l l l l Expression: The JavaScript expression to run.
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. XML and JSON files l Property: Displays a list of Source Record properties set in the Preprocessor step (see "Preprocessor step" on page 262). l Type: Displays the type of the Source Record property. Read only field. l Based on: Determines the origin of the data.
l l l Use JavaScript Editor: Click to display the Edit Script dialog (see "Using scripts in the DataMapper" on page 392 and "DataMapper Scripts API" on page 389). Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected.
l l Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Use selection: Click to use the value of the current data selection. Note If the selection contains multiple lines, only the first line is selected. Repeat step properties The Repeat step adds a loop to the extraction workflow; see "Steps" on page 262 and "Extracting transactional data" on page 245.
l For Each (for XML and JSON files only): The loop executes for all nodes (by default) or for selected nodes on the specified level. To have the loop execute only on selected nodes, you need to edit the Xpath/JsonPath in the Collection field (see below). If the path defines a rule that is true for more then one node/element, a collection of nodes/elements is returned and the For Each loop will go through all of them.
Rule Tree The Rule tree subsection displays the full combination of rules (defined below under Condition) as a tree, which gives an overview of how the conditions work together as well as the result for each of these conditions for the current record or iteration. Condition First, the Condition List displays the conditions in list form, instead of the tree form above. Three buttons are available next to the list: l Add condition: Click to create a new condition in the list.
l l l l l l l l l l l Trim: Select to trim empty characters at the beginning or the end of the field. Value: The text value to use in the comparison. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression.
l 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.
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.
l Value: A specified static text value. l l l l l l l l Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the "boundaries" on page 401 dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used.
l Invert condition: Inverts the result of the condition. For instance, is empty becomes is not empty. JSON files l Based On: l Position: The data in the specified position for the comparison. 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.
l Extractor Property: The value of an internal extractor variable: l l l Counter: The value of the current counter iteration in a Repeat step. Vertical Position: The current vertical position on the page, either in Measure (PDF) or Line (Text and CSV). Operators: l l l l l l is equal to: The two specified values are identical for the condition to be True. contains: The first specified value contains the second one for the condition to be True.
Rule tree The Rule tree subsection displays the full combination of rules (defined below under Condition) as a tree, which gives an overview of how the conditions work together as well as the result for each of these conditions for the current record or iteration. l l To rename a rule, double click on its name from the Rule tree subsection. To change the way rules are combined, right-click "AND". Select OR or XOR instead. XOR means one or the other, but not both.
l 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. 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.
l l l l l is equal to: The two specified values 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.
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 JsonPath (JSON only): The path to the JSON element that is extracted. (See: "JsonPath" on page 245.) Trim: Select to trim empty characters at the beginning or the end of the field. Value: A specified static text value. Value: The text value to use in the comparison.
only once at the beginning of each job. l l Automation Property: The current value of a Document-level property set in the Preprocessor step (see "Steps" on page 262). Extractor Property: The value of an internal extractor variable: l l Counter: The value of the current counter iteration in a Repeat step. Vertical Position: The current vertical position on the page, either in Measure (PDF) or Line (Text and CSV). Condition The Condition drop-down displays the cases in list form.
Goto step properties The Goto step moves the pointer within the source data to a position that is relative to the top of the record or to the current position. See also: "Steps" on page 262. The properties of the Goto step described in this topic become visible in the Step properties pane when you select the Goto step on the Steps pane. 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.
l Next line with content: Jumps to the next line that has contents, either anywhere on the line or in specific columns. l Inspect entire page width: When checked, the Next line with content and Next occurrence of options will look anywhere on the line. If unchecked, options appear below to specify in which area of each line the Goto step checks in: l Left: The starting column, inclusively. l Right: The end column, inclusively.
PDF file l Target Type: Defines the type of jump . l Physical distance: 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 distance to jump. Page: Jumps between pages or to a specific page. l l l From: Defines where the jump begins: From: Defines where the jump begins: l Current Position: The Goto begins at the current cursor position.
l l l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Expression: Enter the text or Regex expression to look for on the page. Use selection: Click while a selection is made in the Data Viewer to copy the contents of the first line of the selection into the Expression box. Use regular expression: Check so that the Expression box is treated as a regular expression instead of static text.
JSON file l Destination: Defines what type of jump to make: l l l l Sibling element: Jumps the number of siblings (elements at the same level) defined in the Move by option. Use a negative value to jump to the previous sibling, or a positive value to go to the next sibling. If there are not enough siblings to make the requested move, the cursor will not move. Element, from top of record: Jumps to the specified element. The JsonPath in the Absolute JsonPath option starts from the root defined by $.
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 389.
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.
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 389 for more details.
If you are new to PReS Connect and you don't know where to start, see "Welcome to PReS Connect 2021.1" on page 16. The Welcome Screen can be reopened in two ways: l The Welcome Screen button in the "Toolbars" on page 1081. 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.
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 448. Project Wizards: Displays a list of available Project Wizards, producing a complete Connect project; see "Project Wizards" on page 1000.
Name Description Available in scripts of type "db" on page 421 An object that allows to connect to a database. Boundaries, all steps except Goto "logger" on page 423 An object that allows to log error, warning or informational messages. Boundaries, all steps except Goto "record" on page 424 The current record in the main data set. Extract, Condition, Repeat and Multiple Conditions steps "region" on page 424 An object that defines a subsection of the input data.
Name Description "Functions" on page 434 Copies a file to the target file path, replacing it if it already exists. "createGUID()" on page 435 Returns a unique 36-character string consisting of 32 alphanumeric, lower case characters and four hyphens (format: 8-4-4-4-12). Example: 123e4567-e89b-12d3-a456426655440000. "createHTTPRequest()" on page 435 Creates a new HTTP Request Object.
Name Description page 440 "newStringArray()" on page 441 Returns a string array. "openBinaryReader()" on page 441 Opens a file as a binary file for reading purposes. "openBinaryWriter()" on page 441 Opens a file as a binary file for writing purposes. "openTextReader()" on page 441 Opens a file as a text file for reading purposes. "openTextWriter()" on page 443 Opens a file as a text file for writing purposes.
l Let an Action step run a JavaScript, for example to: l l l l Extract data to fields at the root level or in a detail table. See Extracting data with a Action step script. Add a value to a custom property defined in the Preprocessor step. (See "Properties and runtime parameters" on page 235.) Note that only the value of properties of which the scope is set to "Each record" can be changed in a script. Change the left and right operands in a Condition step to a JavaScript expression.
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 389).
(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.
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 389. 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.
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.
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.
[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.
Objects automation Returns a ScriptableAutomation object encapsulating the properties of the PReS 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.
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 235): automation.parameters.
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 404 Retrieves an array of strings. Boundaries "getVariable()" on page 404 Retrieves a value of a variable stored in the boundaries object.
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. Consequently, this change was reverted in 2018.1.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 424 and "createRegion()" on page 426. 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.createRegion(); see "createRegion()" on page 426.
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.
set the Boundary accordingly */ if((boundaries.currentDelim % 2) !=0 ) { /* Total is on odd page, let's set the document Boundary on delimiter further, thereby skipping the next blank page */ boundaries.set(1); } else { /* Total is on an even page, set the document Boundary to t current delimiter */ boundaries.set(); } } } setVariable() This method sets a variable in the boundaries to the specified value, automatically creating the variable if it doesn't exist yet.
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. Property Description filename Returns the fully qualified file name of the data file, i.e. the temporary work file being processed. properties Returns an array of the custom properties defined in the Preprocessor step that have their Scope set to "Entire data". These properties are statically set at the start of the job.
Method Description Script type File type "find()" on page 418 Finds the first occurrence of a string starting from the current position. Boundaries All Finds the first match for a regular expression pattern starting from the current position.
given position until the end of the record. Specifying an extraction height that is longer than the number of remaining lines results in a "step out of bound" error message. 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 l l "
" is a very handy string to use as a separator.
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.
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.
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 430). Example The script command data.extract('ID',0); means that the extraction is made on the ID column in the first row.
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.
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.
extract(jPath) Extracts the text value of the specified element in a JSON file. jPath JsonPath expression (String) that can be relative to the current location or absolute from the start of the record. See also: "JsonPath" on page 245. Example The script command data.extract('$[0].FirstName'); means that the extraction is made on the FirstName element found in the first element in the array at the root.
Note that in order to access an extracted object or array in script, the extracted value has to be parsed, for example: var myData = JSON.parse(data.extract('$[0]')); 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 a level in the PDF/VT or AFP. Case sensitive.
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 407.) fieldExists(levelName, propertyName) This method returns true if the given metadata field exists at the given level in a PDF/VT or AFP file. levelName String, specifying a level in the PDF/VT or AFP file. propertyName String, specifying the metadata field.
find() Method of the data object that finds the first occurrence of a string starting from the current position. find(stringToFind, leftConstraint, rightConstraint) Finds the first occurrence of a string starting from the current position. The search can be constrained to a series of characters (in a text file) or to a vertical strip (in a PDF file) located between the given constraints. The method returns null if the string cannot be found.
Number indicating the right limit to which the search is performed. This is expressed in characters for a text file, or in millimetres for a PDF file. Examples To look for the word "text" on an entire Letter page (8 1/2 x 11 inch), the syntax is: data.find("text", 0, 216); The numbers 0 and 216 are in millimeters and indicate the left and right limits (constraints) within which the search should be performed. In this example, these values represent the entire width of a page.
current page - of the smallest possible rectangle that completely encloses the first match for the regular expression. Note Calling this method does not move the current position to the location where the match occurred. This allows you to use the method as a look-ahead function without disrupting the rest of the data mapping workflow. regexpToFind Regular expression pattern to find. flags i: Enables case-insensitive matching.
and POSIX character classes are in conformance with Unicode Technical Standard #18: Unicode Regular Expression Annex C: Compatibility Properties. d: Enables Unix lines mode. In this mode, only the '\n' line terminator is recognized in the behavior of ., ^, and $. leftConstraint Number indicating the left limit from which the search is performed. This is expressed in characters for a text file, or in millimeters for a PDF file.
Method Description Available in page 423 connection object. Preprocessor, Extract, Condition, Repeat, Action, and Postprocessor steps File type connect() Method that returns a new database connection object. connect(url, user, password) This method returns a new database Connection object after connecting to the given URL and authenticating the connection with the provided user and password information. The function accepts arguments as described here: https://docs.oracle.
String that represents the name of the database user on whose behalf the connection is being made. This is used for authentication. password String that represents the user's password. This is used for authentication. Example Here's an example of how to connect to a mySQL database and retrieve a data value. con = db.connect ('jdbc:mysql://localhost:3306/mycompany','root','admin'); statement = con.createStatement(); values = statement.executeQuery("select * from datavalue"); if (values.next()) values.
record The current record in the main data set. Properties Property Description copies The total number of copies of the current record that must be created. By default, this is 1. This value is used when the record is saved, at the end of the data mapping process for each record. fields The field values that belong to this record. You can access a specific field value using either a numeric index or the field name, index The one-based index of this record, or zero if no data is available.
This object is available when triggering document boundaries On script, with all file types; see "Setting boundaries using JavaScript" on page 394. Properties The following table describes the properties and methods of the region object. Property/method Description Return Type found Field that contains a boolean value indicating if the last call to boundaries.find() was successful.
createRegion() This method sets the physical coordinates of the region object. The region is available when setting document boundaries using a script (see "region" on page 424). PDF and Text: createRegion(x1, y1, x2, y2) Creates a region from the data, using the specified left (x1), top (y1), right (x2) and bottom (y2) parameters, expressed in characters for a text file or in millimeters for a PDF file. x1 Double that represents the left edge of the region.
CSV or database: createRegion(columnName) Creates a region from the data in a CSV file, using the specified columnName parameter. columnName String containing the name of the column where the region is to be created. Example This script checks the first value in a certain column. If it is not the same value as in the previous record(s), a document boundary is set. var recordValue = boundaries.get(region.createRegion('ID'))[0]; if(!(recordValue==boundaries.getVariable('lastValue'))){ boundaries.
Property Description properties Returns an array of properties defined in the Preprocessor step with the Record Scope (i.e. dynamically reset with each new record). steps Returns a steps object encapsulating properties and methods pertaining to the current DataMapper process. This object is available in an Extract, Condition, Repeat or Multiple Conditions step script. Methods and properties The following table lists the methods and properties of the steps object.
Method Description File type currentPageHeight The height of the current page in millimeters. PDF currentPageWidth The width of the current page in millimeters. PDF "moveTo()" on the facing page Moves the pointer in the source data file to another position. All "moveToNext()" on page 432 Moves the position of the pointer in the source data file to the next line, row or node. The behavior and arguments are different for each emulation type: text, PDF, tabular (CSV), or XML.
In this example, an extraction area is assigned to the variable curLine each time the current page value has changed. curPage = steps.currentPage; for(i=0;i<100;i++) { if(steps.currentPage > curPage) { let curLine = data.extract(51, 88, 0, 1, "").trim(); curPage++; } } moveTo() Moves the position of the pointer in the source data file. This is a method of the steps object (see "steps" on page 428).
Example The following line of code moves the current position in a text file 14 lines down from the current vertical position (steps.currentPosition) of the pointer in the data, as long as it is on the same page. if(steps.currentPage > curPage) { steps.moveTo(0, steps.currentPosition+14); curPage++; } moveTo(scope, verticalOffset) Moves the current position in a PDF file to verticalOffset where the meaning of verticalOffset changes according to the value specified for scope.
Tip TheXML elementsdrop-down (on the Settings pane, under Input Data) lists xPaths defining nodes in the current XML file. moveTo(row) Moves the current position in a CSV file to the given row number. row Number that represents the index of the row, relative to the top of the record.
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.
l 1 or steps.MOVESIBLING: the current position is set to the next element in the same parent, i.e. the next element in an array or the next key-value pair in an object. moveToNext(left, right) Moves the current position in a PDF file to the next line that contains any text, the search for text being contained within the left and right parameters, expressed in millimeters. left Double that represents the left edge (in millimeters) of the text to find.
createGUID() This function returns a unique 36-character string consisting of 32 alphanumeric, lower case characters and four hyphens. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12 characters).| Example: 123e4567-e89b-12d3-a456-426655440000. The function produces unique strings on each and every call, regardless of whether the call occurs within the same data mapper or not, or on concurrent threads.
Supported properties l response l status l statusText l timeout (ms). Default: 1 minute. Supported methods create() l l open(String method, String url, String user, String password) open(String verb, String url, String userName, String password, String[] headers, String[] headervalues, String requestBody) l send() l send(String requestBody) Creates a new instance of ScriptableHTTPRequest. Opens a HTTP request. Note If you don't use a user name and password, pass empty strings: request.
HTTP request. setRequestBody(String requestBody) Sets the HTTP request body (for POST and PUT). getPassword() Gets the password for HTPP basic authentication setPassword(String password) Sets the password for HTPP basic authentication getTimeout() Gets the time to wait for the server's response setTimeout(int timeout) Sets the time (in ms.) to wait for the server's response. getUsername() gets the username for basic HTTP authentication.
var tmpFile = createTmpFile(); // Open a writer on the temporary file var writer = openTextWriter(tmpFile.getPath()); try{ var line = null; // Current line /* read line by line and readLine will return null at the e the file */ while( (line = reader.readLine()) != null ){ // Edit the line line = line.toUpperCase(); // Write the result in the temporary file writer.write(line); // add a new line writer.newLine(); } } finally{ // Close the writer of the temporary file writer.
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. execute(command) Calls an external program and waits for it to end. command String that specifies the path and file name of the program to execute. newByteArray() Function that returns a new byte array. newByteArray(size) Returns a new byte array of of the specified number of elements.
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. newFloatArray(size) Returns a new Float array of the specified number of elements. size Integer that represents the number of elements in the new array. newIntArray() Function that returns a new array of Integers. newIntArray(size) Returns a new Integer array of the specified number of elements.
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. openBinaryReader() Function that opens a file as a binary file for reading purposes. The function returns a DataInputStream (see DataInputStream). openBinaryReader(filename) filename String that represents the name of the file to open.
openTextReader(filename,encoding) filename String that represents the name of the file to open. encoding String that specifies the encoding of the file to read (UTF-8, ISO-8859-1, etc.). Example In the following example, the openTextReader() function is used to open the actual data sample file in the DataMapper for reading. var var var var fileIn = openTextReader(data.filename); tmp = createTmpFile(); fileOut = openTextWriter(tmp.getPath()); line; while((line = fileIn.readLine())!=null){ fileOut.
Method Description open(inStream, inEncoding) Creates a reader from an input stream. Parameters: open(inFileName, inEncoding) parseCharset (inEncoding) l inStream: the input stream to read l inEncoding: the encoding to use when reading the file Creates a reader on the specified file. Parameters: l inFilename: the path of the file to read l inEncoding: the encoding to use when reading the file Returns a character set (Charset).
String that represents the name of the file to open. encoding String specifying the encoding to use (UTF-8, ISO-8859-1, etc.).. 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). Example In the following example, the openTextWriter() function is used to open the newly created temporary file for writing: var var var var fileIn = openTextReader(data.
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.
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.
page 448. 2. Fill the template Add text, images and other elements to the template and style them. See "Content elements" on page 631 and "Styling and formatting" on page 743. 3. Personalize the content Personalize the content using variable data. See "Personalizing content" on page 787. 4. Generate output Adjust the settings, test the template and generate output: letters, emails, and/or web pages. See "Generating output" on page 1458.
l "Print" on page 473. This topic helps you design and fill sections in the Print context. l "Email" on page 515. This topics helps you design an email template. l "Web" on page 541. This topic helps you design a web page. "Sections" on page 469. Sections in one context are designed for the same output channel. "Content elements" on page 631. Elements make up the biggest part of the content of each design. "Snippets" on page 739.
There are Wizards for each output channel, or contexts as they are called in the Designer: Print, Email and Web. See: l "Creating an Email template with a Wizard" on page 520 l "Creating a Print template with a Wizard" on page 476 l "Creating a Web template with a Wizard" on page 542 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.
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 452). To open a package file, switch the file type to Package files (*.OL-package) in the Open File dialog.
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. Associated data mapping configuration When you save a template, any data mapping configuration that is currently open will be associated with the template by saving a link to the data mapping configuration in the template file. The next time you open the template you will be asked if you want to open the associated data mapping configuration as well.
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 963. The file properties can also be used in scripts; see "template" on page 1426. If you are not familiar with writing scripts, refer to "Writing your own scripts" on page 875.
Package files can be opened by other Connect users. They can also be imported into Workflow and sent to the Connect Server. To open the Package dialog, select File > Package.... For an explanation of the options in the Package dialog, see "Package dialog" on page 987.
Sending files to Connect Server or to another 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 Server dialog provides a way to send templates, data mapping configurations and print presets to the Connect Server directly, or to another server.
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 580. A Web Template Wizard helps you create a Web page that looks good on virtually any browser, device and screen size.
l Jumbotron l Thank You If you don't know what template to choose, see "Web Template Wizards" on page 458 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.
the type of web page, a navigation bar, button and/or Form elements. l l l 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. The JavaScript files are located in the JavaScript folder on the Resources pane, in a Foundation folder. A collection of Snippets in the Snippets folder on the Resources pane.
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.
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.
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. Use this wizard as a way to quickly start any new Zurb Foundation based form for Capture OnTheGo. Event Registration.
4. Click Next to go to the next settings page if there is one. 5. Click Finish to create the template. The Wizard creates: l l l A Web context with one web page template (also called a section) in it. The web page contains an 'off-canvas' Div element, Header, a Section and a Footer element with dummy text, and depending on the type of web page, a navigation bar, button and/or Form elements.
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 707. To learn how to use them, see "Using COTG Elements" on page 594. 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.
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. Internal resources Internal resources are files that are added to and saved with the template.
See also: "Loading a snippet via a script" on page 902 and "Writing your own scripts" on page 875. Note When referring to images or fonts from a CSS file, you need to remember that the current path is css/, meaning you can't just call images/image.jpg. Use a relative path, for example: #header { background-image: url('../images/image.jpg'); } External resources External resources are not stored in the template, but on the local hard drive or on a network drive. They are accessed using a path.
l l "Static Resources", as set in the preferences, are accessed using the resource path, by default something like http://servername:8080/_iRes/images/image.jpg. (For guidance on setting the preferences, search for 'HTTP Server Input 2' in the PReS Workflow help files on: OL Help). Resources can also be served by processes: http://servername:8080/my_ process?filename=image.jpg (assuming "my_process" is the action in the HTTP Server Input).
1. Click the Add button ( ). 2. Give the parameter a name. 3. Select the data type. This impacts the way the data can be handled in a script; for example, if a parameter's type is Number, its value can be used directly in calculations, without having to parse it first. In the Parameters pane, the type of a runtime parameter can be recognized by its icon. 4. Optionally, set a default value. A default value will only be used in the case that there is no actual value coming from the automation tool, e.g.
l 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. If the Data Model contains a JSON Record Data List (see "A JSON Record Data List" on page 974), you could edit the runtime parameters by adding or editing the parameters object using the "JSON sample data dialog" on page 972.
with an Email Template Wizard; see "Creating an Email template with a Wizard" on page 520. Outputting and combining contexts All contexts can be present in any template and they can all be used to output documents; see "Generating Email output" on page 1488, "Generating Print output" on page 1460 and "Generating Web output" on page 1499. They can even be combined in output. If present in the same template, a Print context and a Web context can be attached to an Email context.
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 870. Sections Sections are parts of one of the contexts in a template: Print, Email or Web.
Editing a section To open a section, expand the Contexts folder on the Resources pane, expand the respective context (Print, Email or Web) and double-click a section to open it. Each section can contain text, images and many other elements (see "Content elements" on page 631), including variable data and other dynamic elements (see "Personalizing content" on page 787). To preview a section, open the Preview tab in the Workspace (see "Workspace" on page 1078). Copying a section To copy a section: 1.
Deleting a section To delete a section: l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, right-click the name of the section, and then click Delete. Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored, or by reverting to the last saved state (click File > Revert, on the menu).
1. Click and hold the mouse button on the style sheet on the Resources pane. 2. Move the mouse cursor within the Resources pane to the section to which the style sheet should be applied. 3. Release the mouse button. Using the Includes dialog 1. On the Resources pane, right-click the section, then click Includes. 2. From the File types dropdown, select Stylesheets. 3. Choose which CSS files should be applied to this section. The available files are listed at the left.
l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, and then drag and drop sections to change the order they are in. Alternatively, right-click a section and click Arrange. In the Arrange Sections dialog you can change the order of the sections in the same context by clicking the name of a section and moving it using the Up and Down buttons. Outputting sections Which sections are added to the output, depends on the type of context they are in.
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.
Headers, footers, tear-offs and repeated elements (Master page) In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear on each first page, or only on pages in between the first and the last page, or only on the last page. Examples are a different header on the first page, and a tear-off slip that should show up on the last page. This is what Master Pages are used for.
For more information about this feature see "Copy Fit" on page 760. Creating a Print template with a Wizard A Print template may consist of various parts, such as a covering letter and a policy. Start with one of the Template Wizards for the first part; other parts (called 'sections') can be added later. Print template wizards can be found in the Welcome screen and on the File menu.
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. Postcard The Postcard Wizard lets you choose a page size and two background images, one for the front and one for the back of the postcard.
Formal letter The Formal Letter Wizard first lets you select the page settings, see "Page settings: size, margins and bleed" on page 497. These settings are fairly self-explanatory, except perhaps these: l l l l Duplex means double-sided printing. The margins define where your text flow will go. The actual printable space on a page depends on your printer. The bleed is the printable space around a page. It can be used on some printers to ensure that no unprinted edges occur in the final trimmed document.
The Wizard opens the Print section. You can add text and other elements; see "Content elements" on page 631. The formal letter template already has an address on it. The address lines are paragraphs, located in one cell in a table with the ID address-block-table. As the table has no borders, it is initially invisible. The address lines will stick to the bottom of that cell, even when the address has fewer lines. See "Styling and formatting" on page 743 to learn how to style elements.
l l l A Print context with one section in it; see "Print context" on the next page and "Print sections" on page 486. The selected PDF is used as the background of the Print section; see "Using a PDF file or other image as background" on page 491. For each page in the PDF one page is created in the Print section. One empty Master Page. Master Pages are used for headers, footers, images and other elements that have to appear on more than one page, and for special elements like tearoffs.
Tip Nice to know: your info and preferences are saved and will be reused the next time you create an ERP template. When you click Finish, the Wizard creates: l l l l A Print context with one section in it; see "Print context" below and "Print sections" on page 486. One Master Page. Master Pages are used for headers and footers, for images and other elements that have to appear on more than one page, and for special elements like tearoffs. See "Master Pages" on page 505. One Media.
Creating the Print context You can start creating a Print template with a Wizard (see "Creating a Print template with a Wizard" on page 476), or add the Print context to an existing template (see "Adding a context" on page 468). Tip Editing PDF files in the Designer is not possible, but when they're used as a section's background, you can add text and other elements, such as a barcode, to them.
Initially, the (empty) master page that has been created with the Print context will be applied to all pages in the Print section, but more Master Pages can be added and applied to different pages. l l One Media is added to the template, as is visible on the Resources pane, in the Media folder. This folder can hold the company's stationery in the form of PDF files.
Note Your printer must support duplex for this option to work. Setting the binding style for the Print context The Print context , as well as each of the Print sections, can have its own Finishing settings. In printing, Finishing is the way pages are bound together after they have been printed. Which binding styles can be applied depends on the type of printer that you are using. To set the binding style of the Print context: 1.
Overprint and black overprint Normally, when two colors overlap in Print output, the underlying color is not printed. It is "knocked out", for two reasons: firstly, the underlying color may affect the top color, especially if the top color is lighter than the underlying color. Secondly, not printing an underlying color, which is not visible anyway, will save ink or toner.
Print sections 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 1460). The Print context can also be added to Email output as a PDF attachment; see "Generating Email output" on page 1488. 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.
Using stationery (Media) When the output of a Print context is meant to be printed on paper that already has graphical and text elements on it (called stationery, or preprinted sheets), you can add a copy of this media, in the form of a PDF file, to the Media folder. Media can be applied to pages in a Print section, to make them appear as a background to those pages. This ensures that elements added to the Print context will correspond to their correct location on the preprinted media.
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.
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 818. You can use the Conditional Content script wizard to hide parts of the content of a section; see "Showing content conditionally" on page 814. Importing a Print section To import a section from another template, click File > Import Resources... in the menu. See: "Import Resources dialog" on page 969.
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.
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. included in) a section show a chain icon in the Resources pane (see "Resources pane" on page 1067).
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. 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.
l Fit to page stretches the PDF to fit the page size. l Centered centers the PDF on the page, vertically and horizontally. l Absolute places the PDF at a specific location on the page. Use the Top field to specify the distance between the top side of the page and the top side of the PDF, and the Left field to specify the distance between the left side of the page and the left side of the PDF.
Alternatively you could write your own Control Script to set the background; see "Control Script: Setting a Print section's background" on page 920. The settings in a script take precedence over the settings made in the Print Section Properties dialog. Setting the binding style for a Print section In printing, Finishing is the binding style, or the way pages are bound together.
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. This changes the Duplex job into a Mixplex job.
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.
Although generally the same content elements can be used in all three contexts (see "Content elements" on page 631), the specific characteristics of pages make it possible to use special elements, such as page numbers; see "Page numbers " on page 499. The widow/orphan setting lets you control how many lines of a paragraph stick together, when content has to move to another page; see "Preventing widows and orphans" on page 501.
l On the Resources pane, right-click a section in the Print context and click Properties. For the page size, click the drop-down to select a page size from a list of common paper sizes. Changing the width or height automatically sets the page size to Custom. Margins define where your text flow will go. Static elements can go everywhere on a page, that is to say, within the printable space on a page that depends on the printer. The bleed is the printable space around a page.
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. Do not place the promotional image or snippet inside an absolute positioned box. Whitespacing only works for elements that are part of the text flow, not for absolute-positioned boxes. 3.
in the Sheet Configuration dialog, see "Applying a Master Page to a page in a Print section" on page 507) but no contents, is not included in the Content page count. l l l Content page count: This is the total number of pages in the current document that have contents, supplied by the Print section. A page that has a Master Page but no contents, is not included in the Content page count. Sheet number: The current sheet number in the document.
Configuring page numbers By default the page numbers are Arabic numerals (1, 2, 3, etc.) without leading zeros nor prefix, and page numbering starts with page 1 for each section. But this can be changed. To do that: 1. On the Resources pane, right-click a section in the Print context and click Numbering. 2. Uncheck Restart Numbering if you want the page numbers to get consecutive page numbers, instead of restarting the page numbering with this section.
Note 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 504. In the entire Print context To prevent widows and orphans in the entire Print context: 1. On the menu, select Edit > Stylesheets. 2. Select the Print context. 3. Click New (or, when there are already CSS rules for paragraphs, click the selector p and click Edit). 4. Click Format. 5.
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. Splitting a Standard Table over multiple pages requires setting the Connect-specific data-breakable attribute on all of its rows.
3. In the Breaks group, set the before or after property. l l Before: Sets whether a page break should occur before the element. This is equivalent to the page-break-before property in CSS; see CSS page-break-before property for an explanation of the available options. After: Sets whether a page break should occur after the element. Equivalent to the page-break-after property in CSS; see CSS page-break-after property for an explanation of the available options.
Master Pages In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear only on specific pages, such as only the first page, or the last page, or only on pages in-between. Examples are a different header on the first page, and a tear-off slip that shows up on the last page. This is what Master Pages are used for. Master Pages can only be used in the Print context (see "Print context" on page 481).
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 969. Editing a Master Page Master Pages are edited just like sections, in the workspace. To open a Master Page, expand the Master pages folder on the Resources pane, and double-click the Master Page to open it.
2. Next, define the margins for the header and footer. The margins for a header and footer are set in the Master Page properties. This does not change the content placement within the Master Page itself; in Master Pages, elements can go everywhere on the page. Instead, the header and footer of the Master Page limit the text flow on pages in the Print sections to which this Master Page is applied.
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 501). Note that if the Omit empty back side for Last or Single sheet option (see "General options" on page 1024) is checked as well, the empty backside will not appear in the output at all and will not be counted in any case. 5.
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. Adding Media To add a Media, right-click the Media folder on the Resources pane and select New Media. The new Media is of course empty. You can specify two PDF files for the Media: one for the front, and, optionally, another for the back.
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. On the Virtual Stationery tab, you can click the Select Image button to select a PDF image file. Note Encrypted PDF files are not supported in PDF pass-through mode. See "PDF Options" on page 1196. l Click Resources, Disk or Url, depending on where the image is located.
they are used internally. Therefore, URLs that rely on one of these parameters cannot be used. l With an external image, you can check the option Save with template. If this option is checked, the file will be inserted in the Images folder on the Resources pane at the top left. If it isn't saved with the template, the image remains external.
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. Weight: The intended weight of the media in grammage (g/m2). Front Coating: The pre-process coating applied to the front surface of the media, such as Glossy, High Gloss, Matte, Satin, etc.
2. Optionally, check Duplex to enable content to be printed on the back of each sheet. Your printer must support duplex for this option to work. If Duplex is enabled, you can also check Tumble to duplex pages as in a calendar, and Facing pages to have the margins of the section switch alternately, so that pages are printed as if in a magazine or book. 3. If the option Same for all positions is checked, the same Media will be applied to every page in the print section. Uncheck this option. 4.
3. In the area for the respective sheet position, click the Edit script button next to Media. The Script Wizard appears with a standard script: results.attr("content","Media 1"); Media 1 will have been replaced with the name of the media selected for the chosen sheet position. The field Selector in the Script Wizard contains the name of the section and the sheet position that you have chosen. 4. Change the script so that on a certain condition, another media will be selected for the content.
l Section backgrounds are rotated separately (see "Using a PDF file or other image as background" on page 491). If in the Media properties, the Virtual Stationery position is set to Absolute, any offset given by the Top and Left values will be applied after rotation. A Virtual Stationery image located absolutely at the top left (Top: 0, Left: 0) will still appear at the top left of the page after rotating the Media. Printing virtual stationery Media are not printed, unless you want them to.
When an Email template is created, either with a Wizard or by adding an Email context to an existing template (see "Adding a context" on page 468), the Email context folder is created along with other files that are specific to an Email context; see "Email context" on page 524. Only one Email section is created at the start, but you can add as many Email sections as you need; see "Email templates" on page 526.
This topic explains why designing HTML email design is as challenging as it is, which solutions are used in the Email Template Wizards and it lists good practices, for example regarding the use of images in HTML email. It will help you to create the best possible Email templates in the Designer. HTML email challenges Creating HTML email isn't like designing for the Web. That's because email clients aren't like web browsers.
Tip Click the Edges button on the toolbar to make borders of elements visible on the Design tab. The borders will not be visible on the Preview tab or in the output. Litmus There are several tools to preview how email will be rendered on a variety of clients. We recommend using Litmus. Support for Litmus is integrated into the Designer; the Send Test Email dialog has an option to "Send to Litmus".
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 861. Using CSS files with HTML email Email clients do not read CSS files and some even remove a
