User Guide Version: 1.
User Guide Version 1.5 Last Revision: 2017-04-12 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 PReS Connect 1.
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 Left Operand Condition Operators JavaScript Defining Boolean Values Boolean Expressions Defining Stri
Examples of masks Entering a date using JavaScript Example Defining Object Values Toolbar Shortcut Keys Welcome Screen DataMapper Scripts API Objects Functions Methods Write Your Own Scripts Boundaries Using JavaScript Objects Functions Methods The Designer Basic Steps Templates Contexts Sections Features Print Pages Headers, footers, tear-offs and repeated elements (Master page) Stationery (Media) Creating a Print template with a Wizard Print context Print sections Pages Master Pages Media Email Designing
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 How to position elements Styling text and paragraphs Background color and/or image Border Colors Fonts Spacing Styling a table Rotating elements Locale Personalizing content Variable data Conditional content Dynamic images Dynamic tables Snippets Scripts Loading data Variable Data Formatting variable data S
Writing a script Managing scripts Testing scripts Optimizing scripts Loading a snippet via a script Control Scripts Designer User Interface Dialogs Menus Panes Toolbars Welcome Screen Print Options Job Creation Presets Output Creation Settings Designer JavaScript API Designer API Control Script API Designer Scripts API Control Script API Generating output Print output Email output Web output Optimizing a template Scripts Images Generating Print output Saving Printing options in Printing Presets.
Generating Email output Email output settings in the Email context and sections Generating Email output from Connect Designer Generating Email output from Workflow Email attachments Using an ESP with PReS Connect Generating Web output Attaching Web output to an Email template Generating Web output from Workflow Web output settings in the Web context and sections Print Manager 812 813 814 815 816 817 822 823 824 824 826 Print Manager Introduction Video Print Manager usage Print Manager Interface Menu optio
Welcome to PReS Connect 1.5 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, or visit the online help: help.objectiflune.com and use the feedback tool at the bottom of the page. PReS Connect is a series of four tools designed to optimize and automate customer communications management.
Icons used in this guide Icons are used throughout this guide to point your attention to certain information. Note Complementary information that is not critical, but may help you better use PReS Connect. Tip Information that is useful or suggests an easier method. Technical Information that may require specific knowledge to understand. Warning Information that is potentially critical to using PReS Connect. Pay close attention.
Setup And Configuration This chapter describes the PReS Connect installation and the different considerations that are important in regards to the installation and use of PReS Connect. l "System and Hardware Considerations" below l "Installation and Activation" on page 23 l "Server Settings" on page 44 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 PReS Connect. Minimum Hardware Requirements l NTFS Filesystem (FAT32 is not supported) l CPU Intel Core i7-5960X @ 3.00GHz (8 core with Hyper-Threading) l 16GB RAM l Disk Space: At least 10GB (20GB recommended) Note For tips and tricks on performance, see "Performance Considerations" on page 21.
time. Terminal Server/Service PReS Connect does not support Terminal Server (or Terminal Service) environment as possible under Windows 2000, 2003 and 2008. This is to say, if Terminal Service is installed on the server where PReS Connect is located, unexpected behaviours may occur and will not be supported by Objectif Lune Inc.. Furthermore, using PReS Connect in a Terminal Service environment is an infringement of our End-User License Agreement.
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 PReS Connect is intended to work stably and reliably, based on Java and the Eclipse framework. To ensure this reliability and robustness, many Java and Eclipse parameters have been tested and tuned, which is reflected in the respective .
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 PReS Connect will be able to be stored within the database. character-set-server = utf8 , collation-server = utf8_unicode_ci , default-characterset=utf8 : These indicate database support for UTF-8/Unicode.
l On Update from 1.4.2 or earlier, the DB Configuration Page will always default to MySQL connection settings, and if the installation was manually tweaked to connect to MS SQL Server, the user has to switch to "Microsoft SQL Server" type and enter connection details again. Installing / Updating Connect Using a Local MySQL l l l The Configuration page for the local MySQL is displayed. MySQL settings are pre-filled with default values if no existing MySQL db configuration is found.
Note If Connect was initially installed not containing the local MySQL product (i.e. on 1.5 installation an external MySQL was configured as database), then the Update to 1.6 will allow to select either external MySQL or external Microsoft SQL on the DB Configuration Page.
The PReS 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 PReS Connect on a non-English operating system. These are due to encoding issues and will be addressed in a later release. Performance Considerations This page is a comprehensive guide to getting the most performance out of PReS Connect as well as a rough guideline to indicate when it's best to upgrade.
of used memory in the machine should be pretty much the maximum available (around 95%). For each engine, it's necessary to modify the .ini file that controls its JAVA arguments. Edit as follows: l l l l For the Merge Engine: see C:\Program Files\Objectif Lune\OL Connect\MergeEngine\Mergeengine.ini For the Weaver Engine: see C:\Program Files\Objectif Lune\OL Connect\weaverengine\Weaverengine.ini The parameters are -Xms640m for the minimum RAM size, -Xmx640m for the maximum RAM size.
web are about JavaScript in the browser, but the greatest majority of the tips do, indeed, apply to scripts in general, wherever they are used. High-Performance Hardware The following is suggested when processing speed is important. Before looking into a Performance Packs to enhance performance, ensure that the below requirements are met. l l l l A physical, non-virtualized server.
PReS Connect 1.5 is comprised of 2 different installers: one for the PReS Connect software and one for PReS Workflow 8. Where to Obtain the Installers: The installers for PReS Connect 1.5 and PReS Workflow 8 can be obtained on DVD or downloaded as follows: l l If you are a Customer, the installers can be downloaded from the Objectif Lune Web Activations page: http://www.objectiflune.
Simply click on the download button in the dialog to install the new version of the Update Client. Note that it is no problem to run the update while the Client is open. It will automatically update itself. Once you have done this, PReS Connect 1.5 will become available for download. Note From PReS Connect Version 1.2 onwards, the new version (1.1.8) of the Update Client is included by default with all setups.
The account must have administrative access on the machine. It should also correspond to the user account set up in PReS Worfklow. The Importance of User Credentials on Installing and Running PReS Connect OL Connect and required credentials depends heavily on the Connect component and respective tasks and what sort of user credentials are needed.
different from the credentials of the installation user account, which additionally requires the right to INSTALL services. Please be aware of this fact! Additionally, the Server user must be able to access any network resources that are required for OL Connect to function properly. This includes e.g.
Installing PReS Connect on Machines without Internet Access Installing PReS Connect1.5 in offline mode requires some extra steps. These are listed below. GoDaddy Root Certificate Authority needs to be installed. In order to install PReS Connect it is necessary for the GoDaddy Root Certificate Authority to be installed (G2 Certificate) on the host machine and for this to be verified online.
To circumvent such issues it is highly recommended to switch off the CRL retrieval prior to installing Connect on machines without internet access. There is no security risk associated with this, as the CRLs would never be retrievable without internet access, anyway. Advantage of the switch will not only be found during the installation and operation of Connect, but also in some speed improvements for any application which use signed binaries.
l l l l l l PReS Connect Designer: The Designer module. It may be used as a standalone with no other installed modules, but it will not have certain capabilities such as automation and commingling. PReS Connect Print Manager: The Print Manager module required for handling IPDS print output, as also available for managing PCL and PostScript output. PReS Connect Server: The Server back-end giving capabilities such as automation, commingling, picking.
l Source repository location: Displays the path where the installation files are located. This can be a local drive, installation media, or a network path. Selection Confirmation The next page confirms the installation selections made. Click Next to start the installation itself. End User License Agreement The next page displays the End User License Agreement, which needs to be read and accepted before clicking Next.
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. A check is run to confirm whether the specified TCP\IP Port Number is available on the local machine. If it is already being used by another service (generally, an existing MySQL installation), the number is highlighted in red and a warning message is displayed at the top of the dialog.
l l l l l l Administrator Username: Enter the username for a user with administrative rights on the database. Administrative rights are required since tables need to be created in the database. If accessing a database on a different machine, the server must also be able to accept non-local TCP connections, and the username must also be configured to accept remote connection.
Note The "Server Security Settings" on page 44 dialog can only ever be executed from the user specified here. l l l Username: The account that the service uses to login. If the machine is on a domain, use the format domain\username. This account must be an existing Windows profile with local administrator rights. Password: The password associated with the selected user.
the Connect Master Server. To do so, follow the Binding and Root access on the Master server instructions in Server_Clustering. This page defines the settings which are to be used to connect to that Connect Master Server. l Username: The account that the service uses to login. If the machine is on a domain, use the format domain\username. This account must be an existing Windows profile with local administrator rights.
l Validate Connection button: Click to verify that the entered username and password is correct and the service is able to login. This button must be clicked and the user validated for the Next button to be available. Click Next to start the actual installation process. This process can take several minutes. Completing the installation This screen describes a summary of the components that have been installed. l l l Configure Update Check checkbox: This option is enabled by default.
Product Activation After installation, it is necessary to activate the software. See Activating your license for more information. Technical Before activating the software, please wait 5 minutes for the database to initialize. If the software is activated and the services rebooted too quickly, the database can become corrupted and require a re-installation.
Required and Optional Properties Here is an example of an install.properties file. # Verbose logging logging.verbose = true # Product selection install.product.0 = Connect Designer install.product.1 = Connect Server # Server settings server.runas.username = Localadmin server.runas.password = admin # Database configuration database.type = mysql database.host = 192.168.116.10 database.port = 3308 database.username = root database.password = admin database.
However, it is possible to define the products to be installed using their visible product names, and using a counter for the install.product property, e.g. l install.product.0 = Connect Designer l install.product.1 = Connect Server Other possible product names are Connect Print Manager, Connect Server Extension and MySQL Product.
Optionally, the "schema" name can be defined (the default is objectiflune): l database.schema Activating a License PReS Connect and PReS Workflow 8 includes separate 30 day trial periods during which it is not necessary to have a license for reviewing basic functionality. If a modification to the license if required, such as to allow an extension to the trial period, or for extra functionality or plugins (e.g., the PReS Plugin for Workflow 8), then a new activation code will need to be requested.
l l l l l l l 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 Expiration Date: Displays the date when the activation will expire (or the current date if the product is not activated) License: This box displays the EULA. Please note that this agreement is legally binding. I agree: Select to accept the EULA. This option must be selected to install the license.
Note that if you do not have a serial number, one will be issued to you by the OL Activations team. Accepting the license will activate it, after which the PReS Connect services will need to be restarted. Note that in some case the service may not restart on its own. To resolve this issue, restart the computer, or start the service manually from the computer's Control Panel. Activating PReS Workflow 8 PReS Workflow 8 uses the same licensing scheme as PReS Connect.
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 PReS Connect installation to another. Instructions for migration will be available for later versions of the software when those tools become available.
PlanetPress Workflow can on the same machine simultaneously, whatever version is installed. l It is possible to switch between different versions running by shutting down one version's services and then starting the other. However, this is not recommended. There are no technical limitations that prevent processes from previous PlanetPress Workflow versions (as far back as Version 4) to run on PReS Workflow 8, removing the need to run both versions.
l l Confirm password: Re-enter the password for the server security. Default session length (min): Enter a session time (in minutes) that the authentication stays valid for the requested process. This can reduce the number of requests to the server since an authentication request is not necessary during the session. Server Extension Settings This dialog controls the different settings for the PReS Connect Server Extension.
3. Grant access to the MySQL root user for the appropriate IP range on the Master server. 4. Restart the MySQL Service on the Master server. 5. Install Slave servers (PReS Connect Server Extension module). 6. Install the license on the Master server (a Performance Pack license is required). 7. Set the preferences for the engines (see Scheduling Preferences) on both the Master and Slaves 8. Install the license on the Slave servers 9. Restart the Master server then, once restarted, restart the Slave servers.
Tip Navigate to the folder, SHIFT+Right-click, and then select "Open a command prompt here". l l Type in the following command to connect to the database, where is your MySQL password (by default it is admin): mysql --user=root --password= objectiflune You should see the prompt become mysql>. Here, type the command to allow the "root" user to be accessed from a specific IP subnet range. For example, to accept communication on 192.168.*.*, use: GRANT ALL PRIVILEGES ON objectiflune.
l l l If the number of expected remote engines is lower than the actual number, performance will not be optimal. If the number of expected remote engines is higher than the actual number, jobs may fail and not complete. Cleanup Service requires special configuration on Clustering setups: l l Cleanup service should not run simultaneously on all machines (staggered cleanup). Doing so may cause jobs not to be processed since all servers are busy.
Note The PReS Connect Setup Wizard might take some seconds to appear. Important Note: Stop any Anti-Virus Software before uninstalling Connect. Some anti-virus systems are known to block the uninstallation of MySQL datafiles, as well as blocking the uninstallation of the MySQL database application itself. Therefore it is highly recommended that any anti-virus application be stopped prior to uninstalling PReS Connect, as otherwise the Connect uninstallation might not work correctly.
l l Backup Connect Workspace Data for all specified Users: Check this box to backup the Workspace data for the specified users (as previously determined) into a compressed ZIP file (whose location can be customized), before deletion of the full Workspace data. Delete MySQL objectlune Data: Check this box to delete the MySQL database installed with PReS Connect.
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.
From the Welcome screen 1. Open the PReS ConnectWelcome page by clicking the icon at the top right or select the Help menu and then Welcome. 2. Click Create a New Configuration. 3. From the From a file pane, select the file type (CSV, MS-Access, PDF/VT, Text or XML). 4. Click the Browse button and open the file you want to work with (for a database, you may have to enter a password). 5. Click Finish. From the File menu 1. Click the File menu and select New. 2.
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 PReS ConnectWelcome page by clicking the the Help menu and then Welcome. icon at the top right or select 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.
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 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 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 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 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.
See: l Menus l Toolbars l Steps Pane l Step Properties Pane l Data Model Pane l Data Viewer l Messages Pane l Settings Pane Menus The following menu items are shown in the DataMapper Module's menu: Page 107
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. Close: Close the currently open data mapping configuration or Template.
Edit Menu l Undo: Undoes the previous action. l Redo: Redoes the last action that was undone. l l l l Cut Step: Removes the currently selected step and places it in the clipboard. If the step is a Repeat or a Condition, all steps under it are also placed in the clipboard. If there is already a step in the clipboard, it will be overwritten. Copy Step: Places a copy of the currently selected step in the clipboard. The same details as the Cut step applies.
l l l l l l Add Goto Step: Adds a Goto step that moves the selection pointer to the beginning of the data selection. For instance if an XML node is selected, the pointer moves to where that node is located. Add Condition Step: Adds a condition based on the current data selection. The "True" branch gets run when the text is found on the page. Other conditions are available in the step properties once it has been added.
l l 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. Help Topics: Click to open this documentation. Contact Support: Click to open the Objectif Lune Contact Page in the default system Web browser. l About PReS Connect Designer: Displays the software's About dialog.
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. There are some specific tricks and limitations, however: l l l l l If no Extract step is currently selected in the Steps Pane, a new Extract step is created. If an Extract step is selected, new Extract Fields are added to this existing step.
l 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. Add a table: Click to add a new table at the current level (record or existing table). Enter the table name in the dialog and click OK to add it. Rename: Click to rename the selected table or field. Enter the new name and click OK to rename. Only available for empty Data Model Fields (see below) tables that only contain them.
Record Navigation Records can be navigated directly from the Data Model Pane. The default Record level navigates between records both in the Data Model pane and the Data Viewer, while each table has a similar navigation that influence that table and each under it. l l l l l l l l Expand/Contract: Click to hide or show any fields or tables under the current table level. Table Name: Displays the name of the table as well as the number of records at that level (in [brackets]).
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 (*). If overwriting an existing data model, existing data model fields that are not in the imported data model file will have their asterisks removed.
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 PReS 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 119
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 124
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 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.
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. The Data Viewer itself is surrounded by two different areas: the toolbar at the top and the data map on the left. The toolbar is used to control a few options in the viewer. For example, with a text file Data Source, the font displaying the text can be changed. A button can also hide the data map, and zoom controls are also available.
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. To actually use the data selection instead of moving it, use the drag icon at the right of the selection and drag it into the Data Model pane to create an extraction.
l l l l Hide/Show line numbers the left of the Data Viewer. (Text file only): Click to show or hide the line numbers on Hide/Show datamap : Click to show or hide the icons to the left of the Data Viewer which displays how the steps affect the line. Hide/Show extracted data : Click to show or hide the extraction selections indicating that data is extracted. This simplifies making data selections in the same areas and is useful to display the original data.
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. Drag and drops from the Viewer window to the Data Model pane can be performed to extract data.
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.
the PReS 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. This value is overwritten by the actual value coming from PReS Workflow when the data mapping configuration is run using the Execute Data Mapping task.
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 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. Please refer to ...(link to come) for more information. 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 l l Use JavaScript Editor: Click to display the Script Editor dialog. Trim: Select to trim empty characters at the beginning or the end of the field. Type: The data type of the selected data. Please refer to ...(link to come) for more information.
l l l Remove Extract Field: Click to delete the selected extract field from the list. l Order and rename fields: Click to openOrdering and Renaming Fields. 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.
l l Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected. l Type: The data type of the selected data. Please refer to ...(link to come) for more information.
l l l Treat empty as 0: Considers empty spaces as 0. Currency l l l l l l Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") 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 (.).
If you intend to use the field names as metadata in a PReS Workflow process, do not add spaces to field names, as they are not permitted in metadata field names. l Value: Displays the value of the extract field in the current Record. l Remove button : Click to remove the currently selected field. l Move Up button : Click to move the selected field up one position. l Move Down button : Click to move the selected field down one position.
l Property: Displays a list of Source Record properties set in the Preprocessor Step. l Type: Displays the type of the Source Record property. Read only field. l Based on: Determines the origin of the data. l Location: The contents of the data selection set below will be the value of the extracted field. The data selection settings are different depending on the data sample type.
l l l More features to come in future versions. For more information, see JavaScript in DataMapper. Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Use selection: Click to use the value of the current data selection for the extraction. Note If the selection contains multiple lines, only the first line is selected.
l l l Treat empty as 0: Considers empty spaces as 0. Currency l l l l l l Thousand Separator: Adds the selected character between each thousand position (for example, "1,000,000") 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 (.).
l l l Column: Drop-down listing all fields in the Data Sample, of which the value will be used. Top offset: The vertical offset from the current pointer location in the Data Sample (Viewer). Use selection: Click to use the value of the current data selection for the extraction. 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.
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 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. Language: The language in which the date is written, when relevant.
Note If the selection contains multiple lines, only the first line is selected. Repeat Step Properties The Repeat step is a loop that runs more than once. There are multiple types of repeat steps used for different actions. 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. By default, if an Extract step is added within a Repeat step, its extraction is made in a Details Table.
Note When using an XML For Each loop, it is not necessary to skip to the repeating node or to have a Gotostep to jump to each sibling, as this loop takes care of it automatically. l Maximum iterations on each line: Defines the maximum number of iterations occurring at the same position. This expression is evaluated once when entering the loop. The value returned by the expression must be an integer higher than 0. l Use JavaScript Editor: Click to display the Edit Script dialog.
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. Technical Both the Left and Right operands have the same properties. Text and PDF Files l Based On: l Position: The data in the specified position for the comparison.
l l l l l l Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used. Data Property: The value of a data-level property set in the Preprocessor Step. Record Property: One of the local variables that you can create and that are reset for each document as opposed to data variables that are global because they are initialized only once at the beginning of each job.
l Position: The data in the specified position for the comparison. l l l l l l l l l l Trim: Select to trim empty characters at the beginning or the end of the field. Value: The text value to use in the comparison. Use selected text: Uses the text in the current data selection as the Value. If multiple lines or elements are selected, only the first one is used. Field: The Extracted Record field to use in the comparison. JavaScript : The result of a JavaScript Expression.
l 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 JavaScript : The result of a JavaScript Expression. l l l l l l l 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. If multiple lines or elements are selected, only the first one is used. Data Property: The value of a data-level property set in the Preprocessor step.
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.
Condition First, the Condition List displays the conditions in list form, instead of the tree form above. Three buttons are available next to the list: l Add condition: Click to create a new condition in the list. 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.
l Value: A specified static text value. l l l l l l l l Expression: The JavaScript line that is evaluated. Note that the last value attribution to a variable is the one used as a result of the expression. Use JavaScript Editor: Click to display the Edit Script dialog. Use selected text: Inserts the text in the current data selection in the JavaScript Expression. If multiple lines or elements are selected, only the first one is used.
l l is empty: The first specified value is empty. With this operator, there is no second value. Invert condition: Inverts the result of the condition. For instance, is empty becomes is not empty. Goto Step Properties The Goto step moves the pointer within the data sample to a specific position or one that is relative to the current position. 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.
l l Move by: Enter the number of lines or pages to jump. Next line with content: Jumps to the next line that has contents, either anywhere on the line or in specific columns. l Inspect entire page width: When checked, the Next line with content and Next occurrence of options will look anywhere on the line. If unchecked, options appear below to specify in which area of each line the Gotostep checks in: l Left: The starting column, inclusively. l Right: The end column, inclusively.
l Physical distance: 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 distance to jump. Page: Jumps between pages or to a specific page. l l l From: Defines where the jump begins: From: Defines where the jump begins: l Current Position: The Gotobegins at the current cursor position. l Top of record: The Gotobegins at line 1 of the source record. Move by: Enter the number pages to jump.
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.
Postprocessor Properties The Postprocessor step does not run for every Source Record in the Data Sample. It runs once, at the end of the Steps, after all records have been processed. Postprocessor The Postprocessor subsection defines what postprocessors run on the Data Sample at the end of the data mapping workflow. Each Postprocessor runs in turn, using the result of the previous one as an input. l Name: The name to identify the Postprocessor. l Type: The type of Postprocessor.
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.
When you select a specific data type, it converts it into a native type. If the date inside the Data Source was in a different format (Canadian format, Japanese format, etc.), the source shows that different format. But inside the Data Model, it will always be shown as "year month day" and the time. Here are the data types available in all modules of PReS Connect.
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. Defining Boolean Values l l l Pre-Processor: Specify the "Type" as "Boolean" and set a default value of either true; or false; Extraction: Specify the "Type" as "Boolean".
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. Defining String Values l l l Pre-Processor: Specify the "Type" as "String" and set a default value as any text between quotes, such as "This is my text"; Extraction: Specify the "Type" as "String". The field value will be extracted and treated as a string. JavaScript Expression: Set the desired value to any string between quotes. Example: record.
HTML String Data Type HTML Strings contain textual data that includes HTML Markup. They are essentially the same as String values except in cases where HTML can be treated differently. For instance, when using a script to place an HTML String field into a template, the contents will be HTML instead of plain text. Example: Assuming a value of "He said WOW!"; , if the data type is String and placed on the page, it will display exactly as "He said WOW!" (without the quotes).
l 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. For more advanced mathematical functions, see w3schools - Math Object. Note When adding numbers that are not integers, for instance 4.5 + 1.2 , a round towards zero rounding is applied after the operation was made. In the previous example, the result, 5.7, is rounded to 5.
calculations: it is as precise as integers. Defining Currency Values l l l Pre-Processor: In the step properties selection under Properties specify the "Type" as "Currency" and set a default value as a number with up to 4 decimal points, such as 546513.8798 Extraction: In the step properties under Field Definition specify "Type" as "Currency" and configure how the value will be read from the Source Record (see Extract Step). The field value will be extracted and treated as a float.
Extracting dates To extract data and have that data interpreted as a Date, set the type of the respective field to Date: 1. Select the field in the data model. 2. On the Step properties pane, under Field Definition, specify the Type as Date. 3. Next, under Data Format, specify the Date/Time Format. This format must match the way the date is formatted in the source data; otherwise the data cannot be interpreted as a Date.
l l ap: AM/PM string. In addition, any constant character can be included in the mask, usually to indicate date/time separators (i.e. / - :) . If one of those characters happens to be one of the reserved characters listed above, it must be escaped using the \ symbol. Note The markers that can be used when extracting dates are different from those that are used to display dates in a template (see "Date and time patterns" on page 748).
l In a Preprocessor property. To do this, go to the Steps pane and select the Preprocessor step. Then, on the Step properties pane, under Properties add a property, specify its Type as Date and put the JavaScript in the Default Value field. The use of the JavaScript Date() object is necessary when creating dates through a JavaScript expression. For more information, see w3schools - JavaScript Dates and w3schools - Date Object.
l Save : Saves the current data mapping configuration. If the configuration has never been saved, the Save As... dialog is displayed. 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 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 l l l l Paste Step : Takes the step or steps in the clipboard and places them after the currently selected step. Delete Step : Deletes the currently selected step. If the step is a Repeat or Condition, all steps under it are also deleted. 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.
l The Welcome Screen button in the Toolbars. l From the Menus in Help, Welcome Screen. Contents l Activation: Click to open the Objectif Lune Web Activation Manager. l Release Notes: Opens the current Release Notes for PReS Connect. l Website: Opens the PReS Connect website. l Take A Tour: Click to open the YouTube Playlist giving you a tour of the software. l Use the DataMapper to...
DataMapper Scripts API This page describes the different features available in scripts created inside DataMapper. See "Write Your Own Scripts" on page 210. Objects Name Description Available In automation Returns a ScriptableAutomation object encapsulating the properties of the PReS Workflow process that triggered the current operation.
Name Description Available In sourceRecord Returns a source record object containing properties specific to the current source record being processed. Boundaries, all Steps except Goto and Postprocessor steps Returns a steps object encapsulating properties and methods pertaining to the current DataMapper process. Extract, Condition, Repeat and Multiple Conditions Steps Functions Name Description Available In copyFile() Copies a file to the target file path, replacing it if it already exists.
Name Description Available In newLongArray() Returns a long array. Boundaries, Steps newStringArray() Returns a string array. Boundaries, Steps openBinaryReader () Opens a file as a binary file for reading purposes. Boundaries, Steps 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.
Name Description Object Related Available In File Type currentPosition() Returns the current position of the pointer in the data. steps Extract, Condition, Repeat, and Action steps all 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.
Name Description Object Related Available In File Type extractMeta() Method that extracts the value of a metadata field. data Extract, Condition, Repeat, and Action steps all fieldExists() Method that returns True if metadata field exists. data Finds the first occurrence of a string starting from the current position. data and boundaries found() Method that returns a Boolean value indicating whether the last call to find() was successful.
Name Description Object Related Available In File Type moveLines() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. steps Extract, Condition, Repeat, and Action steps Text moveDelimiters() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. steps Extract, Condition, Repeat, and Action steps Text moveMeasure() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Name Description Object Related Available In File Type moveTo() and moveToNext() methods. moveSibling() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. steps Extract, Condition, Repeat and Multiple Conditions Steps XML moveTo() Moves the current position to a number. steps Extract, Condition, Repeat and Action steps all moveToNext() Moves the current position to the next instance of a number.
Name Description Object Related Available In File Type 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. steps Extract, Condition, Repeat, and Action steps Text and PDF Write Your Own Scripts Data mapping can be taken a lot further than just performing basic extractions.
l l l Extraction step where the data selection is based on JavaScript or you can enter a post function script. Action step using the set properties based on JavaScript or you can use JavaScript run script. Condition step where the left and right operands are based on JavaScript. See Step Properties for more information. From the Settings or from the Step Properties pane, click the Use JavaScript Editor button.
Syntax Rules Every script in the DataMapper must follow JavaScript syntax rules. For example, each statement should end with ; and the keywords that can be used, such as var to declare a variable, are JavaScript keywords. There are countless tutorials available on the Internet to familiarize yourself with the JavaScript syntax. For a simple script all that you need to know can be found on the following web pages: https://developer.mozilla.org/enUS/docs/Web/JavaScript.
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. Instead, it should terminate as soon as any condition it's evaluating is false. Data available inside each event Every time the event is triggered, it has access to the entire data between the current location and the next delimiter. So if you are just beginning the process for a PDF or text file, you have access to the first page only.
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.
changes, then you'd get the first four lines together inside a single record, but that's not what you want since that would include albums from several different artists. And if you were to set it when the "Artist" field changes, then the first few records would be OK but near the end, you'd get both the Led Zeppelin 3 and led Zeppelin 4 albums inside the same record, even though they were released on different years. So that's no good either.
there have been none yet. But if they have already been initialized, then a condition checks if either field has changed since last time. If that's the case, then a boundary is created through the set() method. l Finally, the script stores the values it just read in the variables using the setVariables() method. They will therefore become the "last values encountered" until the next event gets fired.
values if (boundaries.getVariable("lastBand")!=null) { if ( zeBand[0]!=boundaries.getVariable("lastBand") || zeYear[0]!=boundaries.getVariable("lastYear") ) { boundaries.set(); } } boundaries.setVariable("lastBand",zeBand[0]); boundaries.setVariable("lastYear",zeYear[0]); Note We're using the exact same code we as used for CSV files, with the exception of parameters expected by the createRegion() method.
page and probably make multiple extractions on each one since it isn't dealing with single lines like the TXT example given here. For more information on the API syntax, please refer to DataMapper API. Objects Automation Object Returns a ScriptableAutomation object encapsulating the properties of the PReS Workflow process that triggered the current operation. Properties The following table lists the properties of the Automation object.
Property Type Description already been defined in the Preprocessor step as Automation variables. The Preprocessor step attempts to match variable names passed by the Workflow process to those defined inside the step. Example The variable used from Workflow must first be declared in the Preprocessor step: See The Preprocessor Step Properties for more information. Note The Type of the variable must be the same as the variable from Workflow.
automation.properties.OriginalFilename; To access variables declared in the Preprocessor properties (see picture above): 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. Properties The following table lists the properties of the Boundaries object. Property Return Type CurrentDelim A read-only 1-based index (number) of the current delimiter in the file.
Data Object Returns a data object encapsulating properties and methods pertaining to the original data stream. Properties The following table lists the properties of the data object. Property Description Return Type filename The path of the input file. Returns the fully qualified file name of the temporary work file being processed. properties Contains properties declared in the preprocessor step (see Preprocessor Step Properties for details).
Method The following table describes the methods of the db object. Method connect() Logger Object Global object that allows logging messages such as error, warning or informational messages. Methods The following table describes the methods of the logger object. Method Parameters Description error() message: string Logs an error message info() message: string Logs an informational message warn() message: string Logs a warning message Record Object The current record in the main data set.
Example Region Object The region object defines a sub-section of the input data. Its properties vary according to the type of data. Methods The following table describes the methods of the region object. Method Description Return Type found() Contains a Boolean value indicating if the last call to find() was successful. Returns a region. range() Read-only object containing the physical coordinates of the region. Physical location of the region. createRegion() Creates a region.
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. Methods The following table lists the methods of the steps object.
Method currentPosition() currentLoopCounter() currentPage() currentPageHeight() currentPageWidth() moveLines() moveDelimiters() moveMeasure() moveNode() movePage() moveSibling() moveTo() moveToNext() totalPages() Functions copyFile() Function that copies a file to the target file path, replacing it if it already exists. copyFile(source, target) Copies a file to the target file path, replacing it if it already exists.
source String that specifies source file path and name. target String that specifies target file path and name. target String that specifies destination path and file name. Example In this script, the file test.txt included in c:\Content, will be copied into the c:\out folder. copyFile("c:\Content\test.txt","c:\out\") CreateTempFile() Creates a file with a unique name in the temporary work folder and returns a file object. This file stores data temporarily in memory or in a buffer.
} finally{ // Close the writer or the temporary file writer.close(); } } finally{ // Close the reader reader.close(); } DeleteFile() Function used to delete a file. DeleteFile(filename) Deletes a file. filename 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.
Examples NewByteArray() Function that returns a new byte array. NewByteArray(size) Returns a new byte array of size elements. size Integer that represents the number of elements in the new array. Examples NewCharArray() Function that returns a new character array. 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.
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 NewIntArray() Function that returns a new integer array of size elements. NewIntArray(size) Returns a new integer 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.
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 OpenBinaryReader() Function that opens a file as a binary file for reading purposes. OpenBinaryReader(filename) Opens filename as a binary file for reading purposes. The function returns a BinaryReader object. filename String that represents the name of the file to open.
append Boolean parameter that specifies whether the file pointer should initially be positioned at the end of the existing file (append mode) or at the beginning of the file (overwrite mode). Examples OpenTextReader() Function that opens a file as a text file for reading purposes. OpenTextReader(filename,encoding) Opens filename as a text file for reading purposes, using the encoding specified as a string (UTF-8, ISO-8859-1, etc.). The function returns a TextReader object.
Examples Methods connect() Method that returns a new database connection object Related Object: db. 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. user String that represents the user name for the authentication. password String that represents the password for the authentication.
x2 Double that represents the width of the region. y2 Double that represents the height of the region. createRegion(columnName) Creates a region from the data in a CSV file, using the specified columnName parameter. columnName Double that represents the column to be used to create the region. Examples currentLoopCounter() Returns an integer value representing the current iteration of the containing loop.
Related Object: Steps. Example currentPageHeight() Returns the height of the current page in millimeters. Related Object: Steps. 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). Related Object: Steps. Example extract() Extracts the text value from a rectangular region.
Number that represents the distance from the current vertical position. regionHeight Number that represents the total height of the region. separator String inserted between all lines returned from the region. An empty string can be specified. Examples Example 1: In this example you have the script command data.extract(1,22,8,1,"
");.
Example 2: In this example you have the script command data.extract(1,22,9,6,"
");. It means that the left position of the extracted information is located at 1, the right position at 22, the offset position is 9 (since the first line number is 10) and the regionHeight is 6 (6 lines are selected). Finally, the "
" string is used for concatenation. extract(xPath) Extracts the text value of the specified node.
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.
Double that represents the distance from the left edge of the page to the right edge of the rectangular region. verticalOffset Double that represents the distance from the current vertical position. lineHeight Double that represents the total height of the region. separator String inserted between all lines returned from the region. 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,"
");.
extractMeta() Method that extracts the value of a metadata field. Related Object: Data. 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. Related Object: Data.
fieldExists(fieldName) In a CSV file, that method returns True if the specified fieldName exists in the current record. Otherwise, it returns False. fieldName String that represents a field name (column) in a CSV file. 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.
String to find. 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 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.
necessary to examine the value of found() to determine the actual result of the operation. Examples get() Related Object: Boundaries. get(in_Region) Retrieves an array of strings from the region defined by the in_Region object. in_Region object can be created with a call to region.createRegion(). in_Region ScriptRegion tabular Object. Example boundaries.get(region.
Example moveDelimiters() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. Related Object: Steps. Example moveLines() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. Related Object: Steps. Example moveMeasure() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. Related Object: Steps. Example moveNode() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods.
Related Object: Steps. Example moveSibling() Scope constant that can be used as a parameter to moveTo() and moveToNext() methods. Related Object: Steps. Example moveTo() Moves the current position to a number. Related Object: Steps. moveTo(scope, verticalPosition) Moves the current position in a Text file to verticalPosition where the meaning of verticalPosition changes according to the value specified for scope.
0 - millimeters: verticalOffset represents the number of millimeters to move the current position, relative to the top of the record (NOT the top of the current page). 1 - pages: verticalOffset represents the index of the target page, relative to the top of the record. moveTo(xPath) Moves the current position in a XML file to the first instance of xPath, relative to the top of the record. moveTo(row) Moves the current position in a CSV file to the row index, relative to the top of the record.
moveToNext(left, right) Moves the current position in a PDF file to the next line that contains any text, the search for text being contained within the left and right parameters, expressed in millimeters. left Double that represents the left edge of the text to find. right Double that represents the right edge of the text to find. moveToNext(scope) Moves the current position in a XML file to the next node in the XML hierarchy, based on the specified scope. scope Number that may be set to steps.
Examples Set() Sets a new DataMapper record boundary. Related Object: Boundaries. 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.
if(boundaries.find("Invoice Total",myRegion).found) { // a match was found. Check if we are on a odd or even page and set the Boundary accordingly if( (boundaries.currentDelim % 2) !=0 ) { // Total is on odd page, let's set the document Boundary one delimiter further, thereby skipping the next blank page boundaries.set(1); } else { // 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.
Example totalPages() Returns an integer value representing the total number of pages inside the current record. Related Object: Steps.
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 369 and "Styling and formatting" on page 449. 3. Personalize the content Personalize the content using variable data. See "Personalizing content" on page 481. 4. Generate output Adjust the settings, test the template and generate output: letters, emails, and/or web pages. See "Generating output" on page 795. 5. What's next Use Workflow to automate your customer communications.
l l l "Creating an Email template with a Wizard" on page 307 "Creating a Print template with a Wizard" on page 273 "Creating a Web template with a Wizard" on page 323 After creating a template you can add the other contexts (see "Contexts" on page 265), as well as extra sections (see "Sections" on page 267), to the template. It is, however, not possible to use a Template Wizard when adding a context or section to an existing template.
3. Change how often it saves the template by typing a number of minutes. 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.
To test a template first, select Context > Preflight. Preflights executes the template without actually producing output and it displays any issues once it's done (see also: "Testing scripts" on page 518). 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.
Resources This page clarifies the difference between Internal, External and Web resources that may be used in a template, and explains how to refer to them in HTML and in scripts. Internal resources Internal resources are files that are added to and saved with the template. To add images, fonts, style sheets, and snippets to your template, you can drag or copy/paste them into the Resources Pane.
External resources External resources are not stored in the template, but on the local hard drive or on a network drive. They are accessed using a path. The path must have forward slashes, for example 
or var json_variables = loadjson ("file:///d:/jsondata/variables.json");. The complete syntax is: file:///. If the host is "localhost", it can be omitted, as it is in the example, resulting in file:///.
Creating a Web template with a Wizard With the Designer you can design Web templates and output them through Workflow or as an attachment to an email when generating Email output. Capture On The Go templates are a special kind of Web templates; see "Capture OnTheGo template wizards" on page 354. A Web Template Wizard helps you create a Web page that looks good on virtually any browser, device and screen size.
If you don't know what template to choose, see "Web Template Wizards" on the facing page further down in this topic, where the characteristics of each kind of template are described. 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.
l l l Resources related to the Foundation framework (see "Web Template Wizards" below): style sheets and JavaScript files. The style sheets can be found in the Stylesheets folder on the Resources pane. The JavaScript files are located in the JavaScript folder on the Resources pane, in a Foundation folder. A collection of Snippets in the Snippets folder on the Resources pane. The Snippets contain ready-to-use parts to build the web page. Double-click to open them.
Web Template Wizards Foundation All Web Template Wizards in Connect Designer make use of the Zurb Foundation front-end framework. A front-end framework is a collection of HTML, CSS, and JavaScript files to build upon. Foundation is a responsive framework: it uses CSS media queries and a mobile-first approach, so that websites built upon Foundation look good and function well on multiple devices including desktop and laptop computers, tablets, and mobile phones.
A Capture OnTheGo Form is actually just a Web Form, that you could add without a wizard, but the COTG Template Wizards include the appropriate JavaScript files for the Capture OnTheGo app, and styles to create user-friendly, responsive forms. They are built upon the Foundation framework. Foundation 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.
l l l l l l l Bill of Lading. The Bill of Lading Template is a transactional template that includes a detail table with a checkmark on each line, along with Signature and Date COTG elements. Use this wizard as a way to quickly start any new Zurb Foundation based form for Capture OnTheGo. Event Registration. The Event Registration Template is a generic registration form asking for name, phone, email, etc. Event Feedback.
l l l A Web context with one web page template (also called a section) in it. The web page contains an 'off-canvas' Div element, Header, a Section and a Footer element with dummy text, and depending on the type of web page, a navigation bar, button and/or Form elements. 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.
Foundation, the framework added by the COTG template wizards, comes with a series of features that can be very useful in COTG forms; see "Using Foundation" on page 358. Naturally, Web Form elements can also be used on COTG Forms (see "Forms" on page 426 and "Form Elements" on page 431) as well as text, images and other elements (see "Content elements" on page 369).
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" on the facing page. 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 307.
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 583).
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). 4. Go to the Source tab and paste the contents of the other section here (press Ctrl+V). 5.
Section properties Which properties apply to a section, depends on the context it is part of. See also: "Print sections" on page 280, "Email templates" on page 313, and "Web pages" on page 328. 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.
"Content elements" on page 369. Elements make up the biggest part of the content of each design. "Snippets" on page 447. Snippets help share content between contexts, or insert content conditionally. "Styling and formatting" on page 449. Make your Designer templates look pretty and give them the same look and feel with style sheets. "Personalizing content" on page 481. Personalize your customer communications using variable data. "Writing your own scripts" on page 511.
Only one Print section is created at the start, but you can add as many Print sections as you need; see "Print sections" on page 280. 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 288.
When both Media and a Master Page are used on a certain page, they will both be displayed on the Preview tab of the workspace, the Master Page being 'in front' of the Media and the Print section on top. To open the Preview tab, click it at the bottom of the Workspace or select View > Preview View on the menu. The Media will not be printed, unless this is specifically requested through the printer settings in the Print Wizard; see "Generating Print output" on page 798.
Tip Use the Outline pane at the left to see which elements are present in the template and to select an element. Use the Attributes pane at the right to see the current element's ID, class and some other properties. Use the Styles pane next to the Attributes pane to see which styles are applied to the currently selected element. Print Template Wizards There are three Print Template wizards: one for a formal letter, one for a postcard and one for a Print template based on a PDF that you provide.
The Wizard opens the Print section, so that you can fill it with text and other elements; see "Content elements" on page 369. It already has two Positoned Boxes on it: one on the front, for text, and one on the back, for the address. See "Print context" on page 277 and "Print sections" on page 280 for more information about Print templates. Formal letter The Formal Letter Wizard first lets you select the page settings, see "Page settings: size, margins and bleed" on page 288.
l l One Media. You can see this on the Resources pane: expand the Media folder. Media 1 is the Virtual Stationery that you have selected in the Wizard. It is applied to all pages in the Print section, as can be seen in the Sheet Configuration dialog. (To open this dialog, expand the Contexts folder on the Resources pane; expand the Print folder and rightclick "Section 1"; then select Sheet Configuration.) See "Media" on page 298. Selectors for variable data, for example: @Recipient@.
When you click Finish, the Wizard creates: l l l A Print context with one section in it; see "Print context" below and "Print sections" on page 280. The selected PDF is used as the background of the Print section; see "Using a PDF file as background image" on page 284. For each page in the PDF one page is created in the Print section. One empty Master Page.
l l The Print context is created and one Print section is added to it. You can see this on the Resources pane: expand the Contexts folder, and then expand the Print folder. The Print context can contain multiple sections: a covering letter and a policy, for example, or one section that is meant to be attached to an email as a PDF file and another one that is going to be printed out on paper.
Print settings in the Print context and sections The following settings in the Print context and Print sections have an impact on how the Print context is printed. Arranging and selecting sections The Print context can contain one or more Print sections. When generating output from the Print context, each of the Print sections is added to the output document, one after the other in sequence, for each record. The sections are added to the output in the order in which they appear on the Resources pane.
To set the binding style of a Print section, see "Setting the binding style for a Print section" on page 286. 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.
Using headers, footers, tear-offs and repeated elements In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear on each first page, or only on pages in between the first and the last page, or only on the last page. Examples are a different header on the first page, and a tear-off slip that should show up on the last page. This is what Master Pages are used for.
to be printed out on paper. When a Print template is created (see "Creating a Print template with a Wizard" on page 273 and "Print context" on page 277), only one Print section is added to it, but you can add as many print sections as you need. To add a section to a context: l On the Resources pane, expand the Contexts folder, right-click the Print context , and then click New section.
Warning No backup files are maintained in the template. The only way to recover a deleted section, is to click Undo on the Edit menu, until the deleted section is restored. After closing and reopening the template it is no longer possible to restore the deleted context this way. To prevent losing any work, it is recommended to configure the auto-save and autobackup functions in the preferences (see "Saving Preferences" on page 583).
should be applied. 3. Release the mouse button. Using the Includes dialog 1. On the Resources pane, right-click the section, then click Includes. 2. Choose which CSS files should be applied to this section. You can also change the order in which the CSS files are read. This can have an effect on which CSS rule is applied in the end. Using a PDF file as background image In the Print context, a PDF file can be used as a section's background.
is: file:///. Note: if the host is "localhost", it can be omitted, resulting in file:///, for example: file:///c:/resources/images/image.jpg. Check the option Save with template to insert the image into the Images folder on the Resources pane. l Url allows you to choose an image from a specific web address. Select the protocol (http or https), and then enter the web address (for example, http://www.mysite.com/images/image.jpg).
Note To set the background of a section in script, you need a Control Script; see "Control Script API" on page 779. Setting the binding style for a Print section In printing, Finishing is the binding style, or the way pages are bound together. Each Print section can have its own Finishing settings, as well as the Print context as a whole; see "Setting the binding style for the Print context" on page 279. To set the binding style of a Print section: 1.
Note Your printer must support duplex for this option to work. To enable duplex printing: 1. On the Resources pane, expand the Print context, right-click the print section and click Sheet configuration. 2. Check Duplex to enable content to be printed on the back of each sheet. 3. When duplex printing is enabled, further options become available. l l l Check Tumble to duplex pages as in a calendar.
Each page in a print section has a natural position: it is the first page, the last page, a 'middle' page (a page between the first and the last page) or a single page. For each of those positions, a different Master Page and Media can be set. A Master Page functions as a page's background, with for example a header and footer. A Media represents preprinted paper that a page can be printed on. See "Master Pages" on page 295 and "Media" on page 298.
Margins define where your text flow will go. Static elements can go everywhere on a page, that is to say, within the printable space on a page that depends on the printer. The bleed is the printable space around a page. It can be used on some printers to ensure that no unprinted edges occur in the final trimmed document. Note: Printers that can’t print a bleed, will misinterpret this setting. Set the bleed to zero to avoid this. Tip By default, measurements settings are in inches (in).
l 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. Select the image or the element that holds the promotional content: click it, or use the breadcrumbs, or select it on the Outline tab; see "Selecting an element" on page 373. 4. On the Attributes pane, check the option Whitespace element. 5. (Optional.
l l Sheet number: The current sheet number in the document. A sheet is a physical piece of paper, with two sides (or pages). This is equivalent to half the page number, for example if there are 10 pages, there will be 5 sheets. Sheet count: This marker is replaced by the total number of sheets in the document, whether or not they have contents. Note When a marker is inserted, a class is added to the element in which the marker is inserted. Do not delete that class.
3. Use the Format drop-down to select uppercase or lowercase letters or Roman numerals instead of Arabic numerals. 4. In Leading Zeros, type zeros to indicate how many digits the page numbers should have. Any page number that has fewer digits will be preceded by leading zeros. 5. Type the Number prefix. Optionally, check Add Prefix to Page Counts, to add the prefix to the total number of pages, too. 6. Close the dialog.
1. Open the style sheet for the Print context: on the Resources pane, expand the Styles folder and double-click context_print_styles.css. 2. Add a CSS rule, like the following: p { widows: 4; orphans: 3 } Per paragraph To change the widow or orphan setting for one paragraph only: 1. Select the paragraph, using the breadcrumbs or the Outline pane (next to the Resources pane). 2. Select Format > Paragraph, on the menu. 3.
Inserting a page break To insert a page break before or after a certain element, set the page-break-before property or the page-break-after property of that element (a paragraph for example; see also "Styling text and paragraphs" on page 460): 1. Select the element (see "Selecting an element" on page 373). 2. On the Format menu select the respective element to open the Formatting dialog. 3. In the Breaks group, set the before or after property.
Master Pages In Print sections, there are often elements that need to be repeated across pages, like headers, footers and logos. In addition, some elements should appear only on specific pages, such as only the first page, or the last page, or only on pages in-between. Examples are a different header on the first page, and a tear-off slip that shows up on the last page. This is what Master Pages are used for. Master Pages can only be used in the Print context (see "Print context" on page 277).
Initially, the master page that has been created together with the Print context will be applied to all pages in the Print section. After adding more Master Pages, different Master Pages can be applied to different pages; see "Applying a Master Page to a page in a Print section" on the next page. Editing a Master Page Master Pages are edited just like sections, in the workspace. To open a Master Page, expand the Master pages folder on the Resources pane, and double-click the Master Page to open it.
Master Page cannot display content in the space that is reserved by the Master Page for the header and footer, so that content in the Print section does not collide with the content of the header and footer. To set a margin for the header and/or footer: 1. On the Resources pane, expand the Master pages folder, right-click the master page, and click Properties. 2. Fill out the height of the header and/or the footer.
Deleting a Master Page To delete a Master Page, expand the Master pages folder on the Resources pane, right-click the master page, and click Delete. Note that one Master Page as well as one Media must always exist in a Print template. Just leave it empty if you don't need it.
Then drag that the PDF file from the Images folder and drop it on one of the Media in the Media folder. With this method you can not set any options. To be able to specify a PDF file for both the front and the back of the Media, and to specify a position for the Media's PDF files, you have edit the properties of the Media. Setting Media properties Media have a number of properties that you can set, as described below. What you cannot set are a Media's page size and margins.
because the number of pages in a PDF file can not be determined via the http and http protocols. Therefor, with an external image, the option Save with template is always checked. 4. Select a PDF file. 5. If the PDF file consists of more than one page, select the desired page. 6. Click Finish. 7. For each of the PDF files, select a position: l Fit to page stretches the PDF to fit the page size. l Centered centers the PDF on the page, vertically and horizontally.
l Hole Name: A predefined hole pattern that specifies the pre-punched holes in the media, such as R2-generic, R2m-MIB, R4i-US, etc. 3. Click OK. Rename Media To rename Media: l l On the Resources pane, expand the Contexts folder, expand the Media folder, rightclick the Media and click Rename. Type the new name and click OK. Alternatively, on the Resources pane, expand the Contexts folder, expand the Media folder, right-click the Media and click Properties.
Note When both Media and a Master Page are used on a certain page, they will both be displayed on the Preview tab of the workspace, the Master Page being 'in front' of the Media and the Print section on top. To open the Preview tab, click it at the bottom of the Workspace or select View > Preview View on the menu. Dynamically changing the Media In addition to applying Media to sheets via the settings, it is possible to change Media dynamically, based on a value in a data field, in a script.
functions as expected. 6. When you click OK, the script will be added to the Scripts pane. Printing virtual stationery Media are not printed, unless you want them to. Printing the virtual stationery is one of the settings in a Job Creation Preset. To have the virtual stationery printed as part of the Print output: 1. Create a job creation preset that indicates that Media has to be printed: select File > Presets and see "Job Creation Presets" on page 698 for more details. 2.
Email templates are personalized just like any other template; see "Variable Data" on page 493. Sending email When the template is ready, you can change the email settings (see "Email header settings" on page 316) and send the email directly from the Designer or via Workflow. To test a template, you can send a test email first. Output, generated from an Email template, can have the following attachments: l The contents of the Print context, in the form of a single PDF attachment.
show within the email client. Unfortunately, desktop, webmail, and mobile clients all use different rendering engines, which support different subsets of HTML and CSS. More often than not, the result of these operations is that they completely break the HTML email's layout. Designing HTML email in PReSDesigner The problem of HTML email is that preprocessing and rendering engines break the HTML email's layout. HTML tables, however, are mostly left untroubled.
In the Source tab of the Workspace, you could for example type div.row. This is the abbreviation for a
element with the class row.
embedded images appear instantly when viewing the message in your email client. There is, however, a downside to this method: embedded images can't be used to track email open rates. Email services like mandrillapp.com embed a tiny tracer image at the bottom of your message. Each time a recipient opens the email the tracer image (aka beacon image) is downloaded and yet another 'open' is registered. On mobile devices this happens when the user clicks the Display Images button.
With an Email Template Wizard you can easily create an Email template that outputs emails that look good on virtually any email client, device and screen size. After creating an Email template, the other contexts can be added to it, as well as other sections (see "Contexts" on page 265 and "Email templates" on page 313). To create an Email template with a Template Wizard: 1. In the Welcome screen that appears after startup: l l Choose Browse Template Wizards.
page 506. l l One script, named "To". Double-click that script on the Scripts pane to open it. This script ensures that the email is sent to an email address that is specified in a data field called "email-to". After loading data or a data mapping configuration, you can change the script so that it uses the actual field in your data that holds the customer's email address. See "Email header settings" on page 316 A style sheet, named context_htmlemail_styles.
Email Template Wizards There are Wizards for three kinds of Email templates: for Basic Email, for Banded Email, and Slate templates for responsive email designed by Litmus. Slate: Responsive Email Templates by Litmus Scroll past the Web Template Wizards to see the Slate: Responsive Email templates, created by Litmus (see https://litmus.com/resources/free-responsive-email-templates). More than 50% of emails are opened on mobile.
For an Action or Invoice email, the Email Template Wizard lets you choose: l l l l The subject. You can change and personalize the subject later, see "Email header settings" on page 316. The text for the header. The header is the colored part at the top. The text can be edited later. The color of the header and the color of the button. The color value must be a valid HTML Color Name, or a valid hexadecimal color code.
added as well. Style sheets are located in the folder Stylesheets on the Resources pane. These style sheets are meant to be used for styles that are only applied to elements in the Email context. The Wizard opens the Email section, so that you can fill it with text and other elements; see "Content elements" on page 369 and "Email templates" on the next page. Sending email When the template is ready, you can generate Email output; See "Generating Email output" on page 812.
1. On the Resources pane, expand the Contexts folder, and right-click the Email context. 2. Click Properties. 3. Change the properties of the PDF file that will be attached when the Print context is attached to the email. Lossless is the maximum quality. Note that this will produce a larger PDF file. Uncheck this option to be able to set a lower quality. The quality is set in a percentage of the maximum quality. Tile Size is the size of the files in which the image that is being compressed is divided.
'default' Email section (see below) before generating Email output; see also "Generating Email output" on page 812. Adding an Email template When an Email template is created (see "Creating an Email template with a Wizard" on page 307), only one Email section is added to it. An Email context may contain various templates, but per record only one of those can be sent when you generate Email output. It is not possible to add an Email section to an existing Email context with the help of a Template Wizard.
backup functions in the preferences (see "Saving Preferences" on page 583). Styling and formatting an Email template The contents of an Email section can be formatted directly, or styled with Cascading Style Sheets (CSS). See "Styling and formatting" on page 449. Email clients do not read CSS files and some even remove a
