Objectif Lune PRes Connect - 1.4 Operation Manual

Download

Page 1

User Guide

Version:1.4.2

Page 2

Page 3

User Guide Version 1.4.2 Last Revision:2016-06-30

Objectif Lune, Inc. 2030 Pie-IX, Suite 500 Montréal, QC, Canada, H1V 2C8

+1 (514) 875-5863

www.objectiflune.com

All trademarks displayed are the property of their respective owners.

© Objectif Lune, Inc. 1994-2016. All rights reserved. No part of this documentation may be reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever without the express written permission of Objectif Lune Inc. Inc. Objectif Lune Inc. Inc. disclaims responsibility for any errors and omissions in this documentation and accepts no responsibility for damages arising from such inconsistencies or their further consequences of any kind. Objectif Lune Inc. Inc reserves the right to alter the information contained in this documentation without notice.

Page 4

Table of Contents 4

Welcome to PReS Connect 1.4.2 8

Icons used in this guide 9

Setup And Configuration 10

System and Hardware Considerations 10

Installation and Activation 17

Server Settings 33

DataMapper Module 38

Basics 38

Features 38

DataMapper User Interface 89

Defining Boolean Values 163

Defining String Values 163

Building String Values 164

Defining Integer Values 165

Building Integer Values 165

Defining Float Values 166

Page 4

Page 5

Building Float Values 166

Defining Currency Values 166

Building Currency Values 167

Defining Date Values 167

Defining Object Values 168

The Designer 171

API 171

Basic Steps 215

Features 217

Designer User Interface 449

Mark Position Options 535

Additional Text 540

Additional Images 540

Additional Barcodes 541

Additional OMRMarks 541

Additional Text Settings 543

Additional Image Settings 544

Barcode Options 545

Standard Barcode Settings 545

Page 5

Page 6

Codabar Settings 547

Code 128 Settings 549

Code 39 Settings 551

Additional Datamatrix Settings 553

Additional EAN 128 Settings 555

Additional EAN 13 Settings 556

Additional EAN 8 Settings 558

Additional Interleave 2 of 5 Settings 560

Additional PDF417 Settings 562

Additional QR Code Settings 564

Additional UPC A Settings 566

Additional UPC E Settings 568

Additional OMR Mark Settings 570

Keystore 575

PDF Signature 576

Print Manager 597

Print Manager Introduction Video 597

Print Manager usage 597

Print Manager Interface 597

Page 6

Page 7

Legal Notices and Acknowledgements 609

Page 7

Page 8

Welcome to PReS Connect 1.4.2

Note

In our continuous effort to facilitate your PReS Connect experience, our entire documentation is being overhauled. Since we are still in the process of restructuring all this information, expect to see our online help evolve frequently over the next few weeks. We apologize for any inconvenience, but know we are working hard to improve your experience as quickly as possible.

Since we are always looking for new ways to make your life easier, we welcome your questions and comments about our products and documentation. A feedback tool will soon be at the bottom of each page. In the meantime, shoot us an email at

doc@ca.objectiflune.com.

PReS Connect is a series of four tools designed to optimize and automate customer communications management. They work together to improve the creation, distribution, interaction and maintenance of your communications.

The PReS Connect Datamapper and Designer is designed to create output for print, email and the web within a single template and from any data type, including formatted print streams. Output presets applied outside the design phase make printing device independent.

The Designer has an easy-to-use interface that makes it possible for almost anyone to create multi-channel output. More advanced users may use native HTML, CSS and JavaScript.

PReS Connect also includes a process automation server, called Workflow. It is capable of servicing response form web pages and email to provide interactive business communications.

PReS Connect can create documents for tablets and mobile devices that run a free CaptureOnTheGo App. Users with a CaptureOnTheGo subscription can then download documents to their own devices, interact with them and send the captured data back to PReS for conversion into additional documents or workflows.

This online documentation covers PReS Connect version 1.4.2.

Page 8

Page 9

Icons used in this guide

Note

Complementary information that is not critical, but may help you better use PReS Connect.

Tip

Information that is useful or suggests an easier method.

Technical

Information that may require specific knowledge to understand.

Warning

Information that is potentially critical to using PReS Connect. Pay close attention.

Icons are used throughout this guide to point your attention to certain information.

Page 9

Page 10

Setup And Configuration

Note

Windows XP, Windows 2003 and older versions of Windows are not supported by PReS

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 17 l "Server Settings" on page 33

System and Hardware Considerations

There are a variety of considerations to be aware of. These are documented in the following pages:

l "System Requirements" below l "Environment considerations" on the next page l "Database Considerations" on page 13 l "Network considerations" on page 13 l "Language and Encoding considerations" on page 14 l "Performance Considerations" on page 14

System Requirements

These are the system requirements for PReS Connect 1.4.2

Operating System (64-bit only)

l Microsoft Windows 2008/2008 R2 Server l Microsoft Windows 2012/2012 R2 Server l Microsoft Windows Vista l Microsoft Windows 7 l Microsoft Windows 8.1 l Microsoft Windows 10

Page 10

Page 11

Connect.

Minimum Hardware Requirements

Note

For tips and tricks on performance, see "Performance Considerations" on page 14.

Warning

Copying (duplicating) a Virtual Machine with Connect installed and using both images simultaneously constitutes an infringement of our End-User License Agreement.

Note

While some VMWare (from VMWare, Inc.) and Microsoft virtual machine environments are supported, other virtual environments (such as Parallels, Xen and others) are not supported at this time.

l NTFS Filesystem (FAT32 is not supported) l CPU Intel Core i7-5960X @ 3.00GHz (8 core with Hyper-Threading) l 16GB RAM l Disk Space: At least 10GB (20GB recommended)

Environment considerations

Virtual Machine Support

PReS Connect supports VMWare Workstation, VMWare Server, VMWare Player, VMWare ESX, Microsoft Hyper-V and Microsoft Hyper-V/Azure infrastructure environments as software installed on the Guest operating system. PReS Connect does not officially support VMotion under ESX at the moment.

Page 11

Page 12

Terminal Server/Service

PReS Connect does not support Terminal Server (or Terminal Service) environment as possible under Windows 2000, 2003 and 2008. This is to say, if Terminal Service is installed on the server where PReS Connect is located, unexpected behaviours may occur and will not be supported by Objectif Lune Inc.. Furthermore, using PReS Connect in a Terminal Service environment is an infringement of our End-User License Agreement.

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.

64-bit Operating Systems

PReS Connect is a 64-bit software and can only be installed on 64-bit operating systems.

Antivirus Considerations

l Antivirus software may slow down processing or cause issues if they are scanning in

temporary folders or those used by PReS Connect. Please see KB-002: Antivirus Exclusions for more information.

l Antivirus software might interfere with installation scripts, notably a vbs script to install

fonts. McAfee, in particular, should be disabled temporarily during installation in order for MICR fonts to install and the installation to complete successfully.

Windows Search Indexing Service

Tests have concluded that the Windows Search service, used to provide indexing for Windows Search, can interfere with Connect when installing on a virtual machine. If the installation hangs during the last steps, it is necessary to completely disable this service during installation.

l Click on Start, Run.

Type in services.msc and click OK.

Locate the Windows Searchservice and double-click on it.

Change the Startup Type to Disable, and click Stop to stop the service.

Try the installation again.

Once completely, you may re-enable the service and start it.

Page 12

Page 13

Database Considerations

This page describes the different considerations and pre-requisites for the database back-end used by PReS Connect, whether using the MySQL instance provided by the installer, or preexisting instance.

Using the MySQL Instance from the Installer

The MySQL Instance provided in the Installation Wizard is already pre-configured with options to provide the most stable back-end setup.

These are the specific options that have been changed in our version of "my.ini":

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. This substantial packet size maximum setting ensures that the data received by PReS Connect will be able to be stored within the database.

character-set-server = utf8 , collation-server = utf8_unicode_ci , default-characterset=utf8 : These indicate database support for UTF-8/Unicode.

Using a pre-existing MySQL Instance

If MySQL server is already installed and you wish to use it, the following should be taken into consideration:

l The MySQL account must have access to all permissions using the GRANT Command,

including creating databases.

l The database configuration must include the options detailed in the "Using the MySQL

Instance from the Installer" above section.

l The SQL instance must be open to access from other computers. This means the bind-

address option should not be set to 127.0.0.1 or localhost.

Network considerations

The following should be taken into consideration in regards to network settings and communications

Page 13

Page 14

If a local proxy is configured (in the Internet Explorer Optionsdialog, the option Bypass proxy server for local addresses must be checked, or some features depending on

local communication will not work.

Language and Encoding considerations

Please note the following considerations:

Language:

l PReS Connect is currently offered in several languages. These languages can be

switch between via the Preferences dialog. The current languages include:

l English l French l German l Spanish l Italian l Portuguese l Chinese (Simplified) l Chinese (Traditional) l Japanese.

The default language is English. The PReS Connect help system (this document) is currently only available in English.

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.

Performance Considerations

This page is a comprehensive guide to getting the most performance out of PReS Connect as well as a rough guideline to indicate when it's best to upgrade.

Performance Analysis Details

In order to get the most out of PReS Connect, it is important to determine how best to maximize performance. The following guidelines will be helpful in extracting the best performance from

Page 14

Page 15

PReS Connect before looking into hardware upgrades or extra PReS Connect performance packs.

Job Sizes and Speed: In terms of pure output speed, it's important to first determine what job size is expected, and adjust Scheduling Preferences accordingly. The basic rules are:

l If processing a small number of very large records (when each individual record is

composed of a large number of pages), more instances with an equal amount of speed units is better. For hardware, RAM and Hard Drive speeds are most important, since the smallest divisible part (the record) cannot be split on multiple machines or even cores.

l If creating a very large number of small records (hundreds of thousands of 2-3 page

individual records, for instance), a smaller number of instances with a large number of speed packs would be better. As for hardware, then the number of cores becomes critical, whereas RAM and hard drive are secondary. Performance Packs, as well as the MySQL instance being separate, would be helpful if your most powerful machine starts struggling.

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. Assuming that the machine itself is not running any other software, the rule of thumb is the following: The total number of used memory in the machine should be pretty much the maximum available (around 95%).

For each engine, it's necessary to modify the .ini file that controls its JAVA arguments. Edit as follows:

l For the Merge Engine: see C:\Program Files\Objectif Lune\OL

Connect\MergeEngine\Mergeengine.ini

l For the Weaver Engine: see C:\Program Files\Objectif Lune\OL

Connect\weaverengine\Weaverengine.ini

l The parameters are -Xms640m for the minimum RAM size, -Xmx640m for the

maximum RAM size. Explaining Java arguments is beyond the scope of this document. Please read references here, here and here for more details (fair warning: these can get pretty technical!).

Template and data mapping optimization: Some functionality offered by the Designer modules are very useful, and sometimes downright awesome, but can cause the generation of records and of contents items to slow down due to their nature. Here are some of them:

Page 15

Page 16

Preprocessor and Postprocessor scripts: manipulating data using a script may cause delays before and after the data mapping action has actually taken place, especially file conversion and data enrichment from other sources.

Loading external and network resources: In Designer, using images, javascript or css resources located on a slow network or on a slow internet connection will obviously lead to a loss of speed. While we do our best for caching, a document with 100,000 records which queries a page that takes 1 second to return a different image each time will, naturally, slow output generation down by up to 27 hours.

External JavaScript Librairies: While loading a single javascript library from the web is generally very fast (and only done once for the record set), actually running a script on each generated page can take some time. Because yes, JavaScript will run for each record, and often take the same time for each record.

Inefficient Selectors: Using very precise ID selectors in script wizards can be much faster than using a text selector, especially on very large documents. (more details on this in another upcoming page).

Complex Scripts: Custom scripts with large, complex or non-optimized loops can lead to slowing down content creation. While it is sometimes difficult to troubleshoot, there are many resources online to help learn about JavaScript performance and coding mistakes. Here, here, and here are a few. Note that most resources on the web are about JavaScript in the browser, but the greatest majority of the tips do, indeed, apply to scripts in general, wherever they are used.

High-Performance Hardware

The following is suggested when processing speed is important. Before looking into a Performance Packs to enhance performance, ensure that the below requirements are met.

A physical, non-virtualized server. ESX and VMWare servers are great for reducing the numbers of physical machines in your IT space, but they must share the hardware between each other. While you can create a virtual machine that seems as powerful as a physical, it will still be sharing hardware with any other virtual machines, and this will adversely affect performance.

MySQL Database on a separate machine. MySQL's main possible bottleneck is file I/O, and as such a high-performance setup will require this server to be on a separate machine, ideally with a high-performance, low-latency hard drive. A Solid State Drive (SSD) would be recommended.

High-Quality 16+ GB Ram. This is especially true when working with many server instances ("speed units") running in parallel. The more parallel processing, the more RAM is recommended.

Page 16

Page 17

Note

A PDF version of this guide is available for use in offline installations. Click here to

download it.

4 or 8 physical cores. We're not talking Hyper-Threading here, but physical cores. Hyper-Threading is great with small applications, but the overhead of "switching" between the virtual cores, and the fact that, well, they're virtual, means the performance is much lesser on high-power applications such as OL Connect. In short, a dual-core processor with Hyper-Threading enabled is not equivalent to a quad-core processor.

Installation and Activation

This section provides detailed information about the installation and activation of PReS Connect 1.4.2.

PReS Connect 1.4.2 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.4.2 and PReS Workflow 8 can be obtained on DVD or downloaded as follows:

l If you are a Customer, the installers can be downloaded from the Objectif Lune Web

Activations page: http://www.objectiflune.com/activations

l If you are a Reseller, the installers can be downloaded from the Objectif Lune Partner

Portal: http://extranet.objectiflune.com/

For information on licensing, please see Activating your license.

Installation Pre-Requisites

l Make sure your system meets the System requirements. l PReS Version 1.4.2 can be installed under a regular user account with Administrator

privileges.

You must install on an NTFS file system.

Page 17

Page 18

l PReS requires Microsoft .NET Framework 3.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.

l In order to use the automation feature in Version 1.4.2, you need to install PReS Workflow

8. This can be installed on the same machine as an existing PlanetPress® Suite 7.6 installation or on a new computer. For more information, please see Information about

PReS Workflow 8.

l As with any JAVA application, the more RAM available, the faster the product will

execute.

Users of Connect 1.1

In order for users of PReS Connect 1.1 to upgrade to any later version through the Update Manager it is necessary to install a later version (1.1.8 or later) of the Objectif Lune Update Client.

If you do not have such a version installed already, the next time you run your Update Client it will show that there is an update available of itself to Version 1.1.8 (or later).

Simply click on the download button in the dialog to install the new version of the Update Client. Note that it is no problem to run the update while the Client is open. It will automatically update itself.

Once you have done this, PReS Connect 1.4.2 will become available for download.

Installing PReS Connect on Machines without Internet Access

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. When a machine hosting the installation does not have access to the Internet, the installation will fail because the verification cannot be performed. To solve this problem you must first ensure that all Windows updates have been installed on the host machine. You then need to complete the following steps:

1. Go to https://certs.godaddy.com/repository and download the following two certificates to copy to the offline machine:

Page 18

Page 19

l GoDaddy Class 2 Certification Authority Root Certificate - G2 - the file is gdroot-

Note

PReS Connect requires prior installation of Microsoft .NET Framework 3.5 (please refer to

https://www.microsoft.com/en-us/download/details.aspx?id=21 for more details).

g2.crt

l GoDaddy Secure Server Certificate (Intermediate Certificate) - G2 - the file is

gdig2.crt

2. Install the certificates: Right mouse click -> Install Certificate, and follow the steps through the subsequent wizard.

3. Now copy the PReS Connect installer to the offline machine and start the installation as normal

Installation Wizard

Starting the PReS Connect installer

The PReS Connect installer may be supplied as an ISO image or on a DVD:

l If an ISO image, either burn the ISO onto a DVD or unzip the contents to a folder (keeping

the folder structure)

l If on a DVD, either insert the DVD and initiate the installation from there or copy the

contents to a folder (keeping the folder structure)

Navigate to the PReS_Connect_Setup_x64.exe or and double-click on it. After a short while the Setup Wizard will appear as a guide through the installation steps.

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. Currently, the following are available:

PReS Connect Designer: The Designer module. It may be used as a standalone with no other installed modules, but it will not have certain capabilities such as automation and commingling.

PReS Connect Print Manager: The Print Manager module required for handling IPDS print output, as also available for managing PCLand PostScript output.

Page 19

Page 20

Technical

All instances of PReS Connect Server and PReS Connect Server Extension must use the same instances of MySQL. Although it is possible for each separate server installation to have its own MySQL instance, doing so will prevent the servers from functioning together in a "Server Clustering" on page 34 setup. However, this instance can be on any server whether it is a Server (master) or Server Extension (slave) machine.

PReS Connect Server: The Server back-end giving capabilities such as automation, commingling, picking. It saves all entities generated from the Automation module into a database for future use.

PReS Connect Server Extension: A slave server for a PReS Connect Server module. When an extension is installed, it communicates with the master server and shares tasks. Only one Server or Server Extension can be installed per machine, not both.

MySQL Product: The database used by the PReS Connect Engine to save its items. This item is optional if an existing MySQL server, either on the same computer or a separate server, is to be used.

Installation Path: This is the location where modules are to be installed.

The installer can also calculate how much disk space is required for installing the selected components as well as how much space is available:

Disk space required: Displays the amount of space required on the disk by the selected components.

Disk space available on drive: Displays the amount of space available for installation on the drive currently in the Installation Path.

Recalculate disk space: Click to re-check available disk space. This is useful if space has been made available for the installation while the installer was open.

Source repository location: Displays the path where the installation files are located. This can be a local drive, installation media, or a network path.

Selection Confirmation

The next page confirms the installation selections made. Click Next to start the installation itself.

Page 20

Page 21

End User License Agreement

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.

The next page displays the End User License Agreement, which needs to be read and accepted before clicking Next.

MySQL Configuration

The Default Database Configuration page only appears if the MySQL Product module was selected in the Product Selection screen. It defines the administrative password for the MySQL server as well as which port it uses for communication. Note that the installer will automatically configure the Server to use the supplied password and port.

MySQL user 'root' Password: Enter the password for the 'root', or administration account, for the MySQL server. The password must be at least 8 characters long and contain at least one of each of the following:

l a lower case character (a, b, c ... ) l an upper case character (A, B, C ...) l a numeric digit (1, 2, 3 ...) l a punctuation character (@, $, ~ ...)

For example:"Th1sIs@K"

Confirm 'root' Password: Re-enter to confirm the password. Both passwords must match for installation to continue.

TCP/IP Port Number: The port on which MySQL will expect, and respond to, requests. A check is run to confirm whether the specified TCP\IP Port Number is available on the local machine. If it is already being used by another service (generally, an existing MySQL installation), the number is highlighted in red and a warning message is displayed at the top of the dialog.

Allow MySQL Server to accept non-local TCP connections: Click to enable external access to the MySQL server. This is required if setting up clustering, or if MySQL Server

Page 21

Page 22

will need to be accessed from any other machine. It is also required if MySQL is on a

Note

The last option may represent a security risk if the machine is open to the internet. It is recommended to ensure your firewall blocks access to port 3306 from external requests!

separate machine than PReS Connect.

The Database Connection page appears if the MySQL Product module was not selected. It defines the necessary information required to connect to an existing database.

Database Configuration: Select the database type to use for the PReS Connect Engine. Currently, only MySQL is supported.

Administrator Username: Enter the username for a user with administrative rights on the database. Administrative rights are required since tables need to be created in the database. If accessing a database on a different machine, the server must also be able to accept non-local TCPconnections, and the username must also be configured to accept remote connection. For example, the "root"MySQLuser entered as root@localhost is not allowed to connect from any other machine than the one where MySQLis installed.

Administrator Password: Enter the password for the above user. The appropriate MySQL password must be entered or the Connect installation will fail.

TCP/IP Port Number: Enter the port on which the database server expects connections. For MySQL, this is 3306 by default.

Database Host Name: Enter the existing database server's IP or host name.

Server Schema/Table: Enter the name of the MySQL database into which the tables will be created. The Connect standard name is "objectiflune".

Test Connection button: Click to verify that the information provide into previous fields is valid by connecting to the database.

PReS Connect Server/Server Extension Configuration

The Server Configuration page is where the Server orServer Extension component is configured.

Run Server as: Defines the machine username and password that thePReS Connect Server module's service uses. This account should be administrator on the local

machine. Note that the "Server Security Settings" on page 33 dialog can only be

Page 22

Page 23

executed from the user specified here.

l l

Username: The username the service uses to login. If the machine is on a domain, use the format domain\username.

Password: The password associated with the username.

Validate user button: Click to verify that the entered username and password combination is correct and that the service is able to login. This button must be clicked and the user validated before the Next button becomes available.

The Server Extension Configuration page only appears when installing the PReS Connect Server Extension module. It defines the settings to be used to connect to the Master server (PReS Connect Server module):

Username: Enter the username expected by the OLConnect Server.

Username: Enter the username expected by the PReS Connect Server.

Password: Enter the password associated with the selected username

Hostname: Enter the machine name or IPAddress where the PReS Connect Server resides.

Port: Enter the port to use to communicate with the Connect Server. Default:9340

Use Server authentication checkbox: Check this option and enter appropriate User details, if the Server expects authentication.

Validate Connection button: Click to verify that the entered username and password is correct and the service is able to login. This button must be clicked and the user validated for the Next button to be available.

Click Next to start the actual installation process. This process can take several minutes.

Completing the installation

This screen describes a summary of the components that have been installed.

Configure Update Check checkbox: This option is enabled by default. It causes the Product Update Manager to run after the installation is complete. This allows

configuring PReS Connect to regularly check for entitled updates. Note: this checkbox may not be available in the event that an issue was encountered during the installation.

Show Log... : If an issue was encountered during the installation, click this button to obtain details. This information can then be provided to Objectif Lune for troubleshooting.

Page 23

Page 24

l When ready, click the Finish button to close the installation wizard, and initialize the

Technical

Before activating the software, please wait 5 minutes for the database to initialize. If the software is activated and the services rebooted too quickly, the database can become corrupted and require a re-installation.

Product Update Manager, if it was selected.

The Product Update Manager

If the Configure Update Check option has been selected, the following message will be displayed after clicking “Finish” in the setup:

Click “Yes” to install or open the Product Update Manager where the frequency with which the updates can be checked and a proxy server (if required) can be specified. Note: if the Product Update Manager was already installed by another Objectif Lune application, it will be updated to the latest version and will retain the settings previously specified.

Select the desired options and then click OK to query the server and obtain a list of any updates that are available for your software.

l Note that the Product Update Manager can also be called from the “Objectif Lune Update

Client” option in the Start menu.

l It can be uninstalled via Control Panel | Programs | Programs and Features.

Product Activation

After installation, it is necessary to activate the software. See Activating your license for more information.

How to Run Connect Installer in Silent Mode

The trigger for the Connect Installer to run in silent mode is a text file with the fixed name install.properties, which is located either in the same folder as the PReS_Connect_Setup_x86_

64.exe or in the unpacked folder of the installer.exe.

The file needs to be a properties file with the following line types:

Page 24

Page 25

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.

Required and Optional Properties

Here is an example of an install.properties file.

# Verbose logging

logging.verbose = true

# Product selection

install.product.0 = Connect Designer

install.product.1 = Connect Server

# Server settings

server.runas.username = Localadmin

server.runas.password = admin

# Database configuration

database.type = mysql

database.host = 192.168.116.10

database.port = 3308

database.username = root

database.password = admin

database.schema = my_ol

Verbose Logging (Optional)

By default, the Silent Installer will log in the same way as the GUI installer. That means logging of error and warnings, and certain information during database configuration. A more verbose logging can be switched on by using logging.verbose = true.

Page 25

Page 26

Product Selection (Optional)

By default, the Silent Installer will install all products which are visible to the user in the respective brand (except for the Server Extension, because only Server or Server Extension can be installed at the same time).

However, it is possible to define the products to be installed using their visible product names, and using a counter for the install.product property, e.g.

l install.product.0 = Connect Designer l install.product.1 = Connect Server

Other possible product names are Connect Print Manager, Connect Server Extension and MySQL Product.

Server / Extension configuration (required if Server / Extension is selected for install)

For both, Server and Server Extension, the user credentials who will be running the Server service need to be provided:

l server.runas.username l server.runas.password

Additionally for the Server Extension, some properties to define the Master Server are required:

l server.master.host l server.master.port l server.master.authenticate = true_or_false l server.master.username l server.master.password

Database configuration

If the MySQL Product is part of the installation, the following properties should be defined:

l database.type = mysql (required) l database.password (required, needs to match the security rules) l database.port (optional, the default is 3306. The defined port needs to be available.)

Additional properties are required when the configuration of an external MySQL database is required (this is the case if a Server product but not MySQL product is installed):

Page 26

Page 27

l database.host l database.username

Optionally, the "schema" name can be defined (the default is objectiflune):

database.schema

Information about PReS Workflow 8

If you wish to use PReS Workflow (automation) in conjunction with PReS Connect, you will need to install PReS Workflow 8 onto the same machine. Workflow 8 is provided through a separate installer which is available on CD or for download as follows:

l If you are a Customer, the installer can be downloaded from the Objectif Lune Web

Activations page: http://www.objectiflune.com/activations

l If you are a Reseller, the installer can be downloaded from the Objectif Lune Partner

Portal: http://extranet.objectiflune.com/

PReS Workflow 8 can be installed in parallel on the same machine as an existing PlanetPress® Suite 7.x installation. Note however:

l If both versions need to be hosted on the same machine, PReS Workflow 8 should

always be installed after the legacy PlanetPress® Suite 7.x installation.

l When uninstalling PReS Workflow 8, you may be prompted to repair your legacy

PlanetPress® Suite 7.x installation.

l If PReS Workflow 8 has been installed alongside PlanetPress® Suite 7, Capture can no

longer be used with Workflow 7. The plugins are now registered uniquely to Workflow 8 and the messenger for Workflow 7 is taken offline. It is only then possible to use Capture from PReS Workflow 8.

l PReS Workflow 8 and PlanetPress® Workflow 7 cannot run simultaneously, since only

one version of the Messenger service can run at a time. In fact, no 2 versions of PlanetPress Workflow can on the same machine simultaneously, whatever version is installed.

l It is possible to switch between different versions running by shutting down one version's

services and then starting the other. However, this is not recommended. There are no technical limitations that prevent processes from previous PlanetPress Workflow versions (as far back as Version 4) to run on PReS Workflow 8, removing the need to run both versions.

For more information on the licensing of Workflow 8, please see Activating your license.

Page 27

Page 28

Activating a License

PReS Connect and PReS Workflow 8 includes separate 30 day trial periods during which it is not necessary to have a license for reviewing basic functionality. If a modification to the license if required, such as to allow an extension to the trial period, or for extra functionality or plugins (e.g., the PReS Plugin for Workflow 8), then a new activation code will need to be requested.

Obtaining the PReS Connect Magic Number

To obtain an activation file the OL™ Magic Number must first be retrieved. The Magic Number is a machine-specific code that is generated based on the computer's hardware and software using a top-secret Objectif Lune family recipe. Each physical computer or virtual computer should have a different Magic Number, thus require a separate license file to be functional.

To get the PReS Connect Magic Number, open the PReS Connect Designer application:

Open the Start Menu

Click on All Programs, then Objectif Lune, then PReS Connect

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:

License Information section:

Magic Number: Displays the PReS Connect Magic Number.

Copy to Clipboard: Click to copy the Magic Number to the clipboard. It can then be pasted in the activation request email using the CTRL+V keyboard shortcut.

Licensed Products section:

Name: Displays the name of the application or module relevant to this activation.

Serial Number: Displays the activation serial number if the product has been activated in the past.

Expiration Date: Displays the date when the activation will expire (or the current date if the product is not activated)

Web Activations: Click to be taken to the online activation page (not yet functional).

End-User License Agreement (Appears only when loading a license file):

Page 28

Page 29

License: This box displays the EULA. Please note that this agreement is legally binding.

I agree: Select to accept the EULA. This option must be selected to install the license.

I don't agree: Select if you do not accept the EULA. You cannot install the license if this option is selected.

Load License File: Click to browse to the .olconnectlicense file, once it has been received.

Install License: Click to install the license and activate the software (only available when a license file is loaded).

Close: Click to cancel this dialog. If a license file has been loaded, it will not automatically be installed.

The Software Activation dialog can also be reached through a shortcut located in All Programs, then

Objectif Lune, then PReS Connect and is named Software Activation. Since it does not load the

software, it is faster to access for the initial activation.

Requesting a license

After getting the Magic Number, a license request must be done for bothPReS Connect and Workflow 8:

Customersmust submit their Magic Number and serial number to Objectif Lune via the Web Activations page: http://www.objectiflune.com/activations. The OL Customer Care team will then send the PReS Connect license file via email.

Resellerscan create an evaluation license via the the Objectif Lune Partner Portal by following the instructions there: http://extranet.objectiflune.com/

Note that if you do not have a serial number, one will be issued to you by the OL Activations team.

Accepting the license will activate it, after which the PReS Connect services will need to be restarted. Note that in some case the service may not restart on its own. To resolve this issue, restart the computer, or start the service manually from the computer's Control Panel.

Activating PReS Workflow 8

PReS Workflow 8 uses the same licensing scheme as PReS Connect. There are two ways of activating the license for Workflow 8 after saving it to a suitable location:

Page 29

Page 30

l If only PReS Workflow 8 is installed, double-click on the license for the PReS Workflow 8

License Activation dialog to open. Applying the license here activates all of the Workflow 8 components.

If you have both PReS Workflow 8 and PReS Connect installed, it will not be possible to double-click on the license file as this will always open the PReS Connect Activations Tool. Instead, open PReS Workflow 8 manually and apply the license through the activations dialog within.

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:

Open the Start Menu

Click on All Programs, then Objectif Lune, then PReS Connect

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

Click the Load License File button.

l Read the EULA and click I agree option to accept it.

Click Install License to activate the license. The license will then be registered on the computer and you will be able to start using the software.

After installation message will appear warning that the Server services will need to be restarted. Just click OK to proceed.

Migrating to a new computer

Currently there are no special migration tools to move data from one PReS Connect installation to another. Instructions for migration will be available for later versions of the software when those tools become available.

User accounts and security

Permissions for 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.

Page 30

Page 31

If generating Print output, PReS Connect Designer requires permission on the printer or printer queue to send files.

Permissions for PReS Connect Server

The PReS Connect Server module, used by the Automation module, requires some special permissions to run. These permissions are set during installation, in the Engine Configuration section of the Installation Wizard, but it can also be configured later by modifying permissions

for the service. To do this:

l In Windows, open the Control Panel, Administrative Tools, then Services (this may

depend on your operating system).

l Locate the service called Serverengine_UUID , where UUID is a series of characters that

depend on the machine where the software is installed.

Right-click on the service and select Properties.

In the Connection tab, define the account name and password that the service should use. This can be a local account on the computer or an account on a Windows Domain. The account must have administrative access on the machine. It should also correspond to the user account set up in PReS Worfklow.

The Importance of User Credentials on Installation and Running

OL Connect and required credentials depends heavily on the Connect component and respective tasks and what sort of user credentials are needed.

First of all, it is important to distinguish between installation and run-time

Installation

The Connect installer puts all required files, folders, registry entries and much more to their correct places and locations. As many of these locations are protected against malicious accesses, that very user under whose context the Connect installation is started and running, needs very extensive rights on the respective computer. This user must belong to the Local Administrators group on that machine. Here are some required capabilities, this user:

l Must be able to write into the "Programs" folder. l Must be allowed to check for existing certificates and must also be allowed to install new

ones into the global certificate store on that machine.

l Must be able to write into HKLM and any subtree of it in the registry.

Page 31

Page 32

l Must be able to INSTALL, START and RUN services and also to MODIFY service

settings.

l Must be known in the network the machine belongs to and must also need to be able to

use shared network resources like shared drives and/or printers etc.

This list may not be complete, but it gives the extent of the requirements. Generally, the local administrator of the machine will have all these credentials, but there may exist network restrictions and policies, which will block one or more of these capabilities. In such cases, the respective network administrator should provide a valid user account for the installation.

User Account

The user account shall be used to later RUN one of the Connect Server flavors (Server or Server Extension). This dedicated user account has to be entered on the respective installer dialog page and must be allowed to START, STOP and RUN services on this machine. This is different from the credentials of the installation user account, which additionally requires the right to INSTALL services. Please be aware of this fact!

Additionally, the Server user must be able to access any network resources that are required for OL Connect to function properly. This includes e.g. additional drives, printers, scanners, other computers and, where appropriate, internet resources, URLs, mail servers, FTP servers, database servers and everything else planned to be used for the intended operation of Connect. The Server user is the run-time user.

Connect Components

Usually, a standard end user will only be facing Connect Designer and maybe the License Activation Tool. Designer this does not require administrator rights. Either everything required to create documents or also to run some tasks will be already available (installed by the installer) or be accessible in a way, where no specific credentials are required. However some tasks like starting an email campaign will possibly require a respective account at a mail server. But this has generally nothing to do with the credentials of the Designer user.

Activation Tool

To run the Software Activation Tool, administrator rights are required because this tool needs to write the license file in one of the protected folders of Windows. The tool will however allow to restart it with respective credentials if required.

Page 32

Page 33

MySQL

Warning

It is highly recommended to keep security enabled and change the password on any server that accessible from the web. If these precautions are not taken, data saved in the server may be accessible from the outside!

MySQL database service is installed by the install user (thus again the requirement of installing, starting, running and modifying services). Once running it will just work.

Merge and Weaver Engines

These components do run under the Designer (if only Designer is installed) or the Server / Extension service(s) and inherit the rights of their parent application.

Server (Extension) Configuration Tool

This component needs to access the settings of the Server. As these are stored and read by the Server, it should be clear that the user used to run the Configuration tool should be the same as the Server Service user as explained above.

Server Settings

This chapter describes the different considerations that are important in regards to the use of PReS Connect Server.

l "Server Security Settings" below l "Server Extension Settings" on the facing page

Server Security Settings

This dialog controls the security settings for external applications connecting to the PReS Connect Server, such as PReS Workflow or scripts communicating through the REST API.

Enable server security: Enable to add authentication to the REST server. When disabled, a username and password is not required to make REST request, and tasks in PReS Workflow does not require them in the Proxy tab.

Page 33

Page 34

Administrator's username: Enter the username for the server security. The default username is ol-admin.

Administrator's password: Enter a password for the server security. The default password is secret.

Confirm password: Re-enter the password for the server security.

Default session length (min): Enter a session time (in minutes) that the authentication stays valid for the requested process. This can reduce the number of requests to the server since an authentication request is not necessary during the session.

Server Extension Settings

This dialog controls the different settings for the PReS Connect Server Extension.

The Preferences dialog is separated into individual pages, where each page controls certain aspects of the software.

The following Preferences pages are available:

l "Cleanup Service preferences" on page 457 l "Server Extension Scheduling Preferences" on page 36 (these are different in the Server

Extension preferences)

l Merge Engine Scheduling l Weaver Engine Scheduling

l "Server Security Settings" on the previous page

Server Clustering

Server Clustering, available in PReS Connect, enhances the processing capabilities of PReS Connect Server by load-balancing jobs between the main Server module (master) and one or more Server Extension installations.

Setting up Server Clustering requires two or more installations of 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.

Page 34

Page 35

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. Grant access to the MySQL root user for the appropriate IP range on the Master server.

4. Restart the MySQL Service on the Master server.

5. Install Slave servers (PReS Connect Server Extension module).

6. Install the license on the Master server (a Performance Pack license is required).

7. Set the preferences for the engines (see Scheduling Preferences) on both the Master and Slaves

8. Install the license on the Slave servers

9. Restart the Master server then, once restarted, restart the Slave servers.

What if MySQL is not on the Master server?

It is possible to setup clustering with a MySQL instance that is on a Slave server instead of on the master. In this case, the Slave server must be installed with the Server Extension and MySQL modules, the MySQL instance configured (steps 2-4 above) then the master and other slaves can be installed. The remainder of the instructions remain the same.

It is also possible to setup clustering with MySQL being installed completely separately from PReS Connect, such as using an existing MySQL instance. In this case, the instructions for the bind address must be followed, but the user does not have to be root. A user for MySQL must, however, be created and have full access (GRANT ALL PRIVILEGES) to a database called "objectiflune" that can be created before Connect is installed.

Binding and Root access on the Master server

l The MySQL server's binding must be set to accept connections from the slave servers. To

do this, open C:\Program Files\Objectif Lune\OL Connect\MySQL Product\MySQL\my.ini in a text editor and change the line bind-address= 127.0.0.1 to bind-

address=0.0.0.0.

Once the changes have been made and saved you need to restart the MySQL services.

l Access must be granted to the root user on the IPs from which the Slave server will

connect:

l Open a Command Prompt in the following folder: C:\Program Files\Objectif Lune\OL

Connect\MySQL Product\MySQL\bin (tip: navigate to the folder, SHIFT+Right-click and select "Open a command prompt here!).

Page 35

Page 36

l Type in the following command to connect to the database, where <password> is

your MySQL password (by default it is admin):

mysql --user=root --password=<password> objectiflune

l You should see the prompt become mysql>. Here, type the command to allow the

"root" user to be accessed from a specific IP subnet range. For example, to accept communication on 192.168.*.*, use: GRANT ALL PRIVILEGES ON

objectiflune TO 'root'@'192.168.0.0/255.255.0.0' IDENTIFIED BY 'password' , where password is the one provided during installation. (ref:

http://dev.mysql.com/doc/mysql-security-excerpt/5.5/en/adding-users.html)

IP Subnets understanding is beyond the scope of this documentation. If you want to learn more, please see the Subnetwork article on Wikipedia.

Clustering Preferences and Setup

When server extensions are installed and connected to a Master, the following options and settings change in availability or behavior:

l In the Scheduling Preferences of the Slave, both "Maximum Records" are ignored.

Scheduling is handled by the Master.

l The "Expected Remote Merge Engine" and "Expected Remote Weaver Engine" in Merge

Engine Scheduling and Weaver Engine Scheduling respectively, on the Master, should

each equal the total number of engines in all the slaves combined.

For example, the Expected Remote Merge Engine on the Master should equal the total of "Local Engines Launched" for each slave.

If the number of expected remote engines is lower than the actual number, performance will not be optimal.

If the number of expected remote engines is higher than the actual number, jobs may fail and not complete.

l Cleanup Service requires special configuration on Clustering setups:

l Cleanup service should not run simultaneously on all machines (staggered

cleanup). Doing so may cause jobs not to be processed since all servers are busy.

l Only the machine where the MySQL Server product is installed should attempt to

cleanup database items. Essentially server that do not have MySQL should only run Orphan File Cleanup.

Server Extension Scheduling Preferences

The Server Extension Scheduling Preferences define the connection settings for the server extension (slave) and the main Server module (master).

Page 36

Page 37

Location of the master server: Enter the location and port of the main Server module in the hostname:port format. For example, 192.168.100.123:9340 or connect-master:9340.

Username: Enter the username expected by the OLConnect Server.

Password: Enter the password expected by the OLConnect Server for the above username.

Note that Maximum records in a small job and Minimum records in a large job:are note used in Server Extensions. All server scheduling is handled by the Master.

Page 37

Page 38

DataMapper Module

The DataMapper Module is a tool that helps in the preparation of data for a unified data model. You can then use that Data Model in the Designer module.

The tool does this through the use of a data mapping workflow consisting of multiple steps which extract data from each Source Record of a Data Source and places this data in a Data Model. This Data Model contains all the necessary information for the creation of a template in the Designer module. (see Data Model for more information)

Basics

Here is the procedure for a Data Mapping configuration that includes the steps required for a data extraction from a data source:

Create a new Data Mapping configuration. First, you create a new Data Mapping configuration manually from a file or by automatically using a wizard. In this first step, you select a Data Source. See Creating a

new Data Mapping configuration.

Configure settings for the data source. In this step, you configure how the Data Sample is read by the DataMapper so it can delimit each record in the file (using Delimiters). See Data Source.

Configure the data extraction workflow. Here you configure the workflow steps that will be required to extract the data from the Data source to the Data Model. This way, data will be converted and prepared to be used by the Designer module. To learn more, see Data Extraction.

Save the Data Mapping configuration. Now it's time to save a copy of a data mapping configuration under the name of your choice. To learn more, see Saving A Data Mapping configuration.

Features

The DataMapper Module is a tool that extract data and prepares it for use in the Designer module. The tool does this through the use of a Data Mapping Workflow consisting of multiple Steps which process and extract data from each Source Record of a Data Source and stores it in a Record Set.

Page 38

Page 39

Data Mapping Configuration

A Data Mapping Configuration file can refer to either the current active configuration in the DataMapper, or a file on disk containing the information necessary for data mapping. It contains the extraction workflow (steps), Delimiter and Boundary Settings, and any imported Data Samples.

Data Mapping Workflow

The data mapping workflow is a series of Steps inside of a data mapping configuration that extract the appropriate data from the Source Record and places it into the Record (see Data

Model).

The data mapping workflow always starts with the Preprocessor step and ends with the Postprocessor step and can contain as many of the different steps available in the DataMapper.

Data Model

A Data Model is the format into which Records are saved.It is also a file format that can be exchanged between different parts of the PReS Connect solution.

Data Source (Settings)

A data source is simply the source of the data. It can be a file (CSV, PDF, TXT, XML) or a particular database. The data might be located on the same computer as the program, or on another computer somewhere on a network.

The first step to do before creating a Data Mapping configuration is to set up Input Data (setting the delimiters) and Boundaries (setting the trigger) in the Settings pane.

Data Mapping Configuration

Creating A New Data Mapping Configuration

You can create a new Data Mapping configuration from a data file by using a wizard or manually.

Page 39

Page 40

From a File

You can create a new data mapping configuration manually under the From a file section. As opposed to using a wizard, you must configure all settings in the Settings pane of the DataMapper interface. Please refer to Configuring Settings For The Data Source for more

information.

A CSV File

To create a Data Mapping from a CSV file, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the From a file section, select CSV.

Click the Browse button and open the CSV file you want to work with.

Click Finish.

From the File menu

Click the File menu and select New.

Click the Data mapping Configuration drop-down and select Files and then CSV File.

Click Next.

Click the Browse button and open the CSV file you want to work with.

Click Finish.

A MS-Access File

To create a Data Mapping from a Microsoft Access database file, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the From a file section, select MS Access.

Click the Browse button and open the database file you want to work with.

Enter the password if needed and click Next.

Page 40

Page 41

From the File menu

Note

PCL and PostScript (PS) files are automatically converted to PDF files before showing that PDF in the Data Viewer. This happens once when opening the file, but in automation happens for every file. Depending on the processing power available, this may influence the processing speed.

Click the File menu and select New.

Click the Data mapping Configuration drop-down and select Files and then Microsoft Access.

Click Next.

Click the Browse button and open the database file you want to work with.

Enter the password if needed and click Next.

A PDF File

To create a PDF/VT file data mapping configuration, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the From a file section, select PDF/VT.

Click the Browse button and open the PDF/VT file you want to work with.

Click Finish to close the dialog and open the actual Data Mapping configuration).

From the File menu

Click the File menu and select New.

Click the Data mapping Configuration drop-down and select Files and then PDF/PS/PCL/AFP File.

Click Next.

Click the Browse button and open the PDF/VT file you want to work with.

Click Finish to close the dialog and open the actual Data Mapping configuration).

A Text File

To create a TXT file data mapping configuration, use the following steps:

Page 41

Page 42

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the From a file section, select Text.

Click the Browse button and open the text file you want to work with.

Click Finish to close the dialog and open the actual Data Mapping configuration).

From the File menu

Click the File menu and select New

Click the Data mapping Configuration drop-down and select Files and then Text File.

Click Next.

Click the Browse button and open the text file you want to work with.

Click Finish to close the dialog and open the actual Data Mapping configuration).

A XML File

To create a XML File data mapping configuration, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the From a file section, select XML.

Click the Browse button and open the XML file you want to work with.

Click Finish to close the dialog and open the Data Mapping configuration.

From the File menu

Click the File menu and select New.

Click the Data mapping Configuration drop-down and select Files and then XML File.

Click Next.

Click the Browse button and open the XML file you want to work with.

Click Finish to close the dialog and open the Data Mapping configuration.

Page 42

Page 43

Using a Wizard

Note

These settings are generally detected automatically.

The Data Mapping Wizard simplifies extracting records. When using a Data Mapping Wizard, all the fields are automatically extracted inside the record. The Data Mapping Wizard also preconfigure the settings and boundaries of the data source using common values.

For A CSV File

To create a Data Mapping from a CSV file using the wizard, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the Using a wizard section, select CSV.

Click the Browse button and open the CSV file you want to work with.

Take a look at the Preview box content to ensure that the file is the right one and the encoding correctly reads the data.

Click Next.

From the Select a CSV Configuration dialog, choose the proper settings:

Encoding: Choose the correct encoding to read the file.

Separator: Defines what character separates each fields in the file.

Comment Delimiter: Defines what character starts a comment line.

Text Delimiter: Defines what character surrounds text fields in the file, preventing the Field Delimiter from being interpreted within those text delimiters.

Ignore unparseable lines: Ignores any line that does not correspond to the settings above.

First row contains field names: Uses the first line of the CSV as headers, which automatically names all extracted fields.

Verify that the data is read properly and click Finish.

Page 43

Page 44

From the File menu

Note

These settings are generally detected automatically.

Click the File menu and select New.Click the Data mapping Data mapping Wizards drop-down and select From CSV File.

Click Next.

Click the Browse button and open the CSV file you want to work with.

Take a look at the Preview box content to ensure that the file is the right one and the encoding correctly reads the data.

Click Next.

From the Select a CSV Configuration dialog, choose the proper settings:

Encoding: Choose the correct encoding to read the file.

Separator: Defines what character separates each fields in the file.

Comment Delimiter: Defines what character starts a comment line.

Text Delimiter: Defines what character surrounds text fields in the file, preventing the Field Delimiter from being interpreted within those text delimiters.

Ignore unparseable lines: Ignores any line that does not correspond to the settings above.

First row contains field names: Uses the first line of the CSV as headers, which automatically names all extracted fields.

Verify that the data is read properly and click Finish.

For a Database File

To create a Data Mapping from a Database file using the wizard, use the following steps:

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the Using a wizard section, select Database.

Page 44

Page 45

4. Use the drop-down to select the Database type.

Click Next.

From the File menu

Click the File menu and select New.Click the Data mapping Data mapping Wizards drop-down and select From databases.

Click Next.

3. Use the drop-down to select the Database type.

Click Next.

Now set the following properties according to the selected database:

MySQL

Server: Enter the server address for the MySQL database.

Port: Enter the port to communicate with the MySQL server. The default port is 3306.

Database name: Enter the exact name of the database from where the data should be extracted.

User name: Enter a user name that has access to the MySQL server and specified database. The user only requires Readaccess to the database.

Password: Enter the password that matches the user name above.

Table name: The selected database is a set of related tables composed of rows and columns corresponding respectively to source records and fields. Select a table from which you want to extract data.

Encoding: Choose the correct encoding to read the file.

Click Finish to close the dialog and open the actual Data Mapping configuration.

Microsoft Access

Click the Browse button and open the database file you want to work with.

Password: Enter a password if one is required.

Click Next.

Table name: The selected database is a set of related tables composed of rows and columns corresponding respectively to source records and fields. Select a table from which you want to extract data.

Encoding: Choose the correct encoding to read the file.

Click Finish to close the dialog and open the actual Data Mapping configuration.

SQL Server

Page 45

Page 46

Note

Since JDBC can connect to multiple types of databases, a specific database driver and path to

Server: Enter the server address for the SQL Server database.

Port: Enter the port to communicate with the SQL Server server. The default port is 3306.

Database name: Enter the exact name of the database from where the data should be extracted.

User name: Enter a user name that has access to the SQL Server server and specified database. The user only requires Readaccess to the database.

Password: Enter the password that matches the user name above.

Table name: The selected database is a set of related tables composed of rows and columns corresponding respectively to source records and fields. Select a table from which you want to extract data.

Encoding: Choose the correct encoding to read the file.

Click Finish to close the dialog and open the actual Data Mapping configuration.

ODBC DataSource

ODBC Source: Use the drop-down to select an ODBC System Data Source. This must be a data source that has been configured in the 64-bit ODBC Data Source Administrator, as PReS Connect is a 64-bit application and thus cannot access 32-bit data sources.

This ODBC source is MSSQL: Check this option if the ODBC source is MSSQL (SQL

JDBC

Server). The options below appear under MSSQL-ODBCadvanced configuration:

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:

User name: Enter the SQL Server user name.

Password: Enter the password for the above user name.

Click Next.

Click Finish to close the dialog and open the actual Data Mapping configuration.

Page 46

Page 47

this driver's JAR file must be specified.

Oracle

JDBC Driver: Use the drop-down to select which JDBC Driver to use for the database connection. JAR file path: Enter a path to the JAR file that contains the appropriate driver for the database below.

Server: Enter the server address for the database server. Database name: Enter the exact name of the database from where the data should be

extracted. User name: Enter a user name that has access to the server and specified database. The

user only requires Readaccess to the database.

Password: Enter the password that matches the user name above. Advanced mode: Check to enable the Connection String field to manually enter the

database connection string. Connection string: Type or copy in your connection string. Click Next Click Finish to close the dialog and open the actual Data Mapping configuration.

Server: Enter the server address for the Oracle database.

Port: Enter the port to communicate with the Oracle server. The default port is 3306.

Database name: Enter the exact name of the database from where the data should be extracted.

User name: Enter a user name that has access to the Oracle server and specified database. The user only requires Readaccess to the database.

Password: Enter the password that matches the user name above.

Table name: The selected database is a set of related tables composed of rows and columns corresponding respectively to source records and fields. Select a table from which you want to extract data.

Encoding: Choose the correct encoding to read the file.

Click Finish to close the dialog and open the actual Data Mapping configuration.

For a PDF File

To create a PDF/VT file data mapping configuration using the wizard, use the following steps:

Page 47

Page 48

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the Using a wizard section, select PDF/VT.

Click the Browse button and open the PDF/VT file you want to work with. Click Next.

In the Metadata page, select the following options:

Metadata record levels: Use the drop-down to select what level in the metadata defines a Source Record.

Field List: This list displays all fields in all levels of the PDF/VT metadata.

Checkmark: Check any field to add it to the extraction.

Record Level: Displays the level on which the field is located.

Property name: Displays the field names to extract.

Click Finish to close the dialog and open the actual Data Mapping configuration).

From the File menu

Click the File menu and select New.

Click the Data mapping Data mapping Wizards drop-down and select From PDF/VT or AFP.

Click Next.

Click the Browse button and open the PDF/VT file you want to work with. Click Next.

In the Metadata page, select the following options:

Metadata record levels: Use the drop-down to select what level in the metadata defines a Source Record.

Field List: This list displays all fields in all levels of the PDF/VT metadata.

Checkmark: Check any field to add it to the extraction.

Record Level: Displays the level on which the field is located.

Property name: Displays the field names to extract.

Click Finish to close the dialog and open the actual Data Mapping configuration).

From a XMLFile

To create a XML file data mapping configuration, use the following steps:

Page 48

Page 49

From the Welcome screen

Open the PReS Connect Welcome page by clicking the icon at the top right or select the Help menu and then Welcome.

Click Create a New Configuration.

From the Using a wizard section, select XML.

Click the Browse button and open the XML file you want to work with. Click Next.

In the Select split level and trigger type page, select the following options:

XML Elements: A list of node elements that have children nodes. Select the level in the data that will define the Source Record (for example Invoice, Customer ID, Item...etc as opposed to Last name, Due date...etc).

Trigger: According to the node element path selected in the XML Elements field, select On element to create a record in the Data mapping for each occurrence of the element. Or you can select On change to create a record each time the element is different.

Click Finish to close the dialog and open the Data Mapping configuration.

From the File menu

Click the File menu and select New.Click the Data mapping Data mapping Wizards drop-down and select From XML File.

Click Next.

Click the Browse button and open the XML file you want to work with. Click Next.

In the Select split level and trigger type page, select the following options:

Click Finish to close the dialog and open the Data Mapping configuration.

To Generate Counter

The Generate Counter wizard creates a record set where each record contains a "counter" field contains the current counter value for each record, starting and stopping at set values and

Page 49

Page 50

incremented by a set value also. It is useful for numbered tickets or any other template requiring sequential numbers.

Starting Value: The starting number for the counter. Defaults to 1.

Increment Value: The value by which to increment the counter for each record. For example, an increment value of 3 and starting value of 1 would give the counter values of 1, 4, 7, 10, [...]

Number of records: The total number of counter records to generate. This is not the end value but rather the total number of actual records to generate.

Padding character: Which character to add if the counter's value is smaller than the width.

Width: The number of digits the counter will have. If the width is larger than the current counter value, the padding character will be used on the left of the counter value, until the width is equal to the set value. For example for a counter value of "15", a width of "4" and padding character of "0", the value will become "0015".

Prefix: String to add before the counter, for example, adding # to get #00001. The prefix length is not counted in the width.

Suffix: String to add after the counter. The suffix length is not counted in the width.

Opening a Data Mapping Configuration

There are two ways you can open a data mapping configuration:

In the Menus, click on File, Open, ensure that the file type is either DataMapper files or Connect files. Browse to the configuration file to open, select it and click Open.

In the Menus, click onFile, Open Recent, and select one of the recently opened configuration files.

Saving a Data Mapping Configuration

To save a data mapping configuration:

In the Menus, click on File, then Save, or click the Save button in theToolbars.

2. If the data mapping configuration has never been saved, browse to the location where the data mapping configuration should be saved and type a name, then click Save.

To save a copy of a data mapping configuration under a different name:

Page 50

Page 51

In the Menus, click on File, then Save As.

2. Browse to the location where the data mapping configuration should be saved and type a name, then click Save.

Data Mapping Workflow

A data mapping workflow is a series of steps used to process and extract the appropriate data from the Source Record and store it into the Record (see Data Model). With the data model, it is what makes a data mapping configuration (See Data Mapping Configuration).

A data mapping workflow always starts with the Preprocessor step and ends with the Postprocessor step. It can contain as many steps as needed for extracting the required data.

When working with a data mapping workflow, you need to consider the following:

Promotional versus transactional data: Depending on the type of data, whether it is promotional or transactional, you will use a different extraction workflow. See About

Promotional and Transactional Data for more information.

Steps: To extract data from the data sample, you use different steps that make up the extraction process. See Steps for more information.

About Promotional and Transactional Data

Promotional Data is traditionally defined as the unique fields found in each record. For instance, a postal address, a date, or customer number could all be elements of promotional data found in each record.

Transactional data is usually defined as promotional data plus a varying number of fields that represent the elements of a transaction. While the structure is identical for each record, the number of repeated elements varies from one record to the next. For instance, lines of items on an invoice or monthly usage of electricity would be part of the transactional data.

Data Extraction

The following example explains in details how to perform a data extraction for each different data source file types and the Steps that you can use to reach that goal. Delimiters and Boundaries must be properly configured beforehand (see Configuring Settings for more information).

Page 51

Page 52

The Preprocessor and the Postprocessor

Data processors allow the application to perform actions on the data file itself before it is handed over to the Data Mapping workflow (preprocessors) and after the Data Mapping workflow has completed (postprocessors).

To configure settings for the Preprocessor step, see Preprocessor Step Properties.

To configure settings for the Postprocessor step, see Postprocessor Step Properties.

The Extraction

The Extract step is the heart of the DataMapper software. It takes information from the Data Sample and places it in the Extracted Record within the Record Set.

To configure settings for the Extract step, see Extract Step Properties.

For more information about Promotional and Transactional data, please refer to About

Promotional and Transactional Data.

From a CSV file or a Database

Extracting Promotional Data

1. From the Viewer pane, select the fields that contain the customer and invoice information.

For more information about how to select data in a CSVfile, please refer to Data

Selection/From a CSV File.

2. Drag & drop the selected fields into the Data Model pane.

Page 52

Page 53

Note

Alternatively, you can simply right click on the selected fields and select Add Extraction.

Extracting Transactional Data

The Transactional Data (line items information) appears on multiple lines. You must create a loop on these lines to extract the items information. The line items are extracted in a detail table.

1. Select the fields that contain the first line item information.

Right click on this data selection and select Add Repeat .

Right click again on this data selection and select Add Extraction. A new extraction step will be placed between the Repeat and theGoto steps.

Page 53

Page 54

Note

You can also use the toolbar buttons instead of contextual menus, See Toolbars for more details.

From a XML file

Extracting Promotional Data

The Promotional Data (customer and the invoice information) is repeated for each item normally located at the top of the Source Record, before the ITEM information. It generally includes the name, the address, reference numbers, invoice information...etc.

Page 54

Page 55

1. Select the children leaf nodes of the CUSTOMER() node.

Note

Alternatively, you can simply drag & drop the selected fields into the Data Model pane.

Right click on the selected nodes and select Add Extraction.

Page 55

Page 56

3. Select the children leaf nodes of the INVOICE() node.

Right click on the selected nodes and select Add Extraction.

Extracting Transactional Data

The Transactional Data (line items information) appears on multiple lines. In the example below, this information appears under the parent node ITEM(). Each ITEM() node give information about one item. Create a loop on the ITEM() nodes to extract the items information.

1. Select the ITEM() node.

Right click on the selected node and select Add Repeat.

Page 56

Page 57

Note

By default, the For Each option is selected in the Repeat type option as shown in theStep Properties pane. It means that the loop will include each ITEM() node. In the

Collection field, you will find the corresponding ITEM() node path.

3. Select the children leaf nodes of the ITEM() node.

Page 57

Page 58

Note

You can also use the toolbar buttons instead of contextual menus, See Toolbars for more

details.

Note

Alternatively, you can simply drag & drop the selected fields into the Data Model pane.

Right click on the selected nodes and select Add Extraction.

From a Text or a PDF file

Extracting Promotional Data

The Promotional Data (customer and the invoice information) is repeated for each item and normally located at the top of the Source Record. It generally includes the name, the address, reference numbers, invoice information...etc.

1. From the Viewer pane, select the customer and invoice information. Note that you can select multiple lines.

Right click on the selection data and select Add Extraction .

Page 58

Page 59

Extracting Transactional Data

The Transactional Data (line items information) appears on multiple lines and pages. A loop has to be created on these lines to extract the items information. The line items are extracted in a detail table as below:

1. Select a simple data in the first line item. For example the product number.

Right click on the selection and select Add Goto. That moves the cursor at the beginning of the first line item.

3. Add a loop to extract each item until the end of the line items. To stop the loop at the right place, you can use a text located at the end each record. For example, it can be a text string like SUBTOTALS, TOTAL, AMOUNT, ...etc. Now you can use that text as a condition to stop the loop at the end of the line items list. In that case:

Page 59

Page 60

1. Select the text (SUBTOTALSfor example) in the Viewer.

Right click on the selection and select Add Repeat.

The Repeat step loops on all lines until the selected text is found. Since a record can extend on more than one page, lines that are not item lines must be excluded form the extraction. You can use any exclusive information like a "." or "," in prices or totals for example.

4. Select the "." or the "," in the total or in the price of the first line item.

Right click on the selected dot and select Add Conditional. In the Viewer pane, you will see a green check mark besides each included line or X for other lines.

6. From the Viewer pane, select the first field on the left for the first line item.

Page 60

Page 61

Note

The Add Extract Field step allows to add a field to an existing extract step while the Add

Right click on the selection and select Add Extraction.

8. Select the second field.

Right click on the selection and select Add Extract Field.

10. Do the same for the rest of the fields along that same line item.

Page 61

Page 62

Extract Step creates a new step in the Steps pane. For optimization purposes, it is better to

use Add Extract Field than to have a succession of Add Extract steps.

Note

You can also use the toolbar buttons instead of contextual menus, See Toolbars for more details.

Totals Information

After the loop step, the cursor position is at the end of line items. If the record contains sums or totals at the end of the line items list:

1. Select the amounts.

Click the Repeat step in the Steps panel.

Right click on the selection and select Add a Step/Add Extraction.

Page 62

Page 63

Also Note That...

Note

If no Extract step is currently selected in the Steps pane, a new Extraction step is created. If an Extract step is selected, new Extract Fields will be added to this existing step.

l Dragging a data selection or fields into a specific level of the Data Model (record or

detail tables) will add the fields to that level.

When dragging data into a detail table, the Extract step must be located within the appropriate Repeat step, otherwise the extract will not function properly.

l If a Data Model is loaded into the Data Model pane and if a field of the same name

already exists in that level, dragging a named field into it (CSV, XML, Database) will

extract the data to that field. Otherwise a new one with will be created.

l Dragging a single field onto a Data Model field will extract it to that field regardless

of its name.

Action steps could be added to the process described above in order to set the value for a Source Record property or execute a JavaScript code. For more information about the Action step, see The Action Step.

Note

To add an Extract step, you can also use JavaScript (select JavaScript from the Mode drop-down in the Step Properties pane). Please refer toJavaScript _in_DataMapper.htmfor more

information.

Data Selection

The following topics contain information about how to create and manipulate a data selection, and also how to create steps from it.

Selecting Data

From a Text File

The Text data viewer displays the text-based contents of the Data Sample that is currently active within the data mapping configuration in a grid-like fashion, with each character in the file being in a separate grid position.

Page 63

Page 64

To select data, click on a starting character within the grid, keeping the mouse button down, dragging to the end character and releasing the button. This creates a data selection that can contain multiple lines.

From a PDF File

The PDF data viewer displays the PDF file contents of the Data Sample that is currently active within the data mapping configuration as pages.

To select data, click on a starting point, keeping the mouse button down, dragging to the end location and releasing the button. This creates a data selection that can contain multiple lines.

Page 64

Page 65

From a CSV or a Database File

The CSV/Database data viewer displays the field-based contents of the Data Sample that is currently active within the data mapping configuration in a grid-like fashion, with each field being in a separate grid position.

To select data, click on a starting point, keeping the mouse button down, dragging to the end location and releasing the button. This creates a data selection that can contain multiple lines.

Page 65

Page 66

From a XML File

The XML data viewer displays the XML-based contents of the Data Sample that is currently active within the data mapping configuration in a tree view, with XML fields displayed at each level of the Sample Record.

To select data, click on a starting point, keeping the mouse button down, dragging to the end location and releasing the button. This creates a data selection that can contain multiple lines.

Page 66

Page 67

Adding an Extraction Step from a Data Selection

To add a new step from the Data Viewer:

1. Create your data selection (refer to Creating a Data Selection for more information).

2. Right-clicking on the data selection and select the appropriate step.

See Type of Steps for more information on available steps.

Manipulating a Data Selection

From a Text File

Page 67

Page 68

Once created, data selections can be modified and moved in order to change or extend the data included in the selection. You can also modify a data selection that is attached to a field extraction in an Extract step by double-clicking on the data selection in the Data Viewer and then modifying the data selection.

Moving a Data Selection

To move a data selection, click and hold anywhere on the data selection, move it to its new desired location and release the mouses.

Resizing a Data Selection

To resize a data selection, click and hold on one of the resize handles on the borders or corners, move them to the new size and release the mouse.

Page 68

Page 69

From a PDF File

The PDF data viewer displays the PDF file contents of the Data Sample that is currently active within the data mapping configuration as pages.

Once created, data selections can be modified and moved in order to change or extend the data included in the extraction. Moving a new data selection can be done directly if the data selection is new. Data selections that are attached to a field extraction in an Extract step can also be modified by double-clicking on the data selection in the Data Viewer and then modifying the data selection.

Moving a Data Selection

To move a data selection, click and hold anywhere on the data selection, move it to its new desired location and release the mouse.

Page 69

Page 70

Resizing a Data Selection

To resize a data selection, click and hold on one of the resize handles on the borders or corners, move them to the new size and release the mouse.

Page 70

Page 71

From a CSV or a Database File

Once created, data selections can be modified. Modifying a new data selection can be done directly if the data selection is new.

Modifying a Data Selection

To modify a data selection, press and hold the CTRLkey click, and click on a field to add it or remove it from the selection (the blue color indicates that the field is part of the current selection).

From a XML File

Once created, data selections can be modified. Modifying a new data selection can be done directly if the data selection is new.

Page 71

Page 72

Modifying a Data Selection

Note

For more details about operations that can be performed on steps, please refer to The

Steps Pane Interface.

Steps

Steps are executed sequentially, from top to bottom. Inside conditions, some steps may be skipped altogether when they are on a particular branch, whereas in loops several steps may be repeated a number of times. The Preprocessor and Postprocessor steps are special in that the former can be used to modify the incoming data prior to executing the rest of the workflow while the latter can be used to further process the Data Set after the entire workflow has been executed.

You will find below a list of different steps that can be added to a Data Mapping Workflow.

Page 72

Page 73

Preprocessor and Postprocessor

Preprocessors

Data preprocessors allow the application to perform actions on the data file itself before it is handed over to the Data Mapping workflow

Some preprocessors might for instance, using a JavaScript expression, convert all characters of a text file from lowercase to uppercase prior to running Data Mapping workflow :

Any number of preprocessing tasks can be added to a workflow and run in sequence before the data is sent to the Data Mapping workflow. Click the button to add a Preprocessor to the list.

Page 73

Page 74

Postprocessors

Data postprocessors allow the application to extract data that was stored in the data model once the workflow is complete. For example, the post processor can export all data or only addresses, to a CSV file which can then be given directly to a postal addresses verification application.

Some postprocessors might for instance, using a JavaScript expression, create a CSV file from the Record set:

Page 74

Page 75

Any number of postprocessing tasks can be added to a workflow and be executed after the Data Mapping workflow is complete. Click the button to add a Postprocessor to the list.

Page 75

Page 76

Extract

Note

To add an Extract step, you can also use JavaScript (select JavaScript from the Mode drop-down in the Step Properties pane). Please refer toJavaScript _in_DataMapper.htmfor more

information.

The Extract step is the heart of the DataMapper software. It takes information from the Data Sample and places it in the Extracted Record within the Record Set.

Please refer to Data Extraction for an animated example.

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Page 76

Page 77

Goto

The cursor position determines how data is extracted from the Source Record. The cursor in a Source Record is always at a specific position.

In a Source Record, the cursor position starts off at the top-left corner of the Sample Data. When the Goto step is used, that cursor position is moved to the location (either relative or absolute) set by the Goto step. In the case of a Goto step within a Repeat step, the cursor position will gradually be moved with each loop of the repeat step, for example when extracting transactional data.

Since data extracted by the Extract step is always relative to the current cursor position, this becomes useful when extracting data at the end of the loop. For instance, when a "Totals" line appears at the end of line items in an invoice, the Extract step can find the appropriate position of the "Totals" simply by looking at a certain distance (or offset) from the last line item and always find the "Totals" at the same place.

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Condition

A Condition step splits the extraction workflow into two separate branches, one that is executed when the condition is True, the other when it is False. In the Viewer on the left side of the window, an icon is displayed indicating the result of the evaluation: when true and when false.

Page 77

Page 78

A Condition step is used when the data extraction must be made based on specific criteria. In the example shown in the following figure, the transactional data must be extracted according to two main criteria. First, the line item must include an amount of money and secondly, the lines that include a Description field on two lines have to be extracted as a single record.

Page 78

Page 79

Since the extraction is for transactional data, a Repeat step is first added.

2. A first condition is added to determine whether the line should be considered for the extraction.

Page 79

Page 80

3. The extraction is performed if the condition is true.

4. Under the true branch of the first condition, a second condition is added for Description fields on two lines.

Page 80

Page 81

5. The extraction performed under the true branch of the second condition.

6. The extraction performed under the false branch of the second condition.

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Page 81

Page 82

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Repeat

The Repeat step is a loop that may run 0 or more times, depending on the condition specified. It is generally used for the extraction of transactional data. A Repeat steps do not automatically move the pointer in the file. In order to avoid infinite loops, a Goto step must be present within the loop itself.

The following picture shows a usage example of a Repeat step. As you can see, the Repeat step is a loop that includes both Goto and Extract steps. The extraction result for transactional data is placed in a Detail table.

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Page 82

Page 83

Note

By default, if an Extract step is added within a Repeat step, its extraction is made in a detail

table.

Note

If an XML node that has children is selected, and the pointer is currently at this node, creating a repeat step will loop on that node.

Extract Field

The Add Extract Field function adds the selected data to a selected Extract step in the Steps pane. If multiple lines, nodes or fields are selected, multiple extract fields are added simultaneously (see also About Records and Fields for more information).

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Action

The Action step can set the value for a Source Record property or execute a JavaScript code. The Action Step can run multiple specific actions one after the other in order.

The following picture shows a usage example of an Action step...

Page 83

Page 84

For more information on how to add a step, please refer to Toolbar, Menus or Shortcut Keys under the Interface section.

Properties

You can also further customize the step properties. Please refer to The Step Properties

Interface for more information.

Data Model

A Data Model is the format into which Records are saved.It is also a file format that can be exchanged between different parts of the PReS Connect solution.

Data Model Principle

The idea behind the Data Model is that the structure of a Record can be separated from the actual data. It can be shared between multiple templates, data mapping configurations, job presets and output presets. These files are deemed compatible if their data model is identical

or if one data model is an exact subset of another.

Data Models can be used directly in the Designer module, even if no data is attached to it, to create the template.

Page 84

Page 85

They can be imported to, and exported from, the Data Model Pane in the Designer and DataMapper Modules.

For more information about the operations you can perform on the Data Model, please refer to

The Data Model Interface.

About Records and Fields

A Record is a collection of fields and contains all the data about one particular person, company, or item in a database that is required for creating a single document for a single recipient (see Record for more information).

A Field is part of a record and contains a single piece of data for the subject of the record. If the record is an employee, a field would be Firstname, Lastname, or City or State.

Data Model File Structure

The Data Model file is a XML file that contains the structure of the data model, including each field's name, data type, and any number of detail tables and nested tables.

Example for promotional data, including a simple name and address:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <datamodel schemaVersion="1.0.0.3" name="Generic Address Block" version="1" xmlns="http://www.objectiflune.com/connectschemas/DataModelConfig" 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.org/2001/XMLSchema-instance"> <field type="string" name="Name" required="true"/> <field type="string" name="Organization" required="true"/> <field type="string" name="Address1" required="true"/> <field type="string" name="Address2" required="true"/> <field type="string" name="Address3" required="true"/> <field type="string" name="City" required="true"/> <field type="string" name="StateOrProvince" required="true"/> <field type="string" name="Country" required="true"/> <field type="string" name="ZipOrPostalCode" required="true"/> <field type="string" name="Extra1" required="true"/> <field type="string" name="Extra2" required="true"/> </datamodel>

Page 85

Page 86

Example with transactional details, a simple invoice format

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <datamodel schemaVersion="1.0.0.3" name="Transactional Invoice" version="1" xmlns="http://www.objectiflune.com/connectschemas/DataModelConfig" 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.org/2001/XMLSchema-instance"> <field type="string" name="ID" required="true"/> <field type="string" name="Gender" required="true"/> <field type="string" name="LastName" required="true"/> <field type="string" name="FirstName" required="true"/> <field type="string" name="Address1" required="true"/> <field type="string" name="Address2" required="true"/> <field type="string" name="City" required="true"/> <field type="string" name="State" required="true"/> <field type="string" name="Country" required="true"/> <field type="string" name="ZipCode" required="true"/> <field type="string" name="Title" required="true"/> <field type="string" name="Company" required="true"/> <field type="string" name="Phone2" required="true"/> <field type="string" name="Email" required="true"/> <field type="string" name="Language" required="true"/> <field type="string" name="Number" required="true"/> <field type="datetime" name="Date" required="true"/> <field type="datetime" name="DueDate" required="true"/> <field type="string" name="Rep" required="true"/> <field type="currency" name="SubTotal" required="true"/> <field type="currency" name="TaxTotal" required="true"/> <field type="currency" name="Total" required="true"/> <table name="detail"> <field type="string" name="Number2" required="true"/> <field type="string" name="Description" required="true"/> <field type="currency" name="UnitPrice" required="true"/> <field type="integer" name="Ordered" required="true"/> <field type="integer" name="Shipped" required="true"/> <field type="integer" name="BackOrder" required="true"/> <field type="currency" name="Total2" required="true"/> </table> </datamodel>

Page 86

Page 87

Example of Nested Tables (one table into another)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<datamodel schemaVersion="1.0.0.3" name="Nested Table Example" version="1" xmlns="http://www.objectiflune.com/connectschemas/DataModelConfig" 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.org/2001/XMLSchema-instance"> <field type="string" name="RecordField" required="true"/> <table name="details"> <field type="string" name="DetailsTableField" required="true"/> <table name="nestedtable"> <field type="string" name="NestedTableField" required="true"/> </table> </table> </datamodel>

Example of Default Values that can be added to any field with the defaultValue attribute:

Data Source (Settings)

The first step to do before creating a Data Mapping configuration is to set up Input Data (setting the delimiters) and Boundaries (setting the trigger) in the Settings pane.

Input Data (Delimiters)

Delimiters defines the separation within the source file. For example, in a CSV file the delimiters are between each row whereas in a PDF file, delimiters separate pages.

Please refer to The Settings Pane Interface for more information about each fields and buttons.

Page 87

Page 88

Boundaries

Boundaries are the division between source records. They can be set using different types of rules such as text, pages or even custom JavaScript rules.

Boundaries differ from Delimiters. When defining boundaries , multiple delimiters can be included between boundaries - many pages per invoice, many CSV row per transaction, etc.

To set a boundary, a specific trigger must be found. The trigger is something that is either static ("Page 1 of" on text or PDF files) or something that changes on each source record (a customer ID at a specific location, a username, etc).

Please refer to The Settings Pane Interface for more information about each fields and buttons.

Data Samples

The Data Samples are the data sources that have been imported into the data mapping configuration.

Please refer to The Settings Pane Interface for more information about each fields and buttons.

External JS Libraries

You can use the External JS libraries to add more JavaScript functionality to your data mapping configuration. Any functions included in the JS library will be available in Preprocessor scripts, as well as Action tasks, Post Functions and JavaScript -based extraction steps.

For example let's take the following JavaScript file, for example:

function myAddFunction(p1, p2) { return p1 + p2; };

If this is saved as myFunction.js and imported, then the following would work anywhere in the configuration:

var result = myAddFunction(25, 12); // returns 37!

The External JS Libraries box displays all the libraries that have been imported into the data mapping configuration.

Please refer to The Settings Pane Interface for more information about each fields and buttons.

Page 88

Page 89

DataMapper User Interface

Interface Sections and Panels

A. Menus

B. Toolbars C. Steps Pane D. Step Properties Pane

Page 89

Page 90

E. Data Model Pane

F. Data Viewer G. Messages Pane H. Settings Pane

Menus

The following menu items are shown in the DataMapper Module's menu:

File Menu

New... : Opens the Creating a New Data Mapping Configuration dialog.

Open: Opens a standard File Open dialog. This dialog can be used to open Templates and data mapping configurations.

Open Recent: List the most recently opened Templates and configurations. Clicking on a template will open it in the Designer module, clicking on a data mapping configuration will open it in the DataMapper module.

Close: Close the currently open data mapping configuration or Template. If the file needs to be saved, the appropriate Save dialog will open.

Close All: Close any open data mapping configuration or Template. If any of the files need to be saved, the Save Resources dialog opens.

Save: Saves the current data mapping configuration or Template to its current location on disk. If the file is a data mapping configuration and has never been saved, the Save As dialog appears instead.

Save As...: Saves the current data mapping configuration or Template to a new location on disk. In the case of Templates, it is saved to a location that can be different than the local repository.

Save All: Saves all open files. If any of the open files have never been saved, the Save As dialog opens for each new unsaved file.

Revert: Appears only in the Designer module. Reverts all changes to the state in which the file was opened or created.

Add Data: Adds data either to the current data mapping configuration or to the open template. In data mapping configuration

From File...: Opens the dialog to add a new data file to the currently loaded data mapping configuration. Not available if the currently loaded data mapping configuration connects to a database source.

From Database...: Opens the Edit Database Configuration dialog. Not available if the currently loaded data mapping configuration is file-based.

Page 90

Page 91

Send to Workflow: Opens theSend to Workflow dialog to send files to a local PReS Workflow software installation.

Exit:Closes the software. If any of the files need to be saved, the Save Resources dialog opens.

Edit Menu

Undo: Undoes the previous action.

Redo: Redoes the last action that was undone.

Cut Step: Removes the currently selected step and places it in the clipboard. If the step is a Repeat or a Condition, all steps under it are also placed in the clipboard. If there is already a step in the clipboard, it will be overwritten.

Copy Step: Places a copy of the currently selected step in the clipboard. The same details as the Cut step applies.

Paste Step: Takes the step or steps in the clipboard and places them in the Steps after the currently selected step.

Delete Step: Deletes the currently selected step. If the step is a Repeat or Condition, all steps under it are also deleted.

Cut: Click to remove the currently selected step, or steps, and place them in the clipboard.

Copy: Click to place a copy of the currently selected step, or steps, in the clipboard.

Paste: Click to place any step, or steps, from the clipboard before the currently selected step in the Steps Pane.

Data Menu

Hide/Show datamap: Click to show or hide the icons to the left of the Data Viewer that displays how the steps affect the line.

Hide/Show extracted data: Click to show or hide the extraction selections indicating that data is extracted. This simplifies making data selections in the same areas and is useful to display the original data.

Validate All Records: Runs the Steps on all records and verifies that no errors are present in any of the records. Errors are displayed in the Messages Pane.

Steps

Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps do not run when in DataMapper and do not execute when the data mapping configuration is executed in Workflow. However, they can still be modified normally.

Add Extract Step: Adds an Extract Step with one or more extract fields. If more than one line or field is selected in the Data Viewer, each line or field will have an extract field.

Page 91

Page 92

Add Goto Step: Adds a Goto step that moves the selection pointer to the beginning of the data selection. For instance if an XML node is selected, the pointer moves to where that node is located.

Add Condition Step: Adds a condition based on the current data selection. The "True" branch gets run when the text is found on the page. Other conditions are available in the step properties once it has been added.

Add Repeat Step: Adds a loop that is based on the current data selection, and depending on the type of data. XML data will loop on the currently selected node, CSV loops for all rows in the record. In Text and PDF data, if the data selection is on the same line as the cursor position, the loop will be for each line until the end of the record. If the data selection is on a lower line, the loop will be for each line until the text in the data selection is found at the specified position on the line (e.g. until "TOTAL" is found).

Add Extract Field: Adds the data selection to the selected Extract step, if an extract step is currently selected. If multiple lines, nodes or fields are selected, multiple extract fields are added simultaneously.

Add Action Step: Adds a step to run one or more specific actions such as running a JavaScript expression or setting the value of a Source Record Property.

View Menu

Zoom In: Click to zoom in the Steps Pane.

Zoom Out: Click to zoom out the Steps Pane.

Window Menu

Show View

Messages: Shows the Messages Pane.

Steps: Shows the Steps Pane.

Settings: Shows the Settings Pane.

Record: Shows the Record Pane.

Detail tables : Each detail table and nested table is listed here. Click on one to show it in the Data Model Pane.

Step Properties: Shows the Step Properties Pane.

Reset Perspective: Resets all toolbars and panes to the initial configuration of the module.

Page 92

Page 93

Help Menu

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.

Welcome Screen: Click to re-open the Welcome Screen.

Panes

The following topics explain in detail the different panes of the DataMapper Interface.

Data Model Pane

The Data Model Pane displays the Extracted Record, all its fields as well as any detail tables present in the Extracted Record. The information shown is the extracted information for the current record within the Record Set. It is also used as a navigation tool between records and all tables.

Data is displayed as a tree view, with the root level being the Record table, levels below it being detail tables, and any level below being called Nested Tables.

Adding Data

Beyond the methods for adding data described in the Steps Pane and the Data Viewer, there is a specific way to add an Extract step directly into the Data Model pane, which is drag & drop: Dragging a data selection (text and PDF) or a field (CSV, XML and Database) into the Data

Model pane will automatically add the appropriate extraction method into a specific location.

Page 93

Page 94

There are some specific tricks and limitations, however:

If no Extract step is currently selected in the Steps Pane, a new Extract step is created. If an Extract step is selected, new Extract Fields are added to this existing step.

l Dragging a data selection or fields into a specific level of the Data Model (Record or detail

tables) will add the fields to that level.

l When dragging data into a detail table, the Extract Step must be located within the

appropriate Repeat Step, otherwise the extract will not function properly.

l If a Data Model is loaded into the Data Model Pane, when dragging named fields (CSV,

XML, Database), if a field of the same name exists in that level, the extract field extract the data to that field, otherwise it creates a new one.

l Dragging a single field onto a Data Model field will extract to that field regardless of name.

Modifying the Data Model

It is possible to modify the fields within the Data Model pane, effectively generating data models, even if no data is present in the pane. To do this, use the contextual menu within the pane itself. The following options appear depending on the selected line when right-clicking:

Add a field: Click to add a new field at the current level (record or table). Enter the field name in the dialog and click OK to add it.

Add a table: Click to add a new table at the current level (record or existing table). Enter the table name in the dialog and click OK to add it.

Page 94

Page 95

Rename: Click to rename the selected table or field. Enter the new name and click OK to rename. Only available for empty Data Model Fields (see below) tables that only contain them.

Delete: Click to delete the selected table or field. Only available for empty Data Model Fields or tables that only contain them.

Set Type: Use the list to select which the field type (see Data Types). Only available for empty Data Model Fields or tables that only contain them.

Default Value: Click to set the default value for empty Data Model Fields. This value is used if no extraction is present, or if an extraction attached to this field returns no value.

Field Display

Fields in the Data Model pane are displayed in specific ways to simplify comprehension of the display data:

Value: The current value of the extracted field, based on the current Source Record.

The column on the left displays the name of the field. The column on the right displays the extracted data if it exists.

The column on the right displays the current valueof the extracted field based on the current Source Record, when anExtract Step has an extraction for this field.

The icon to the left of the name indicates the Data Type of the field (see Data Types).

A field name with an asterisk to the right indicates that this field is part of an imported Data Model file (called a Data Model Field).

A field with a grey background indicates this Data Model Field does not have any attached extracted data.

A field with a white background indicates that the field has attached extracted data but the step extracting the data is not currently selected.

A field with a blue background indicates that the field has attached extracted data and the step extracting the data is currently selected.

Record Navigation

Records can be navigated directly from the Data Model Pane. The default Record level navigates between records both in the Data Model pane and the Data Viewer, while each table has a similar navigation that influence that table and each under it.

Expand/Contract: Click to hide or show any fields or tables under the current table level.

Table Name: Displays the name of the table as well as the number of records at that level (in [brackets]). At the Record level this is the number of Source records (affected by the

Page 95

Page 96

Boundary settings, Preprocessor and the Record Limit setting). In other levels it represents the number of entries in a table.

Number of Records: The number of available records in the Data Sample. Affected by the Boundary settings, Preprocessor and the Record Limit setting.

First Record: Jumps to the first record in the Data Sample. Disabled if the first record is already shown.

Previous Record: Moves to the previous record in the Data Sample. Disabled if the first record is already shown.

Current Record: Displays the current record or table entry. Type in a record number and press the Enter key to display that record. The number has to be within the number of available records in the Data Sample.

Next Record: Moves to the next record in the Data Sample. Disabled if the last record is already shown.

Last Record: Jumps to the last record in the Data Sample. Disabled if the last record is already shown. If a Record Limit is set in the Settings Pane, the last record will be within that limit.

Importing/Exporting Data Models

Within the Data Model pane, data model files can be exported using the current structure, or imported in order to simplify the extraction process.

Importing and Exporting Data Models is done from within the Data model Pane, using the top-

right icons and .

Rules for importing:

l Imported Data Model fields always overwrite existing field properties when the field name

is the same. Non-existent fields are created automatically with the appropriate field settings. The import is case-insensitive, so fields with a different case will be ignored.

l All data model fields are tagged with the Asterisk (*). If overwriting an existing data model,

existing data model fields that are not in the imported data model file will have their asterisks removed.

Detail Tables

Detail tables contain transactional data that is created when an Extract step is added within a Repeat step.

Page 96

Page 97

In the most basic of transactional systems, a single detail table is used. However, it is possible to create multiple detail tables, as well as nested tables. When detail and nested tables are present in the record, they are displayed as separate levels in the Data Model (see The Data

Model Interface for more information).

Multiple detail tables

Multiple detail tables are useful when more than one type of transactional data is necessary, for instance if two different type of fields are used for different types of data. One example of this would be invoice data containing purchases (items with a set price, quantity, item number) as well as services (service with a price, frequency, contract end date, etc).

Creating more than one detail table is simple. Click the Extract steps and change the name of tables from record.details to something else. In the following example, we will create two tables called record.purchases and record.services.

Page 97

Page 98

Example

1. Data Overview.

Page 98

Page 99

Page 100

2. Extracting Customer and Invoice information.

Page 100

Objectif Lune PRes Connect - 1.4 Operation Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

Welcome to PReS Connect 1.4.2

Icons used in this guide

Setup And Configuration

System and Hardware Considerations

Installation and Activation

Server Settings

DataMapper Module

Basics

Features

DataMapper User Interface