User Guide Version: 1.6.
User Guide Version 1.6.1 Last Revision: 2017-04-18 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-2017. All rights reserved. No part of this documentation may be reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever without the express written permission of Objectif Lune Inc. Objectif Lune Inc. 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.
Table of Contents Table of Contents 5 Welcome to PlanetPress Connect 1.6.
Data Mapping Configuration Creating A New Data Mapping Configuration Opening a Data Mapping Configuration Saving a Data Mapping Configuration Data Mapping Workflow Selecting Data Extracting Data About Promotional and Transactional Data Steps The Data Model How to Use a Data Model? About Records and Fields Data Model File Structure Data Source (Settings) Input Data (Delimiters) Boundaries Data Samples External JS Libraries DataMapper User Interface Menus Panes Example Example Defining Boolean Values Boolean
Example Defining Object Values Text File PDF File CSV and Database Files XML File Left Operand Condition Operators JavaScript Toolbar Shortcut Keys Welcome Screen DataMapper Scripts API Write Your Own Scripts Setting boundaries using JavaScript Objects Functions Methods The Designer Basic Steps Features Templates Contexts Sections Print Creating a Print template with a Wizard Print context Print sections Pages Master Pages Media Email Designing an Email template Creating an Email template with a Wizard Emai
Email header settings Email attachments Web Creating a Web template with a Wizard Web Context Web pages Forms Using Form Elements Using JavaScript Capture OnTheGo COTG Forms Creating a COTG Form Filling a COTG template Testing the template Sending the template to the Workflow tool Using COTG data in a template Designing a COTG Template Capture OnTheGo template wizards Using Foundation Using COTG Elements Testing a Capture OnTheGo Template Content elements Element types Editing HTML Attributes Inserting an e
Table Text and special characters Snippets Adding a snippet Creating a snippet JSON Snippets Styling and formatting Local formatting versus style sheets Layout properties Styling templates with CSS files Styling text and paragraphs How to position elements Rotating elements Styling a table Background color and/or image Border Colors Fonts Locale Spacing Personalizing Content Dynamic tables Loading data Variable Data Formatting variable data Showing content conditionally Dynamic Images Dynamic table Personal
Control Scripts Designer User Interface Dialogs Menus Panes Toolbars Welcome Screen Print Options Job Creation Presets Output Creation Settings Designer JavaScript API Designer Scripts API Control Script API Generating output 545 559 560 630 641 656 661 662 714 723 741 742 797 813 Optimizing a template Scripts Images Generating Print output Saving Printing options in Printing Presets. Connect Printing options that cannot be changed from within the Printer Wizard.
Overview OL Connect Send Connect 1.6.1 General Enhancements and Fixes Connect 1.6.1 Designer Enhancements and Fixes Connect 1.6.1 DataMapping Enhancements and Fixes Connect 1.6.1 Output Enhancements and Fixes Connect Workflow 8.6.
Welcome to PlanetPress Connect 1.6.1 Note Since we are always looking for new ways to make your life easier, we welcome your questions and comments about our products and documentation. Shoot us an email at doc@ca.objectiflune.com. PlanetPress Connect is a series of four tools designed to optimize and automate customer communications management. They work together to improve the creation, distribution, interaction and maintenance of your communications.
Note Information that is important or essential to the completion of a task. Tip Complementary information that may help you better use PlanetPress Connect or suggests an easier method. Warning Information that is potentially critical to using PlanetPress Connect. Pay close attention.
Setup And Configuration This chapter describes the PlanetPress Connect installation and the different considerations that are important in regards to the installation and use of PlanetPress Connect. l "System and Hardware Considerations" below l "Installation and Activation" on page 25 l "Server Settings" on page 55 l Uninstalling System and Hardware Considerations There are a variety of considerations to be aware of.
Note Windows 8.0, Windows XP, Windows 2003 and older versions of Windows are not supported by PlanetPress Connect. Minimum Hardware Requirements l NTFS Filesystem (FAT32 is not supported) l CPU Intel Core i7-4770 Haswell (4 Core) l 8GB RAM (16GB Recommended) l Disk Space: At least 10GB (20GB recommended) Note For tips and tricks on performance, see "Performance Considerations" on page 22.
time. Terminal Server/Service PlanetPress Connect does not support Terminal Server (or Terminal Service) environment as possible under Windows 2000, 2003 and 2008. This is to say, if Terminal Service is installed on the server where PlanetPress Connect is located, unexpected behaviours may occur and will not be supported by Objectif Lune Inc.. Furthermore, using PlanetPress Connect in a Terminal Service environment is an infringement of our End-User License Agreement.
l Locate the Windows Search service and double-click on it. l Change the Startup Type to Disable, and click Stop to stop the service. l Try the installation again. l Once completely, you may re-enable the service and start it. Commandline switches and .ini entries PlanetPress Connect is intended to work stably and reliably, based on Java and the Eclipse framework.
l l max_allowed_packet = 500M : In some implementations, especially when using Capture OnTheGo, large packet sizes are required to allow transferring binary files. This substantial packet size maximum setting ensures that the data received by PlanetPress Connect will be able to be stored within the database. character-set-server = utf8 , collation-server = utf8_unicode_ci , default-characterset=utf8 : These indicate database support for UTF-8/Unicode.
Updating With No Local MySQL Product l l When updating a Connect installation from 1.5.0 which contains a Server Product but no local MySQL Product, the DB Configuration Page will detect which db type was set before (especially if the db configuration was switched from MySQL to MS SQL using the Server Configuration Tool), and default to those settings. On Update from 1.4.
To remove this dependency the user needs to do the following 1. Have a foreign MSSQL running, ready for use with Connect Server. 2. Use the Server Configuration Tool (SCT) to switch the database to MSSQL. 3. (Re-)start Connect Server Service, so that the modifications will become active. 4. Counter check that everything is working properly with MSSQL. 5. Open a commandline prompt with full administration rights. 6. Enter the command sc config OLConnect_Server depend= /. This removes the dependency.
1. Run the Update to Connect 1.6. This will assume the local MySQL database needs to be updated and configured, so the user has to enter a root password on the MySQL Configuration Page (can be any password matching Connect security rules). 2. After the update, the Connect 1.6 Setup needs to be run once more to modify Connect. 3. On the Product Selection page, now the MySQL product can be unselected. 4.
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 PlanetPress Connect help system (this document) is currently only available in English. l Encoding: l Issues can sometimes be encountered in menus and templates when running PlanetPress Connect on a non-English operating system. These are due to encoding issues and will be addressed in a later release.
l l l Mix and match. For example, one instance prioritized for large jobs and the rest for smaller, quicker jobs. Or the contrary. Or, whatever you want, really. RAM Configuration: By default, each instance of the Merge Engine and Weaver Engine is set to use 640MB of RAM. This means that regardless of speed units, if not enough memory is available, output speed might not be as expected.
l l l External JavaScript Libraries: While loading a single JavaScript library from the web is generally very fast (and only done once for the record set), actually running a script on each generated page can take some time. Because yes, JavaScript will run for each record, and often take the same time for each record. Inefficient Selectors: Using very precise ID selectors in script wizards can be much faster than using a text selector, especially on very large documents.
Installation and Activation This topic provides detailed information about the installation and activation of PlanetPress Connect 1.6.1. Note A PDF version of this guide is available for use in offline installations. Click here to download it. PlanetPress Connect 1.6.1 is comprised of 2 different installers: one for the PlanetPress Connect software and one for PlanetPress Workflow 8. Where to Obtain the Installers: The installers for PlanetPress Connect 1.6.
Suite 7.6 installation or on a new computer. For more information, please see Information about PlanetPress 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 PlanetPress Connect 1.1 to upgrade to any later version through the Update Manager it is necessary to install a later version (1.1.8 or later) of the Objectif Lune Update Client.
User accounts and security Permissions for PlanetPress Connect Designer PlanetPress Connect Designer does not require any special permissions to run besides a regular program. It does not require administrative rights and only needs permission to read/write in any folder where Templates or Data Mapping Configurations are located. If generating Print output, PlanetPress Connect Designer requires permission on the printer or printer queue to send files.
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.
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.
updates are confirmed as being up to date, then complete the following steps: 1. Go to https://certs.godaddy.com/repository and download the following two certificates to copy to the offline machine: l l GoDaddy Class 2 Certification Authority Root Certificate - G2 - the file is gdrootg2.crt GoDaddy Secure Server Certificate (Intermediate Certificate) - G2 - the file is gdig2.crt 2. Install the certificates: Right mouse click -> Install Certificate, and follow the steps through the subsequent wizard. 3.
4. Click the OK button to close the dialog. 5. Re-start the computer.
The installer can also calculate how much disk space is required for installing the selected components as well as how much space is available: l l l l Disk space required: Displays the amount of space required on the disk by the selected components. Disk space available on drive: Displays the amount of space available for installation on the drive currently in the Installation Path. Recalculate disk space: Click to re-check available disk space.
For example: "Th1sIs@K" Note When updating from an earlier Connect version, the appropriate MySQL password must be entered or the update will fail. If the password is subsequently forgotten, then the MySQL product must be uninstalled and its database deleted from disk before attempting to reinstall. l l 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.
Tip This option may represent a security risk if the machine is open to the internet. It is heavily recommended that your firewall is set to block access to port 3306 from external requests. The Database Connection page appears if the MySQL Product module was not selected. It defines the necessary information required to connect to an existing database. l l l l l l l Database Configuration: Select the database type to use for the PlanetPress Connect Engine. Currently only MySQL is supported.
PlanetPress Connect Server Configuration The Server Configuration page is where the Connect Server component is configured. The Connect Server settings are as follows:. l Run Server as: Defines the machine username and password that thePlanetPress Connect Server module's service uses. Note The "Server Security Settings" on page 55 dialog can only ever be executed from the user specified here. l l l Username: The account that the service uses to login.
l When ready, click the Finish button to close the installation wizard, and initialize the Product Update Manager, if it was selected. The Product Update Manager If the Configure Update Check option has been selected, 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.
the same folder as the PlanetPress_Connect_Setup_x86_64.exe or in the unpacked folder of the installer.exe. Note Only the installation can be run silently. Silent Mode does not apply to uninstalling, modifying, or updating Connect. Any previous version of Connect must be uninstalled before using the Silent Installer. The required properties file has the following attributes: l Comment Lines, starting with # (e.g. # The options to configure an external database) l Key = Value pairs (e.g. install.
# Database configuration database.type = mysql database.host = 192.168.116.10 database.port = 3308 database.username = root database.password = admin database.schema = my_ol Verbose Logging (Optional) By default, the Silent Installer will log the same way as the GUI installer. 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.
server.runas.username = server.runas.password = server.master.host = server.master.port = server.master.authenticate = true or false server.master.username = server.master.
defined port. A different port is required if 3306 is already taken on that machine by another application. Case 2: The Connect Server is selected and an external database needs to be configured In this case, an external database must be configured for the Server (and other Connect products included in the Silent installation) to be used. 2a: Configuring an external MySQL database To configure an external MySQL database, the following properties should be defined: database.type = mysql (required) database.
required) database.password = (required) database.schema = (default value is objectiflune, optional) Activating a License PlanetPress Connect and PlanetPress Workflow 8 includes separate 30 day trial periods during which it is not necessary to have a license for reviewing basic functionality. If a modification to the license if required, such as to allow an extension to the trial period, or for extra functionality or plugins (e.g.
l l l l l l l l l Serial Number: Displays the activation serial number if the product has been activated in the past. Expiration Date: Displays the date when the activation will expire (or the current date if the product is not activated) Web Activations: Click to be taken to the online activation page (not yet functional). End-User License Agreement (Appears only when loading a license file): l l Name: Displays the name of the application or module relevant to this activation.
l l Customersmust submit their Magic Number and serial number to Objectif Lune via the Web Activations page: http://www.objectiflune.com/activations. The OL Customer Care team will then send the PlanetPress Connect license file via email. Resellerscan create an evaluation license via the 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.
l 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. Warning After installation message will appear warning that the Server services will need to be restarted. Just click OK to proceed. Migrating to a new computer Currently there are no special migration tools to move data from one PlanetPress Connect installation to another.
Workflow 8 and the messenger for Workflow 7 is taken offline. It is only then possible to use Capture from PlanetPress Workflow 8. l l PlanetPress Workflow 8 and PlanetPress® Workflow 7 cannot run simultaneously, since only one version of the Messenger service can run at a time. In fact, no 2 versions of PlanetPress Workflow can on the same machine simultaneously, whatever version is installed.
please contact your reseller or your Objectif Lune Account Manager for more information. What does PlanetPress Connect Contain? PlanetPress Connect is comprised of the following modules: l PlanetPress Workflow 8. This is the natural evolution of PlanetPress® Workflow 7 (Watch, Office or Production). PlanetPress Workflow 8 is very similar to PlanetPress® Workflow 7 version but contains new features and has the ability to run PlanetPress Connect, PlanetPress Suite, PrintShop Mail and PReS Documents.
remain functional. Please note that PlanetPress Workflow 7 and PlanetPress Workflow 8 cannot run at the same time. See Information about PlanetPress Workflow 8 for information about these limitations. The only exception is the PlanetPress Suite Design tool that you can continue to use as it is not part of PlanetPress Connect. For customers upgrading to the free “Print only” version, if you wish you to continue your OL Care engagement, the next year will be priced at the same price as your current price.
l l l l Ability to input data from PDF Ability to print your PlanetPress Suite documents on any Windows printer (no need for printer licenses) Ability to create standard PDF output from your PlanetPress Suite documents Even if you don’t recreate your existing PlanetPress Suite documents, you can easily change your workflow to convert your output to PDF, then output them in PCL to any device supporting it.
l l l Use the new Data Mapper to easily map any input data into a clean data model that any designer person can use Easily create documents with tables that spread over multiple print pages, respecting widow and orphan rules, displaying sub-totals and totals properly Have text that wrap around images Upgrade steps 1. To upgrade to PlanetPress Connect, the first step is to stop your PlanetPress Workflow services.
help importing all those settings, if you wish to import them. 4. To launch the Upgrade wizard, open the PlanetPress Workflow 8 configuration tool and, from the Tools menu, launch the Upgrade Wizard. IMPORTANT: Before you start this process, make sure you have a backup of your current installation/computer.
5.
6. Then select the product from which you wish to upgrade: 7.
8.
9. After that you will need to get the activation file for your product. To obtain your activation, download the PlanetPress Connect installer from the Web Activation Manager, follow the instructions for the installation using the serial number provided to you. You can activate your license through the Web Activation Manager. 10.
Server Settings This chapter describes the different considerations that are important in regards to the use of PlanetPress Connect Server. l "Server Security Settings" below l "Server Extension Settings" below Server Security Settings This dialog controls the security settings for external applications connecting to the PlanetPress Connect Server, such as PlanetPress Workflow or scripts communicating through the REST API.
The Preferences dialog is separated into individual pages, where each page controls certain aspects of the software.
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.
Technical 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 l In the Scheduling Preferences of the Slave, both "Maximum Records" are ignored. Scheduling is handled by the Master.
l l l Username: Enter the username expected by the PlanetPress Connect Server. Password: Enter the password expected by the PlanetPress Connect Server for the selected username. Note that Maximum records in a small job and Minimum records in a large job are not used in Server Extensions. All server scheduling is handled by the Master. Uninstalling This topic provides some important information about uninstalling (removing) PlanetPress Connect1.6.1.
1. PlanetPress Connect 2. Any Connect Workflow using PlanetPress Connectplugins which connect to this server. 3. PlanetPress Connect Server Extensions on remote systems which connect to this machine as the Master Server. 4. Connect products on remote systems which refer to this MySQL database. Uninstallation Wizard The uninstallation is done by running the PlanetPress Connect Setup Wizard in uninstall mode. The Wizard consists of the following pages: 1.
The DataMapper Module The DataMapper is the tool to extract your data and transpose it into a format (a Unified Data Model or UDM) that will allow it to be shared amongst different layouts and outputs created with the Connect Designer. This UDM is a generic format with an emphasis on content, free from any restrictions imposed by the file types or the origin of the data. This UDM also allows a same layout or output to be populated with data from different sources and formats without the need to modify it.
2. Configure settings for the data source. Configure how the Data Sample is read by the DataMapper so it can delimit each record in the file (using Delimiters). See Data Source. 3. Configure the data extraction workflow. Configure the workflow steps that will be required to extract the data from the Data source to the Data Model. This way, data will be converted and prepared to be used by the Designer module. To learn more, see Data Extraction. 4. Editing the Data Model.
The data mapping workflow always starts with the Preprocessor step and ends with the Postprocessor step and can contain as many of the different steps available in the DataMapper. Data Model A Data Model is the format into which Records are saved. It is also a file format that can be exchanged between different parts of the PlanetPress Connect solution. Data Source (Settings) A data source is simply the source of the data. It can be a file (CSV, PDF, TXT, XML) or a particular database.
From the Welcome screen 1. Click Create a New Configuration. 2. From the From a file pane, select the file type (CSV, MS-Access, PDF/VT, Text or XML). 3. Click the Browse button and open the file you want to work with (for a database, you may have to enter a password). 4. Click Finish. From the File menu 1. Click the File menu and select New. 2. Click the Data mapping Configuration drop-down and select Files and then the file (CSV, MS-Access, PDF/VT, Text or XML).. 3. Click Next. 4.
For A CSV File The DataMapper Wizard will guide you through setting the data mapping configuration in three steps. The first step, is to select the data file. The Data Mapper will allow you to verify that the right data file is being used by giving you a preview of the raw data inside the file. The second will then display the different settings it has detected and allow you to change them. A preview window of the extracted data helps you with choosing the settings.
l l Ignore unparseable lines: Ignores any line that does not correspond to the settings above. First row contains field names: Uses the first line of the CSV as headers, which automatically names all extracted fields. 6. Verify that the data is read properly and click Finish. From the File menu 1. Click the File menu and select New.Click the Data mapping Data mapping Wizards drop-down and select From CSV File. 2. Click Next. 3. Click the Browse button and open the CSV file you want to work with.
For a Database File To create a Data Mapping from a Database file using the wizard, use the following steps: From the Welcome screen 1. Open the PlanetPress ConnectWelcome page by clicking the select the Help menu and then Welcome. icon at the top right or 2. Click Create a New Configuration. 3. From the Using a wizard pane, select Database. 4. Use the drop-down to select the Database type. 5. Click Next. From the File menu 1. Click the File menu and select New.
l Encoding: Choose the correct encoding to read the file. l Click Finish to close the dialog and open the actual Data Mapping configuration. Microsoft Access l Click the Browse button and open the database file you want to work with. l Password: Enter a password if one is required. l Click Next. l 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.
sources. l This ODBC source is MSSQL: Check this option if the ODBC source is MSSQL (SQL Server). The options below appear under MSSQL-ODBC advanced configuration: l l Windows authentication: Select to use the Windows User name and Password that are used by the Connect Service. SQL Server authentication: Select to use the User name and Password set below to connect to the SQL Server: l User name: Enter the SQL Server user name. l Password: Enter the password for the above user name. l Click Next.
l Click Next l Click Finish to close the dialog and open the actual Data Mapping configuration. Oracle l Server: Enter the server address for the Oracle database. l Port: Enter the port to communicate with the Oracle server. The default port is 3306. l l l l Database name: Enter the exact name of the database from where the data should be extracted. User name: Enter a user name that has access to the Oracle server and specified database. The user only requires Readaccess to the database.
5. In the Metadata page, select the following options: l l Metadata record levels: Use the drop-down to select what level in the metadata defines a Source Record. Field List: This list displays all fields in all levels of the PDF/VT metadata. l Checkmark: Check any field to add it to the extraction. l Record Level: Displays the level on which the field is located. l Property name: Displays the field names to extract. 6.
2. Click Create a New Configuration. 3. From the Using a wizard pane, select XML. 4. Click the Browse button and open the XML file you want to work with. Click Next. 5. In the Select split level and trigger type page, select the following options: l l XML Elements: A list of node elements that have children nodes. Select the level in the data that will define the Source Record (for example Invoice, Customer ID, Item...etc as opposed to Last name, Due date...etc).
you can set all the parameters here. Enter the starting number, how it should be incremented, the amount required, a suffix, a prefix or if padding is needed. Note You can’t join this configuration to another data file. It is just a counter to be applied on a static template. l l l l l l l Starting Value: The starting number for the counter. Defaults to 1. Increment Value: The value by which to increment the counter for each record.
1. In the Menus, click on File, thenSave, orclick theSave 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: 1. In the Menus, click on File, thenSave As. 2. Browse to the location where the data mapping configuration should be saved and type a name, then click Save.
being in a separate grid position. 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.
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.
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.
Manipulating a Data Selection From a Text File The Text data viewer displays the text-based contents of the Data Sample that is currently active within the data mapping configuration in a grid-like fashion, with each character in the file being in a separate grid position. Once created, data selections can be modified and moved in order to change or extend the data included in the selection.
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.
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.
From a CSV or a Database File The CSV/Database data viewer displays the field-based contents of the Data Sample that is currently active within the data mapping configuration in a grid-like fashion, with each field being in a separate grid position. Once created, data selections can be modified. Modifying a new data selection can be done directly if the data selection is new.
From a XML File The XML data viewer displays the XML-based contents of the Data Sample that is currently active within the data mapping configuration in a tree view, with XML fields displayed at each level of the Sample Record. Once created, data selections can be modified. Modifying a new data selection can be done directly if the data selection is new.
Extracting Data The following example explains in detail how to perform a data extraction for each different data source file types and the Steps used to achieve it. Delimiters and Boundaries must be properly configured beforehand (see Configuring Settings for more information).
To configure the settings for the extraction step such as the list of fields included in the extraction, how to change a field name, the data format of each field or if the information is extracted from a position on the page or to using a script, see Extract Step Properties. From a CSV file or a Database Extracting Promotional Data For more information about Promotional and Transactional data, please refer to About Promotional and Transactional Data. 1.
1. Select the fields that contain the first line item information. 2. Right click on this data selection and select Add Repeat . For more information about what a Repeat step is and why it should be used, please refer to Step_types.htm. 3. Right click again on this data selection and select Add Extraction. A new extraction step will be placed between the Repeat and the Goto steps.
Note Please refer to Menus, Toolbar and Shortcut Keys for more information about the available toolbar buttons, menus and keyboard shortcuts.
The Promotional Data (the customer and invoice information) is 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. 1. Select the child leaf elements of the CUSTOMER() node. 2. Right click on the selected elements and select Add Extraction. Note Alternatively, you can simply drag & drop the selected elements into the Data Model pane.
3. In this case, the invoice information is also part of the promotional data. Select the child leaf elements of the INVOICE() node. 4. Right click on the selected nodes and select Add Extraction. Extracting Transactional Data The Transactional Data (line items information) appears in repeated elements. In the example below, this information appears under the parent node ITEM(). Each ITEM() node gives information about one item. Create a loop on the ITEM() nodes to extract the items information.
1. Select the ITEM() node. 2. Right click on the selected node and select Add Repeat. Note By default, when you click on the Repeat step in the Steps pane, the For Each option is selected in the Repeat type option as shown in theStep Properties pane. The loop will include each ITEM() node. In the Collection field, you will find the corresponding ITEM() node path. Please refer to Repeat Step Properties. 3. Select the children leaf nodes of the ITEM() node.
4. Right click on the selected nodes and select Add Extraction. Note Please refer to Menus, Toolbar and Shortcut Keys for more information about the available toolbar buttons, menus and keyboard shortcuts. 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.
Note Alternatively, you can simply drag & drop the selected fields into the Data Model pane. Extracting Transactional Data The Transactional Data (line items in an invoice) appears on multiple lines and pages. A loop has to be created on these lines to extract the item's information. The line items are extracted in a detail table as described below: 1. Select a simple data in the first line item. For example the product number. 2. Right-click on the selection and select Add Goto.
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 or AMOUNT. Now you can use that text as a condition to stop the loop at the end of the line items list. In that case: 1. Select the text (SUBTOTALS for example) in the Viewer. 2. Right click on the selection and select Add Repeat.
6. From the Viewer pane, select the first field on the left for the first line item. 7. Right click on the selection and select Add Extraction. 8. Select the second field.
9. Right click on the selection and select Add Extract Field. 10. Do the same for the rest of the fields along that same line item. Note The Add Extract Field step allows to add a field to an existing extract step while the Add 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 extraction steps.
1. Select the amounts. 2. Click the Repeat step in the Steps panel. 3. Right click on the selection and select Add a Step/Add Extraction. Also Note That... Note l l l l 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 (in the Data Model pane), the Extract step must be located within the appropriate Repeat step, otherwise the extract will not function properly.
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 to DataMapper API for more information. About Promotional and Transactional Data Promotional data, like its name suggests it, is used for promotional communications. It usually contains personal information like addresses, names and phone numbers used to identify the recipient of these communications.
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. Using a JavaScript a Preprocessor step could be used add a new field in each record set. A unique ID could be created to be added to the output for integrity checks latter on. A time stamp could be added to create reports. A tag could be added to process certain records differently.
Postprocessors Data postprocessors allow the application to extract data that was stored in the data model once the workflow is completed. For example, the postprocessor can export all or parts of the data to a CSV file which can then used to generate daily reports of the Workflow processes.
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.
Extract The Extract step is the heart of the DataMapper software. It takes information from the Data Sample and places it in the Extracted Record within the Record Set. Please refer to Data Extraction for an animated example. For more information on how to add a step, please refer to Toolbar, Menus or "Shortcut Keys" on page 210 under the Interface area. Note To add an Extract step, you can also use JavaScript (select JavaScript from the Mode drop-down in the Step Properties pane).
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.
A Condition step is used when the data extraction must be made based on specific criteria. In the following example, 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.
1. Since the extraction is for transactional data, a Repeat step is first added. 2. A first condition is added to determine whether the line should be considered for the extraction.
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.
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" on page 210 under the Interface area.
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. 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 an example of a Repeat step.
Properties You can also further customize the step properties. Please refer to The Step Properties Interface for more information. 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.
Instead of these nested conditions, it is more convenient to use the Multiple Conditions step.
Each Case condition led to an extraction that occurs when the condition is True. The resulting process has a structure easier to understand and manage. Cases are executed from left to right. For more information on how to add a step, please refer to Toolbar, Menus or "Shortcut Keys" on page 210 under the Interface area. Properties You can also further customize the step properties. Please refer to The Step Properties Interface for more information.
For more information on how to add a step, please refer to Toolbar, Menus or "Shortcut Keys" on page 210 under the Interface area. Properties You can also further customize the step properties. Please refer to The Step Properties Interface for more information. The Data Model The Data Model is basically the structure into which the records are extracted. It is the structure of all the fields and tables of an extracted record.
How to Use a Data Model? The Data Model is simply a file containing that structure and all you need to do is to import that Data Model file into your data mapping configuration in order to be able to use it. When you import the Data Model, it appears in the Data Model pane where you can see all the fields and their types. Once imported a Data Model can be modified. You can delete or add fields, or change their type.
You can edit a Data Model directly from the Data Model pane. Right-click anywhere and a contextual menu will appear, depending on the location. If you right-click inside the record itself, you can add a field or a table. A field will simply be added at the end with no extraction, while a table will be added with no fields inside. The Data Model pane acts as a Data Model editor.
in the Designer module to generate a single documentfor a singlerecipient, and is part of theRecord Set, the complete information being generated by a data mapping configuration and later merged with a template created in Designer. A Field is part of a record and contains a single piece of data from that record. 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.
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.
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.
Boundaries differ from Delimiters. When defining boundaries , multiple delimiters can be included between boundaries - many pages per invoice, many CSV rows 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).
DataMapper User Interface The DataMapper's user interface gives you several options to work with.
Menus The following menu items are shown in the DataMapper Module's menu: File Menu l l l l l l l l l l New...: Opens the Creating a New Data Mapping Configuration dialog. Open: Opens a standard File Open dialog. This dialog can be used to open Templates and data mapping configurations. Open Recent: List the most recently opened Templates and configurations. Clicking on a template will open it in the Designer module, clicking on a data mapping configuration will open it in the DataMapper module.
l l Send to Workflow: Opens theSend to Workflow dialog to send files to a local PlanetPress Workflow software installation. Exit:Closes the software. If any of the files need to be saved, the Save Resources dialog opens. Edit Menu l Undo: Undoes the previous action. l Redo: Redoes the last action that was undone. l l l l Cut Step: Removes the currently selected step and places it in the clipboard. If the step is a Repeat or a Condition, all steps under it are also placed in the clipboard.
Steps l l l l l l l l Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps do not run when in DataMapper and do not execute when the data mapping configuration is executed in Workflow. However, they can still be modified normally. Add Extract Step: Adds an Extract Step with one or more extract fields. If more than one line or field is selected in the Data Viewer, each line or field will have an extract field.
l Settings: Shows the Settings Pane. l Record: Shows the Record Pane. l l l l 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. Preferences: Click to open the Preferences dialog. Help Menu l l l Software Activation: Displays the Software Activation dialog. See Activating your license.
The Data Model is also used as a navigation tool between records and all 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.
Modifying the Data Model It is possible to modify the fields within the Data Model pane, effectively generating data models, even if no data is present in the pane. To do this, use the contextual menu within the pane itself. The following options appear depending on the selected line when right-clicking: l l l l l l Add a field: Click to add a new field at the current level (record or table). Enter the field name in the dialog and click OK to add it.
l l 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.
Importing and Exporting Data Models is done from within the Data model Pane, using the topright icons and . Rules for importing: l l Imported Data Model fields always overwrite existing field properties when the field name is the same. Non-existent fields are created automatically with the appropriate field settings. The import is case-insensitive, so fields with a different case will be ignored. All data model fields are tagged with the Asterisk (*).
The field is not visible in the DataMapper because no data can be extracted into it during the data mapping process. But it will be visible in the Designer, even for existing data models. The only way to add a value to the Extradata field is by using a PlanetPress Connect Workflow process. For example, It could basically include the following steps (2 and 3 are optional): 1. Start the data mapping process. 2. Save the Metadata. 3. Create a database with the Metadata. 4.
Detail Tables Detail tables contain transactional data that is created when an Extract step is added within a Repeat step. 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).
Example 1. Data Overview.
Page 129
2. Extracting Customer and Invoice information.
3. Extracting Transactional Data.
4. Renaming Tables. Nested Tables Nested detail tables are used to create transactional data that is relative to other data. An example of this would be an invoice for a multi-service provider. In this example, a first table contains services (Internet, Cable, Home Phone, Mobile), while one or more nested tables giving details for charges and rebates on each of those services.
Example 1. Data Overview.
Page 134
2. Extracting Customer and Invoice information.
3. Extracting Transactional Data for the First Table.
4. Extracting Transactional Data for Nested Tables.
5. Renaming Tables. Note Creating nested tables is currently an advanced feature, and using these nested tables in the Designer module requires some amount of coding. Note For more information about operations that can be performed on tables, please refer to The Data Model Interface Data Types Looking at the Data Model pane, you will see that the fields are either string or HTML string, depending on how they were extracted. Basically, it is all just text.
module, which is very useful when we’re actually working with the data in a template, you can change the actual type of data that is being extracted so that it can be evaluated differently. How can it be changed? Simply by clicking on any field where you want to modify the data type. You then go to the bottom of the Step Properties pane and click the Type drop-down. Changing the type does not only determine the data type inside your record. It also sets the way it will be read into the Data Source.
l Boolean l String l HTMLString l Integer l Float l Currency l Date l Object Note The Object data type is only available in the DataMapper module. It is created in the Properties subsection in the Preprocessor step, and can be used throughout the data mapping configuration. Boolean Data Type Booleans are a simple True/False data type often used in conditions and comparisons.
Boolean Expressions Boolean values can also be set using an expression of which the result is true or false. This is done using operators and comparisons. Example: record.fields["isCanadian"] = (extract("Country") == "CA"); For more information on JavaScript comparison and logical operators, please see w3schools.com or developer.mozilla.org. String Data Type Strings contain textual data. Strings do not have any specific meaning, which is to say that their contents are never interpreted in any way.
l l It is possible to put more than one string, as well as variables containing strings, by concatenating them with the +operator. For example,"Hello " + sourceRecord.property.FirstName + ", nice to meet you!". Adding more data to an existing string variable or field is possible using a combination of concatenation and assignment.
Building Integer Values Integers can be set through a few methods, all of which result into an actual integer result. l l Direct attribution: Assign an integer value directly, such as 42,99593463712ordata.extract("TotalOrdered"). Mathematical operations: Assign the result of any mathematical operation. For example:22 + 51,3*6,10/5orsourceRecord.property.SubTotal. For more information on mathematics in JavaScript , see w3Schools - Mathematical Operators.
Building Float Values Float values can be the result of direct attribution or mathematical operations just like Integer values. Currency Data Types A signed, numeric, fixed-point 64-bit number with 4 decimals. Values range from -922 337 203 685 477.5808 to 922 337 203 685 477.5808. This data type is routinely used for financial calculations: it is as precise as integers.
Note The Date property is stored in Connect database with zero time zone offset, which makes it possible to convert the time correctly in any location. PlanetPress Workflow, however, shows the date/time as it is stored database (with 0 time zone offset). This is expected behavior for the moment and the zone offset must be calculated manually in PlanetPress Workflow. Extracting dates To extract data and have that data interpreted as a Date, set the type of the respective field to Date: 1.
l DD: Long version of the weekday name (i.e. Monday, Wednesday). These values are based on the current regional settings. l dd: Numeric representation of the day of the month (i.e. 1, 09, 22) l hh: Numeric representation of the hours l nn: Numeric representation of the minutes l ss: Numeric representation of the seconds l ms: Numeric representation of the milliseconds. l ap: AM/PM string.
Entering a date using JavaScript In several places in the DataMapper, Date values can be set through a JavaScript. For example: l l In a field in the Data Model. To do this, go to the Steps pane and select an Extract step. Then, on the Step properties pane, under Field Definition click the Add JavaScript Field button (next to the Field List drop-down). Type the JavaScript in the Expression field. (To rename the field, click the Order and rename fields button.) In a Preprocessor property.
The Data Viewer The Data Viewer is a central part of the module, as the most important aspect of the DataMapper is obviously the data. It displays the content of the Data Source that is currently loaded in the DataMapper in a way that is easy to view and interact with. What is seen in the Data Viewer, however, is not simply the raw Data Source. It is formatted to fit your screen and can be modified through the use of a Preprocessor.
and using the respective resize handles. As long as data selections exist, any step you add does not remove that data selection. Here is a small trick to extract multiple lines. Make a selection for the first line, click on Add Extract Step, move the selection to the next line, then click Add Extract Field and so on until the end of the data you want to extract.
l l l l l Font (Text file only): Use the drop-down to change the font used to display text. Useful for double-byte data. It is recommended that monospace fonts be used. Hide/Show line numbers the left of the Data Viewer. (Text file only): Click to show or hide the line numbers on Hide/Show datamap : Click to show or hide the icons to the left of the Data Viewer which displays how the steps affect the line.
The Add Extract Field item is available only after an Extract step has been added to the workflow. For more information about the different steps that can be added to a Data Mapping workflow, please refer to Steps. Operations In the following example, clicking on the Repeat step shows in which lines the loop takes place. Click on the Goto within the loop to show which lines are skipped. Clicking on a Condition shows whether that condition is true or false for each line.
Messages Pane The Messages pane is shared between the DataMapper and Designer modules and displays any warnings and errors from the data mapping configuration or template. At the top of the Message pane are control buttons: l Export Log: Click to open a Save As dialog where the log file (.log) can be saved on disk. l Clear Log Viewer: Click to remove all entries in the log viewer. l Filters: Displays the Log Filter .
Log Filter The log filter determines what kind of events are show in the Messages Pane. l l Event Types group: l OK: Uncheck to hide OK-level entries. l Information: Uncheck to hide information-level entries. l Warning: Uncheck to hide any warnings. l Error: Uncheck to hide any critical errors. Limit visible events to: Enter the maximum number of events to show in the Messages Pane. Default is 50.
l l l l l l l l Field separator: Defines what character separates each fields in the file. Text delimiter: Defines what character surrounds text fields in the file, preventing the Field separator from being interpreted within those text delimiters. Comment delimiter: Defines what character starts a comment line. Encoding: Defines what encoding is used to read the Data Source ( US-ASCII, ISO8859-1, UTF-8, UTF-16, UTF-16BE or UTF-16LE ).
average character in the font. l l l l Line spacing: Determines the spacing between lines of text. The default value is 1, meaning the space between lines must be equal to at least the average character height. Paragraph spacing: Determines the spacing between paragraphs. The default value is 1.5, meaning the space between paragraphs must be equal to at least "1.5" times the average character height to start a new paragraph. Magic number: Determines the tolerance factor for all of the above values.
l Custom SQL button query. : Click to open the SQL Query Designer and type in a custom SQL For a Text File Because text files have many different shapes and sizes, there are a lot more options for the input data in these files. You can add or remove characters in lines if you have a big header you want to get rid of, or really weird characters at the beginning of your file. Set a line width if you are still working with old line printer data and so on.
l l l Location: Choose Selected area or Entire width to use the value of the current data selection as the text value. Left/Right: Use the spin buttons to set the start and stop columns to the current data selection (Selected area) in the Source Record. Lines before/after: Defines the delimiter a certain number of lines before or after the current line. This is useful if the text triggering the delimiter is not on the first line of each page.
single record or you could group all invoices for one customer into a single record. So the boundaries for each record can be completely dependent on how you want to use the data. With no actual boundary markers inside the data, there needs to be a way to identify specific locations in the input stream and mark those locations as record boundaries. Fortunately, every single file format has intrinsic, natural delimiters that are used to identify chunks of related data.
l Record(s) per page: Defines a fixed number of lines in the file that go in each Source Record. l l On change: Defines a new Source Record when a specific field (Field name) has a new value. l l l Records: The number of records to show in each Source Records. Field name: Displays the fields in the top line. The selected value determines new boundaries. On script: Defines the boundaries using a custom user-defined JavaScript. For more information see Boundaries Using javaScript.
l Trigger: Defines the type of rule that defines when a boundary is created, establishing a new record in the Data Sample (called a Source Record). l On page: Defines a boundary on a static number of pages. l l Number of pages: Defines how many pages are in each Source Record. On text: Defines a boundary on a specific text comparison in the Source Record. l l l Start coordinates (x,y): Defines the left and top coordinates of the data selection to compare with the text value.
end of a record would not be found in the middle of a line. Note also that it is possible with this format to set the DataMapper's Input Data settings to 1 line per page. That essentially allows you to set the natural delimiter on each and every line in the file. If you select the wrong page at the top, for example, making a new selection and clicking on Select the area will redefine the location.
on the first and on the last page of a document, you could specify a number of occurrences of 2. In this way, no need to inspect other items for whether it is on the first page or the last page. you know you have found the string two times, which is enough to fix the boundary. l l Delimiters before/after: Defines the boundary a certain number of pages before or after the current page. This is useful if the text triggering the document is not located on the first page of each Source Record.
The Data Samples The Data Sample area displays a list of all the imported Data Samples that are available now in the data mapping configuration. As many Data Samples as necessary can be imported to properly test the configuration. Instead of buttons listed below, you can also right-click to bring up the context menu, which offers the same options. l l l l l Add : Adds a new Data Sample from an external Data Source. The new Data Sample will need to be of the same data type as the current one.
Default Data Format Default Format Settings can also be defined at the DataMapper configuration level (see DataMapper Default Data Format for more information). SQL Query Designer The SQL Query Designer is used to design a custom SQL query to pull information from a database. l l l l Tables: Lists all tables and stored queries in the database. Custom Query: Displays the query that retries information from a database. Each database type has their own version of the SQL query language.
l Add a Step: Adds a step to the process. Right click anywhere in the Steps pane and select Add a Step from the contextual menu. For more information about the steps and how to use them, please refer to Steps. More options are available when a Repeat or a Condition step is selected: l Add Step in Repeat: To add a step into the Repeat loop, right-click on the step and select Add a Step in Repeat.
l Add Step in True: To add a step under the true branch of a condition step, rightclick on the condition and select Add a Step in True.
l l l Add Step in False: To add a step under the false branch of a condition step, rightclick on the condition and select Add a Step in False. Add Multiple Conditions Step: To add a Multiple Conditions step. Add Case Step: Add a case condition under the selected Multiple Conditions step.
l l Ignore Step: Click to set the step to be ignored (aka disabled). Disabled steps are grayed and do not run when in DataMapper and do not execute when the data mapping configuration is executed in Workflow. However, they can still be modified normally. Moving: To move a step, right-click on it and select Cut Step or use the button in the Toolbar. If the step is Repeat or Condition, all steps under it will also be placed in the clipboard.
Note You can also use a drag & drop to move steps. l Delete Step: To remove a step, right-click on it and select Delete step from the contextual menu or use the button in the Toolbar. If the step to be deleted is Repeat or Condition, all steps under it will also be deleted. Warning Currently there is no Undo and Redo feature in the DataMapper module.
l l Copy Step: To copy a step, right-click on it and select Copy Step or use the button in the Toolbar. If the step is Repeat or Condition, all steps under it will also be placed in the clipboard. If there is already a step in the clipboard, it will be overwritten. To place a copy of the step at its destination, right-click the step in the position before the desired location and select Paste Step, or use the button in the Toolbar.
within the PlanetPress Workflow process. For each property, the following is available: l Name: A read-only field displaying the name of the property. l Scope: A read-only field indicating that the scope of the property is Automation. l Type: A read-only field indicating the data type for each property. l Default Value: Enter a default value for the property.
Note Properties are evaluated in the order they are placed in the list, so properties can use the values of previously defined properties in their expression. l Name: The name of the property used to refer to its value. l Scope: What this property applies to: l l l l l Entire Data: These properties are static properties that cannot be changed once they have been set, in other words they are Global constants. Each Record: These properties are evaluated and set at the beginning of each Source Record.
Preprocessor The Preprocessor subsection defines what preprocessors run on the Data Sample before it is sent to the extraction. Preprocessors modify the Data Sample in many ways, and each Preprocessor runs in turn, using the result of the previous one as an input. l Name: The name to identify the Preprocessor. l Type: The type of Preprocessor. Currently there is only one type available. Preprocessor definition l Expression: The JavaScript expression that will run on the Data Sample. See DataMapper API.
Extraction Definition l l Data Table: Defines where the data will be placed in the Extracted Record. The root table is record, any other table becomes a detail table. For more information see detail tables. Append values to current record: When the Extract Step is within a loop, check this to ensure that the extraction will be done in the same detail line as any previous extractions within the same loop. This ensures that, if multiple extracts are present, only one detail line is created.
Note If the selection contains multiple lines, only the first line is selected. l Post Function: Enter a JavaScript expression to be run after the extraction. For example replace("-","") would replace a single dash character inside the extracted string. l l Trim: Select to trim empty characters at the beginning or the end of the field. l Concatenation string: l l l Use JavaScript Editor: Click to display the Script Editor dialog.
l Left: Defines the start of the data selection to extract. l Right: Defines the end of the data selection to extract. l l l Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Height: The height of the selection box. Use selection: Click to use the value (Left, Right, Top offset and Height) of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected.
Note If the selection contains multiple lines, only the first line is selected. l Type: The data type of the selected data. CSV and Database Files l Field List: The Field List displays each of the single fields that are being extracted in a drop-down. Fields can be re-ordered and re-named within the Ordering and Renaming Fields dialog. l l l Add JavaScript Field: Click to add a new extract field.
l Post Function: Enter a JavaScript expression to be run after the extraction. For example replace("-","") would replace a single dash character inside the extracted string. l l Use JavaScript Editor: Click to display the Script Editor dialog. l Trim: Select to trim empty characters at the beginning or the end of the field. l Type: The data type of the selected data. JavaScript : The result of the JavaScript Expression written below the drop-down will be the value of the extracted field.
l l Add Unique ID to extraction field: Check to add a unique numerical set of characters to the end of the extracted value. This ensures no two values are identical in the Record Set. Based on: Determines the origin of the data. l Location: The contents of the data selection set below will be the value of the extracted field. The data selection settings are different depending on the data sample type. l XPath: The path to the XML field that is extracted.
Note If the selection contains multiple lines, only the first line is selected. l Type: The data type of the selected data. Data Format The data format defines the precise format for some of the variable types, such as dates and currencies. l Boolean l String l HTML String l Integer l l l l Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Treat empty as 0: Considers empty spaces as 0.
l l l l l Decimal Separator: Determines the character to use for decimal values, generally a dot (.). Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Currency Sign: Determines the character to add before the value in the Extracted Record. Treat empty as 0: Considers empty spaces as 0. Date l l Date/Time Format: Determines how the date is read. The format written here needs to correspond with the format in the data selection.
Action Step Properties The Action step can run multiple specific actions one after the other in order. More actions will be available in the future. Description This subsection is collapsed by default in the interface, to allow more screen space be given to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane.
l Left: Defines the start of the data selection to extract l Right: Defines the end of the data selection to extract l l l Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Height: The height of the selection box. Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected.
l Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Data Format The data format defines the precise format for some of the variable types, such as dates and currencies. l Boolean l String l HTML String l Integer l l l l Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Treat empty as 0: Considers empty spaces as 0.
l l l l l Decimal Separator: Determines the character to use for decimal values, generally a dot (.). Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Currency Sign: Determines the character to add before the value in the Extracted Record. Treat empty as 0: Considers empty spaces as 0. Date l l Date/Time Format: Determines how the date is read. The format written here needs to correspond with the format in the data selection.
Note If the selection contains multiple lines, only the first line is selected. l l Trim: Select to trim empty characters at the beginning or the end of the field JavaScript : The result of the JavaScript Expression written below the drop-down will be the value of the extracted field. If the expression contains multiple lines, the last value attribution (variable = "value";) will be the value. See DataMapper API. l Expression: The JavaScript expression to run.
l Data Format The data format defines the precise format for some of the variable types, such as dates and currencies. l Boolean l String l HTML String l Integer l l l l Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Treat empty as 0: Considers empty spaces as 0. Float l l l l l Negative Sign Before: Adds a negative (-) sign before negative values in the Extracted Record.
l Date l l Date/Time Format: Determines how the date is read. The format written here needs to correspond with the format in the data selection. Language: The language in which the date is written, when relevant. Useful when months or days are written alphabetically. Note Default Format Settings can be defined at the user level, at the DataMapper configuration level and/or at the field level. (See Datamapper Default Data Format for more information.
l JavaScript : The result of the JavaScript Expression written below the drop-down will be the value of the extracted field. If the expression contains multiple lines, the last value attribution (variable = "value";) will be the value. See DataMapper API. l Expression: The JavaScript expression to run. l Use JavaScript Editor: Click to display the Edit Script dialog.
l HTML String l Integer l l l l l l l Treat empty as 0: Considers empty spaces as 0. Negative Sign Before: Adds a negative (-) sign before negative values in the Extracted Record. Decimal Separator: Determines the character to use for decimal values, generally a dot (.). Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") Treat empty as 0: Considers empty spaces as 0.
Note Default Format Settings can be defined at the user level, at the DataMapper configuration level and/or at the field level. (See Datamapper Default Data Format for more information.) Run JavaScript l Expression: The JavaScript expression to run. l Use JavaScript Editor: Click to display the Edit Script dialog.
By default, if an Extract step is added within a Repeat step, its extraction is made in a Details Table. Description This subsection is collapsed by default in the interface, to allow more screen space be given to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here gives more details on the step and will be displayed in the tooltip appearing when hovering over the step in the Steps pane.
l Use JavaScript Editor: Click to display the Edit Script dialog. Note Running a JavaScript expression offers many possibilities, for example: l l l Setting Properties and Record Field values using advanced expressions Do complex mathematical operations and calculations More features to come in future versions. For more information, see JavaScript in DataMapper.
l Based On: l Position: The data in the specified position for the comparison. l l l l l l l l l l l l Height: The height of the selection box. Use Selection: Click to use the value of the current data selection for the extraction. Trim: Select to trim empty characters at the beginning or the end of the field. Value: The text value to use in the comparison. Use selected text: Uses the text in the current data selection as the Value.
l Extractor Property: The value of an internal extractor variable: l l l Counter: The value of the current counter iteration in a Repeat step. Vertical Position: The current vertical position on the page, either in Measure (PDF) or Line (Text and CSV). Operators: l l l l l l is equal to: The two specified value are identical for the condition to be True. contains: The first specified value contains the second one for the condition to be True.
l Field: The contents of a specific field in the Extracted Record. l l JavaScript : The result of a JavaScript Expression. l l l l l l l Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the Edit Script dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression.
XML Files l Based On: l Position: The data in the specified position for the comparison. l l l l l l l l l l Value: The text value to use in the comparison. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression.
l Operators: l l l l l l is equal to: The two specified value are identical for the condition to be True. contains: The first specified value contains the second one for the condition to be True. is less than: The first specified value is smaller, numerically, than the second value for the condition to be True. is greater than: The first specified value is larger, numerically, than the second value for the condition to be True. is empty: The first specified value is empty.
l Add condition: Click to create a new condition in the list. This will always branch the current condition as an "AND" operator. l Delete condition: Delete the currently selected condition. l To rename a Condition, double click on its name from the Rule tree subsection . Conditions are made by comparison of two operands using a specific Operator. Note Both the Left and Right operands have the same properties. l Based On: l Position: The data in the specified position for the comparison.
l Field: The contents of a specific field in the Extracted Record. l l JavaScript : The result of a JavaScript Expression. l l l l l l l Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the Edit Script dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression.
Multiple Conditions Step Properties Description This subsection is collapsed by default in the interface, to allow more screen space be given to other important parts. Name: The name of the step. This name will be displayed on top of the step's icon in the Steps pane. Comments: The text entered here gives more details on the step and will be displayed in the tooltip appearing when hovering over the step in the Steps pane.
l Value: A specified static text value. l l l l l l l l Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression. l l Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The contents of a specific field in the Extracted Record. l l Value: The text value to use in the comparison. Expression: The JavaScript line that is evaluated.
l Order Multiple Conditions: Under the Name column, select a case then click one of the buttons on the right (Delete, Move Up, Move Down) to delete or change the order of a case in the list. Operators Case conditions are made by comparison of the two operands, left and right, using a specific Operator. l is equal to: The two specified value are identical for the condition to be True. l contains: The first specified value contains the second one for the condition to be True.
l Target Type: Defines the type of jump . l Line: Jumps a certain number of lines or to a specific line. l l l l Current Position: The Goto begins at the current cursor position. l Top of record: The Gotobegins at line 1 of the source record. Move by: Enter the number of lines or pages to jump. Page: Jumps between pages or to a specific page. l l l From: Defines where the jump begins: From: Defines where the jump begins: l Current Position: The Gotobegins at the current cursor position.
l l l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Expression: Enter the text or Regex expression to look for on the page. Use selection: Click while a selection is made in the Data Viewer to copy the contents of the first line of the selection into the Expression box. Use regular expression: Check so that the Expression box is treated as a regular expression instead of static text.
l l Use selection: Click while a selection is made in the Data Viewer to automatically set the left and right values to the left and right edges of the selection. Next occurrence of: Jumps to the next occurrence of specific text or a text pattern, either anywhere on the line or in specific columns. l Inspect entire page width: When checked, the Next line with content and Next occurrence of options will look anywhere on the line.
l l l l l Sibling element: Jumps the number of siblings (nodes at the same level) defined in the Move byoption. Sibling element with same name: Jumps the number of same name siblings (nodes at the same level of which the node is the same name) defined in the Move byoption. Element, from top of record: Jumps to the specified node. The XPATH in the Absolute XPATHoption starts from the root node defined by /.
l Export: Click to export the current Postprocessor configuration and content to a file. l Import: Click to import a Postprocessor configuration and content from an external file. Postprocessor definition JavaScript l l l Expression: The JavaScript expression that will run on the Data Sample. See DataMapper API. Use JavaScript Editor: Click to display the Script Editor dialog. Use selected text: Uses the text in the current data selection as the Value.
Step Manipulation Note All steps except JavaScript require an active data selection in the Data Viewer. l l l l l l l l l l Add Extract Step : Adds an Extract Step with one or more extract fields. If more than one line or field is selected in the Data Viewer, each line or field will have an extract field. Add Goto Step : Adds a Goto step that moves the selection pointer to the beginning of the data selection.
l l l l Delete Step : Deletes the currently selected step. If the step is a Repeat or Condition, all steps under it are also deleted. Ignore Step : Click to set the step to be ignored (aka disabled). Disabled steps do not run when in DataMapper and do not execute when the data mapping configuration is executed in Workflow. However, they can still be modified normally. Validate All Records : Runs the process on all records and verifies that no errors are present in any of the records.
Contents l Activation: Click to open the Objectif Lune Web Activation Manager. l Release Notes: Opens the current Release Notes for PlanetPress Connect. l Website: Opens the PlanetPress Connect website. l Take A Tour: Click to open the YouTube Playlist giving you a tour of the software. l Use the DataMapper to...: l l l l Open an Existing Configuration: Click to open the standard Browse dialog to open an existing data mapping configuration.
Objects Name Description Available In automation Returns a ScriptableAutomation object encapsulating the properties of the PlanetPress Workflow process that triggered the current operation. Boundaries, all Steps except Goto boundaries Returns a boundaries object encapsulating properties and methods allowing to define the boundaries of each document in the job. Boundaries data Returns a data object encapsulating properties and methods pertaining to the original data stream.
Name Description Available In the current DataMapper process. Steps Functions Name Description Available In copyFile() Copies a file to the target file path, replacing it if it already exists. Boundaries, Steps createTmpFile() Creates a file with a unique name in the temporary work folder and returns a file object. Boundaries, Steps deleteFile() Deletes a file. Boundaries, Steps execute() Calls an external program and waits for it to end.
Name Description Available In openBinaryWriter() Opens a file as a binary file for writing purposes. Boundaries, Steps openTextReader() Opens a file as a text file for reading purposes. Boundaries, Steps openTextWriter() Opens a file as a text file for writing purposes. Boundaries, Steps Methods Name Description Related object Available In File Type connect() Method that returns a new database connection object.
Name Description Related object Available In File Type currentLoopCounter () Returns an integer value representing the current iteration of the containing loop. steps Extract, Condition, Repeat, and Action steps all currentPage() Returns an integer value representing the current page where the current position is located, inside the current record. steps Extract, Condition, Repeat, and Action steps Text and PDF currentPageHeight() Returns the height of the current page in millimeters.
Name Description Related object Available In File Type Method that returns True if metadata field exists. data Boundaries all Finds the first occurrence of a string starting from the current position. data and boundaries findRegExp() Finds the first match for a regular expression pattern starting from the current position. data Extract, Condition, Repeat, Multiple Conditions and Action steps TXT and PDF found A boolean value indicating whether the last call to find () was successful.
Name Description Related object Available In File Type get() Retrieves an array of strings. automation and boundaries Boundaries all getVariable() Method that retrieves the value currently stored in a variable. automation and boundaries Boundaries all moveTo() Moves the pointer in the source data file to another position. steps Extract, Condition, Repeat and Action steps all moveToNext() Moves the position of the pointer in the source data file to the next line, row or node.
Name Description Related object Available In File Type coordinates of the region. set() Sets a new DataMapper record boundary. automation and boundaries Boundaries all setVariable() Method that sets a variable to the specified value, automatically creating the variable if it doesn't exist yet. automation and boundaries Boundaries all totalPages() Returns an integer value representing the total number of pages inside the current record.
How Scripts Work A script is a small set of instructions, written in JavaScript. When Connect generates the actual extraction process, it takes each step, one by one, and runs all scripts for it. Creating a New Script In DataMapper, you can use scripts to set Boundaries (see Boundaries Using JavaScript) or in the Step Properties for steps such as: l l l Extraction step where the data selection is based on JavaScript or you can enter a post function script.
Tip In the Edit script dialog, press Ctrl-Space to bring up the list of available JavaScript objects and functions (see Datamapper API). Use the arrow keys to select a function or object and press enter to insert it. Type a dot after the name of the function or object to see which features are subsequently available. Syntax Rules Every script in the DataMapper must follow JavaScript syntax rules.
already available through the GUI when setting the trigger to On Page and specifying 3 as the Number of Pages. Note Remember that your script is being called on each new delimiter encountered by the DataMapper parsing algorithm. If you are dealing with a DB Query that returns a million records, the script will be executed a million times! So you have to craft your script in such a way that it doesn't waste too much time examining all possible conditions.
Examples Basic example using a CSV file Note In this first example, don't focus on the actual syntax being used. You can take a look at the API reference later on for more information. Imagine you are a classic rock fan and you want to extract the data from a CSV listing of all the albums in your collection. Your goal is to extract records that change whenever the artist OR the release year changes.
Note The first line is just the header with the names of the CSV columns. Obviously, the data is already sorted per year, per artist, and per album. Your goal is to examine two values in each CSV record and to act when either changes. The DataMapper GUI allows you to specify a On Change trigger, but you can only specify a single field.
expects is simply the column name. The region is then passed as a parameter to the get() method, which reads its contents and converts it into an array of strings (because any region, even a CSV field, may contain several lines). l l l To "remember" the values that were processed the last time the event was triggered, we use variables that remain available in between events.
Then our script would look like this: // Read the values of both columns we want to check var zeBand = boundaries.get(region.createRegion(1,1,30,1)); var zeYear = boundaries.get(region.createRegion(61,1,65,1)); // Check that at least one of our variables holding previous values have been initialized already, before attempting to compare the values if (boundaries.getVariable("lastBand")!=null) { if ( zeBand[0]!=boundaries.getVariable("lastBand") || zeYear[0]!=boundaries.
Note The PDF context also expects physical coordinates, just like the Text context does, but since PDF pages do not have a grid concept of lines and columns, the above parameters would instead be specified in millimeters relative to the upper left corner of each page. So for instance, to create a region for the Year, the code might look like this: region.createRegion(190,20,210,25) which would create a region located near the upper right corner of the page.
Property Type Description PlanetPress Workflow properties ScriptableAutomationProperty Returns a ScriptableAutomation object containing additional information (file name, process name and task ID) from PlanetPress Workflow variables ScriptableAutomationProperty Returns a ScriptableAutomation object containing the list of local and global variables defined by the user in PlanetPress Workflow to the DataMapper.
The other properties are accessible as they are. Examples To access JobInfo 1 to 9 from Workflow: automation.jobInfo.JobInfo1; To access ProcessName, OriginalFilename or TaskIndex from Workflow: automation.properties.OriginalFilename; To access Workflow variables (declared in the Preprocessor properties): automation.variables.Same_as_workflow; boundaries Object Returns a boundaries object encapsulating properties and methods allowing to define the boundaries of each document in the job.
Property Return Type currentDelim A read-only 1-based index (number) of the current delimiter in the file. In other words, the Beginning Of File (BOF) delimiter equals 1. It indicates the position of the current delimiter relative to the last document boundary Methods The following table describes the functions of the boundaries object. Method Description find() Finds the first occurrence of a string starting from the current position. get() Retrieves an array of strings.
Property Description Return Type properties Contains properties declared in the preprocessor step (see Preprocessor Step Properties for details). Returns an array of properties defined in the Preprocessor step with the data scope (i.e. statically set at the start of the job). Methods The following table lists the methods of the data object. Method extract() extractMeta () fieldExists () find() findRegExp() db Object Returns a db object allowing you to connect to a database.
Methods The following table describes the methods of the logger object. Method Parameters Description error() message: string Logs an error message info() message: string Logs an informational message warn() message: string Logs a warning message record Object The current record in the main data set. Properties Property Return Type fields The field values that belong to this record.
Methods The following table describes the methods of the region object. Method Description Return Type found Field that contains a boolean value indicating if the last call to boundaries.find() was successful. Since the find() method always returns a region, regardless of search results, it is necessary to examine the value of found to determine the actual result of the operation. Boolean range Read-only object containing the physical coordinates of the region.
Property Return Type properties Returns an array of properties defined in the Preprocessor step with the Record Scope (i.e. dynamically reset with each new record). Example The property, used by the object Source Record, must first be declared in a Preprocessor step: 1. Enter the property Name. 2. Select Each record from the Scope drop-down list. 3. Select a Type for the Property.
steps Object Returns a steps object encapsulating properties and methods pertaining to the current DataMapper process. This object is available in an Extract, Condition, Repeat or Multiple Conditions step script. Methods The following table lists the methods of the steps object. Method Description currentPosition() Returns the current position of the pointer in the data. currentLoopCounter () Returns an integer value representing the current iteration of the containing loop.
position to 14 lines below the current position of the pointer in the data */ curPage++; } else if(curLine.startsWith("LOAD FACTOR")) { /* Extracts data to the curLine variable until the string "LOAD FACTOR" is encountered */ break; } else { lineArray.push(curLine); /* Adds the current line value (extraction) to the array */ } Functions copyFile() Function that copies a file to the target file path, replacing it if it already exists.
access to a physical file when writing. In the end, the contents is transferred into a physical file for which only a single input/output access will occur. Examples In the following script, a file is read in a created temporary file: try{ // Create a temporary file var tmpFile = createTmpFile(); // Open a writer on the temporary file var writer = openTextWriter(tmpFile.getPath()); try{ var line = null; // Current line // read line by line and readLine will return null at the end of the file.
String that specifies the path and file name of the file to be deleted. Examples 1. You can delete the data file used in the DataMapper: deleteFile(data.filename); 2. You can delete a file in a local folder deleteFile("c:\Content\test.txt"); execute() Function that calls an external program and waits for it to end. execute(command) Calls an external program and waits for it to end. command String that specifies the path and file name of the program to execute.
newCharArray(size) Returns a new character array of size elements. size Integer that represents the number of elements in the new array. Examples newDoubleArray() Function that returns a new double array. newDoubleArray(size) Returns a new double array of size elements. size Integer that represents the number of elements in the new array. Examples newFloatArray() Function that returns a new float array. newFloatArray(size) Returns a new float array of size elements.
size Integer that represents the number of elements in the new array. Examples newLongArray() Function that returns a new long array. newLongArray(size) Returns a new long array of size elements. size Integer that represents the number of elements in the new array. Examples newStringArray() Function that returns a new string array. newStringArray(size) Returns a new string array of size elements. size Integer that represents the number of elements in the new array.
Examples openBinaryWriter() Function that opens a file as a binary file for writing purposes. openBinaryWriter(filename, append) Opens filename as a binary file for writing purposes. The append Boolean parameter specifies whether the file pointer should initially be positioned at the end of the existing file (append mode) or at the beginning of the file (overwrite mode). The function returns a BinaryWriter object. filename String that represents the name of the file to open.
while ((line = fileIn.readLine())!=null){ fileOut.write(line.replace((subject),"")); fileOut.newLine(); } fileIn.close(); fileOut.close(); deleteFile(data.filename); tmp.move(data.filename); Please note that the temporary file must be closed at the end of the program. OpenTextWriter() Function that opens a file as a text file for writing purposes. OpenTextWriter(filename, encoding, append) Opens filename as a text file for writing purposes, using the encoding specified as a string (UTF-8, ISO-8859-1, etc.).
fileOut.newLine(); } fileIn.close(); fileOut.close(); deleteFile(data.filename); tmp.move(data.filename); Please note that the temporary file must be closed at the end of the program. Methods connect() Method that returns a new database connection object connect(url, user, password) Returns a new database connection object after connecting to the url and authenticating the connection with the provided user and password information. url String that represents the url to connect to.
x1 Double that represents the left edge of the region. y1 Double that represents the top edge of the region. x2 Double that represents the right edge of the region. y2 Double that represents the bottom edge of the region. Example The following script attempts to match ((n,m)) or ((n)) against any of the strings in the specified region and if it does, a document boundary is set. var myRegion = region.createRegion(170,25,210,35); var regionStrings=boundaries.
if(!(boundaries.Eof || boundaries.Bof)){ var recordValue = boundaries.get(region.createRegion('ID'))[0]; if(!(recordValue==boundaries.getVariable('lastValue'))){ boundaries.setVariable('lastValue',recordValue); boundaries.set(0); } } currentLoopCounter() Returns an integer value representing the current iteration of the containing loop. When loops are nested, you have access to the iteration for the current loop but not to any of the parent loops.
Example currentPosition() Returns the current position of the pointer in the data. Depending on the type of data being processed, the return value may be a string (e.g. XPath value in XML), an integer (e.g. line numbers in text ot tabular data), or a measure in millimeters(e.g. PDF data). Example extract() Extracts the text value from a rectangular region. All coordinates are expressed as characters. The extract method always returns a String data type.
Examples Example 1: In this example you have the script command data.extract(1,22,8,1,"
");. It means that the left position of the extracted information is located at 1, the right position at 22, the offset position is 8 (since the line number is 9) and the regionHeight is 1 (only 1 line selected). Finally, the "
" string is used for concatenation. Example 2: In this example you have the script command data.extract(1,22,9,6,"
");.
extract(xPath) Extracts the text value of the specified node. xPath String that can be relative to the current location or absolute from the start of the record. Example In this example you have the script command data.extract('./CUSTOMER/FirstName');. It means that the extraction is made on the FirstName node under Customer.
extract(columnName, rowOffset) Extracts the text value for the specified fieldName. fieldName String that represents the column name. rowOffset Number that represents the row index relative to the current position. To extract the current row, specify 0 as the rowOffset. Example In this example you have the script command data.extract('ID',0);. It means that the extraction is made on the ID field in column 0 (the first from the left).
extract(left, right, verticalOffset, lineHeight, separator) Extracts the text value from a rectangular region. All coordinates are expressed in millimeters. left Double that represents the distance from the left edge of the page to the left edge of the rectangular region. right Double that represents the distance from the left edge of the page to the right edge of the rectangular region. verticalOffset Double that represents the distance from the current vertical position.
Double that represents the total height of the region. separator String inserted between all lines returned from the region. An empty string can be specified. Example In this example you have the script command data.extract (4.572,51.815998,37.761333,3.7253342,"
");. It means that the left position of the extracted information is located at 4.572mm, the right position at 51.815998mm, the vertical offset position is 37.761333mm and the lineHeight is 3.7253342mm.
extractMeta(levelName String, propertyName String) Extracts the value of metadata field propertyName from a PDF/VT's levelName level. Note that names are case-sensitive. The extractMeta method always return a string data type. levelName String. propertyName String. Examples fieldExists() Method that returns True if a metadata field exists. fieldExists(levelName, propertyName) In a PDF file, that method that returns True if metadata field propertyName exists at the levelName level or False otherwise.
fieldExists(xPath In a XML file, that method returns True if the specified xPath exists in the current record. Otherwise, it returns False. xPath String. Examples find() Finds the first occurrence of a string starting from the current position. The search can be constrained to the series of characters in a text file or to a vertical strip in a PDF file located between leftConstraint and rightConstraint, expressed in characters (or in millimeters for a PDF file).
Examples To search the word "text" on a 8 1/2 x 11 page, the syntax is: data.find("text", 0, 216); Numbers 0 and 216 are in millimeters and indicate the left and right limits (constraints) within which the search should be. Values (0, 216) in this example represent the entire width of a page. Note that the smaller the area is, the faster the search is. So if you know that the word "text" is within 3 inches from the left edge of the page, provide the following: data.find("text", 0, 76.2); 76.2mm = 3*25.
findRegExp (regexpToFind, flags, leftConstraint, rightConstraint): rectValueText Finds the first occurrence of a string starting from the current position. regexpToFind Regular expression pattern to find. flags i: Enables case-insensitive matching. By default, case-insensitive matching assumes that only characters in the US-ASCII charset are being matched. Unicode-aware case-insensitive matching can be enabled by specifying the UNICODE_CASE flag (u) in conjunction with this flag. s: Enables dotall mode.
leftConstraint Number indicating the left limit from which the search is performed. rightConstraint Number indicating the right limit from which the search is performed. Examples data.findRegExp(/\d{3}-[A-Z]{3}/,"gi",50,100); or data.findRegExp("\\d{3}-[A-Z]{3}","gi",50,100);}} Both expressions would match the following strings: 001-ABC, 678-xYz.
getVariable() Method that retrieves the value currently stored in a variable. getVariable(varName) Retrieves the value currently stored in variable varName. If the variable does not exist, the value null is returned. It is considered good practice (almost mandatory, even!) to always check whether a variable is defined before attempting to access its value. varName String name of the variable from which the value is to be retrieved. Example moveTo() Moves the position of the pointer in the source data file.
With the scope set to 1 or steps.MOVEDELIMITERS, verticalPosition represents the index of the delimiter (as defined in the Input Data settings) to move to from the top of the record. With the scope set to 2, verticalPosition is not used. The position is moved to the next line after the current position that contains any text. Example The following line of code moves the current position in a text file 14 lines down from the current vertical position (steps.
moveTo(xPath) Moves the current position in a XML file to the first instance of the given node, relative to the top of the record. xPath String that defines a node in the XML file. Tip The XML elements drop-down (on the Settings pane, under Input Data) lists xPaths defining nodes in the current XML file. moveTo(row) Moves the current position in a CSV file to the given row number. row Number that represents the index of the row, relative to the top of the record.
l l l 0 or steps.MOVELINES: the current position is set to the next line. 1 or steps.MOVEDELIMITERS: the current position is set to the next delimiter (as defined in the Input Data settings). 2 (next line with content): the current position is set to the next line that contains any text. Example The following line of code moves the current position to the next line that contains any text. steps.moveToNext(2); XML scope Number that may be set to: l l 0 or steps.
set(delimiters) Sets a new DataMapper record boundary. Delimiters Sets a new record boundary. The delimiters parameter is an integer number representing an offset from the current delimiter. If this parameter is not specified, then a value of 0 is assumed. A value of 0 indicates the record boundary occurs on the current delimiter. A negative value of -n indicates that the Record boundary occurred -n delimiters before the current delimiter.
// Total is on an even page, set the document Boundary to the current delimiter boundaries.set(); } } } Note The above code could be completely rewritten as: if(boundaries.find("Invoice Total",region.createRegion(150,220,200,240).found) { (boundaries.currentDelim % 2) !=0 ? boundaries.set(1): boundaries.set(); } setVariable() Method that sets a variable to the specified value, automatically creating the variable if it doesn't exist yet.
Example Page 262
The Designer The Designer is a WYSIWYG (what you see is what you get) editor that lets you create templates for various output channels: Print, Email and Web. A template may contain designs for multiple output channels: a letter intended for print and an e-mail variant of the same message, for example. Content, like the body of the message or letter, can be shared across these contexts. Templates are personalized using scripts and variable data extracted via the DataMapper.
2. Fill the template Add text, images and other elements to the template and style them. See "Content elements" on page 385 and "Styling and formatting" on page 465. 3. Personalize the content Personalize the content using variable data. See "Personalizing Content" on page 499. 4. Generate output Adjust the settings, test the template and generate output: letters, emails, and/or web pages. See "Generating output" on page 813. 5. What's next Use Workflow to automate your customer communications.
"Snippets" on page 464. Snippets help share content between contexts, or insert content conditionally. "Styling and formatting" on page 465. Make your Designer templates look pretty and give them the same look and feel with style sheets. "Personalizing Content" on page 499. Personalize your customer communications using variable data. "Writing your own scripts" on page 528. Scripting can take personalization much further. Learn how to script via this topic. "Generating output" on page 813.
After creating a template you can add the other contexts (see "Contexts" on page 278), as well as extra sections (see "Sections" on page 280), to the template. It is, however, not possible to use a Template Wizard when adding a context or section to an existing template. Tip If an Email context is going to be part of the template, it is recommended to start with an Email Template Wizard; see "Creating an Email template with a Wizard" on page 320.
Auto Backup Connect Designer can automatically create a backup file when you manually save a template. To configure Auto Backup: 1. Select the menu option Window > Preferences > Save. 2. Under Auto backup, check the option Enable to activate the Auto Backup function. 3. Type the number of revisions to keep. 4. Select the directory in which the backups should be stored.
Sending files to Workflow Workflow can generate output from a template as well. For this, the template has to be sent to Workflow. The Send to Workflow dialog sends templates, Data Mapping Configurations and print presets to the Workflow server, or saves them as a package file.
Capture On The Go templates are a special kind of Web templates; see "Capture OnTheGo template wizards" on page 368. A Web Template Wizard helps you create a Web page that looks good on virtually any browser, device and screen size. Foundation All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon.
3. Click Next and make adjustments to the initial settings. l Section: l l l Description: Enter the description of the page. This is the contents of a HTML tag. Top bar group: l l l l Name: Enter the name of the Section in the Web context. This has no effect on output. Set width to Grid: Check this option to limit the width of the top bar contents to the Foundation Grid, instead of using the full width of the page.
l l A collection of Snippets in the Snippets folder on the Resources pane. The Snippets contain ready-to-use parts to build the web page. Double-click to open them. See "Snippets" on page 464 for information about using Snippets. Images: icons, one picture and one thumbnail picture. Hover your mouse over the names of the images in the Images folder on the Resources pane to get a preview.
tested across many browsers and devices, and works back as far as IE9 and Android 2. See http://foundation.zurb.com/learn/about.html and "Using Foundation" on page 372. Jumbotron The name of the Jumbotron template is derived from the large screens in sports stadiums. It is mostly useful for informative or marketing-based websites. Its large banner at the top can display important text and its "call to action" button invites a visitor to click on to more information or an order form.
Foundation All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first approach, so that websites built upon Foundation look good and function well on multiple devices including desktop and laptop computers, tablets, and mobile phones.
l l l l l l Event Registration. The Event Registration Template is a generic registration form asking for name, phone, email, etc. Event Feedback. The Event Feedback Template is a questionnaire containing different questions used to rate an experience. Membership Application. The Membership Application Template is a signed generic request form that can be used for memberships such as gyms, clubs, etc. Patient Intake.
l l Style sheets and JavaScript files related to the COTG form itself and others related to the Foundation framework (see above). The style sheets can be found in the Stylesheets folder on the Resources pane. The JavaScript files are located in the JavaScript folder on the Resources pane. A collection of snippets in the Snippets folder on the Resources pane. The snippets contain ready-to-use parts to build the web form. Double-click to open them.
Naturally, Web Form elements can also be used on COTG Forms (see "Forms" on page 444 and "Form Elements" on page 449) as well as text, images and other elements (see "Content elements" on page 385). Capture OnTheGo templates can be personalized just like any other type of template; see "Variable Data" on page 510 and "Personalizing Content" on page 499. Tip Use the Outline pane at the left to see which elements are present in the template and to select an element.
Once imported, internal resources are accessed using a relative path, depending where they're called from. Resources can be located in the following folders: l images/ contains the files in the Images folder. l fonts/ contains the files in the Fonts folder. l css/ contains the files in the StyleSheets folder. l js/ contains the files in the JavaScripts folder. l snippets/ contains the files in the Snippets folder.
Some limitations l l Style sheets cannot refer to external resources. The Connect Server user needs access to whichever network path is used. If the network path is on a domain, the Connect Server must be identified with domain credentials that have access to the domain resources. For more information on network paths, please see this Wikipedia entry: file URI scheme. Web resources Web resources are simply accessed using a full URL.
When a new template is made, the Context appropriate to that new template is automatically created, including one section. After a template has been created, the other two contexts can be added to it; see "Adding a context" below. Tip If an Email context is going to be part of the template, it is recommended to start with an Email Template Wizard; see "Creating an Email template with a Wizard" on page 320. After creating a template, contexts can be added to it, but that can not be done with a wizard.
Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored. After closing and reopening the template it is no longer possible to restore the deleted context this way. To prevent losing any work, it is recommended to configure the auto-save and autobackup functions in the preferences (see "Saving Preferences" on page 600).
Copying a section Copying a section, either within the same template or from another template, can only be done manually. You have to copy the source of the HTML file: 1. Open the section that you want to copy and go to the Source tab in the workspace. 2. Copy the contents of the Source tab (press Ctrl+A to select everything and then Ctrl+C to copy the selection). 3. Add a new section (see "Adding a section" on the previous page). 4.
Section properties Which properties apply to a section, depends on the context it is part of. See also: "Print sections" on page 292, "Email templates" on page 326, and "Web pages" on page 341. To change the properties for a section: l On the Resources pane, expand the Contexts folder, expand the folder of the respective context, right-click the name of the section, and then click one of the options.
can change the order of the sections in the same context by clicking the name of a section and moving it using the Up and Down buttons. Outputting sections Which sections are added to the output, depends on the type of context they are in. When generating output from the Print context, each of the Print sections is added to the output document, one after the other in sequence, for each record. The sections are added to the output in the order in which they appear on the Resources pane.
Email output" on page 830. When generating output from the Print context, each of the Print sections is added to the output document, one after the other in sequence, for each record.
Stationery (Media) When the output of a Print context is meant to be printed on paper that already has graphical and text elements on it (called stationery, or preprinted sheets), you can add a copy of this media, in the form of a PDF file, to the Media folder. Media can be applied to pages in a Print section, to make them appear as a background to those pages. This ensures that elements added to the Print context will correspond to their correct location on the preprinted media.
See "Print Template Wizards" below for information about the various types of Template wizards. 2. Make adjustments to the initial settings (the options for each type of template are listed below). Click Next to go to the next settings page if there is one. 3. Click Finish to create the template. See "Print context" on page 289 and "Print sections" on page 292 for more information about Print templates.
l l l Scripts and selectors for variable data. The Scripts pane shows, for example, a script called "first_name". This script replaces the text "@first_name@" on the front of the postcard by the value of a field called "first_name" when you open a data set that has a field with that name. See "Variable Data" on page 510. A script called Dynamic Front Image Sample. This script shows how to toggle the image on the front page dynamically. See also "Writing your own scripts" on page 528. One empty Media.
l Select Virtual Stationery: a PDF file with the letterhead stationery. Also see Media. When you click Finish, the Wizard creates: l l l l A Print context with one section in it; see "Print context" on the next page and "Print sections" on page 292. One empty Master Page. Master Pages are used for headers and footers, for images and other elements that have to appear on more than one page, and for special elements like tear-offs. See "Master Pages" on page 307. One Media.
By default, the PDF itself is added to the Image folder located in the Resources pane. Uncheck the option Save with template if the PDF should not be imported in the template. If not saved with the template, the image will remain external. Note that external images need to be available when the template is merged with a record set to generate output, and that their location should be accessible from the machine on which the template's output is produced.
Tip Editing PDF files in the Designer is not possible, but when they're used as a section's background, you can add text and other elements, such as a barcode, to them. To create a new Print template from a PDF file, use the PDF-based Print template (see "Creating a Print template with a Wizard" on page 285). To use a PDF file as background image for an existing section, see "Using a PDF file as background image" on page 296.
add Media and, optionally, print them. Initially, the (empty) media that has been created with the Print context, is applied to all pages in the Print section. You can add more Media and apply them each to different pages. l One Stylesheet, named context_print_styles.css, is added to the template, as you can see on the Resources pane, in the Stylesheets folder. This stylesheet is meant to be used for styles that are only applied to elements in the Print context.
Setting the binding style for the Print context The Print context , as well as each of the Print sections, can have its own Finishing settings. In printing, Finishing is the way pages are bound together after they have been printed. Which binding styles can be applied depends on the type of printer that you are using. To set the binding style of the Print context: 1. On the Resources pane, expand the Contexts folder, and right-click the Print context. 2. Click Properties. 3.
Pages Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally limited by their size and margins. If the content of a section doesn't fit on one page, the overflow goes to the next page. This happens automatically, based on the section's page size and margins; see "Page settings: size, margins and bleed" on page 301.
displayed on the Preview tab of the workspace, the Master Page being 'in front' of the Media and the Print section on top. To open the Preview tab, click it at the bottom of the Workspace or select View > Preview View on the menu. See "Media" on page 310 for a further explanation about how to add Media and how to apply them to different pages. Note: The Media will not be printed, unless this is specifically requested through the printer settings; see "Generating Print output" on page 816.
Note Via a Control Script, sections can be added to a Print context dynamically; see "Control Scripts" on page 545. Deleting a Print section To delete a Print section: l On the Resources pane, expand the Contexts folder, expand the Print context, rightclick the name of the section, and then click Delete. Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored.
Styling and formatting a Print section The contents of a Print section can be formatted directly, or styled with Cascading Style Sheets (CSS). See "Styling and formatting" on page 465. In order for a style sheet to be applied to a specific section, it needs to be included in that section. There are two ways to do this. Drag & drop a style sheet 1. Click and hold the mouse button on the style sheet on the Resources pane. 2.
2. Click the downward pointing arrow after Image and select either From Datamapper input or From PDF resource. From Datamapper input uses the active Data Mapping Configuration to retrieve the PDF file that was used as input file, or another type of input file, converted to a PDF file. With this option you don't need to make any other settings; click OK to close the dialog. 3. For a PDF resource, you have to specify where it is located. Click the Select Image button.
and the Left field to specify the distance between the left side of the page and the left side of the PDF. 5. Optionally, if the PDF has more than one page, you can set the range of pages that should be used. Note The number of pages in the Print section is automatically adjusted to the number of pages in the PDF file that are being used as the section's background image. 6. Finally, click OK.
Overriding binding styles in a job creation preset A Job Creation Preset can override the binding styles set for the Print sections and for the Print context as a whole. To bind output in another way than defined in the template’s settings: 1. Create a Job Creation Preset that overrides the settings of one or more sections: select File > Presets and see "Job Creation Presets" on page 714 for more details. 2. Select that Job Creation Preset in the Print wizard; see "Generating Print output" on page 816.
Pages Unlike emails and web pages, Print sections can contain multiple pages. Pages are naturally limited by their size and margins. If the content of a section doesn't fit on one page, the overflow goes to the next page. This happens automatically, based on the section's page size and margins; see "Page settings: size, margins and bleed" on the next page.
When it comes to positioning elements on a page, Guides can be useful, as well as Tables. See "How to position elements" on page 478. Page settings: size, margins and bleed On paper, whether it is real or virtual, content is naturally limited by the page size and margins. These, as well as the bleed, are set per Print section, as follows: l On the Resources pane, right-click a section in the Print context and click Properties.
1. Import the promotional image or snippet; see "Images" on page 453 and "Snippets" on page 464. 2. Insert the promotional image or snippet in the content. Note l l Only a top-level element (for example, a paragraph that is not inside a table or div) can function as a whitespace element. Do not place the promotional image or snippet inside an absolute positioned box. Whitespacing only works for elements that are part of the text flow, not for absolute-positioned boxes. 3.
l l l l Content page number: The current page number in the document, counting only pages with contents that are supplied by the Print section. A page that has a Master Page (as set in the Sheet Configuration dialog, see "Applying a Master Page to a page in a Print section" on page 309) but no contents, is not included in the Content page count. Content page count: This is the total number of pages in the current document that have contents, supplied by the Print section.
Note Even if a section is disabled, so it doesn't produce any output, this setting is still taken into account for the other sections. This means that if Restart Numbering is checked on a disabled section, the page numbering will be restarted on the next section. Disabling a section can only be done in a Control Script (see "Control Scripts" on page 545). Control Scripts can also change where page numbers restart. 3.
1. On the menu, select Edit > Stylesheets. 2. Select the Print context. 3. Click New (or, when there are already CSS rules for paragraphs, click the selector p and click Edit). 4. Click Format. 5. After Widows and Orphans, type the number of lines that should be considered a widow or orphan (this amounts to the minimum number of lines that may be separated from a paragraph, minus one). Alternatively, manually set the set the widows and orphans properties in a style sheet: 1.
3. Click New (or, when there are already CSS rules for tables, click the selector table and click Edit). 4. Click the Advanced button. 5. Add a rule for widows and/or orphans, typing the name of the CSS property in the left column and the value in the right column. 6. Close the dialogs. Page breaks A page break occurs automatically when the contents of a section don't fit on one page.
l Select the element (see "Selecting an element" on page 389). l On the Format menu, select the respective element to open the Formatting dialog. l In the Breaks group, set the inside property to avoid, to prevent a page break inside the element. This is equivalent to the page-break-inside property in CSS; see CSS pagebreak-inside property for an explanation of all available options.
l A tear-off section on the first page of an invoice. Adding a Master Page When a Print template is created, one master page is added to it automatically. Adding more Master Pages can be done as follows: l On the Resources pane, right-click the Master pages folder and click New Master Page. l Type a name for the master page. l l Optionally, set the margin for the header and footer. See "Master Pages" on the previous page. Click OK.
Adding a header and footer Headers and footers are not designed as part of the contents of a Print section, but as part of a Master Page, which is then applied to a page in a print section. To create a header and footer: 1. First insert elements that form the header or footer, such as the company logo and address, on the Master Page; see "Editing a Master Page" on the previous page. 2. Next, define the margins for the header and footer.
check Tumble to duplex pages as in a calendar, and Facing pages to have the margins of the section switch alternately, so that pages are printed as if in a magazine or book. 3. If the option Same for all positions is checked, the same Master Page will be applied to every page in the print section (and to both the front and the back side of the page if duplex printing is enabled). Uncheck this option. 4.
Per Media, a front and back can be specified and you can specify on what kind of paper the output is meant to be printed on. This includes paper weight, quality, coating and finishing; see "Adding Media" below. Adding Media To add a Media, right-click the Media folder on the Resources pane and select New Media. The new Media is of course empty. You can specify two PDF files for the Media: one for the front, and, optionally, another for the back.
l l l Resources lists the PDF files that are present in the Images folder on the Resources pane. Disk lets you choose an image file that resides in a folder on a hard drive that is accessible from your computer. Click the Browse button to select an image. As an alternative it is possible to enter the path manually. The complete syntax is: file:///. Note: if the host is "localhost", it can be omitted, resulting in file:///, for example: file:///c:/resources/images/image.jpg.
1. On the Resources pane, expand the Contexts folder, expand the Media folder, and right-click the Media. Click Characteristics. 2. Specify the paper's characteristics: l l l l l l l Media Type: The type of paper, such as Plain, Continuous, Envelope, Labels, Stationery, etc. Weight: The intended weight of the media in grammage (g/m2). Front Coating: The pre-process coating applied to the front surface of the media, such as Glossy, High Gloss, Matte, Satin, etc.
1. On the Resources pane, expand the Print context; right-click the Print section, and click Sheet configuration. 2. Optionally, check Duplex to enable content to be printed on the back of each sheet. Your printer must support duplex for this option to work. If Duplex is enabled, you can also check Tumble to duplex pages as in a calendar, and Facing pages to have the margins of the section switch alternately, so that pages are printed as if in a magazine or book. 3.
Media 1 will have been replaced with the name of the media selected for the chosen sheet position. The field Selector in the Script Wizard contains the name of the section and the sheet position that you have chosen. 4. Change the script so that on a certain condition, another media will be selected for the content. For instance: if(record.fields.GENDER === 'M') { results.attr("content","Media 2"); } This script changes the media to Media 2 for male customers.
Email template It is strongly recommended to start creating an Email template with a Wizard; see "Creating an Email template with a Wizard" on page 320. Designing HTML email that displays properly on a variety of devices and screen sizes is challenging. Building an email is not like building for the web. While web browsers comply with standards (to a significant extent), email clients do not. Different email clients interpret the same HTML and CSS styles in totally different ways.
Designing an Email template With the Designer you can design Email templates. It is strongly recommended to start creating an Email template with an Email Template Wizard, because it is challenging to design HTML email that looks good on all email clients, devices and screen sizes that customers use when they are reading their email.
Email templates: Slate and others The most obvious solution offered in the Designer is to use one of the templates provided with the Designer; see "Creating an Email template with a Wizard" on page 320. The layout of these templates has been tested and proven to look good in any email client, on any device and screen size. The Tables in these templates are nested (put inside another table) and they have no visible borders, so readers won't notice them.
To learn more about Emmet, please see their website: Emmet.io and the Emmet.io documentation: http://docs.emmet.io/. Preferences To change the way Emmet works in the Designer, select Window > Preferences, and in the Preferences dialog, select Emmet; see "Emmet Preferences" on page 596. Using CSS files with HTML email Email clients do not read CSS files and some even remove a
