User Guide Version: 1.
User Guide Version 1.8 Last Revision: 2019-05-23 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-2019. 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.
Table of Contents Table of Contents 4 Welcome to PReS Connect 1.
GoDaddy Certificates MySQL Compatibility PostScript Print Presets Available Printer Models External Resources in Connect Using Capture After Installing Workflow 8 Capturing Spool Files After Installing Workflow 8 Colour Model in Stylesheets Image Preview in Designer Merge\Weaver Engines when Printing REST Calls for Remote Services Print Content and Email Content in PReS Workflow Print Limitations when the Output Server is located on a different machine VIPP Output Server Configuration Settings Scheduling Pr
Creating a new data mapping configuration Opening a data mapping configuration Saving a data mapping configuration Using the wizard for CSV and Excel files Using the wizard for databases Using the wizard for PDF/VT and AFP files Using the wizard for XML files Data mapping workflow Creating a data mapping workflow Testing the extraction workflow Data source settings Extracting data Steps The Data Model Creating a Data Model Editing the Data Model Using the Data Model Fields Detail tables Data types Data Mode
Condition Operators Text file PDF File CSV File XML File JavaScript Toolbar Welcome Screen DataMapper Scripts API Using scripts in the DataMapper Setting boundaries using JavaScript Objects Example Example Examples Example Example Example Examples Examples Example Example Example Text XML Functions The Designer Designer basics Features Templates Contexts Sections Print Copy Fit Creating a Print template with a Wizard Print context 250 250 251 252 254 254 256 256 258 259 262 264 269 273 275 278 280 281 283
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 Testing the template Sending the template to the Workflow tool Using COTG data in a template Designing a COTG Template Capture OnTheGo template wiza
Editing HTML Attributes Inserting an element Selecting an element Deleting an element Styling and formatting an element Barcode Boxes Business graphics COTG Elements Date Forms Form Elements Hyperlink and mailto link Images Table Text and special characters Snippets Adding a snippet to the Resources Adding a snippet to a section Creating a snippet JSON Snippets Styling and formatting Local formatting versus style sheets Layout properties Styling templates with CSS files Styling text and paragraphs How to po
Personalizing Content Variable data Conditional content Dynamic images Dynamic tables Snippets Scripts Loading data Variable Data Formatting variable data Showing content conditionally Conditional Print sections Dynamic Images Dynamic table Personalized URL Writing your own scripts Script types Creating a new script Writing a script Managing scripts Testing scripts Optimizing scripts Loading a snippet via a script Loading content using a server's RESTful API Control Scripts The script flow: when scripts run
Designer Script API Designer Script API Examples Examples Examples Examples Examples Examples Examples Examples Examples Examples Examples Examples Examples Example Example Example Example Example Examples Creating a table of contents Example Examples Examples Examples Examples Replace elements with a snippet Replace elements with a set of snippets Example Example Creating a Date object from a string Control Script API Examples Generating output Print output Email output 884 885 893 894 895 897 900 900 901
Web output Optimizing a template Scripts Images Generating Print output Saving Printing options in Print Presets Connect Printing options that cannot be changed from within the Printer Wizard Print Using Standard Print Output Settings Print Using Advanced Printer Wizard Adding print output models to the Print Wizard Splitting printing into more than one file Print output variables Generating Fax output Generating Tags for Image Output Generating Email output Email output settings in the Email context and se
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 Previous Releases Overview Connect 1.7.1 General Enhancements and Fixes Connect 1.7.1 Designer Enhancements and Fixes Connect 1.7.
Connect 1.4.1 Output Enhancements and Fixes Connect 8.4.
Welcome to PReS Connect 1.8 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 30 l "Known Issues" on page 82 l "Server Configuration Settings" on page 87 l Uninstalling System and Hardware Considerations There are a variety of considerations to be aware of.
Directories and folders Main installation folder All Connect applications are installed under an arbitrarily selectable main folder. We will refer to it as the "Installation Target" hereafter. The installation target will hold the executables and files and sub-folders required for the operation of the whole product suite. All these files and folders are static after installation. It depends upon the company virus protection strategy, if such files and folders are to be monitored or not.
Virus protection on this folder and contents may have an impact on the speed of the whole Connect suite. l l %USERPROFILE%\Connect\temp: Storage folder for temporary data, usually intermittent files in multiple folders. Virus protection on this folder and contents might have a serious impact on the performance of Connect. %USERPROFILE%\Connect\workspace: Usually containing settings and helper files and folders.
These are the specific options that have been changed in our version of "my.ini": l l l max_connections = 200 : PReS Connect uses a lot of database connections. This number ensures that even in high volume environments, enough connections will be available. max_allowed_packet = 500M : In some implementations, especially when using Capture OnTheGo, large packet sizes are required to allow transferring binary files.
l l l The Configuration page for the local MySQL is displayed. MySQL settings are pre-filled with default values if no existing MySQL db configuration is found. MySQL settings are pre-filled with existing db configuration settings, if they point to a MySQL db type.
Updating With No Local MySQL Product l l When updating a Connect installation from 1.5.0 which contains a Server Product but no local MySQL Product, the DB Configuration Page will detect which db type was set before (especially if the db configuration was switched from MySQL to MS SQL using the Server Configuration Tool), and default to those settings. On Update from 1.4.
6. Enter the command sc config OLConnect_Server depend= /. This removes the dependency. Please be aware: The key word depend must be followed immediately by the equal sign, but between the equal sign and the forward slash there must be a space. Additional information can be found here: http://serverfault.com/questions/24821/howto-add-dependency-on-a-windows-service-after-the-service-is-installed#228326. 7.
After this modification, the local MySQL is removed, and also the service dependency from Server to MySQL is removed. Note If Connect was initially installed not containing the local MySQL product (i.e. on 1.5 installation an external MySQL was configured as database), then the Update to 1.6 will allow to select either external MySQL or external Microsoft SQL on the DB Configuration Page.
be supported by Objectif Lune Inc.. Furthermore, using PReS Connect in a Terminal Service environment is an infringement of our End-User License Agreement. Remote Desktop Tests have demonstrated that PReS Connect can be used through Remote Desktop. It is however possible that certain combination of OS could cause issues. If problems are encountered, please contact OL Support and we will investigate. PReS Connect 1.3 and later have been certified under Remote Desktop.
Commandline switches and .ini entries PReS Connect is intended to work stably and reliably, based on Java and the Eclipse framework. To ensure this reliability and robustness, many Java and Eclipse parameters have been tested and tuned, which is reflected in the respective .ini entries and the used command line switches. A collection of valuable settings has been elaborated and found its entry in PReS Connect “good switches list” (called the “whitelist”).
l Encoding: l Issues can sometimes be encountered in menus and templates when running PReS Connect on a non-English operating system. These are due to encoding issues and will be addressed in a later release.
l l l Mix and match. For example, one instance prioritized for large jobs and the rest for smaller, quicker jobs. Or the contrary. Or, whatever you want, really. RAM Configuration: By default, each instance of the Merge Engine and Weaver Engine is set to use 640MB of RAM. This means that regardless of speed units, if not enough memory is available, output speed might not be as expected.
l l l External JavaScript libraries: While loading a single JavaScript library from the web is generally very fast (and only done once for the record set), actually running a script on each generated page can take some time. Because yes, JavaScript will run for each record, and often take the same time for each record. Inefficient selectors: Using very precise ID selectors in script wizards can be much faster than using a text selector, especially on very large documents.
low, it makes sense to see if that can be increased. When running on a virtual machine, this is usually easy. When running on a physical machine, it means that you may have to switch hardware. l For both virtual and non-virtual environments, make sure the machine is not busy with all kinds of other processes. System Requirements These are the system requirements for PReS Connect 1.
Installation and Activation This topic provides detailed information about the installation and activation of PReS Connect 1.8. Note A PDF version of this guide is available for use in offline installations. Click here to download it. PReS Connect 1.8 is comprised of 2 different installers: one for the PReS Connect software and one for PReS Workflow 8. Where to obtain the installers The installers for PReS Connect 1.
l Installation l Silent Installation l Installation on machines without Internet access Activation For information on licensing, please see Activating your license. Installation Prerequisites l l l l l l Make sure your system meets the System requirements. PReS Version 1.8 can be installed under a regular user account with Administrator privileges. PReS must be installed on an NTFS file system. PReS Connect requires Microsoft .NET Framework 4.5 already be installed on the target system.
Note From PReS Connect Version 1.2 onwards, the new version (1.1.8) of the Update Client is included by default with all setups. User accounts and security Permissions for PReS Connect Designer PReS Connect Designer does not require any special permissions to run besides a regular program. It does not require administrative rights and only needs permission to read/write in any folder where Templates or Data Mapping Configurations are located.
The Importance of User Credentials on Installing and Running PReS Connect OL Connect and required credentials depends heavily on the Connect component and respective tasks and what sort of user credentials are needed. First of all, it is important to distinguish between installation and run-time Installation The Connect installer puts all required files, folders, registry entries and much more to their correct places and locations.
Additionally, the Server user must be able to access any network resources that are required for OL Connect to function properly. This includes e.g. additional drives, printers, scanners, other computers and, where appropriate, internet resources, URLs, mail servers, FTP servers, database servers and everything else planned to be used for the intended operation of Connect. The Server user is the run-time user.
Installing PReS Connect on Machines without Internet Access Installing PReS Connect1.8 in offline mode requires some extra steps. These are listed below. GoDaddy Root Certificate Authority needs to be installed. In order to install PReS Connect it is necessary for the GoDaddy Root Certificate Authority to be installed (G2 Certificate) on the host machine and for this to be verified online.
To circumvent such issues it is highly recommended to switch off the CRL retrieval prior to installing Connect on machines without internet access. There is no security risk associated with this, as the CRLs would never be retrievable without internet access, anyway. Advantage of the switch will not only be found during the installation and operation of Connect, but also in some speed improvements for any application which use signed binaries.
Note If the same version of PReS Connect is already installed on the target machine, you will be presented with options to either Uninstall or Modify the existing instance. If Modify is selected, the standard installation Wizard sequence will be followed, but with all options from the existing installation selected. 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.
Warning If you chose not to install the supplied MySQL database, and instead opt for using a pre-existing external database then you must ensure that your external database is accessible to Connect, yourself. Objectif Lune Inc. will take no responsibility for database connections to any but the supplied MySQL database. See "Database Considerations" on page 18 for more information about setting up external databases.
l l l Disk space available on drive: Displays the amount of space available for installation on the drive currently in the Installation Path. Recalculate disk space: Click to re-check available disk space. This is useful if space has been made available for the installation while the installer was open. Source repository location: Displays the path where the installation files are located. This can be a local drive, installation media, or a network path.
Note When updating from an earlier Connect version, the appropriate MySQL password must be entered or the update will fail. If the password is subsequently forgotten, then the MySQL product must be uninstalled and its database deleted from disk before attempting to reinstall. l l Confirm 'root' Password: Re-enter to confirm the password. Both passwords must match for installation to continue. TCP/IP Port Number: The port on which MySQL will expect, and respond to, requests.
external requests. Configuring External Database Connection The Database Connection page appears if the supplied MySQL Product 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 l Database Configuration: Select the database type to use for the PReS Connect Engine. Currently only MySQL and Microsoft SQL Server are supported. Administrator Username: Enter the username for a user with administrative rights on the database.
PReS Connect Server/Server Extension Configuration The Server Configuration page is where either the Connect Server or Connect Server Extension component is configured, depending upon whether the Connect Server (Master) or Connect Server Extension (Slave) option was selected as part of the installation. The Connect Server (Master) settings are as follows:. l Run Server as: Defines the machine username and password that the PReS Connect Server module's service uses.
Note Before installing the software, make sure that both TCP/IP ports 3306 and 9340 are open on the Connect Master Server and Connect Extension Server, in both the Inbound and Outbound Firewall Rules. Access within the Private and Domain profiles is sufficient.
Note There is no requirement for the Master and Extension servers to belong to the same IP subnet. IP subnetting is beyond the scope of this documentation, but more information can be found here: https://en.wikipedia.org/wiki/Subnetwork l l l Port: Enter the port to use to communicate with the Connect Server. The Connect Server controlled by the OLConnect_Server service communicates through port 9340 by default.
application, it will be updated to the latest version and will retain the settings previously specified. Select the desired options and then click OK to query the server and obtain a list of any updates that are available for your software. l l Note that the Product Update Manager can also be called from the “Objectif Lune Update Client” option in the Start menu. It can be uninstalled via Control Panel | Programs | Programs and Features.
l Comment Lines, starting with # (e.g. # The options to configure an external database) l Key = Value pairs (e.g. install.product.0 = Connect Designer) For supported keys, please refer to the next paragraph. Note 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.
server.master.username = server.master.password = Database configuration Case 1: MySQL is among the selected Connect products to be installed (new MySQL installation) If MySQL is selected and there is no previous MySQL configuration on the machine, the following properties should be defined: database.password = (required and must meet the rules) database.port = (3306 is the default port value) database.
Case 2: The Connect Server or the Connect Server Extension is selected and the MySQL Product is not selected In this case, an external database must be configured for the Server (and other Connect products included in the Silent installation) to be used. 2a: Configuring an external MySQL database To configure an external MySQL database, the following properties should be defined: database.type = mysql (required) database.host = (default value is localhost, otherwise required) database.
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.
Sample batch file @echo off preinstall.exe if errorlevel 10 goto err_installer if errorlevel 2 goto err_unknown 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.
l Open the Start Menu l Click on All Programs, then Objectif Lune, then PReS Connect l Open the PReS Connect Designer [version] shortcut. l When the application opens, if it has never been activated or the activation has expired, the Software Activation dialog appears: l License Information subsection: l l l l l l l l l l Name: Displays the name of the application or module relevant to this activation.
Note The Software Activation dialog can also be reached through a shortcut located in All Programs, then Objectif Lune, then PReS Connect and is named Software Activation. Since it does not load the software, it is faster to access for the initial activation.
Activating PReS Connect To activate PReS Connect, simply save the license file somewhere on your computer where you can easily find it, such as on your desktop. You can then load the license by doubleclicking on it, or through the start menu: l Open the Start Menu l Click on All Programs, then Objectif Lune, then PReS Connect l Open the PReS Connect Designer [version] shortcut. The “PReS Connect Software Activation” tool displays information about the license and the End-User License Agreement (EULA).
l Environment Considerations l Installation Pre-Requisites l Antivirus Exclusions Downloading and Installing the Software In order to migrate to a new workstation, the software must already be installed on the new workstation. Follow the Installation and Activation Guide to download and install the newest version of PReS Connect on the new workstation. If using Clustering, please read the Server Clustering page of this documentation for more details relevant to the installation.
PlanetPress Workflow 8 folder directly, it's important to delete any file with the .ps7 extension so as to refresh the postscript file for the new workstation. l l l l l l l l l The Workflow configuration file itself is named ppwatch.cfg, and is backed up with the folders. However, it needs to be re-sent to the Service to be used. To do this, rename the file to .OL-Workflow, open the file with the Workflow tool, and send the configuration. Locate Custom Plugins (.
l l If required, grant permissions to other machines (Designer clients and other servers) to send documents and jobs to the new server.
Other Resources 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 Workflow button on top left corner and clicking on Preferences, then reconfigure the PlanetPress Capture options under Behavior >PlanetPress Capture > Use ODBC Database l 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 • Re-install OL Connect Send on the new Workstation.
l l C:\Program Files\Objectif Lune\OL Connect\weaverengine\weaverengine.ini Now start the OLConnect_Server service Configuring the Server Extensions In the case where the OLConnect MySQL is installed on the new Master Server, it is important to reconnect all Server Extension systems to the new Master Server.
To apply the license file received from the Activation Team: l Start the PReS Connect, PlanetPress Connect or PrintShopMail Connect Software Activation module: C:\Program Files\Objectif Lune\OL Connect\Connect Software Activation\ SoftwareActivation.exe l Click on Load License File to import the license.OLConnectLicense l Start the Software Activation module on the Extension servers, where applicable l Click on Load License File to import the above same license.
PReS Workflow 8 can be installed in parallel on the same machine as an existing PlanetPress® Suite 7.x installation. Note however: l l l l l If both versions need to be hosted on the same machine, PReS Workflow 8.8 must always be installed after the legacy PlanetPress® Suite 7.x installation. When uninstalling PReS Workflow 8.8, you may be prompted to repair your legacy PlanetPress® Suite 7.x installation. If PReS Workflow 8.
This migration benefits existing users in many ways and has limited impact on their current processes and how they use PlanetPress Suite version 7 and 6. This document provides information on the migration process and the requirements and considerations for existing PlanetPress Suite users to upgrade to the latest generation of our products. What does PReS Connect contain? PReS Connect is comprised of the following modules: l PReS Workflow 8.
You can keep everything you have The first thing to know is that you can keep your current PlanetPress Suite Workflow 7 configuration and your PlanetPress Suite Design documents. When upgrading to PReS Connect, they will remain functional. Please note that PlanetPress Suite Workflow 7 and PReS Workflow 8 cannot run at the same time. See Information about Connect Workflow 8 for information about these limitations.
l l l l Ability to input data from PDF Ability to print your PlanetPress Suite documents on any Windows printer (no need for printer licenses) Ability to create standard PDF output from your PlanetPress Suite documents Even if you don’t recreate your existing PlanetPress Suite documents, you can easily change your workflow to convert your output to PDF, then output them in PCL to any device supporting it.
2. Then, using the PReS Connect setup, install the Designer and/or Server on the appropriate computers. Then, using the PReS Workflow 8 setup, install PReS Workflow and/or PReS Image on the appropriate computers. (See the installation and activation document for more details) 3.
6.
7. Then select the product from which you wish to upgrade: 8.
9.
10. 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, follow the instructions for the installation using the serial number provided to you. You can activate your license through the Web Activation Manager. 11. From now on, if you need to modify your PlanetPress Design documents, simply open PlanetPress Design 6 or 7, edit your document and send the updated version to PReS Workflow 8.
How to perform a Workflow migration What do you need to consider when upgrading from PlanetPress Suite 7 to PReS Connect Workflow 8.8 on a new computer? Installing and Activating Workflow 8.8 on a new computer Points to consider: l l l l Before installing, be sure to read the Installation and Activation Guide. There you will find detailed Connect Workflow installation steps as well as system requirements, notes on license activation and much more.
then activate all of your printers on the new computer. l l Login to our Web Activation Manager (www.objectiflune.com/activations) using your customer number and password to get your Printer Activation Codes. 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.
2. Copy all the PlanetPress Suite 7 Documents and Compiled forms (*.ptk and *.ptz) from the Documents folder on the PlanetPress Suite computer and paste them into the equivalent folder on the Connect Workflow Computer. The PlanetPress Suite 7 folder would be "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\Documents". The PReS Connect Workflow 8 folder will be "C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Documents" 3.
Alternatively, you can download custom plug-ins from this link 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 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. This is done by going into Tools/Configure services. The user will need to have local administration rights in order to be able to run the services. For more information, see Users and Configurations.
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 8.8 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 8.8 on the same computer. 3. Do the following for both PlanetPress Suite version 7.6 and PReS Connect Workflow 8. 1. Open Workflow Service Console.
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. Copy the contents of this folder: "C:\ProgramData\Objectif Lune\PlanetPress Suite 7\PlanetPress Watch\PGC" to this fo
rending the parallel mode very hard to produce. It is not impossible, but describing how it can be done this 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 8.8 on new computer. 3. The Anoto PenDirector must be installed. It if is not, you can download it from here and then install it. Note It is strongly recommended that you install the latest version of the PenDirector.
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 8.8 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. Known Issues This page lists important information that applies to PReS Connect 1.8. Memory Usage in Clustered Environments In high speed clustered environments, PReS Connect will fill the database faster than the Clean-up service can clear it (the ratio is approximately 3:1).
Installation Paths with Multi-Byte Characters When installing the Chinese (Traditional or Simplified) or Japanese versions of Connect, if the user specifies an alternative installation path containing multi-byte/wide-char characters it can break some of the links to the Connect-related shortcuts in the Start Menu and cause an error to appear at the end of the installer. The workaround for the moment is to use the default installation path. The problem will be addressed in a later release.
installing the older version. PostScript Print Presets The print presets for PostScript were changed from Version 1.1 onwards meaning that some presets created in Version 1.0 or 1.0.1 may no longer work. Any PostScript print preset from Version 1.0 that contains the following will not work in Version 1.8: *.all[0].* Any preset containing this code will need to be recreated in Version 1.8.
Warning Important Note: The Designer itself and Proof Print do not use processes that run as services and they may find local files with non-UNC paths which can lead to the false impression that the resources are correct. Using Capture After Installing Workflow 8 If PReS Connect Workflow 8 is installed alongside PlanetPress Suite Workflow 7, Capture can no longer be used within Workflow 7. The plugins are now registered uniquely to Workflow 8 and the Messenger for Workflow 7 is taken offline.
proceed as normal. This message can also occur in the following circumstances: l If the server is offline and you are not using Proof Print l On some occasions before the Print Wizard opens REST Calls for Remote Services The Server will now accept REST calls for all remote services and will make commands wait indefinitely until the required engines become available. The Server will log when it is waiting for an engine and when it becomes available.
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 94 topic. The Connect Sever settings are maintained by the "Connect Server Configuration" utility tool which is installed alongside PReS Connect.
l l l "Scheduling Preferences" below for the Master Server preferences. "Server Extension Scheduling Preferences" on page 93 for the Slave (Server Extension) preferences. l "Merge Engine Scheduling" on the next page l "Weaver Engine Scheduling" on page 91 "Server Security Settings" on page 97 Scheduling Preferences The scheduling preferences are a way to control precisely how the PReS Connect services work in the background.
Note Changes made to these settings will be applied on the run. Existing jobs will be taken into account when determining if a job can run. For instance, if the minimum records for a Large job is increased from 1,000 to 10,000 and a job of 2,000 records is already running, then this existing job will now be considered a Medium job.
Email and Web output is generated only with the Merge Engine and thus their output speed is limited through this engine. However, the output speed of Print jobs is limited through the Weaver Engine, so when Print Content is generated through the Merge Engine, its speed is not limited. Additionally, you may launch up to 256 engines for Print Content generation, but Email and Web may only use the number of engines permitted by your license.
l Engine reservations:This area is used to reserve engines specifically for certain types of jobs. Reserved engines cannot be used by any other type of job. l l l l l Floating: Read-only box indicating the number of floating engines that can be used for any type of job. This number is equal to the Total Engines Available Reservations. For example if 6 engines are launched and 4 are reserved for small jobs, 2 will be Floating.
Engine to prepare the Print output. This preference page determines the number of Weaver engines launched, as well as their speed, when generating the output. One single engine can only process a single job at a time, at the speed available depending on licence and configuration. Note that in this dialog, the use of the term "Speed Unit" is in relation of the available speed for each engine. One speed unit = one unit of speed at the maximum speed your licence and number of Performance Packs allows.
l l Speed unit reservations: l l l l l Parallel engines/speed units per large job: Enter the number of engines/speed units that prioritize large print jobs. Floating: Read-only box indicating the number of floating speed units that can be used for any type of job. Small job speed unit reservations: Enter a number of speed units reserved for small print jobs. Medium job speed unit reservations: Enter a number of speed units reserved for medium print jobs.
l l l l l l l l Once the database is (re)started, Connect Server and Server Extensions all need to restart. The order is not important. Location of the master server: Enter the location and port of PReS Connect Master Server module in hostname:port format. For example, 192.168.100.123:9340 or connect-master:9340. Username for the master server: Enter the username expected by the PReS Connect Master Server.
Setting up Server Clustering requires two or more installations of PReS Connect on separate machines. The Master server is setup by installing the PReS Connect Server module during the Installation Wizard, while the Slave Server is setup by installing the PReS Connect Server Extension module instead. Quick Howto 1. Install the Master server (PReS Connect Server module), making sure to select the MySQL module. 2. Set the appropriate bindings in MySQL's my.ini file on the Master server. 3.
address=0.0.0.0. l l Once the changes have been made and saved you need to restart the MySQL services. Access must be granted to the root user on the IPs from which the Slave server will connect: l l l Open a Command Prompt in the following folder: C:\Program Files\Objectif Lune\OL Connect\MySQL Product\MySQL\bin (tip: navigate to the folder, SHIFT+Right-click and select "Open a command prompt here!).
l l l If the number of expected remote engines is lower than the actual number, performance will not be optimal. If the number of expected remote engines is higher than the actual number, jobs may fail and not complete. Clean-up Service requires special configuration on Clustering setups: l l Clean-up service should not run simultaneously on all machines (staggered cleanup). Doing so may cause jobs not to be processed since all servers are busy.
l Default session length (min): Enter a session time (in minutes) that the authentication stays valid for the requested process. This can reduce the number of requests to the server since an authentication request is not necessary during the session. Uninstalling This topic provides some important information about uninstalling (removing) PReS Connect1.8. To uninstall PReS Connect select the application from within the Add/Remove programs option under the Control Panel.
Uninstallation Wizard The uninstallation is done by running the PReS Connect Setup Wizard in uninstall mode. The Wizard consists of the following pages: 1. PReS Connect Setup: An information page, listing what will be uninstalled, and also warning about impacts upon running Applications and Services. 2. Data Management: A page that provides options for backing up or deleting Connect data.
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 a list of all file types used in Connect, see: "Connect File Types" on page 105. You can find additional information that complements the user manuals, such as error codes and frequently asked questions about PReS Connect, in the Knowledge base.
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. The Messenger service, for example, receives the files sent to Workflow from the Designer and the Workflow configuration 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 strictly 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 18).
The engines Merge engine/s. A merge engine merges data with a template using the scripts in the template, in order to create (Print,Email or Web) content items. The number of merge engines is configurable. By default, only one merge engine is used, but this number can be increased depending on the capacity of the machine that runs the solution (see "Performance Considerations" on page 26). Weaver engines. The Weaver engines create Print output from Print content items.
appropriate engine and returns the results to the caller. The results are the id's of the items (records, content items, job etc.) that are stored in the Connect database (see below). All Connect tasks except the Create Web Content task integrate the results in the Metadata in Workflow. The figure below shows the communication between Connect tasks and the Connect server in a Print process.
l l l l l l l l .OL-datamapper: A Data Mapping Configuration file, which can include sample data (excluding database source files such as mySQL, oracle, etc). .OL-datamodel: A data model file which can be imported or exported into either a data mapping configuration or a template. Contains a list of fields and their data type (date, currency, string, etc). .OL-jobpreset: A job preset file, used when generating a job (ready for output) from Designer or through automation (Create Job task).
The DataMapper Module The DataMapper is the tool to create a data mapping configuration. A data mapping configuration file contains the information necessary for data mapping: the settings to read the source file (Delimiter and Boundary settings), the data mapping workflow with its extraction instructions ('Steps'), the Data Model and any imported data samples.
2. Configure settings for the data source. The data source can be a file (CSV, PDF, TXT, XML) or a particular database. Configure how the data source is read by the DataMapper and create a record structure. See "Data source settings" on page 122. 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.
template and any print presets have to be sent to Workflow; see "Sending files to Workflow" on page 316. Note AFP input requires the CDP library. The library licence allows PReS Connect to run up to 4 instances of that library on a given machine at a given time. Using AFP input in a Server Clustering setup requires you to purchase one additional copy of the library per Server Extension (slave). On each computer you can run up to 4 instances of the CDP library at a given time.
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 (Comma Separated Values or Excel (CSV/XLSX/XLS), MS-Access, PDF/VT, Text or XML). 3. Click Next. 4. Click the Browse button and open the file you want to work with. 5. Click Finish.
l From the Welcome screen 1. Open the PReS ConnectWelcome page by clicking the select the Help menu and then Welcome. icon at the top right or 2. Click Create a New Configuration. 3. From the Using a wizard pane, select the appropriate file type. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select the appropriate file type. The steps to take with the wizard depend on the file type.
2. Click Create a New Configuration. 3. From the Using a wizard pane, select Generate counters. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select Generate counters. You can set the following parameters: l l l l l l l Starting Value: The starting number for the counter. Defaults to 1. Increment Value: The value by which to increment the counter for each record.
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, click on File > Save, or click on Save As to save a copy of a data mapping configuration under a different name. In the Toolbars, click the Save button.
4. Click the Browse button and open the file you want to work with. 5. Click Next. l From the File menu 1. In the menu, click File > New. 2. Click the Data mapping Wizards drop-down and select From CSV/XLSX/XLS File. 3. Click Next. 4. Click the Browse button and open the file you want to work with. 5. Click Next. 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.
First row contains field names: Uses the first line of the CSV as headers, which automatically names all extracted fields. Verify that the data are read properly. l 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.
Wizard settings for a database file After opening a database file with a wizard there are a number of settings to make, depending on the database type (see below). On the last page of the dialog, click Finish to close the dialog and open the actual data mapping configuration. MySQL, SQL Server or Oracle l Server: Enter the server address for the database. l Port: Enter the port to communicate with the server. The default port is 3306.
l l Windows authentication: Select to use the Windows user name and password that are used by the Connect Service. SQL Server authentication: Select to use the User name and Password set below to connect to the SQL Server: l User name: Enter the SQL Server user name. l Password: Enter the password for the above user name. JDBC Note Since JDBC can connect to multiple types of databases, a specific database driver and path to this driver's JAR file must be specified.
and it also enables you to extract the additional information from the metadata. You can extract data from the content afterwards. Tip To extract information from the metadata in the extraction workflow itself, you have to create a JavaScript extraction (see "Using scripts in the DataMapper" on page 262 and "extractMeta()" on page 284).
l Field List: This list displays all fields on the chosen level and higher levels in the PDF/VT metadata. The right column shows the field name. The left column displays the level on which it is located. Check any field to add it to the extraction. 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.
After selecting the file, you have to set the split level and trigger type: l l XML Elements: This is a list of node elements that have children nodes. Select the level in the data that will define the source record. Trigger: select On element to create a record in the Data mapping for each occurrence of the node element selected in the XML Elements field, or select On change to create a record each time the element is different.
In between the Preprocessor and Postprocessor step, the workflow can contain as many steps as needed to extract the required data. Adding steps Extracting data is the main way to build a data mapping workflow; see "Extracting data" on page 125. Extract steps, Condition steps and Repeat steps can be added after selecting data in the Data Viewer. All steps can be added via the Steps pane: 1. In the extraction workflow on the Steps pane, select the step after which to add the new step. 2.
Testing the extraction workflow The extraction workflow is always performed on the current record in the data source. When an error is encountered, the extraction workflow stops, and the field on which the error occurred and all subsequent fields will be greyed out. Click the Messages tab (next to the Step properties pane) to see any error messages. To test the extraction workflow on all records, you can: l Click the Validate All Records toolbar button. l Select Data > Validate Records in the menu.
For a CSV File In a CSV file, data is read line by line, where each line can contain multiple fields, separated by a delimiter. Even though CSV stands for comma-separated values, fields may be separated using any character, including commas, tabs, semicolons, and pipes. The text delimiter is used to wrap around each field just in case the field values contain the field separator.
For an XML file XML is a special file format because these file types can have a theoretically unlimited number of structure types. The input data has two simple options that basically determine at which node level a new record is created. You can either select an element type, to create a new delimiter every time that element is encountered, or choose to use the root node. If there is only one toplevel element, there will only be one record before the Boundaries are set.
Data format settings 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 (see "Data types" on page 175). When that data type is Date, Number or Currency, the DataMapper will expect the data in the data source to be formatted in a certain way, depending on the settings.
Before you start Data source settings Data source settings must be made beforehand, not only to make sure that the data is properly read but also to have it organized in a record structure that meets the purpose of the data mapping configuration (see "Data source settings" on page 122). It is important to set the boundaries before starting to extract data, especially transactional data (see "Extracting transactional data" on page 131).
l Alternatively, drag & drop the selected fields into the Data Model pane. Tip In a PDF or Text file, use the Drag icon Data Model. to drag selected data into the With this method, a new Extract step will only be added to the extraction workflow when no Extract step already present on the Steps pane. Otherwise the field/s will be added to the selected Extract step or to the one that was last added. Dragging data into an existing field in the Data Model will replace the data.
l l l The field name is the same. (See: "Renaming and ordering fields" on page 165.) 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. The option Append values to current record is checked in the Step properties pane under Extraction Definition.
l Change the names of fields that are included in the extraction. l Change the order in which fields are extracted. l Set the data type, data format and default value of each field. l Modify the extracted data through a script. l Delete a field. All this can be done via the Step properties pane (see "Settings for location-based fields in a Text file" on page 228), because the fields in the Data Model are seen as properties of an Extract step. See also: "Fields" on page 162.
Right-clicking on a data selection displays a contextual menu with the actions that can be done with that selection or the steps that can be added to them. That menu also displays the keyboard shortcuts. Text or PDF file To select data in a Text or PDF file, click on a starting point, keep the mouse button down, drag to the end of the data that needs to be selected and release the mouse button. The data selection can contain multiple lines.
button pressed down while clicking on nodes to select or deselect them, or keep the Shift button pressed down to select consecutive nodes. You can select multiple fields even if those fields are in different nodes. Note The Goto step isn't used in XML extraction workflows The DataMapper moves through the file using Xpath, a path-like syntax to identify and navigate nodes in an XML document. Extracting transactional data Promotional data are data about customers, such as addresses, names and phone numbers.
Detail tables are created when an Extract step is added within a Repeat step. The Repeat step goes through a number of lines or nodes. An Extract step within that loop extracts data from each line or node. It depends on the type of source data how this loop is constructed exactly. For more information about detail tables, multiple detail tables and nested detail tables, see "Example " on page 204. From a CSV file or a Database The transactional data (also called line items) appear in multiple rows.
1. Select a field in the column that contains the first line item information. 2. Right-click this data selection and select Add Repeat. This adds a Repeat step with a GoTo step inside it. The GoTo step moves the cursor down to the next line, until there are no more lines (see "Goto step" on page 151). 3. (Optional.) Add an empty detail table via the Data Model pane: right-click the Data Model and select Add a table. Give the detail table a name. 4. Select the Repeat step on the Steps pane. 5.
Page 134
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.
elements is extracted. 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. Tip It is possible to edit the Xpath in the Collection field, to include or exclude elements from the loop. One example of this is given in a How-to: Using Xpath in a Repeat step. The example in the How-to uses the starts-with() function. For an overview of XPath functions, see Mozilla: XPath Functions.
The new Extract step will be located in the Repeat step. From a Text or a PDF file In a PDF or Text file, transactional data appears on multiple lines and can be spread over multiple pages. 1. Add a Goto step if necessary. 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, but previous steps may have moved it. Note that an Extract step does not move the cursor. 1. Select something in the first line item. 2.
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 form 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: Type the value in the right operand (in the Step properties pane).Move or resize the selection rectangle in the data.Click the Use selection button in the left operand (in the Step properties pane).When the Condition evaluates to true, the value is found in the selected region.
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 126). 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. To learn how to handle this, see "Extracting data of variable length" on the facing 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.
Tip This how-to describes in detail how to extract an item description that appears in a variable number of lines: How to extract multiline items. Extracting data of variable length In PDF and Text files, transactional data isn't structured uniformly, as in a CSV, database or XML file. Data can be located anywhere on a page. Therefore, data are extracted from a certain region on the page.
Text file: setting the height to 0 If the variable part in a TXT file is at the end of the record (for example, the body of an email) the height of the region to extract can be set to 0. This instructs the DataMapper to extract all lines starting from a given position in a record until the end of the record, and store them in a single field. This also works with the data.extract() method in a script; see "Examples" on page 278.
Tip Create and edit the Extract step in the 'true' branch, then right-click the step on the Steps pane, select Copy Step, and paste the step in the 'false' branch. Now you only have to adjust the region from which this Extract step extracts data. To learn how to configure a Condition step or a Case in a Multiple Conditions step, see "Configuring a Condition step" on page 154.
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 125. To add a field without extracting data, see "JavaScript-based field" on page 163. 2. On the Step properties pane, under Field Definition, select the field and change its Mode to Javascript. If the field was created with its Mode set to Location, you will see that the script already contains one line of code to extract data from the original location. 3. Expand the script.
Steps In the DataMapper, steps are part of an extraction workflow (see "Data mapping workflow" on page 120). They contain a specific instruction for the DataMapper, for example to extract data, create a loop, or apply a condition. Some types of steps contain other steps. Steps are executed sequentially, from top to bottom in an extraction workflow.
added to create reports. A tag could be added to process certain records differently. A preprocessor could remove certain records altogether. One example of how a preprocessor could be used is given in a How-to: Using Preprocessors in DataMapper. Properties To add a property: 1. Select the Preprocessor step on the Steps pane. 2. On the Step properties pane, under Properties, click the Add button . See "Properties" on page 224 for an explanation of the settings for properties.
Configuring the Preprocessor step For an explanation of the settings for preprocessors, see: "Preprocessor step properties" on page 223. Extract step The Extract step is essential in each and every data mapping configuration. It extracts data from the data source, based on their location (a row and column in CSV or tabular data, an XPath in XML, or a region of the page in PDF and Text) or on a JavaScript. The data is placed in the record set that is the result of the extraction workflow.
Adding an Extract step To add an Extract step, first select the step on the Steps pane after which to insert the Extract step. Then: l l In the Data Viewer, select some data, right-click that data and choose Add Extraction, or drag & drop the data in the Data Model. For more detailed information and instructions, see: "Extracting data" on page 125. Alternatively, right-click the Steps pane and select Add a Step > Add Extraction. Make the required settings on the Step properties pane.
XML files. When you select a node in an XML file and add a Repeat step on it, the Repeat step will automatically loop over all nodes of the same type on the same level in the XML file. Adding a Repeat step To add a Repeat step: 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.
Note The Goto step isn't used in XML extraction workflows The DataMapper moves through the file using Xpath, a path-like syntax to identify and navigate nodes in an XML document. Adding a Goto step To add a Goto step: l l On the Steps pane, select the step after which to insert the Goto step. In the Data Viewer, select some data, right-click that data and choose Add Goto, to add a Goto step that moves the cursor to that data. Alternatively, right-click the Steps pane and select Add a Step > Add Goto.
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.
operand (in the Step properties pane).Move or resize the selection rectangle in the data.Click the Use selection button in the left operand (in the Step properties pane).When the Condition evaluates to true, the value is found in the selected region. l Alternatively, right-click the Steps pane and select Add a Step > Add Conditional. Enter the settings for the condition on the Step properties pane.
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 "Left operand, Right operand" on page 248. The settings for a Case are the same as for a Condition step; see "Condition step properties" on page 245.
l l l Execute JavaScript code. Set the value for a record property. Record properties are defined in the Preprocessor step; see "Preprocessor step" on page 147. Stop the processing of the current record. 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 records or skip records partially. The Action step can run multiple specific actions one after the other in order.
Configuring the Postprocessor step For an explanation of the settings for postprocessors, see "JavaScript " on page 256. The Data Model The Data Model is the structure of records into which extracted data are stored. It contains the names and types of the fields in a record and in its detail tables. A detail table is a field that contains a record set instead of a single value.
pane, filled with data from the current record. The Data Model is not related to the type of data source: whether it is XML, CSV, PDF, Text or a database does not matter. The Data Model is a new structure, designed to contain only the required data. 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.
Importing/exporting a Data Model To use a Data Model in another data mapping configuration, or to use it in a Designer template without a data mapping configuration, you have to export that Data Model and import it into a data mapping configuration or template. Importing and exporting Data Models is done from within the Data model Pane, using the topright icons and . For information about the structure of the exported Data Model file, see "Data Model file structure" on page 184.
Using the Data Model The Data Model is what enables you to create personalized templates in the Designer module. You can drag & drop fields from the Data Model into the template that you are creating (see "Variable Data" on page 611). For this, you have to have a template and a data mapping configuration open at the same time, or import a Data Model (see "Importing/exporting a Data Model" on the previous page).
1. Use an Execute Data Mapping task or Retrieve Items task to create a record set. On the General tab select Outputs records in Metadata. 2. Add a value to a field in the Metadata using the Metadata Fields Management task. Data added to the _vger_fld_ExtraData field on the Document level will appear in the record's ExtraData field, once the records are updated from the Metadata (in the next step). Other fields have the same prefix: _vger_fld_. 3. Update the record/s from the Metadata.
Adding fields Location-based field Generally location-based fields are added to a Data Model by extracting data; see "Extracting data" on page 125. Location-based fields in detail tables are created by extracting transactional data; see "Extracting transactional data" on page 131. Alternatively, you can add fields and detail tables directly in the Data Model pane. Right-click anywhere on the Data Model and a contextual menu will appear. Which menu items are available depends on where you've clicked.
2. On the Step properties pane, under Field Definition, click the Add JavaScript Field button next to the Field List. 3. On the Step properties pane, under Field Definition, enter the script in the Expression field. By changing a field's mode Alternatively you can change a location-based into a JavaScript-based field. 1. Select the field in the Data Model. 2. On the Step properties pane, under Field Definition, change its Mode to JavaScript. 3. Enter the script in the Expression field.
Adding fields dynamically Outside of the DataMapper the Data Model cannot be changed. It isn't possible to add fields to it when using the data mapping configuration in Workflow. It is however possible to add data to existing fields via Workflow; see "About adding fields and data via Workflow" on page 161. 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.
Setting the data type Fields store extracted data as a String by default. The data type of a field can be changed via the properties of the Extract step that the field belongs to. 1. Select the Extract step that contains the field. You can do this by clicking on the field in the Data Model, or on the step in the Steps pane that contains the field. 2. On the Step properties pane, under Field Definition, set the Type to the desired data type. See "Data types" on page 175 for a list of available types.
Post function On the Step properties pane, under Field Definition, you can enter a script in the Post function field to be run after the extraction. (Click the Use JavaScript Editor button to open the Script Editor dialog if you need more space.) A Post function script operates directly on the extracted data. Its results replace the extracted data. For example, the Post function script replace("-", ""); replaces the first dash character that occurs inside the extracted string.
2. In the Step properties pane, under Field Definition, click the Remove Extract Field button next to the Field List drop-down. Detail tables A detail table is a field in the Data Model that contains a record set instead of a single value. Detail tables contain transactional data. They are created when an Extract step is added within a Repeat step; see "Extracting transactional data" on page 131. In the most basic of transactional communications, a single detail table is sufficient.
Creating multiple detail tables Multiple detail tables are useful when more than one type of transactional data is present in the source data, for example purchases (items with a set price, quantity, item number) and services (with a price, frequency, contract end date, etc). To create more than one detail table, simply extract transactional data in different Repeat steps (see "Extracting transactional data" on page 131).
Page 170
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 182 l "Integer" on page 182 l "Float" on page 181 l "Currency" on the next page l "Date" on page 178 l "Object" on page 183 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 also be set using an expression of which the result is true or false. This is done using operators and comparisons. Example: record.fields["isCanadian"] = (extract("Country") == "CA"); For more information on JavaScript comparison and logical operators, please see w3schools.com or developer.mozilla.org. 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.
Building Currency values Currency values can be the result of direct attribution or mathematical operations just like Integer values (see "Integer" on page 182). 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.
For the letters and patterns that you can use in a date format, see "Defining a date/time format" below. Data format settings tell the DataMapper how certain types of data are formatted in 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.
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 929). 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 pl
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. Floats are routinely used for calculations. Note that Float values can only have up to 3 decimals.
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!. If the data type is String and the value is placed in a template, it will display exactly as "He said WOW!" (without the quotes). If the data type is HTMLString, it will display as "He said WOW!" (again, without the quotes).
l Mathematical operations: Assign the result of any mathematical operation. For example: 22+51, 3*6, 10/5 or sourceRecord.property.SubTotal. For more information on mathematics in JavaScript , see w3Schools - Mathematical Operators. For more advanced mathematical functions, see w3schools - Math Object. Note When adding numbers that are not integers, for instance 4.5 + 1.2 , a round towards zero rounding is applied after the operation was made. In the previous example, the result, 5.7, is rounded to 5.
l Extraction: l In the Data Model, select a field. On the Step properties pane, under Field Definition set the Type to String. The field value will be extracted and treated as a string. l l JavaScript Expression: Set the desired value to any string between quotes. Example: record.fields["countryOfOrigin"] = "Canada"; Building String values String values can be made up of more than just a series of characters between quotes.
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 187Example: nested tables (one table into another) PAGE 188Keyboard 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 746. 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 Z Ctrl + Shift + S Save all Ctrl + Shift + W or Ctrl + Shift + F4 Close all Ctrl + F5 Revert Ctrl + F7 Next view Ctrl + Shift + F7 Previous view Ctrl + F8 Next perspective Ctrl + Shift + F8 Previous perspective Ctrl + F10 Save as Ctrl + F12 Send to Workflow / Package files F4 Ignore step F6 Add an Extract step F7 Add a Goto step F8 Add a Condition step Page 190
Key combination Function F9 Add a Repeat step F10 Add an Extract field F11 Add an Action step F12 Add a Multiple Conditions step Alt + F12 Add a Case step (under a Multiple Conditions step) Home Go to the first step in the workflow End Go to the last step in the workflow Alt + V Validate records Shift + F10 or Ctrl + Shift + F10 Open context menu Viewer pane The following key combinations activate a function in the Viewer.
Key combination Function Ctrl + F6 Next editor (when there is more than one file open in the Workspace) Ctrl + Shift + F6 Previous editor (when there is more than one file open in the Workspace) Data Model pane Key combination Function PageUp Go to previous record PageDown Go to next record Alt + CR Property page Alt + PageDown Scroll down to the last field Alt + PageUp Scroll up to the first field Steps tab Key combination Function Ctrl + - Zoom out Ctrl + + Zoom in Edit Script and
Key combination Function Ctrl + space Content assist (auto-complete) Ctrl + A Select all Ctrl + D Duplicate line Ctrl + I Indent (Tab) Ctrl + J Line break Ctrl + L Go to line; a prompt opens to enter a line number.
l l l l l l l l Open Recent: List the most recently opened Templates and configurations. Clicking on a template will open it in the Designer module, clicking on a data mapping configuration will open it in the DataMapper module. Close: Close the currently open data mapping configuration or Template. If the file needs to be saved, the appropriate Save dialog will open. Close All: Close any open data mapping configuration or Template.
l l l l Cut Step: Removes the currently selected step and places it in the clipboard. If the step is a Repeat or a Condition, all steps under it are also placed in the clipboard. If there is already a step in the clipboard, it will be overwritten. Copy Step: Places a copy of the currently selected step in the clipboard. The same details as the Cut step applies. Paste Step: Takes the step or steps in the clipboard and places them in the Steps after the currently selected step.
l l l l l Add Condition Step: Adds a condition based on the current data selection. The "True" branch gets run when the text is found on the page. Other conditions are available in the step properties once it has been added. Add Repeat Step: Adds a loop that is based on the current data selection, and depending on the type of data. XML data will loop on the currently selected node, CSV loops for all rows in the record.
Help Menu l l l Software Activation: Displays the Software Activation dialog. See Activating your license. Help Topics: Click to open this documentation. Contact Support: Click to open the Objectif Lune Contact Page in the default system Web browser. l About PReS Connect Designer: Displays the software's About dialog. l Welcome Screen: Click to re-open the Welcome Screen. Panes The DataMapper screen contains the following panes. l "Settings pane" on page 210.
: Show the ExtraData field. Note that this field is not meant to be filled via an extraction. It can be used in Workflow to add data to the Data Model; see "About adding fields and data via Workflow" on page 161. Data Model contextual menu The Data Model is generally constructed by extracting data; see "Extracting data" on page 125. It is however possible to modify the Data Model, even if no data is present in the pane.
Field display Fields in the Data Model pane are displayed in specific ways to simplify comprehension of the display data: l l l l l l l l Value: The current value of the extracted field, based on the record shown in the Data Viewer. The column on the left displays the name of the field. The column on the right displays the current value of the extracted field based on the record shown in the Data Viewer, if an Extract step has an extraction for this field (see "Extracting data" on page 125).
l l l l l First Record: Go to the first record in the data sample. This button is disabled if the first record is already shown. Previous Record: Go to the previous record in the data sample. This button is disabled if the first record is shown. Current Record: Displays the current record or table entry. Type a record number and press the Enter key to display that record. The number has to be within the number of available records in the data sample.
Note A detail table’s name should always begin with ‘record.’. 3. Click somewhere else on the Step Properties pane to update the Data Model. You will see the new name appear. Creating multiple detail tables Multiple detail tables are useful when more than one type of transactional data is present in the source data, for example purchases (items with a set price, quantity, item number) and services (with a price, frequency, contract end date, etc).
To create more than one detail table, simply extract transactional data in different Repeat steps (see "Extracting transactional data" on page 131). 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.
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).
Example An XML source file lists the services of a multi-service provider: Internet, Cable, Home Phone, Mobile. Each service in turn lists a number of "charges", being service prices and rebates, and 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 set in the Data Source settings (see "Record boundaries" on page 124).
l l l l Hide/Show line numbers the left of the Data Viewer. (Text file only): Click to show or hide the line numbers on Hide/Show datamap : Click to show or hide the icons to the left of the Data Viewer which displays how the steps affect the line. Hide/Show extracted data : Click to show or hide the extraction selections indicating that data is extracted. This simplifies making data selections in the same areas and is useful to display the original data.
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 122.
l Ignore unparseable lines: Ignores any line that does not correspond to the settings above. PDF file Input Data settings PDF Files have a natural, static delimiter in the form of pages, so the options here are interpretation settings for text in the PDF file. The Input Data settings for PDF files determine how words, lines and paragraphs are detected in the PDF when creating data selections. Each value represents a fraction of the average font size of text in a data selection, meaning "0.
l l l l l Connection String: Displays the connection string used to access the Data Source. Table: Displays the tables and stored procedures available in the database. The selected table is the one the data is extracted from. Clicking on any of the tables shows the first line of the data in that table. 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.
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. Boundaries Boundaries are the division between records: they define where one record ends and the next record begins; for an explanation see "Record boundaries" on page 124.
l On field value: Sets a boundary on a specific field value. l l l Field name: Displays the fields in the top line. The value of the selected field is compared with the Expression below to create a new boundary. Expression: Enter the value or Regular Expression to compare the field value to. Use Regular Expression: Treats the Expression as a regular expression instead of static text. For more information on using Regular Expressions (regex), see the Regular-Expressions.info Tutorial.
boundary can be effectively defined. For example, if a string is always found on the first and on the last page of a document, you could specify a number of occurrences of 2. This way, there is no need to inspect other items for whether it is on the first page or the last page. Having found the string two times is enough to set the boundary. l Pages before/after: Defines the boundary a certain number of pages before or after the current page.
l l l l l l l Top/Bottom: Defines the start and end row of the data selection to compare with the text value. Entire width: Ignores the column values and compares using the whole line. Entire height: Ignores the row values and compares using the whole column. Entire page: Compares the text value on the whole page. Only available with contains, not contains, is empty and is not empty operators.
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). Trigger: Defines the type of rule that controls when a boundary is set, creating a new record. l On Element: Defines a new record on each new instance of the XML element selected in the Input Data settings.
l l l l Delete Replace source. : Remove the current Data Sample from the data mapping configuration. : Open a Data Sample and replace it with the contents of a different data Reload : Reload the currently selected Data Sample and any changes that have been made to it. Set as Active : Activates the selected Data Sample. The active data sample is shown in the Data Viewer after it has gone through the Preprocessor step as well as the Input Data and Boundary settings.
l l l Date Format : Set the date format for a date value. 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. Note Default data formats tell the DataMapper how certain types of data are formatted in the data source. They don't determine how these data are formatted in the Data Model or in a template.
Moving a step To rearrange steps, simply drag & drop them somewhere else on the dotted line in the Steps pane. Alternatively you can right-click on a step and select Cut Step or use the Cut button in the Toolbar. If the step is Repeat or Condition, all steps under it will also be placed in the clipboard. To place the step at its destination, right-click the step in the position before the desired location and click Paste Step, or use the Paste button in the toolbar.
l l l Add Case Step: Adds a Case condition under the selected Multiple Conditions step. Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps are grayed and do not run, neither in the DataMapper nor when the data mapping configuration is executed in Workflow. However, they can still be modified normally. Delete Step: To remove a step, right-click on it and select Delete step from the contextual menu or use the Delete button in the Toolbar.
Preprocessor step properties The Preprocessor step does not run for every record in the source data. It runs once, at the beginning of the extraction workflow, before anything else; see "Preprocessor step" on page 147. The properties described below become visible in the Step properties pane when the Preprocessor step is selected in 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.
Configuration, use the automation.jobInfos.JobInfoX (where X is the job info number, from 0 to 9). l l l OriginalFilename: This property contains the original file name that was captured by the PReS Workflow process and is equivalent to the %o variable in the process. To access these property inside of any JavaScript code within the Data Mapping Configuration, use automation.properties.OriginalFilename.
l l l Automation variable: These properties initialize variables coming from the PReS Workflow automation tool. The name of the property needs to be the same as the variable name in Workflow, and they can be either a Local variable or a Global variable. For either one, only the actual name is to be used, so for %{MyLocalVar} use only MyLocalVar , and for %{global.MyGlobalVar} use MyGlobalVar. If a global and a local variable have the same name ( %{myvar} and %{global.
Extract step properties The Extract step takes information from the data source and places it in the record set that is the result of the extraction workflow. For more information see "Extract step" on page 149 and "Extracting data" on page 125. Description This subsection is collapsed by default in the interface, to give more screen space to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane.
l Mode: Determines the origin of the data. Fields always belong to an Extract step, but they don't necessarily contain extracted data. See "Fields" on page 162 for more information. l l Location: The contents of the data selection determine the value of the extracted field.
l Type: The data type of the selected data; see "Data types" on page 175. Make sure that the data format that the DataMapper expects matches the actual format of the data in the data source; see "Data Format" on page 230. Settings for location-based fields in a Text file l Left: Defines the start of the data selection to extract. l Right: Defines the end of the data selection to extract. l Top offset: The vertical offset from the current pointer location in the Data Viewer).
l Left: Defines the start of the data selection to extract. l Right: Defines the end of the data selection to extract. l l l Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Height: The height of the selection box. Use selection: Click to use the value (Left, Right, Top offset and Height) of the current data selection for the extraction. Note If the selection contains multiple lines, the lines are by default joined and extracted into one field.
l Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Post Function: Enter a JavaScript expression to be run after the extraction. For example replace("-","") would replace a single dash character inside the extracted string. l l Use JavaScript Editor: Click to display the Script Editor dialog. Trim: Select to trim empty characters at the beginning or the end of the field.
Note Data format settings tell the DataMapper how certain types of data are formatted in 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 in the Data Model, and will always be shown as "year-month-day" plus the time stamp, for example: 2012-04-11 12.00 AM.
l Name: The name of the field. Click the field name and enter a new name to rename the field. 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 Name: A name by which to refer to the action. This name has no impact on functionality. l Type: l l l Set property: Sets the value of a record property which was created in the Preprocessor step (see "Preprocessor step" on page 147). Run JavaScript : Runs a JavaScript expression, giving much more flexibility over the extraction process. Stop Processing Record: When this option is selected, the extraction workflow stops processing the current record and moves on to the next one.
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 259. 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. CSV and Database Files l Property: Displays a list of record properties set in the Preprocessor step (see "Preprocessor step" on page 147). l Type: Displays the type of the property. Read only field. l Based on: Determines the origin of the data.
l l Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Data Format: Data format settings tell the DataMapper how certain types of data are formatted in the data source.
l XPath: The path to the XML field that is extracted. l Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l 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.
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 : A negative sign will be displayed before any 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.
The properties described below become visible in the Step properties pane when the Repeat step is selected in 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. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here will be displayed in the tooltip that appears when hovering over the step in the Steps pane.
Rule Tree The Rule tree subsection displays the full combination rules (defined below under Condition) as a tree, which gives an overview of how the conditions work together as well as the result for each of these conditions for the current record or iteration. Condition First, the Condition List displays the conditions in list form, instead of the tree form above. Three buttons are available next to the list: l Add condition: Click to create a new condition in the list.
extraction. l l Value: A specified static text value. l l l l l l l l Field: The Extracted Record field to use in the comparison. Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the Edit Script dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression.
l l l l is less than: The first specified value is smaller, numerically, than the second value for the condition to be True. is greater than: The first specified value is larger, numerically, than the second value for the condition to be True. is empty: The first specified value is empty. With this operator, there is no second value. Invert condition: Inverts the result of the condition. For instance, is empty becomes is not empty.
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.
XML Files l Based On: l Position: The data in the specified position for the comparison. l l l l l l l l l l Value: The text value to use in the comparison. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression.
l 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 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. Condition First, the Condition List displays the conditions in list form, instead of the tree form above. Three buttons are available next to the list: l l Add condition: Click to add a new rule. This will always branch the current condition as an "AND" operator.
l Value: A specified static text value. l l l l l l l l Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the Edit Script dialog (see "Using scripts in the DataMapper" on page 262). 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 is greater than: The first specified value is larger, numerically, than the second value for the condition to be True. is empty: The first specified value is empty. With this operator, there is no second value. Invert condition: Inverts the result of the condition. For instance, is empty becomes is not empty. l Multiple Conditions step properties The Multiple Conditons step contains a number of Case conditions (one to start with) and a Default, to be executed when none of the other cases apply.
l l l l l Trim: Select to trim empty characters at the beginning or the end of the field. Value: A specified static text value. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression. l l l Value: The text value to use in the comparison.
l 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. Three buttons are available next to the list: l l l Add case: Click to add a new case to the step. It will be placed next to any existing cases.
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. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here will be displayed in the tooltip that appears when hovering over the step in the Steps pane.
options appear below to specify in which area of each line the Gotostep checks in: l Left: The starting column, inclusively. l Right: The end column, inclusively. l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Next occurrence of: Jumps to the next occurrence of specific text or a text pattern, either anywhere on the line or in specific columns.
l Page: Jumps between pages or to a specific page. l l l From: Defines where the jump begins: l Current Position: The Gotobegins at the current cursor position. l Top of record: The Gotobegins at line 1 of the source record. Move by: Enter the number pages to jump. Next line with content: Jumps to the next line that has contents, either anywhere on the line or in specific columns.
l Use regular expression: Check so that the Expression box is treated as a regular expression instead of static text. For more information on using Regular Expressions (regex), see the Regular-Expressions.info Tutorial. CSV File l From (CSV files): Defines where the jump begins: l Current Position: The Goto begins at the current cursor position. l l Move by: Enter the number of lines or pages to jump. Top of record: The Gotobegins at line 1 of the source record.
The properties described below become visible in the Step properties pane when the Postprocessor step is selected in 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. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here will be displayed in the tooltip that appears when hovering over the step in the Steps pane.
Postprocessor definition JavaScript l l l Expression: The JavaScript expression that will run on the Data Sample. See "DataMapper Scripts API" on page 259. Use JavaScript Editor: Click to display the Script Editor dialog. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Toolbar In the DataMapper module, the following buttons are available in the top toolbar.
l l l l l l l l l l l l Add Condition Step : Adds a condition based on the current data selection. The "True" branch gets run when the text is found on the page. Other conditions are available in the step properties once it has been added. Add Repeat Step : Adds a loop that is based on the current data selection, and depending on the type of data. XML data will loop on the currently selected node, CSV loops for all rows in the record.
Welcome Screen The Welcome Screen appears when first starting up PReS Connect. It offers some useful shortcuts to resources and to recent documents and data mapping configurations. If you are new to PReS Connect and you don't know where to start, see "Welcome to PReS Connect 1.8" on page 15. The Welcome Screen can be brought back in two ways: l The Welcome Screen button in the "Toolbars" on page 779. l From the Menus in Help, Welcome Screen.
l l Recent Templates: Lists recently used templates. Click any template to open it in the Designer module. Other Resources: l Documentation: Opens this documentation. l Courses (OL Learn): Opens the Objectif Lune e-Learning Center. l User Forums: Opens the Questions & Answer forums. DataMapper Scripts API This page describes the different features available in scripts created inside DataMapper. See "Using scripts in the DataMapper" on page 262.
Name Description Available in scripts of type "logger" on page 290 An object that allows to log error, warning or informational messages. Boundaries, all steps except Goto "record" on page 290 The current record in the main data set. Extract, Condition, Repeat and Multiple Conditions steps "region" on page 291 An object that defines a subsection of the input data. Boundaries "sourceRecord" on page 293 An object containing properties specific to the current source record being processed.
Name Description exists. "createHTTPRequest()" on page 301 Creates a new HTTP Request Object. createTmpFile() Creates a file with a unique name in the temporary work folder and returns a file object. deleteFile() Deletes a file. execute() Calls an external program and waits for it to end. newByteArray() Returns a new byte array. newCharArray() Returns a character array. newDoubleArray() Returns a double array. newFloatArray() Returns a float array. newIntArray() Returns an integer array.
Using scripts in the DataMapper In the DataMapper every part of the extraction process can be customized using scripts. A script can be used to set boundaries for a data source (see "Setting boundaries using JavaScript" on page 264). The script determines where a new record starts. Scripts can also be used in different steps in the extraction workflow.
subsequently available. Keyboard shortcuts for the script editor are listed in the following topic: "Keyboard shortcuts" on page 746. Syntax rules In the DataMapper, all scripts must be written in JavaScript, following JavaScript syntax rules. For example, each statement should end with ; and the keywords that can be used, such as var to declare a variable, are JavaScript keywords. There are countless tutorials available on the Internet to familiarize yourself with the JavaScript syntax.
If this is saved as myFunction.js and imported, then the following would work anywhere in the configuration: var result = myAddFunction(25, 12); // returns 37! Setting boundaries using JavaScript As soon as you select the On Script option as the trigger for establishing record boundaries (see "Record boundaries" on page 124), you are instructing the DataMapper to read the source file sequentially and to trigger an event each and every time it hits a delimiter.
l Examine the data found in between delimiters for specific conditions. l Examine specific regions of that data, or the available data as a whole. l Compare the contents of one region with another. l Etc. To access this data in the script, use the get() function of the boundaries object. This function expects different parameters depending on the type of source file; see "Example" on page 273.
Note The first line is just the header with the names of the CSV columns. The data is already sorted per year, per artist, and per album. Your goal is to examine two values in each CSV record and to act when either changes. The DataMapper GUI allows you to specify a On Change trigger, but you can only specify a single field. So for instance, if you were to set the record boundary when the "Released" field changes, you'd get the first four lines together inside a single record.
simply the column name. The region is passed as a parameter to the get() method, which reads its contents and converts it into an array of strings (because any region, even a CSV field, may contain several lines). l l l To "remember" the values that were processed the last time the event was triggered, we use variables that remain available in between events. Note that these variables are specific to the Boundary context and not available in any other scripting context in the DataMapper.
The purpose of the script, again, is to set the record boundary when EITHER the year OR the artist changes. The script would look like this: /* Read the values of both columns we want to check */ var zeBand = boundaries.get(region.createRegion(1,1,30,1)); var zeYear = boundaries.get(region.createRegion(61,1,65,1)); /* Check that at least one of our variables holding previous values have been initialized already, before attempting to compare the values */ if (boundaries.
pages do not have a grid concept of lines and columns, the above parameters would instead be specified in millimeters relative to the upper left corner of each page. So for instance, to create a region for the Year, the code might look like this: region.createRegion(190,20,210,25) which would create a region located near the upper right corner of the page.
Property Description properties Returns a ScriptableAutomation object containing additional information (file name, process name and task ID) from PReS Workflow. variables Returns a ScriptableAutomation object containing the list of local and global variables defined by the user in PReS Workflow. Note that there is no way to distinguish local variables from global ones (local variables take precedence over global variables).
automation.properties.OriginalFilename; To access Workflow variables (declared in the Preprocessor properties): automation.variables.Same_as_workflow; boundaries Returns a boundaries object encapsulating properties and methods allowing to define the boundaries of each document in the job. This object is available when triggering document boundaries On script. Properties The following table lists the properties of the boundaries object.
Method Description Script type getVariable () Retrieves a value of a variable stored in the boundaries object. Boundaries set() Sets a new record boundary. (See: "Record boundaries" on page 124.) Boundaries setVariable () Sets a boundaries variable to the specified value, automatically creating the variable if it doesn't exist yet. Boundaries find() Method of the boundaries object that finds a string in a region of the data source file.
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 291 and "Example" on page 292. 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 "Example" on page 292.
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 Return type filename The path of the input file. Returns the fully qualified file name of the temporary work file being processed. properties Contains properties declared in the preprocessor step (see Preprocessor Step Properties for details).
Method Description Script type File type and Postprocessor steps "Examples" on page 286 Finds the first occurrence of a string starting from the current position. Boundaries "Examples" on page 289 Finds the first match for a regular expression pattern starting from the current position.
Number that represents the total height of the region, measured in lines. Setting the regionHeight to 0 instructs the DataMapper to extract all lines starting from the given position until the end of the record. 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 ("").
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 "Example" on page 297). 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.
extractMeta() Method that extracts the value of a metadata field on a certain level in a PDF/VT. This method always return a String. extractMeta(levelName String, propertyName String) levelName String, specifying the PDF/VT's level. Case-sensitive. propertyName String, specifying the metadata field. fieldExists() Method of the data object that returns true if a certain metadata field, column or node exists. (See "data" on page 276.
fieldExists(levelName, propertyName) This method returns true if the given metadata field exists at the given level in a PDF file. levelName String that specifies the metadata field. propertyName String that specifies the level. fieldExists(fieldName) This method returns true if the specified column exists in the current record in a CSV file. fieldName String that represents a field name (column) in a CSV file.
Partial matches are not allowed. The entire string must be found between the two constraint parameters. The data.find() function only works on the current page. If the record contains several pages, you must create a loop that will perform a jump from one page to another to do a find() on each page. Note Calling this method does not move the current position to the location where the string was found.
Left=26,76, Top=149.77, Right=40,700001, Bottom=154.840302 These values represent the size of the rectangle that encloses the string in full, in millimeters relative to the upper left corner of the current page. findRegExp() Finds the first occurrence of a string that matches the given regular expression pattern, starting from the current position.
matching can be enabled by specifying the UNICODE_CASE flag (u) in conjunction with this flag. s: Enables dotall mode. In dotall mode, the expression . matches any character, including a line terminator. By default this expression does not match line terminators. L: Enables literal parsing of the pattern. When this flag is specified, then the input string that specifies the pattern is treated as a sequence of literal characters.
Examples data.findRegExp(/\d{3}-[A-Z]{3}/,"gi",50,100); or data.findRegExp("\\d{3}-[A-Z]{3}","gi",50,100);}} Both expressions would match the following strings: 001-ABC, 678-xYz. Note how in the second version, where the regular expression is specified as a string, some characters have to be escaped with an additional backslash, which is standard in JavaScript. db Object that allows to connect to a database. Methods The following table describes the methods of the db object.
user String that represents the user name for authentication. password String that represents the password for authentication. logger Global object that allows logging messages such as error, warning or informational messages. Methods The following table describes the methods of the logger object.
Example See this How-to for an example of how the current record index, and/or the total number of records in the record set, can be displayed in a document: How to get the record index and count. region The region object defines a sub-section of the input data. Its properties vary according to the type of data. This object is available when triggering document boundaries On script; see "Setting boundaries using JavaScript" on page 264. Methods The following table describes the methods of the region object.
Method Description Return Type () physical coordinates of the region object. coordinates. 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 the previous page). 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.
} } (The match() function expects a regular expression; see w3schools.) 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. if(!(boundaries.Eof || boundaries.Bof)){ var recordValue = boundaries.
Example The property, used by the object Source Record, must first be declared in a Preprocessor step: 1. Enter the property Name. 2. Select Each record from the Scope drop-down list. 3. Select a Type for the Property. steps 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. These are available in Extract, Condition, Repeat, and Action steps, depending on the file type. Method Description File type currentPosition Returns the current position of the pointer in the data. Depending on the type of data being processed, the return value may be a string (e.g. XPath value in XML), an integer (e.g. line numbers in text ot tabular data), or a measure in millimeters(e.g. PDF data).
Method Description File type inside the current record. PDF Example if(steps.currentPage > curPage) { steps.moveTo(0, steps.currentPosition+14); /* Moves the current position to 14 lines below the current position of the pointer in the data */ curPage++; } else if(curLine.startsWith("LOAD FACTOR")) { /* Extracts data to the curLine variable until the string "LOAD FACTOR" is encountered */ break; } else { lineArray.
With the scope set to 0 or steps.MOVELINES, verticalPosition represents the index of the line to move to from the top of the record. With the scope set to 1 or steps.MOVEDELIMITERS, verticalPosition represents the index of the delimiter (as defined in the Input Data settings) to move to from the top of the record. With the scope set to 2, verticalPosition is not used. The position is moved to the next line after the current position that contains any text.
With the scope set to 1 or steps.MOVEPAGES, verticalOffsetrepresents the index of the target page, relative to the top of the record. moveTo(xPath) Moves the current position in a XML file to the first instance of the given node, relative to the top of the record. xPath String that defines a node in the XML file. Tip The XML elements drop-down (on the Settings pane, under Input Data) lists xPaths defining nodes in the current XML file.
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.
copyFile(source, target) source String that specifies the source file path and name. target String that specifies the target file path and name. Example This script copies the file test.txt from c:\Content into the c:\out folder. copyFile("c:\Content\test.txt","c:\out\") createTmpFile() Function that creates a file with a unique name in the temporary work folder and returns a file object. This file stores data temporarily in memory or in a buffer.
writer.newLine(); } } finally{ // Close the writer of the temporary file writer.close(); } } finally{ // Close the reader reader.close(); } deleteFile(data.filename); tmpFile.move(data.filename); createHTTPRequest() Function that creates a new ScriptableHTTPRequest object, in order to issue REST/AJAX calls to external servers.
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.
getResponseBody() Returns the full response body of the last 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.
Examples 1. Deleting a file in a local folder: deleteFile("c:\Content\test.txt"); 2. Deleting the sample data file used in the DataMapper: deleteFile(data.filename); execute() Function that calls an external program and waits for it to end. 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.
newDoubleArray() Function that returns a new double array. newDoubleArray(size) Returns a new Double array of the specified number of elements. size Integer that represents the number of elements in the new array. newFloatArray() Function that returns a new float array. 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.
Integer that represents the number of elements in the new array. newStringArray() Function that returns a new string array. newStringArray(size) Returns a new String array of the specified number of elements. size Integer that represents the number of elements in the new array. openBinaryReader() Function that opens a file as a binary file for reading purposes. The function returns a BinaryReader object. 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 Data Mapper for reading. var var var var fileIn = openTextReader(data.filename); tmp = createTmpFile(); fileOut = openTextWriter(tmp.getPath()); line; while((line = fileIn.readLine())!=null){ fileOut.
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.filename); tmp = createTmpFile(); fileOut = openTextWriter(tmp.getPath()); line; while ((line = fileIn.readLine())!=null){ fileOut.write(line.
The Designer The Designer is a WYSIWYG (what you see is what you get) editor that lets you create templates for various output channels: Print, Email and Web. A template may contain designs for multiple output channels: a letter intended for print and an e-mail variant of the same message, for example. Content, like the body of the message or letter, can be shared across these contexts. Templates are personalized using scripts and variable data extracted via the DataMapper.
1. Create a template Create a template, using one of the Template Wizards. See "Creating a template" on the next page. 2. Fill the template Add text, images and other elements to the template and style them. See "Content elements" on page 472 and "Styling and formatting" on page 558. 3. Personalize the content Personalize the content using variable data. See "Personalizing Content" on page 599. 4. Generate output Adjust the settings, test the template and generate output: letters, emails, and/or web pages.
"Content elements" on page 472. Elements make up the biggest part of the content of each design. "Snippets" on page 555. Snippets help share content between contexts, or insert content conditionally. "Styling and formatting" on page 558. Make your Designer templates look pretty and give them the same look and feel with style sheets. "Personalizing Content" on page 599. Personalize your customer communications using variable data. "Writing your own scripts" on page 631.
l "Creating a Web template with a Wizard" on page 389 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. After creating a template you can add the other contexts (see "Contexts" on page 327), as well as extra sections (see "Sections" on page 328), to the template. It is, however, not possible to use a Template Wizard when adding a context or section to an existing template.
dialog. When the package contains print presets, you will be asked if you want to import them into the proper repositories. Saving a template A Designer template file has the extension .OL-template. It is a zip file that includes up to 3 contexts, all the related resources and scripts, and (optionally) a link to a Data Mapping Configuration. To save a template for the first time, select File > Save as. After that you can save the template by selecting File > Save or pressing Ctrl+S.
To change which data mapping configuration is linked to the template, open both the template and the data mapping configuration that should be linked to it; then save the template. Auto Save After a template has been saved for the first time, Connect Designer can auto save the template with a regular interval. To configure Auto Save: 1. Select the menu option Window > Preferences > Save. 2. Under Auto save, check the option Enable to activate the Auto Save function. 3.
Sharing a template To share a template, you can send the template file itself, or save the template to a package file, optionally together with a Data Mapping Configuration, a Job Creation Preset and an Output Creation Preset. (See "Job Creation Presets" on page 849 and "Output Creation Settings" on page 860 for more details.) To create a package file, select File > Send to Workflow and choose File in the Destination box. For the other options, see "Sending files to Workflow" on the facing page.
The following zip file contains both the template and data mapping configuration that are used to generate the standard template report: http://help.objectiflune.com/en/archive/reporttemplate.zip. Generating output from the Designer Output can be generated directly from the Designer; see "Generating Print output" on page 967, "Generating Email output" on page 984 and "Generating Web output" on page 992. To test a template first, select Context > Preflight.
5. Use the drop-down to select an Output Creation Preset. Click Browse to select a preset that is not in the default location for presets. An Output Creation Preset file has the extension .OL-outputpreset. 6. Finally, choose the Destination: use the drop-down to select where to send the files. The option Workflow machines lists all the PReS Workflow installations detected on the network. Select File to save the files as a package that can be loaded within the Workflow tool.
1. l l In the Welcome screen that appears after startup, choose Browse Template Wizards. Scroll down until you see the Foundation Web Page Starter Template Wizards. Alternatively, on the File menu, click New, expand the Template folder, and then expand the Foundation Web Page Starter folder. 2. Select a template.
l Primary: links on the page. l Secondary: secondary links on the page. l Text: text on the page contained in paragraphs (
). l Headings: all headings (
through ) including the heading section's subhead. 4. Click Finish to create the template. The Wizard creates: l l l l A Web context with one web page template (also called a section) in it.
Use the Styles pane next to the Attributes pane to see which styles are applied to the currently selected element. Tip Click the Edges button on the toolbar to make borders of elements visible on the Design tab. The borders will not be visible on the Preview tab. Web Template Wizards Foundation All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon.
Blank web page The Blank Web Page template is a very simple Foundation template that contains a top bar menu and some basic contents to get you started. Capture OnTheGo template wizards With the Designer you can create Capture OnTheGo (COTG) templates. COTG templates are used to generate forms for the Capture OnTheGo mobile application. For more information about this application, see the website: Capture OnTheGo.
user-friendly as possible. See "Designing a COTG Template" on page 420. Creating a COTG template using a Wizard To create a COTG template with a Template Wizard: 1. l l In the Welcome screen that appears after startup and when you click the Home icon at the top right, choose Browse Template Wizards. Scroll down until you see the Capture OnTheGo Starter Template Wizards. Alternatively, on the File menu, click New, expand the Template folder, and then expand the Capture OnTheGo Starter folder. 2.
3. Click Next and make adjustments to the initial settings. l l l l Create Off-Canvas navigation menu: an Off-Canvas menu is a Foundation component that lets you navigate between level 4 headings (
) in the form. Check this option to add the menu automatically. Submit URL: enter the URL where the form data should be sent. The URL should be a server-side script that can accept COTG Form data. The Title and the Logo that you choose will be displayed at the top of the Form.
http://127.0.0.1:8080/action (8080 is Workflow's default port number; 'action' should be replaced by the HTTP action of that particular HTTP Server Input task). The method of a Capture OnTheGo form should be POST to ensure that it doesn't hit a data limit when submitting the form. The GET method adds the data to the URL, and the length of a URL is limited to 2048 characters. Especially forms containing one or more Camera inputs may produce a voluminous data stream that doesn't fit in the URL.
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. 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.
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. The path must have forward slashes, for example 
PAGE 327
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).
If present in the same template, a Print context and a Web context can be attached to an Email context. Outputting other combinations of contexts, and selecting sections based on a value in the data, can be done via a Control Script; see "Control Scripts" on page 652. Adding a context To add a context, right-click the Contexts folder on the Resources pane and click New print context, New email context or New web context. Only one context of each type can be present in a template.
Tip If an Email context is going to be part of the template, it is recommended to start with an Email Template Wizard; see "Creating an Email template with a Wizard" on page 371. After creating a template, contexts can be added to it, but that can not be done with a wizard. Editing a section To open a section, expand the Contexts folder on the Resources pane, expand the respective context (Print, Email or Web) and double-click a section to open it.
Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored. After closing and reopening the template it is no longer possible to restore the deleted context this way. Renaming a section To rename a section: l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, right-click the name of the section, and then click Rename.
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.
Outputting sections Which sections are added to the output, depends on the type of context they are in. When generating output from the Print context, each of the Print sections is added to the output document, one after the other in sequence, for each record. The sections are added to the output in the order in which they appear on the Resources pane. See "Generating Print output" on page 967. In email and web output, only one section can be executed at a time.
When a Print template is created or when a Print context is added to an existing template the Print context folder is created along with other folders and files that are specific to a Print context (see "Creating a Print template with a Wizard" on the facing page, "Adding a context" on page 328 and "Print context" on page 339). Only one Print section is created at the start, but you can add as many Print sections as you need; see "Print sections" on page 342.
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. When both Media and a Master Page are used on a certain page, they will both be displayed on the Preview tab of the workspace, the Master Page being 'in front' of the Media and the Print section on top.
l l Select the PDF-based Print wizard. Or expand the Basic Print templates folder, select Postcard or Formal Letter and click Next. See "Print Template Wizards" below for information about the various types of Template wizards. 2. Make adjustments to the initial settings (the options for each type of template are listed below). Click Next to go to the next settings page if there is one. 3. Click Finish to create the template.
l l l l Two Master Pages that each contain a background image. The first Master Page is applied to the front of every page in the Print section. The second Master Page is applied to the back of every page in the Print section. See "Master Pages" on page 357. Scripts and selectors for variable data. The Scripts pane shows, for example, a script called "first_name".
l l Click the Browse button to select a signature image. This image will appear above the sender's name and title. Select Virtual Stationery: a PDF file with the letterhead stationery. Also see Media. When you click Finish, the Wizard creates: l l l l A Print context with one section in it; see "Print context" on page 339 and "Print sections" on page 342. One empty Master Page.
PDF-based Print template 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. The PDF-based Print template wizard creates a document from an existing PDF file: a brochure, voucher, letter, etc. The PDF is used as the background image of the Print section (see "Using a PDF file as background image" on page 346).
Print context The Print context is the folder in the Designer that can contain one or more Print templates. Print templates, also called Print sections, are part of the Print context. They are meant to be printed to a printer or printer stream, or to a PDF file (see "Generating Print output" on page 967). The Print context can also be added to Email output as a PDF attachment; see "Generating Email output" on page 984.
l One Master Page is added to the template, as can be seen on the Resources pane, in the Master Page folder. In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear on each first page, or only on pages in between the first and the last page, or only on the last page. Examples are a different header on the first page, and a tear-off slip that should show up on the last page.
It is also possible to exclude sections from the output, or to include a section only on a certain condition that depends on a value in the data. This can be done using a Control Script; see "Control Scripts" on page 652. Printing on both sides To print a Print section on both sides of the paper, that Print section needs to have the Duplex printing option to be enabled; see "Enabling double-sided printing (Duplex, Mixplex)" on page 349.
1. Create a Job Creation Preset that overrides the settings of one or more sections: select File > Presets and see "Job Creation Presets" on page 849 for more details. 2. Select that Job Creation Preset in the Print wizard; see "Generating Print output" on page 967. Setting the bleed The bleed is the printable space around a page. It can be used on some printers to ensure that no unprinted edges occur in the final trimmed document. The bleed is one of the settings for a section.
This is what Master Pages are used for. Master Pages can only be used in the Print context. See "Master Pages" on page 357 for an explanation of how to fill them and how to apply them to different pages. Using stationery (Media) When the output of a Print context is meant to be printed on paper that already has graphical and text elements on it (called stationery, or preprinted sheets), you can add a copy of this media, in the form of a PDF file, to the Media folder.
to be printed out on paper. When a Print template is created (see "Creating a Print template with a Wizard" on page 334 and "Print context" on page 339), only one Print section is added to it, but you can add as many print sections as you need. To add a section to a context: l On the Resources pane, expand the Contexts folder, right-click the Print context , and then click New section.
Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored. After closing and reopening the template it is no longer possible to restore the deleted context this way. Arranging Print sections When generating output from the Print context, each of the Print sections is added to the output document, one after the other in sequence, for each record.
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. Use the arrow buttons to move the files that should be included to the list at the right. 4. You can also change the order in which the CSS files are read: click one of the included CSS files and use the Up and Down buttons.
file that was used as input file, or another type of input file, converted to a PDF file. With this option you don't need to make any other settings; click OK to close the dialog. 3. For a PDF resource, you have to specify where it is located. Clicking the Select Image button opens the Select Image dialog (see "Select Image dialog" on page 733). Click Resources, Disk or Url, depending on where the image is located.
5. Optionally, if the PDF has more than one page, you can set the range of pages that should be used. Note The number of pages in the Print section is automatically adjusted to the number of pages in the PDF file that are being used as the section's background image. 6. Finally, click OK. Note To set the background of a section in script, you need a Control Script; see "Control Scripts" on page 652 and "Control Script API" on page 941.
1. Create a Job Creation Preset that overrides the settings of one or more sections: select File > Presets and see "Job Creation Presets" on page 849 for more details. 2. Select that Job Creation Preset in the Print wizard; see "Generating Print output" on page 967. Enabling double-sided printing (Duplex, Mixplex) To print a Print section on both sides of the paper, that Print section needs to have the Duplex printing option to be enabled. This is an option in the Sheet Configuration dialog.
Pages Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally limited by their size and margins. If the content of a section doesn't fit on one page, the overflow goes to the next page. This happens automatically, based on the section's page size and margins; see "Page settings: size, margins and bleed" on the next page.
When it comes to positioning elements on a page, Guides can be useful, as well as Tables. See "How to position elements" on page 574. Page settings: size, margins and bleed On paper, whether it is real or virtual, content is naturally limited by the page size and margins. These, as well as the bleed, are set per Print section, as follows: l On the Resources pane, right-click a section in the Print context and click Properties.
1. Import the promotional image or snippet; see "Images" on page 544 and "Snippets" on page 555. 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.
l l l l Content page number: The current page number in the document, counting only pages with contents that are supplied by the Print section. A page that has a Master Page (as set in the Sheet Configuration dialog, see "Applying a Master Page to a page in a Print section" on page 359) but no contents, is not included in the Content page count. Content page count: This is the total number of pages in the current document that have contents, supplied by the Print section.
1. On the Resources pane, right-click a section in the Print context and click Numbering. 2. Uncheck Restart Numbering if you want the page numbers to get consecutive page numbers, instead of restarting the page numbering with this section. Note Even if a section is disabled, so it doesn't produce any output, this setting is still taken into account for the other sections. This means that if Restart Numbering is checked on a disabled section, the page numbering will be restarted on the next section.
In the entire Print context To prevent widows and orphans in the entire Print context: 1. On the menu, select Edit > Stylesheets. 2. Select the Print context. 3. Click New (or, when there are already CSS rules for paragraphs, click the selector p and click Edit). 4. Click Format. 5. After Widows and Orphans, type the minimum number of lines that should be kept together. Alternatively, manually set the set the widows and orphans properties in a style sheet: 1.
requires setting the Connect-specific data-breakable attribute on all of its rows. You can either open the Source tab, or write a script to replace each
with
. Note that the effect will only be visible in Preview mode. To set the number of widows and orphans for a table: 1. Open the Formatting dialog. To do this, you can: l l Select the table using the breadcrumbs or the Outline pane (next to the Resources pane) and then select Format > Table in the menu.Note You cannot use these properties on an empty
or on absolute-positioned elements. Preventing a page break To prevent a page break inside a certain element, set the page-break-inside property of that element to avoid: l Select the element (see "Selecting an element" on page 476). l On the Format menu, select the respective element to open the Formatting dialog. l In the Breaks group, set the inside property to avoid, to prevent a page break inside the element.
"Adding a Master Page" below. Initially, the original Master Page will be applied to all pages, but different Master Pages can be applied to different pages; see "Applying a Master Page to a page in a Print section" on the next page. Examples There are a few How-tos that demonstrate the use of Master Pages: l Showing a Terms and Conditions on the back of the first page only. l A tear-off section on the first page of an invoice. l Tips and tricks for Media and Master Pages.
Keep in mind that a Master Page always remains a single page. Its content cannot overflow to a next page. Content that doesn't fit, will not be displayed. Note Editing the Master Page is optional. One Master Page must always exist in a Print template, but if you don't need it, you can leave it empty. Adding a header and footer Headers and footers are not designed as part of the contents of a Print section, but as part of a Master Page, which is then applied to a page in a print section.
set a different Master Page and Media (see "Media" below). It can even have two master pages, if printing is done on both sides (called duplex printing). To apply Master Pages to specific page positions in a Print section: 1. On the Resources pane, expand the Print context; right-click the Print section, and click Sheet configuration. 2. Optionally, check Duplex to enable content to be printed on the back of each sheet. Your printer must support duplex for this option to work.
Media can be applied to pages in a Print section, to make them appear as a background to those pages. This ensures that elements added to the Print context will correspond to their correct location on the preprinted media. For further explanation about how to apply Media to different pages, see "Applying Media to a page in a Print section" on page 364. Media will not be printed, unless you want them to; see below.
type of image file) for both the front and the back of the Media, and you can determine how the virtual stationery should be positioned on the page. This is done as follows: 1. On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Properties. 2. Now you can change the name and page size of the Media. Note that it isn't possible to change the page size once the Media is applied to a section. Media can only be applied to sections that have the same size. 3.
8. For each of the PDF files, select a position: l Fit to page stretches the PDF to fit the page size. l Centered centers the PDF on the page, vertically and horizontally. l Absolute places the PDF at a specific location on the page. Use the Top field to specify the distance between the top side of the page and the top side of the PDF, and the Left field to specify the distance between the left side of the page and the left side of the PDF. 9. Finally, click OK.
l l On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Rename. Type the new name and click OK. Alternatively, on the Resources pane, expand the Contexts folder, expand the Media folder, right-click the Media and click Properties. Type the new name in the Name field and click OK.
Dynamically switching the Media In addition to applying Media to sheets via the settings, it is possible to change Media dynamically, based on a value in a data field, in a script. The script has already been made; you only have to change the name of the Media and the section in the script, and write the condition on which the Media has to be replaced. 1. On the Resources pane, expand the Contexts folder, expand the Print context, rightclick the print section and click Sheet configuration. 2.
l l On the Resources pane, expand the Print context; right-click the Print section, and click Sheet configuration. Click one of the options next to Media rotation. The Media (to be more accurate: the Virtual Stationery images specified for this Media) as well as the section's background image will be rotated accordingly in the entire section. Note that any Virtual Stationery settings made for the Media also influence how the Media is displayed in each section (see "Setting Media properties" on page 361).
Email template It is strongly recommended to start creating an Email template with a Wizard; see "Creating an Email template with a Wizard" on page 371. Designing HTML email that displays properly on a variety of devices and screen sizes is challenging. Building an email is not like building for the web. While web browsers comply with standards (to a significant extent), email clients do not. Different email clients interpret the same HTML and CSS styles in totally different ways.
Designing an Email template With the Designer you can design Email templates. It is strongly recommended to start creating an Email template with an Email Template Wizard, because it is challenging to design HTML email that looks good on all email clients, devices and screen sizes that customers use when they are reading their email.
Email templates: Slate and others The most obvious solution offered in the Designer is to use one of the templates provided with the Designer; see "Creating an Email template with a Wizard" on page 371. The layout of these templates has been tested and proven to look good in any email client, on any device and screen size. The Tables in these templates are nested (put inside another table) and they have no visible borders, so readers won't notice them.
To learn more about Emmet, please see their website: Emmet.io and the Emmet.io documentation: http://docs.emmet.io/. Preferences To change the way Emmet works in the Designer, select Window > Preferences, and in the Preferences dialog, select Emmet; see "Emmet Preferences" on page 715. Using CSS files with HTML email Email clients do not read CSS files and some even remove a
