Objectif Lune PlanetPress Workflow - 2018.1 User Guide
User Guide
Version:2018.1
User Guide
Version 2018.1
Last Revision:7/11/2018
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-2018. All rights reserved. No part of this documentation may be
reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever
without the express written permission of Objectif Lune Inc. Inc. Objectif Lune Inc. Inc. disclaims
responsibility for any errors and omissions in this documentation and accepts no responsibility
for damages arising from such inconsistencies or their further consequences of any kind.
Objectif Lune Inc. Inc reserves the right to alter the information contained in this documentation
without notice.
Table of Contents
Table of Contents 4
Welcome to PlanetPress Workflow 2018.1 10
Notes in this guide 10
Installation and Setup 12
System Requirements 12
Operating System (64-bit only) 12
Minimum Hardware Requirements 12
Environment considerations 12
Terminal Services 13
Virtual environments 13
32-Bit or 64-Bit? 14
Antivirus considerations 14
Backup considerations 15
Microsoft Office compatibility 15
Setting up the working environment 15
Known Issues 16
Upgrade to Workflow 2018.1 leaves Uninstallation entry for earlier version 16
Microsoft patch causing handling of XLS to fail 16
Other known issues 17
Basics 21
Related tools and resource files 21
Features 23
The Nature of PlanetPress Workflow 23
About data 23
Data file and job file 24
Job File Names and Output File Names 25
Data selections 26
About data emulation 36
Sample Data 37
Metadata 39
Data Repository 53
Structure 53
Accessing the Data Repository 54
Page 4
Where to find the Data Repository 56
Debugging and Error Handling 56
About error handling 56
Using the On Error tab 57
Creating and Using Error Processes 58
Accessing the Logs 59
Resubmit Backed Up Input Files to a Process 61
Knowing What to Resubmit 62
Debugging your PlanetPress Workflow process 63
About Printing 66
PlanetPress Workflow Printer Queues 68
Shared Printer Queue Properties 68
Windows Output Printer Queue 70
LPR Output Printer Queue 71
FTP Output Printer Queue 73
Send to Folder Printer Queue 74
Triggers 75
Load Balancing 76
Objectif Lune Printer Driver (PS) 76
About Processes and Subprocesses 79
Processes 79
Subprocesses 80
Creating a new process 81
About branches and conditions 82
Process properties 83
Activating or deactivating a process 88
Converting a branch to a subprocess 88
Importing processes 89
Toggle the Run on Desktop property 90
Executing the Processes (Sending Configuration) 93
Using Scripts 93
The Script Editor and XSLT Editor 94
SOAP Server API Reference 100
The Watch Object 107
Data Repository API 122
Stopping Execution 143
Special Workflow Types 144
Page 5
Special Workflows 144
PlanetPress Capture Workflow 145
Database Considerations (ODBC) 152
HTTP Server Workflow 181
PDF Workflow 188
Capture OnTheGo Workflow 191
Workflow processes in a Connect Send solution 192
ZUGFeRD 193
About Tasks 202
Adding tasks 203
Editing a task 204
Task properties 205
Variable Properties 205
Input tasks 209
Action Tasks 254
Data Splitters 324
Process Logic tasks 344
Connector Tasks 360
PlanetPress Capture 399
Metadata Tasks 422
OL Connect Send 439
OL Connect tasks 453
Output Tasks 496
Working With Variables 512
Types of variables 512
Job Info Variables 513
Standard Variables 514
Manipulate Local Variables 519
Manipulate Global Variables 521
About Workflow Configurations 523
Creating a new configuration 523
Open a PlanetPress Workflow Configuration File 524
Saving and sending a Workflow Configuration 525
Exit PlanetPress Workflow Configuration Program 527
Workflow Configuration resource files 528
Connect resources 528
PlanetPress Design documents 532
Page 6
PrintShop Mail documents 536
About related programs and services 537
Available Input services 537
Available Output services 538
Start and Stop PlanetPress Workflow Service 539
Users and configurations 540
Workflow Services 541
The Interface 544
Customizing the Workspace 545
Dock and Undock Areas of the Program Window 545
Show or Hide Areas of the Program Window 547
Combine and Attach Areas 547
Resize the Program Window Areas 552
Change the Interface Language 552
PlanetPress Workflow Button 553
Options 553
Configuration Components pane 555
Components Area Sections 555
Process properties 558
Manipulate Global Variables 563
Connect resources 565
PPS/PSM Documents 568
Associate Documents and PlanetPress Printer Queues 573
Using the Clipboard and Drag & Drop 574
Renaming objects in the Configuration Components Pane 577
Reordering objects in the Configuration Components pane 578
Grouping Configuration Components 579
Expanding and collapsing categories and groups in the Configuration Components
pane
Delete objects and groups from the Configuration Components pane 580
Other Dialogs 581
Activate Your Printers 581
Workflow Services 582
Process properties 583
580
Advanced SQL Statement Dialog 588
Access Manager 589
PDF Viewer 595
Page 7
Update document 597
Data Repository Manager 598
Virtual Drive Manager 601
The Debug Information Pane 602
The Message Area Pane 603
The Object Inspector Pane 604
The Plug-in Bar 605
Categories 605
Settings & Customization 606
Preferences 607
Other Preferences and Settings 608
General appearance preferences 608
Object Inspector appearance preferences 609
Configuration Components Pane appearance preferences 610
Default Configuration behavior preferences 611
Notification Messages behavior preferences 611
Sample Data behavior preferences 614
Network behavior preferences 614
PlanetPress Capture preferences 615
OL Connect preferences 624
PDF Text Extraction Tolerance Factors 625
General and logging preferences 627
Messenger plugin preferences 628
HTTP Server Input 1 plugin preferences 629
HTTPServer Input 2 plugin preferences 632
LPD Input plugin preferences 633
Serial Input plugin preferences 634
Telnet Input plugin preferences 636
PlanetPress Fax plugin preferences 636
FTP Output Service preferences 640
PlanetPress Image preferences 640
LPR Output preferences 644
PrintShop Web Connect Service preferences 645
Editor Options 646
The Process area 650
Zoom In or Out within Process Area 651
Adding Tasks 651
Page 8
Adding Branches 652
Edit a Task 652
Replacing Tasks, Conditions or Branches 653
Remove Tasks or Branches 653
Task Properties dialog 654
Cutting, Copying and Pasting Tasks and Branches 655
Moving a Task or Branch Using Drag-and-Drop 657
Ignoring Tasks and Branches 658
Resize Rows and Columns of the Process Area 658
Selecting Documents in Tasks Links 659
Highlight a Task or Branch 660
Undo a Command 660
Redo a Command 660
The Quick Access Toolbar 661
The PlanetPress Workflow Ribbon 662
The Task Comments Pane 664
Additional Information 665
Copyright Information 666
Legal Notices and Acknowledgements 667
Page 9
Welcome to PlanetPress Workflow
Note
Important information that deserves your attention.
Tip
Information that may help you better use PlanetPress Workflow or suggests an easier method.
2018.1
This PDF documentation covers version 2018.1. To view the documentation of previous
versions please refer to the PDF files available in the Downloads section of our website:
http://www.objectiflune.com/OL/Download/DownloadCenter.
Workflow is the heart of all of our solutions. Working in conjunction with PlanetPress Connect,
PlanetPress Capture, CaptureOnTheGO, PlanetPress Imaging, PlanetPress Fax, and a variety
of plugins, it helps improve your communications processes. Processes such as
communication creation, interaction, distribution and even maintenance.
Workflow is the "super dispatcher". It caters for inputs from a huge variety of sources, such as
email, web pages, databases, individual files (PDF, csv, XML, etc), print streams, FTP, Telnet
and ERP systems. This data can then be analyzed, modified, stored, verified, routed and used
as triggers for other processes from entirely within Workflow. Finally it is passed to one of our
other products (or not) to be outputted in multiple ways (printed, emailed, posted, archived, sent
to third party solutions, etc..).
Consider Workflow as a set of buildings blocks that enable you to build your own customized
automated processes which will fit your environment and not the other way around. Create
processes that will save you time and money!
Notes in this guide
Notes are used throughout this guide to draw your attention to certain information.
Page 10
Warning
Information that is potentially critical to using PlanetPress Workflow.
Technical
Background information.
Page 11
Installation and Setup
Note
Windows XP, Windows 2003 and older versions of Windows are not supported by PlanetPress
Workflow.
System Requirements
These are the system requirements for PlanetPress Workflow 2018.1.
Operating System (64-bit only)
l Microsoft Windows 2008/2008 R2 Server
l Microsoft Windows 2012/2012 R2 Server
l Microsoft Windows 2016 Server
l Microsoft Windows Vista
l Microsoft Windows 7
l Microsoft Windows 8.1
l Microsoft Windows 10 (Pro and Enterprise versions only)
Minimum Hardware Requirements
l NTFS Filesystem (FAT32 is not supported)
l CPU Intel Core i7-4770 Haswell (4 Core)
l 8GB RAM (16GB Recommended)
l Disk Space: At least 10GB (20GB recommended)
Environment considerations
This page is intended to provide technical information about the environment in which
PlanetPress Workflow is intended to run.
Page 12
Terminal Services
Warning
The PlanetPress Workflow End-User License Agreement (EULA) specifies that a
PlanetPress Workflow does not support Terminal Services environment as possible under
Windows 2000, 2003 and 2008. This is to say, if Terminal Services is installed on the server
where PlanetPress Workflow is located, unexpected behaviors may occur and will not be
supported by our company. Furthermore, using PlanetPress Workflow in a Terminal Service
environment is probably an infringement of our End-User License Agreement.
Terminal Services may also be referred to as Terminal Server or Remote Administration Mode
(Windows Server 2003 and 2008).
Single-User Remote Desktop Protocol (RDP)(where only one person can use RDPat a time)
is supported for PlanetPress Workflow version 6.2 and higher, however it is only supported in
Windows XP or Windows 2003. While later versions of Windows may not cause issues when
accessing PlanetPress Workflow through RDP, these combinations are no longer tested and
may not be functional.
Virtual environments
Both PlanetPress Suite 6 and PlanetPress Suite 7 officially support VMWare Environment. This
includes VMWare Player, VMWare Workstation as well as an ESXVMWare Installation.
PlanetPress Suite 7.1 and higher also support VMotion, which means the virtual machine
hosting PlanetPress Suite can be automatically moved from one ESXserver to another in a
clustered installation.
PlanetPressSuite 7.5.1 and higher started supporting Hyper-V virtualization in addition to the
previous environments.
PlanetPress Workflow is not officially supported on any other virtual machines such as Virtual
PC, Parallels, Bochs, Xen, etc. While running PlanetPress on these virtual machines may work,
and they are properly detected by PlanetPress Suite 7.5.1 and higher, we have not tested them
and cannot offer support for them.
Page 13
PlanetPress Workflow software license may only be used on a single virtual or physical
PC at a time. While copying a virtual machine for backup purposes is acceptable, running
two instances of the same machine, using the same serial number, is strictly prohibited.
32-Bit or 64-Bit?
Warning
Disabling any antivirus scanning permanently on any folder or program is not
recommended, and ObjectifLune cannot be held reliable for any consequence of
disabling your antivirus or whitelisting the folders or executables listed here, or any other
change in your antivirus protection setup!
PlanetPress Suite version 7.1.3 and higher support 64-Bit operating system. However, our
application remains 32-bits in this environment, which means that for all intents and purposes
there is no difference between those two environments as far as PlanetPress Workflow is
concerned.
Antivirus considerations
PlanetPress Workflow generates a very large amount of temporary data on your hard disk,
especially when manipulating or creating PDF files. This can sometimes cause issues when
any other software is trying to access the temporary files at the same time as PlanetPress
Workflow and its components are trying to read, write, create or delete those files.
If you experience these issues you may want to temporarily disable your antivirus "live",
"daily"or "deep"scans for the following folders and processes:
l On Windows Vista/7/2008:
l C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\
l C:\Users\planetpress\AppData\Local\Temp\ (where planetpress is the user under
which Workflow is configured)
l C:\Users\planetpress\Connect (where planetpress is the user under which Workflow
is configured)
Page 14
l On all systems:
Note
C:\Windows\Temp\ is used by multiple software which may cause risks on your computer.
However, PlanetPress Workflow may use this folder as temporary storage, especially in the case of
creating PDF files. We do not recommend disabling scan on this folder, unless you notice
performance issues when generating PDFs, and then only as a test.
l C:\Windows\Temp\
l Processes:
l PPAlmbic.exe
l Service.exe
l PPWatchService.exe
l PPImageService.exe
l MessengerService.exe
Backup considerations
For similar reasons, it is important to know that backup software can also access files while
copying them to a remote backup location, so you should make sure that no PlanetPress
Workflow process is working during your backups.
Microsoft Office compatibility
The Microsoft Office 2010 line of products, other than Pro and Enterprise, has not been certified
for use with PlanetPress Workflow. Some of its products may not be compatible with the
connectors included in the Suite.
Setting up the working environment
After installation, the working environment needs to be set up before you start using Workflow.
This involves:
l Defining the printer (see Activate Your Printers).
l Configuring PlanetPress Workflow Services (see "Workflow Services" on page582).
Page 15
l Setting up the Workflow Configuration tool.
Configure a variety of options, from how the application itself looks or behaves, to plugin
specific options. These are accessible through the Preferences button under the
PlanetPress Workflow Button (see "Preferences" on page607).
Known Issues
Upgrade to Workflow 2018.1 leaves Uninstallation entry for earlier version
If PlanetPress Workflow 2018.1 is installed as an update over a earlier version of PlanetPress
Workflow, then an obsolete entry "PlanetPress Workflow 8" will remaining alongside the new
"PlanetPress Workflow" entry in the Windows "Programs and Features" folder.
The "PlanetPress Workflow 8" entry can be manually removed if desired. Alternatively, it will be
removed in the installation of the next major version of PlanetPress Workflow.
Microsoft patch causing handling of XLS to fail
Some recent Windows updates from Microsoft have impacted the handling of XLS sources in
PReS\PlanetPress Workflow 8.
The Microsoft updates concerned are as follows:
l KB4041693 for Windows 8.1 and Windows Server 2012 R2
l KB4041681 for Windows 7 and Windows Server 2008 R2
l KB4041690 for Windows Server 2012 (no service pack)
Installing these updates may cause the application to fail when attempting to open or load XLS
files via a plugin or in a script. The following error message may appear: “Unexpected error
from external database driver (1). (Microsoft JET Database Engine)".
Suggested resolution
Uninstall the Microsoft patches and wait for the issue to be fixed in a subsequent Microsoft
patch.
Page 16
Workarounds
l For the Lookup in Microsoft Excel Documents plugin (found in the Connectors tab of the
plugin bar): Open the original .xls file and save it with the .xlsx format. That will force the
Excel Lookup plugin to switch drivers.
l For the Database Query plugin (found in the Actions tab of the plugin bar) and when
using Excel/Access in PlanetPress Design: Change the ODBC driver used for Excel files
from JET to ACE (change the Data Source). As an example: in Windows 10: Change the
Excel File ODBC driver from ODBCJT32.dll to ACEODBC.dll. (Naming may vary from
versions of the OS but the basics stay the same.) Important: Before switching from JET to
ACE, install the latest MS Access Database Engine 2016 Redistributable
(https://www.microsoft.com/en-us/download/details.aspx?id=54920). Otherwise, using
ACE in one or more self-replicating processes in a Workflow configuration can cause
Workflow to crash.
In the meantime Objectif Lune would like to apologize to any customers affected by this
problem and for any inconvenience caused. For more information, please contact your local
support team.
Other known issues
l Anoto Pen Director 2.8 is not supported on Windows Server 2012 and Windows 10.
l 22356: Using the PT-PT setting to perform ICR on AlphaNumeric fields may not work
properly. If you encounter the issue, use the PT-BR setting instead, or use another
PlanetPess Field in your document design.
l 21962: Barcode scanner task may have issues reading 2-D barcodes printed/scanned
with low resolution. Make sure the scans and the original printed output are at least
300DPI (600 or better recommended)
l 21405: When printing through a Windows printer driver on Windows Server 2008 or
Windows Server 2008 R2, the Job Owner setting is ignored. This is caused by a
documented issue in those two Operating Systems. Microsoft has provided no reason nor
workaround for the problem, therefore PlanetPress Workflow cannot circumvent the issue.
l Under Windows 2000, the SharePoint output task does not work with SharePoint 2010.
Under the same OS, the PlanetPress Capture ICR does not work due to the .NET 3.5
requirement.
l
21465: The SharePoint Output task does not validate the field contents. That's
Sharepoint's responsibility.
Page 17
l
20143: The Metadata to PDI task encodes the XML using the default system encoding,
not the document's. In addition, it does not discriminate between index names written in
different cases (e.g. Name vs. name).
l Printing PDF files in passthrough mode using a Windows Printer Driver task causes jobs
to be processed sequentially rather than in parallel. This is caused by a 3rd party library
used in the printing process. Possible workarounds are to use a PlanetPress document to
call the PDF files as dynamic images, or to use the PDF file as the Data File for a
PlanetPress Document.
l
JobInfo #4 in the Windows Input Queue task (the original document name set by the
printing application) replaces any non-alphanumeric character with underscores in order
to filter out any invalid characters. Consequently, if the path contains slashes or colons,
those will be replaced with underscores.
l
When the PlanetPress Capture database is set to MS Access, it is considered good
practice to have a single process generate Patterns for documents because the Access
engine may lock the other process out of the database as the first process updates it.
l After the initial installation, the PlanetPress Workflow Configuration tool may display an
error message the first time you launch it if you had already sent a PlanetPress Workflow
Document to it. You can safely ignore this message, you will simply have to manually
start the PlanetPress Messenger service from the Workflow console for this one time only.
To avoid getting the error altogether, make sure you launch the PlanetPress Workflow
tool once before sending any document to it.
l
13554: In the LaserFiche connector, when selecting a different template after filling up
the fields and then going back to the first template, the values entered in the fields are
lost. They have to be entered again.
l When loading a Workflow configuration that includes references to Windows printers, the
output task may fail to recognize the printer if the printer driver has changed between the
moment the configuration was set up and the moment it was loaded. This is unlikely to
occur, but it could, for instance, happen when importing a Version 7 configuration file into
Version 8. To circumvent the issue, open the output task's properties, make sure you
reselect the proper printer, close the task and send the configuration again.
l
The HTTP/SOAP service may fail when both it and the Workflow service are logged on
using 2 non-local users or 2 local users with different privileges. To resolve the issue,
make sure both services use the same logon credentials.
l
13559: The WordToPDF task, when run under the LocalSystem account, may seem to
hang if the installation of MS-Word wasn't properly completed for the LocalSystem
account. If the task seems to take longer than it does when run in Debug mode, this may
Page 18
be the case. You can confirm this behavior by opening up the Windows Task Manager
and checking whether the MSIExec application is running. In order to complete the
installation of MS-Word for the LocalSystem account, follow these steps:
1. Open a command-line window (CMD.exe)
2. Type "AT 10:56 /INTERACTIVE CMD.EXE" (replace 10:56 with the next upcoming
minute on your system)
3. At the specified time, a new command-line window opens. In it, navigate to Word
Installation folder, then type Winword Follow the instructions to complete the
installation
4. Re-start PlanetPress Workflow and test your process.
l
The WordToPDF task relies on MS-Word to perform its functions. However, MS-Word
sometimes displays confirmation dialogs when it encounters a situation requiring user
input. Such dialog windows cannot be displayed when PlanetPress Workflow runs as a
service. As a result, the process may seem to hang because it is awaiting user input on a
window that isn't displayed. The only way to resolve this situation is to kill the
PlanetPress Workflow service. To avoid these types of issues from occurring, it is
imperative that the configuration for the WordToPDF task be tested thoroughly in Debug
mode prior to sending it into production. In particular, the connection to the database must
be validated.
l
The WordToPDF task requires the default system printer to be set to a queue that uses
the PlanetPress printer driver. If you change the default system printer or if you import a
PlanetPress Workflow configuration file from another PC that includes an instance of the
WordToPDF task, you must review the properties of each instance of the task and click
OK to validate its contents. A new printer queue will be created if required and the default
printer will be reset properly. If you do not perform these steps, running the configuration
will result in several error messages being logged and the task failing.
l The preferences for the PrintShop Mail Web connector may not be saved properly if you
set them and close the PlanetPress Workflow Configuration tool without first sending the
configuration to the service. Make sure you send the configuration before exiting from the
Configuration tool.
l
13009: With Outlook 2010, the Send Email functionality requires that the service be run
with administrative credentials in the domain. In addition, both Outlook and the
PlanetPress Workflow Configuration tool must *not* be running while the service is.
l The Microsoft Office 2010/2013/2016 and 365 line of products has not been certified for
use with PlanetPress Workflow. Some of its products may not be compatible with the
connectors included.
Page 19
l
Barcodes produced in printer-centric mode may have a slightly different aspect from
those produced in Optimized PostScript mode. This is due to the different types of 3rd
party libraries being used to generate the barcodes. However, all barcodes scan correctly.
Page 20
Basics
PlanetPress Workflow is a tool to automate the processing, distribution and printing of your
business documents. Once installed on the server, it can be set up to automate all tasks related
to document processing (see "Setting up the working environment" on page15).
When you're all set up, you can start using the Workflow Configuration tool, assuming that you
have already done research on the processes that need to be automated.
Working with Workflow implies the following basic steps:
1.
Creating a Workflow configuration
A Workflow configuration consists of a number of processes, of which each has an input
task, output task and possibly a number of tasks in between. See: "About Workflow
Configurations" on page523.
2.
Debugging the configuration
Debugging is the act of running through your process, either step by step or as a whole,
directly from the PlanetPress Workflow Configuration Tool, in order to detect and resolve
issues with your process. Debugging a process requires providing a sample data file.
See: "Debugging and Error Handling" on page56.
3.
Sending it to the Server (and testing it again)
As you are working on your configuration, you can save that configuration file as a file on
your local hard drive. Saving a configuration file never replaces the current PlanetPress
Workflow service configuration. To do this, you must use the Send Configuration
command; see "Sending a configuration" on page525.
Related tools and resource files
Workflow serves as automation tool in a number of distinct products. Some of the tasks that can
be used in a Workflow configuration only work with product-specific files. The tools that you
need in order to produce those files depend on the product that you are using:
l
PlanetPress Connect users will use the other Connect modules - the Designer and
DataMapper - to create the templates and data mapping configurations used by OL
Connect tasks. The user guides of these modules can be found here:
http://help.objectiflune.com/en/PlanetPress-connect-user-guide/2018.1/.
l
PlanetPress Suite users may use documents made with PlanetPRess Design. For the
user guide, see http://help.objectiflune.com/en/planetpress-design-user-guide/.
Page 21
The product-specific files need to be sent to (or imported into) Workflow before they can be
used in conjunction with a task (see "Workflow Configuration resource files" on page528).
They become visible in the "Configuration Components pane" on page555.
Page 22
Features
PlanetPress Workflow are input driven applications designed to output data in a variety of ways
through diverse means to various applications and devices. PlanetPress Workflowcan be used
as simple go between, passing along input data to output devices, but it can also perform
various types of data processing. You can combine the various PlanetPress Workflow services
to set up versatile automated processes to print jobs as well as generate other types of output.
The Nature of PlanetPress Workflow
PlanetPress Workflow act as sorts of dispatchers. On the one hand, they retrieves data and
controls plugins that retrieve data from watched locations, and on the other hand they send data
and controls plugins that send data to various devices, for printing or to generate documents
that can then be emailed or faxed. PlanetPress Workflow can also perform a variety of
operations on the data using its action plugins.
In fact, the PlanetPress Workflow plugin based architecture enables almost limitless
customization. You can create or purchase compatible plugins, drop them in any of
PlanetPress Workflow plugin folder and use them to perform other operations. You can even
find free unsupported plugins on the Objectif Lune Web site.
PlanetPress Workflow are service applications, or if you will, applications that continuously run
on a given computer and that perform actions automatically. Those actions are defined in a
PlanetPress Workflow configuration. A given computer can only run one PlanetPress Workflow
configuration at a time. The PlanetPress Workflow Service Console may be used to monitor the
services running on a given computer.
About data
Data is what drives your business, and our software. We define data as anything that is
obtained through an Input task and used within the process itself. Once the data is obtained, it
becomes the job file that is passed from one task to another and generally used to generate
output.
Data can be manipulated using the tasks in the process, used as comparison for conditions and
loops, complemented with data from other sources, and used to generate your output. It
Page 23
originates from many different sources (as many as the input tasks support), parts of it can be
Note
Null characters present in the data may not be displayed properly when using the
PlanetPress Workflow Configuration tool, and they may also be printed differently by
different printers. To ensure consistency, you should consider filtering out such
characters.
stored in variables, and it is always accessible by the task that currently handles it.
Data is referred to in tasks using data selections; see "Data selections" on page26.
Data file and job file
Whichever source it may come from, a serial port, an e-mail message, or an LPR request, for
instance, and whatever its format, data entering a PlanetPress Workflow process via an Input
task is always referred to as a data file.
When a data file enters a process, it becomes the job file. 'Job file' however is a more general
term, that can refer to data files as well as other types of files traveling through a process. Image
files, for example, can be passed from task to task in order to be downloaded to a printer. So
files traveling within a process are referred to as job files.
A single job file can be the source of multiple job files. This is the case, for example, when a
process includes multiple branches, as each branch is given a duplicate copy of the job file.
This is also the case when a job file is split into multiple smaller files by a Splitter action task,
for instance (see "Data Splitters" on page324).
It is important to note that job files may be used as a helpful debugging resource (see
"Debugging and Error Handling" on page56).
Job file names are generated automatically and stored in the %f system variable (see "Job File
Names and Output File Names" on the next page).
Actual data and sample data
The actual data is the dynamic data captured by PlanetPress Workflow at run-time. The sample
data file is a static sampling of the run-time data.
Page 24
In the PlanetPress Workflow Configuration program, you use sample data files to create, edit
and debug PlanetPress Workflow configurations.
Job File Names and Output File Names
When an Input task sends a new data file down a process, it gives it an internal file name
referred to as the job file name (associated with the %f variable). The new job file typically
keeps the same name until the end of the process.
l If the job file comes to a branch in the process, PlanetPress Workflow makes a copy of the
job file and gives the new file a new job file name.
l If the job file is processed by a Splitter action task, the task typically creates a number of
new files which are all given new job file names.
Since these files are generated and managed by PlanetPress Workflow, you should not
actually pay too much attention to their names.
Many Output tasks, on the other hand, let you determine exactly how you want the files they
generate to be named. In the case of Send to Folder output tasks, for example, output files are
saved under their job file names by default (using the variable %f), but you may use a static
(MyOutput.txt, for example) or variable name (%O_Invoices, for instance) of your choosing.
Variables such as %o (original file name) bring up the issue of file overwriting. If the process
receives two source files with the same name, the second output file may overwrite the first one.
This may be what you want, but otherwise you may consider using another variable, such as
%u (unique 13-character string).
When choosing naming schemes for output files, consider the following:
l For the benefit of users who must identify files, be it in a folder or on a printer queue,
consider using names that are as meaningful and precise as possible.
l Some devices or applications may use file name extensions to know what to do with
incoming files.
Since variable properties can be entered in the boxes where you specify the folder and file
names, you can use variables (see "Working With Variables" on page512), data selections
(see "Data selections" on the facing page) and static text. You could, for example, use the
following: ClientID_@(1,1,1,1,14,KeepCase,Trim)_StatMonth_%m.
Page 25
One last consideration regarding output file names has to do with standard JPEG and TIFF files
Note
You can change the name of a previously named file using a Rename action task (see "Rename"
on page303).
generated by PlanetPress Image. When an output job contains multiple pages, multiple JPEG
or TIFF files are generated (one image per file), each one identified by a sequence number
appended to its name (this is managed by your PlanetPress Workflow). A three page job to be
called Invoice, for example, will generate three JPEGs or TIFFs called Invoice0, Invoice1 and
Invoice2. Note that this does not apply to multiple TIFFs, which can include multiple images in
a single file.
Data selections
A data selection could be compared to an address. It indicates a location within a data file or
database (the job file, metadata file, or Data Repository).
Data selections are always evaluated at run-time so they are always dynamic and depend on
the job file that is currently being processed.
There are several types of data selections you can use, depending on which emulation you are
using, whether or not Metadata have been created by a previous task in the process, and
whether or not data have been entered in the Data Repository.
PlanetPress Workflow includes a tool called the Data Selector that helps you make data
selections. The Data Selector does two things:
l It uses the current emulation (either the emulation chosen when the sample data file was
selected, or the one chosen in the last Change Emulation action task appearing above
the current task) to format the data.
l It displays the formatted data to let you make selections easily using the mouse pointer.
Adding a data selection
A data selection can be used in any task property that may contain a variable. These properties
are recognizable by their colored field label (maroon, by default). Right-click the property field
and choose Get Data Location or Get Metadata Location to open the Data Selector (see "The
Page 26
Data Selector" on page32) or Get Repository Location to open the Data Repository Manager
Note
The Get (...) Value options will also open the Data Selector or the Data Repository Manager, but
once selected, the value becomes static and does not change between each datapage and job file.
(see "Data Repository Manager" on page598).
After opening a sample of the data and/or metadata, you can easily make a selection.
It is also possible to manually enter a data selection, or to change it after making a selection
with the mouse pointer.
Data selections can also be used in a PlanetPress Design Document that is being merged with
the data (for example in a printed output); for more information, see PlanetPress Design User
Guide.
Wild card parameter "?"
Data/metadata selection functions accept a wildcard parameter "?", indicating the function
operates on allnodes (not just one) of a given level.
Examples
l In a PDF emulation, the format of a selected region could be:
region(?,0.59375,2.21875,1.85416,2.51041,KeepCase,NoTrim)
In this case “?” represents the current physical data page processed by the task.
l In the following rule, the Metadata selection function loops through all datapages in a job,
comparing their index in the document to a value:
(GetMeta(SelectedIndexInDocument[0], 11, Job.Group[?].Document
[?].Datapage[?]) Equal 0
l In the following rule, the question mark in the text-based data selection represents the
current page number:
(@(?,1,1,1,9,KeepCase,NoTrim) IS EQUAL TO Page 1 of)
Text-based data selections
Text-based selections are used for text data files such as Line Printer, ASCIIand Channel Skip
emulations. The selection refers to a rectangular selection that may contain multiple lines, rows,
Page 27
columns on a given page.
Syntax
@(page number, from line, to line, from column, to column, case option, trim
option)
Here is a breakdown of the syntax (all options are mandatory):
l @():Always surrounds a data selection.
l Page Number:The data page number from which you want the data selection to grab the
data. If you want to get data from each page individually, this has to be done after a
splitter.
l From Line:The starting line of the data selection.
l To Line:the last line of the data selection.
l From Column:the leftmost character position of the data selection.
l To Column:the rightmost character position of the data selection.
l Case Options:This can be one of three options:
l
KeepCase:Keeps the current uppercase and lowercase letters as they are.
l
UpperCase:Converts all letters to their uppercase equivalent.
l
LowerCase:Converts all letters to their lowercase equivalent.
l Trim Option:Can either be "Trim"if you want to trim empty spaces before and after the
data selection or "NoTrim"if you want to retain the extra spaces.
Database data selections
These selections are used for database-driven data files such as Database and
CSVemulations. The selection refers to a specific field on any given data page.
Syntax
field(record set number, child number, field name, treatment of character case,
treatment of empty trailing cells)
Here is a breakdown of the syntax (all options are mandatory):
Page 28
l field():Always surrounds database field selections.
l Record Set Number: The data page (or "record") of the data selection.
l Child Number:Line Number in the record (if there are multiple lines returned for one
single record).
l Field Name: The name of the field you want to retrieve.
l Case Option: This can be one of three options:
l KeepCase:Keeps the current uppercase and lowercase letters as they are.
l UpperCase:Converts all letters to their uppercase equivalent.
l LowerCase:Converts all letters to their lowercase equivalent.
l Trim Option:Can either be "Trim"if you want to trim empty spaces before and after the
data selection or "NoTrim"if you want to retain the extra spaces.
Data Repository lookups
The Data Repository selections are made through the lookup function. Selections are done
from the data located in the "Data Repository Manager" on page598. The lookup function
returns the value of a single key, which is always a string.
Syntax
lookup(group, return key, lookup key, lookup value)
Here is a breakdown of the syntax (all arguments are mandatory):
l group:The name of the group in which to retrieve the value. Does not need to be
surrounded by quotes.
l return key:The name of the key where the information you want to retrieve is located.
Does not need to be surrounded by quotes.
l lookup key:The name of the key in the group with which to look up the value. The return
key of the KeySet in which the lookup key's value matches the lookup value will be
returned.
l lookup value: A string surrounded by quotes which will be used in the lookup.
PDF data selections
These selections are used for PDF data files. The selection refers to a specific area of any
given page of the PDF by using precise region coordinates (in inches).
Page 29
Note that when adding a metadata field, if you perform a multi-line data selection on a PDF
Tip
To get a sample of the metadata file, debug your process and step through it until the option View
Metadata gets enabled. This happens when metadata have been created by a task in the process.
Open the metadata viewer and save the metadata file to use it as a metadata sample file in the Data
Selector.
region, only the first line of that region will be set to the metadata field.
Syntax
region(page, left, top, right, bottom, case option, trim option)
Here is a breakdown of the syntax (all options are mandatory):
l region():Always surrounds PDFdata selections.
l Page:The page of the PDFfrom which to retrieve the data.
l Left:Exact horizontal position (in inches)that defines the left of the selection region.
l Top:Exact vertical position (in inches)that defines the top of the selection region.
l Right:Exact horizontal position (in inches)that defines the right of the selection region.
l Bottom:Exact vertical position (in inches)that defines the bottom of the selection region.
l Case Option: This can be one of three options:
l KeepCase:Keeps the current uppercase and lowercase letters as they are.
l UpperCase:Converts all letters to their uppercase equivalent.
l LowerCase:Converts all letters to their lowercase equivalent.
l Trim Option:Can either be "Trim"if you want to trim empty spaces before and after the
data selection or "NoTrim"if you want to retain the extra spaces.
Metadata selections
Metadata selections are used with any type of emulation, as long as a metadata file was
created by a previous task in the process.
Page 30
Loading...