PlanetPress Workflow User Guide Planet Press 8.8 Ug

User Manual: Pdf PlanetPress Workflow - 8.8 - User Guide User Guide for Objectif Lune PlanetPress Software, Free Instruction Manual

Open the PDF directly: View PDF PDF.
Page Count: 796 [warning: Documents this large are best viewed by clicking the View PDF Link!]

User Guide
User Guide
Version 8.8
Last Revision:4/9/2018
Objectif Lune, Inc.
2030 Pie-IX, Suite 500
Montréal, QC, Canada, H1V 2C8
+1 (514) 875-5863
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 8.8 10
Icons used in this guide 10
System Requirements 12
Operating System (64-bit only) 12
Minimum Hardware Requirements 12
Known Issues 12
Basics 16
Setting Up the Working Environment 16
Setting Up Preferences 16
Create a New Process 16
Considerations 17
Send your Configuration 17
Features 20
The Nature of PlanetPress Workflow 20
About Branches and Conditions 20
Branches 21
Conditions 21
Configuration Components 21
Connect Resources 21
Available Resources 22
Resource Save Location 22
Resource Archives 23
About Data 23
Data File and Job File 24
Job File Names and Output File Names 25
Data selections 26
AboutData Emulation 35
Using the File Viewer 36
Sample Data 36
Metadata 38
Data Repository 51
Structure 52
Page 4
Accessing the Data Repository 53
Where to find the Data Repository 54
About Documents 54
Import Documents 54
Import PrintShop Mail Documents 55
Debugging and Error Handling 55
About Error Handling 55
Using the On Error tab 56
Creating and Using Error Processes 57
Accessing the Logs 58
Resubmit Backed Up Input Files to a Process 60
Knowing What to Resubmit 62
Debugging your PlanetPress Workflow Process 63
The Plug-in Bar 66
Categories 66
Settings & Customization 67
About Printing 68
PlanetPress Workflow Printer Queues 69
Shared Printer Queue Properties 70
Windows Output Printer Queue 72
LPR Output Printer Queue 73
FTP Output Printer Queue 74
Send to Folder Printer Queue 76
Triggers 77
Load Balancing 77
Objectif Lune Printer Driver (PS) 78
About Processes and Subprocesses 81
Processes 81
Subprocesses 81
Process Properties 82
Activate or Deactivate a Process 87
Convert a Branch to a Subprocess 87
Import Processes from Another Configuration File 88
Toggle the Run on Desktop Property 89
Using Scripts 91
The Script Editor and XSLT Editor 92
SOAP Server API Reference 98
Page 5
The Watch Object 105
Data Repository API 121
Stopping Execution 141
Special Workflow Types 142
Special Workflows 142
PlanetPress Capture Workflow 143
Database Considerations (ODBC) 150
HTTP Server Workflow 179
PDF Workflow 186
Workflow processes in a Connect Send solution 189
The basic processes involved in the Capture OnTheGo Workflow 191
About Tasks 196
Task Properties 197
Variable Properties 197
Input Tasks 203
Action Tasks 268
Data Splitters 368
Process Logic Tasks 396
Connector Tasks 426
PlanetPress Capture 475
Metadata Tasks 509
OL Connect Send 538
OL Connect tasks 555
Output Tasks 619
Working With Variables 644
Types of Variables 644
Job Info Variables 645
Standard Variables 646
Manipulate Local Variables 650
Manipulate Global Variables 652
About Configurations 654
Create a New Configuration 654
Open a PlanetPress Workflow Configuration File 655
Saving and Sending 656
Exit PlanetPress Workflow Configuration Program 658
About related programs and services 658
Available Input services 659
Page 6
Available Output services 660
Start and Stop PlanetPress Workflow Service 660
The Interface 663
Customizing the Workspace 664
Dock and Undock Areas of the Program Window 664
Show or Hide Areas of the Program Window 666
Combine and Attach Areas 666
Resize the Program Window Areas 671
Change the Interface Language 671
PlanetPress Workflow Button 672
Options 672
The Configuration Components Pane 674
Components Area Sections 674
Processes and Subprocesses 677
Manipulate Global Variables 685
Connect Resources 687
PPS/PSM Documents 689
Associate Documents and PlanetPress Printer Queues 694
Using the Clipboard and Drag & Drop 695
Rename Objects in the Configuration Components Pane 698
Reorder Objects in the Configuration Components Pane 698
Grouping Configuration Components 699
Expand and Collapse Categories and Groups in the Configuration Components Pane 700
Delete Objects and Groups from the Configuration Components Pane 701
Other Dialogs 701
Activate Your Printers 701
Workflow Services 702
Process Properties 704
Advanced SQL Statement Dialog 709
Access Manager 709
PDF Viewer 717
The PlanetPress Workflow Service Console 719
Update document 721
Data Repository Manager 721
Virtual Drive Manager 724
The Debug Information Pane 725
The Message Area Pane 726
Page 7
The Object Inspector Pane 727
The Plug-in Bar 728
Categories 729
Settings & Customization 729
Preferences 730
Other Preferences and Settings 732
General appearance preferences 732
Object Inspector appearance preferences 733
Configuration Components Pane appearance preferences 733
Default Configuration behavior preferences 734
Notification Messages behavior preferences 735
Sample Data behavior preferences 737
Network behavior preferences 738
PlanetPress Capture preferences 739
OL Connect preferences 748
PDF Text Extraction Tolerance Factors 749
General and logging preferences 751
Messenger plugin preferences 752
HTTP Server Input 1 plugin preferences 753
HTTPServer Input 2 plugin preferences 756
LPD Input plugin preferences 757
Serial Input plugin preferences 758
Telnet Input plugin preferences 759
PlanetPress Fax plugin preferences 759
FTP Output Service preferences 763
PlanetPress Image preferences 764
LPR Output preferences 767
PrintShop Web Connect Service preferences 768
Editor Options 769
The Process Area 773
Zoom In or Out within Process Area 774
Adding Tasks 774
Adding Branches 775
Edit a Task 775
Replacing Tasks, Conditions or Branches 776
Remove Tasks or Branches 776
Task Properties Dialog 777
Page 8
Cutting, Copying and Pasting Tasks and Branches 778
Moving a Task or Branch Using Drag-and-Drop 781
Ignoring Tasks and Branches 782
Resize Rows and Columns of the Process Area 782
Selecting Documents in Tasks Links 783
Highlight a Task or Branch 784
Undo a Command 784
Redo a Command 784
The Quick Access Toolbar 785
The PlanetPress Workflow Ribbon 786
The Task Comments Pane 788
Additional Information 789
Copyright Information 790
Legal Notices and Acknowledgements 791
Page 9
Welcome to PlanetPress Workflow
This PDF documentation covers version 8.8. To view the documentation of previous versions
please refer to the PDF files available in the Downloads section of our website:
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 even ERP systems! This data can then be analysed, 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 customised
automated processes which will fit your environment and not the other way around. Create
processes that will save you time and money!
Icons used in this guide
Icons are used throughout this guide to point your attention to certain information.
Complementary information that is not critical, but may help you better use PlanetPress Workflow.
Information that is useful or suggests an easier method.
Page 10
Information that may require specific knowledge to understand.
Information that is potentially critical to using PlanetPress Workflow. Pay close attention.
Page 11
System Requirements
These are the system requirements for PlanetPress Workflow 8.8.
Operating System (64-bit only)
lMicrosoft Windows 2008/2008 R2 Server
lMicrosoft Windows 2012/2012 R2 Server
lMicrosoft Windows Vista
lMicrosoft Windows 7
lMicrosoft Windows 8.1
lMicrosoft Windows 10 (Pro and Enterprise versions only)
Windows XP, Windows 2003 and older versions of Windows are not supported by PlanetPress
Minimum Hardware Requirements
lNTFS Filesystem (FAT32 is not supported)
lCPU Intel Core i7-4770 Haswell (4 Core)
l8GB RAM (16GB Recommended)
lDisk Space: At least 10GB (20GB recommended)
Known Issues
lAnoto Pen Director 2.8 is not supported on Windows Server 2012 and Windows 10.
l22356: 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.
Page 12
l21962: 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)
l21405: 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.
lUnder 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
l21465: The SharePoint Output task does not validate the field contents. That's
Sharepoint's responsibility.
l20143: 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).
lPrinting 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
lJobInfo #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.
lWhen 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.
lAfter 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.
Page 13
l13554: 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.
lWhen 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 config 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.
lThe 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.
l13559: 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
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
4. Re-start PlanetPress Workflow and test your process.
lThe 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.
lThe 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
Page 14
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.
lThe 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.
l13009: 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.
lThe 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.
lBarcodes 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 15
PlanetPress Workflow is a tool for the automation of the processing, the distribution and the
printing of your business documents. Once installed on the server, it can be set up to automate
all tasks related to document processing.
Setting Up the Working Environment
Setting up the working environment has to be done the first time you start PlanetPress
1. Defining the printer (see Activate Your Printers).
2. Configure PlanetPress Workflow Services (see Workflow Services).
Setting Up Preferences
PlanetPress Workflow Configuration program lets you configure a variety of options, from how
the application itself looks or behaves, to plugin specific options. For more information about
preferences accessible through the Preferences button in the PlanetPress Workflow Button,
please refer to Preferences.
Create a New Process
You can create a new process in a two different ways:
lIn the Ribbon, go to the Home tab and click the Process button in the Processes group.
lIn the Configuration Components pane, right-click on any process or the Processes
folder and select Insert Process.
Regardless of the method, a new process is created with a default name (Process1, Process2,
etc), Input Task and Output Task. The defaults are configurable in the "Default Configuration
behavior preferences" on page734 screen. The same methods can be used to create a new
Startup process.
Page 16
To add a PlanetPress Workflow startup process:
lIn the Ribbon, go to the Home tab and click the Startup Process button in the
Processes group.
lIn the Configuration Components pane, right-click on any process or the Processes
folder and select Insert Startup Process.
You can only have one Startup Process in any given configuration and cannot add more.
lWhile your configuration is limited to a maximum of 512 processes, any given process
can have as many tasks as necessary.
lA given process may include output tasks that generate files used by input tasks from
other processes.
lWhen you send a configuration to your PlanetPress Workflow service, all its active
processes are applied.
lEach process’ schedule determines when its initial input task can be performed.
lOther tasks included in the process are performed regardless of schedule, granted that
the previous task was performed.
Send your Configuration
PlanetPress Workflow Configuration saves entire configurations in the form of a single file. Like
any other file, configuration files may be saved and reopened, as well as rename as desired.
Simply saving a configuration has no effect on the configuration actually used by the
PlanetPress Workflow when it is started. To change any currently active configuration, you
must use the Send Configuration command.
When you use the Send command, the PlanetPress Workflow Configuration program uses the
currently opened configuration (Any_name.OL-workflow) to overwrite PlanetPress Workflow
service's current configuration (ppwatch.cfg).
Page 17
OL-workflow files are equivalent to .pp7 files made with older versions of PlanetPress Workflow.
They contain the processes and such used by Workflow.
If PlanetPress Workflow service is running when you send a new configuration, it stops and
restarts automatically with the new configuration. If the service is stopped, it will not start
To send a Configuration to the local server:
1. Open the configuration you want to use as a new configuration.
2. Edit the configuration, if required.
3. When the configuration is ready to be used, from the PlanetPress Workflow button,
choose Send Configuration, then Send Local.
To send a Configuration to a remote server:
1. Open the configuration you want to use as a new configuration.
2. Edit the configuration, if required.
3. When the configuration is ready to be used, from the PlanetPress Workflow button,
choose Send Configuration, then Send Remote.
Alist of available servers on the local network appears.
4. Put a checkmark next to each server where the configuration should be sent.
5. Click OK.
If a server is grayed out, this may mean you do not have access to send a configuration
remotely to it. For more information, please see "Access Manager" on page709.
If PlanetPress Workflow service is paused when you send a new configuration, it will not
stop and restart. Since PlanetPress Workflow service reads its configuration file when it
starts up, when you resume processing, PlanetPress Workflow service will continue
Page 18
using the old configuration.
Page 19
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 Branches and Conditions
While some processes can simply start with an input task, manipulate the data with a few action
tasks and finish with an output task, in some cases you may want to have more control over the
flow of your process. For example, you may want multiple outputs, such as printing to multiple
printers as well as generating a PDFand emailing it. To do this, you will need branches. You
may also want to detect certain criteria in your data and act differently depending on that data,
such as sending a fax only when a fax number is found, or printing to a different printer
depending on who send you a print job. To do this, conditions are used.
Page 20
A branch is effectively a doubling of your job file. As your job file goes down the process, when
it encounters a branch it will go in that branch, process all tasks up to the output, and return to
the main trunk to continue processes. You can have branches within branches, and all
branches must have an output. For more information on branches, see Branch.
A branch is represented as a crossing .
Acondition will either execute the branch it creates or the main trunk, but never both. As your
job file goes down the process, when it encounters a condition it will verify whether that
condition results in a "true"or "false"value. If the result is true, it goes in the branch, processes
all tasks up to the output, and the process finishes. If the result is false, it goes down the main
trunk and continues processing until the process finishes.
A conditional branch (or condition) is shown as a crossing with a red diamond over it .
For the list of operations you can perform on Branches and Conditions, please refer to The
Process Area.
Configuration Components
The Configuration Components items displayed in the pane are processes, subprocesses,
variables, documents and printer queues. For more information on operations that you can
perform on each component, please refer to The Configuration Components pane.
Connect Resources
Connect resources are visible in The Configuration Components pane and are added by
using the Send to Workflow option from the PlanetPress 's File menu.
Page 21
Available Resources
lData Mapping Configurations:Displays a list of data mapping configurations used with
the Execute Data Mapping task. Each of the templates have been sent from PlanetPress
Connect using the Send to Workflow tool. For each template in the list, the following two
items appear within them:
lData Model:Displays the data model used in the data mapping configuration.
Double-click on the data model to view it in your default XMLviewer (generally,
Internet Explorer).
lSample Data File(s):Displays a list of sample files that are included in the data
mapping configuration. Double-click on a file to use it as a sample data file for the
active process.
lDocument Templates:Displays a list of templates that can be used in content creation
tasks:"Create Email Content" on page562, "Create Web Content" on page587 and
"Create Print Content" on page582.
lJob Presets:Displays a list of Job Presets that can be used in the "Create Job" on
page567 task.
lOutput Presets:Displays a list of Output Presets that can be used in the "Create Output"
on page570 task.
Resource Save Location
Any resource sent to PlanetPress Workflow from PlanetPress Connect is saved locally at the
following location: %PROGRAMDATA%\Objectif Lune\PlanetPress Workflow 8\PlanetPress
Resources are saved in their appropriate folder:
lDataMapper contains the data mapping configurations (.OL-datamapper)
lJobCreation contains the Job Presets(.OL-jobpreset)
lOutputCreation contains the Output Presets (.OL-outputpreset)
lTemplate contains the templates (.OL-template)
Page 22
Package Files are not saved anywhere. The individual resources contained within the
package are extracted and placed in the folders noted above.
Resource Archives
From version 8.2, PlanetPress Workflow maintains an archive of previous versions of
resources, in the following location:%PROGRAMDATA%\Objectif Lune\PlanetPress Workflow
8\PlanetPress Watch\OLConnect\Archive , each in their own folder:
ldatamapper contains archives of the data mapping configurations (.OL-datamapper)
ljobcreation contains archives of the Job Presets(.OL-jobpreset)
loutputcreation contains archives of the Output Presets (.OL-outputpreset)
ltemplate contains archives of the templates (.OL-template)
lworkflow contains archives of Workflow configurations received by the server.
The archives are saved using the template named followed by a timestamp. A maximum of 30
of each instance of a resource is kept (meaning if you have 10 different templates, a maximum
of 300 files will be present in the archive\template folder). Older archives are deleted
automatically as new archives are created.
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
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
originates from many different sources (as many as the input tasks support), parts of it can be
stored in variables, and is always accessible by the task that currently handles it.
Data is referred to using Data Selections either from PlanetPress Workflow or a PlanetPress
Design Document that is being merged with the data (for example in a printed output).
Page 23
For more information about Data, please refer to "Sample Data" on page36.
Null characters present in the data may not be displayed properly when using
PlanetPress Workflow Configuration program, and that they may also be printed
differently by different printers. To ensure consistency, you should consider filtering out
such characters.
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. Job file 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 mostly referred to as job files.
By default, job file names are generated using the %f variable. You may change the
wayPlanetPress Workflow names job files by using any combination of static characters,
variables and Job info variables. You could for instance enter Process_%w_Job_%f in the
File name box to add the process name in the name generated by the PlanetPress Workflow
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 page368).
It is important to note that job files may be used as a helpful debugging resource (See
"Debugging and Error Handling" on page55).
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 and
edit 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.
lIf the job file comes to a branch in the process, PlanetPress Workflow makes a copy of the
job file and give the new file a new job file name.
lIf 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 in
%u (unique 13-character string).
When choosing naming schemes for output files, consider the following:
lFor 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.
lSome 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, data selections 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
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.
You can change the name of a previously named file using a Rename action task (see "Rename"
on page334).
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.
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
Data Selector" on page31) or Get Repository Location to open the Data Repository Manager
(see "Data Repository Manager" on page721).
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.
Page 26
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.
Wild card parameter "?"
Data/metadata selection functions accept a wildcard parameter "?", indicating the function
operates on allnodes (not just one) of a given level.
lIn a PDF emulation, the format of a selected region could be:
In this case “?” represents the current physical data page processed by the task.
lIn 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
lIn 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,
columns on a given page.
@(page number, from line, to line, from column, to column, case option, trim
Here is a breakdown of the syntax (all options are mandatory):
l@():Always surrounds a data selection.
lPage 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
Page 27
lFrom Line:The starting line of the data selection.
lTo Line:the last line of the data selection.
lFrom Column:the leftmost character position of the data selection.
lTo Column:the rightmost character position of the data selection.
lCase Options:This can be one of three options:
lKeepCase:Keeps the current uppercase and lowercase letters as they are.
lUpperCase:Converts all letters to their uppercase equivalent.
lLowerCase:Converts all letters to their lowercase equivalent.
lTrim 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
CSVemulations. The selection refers to a specific field on any given data page.
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):
lfield():Always surrounds database field selections.
lRecord Set Number: The data page (or "record") of the data selection.
lChild Number:Line Number in the record (if there are multiple lines returned for one
single record).
lField Name: The name of the field you want to retrieve.
lCase Option: This can be one of three options:
lKeepCase:Keeps the current uppercase and lowercase letters as they are.
lUpperCase:Converts all letters to their uppercase equivalent.
lLowerCase:Converts all letters to their lowercase equivalent.
lTrim 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.
Page 28
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 page721. The lookup function
returns the value of a single key, which is always a string.
lookup(group, return key, lookup key, lookup value)
Here is a breakdown of the syntax (all arguments are mandatory):
lgroup:The name of the group in which to retrieve the value. Does not need to be
surrounded by quotes.
lreturn key:The name of the key where the information you want to retrieve is located.
Does not need to be surrounded by quotes.
llookup 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
llookup 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).
Note that when adding a metadata field, if you perform a multi-line data selection on a PDF
region, only the first line of that region will be set to the metadata field.
region(page, left, top, right, bottom, case option, trim option)
Here is a breakdown of the syntax (all options are mandatory):
lregion():Always surrounds PDFdata selections.
lPage:The page of the PDFfrom which to retrieve the data.
lLeft:Exact horizontal position (in inches)that defines the left of the selection region.
lTop:Exact vertical position (in inches)that defines the top of the selection region.
Page 29
lRight:Exact horizontal position (in inches)that defines the right of the selection region.
lBottom:Exact vertical position (in inches)that defines the bottom of the selection region.
lCase Option: This can be one of three options:
lKeepCase:Keeps the current uppercase and lowercase letters as they are.
lUpperCase:Converts all letters to their uppercase equivalent.
lLowerCase:Converts all letters to their lowercase equivalent.
lTrim 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.
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
GetMeta(Field Name [, Option Flags, Metadata Path])
Here is a breakdown of the syntax:
lGetMeta():Always surrounds metadata selections.
lField/Attribute Name:specifies the name of the field (or attribute, if the GetAttribute
option flag is set) to retrieve (see "Metadata" on page38).
lOption Flag (optional):Sets the options for the selection (see table below).
Page 30
lMetadata Path (optional):Defines the precise path where the Metadata Field is located.
Metadata Index/Count values are zero-based: the first element in any collection
has an index of 0 and the last element's index corresponds to the collection's length
minus 1.
Option flags
The flag value to enter should be the sum of all desired flags. So, a value of 11, which is 8+2+1,
means that behavior 8, 2 and 1 are applied.
A value of 0 means 'no flag'.
Name Value Behavior
GetAttribute 1 Search for the name argument in the attribute collection
instead of the default field collection. See: "Metadata" on
NoCascade 2 Search only the level specified by the path argument
(defaults to Page level when path argument is empty),
instead of default behavior, going from the Page level to
the Job level.
FailIfNotFound 4 Raise an error and crash the job is the specified name is
not found instead of returning an empty string.
SelectedNodesOnly 8 Returns values from the selected nodes only.
The Data Selector
The Data Selector is the tool you use to choose your sample data and metadata files, to select
the appropriate emulation, to make data selections, and to stabilize your data.
To open it:
Page 31
lChoose Debug > Select, on the menu.
lRight-click a task property that may contain variables (recognizable by the color of its field
label, which is maroon by default)and choose one of the Get Data ... or Get Metadata ...
lDebug your configuration and step through it until the option Debug > View Metadata
gets enabled. This happens when the metadata file has been created by a task in the
The Data Selector is divided in two tabs:Data and Metadata.
Data tab
The Data tab contains the Data Options, which let you select your emulation, and the Selector
Options, which let you personalize the data selector's display options (see Data Selector
Page 32
Display Preferences).
The Data Selector uses the 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. It displays the formatted data to let you make selections
easily using the mouse pointer.
Depending on the chosen emulation and data file, the options in the Data Selector, the Sample
data file section and the Data pane itself may change to accommodate your choice. The Line
Printer, Ascii, Channel Skip and User-Defined emulations will display the default options (see
the Emulation section)and a grid-like display of each character on each line. The following
emulations however, will be slightly different.
Database Emulation
lThe Database emulation changes the Browse button( ) for the Database Emulation
Configuration button ( ), which displays the Database Emulation Configuration (see
Database Emulation).
lOnce a database has been opened and query entered, the Data pane displays the results
of the SQLQuery in a grid format, which each line representing a single returned row from
the database. Each column represents a field returned by the query, with its field name as
a row header.
lXMLdata is represented in a tree structure which corresponds to the data in the XMLfile.
Each node of the XMLcan be expanded to see the nodes under it. See XML Data
PDF Emulation
lIf you use a PDF emulation, the Data pane displays the data as you would see it in any
lA new zoom drop-down list is displayed to let you set the zoom in percentage or fit the
PDFto the window or the width of the window.
lA new status bar, displaying the (Left, Top) and (Right, Bottom) coordinate pairs, is shown
under the Data pane.
Page 33
Metadata tab
The Metadata tab allows to load a metadata file and make a selection from it.
The Sample metadata filename is the path to the metadata file describing the current sample
data file. Buttons on the rightcan be usedto load metadata from a file or to save the current
metadata to a file.
To get a sample of the metadata file, debug your process and step through it until the option Debug
> 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 sample file. Click the
Open a meta data file button to open the sample in the metadata selector.
PlanetPress Design documents (unlike Connect Designer templates) are built to contain
metadata. PlanetPress Design users may therefore generate a metadata file for their active
sample data file, using a PlanetPress Design document:click the Create meta data file button.
The Generated PressTalk Expression shows the expression to retrieve the currently selected
attribute or field. Metadata are retrieved with the GetMeta() function (see "Metadata selections"
on page30). This expression is editable, which allows you to customize the string returned by
the metadata selector.
The wildcard parameter '?' indicates that the function operates on allnodes (not just one) of a given
level; see "Wild card parameter "?" " on page27.
The Enable search on multiple levels option is available when a metadata is selected under
Production information or User defined information. If it is not selected, the option flag includes
NoCascade (+2). For an explanation of option flags in the GetMeta() function, see "Option
flags" on page31.
Metadata level is a tree view allowing users to select the metadata level from which to display
or select metadata elements.
Page 34
The Production information list displays all metadata fields describing the current
metadatalevel,as selected in the Metadata Level tree view, for the current data page, as
selected in theData page box.
The User defined information lists all metadata fields defined by the user on the current
metadata level.
A number of the options in the Metadata Selector in PlanetPress Design 7 are no longer available in
the user interface of PlanetPress Workflow . However, when these settings are made in PlanetPress
Design 7, they will function as expected in PlanetPress Workflow 8.8.
AboutData Emulation
Emulations are like filters that can be used to read the data. When you create a document in
PlanetPress Design, you choose a sample data file and specify the emulation to use for the
chosen data. The emulation setting you choose will typically always be associated with that
document. If you choose a CSV (comma separated values) file and specify the corresponding
emulation, for instance, commas encountered in the data will typically be considered as value
Within PlanetPress Workflow, the same emulation tools as PlanetPress Design are available
throughout your process, using the Data Selector. One notable exception however is that User-
Defined Emulation is not available because it uses PlanetPress Talk code, which is not
available within PlanetPress Workflow Configuration Program.
The emulation that is used in your process can change during the process, and can be different
than the one used in any PlanetPress Design document used in your process. PlanetPress
Design documents use their own emulations, as defined in the document itself from
PlanetPress Design.
Emulations in PlanetPress Workflow:
lLine Printer
Page 35
lChannel Skip
PDFEmulation, also called Document Input, is only available in PlanetPress Workflow.
For more information about each emulation and how to use them, please refer to PlanetPress
Design User Guide.
Using the File Viewer
The File Viewer is like a Data Selector without any data related options, such as emulation
settings. It is displayed when doing a data selection from the Generic Splitter task (see
"Generic Splitter" on page377) with the Use Emulation option unchecked. The only data
formatting codes to which the File Viewer responds are line breaks.
For more information on the selecting data, see "The Data Selector" on page31.
Sample Data
PlanetPress Workflow is a versatile tool that can capture various types of data files and
dispatch this data to various PlanetPress Design documents. To fully understand PlanetPress
Workflow and how it treats data, you must understand how it is integrated into PlanetPress
This section covers issues relating to the sample data used to create your PlanetPress
Workflow configuration and to the actual data that PlanetPress Workflow will send to
PlanetPress Design documents. It is an important section which you should fully understand
before you start creating your configuration. Also included in this section are procedures that let
you make data selections as well as get data from the sample data file.
Since many of the concepts and explanations included in this chapter are closely related to
concepts and explanations found in the PlanetPress Design User Guide, we suggest that you
review this document, especially the Selecting an Emulation section.
Page 36
Choosing a Database Type Sample Data File
The procedure for selecting a sample data file that is in fact a database is the same as doing so
in PlanetPress Design. For more information, please see the relevant page in the PlanetPress
Design User Guide.
You can also use the PlanetPress Workflow Database action task to get data form a
database, and output in multiple different formats such as CSV. See "Database Query"
on page299.
Choosing a Sample Data File
In order to create your PlanetPress Workflow Process, the sample data you are going to use
has to correspond precisely to the job files that will be treated by that process, at least in terms
of structure.
The sample data file should have a relatively small number of pages (generally less than a
hundred)in order to be processed quickly, while your actual data may be much larger and take
more time to process. The sample data file should also contain at least one of every exception
you may want to detect, or data used for a specific condition. For example if you wanted to filter
out any data for clients in Canada, you would want to use a data file that has at least one user
from Canada, to test whether your condition removes it.
To choose a sample data file:
1. Click the Debug tab in the PlanetPress Workflow Ribbon.
2. Click on Select in the Data group.
3. Use the Data Selector to choose your sample data file and emulation options.
4. Click OK on the Data Selector.
PlanetPress Workflow also keeps the last 9 used data files in memory, which you can reopen to
use in the same process, or a different one.
Page 37
To reopen a sample data file used previously:
1. Click the Debug tab in the PlanetPress Workflow Ribbon.
2. Click on Reopen Data File in the Data group.
3. Click on one of the data files in the list.
4. Use the Data Selector to change the emulation options if necessary.
5. Click OK on the Data Selector.
Metadata is a hierarchical structure describing a job. Simply put, metadata is data about data
or, in other words, information tagged to data. Metadata includes information about the data file
itself, the document, custom user fields and in some cases page properties and page counts.
PlanetPress Workflow provides a whole series of plugins to create and edit Metadata within
processes (see "Metadata Tasks" on page509).
Applications or plugins created in PlanetPress Suite 6 and using metadata will need to
be updated for use in version 8.8. No backward compatibility mode is available.
When a user-defined emulation is used with metadata, results and behavior are unknown
and unsupported. For instance, refreshing the metadata file may cause the document to
crash and/or corrupt. For this reason, it is strongly advised to create backup copies of
your documents beforehand.
Metadata structure
The hierarchical structure of the metadata is composed of a number of basic levels for adding
information to the job. These levels are, from top to bottom:
Page 38
lJob: a file that contains 1 or more groups.
lGroup: a logical and ordered group of documents (ex: all invoices for a specific customer
number; all documents going to the same address, etc.).
lDocument: group of 1 or more ordered datapages intended to the same recipient from the
same source (ex: invoice).
lDatapage: 1 atomic unit of content that produces zero, one or more pages.
lPage: 1 side of a physical paper sheet.
When metadata is produced for a given job, a hierarchical (i.e. tree-like) structure is created,
composed of the above elements in the following order: Job > Group(s) > Document(s) >
Datapage(s) > Page(s). Any operation that modifies the data with regards to the structure (ex:
remove pages, alter the data, etc.) makes the metadata obsolete and so it must be recreated or
Metadata in OL Connect tasks
Although the metadata file created and maintained by OL Connect tasks looks the same as the
metadata file produced by other tasks, it is in fact different: it contains less information. Only the
first three levels in the metadata hold information about the job: Job,Group and Document. A
Group has information about a record set and a Document about one record. Datapage and
Page nodes are visible in the Metadata file, but in this case they don't contain any actual job
related information.
Taking this limitation into account, the Metadata related plugins (see "Metadata Tasks" on
page509) can be used in conjunction with OL Connect tasks nonetheless.
PlanetPress Design example
As an example, consider the typical case of a PlanetPress Design document which uses a Line
Printer data file of transactional data in order to generate PDF invoices for a series of clients. By
using the Metadata tools available in PlanetPress Workflow, the following information can be
added to the data file:
lThe job contains only invoices for clients located in Montreal.
lSince more than one invoice can go to the same recipient, invoices are grouped by
lEach invoice is a document resulting from the execution of a PlanetPress Design
document over one or more datapages, which results in zero or more physical pages
being output.
Page 39
A single JOB can be composed of GROUPS of DOCUMENTS, which themselves are
composed of physical PAGES produced by executing a PlanetPress Design document on one
or more DATAPAGES.
Metadata elements
Each metadata node (i.e. Job, Group, Document, etc.) is described with a series of elements,
that is, system-defined attributes or user-defined fields holding static or dynamic information
about the node they are attached to. Each element has a name and a value. More specifically,
here is a definition of these 2 types of elements:
lAttribute: A read-only, system-defined element which holds a certain information about a
certain node in the Metadata structure. This information can be static (e.g. the size of a
physical page) or evaluated on-the-fly (e.g. the number of documents in a group).
Attributes are non-repetitive (i.e. name is unique) and do not persist through metadata
lField: A read-write, user-defined element which holds custom information about a certain
node in the metadata structure. Fields are repetitive (i.e. the same field may appear
multiple times) and persist through metadata recreation.
Page 40
In addition to attributes and fields, each node of type group, document or datapage has a
Boolean property called 'selected' that indicates whether or not to produce the pages under that
node. By default, this property is set to true for all nodes.
Metadata attributes reference
The Metadata attributes are categorized as either Production, Finishing or Index/Count.
Production attributes describe the production of the job and/or metadata (e.g. path and name
of the datafile, date at which metadata was created, etc.)
Finishing attributes describe the finishing intent (e.g. page dimensions, page orientation,
duplex mode, etc.).
The presence of some finishing attributes depends on the PlanetPress Design document and target
device used when producing the job.
Index/Count attributes are not part of the original metadata file. They are evaluated live based
on the content of the metadata.
Metadata Index/Count values are one-based when viewed in the user interface: the first element in
any collection has an index of 1 and the last element's index corresponds to the collection's length.
However, in the API and in metadata selections, they are zero-based: the first element in any
collection has an index of 0 and the last element's index corresponds to the collection's length minus
1. This means the zero-based value has to be used when retrieving metadata (see also: "Metadata
selections" on page30 and Rule Interface).
In the following table, the last 5 columns indicate at which level the corresponding attribute is
available. This also depends on the type of job, however. In the metadata file created for an OL
Connect job, only three levels are filled with actual data about the job: Job, Group and
Page 41
Attribute Description Categor
DataEncoding (optional)
Name of the
DataFile (optional) Path
and name of
the data file
used by the
Date Date the
metadata was
created in ISO
Time Time the
metadata was
created in ISO
Title Title of the
Producer Name of the
software that
created the
Page 42
Attribute Description Categor
Creator Name of the
software that
created the
source of the
TargetDevice Name of the
device for
which the
metadata and
data is
Dimension Two floats
separated by a
indicating the
media size in
points (ex:
Orientation "Rotate0",
"Rotate180" or
rotated portrait
Page 43
Attribute Description Categor
and rotated
Side "Front" or
whether the
page is on the
front or the
back of the
paper sheet.
This attribute
is a "best
effort" and is
Duplex "None",
e" or
indicates a
change of the
duplex status.
InputSlot Device-
identifier of the
media source.
OutputBin Device- Finishin X X X X X
Page 44
Attribute Description Categor
identifier of the
Weight Device-
weight of the
MediaColor Device-
color of the
MediaType Device-
type of the
Index Index/C
IndexInDocument Returns the
index of the
node within all
the nodes
under the
Page 45
Attribute Description Categor
IndexInGroup Returns the
index of the
node within all
the nodes
under the
parent Group.
IndexInJob Returns the
index of the
node within all
the nodes
under the
parent Job.
Count Index/C
DocumentCount Index/C
DatapageCount Index/C
PageCount Index/C
SelectedCount Index/C
SelectedDocument Index/C X
Page 46
Attribute Description Categor
Count ount
Returns the
index of the
node within all
the selected
nodes under
the parent
Returns the
index of the
node within all
the selected
nodes under
the parent
Returns the
index of the
node within all
the selected
nodes under
Page 47
Attribute Description Categor
the parent Job.
NumCopies Indicates how
many times
the job is set
to execute, as
set when
printing using
a Windows
Author Name of the
user who
printed the job
initially, as
available in
the spool file,
and as the first
job info of the
capture input.
Metadata tasks
A set of special Workflow plugins allows to edit the metadata during a Workflow process. See
"Metadata Tasks" on page509.
Metadata Tools in PlanetPress Design
PlanetPress Design includes a complete set of metadata-related functionality, which can be
referred to as Metadata Tools. These tools can be used to generate metadata, retrieve or define
metadata elements, and build the metadata structure.
Using PlanetPress Design, one can:
Page 48
lGenerate metadata for any given sample datafile.
lGraphically retrieve the value of a metadata attribute or field for use in any design object.
lDefine documents and groups using any condition.
lDefine custom metadata fields.
lManipulate Metadata with PlanetPress Talk commands.
Following is a description of the Metadata tools which allow to perform the above tasks:
Metadata Generation using Data Capture with PlanetPress Printer
The Objectif Lune Printer Driver (PS) allows end-users to print directly to PlanetPress Design
from any Windows application, by using the familiar File|Print option. At the other end,
PlanetPress Design can capture the incoming stream and convert it internally into a PDF file
along with its metadata. By default, capturing a document input using a PlanetPress Printer will
generate a PDF along with its metadata.
Metadata Generation and Refresh without using PlanetPressPrinter
It is possible to generate or refresh metadata for any given sample datafile by using the Refresh
Metadata option available when right-clicking on the Metadata Fields folder found in the
Document Structure Window. For example, metadata can be generated this way for a Line
Printer sample datafile captured using an LPD Queue Input.
Metadata Selector
PlanetPress Design's Data Selector window allows to view and select metadata elements. It is
accessible by double clicking inside the Sample Data window or by clicking on the Open
Active Data button available in the ribbon. The Data Selector is equipped with a new tab
labeled Metadata.
Firstly, two buttons at the top right corner of this tab allows to load or save a metadata file
generated for the current sample datafile.
Secondly, the metadata tab graphically displays all elements (i.e. attributes and fields)
available at the current level (i.e. Page, Datapage, Document, etc.). More importantly, these
elements are graphically selectable, like any other part of the sample datafile when using the
'Select Data' option inside a Text object, for example.
Page 49
Metadata in document properties
Page 50
The Metadata tab in the properties of a PlanetPress Design document allows to easily define
documents or groups.
Metadata fields
The Metadata Fields in the structure of a PlanetPress Design document allow to easily define
documents or groups, by dragging and dropping data from the Sample Data directly onto the
document's Metadata Fields.
Data Repository
The Data Repository is a permanent structure to store data that can then be reused, modified or
augmented at a later time, by different processes.
This feature was introduced in version 8.5.
The Data Repository is especially useful in situations where data needs to be kept in between
processes. A few examples:
lAn HTTP-based authentication process, once it has validated user credentials, could
store session information (unique ID, user name, session starting time) into the repository.
All other related processes could then look into the repository to determine if a new
Page 51
request is received from an already authenticated user, if the session has expired, what
the user name is, etc.
lData comes in and is merged into a Capture OnTheGo template and stored in the Data
Repository. The end-user augments the data (using the COTG as a data-entry system).
The process that receives the augmented data could look into the Data Repository to
retrieve the original data (or the ID of the original data records) in order to augment,
modify or delete it.
As can be seen in the "Data Repository Manager" on page721, the Data Repository consists of
Groups, Keys and KeySets.
Feature Name Description Equivalent Database Terminology
Group A Group is defined by its Keys
(columns), and may contain 0 or
more KeySets (rows)within it.
Key A Key is defined only by its name.
The Data Repository only supports
STRING values and any data
inserted into it is converted to
string automatically. The maximum
size of a single key is 1 billion
KeySet Agroup may contain as many
KeySets (rows), which contain
variable data, as necessary. A
KeySet is inserted using the "Push
to Repository" on page331 task.
Lookup A method of retrieving one or more
KeySets from a group in the data
Page 52
Accessing the Data Repository
Via plugins
Storing data in the Data Repository
Data can be stored in the Data Repository using the Push to Repository task (see "Push to
Repository" on page331).
Retrieving data from the Data Repository
In any Workflow task where variable data is allowed (recognisable by the maroon field labels),
information can be retrieved from the Data Repository using a Lookup function. Right-click a
field with a maroon label and select Get Repository Location. This will bring up the "Data
Repository Manager" on page721. Select a Group, Key and KeySet entry to determine which
value or values should be retrieved at runtime; then click OK. The Lookup Function Syntax,
displayed at the bottom left of the Data Repository Manager, will be copied into the field.
The syntax is of the Lookup function is:
Lookup(Group_Name, Key_To_Retrieve, Key_To_Match, Value_To_Match)
This function may also be used anywhere else where the contextual menu gives access to it.
You could, for example, use it on the General tab of the Create File task, to fill in the value of a
key/value pair in a JSON string.
The Data Repository Manager displays, at the bottom left, the syntax used for accessing a specific
In a script you can access the Data Repository using the "Data Repository API" on page121.
For a quick start, turn to this How-to: Interacting with the Data Repository API.
Data Repository Manager
At design-time, the Data Repository Manager may be used to insert or remove Groups, Keys
and KeySets; see "Data Repository Manager" on page721.
Page 53
Where to find the Data Repository
In case the Repository contains valuable information that must not be lost in case of a hardware
failure, create a backup of the repository.
The Data Repository is located in the following folder:
%ProgramData%\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Repository.
About Documents
A Document is a file sent to PlanetPress Workflow by PlanetPress Design and is used to
produce an output when merged with data. ADocument can be an invoice, a report, a receipt or
anything else, but by itself it is empty and without any variable data.
Document are typically selected in Output Tasks, but can also appear in other tasks that
produce formatted data such as the Digital Action task and the Add Document task.
Documents contain static data such as logos, addresses and graphic formatting, as well as
placeholders for data. Documents can also contain conditions and programming logic. For
more information about PlanetPress Design documents, please see the PlanetPress Design
User Guide.
Import Documents
This procedure describes how to import variable content documents created in PlanetPress
Design. Importing documents can be useful when transferring configurations between
PlanetPress Workflow installations.
To import documents into PlanetPress Workflow:
1. Choose File | Import Documents. The Import PlanetPress Design Document dialog
box appears.
2. In the File type box, select the desired file type.
3. Navigate to the document you want to import, select it and click Open.
Page 54
The document is imported and displayed in the Configuration Components pane. This
physically installs the documents to the Documents folder relative to the install folder of
PlanetPress Workflow.
Import PrintShop Mail Documents
This procedure describes how to import variable content documents created in PrintShop Mail.
Importing documents can be useful when transferring configurations between PlanetPress
Workflow installations.
To import documents into PlanetPress Workflow:
1. Click the PlanetPress Workflow button. The Import PrintShop Mail Document dialog
box appears.
2. Choose Import, then PrintShop Mail Documents.
3. Navigate to the document you want to import, select it and click Open. The document is
imported and displayed in the Configuration Components pane. This physically installs
the documents to the Documents folder relative to the install folder of PlanetPress
Debugging and Error Handling
This chapter touches on two subjects that are intrinsically linked, though their use is different.
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.
Error Handling, on the other hand, occurs when your configuration has been sent to
PlanetPress Workflow services, and are running in "production"mode. On one hand the
manual task is critical when creating a process, on the other the automated handling of errors
within your processes will have a large impact on recovering from errors as they happen during
About Error Handling
When your process is running, or during debugging, it may happen that the task that is currently
running causes an error, and the task fails. For example, when trying to save to a folder that
Page 55
does not exist, or printing to a printer that cannot be found.
When such an error occurs, in most cases you would want to be aware of it and to take certain
actions in order to correct or report the error. This is where our error handling features come in
Most of the tasks, branches and conditions included in your process can have their own error
handling behavior, with the exception of Comments, the Input Error bin task, and older legacy
tasks from previous versions of PlanetPress Workflow that did not have error handling.
By default, when an error occurs, the task is skipped and the unmodified job file is passed on to
the next task. You can overwrite this behavior by changing the options of the On Error tab of
the task.
Using the On Error tab
Whenever an error is triggered either during debugging or when a process runs in production,
the settings specified in the On Error tab of the task that generated the error will be used to
determine a course of action.
On Error Tab
The On Error tab is common to all tasks. Details can be found in the" Task Properties Dialog"
on page777.
By default, any action task, branch, splitter or condition that generates an error will simply be
ignored, and the task just under it (not within a branch)will be given control of the job file
without any modification. Any initial input task that generates an error will stop the process from
running as a whole, and output tasks will not generate output. The On Error tab can be used to
overwrite the default behaviors.
lSend to Process: Check this option to send the job file to an error management process.
lError Process drop-down:Enabled only when the Send to Process option is checked.
Lists any process of which the initial input task is the Input Error Bin task.
lAction:In the initial input tasks, this group is disabled and defaults to Stop Process. In
all other tasks where the On Error tab is present, the following options are available:
lDefault:By default, the task is ignored as if it did not exist and the error is logged
before continuing the branch or process; the job file is passed on to the next task in
Page 56
the process. When an error occurs in a loop (or in a plugin that acts like a loop), the
loop may log the error, terminate the current iteration and proceed with the next
lStop Branch:If the task is in a branch of the process, the branch is stopped and the
job file is returned to the process after the branch. The branch will not produce any
output. If the task is not on a branch, the entire process will be stopped.
lStop Process:The process is stopped and no more processing is done. No further
output is produced.
lLog Message:Check this option to enable logging a custom error message in the
PlanetPress Workflow log file and in the Windows Application Events.
lMessage:Enabled only when the Log Message option is checked. Enter a message that
will be logged in the PlanetPress Workflow log file. You can use any variables available
in PlanetPress Workflow to customize the message.
lStore the message in variable:Select in which jobinfo, local or global variable you
want to store the message content.
lID:Enter an error ID. This IDwill be visible in the Windows Event Viewer. However, the
IDis not visible in the PlanetPress Workflow log file.
lStore the IDin variable:Select in which jobinfo, local or global variable you want to
store the error ID.
lReset to defaults:Resets all options in this tab to their default values.
When storing the message or ID, if they are stored in a jobinfo they will be available in any
error handling process where errors are being forwarded. If your process continues after the
error, the contents of the variables selected in this window will be available to the rest of your
process, or as long as they are not overwritten.
Common Errors
Though some error messages are specific to a task in particular, others may apply to any and
all tasks because they are related more to the system than to PlanetPress itself. Some
examples would be W3813,W3830,W3991,W4005. These correspond to issues such as not
having any space to write files, permission errors on folders or files, etc.
Creating and Using Error Processes
An Error Process is a special type of process that never runs on its own, and cannot be called
using the GoSub or Send to Process tasks. It can only be used in the On Error tab of a task in
Page 57
your process, and will be triggered if the Send to Process option is checked in that tab and an
error process is selected in the drop-down list.
To create an error process, simply replace the initial input task by the InputErrorBin input task,
and that process automatically becomes able to handle error jobs sent to it. It is up to you,
however, to decide how that error job will be handled.
For example, you could place the job file in a specific folder, then send an email to a supervisor
indicating that a job has failed. Or you could update a database with an error status so that it
appears on a customer's online order. You could also zip the order up and send it to an
administrator, while simultaneously advising the person that sent the job that it failed.
You can have as many error processes as you can normal processes - that is, you are limited to
512 processes, subprocesses, startup processes and error processes combined.
The following information is available from within your information process when it is
lJob Information variables (%1 to %9)
lThe data file as it was before starting the task
lGlobal variables (which are, of course, available anywhere)
lAseries of variables containing information about the error, the task that triggered it and
the process that contained it. See "Standard Variables" on page646
Local variables in the process are not sent to error processes, even if the error process has a variable
of the same name.
Accessing the Logs
If your process is running live in PlanetPress Workflow service, you have two ways of seeing
what is happening, now or in the past.
Page 58
To view what processes are running and processing data as it happens:
1. In the PlanetPress Workflow Ribbon, click on the Tools tab, then select Service Console
in the Services group. The PlanetPress Workflow Service Console opens.
2. Click on the service you want to check, including:
lPlanetPress Workflow
lTelnet Capture
lSerial Capture
lPlanetPress Image
lPlanetPress Fax
lPlanetPress Messenger
3. When any job or file is processed by the selected service, the processing logs will be
displayed in the window on the right.
The information that is displayed here is the same as in PlanetPress Workflow logs and
depends on the logging level that you set in the "General and logging preferences" on
To view logs for jobs that have already processed
By default, the logs are available in the following folder:
C:\Documents and Settings\All Users\Application Data\Objectif Lune\PlanetPress
7\PlanetPress Watch\Log
You can access this folder more quickly by using this procedure:
Page 59
1. From PlanetPress Workflow Configuration software, press CTRL+SHIFT+ALT+F4
simultaneously. The PlanetPress Workflow working folders are opened.
2. Double-click on the folder called Log.
3. There are multiple logs displayed here, including:
lppwYYYYMMDD.log - PlanetPress Workflow logs, including the year, month and
day of the log (from midnight to midnight).
lFTP, LPD, LPR, ??? (to be verified)
The PlanetPress Image and PlanetPress Fax logs are available in different folders. From
the Watch folder, go up one level then go in either folders, under which you will find the
Log folder for that specific software within the suite.
Resubmit Backed Up Input Files to a Process
Each input task includes an option that lets you back up input files. This options is not selected
by default, since it has the potential to generate a very large number of back up files. To turn on
the backup option of an input task, simply open its properties, go to the Other tab and check the
Backup input files option, then type in a unique file name for the backup file (this should be
But if, for a given input task, you did select this option and something goes wrong and an
original input file is lost or corrupted, you will have the option to use the Resubmit Job
command to pull the backed up input file into the process.
Granted that you have back up copies of the files polled by an input task, you may resubmit
them as required. The PlanetPress Workflow Configuration gives you the option to resubmit
them as they were submitted originally (polled by the initial input task) or to submit them to
those tasks located on the index you select.
Page 60
The numbers on the left indicate the task index, the folder capture being level 1 and the Text
condition being on level 4.
To resubmit backed up input data files:
1. In the PlanetPress Workflow Ribbon, go to the Tools tab then click Resubmit Job in the
Services group. The File Resubmission dialog box is displayed.
2. From the Process box, select the process for which you want to resubmit the backed up
input files.
3. From the Task index box, select the index level to which you want the data to be sent.
The index is the position in the process where you want to submit the job file.
4. In the list of backed up input files, select the file you want to resubmit.
5. Using the From page and To page boxes, select the data pages that you want to
resubmit. If you want to resubmit all the data pages from the selected input file, enter 0 in
both boxes.
6. Click Send to resubmit the data.
7. To resubmit backed up input files for the same process or for a different one, repeat step 2
to step 6.
8. To close the File Resubmission dialog box, click Close.
Page 61
The From page and To page boxes are only useful for printer queue (or printer
capture)inputs. They will not function for other types of inputs. In these cases, the
complete backup job is submitted.
Knowing What to Resubmit
When something goes wrong with an output job, a print job for instance, and printouts are lost,
you usually need to know the following information in order to resubmit the input:
lThe name of the job. This refers to the name used internally by PlanetPress Workflow.
This name is generated by the input task using parameters defined within the task. To
simplify file identification, you should consider using names that include both the name of
the original input file (if any) plus some details such as the current date and time.
lThe number of each failed page. If a job contains 1000 pages and if pages 1 to 950 were
printed correctly, you need not resubmit the entire job, but only the 50 last pages.
But finding this information often poses a problem. A good way to find this information easily is
to print it using small characters at the bottom of every page. To do this, you have to do the
In PlanetPress Design:
1. Use a Set Job Info action task and associate a variable with the job’s name.
2. In the output task, make sure to select the option that adds the job information to the
In PlanetPress Connect:
lSomewhere at the bottom of each document page, add a Data Selection object defined
as a custom data selection that contains a reference to the job info variable sent from
PlanetPress Workflow and a current page marker.
You can use, for example, =&watch.jobinfos[6]+'-'+intostr(&current.datapage)'
Page 62
Debugging your PlanetPress Workflow Process
Debugging a process is separated in two parts. The first part is designing the process, which is
to add the different tasks, branches and conditions to the process and configuring them. The
second step is testing whether or not the process and configuration actually work.
Before debugging begins, the following prerequisites must be completed:
lThere must not be any Unknown Tasks in the process.
lAsample data file must be selected.
To choose a sample data file, click the Select button in the PlanetPress Workflow
Ribbon's Debug tab and browse to a valid sample data file.
Alternatively, if a document present in the configuration contains the necessary data file, it
can be attached to the process easily. For example to use a sample data file included in a
Connect data mapper configuration: select Connect Resources > Data Mapping
Configurations > [your data mapping configuration], right-click a data file and choose
Set as sample data file.
How to do this with Planet Press Suite Design Documents is explained here: Use Data
and Metadata Files Attached to Documents.
When debugging your process, it is important to keep in mind that:
lThe Initial Input task is never executed. The sample data file is used instead of the initial
run. This is to prevent "live"data from being retrieved by the initial input task while
debugging is being done. If, however, the initial task is critical to the process, it can be
executed by copying the initial input task and pasting it as a secondary input task (the first
action task to actually run in the process). Do not forget, however, to remove this duplicate
task before saving the configuration!
lSince the initial input task is not performed, there is no actual job information to be added
at the beginning of a data file. Note that you can use the Object Inspector on your
process to enter sample job information as required.
lIf any task makes an operation on the system (for example, capturing files, sending data,
printing, etc), it is actually executed, not simulated.
lAny task is executed with the permissions of the user that is currently running the
PlanetPress Workflow Configuration Tool. When running in service mode, the user
configured in the Configure Services dialog is used instead and this may lead to
unexpected behaviors. Please See "Workflow Services" on page702 for more details.
Page 63
The sample job file should generally be the exact same format as the data that you will
receive when PlanetPress Workflow is processing the job at run-time. For more
information on how to capture your sample data file properly, please refer to the
PlanetPress Trigger and Data Capture Guide.
Debugging can be run in different ways:
lFrom the Debug tab, click on Step. This executes only the first task in the process and
waits for further action.
lFrom the Debug tab, click on Run. This executes the complete process, step by step,
until it is completed.
lRight-click on any task in the process and click Run from Here or Step from Here.
These actions are the same as using the debug Step and Run buttons, but will execute
the process only starting from that task forward.
While stepping through a process (using Step, not Run):
lDouble-click on any task to change its properties. If you change the properties of a task
before you step through it, those new properties will be used when the task is executed.
Note that you cannot modify the process itself while in debug mode (you cannot add,
delete or move tasks, change branches and conditions, etc).
lClick on Skip to ignore the next task or branch and go to the next one. The job file is not
modified in any way.
lClick on View as Text in the Data group of the Debug tab to view the current job file
using a text editor (Notepad by default).
lClick on View as PDFto view the current job file in Adobe Acrobat if it is present (this will
work only for PDFjob files).
lClick on View Metadata to open the data selector and see the current state of the
process' Metadata.
lClick on View as Hex to view the current job file in the internal Hex editor.
lClick on the Stop button to stop the debugging process. If you use Run,Step or Skip
after stopping the process, debugging starts over from the top.
Page 64
lUse the Set Breakpoint button to tag the currently selected task, branch or condition as a
breakpoint. When you click Run in your process, the process will execute every task until
it reaches a breakpoint and will stop just before the task that is set as a breakpoint.
lUse the Ignore button to disable the task, branch or condition that is currently selected. If
you disable a branch or condition, all tasks inside that branch or condition are ignored
including the output. Note that if you set a task, branch or condition to be ignored, it will
also be ignored at run-time, providing you sent the configuration to the service.
lLook at the Messages Area pane to see any message generated by the tasks that run
(See " The Message Area Pane" on page726).
lUse the Debug Information pane to see the current value of any variable in your process
or globally, or to evaluate custom expression. See "The Debug Information Pane" on
Debugging and Emulation changes
One of the most useful case where debugging is crucial is whenever the job file is converted to
another type of emulation, or if a new data file of a different emulation is used within the
process. For example, if a process starts with a Line Printer data file and the converts it into a
PDF, it is not possible to do any data selection on the PDFbecause the Line Printer emulation
is active by default. The debugging features can easily resolve this limitation.
The first method is used if your process has all the required tasks, but data selections after an
emulation change are necessary.
lStep through the process until you have reached the point after the emulation or data
lAny data selection used in task properties after this point will use the new emulation.
lContinue stepping through each task until the end of the process to debug it.
This method does not allow you to add, remove or move tasks, however. The second method
can be used when that is required.
lStep through the process in debug mode until you reach the emulation or data change.
lClick on View as Text (or View as PDFif your data is PDF at this point) in the Data group
of the Debug tab.
lIn the viewer that appears, save the file to a location on your hard drive.
lStop the process, and select the file you saved as your process' data file.
Page 65
lIf you need to continue debugging your process after the emulation change, you can still
do it by using Skip on all the tasks until the emulation change, inclusively. Then use Step
or Run to continue debugging.
Lastly, PlanetPress Workflow 7.4 and higher also has an option that can be used in conjunction
with the previous to avoid skipping through large processes:
lStep through the process until the emulation or data change, as in the first method.
lSave the data file locally and then select it as your sample data file, as with the second
lInstead of skipping through each task, use the Run from here or Step from here options,
either from the Debug tab or by right-clicking on the task where you want to start the
Once you have created and fully debugged all your processes, you will be ready to send it to
PlanetPress Workflow service. See "Saving and Sending" on page656.
The Plug-in Bar
PlanetPress Workflow offers a constantly increasing number of plugins, while always allowing
third party plugins to be installed and set up to be used by PlanetPress Workflow. The
PlanetPress Workflow Plug-in Bar lists all plugins available in PlanetPress Workflow, and is
divided into categories, which users can customize at will.
Most of the PlanetPress plugins are installed by default, but other plugins may be added.
Because the plugins are always expected to execute some sort of task, they are always
referred to, in this documentation, as tasks, except in the specific case of importing a new
plugin or customizing the Plug-in Bar.
The default categories list plugins according to what type of task they achieve. When first
starting your PlanetPress Workflow program, the following categories are used:
Page 66
lData splitters
lProcess logic
lPlanetPress Capture
lMetadata Related
lOL Connect Send
lOL Connect
An Uncategorized category is dynamically created if your PlanetPress Workflow finds any plugin
that would not be part of the existing Plug-in Bar. User-defined plugins and third party application
plugins falls into such a category.
Settings & Customization
The Plug-in Bar can be customized according to your needs and the plugins you most
frequently used.
You can use the horizontal dark blue bar separating the plugin area and the list of categories to
change how many plugin categories are displayed as the full-width bar with the title, and how
much are displayed as icon only. Move the bar up to display more full-width categories, or
down to display them more as icons.
Furthermore, the Plug-in Bar can be customized using the popup indicator control ( ).
Customizing the Plug-in Bar is mostly used for third party or legacy plugins.
Using the contextual menu displayed by the popup indicator, you can:
lInsert, delete and rename custom categories.
lMove categories up or down.
lImport third party or legacy plugins.
Page 67
lMove plugins from one custom category to another (that you cannot move default plugins
from the default categories, you can only copy them)
lCopy plugins from one custom category to another by holding the CTRL key.
lDelete plugins from any custom category by using the Delete key.
lRevert to the default Plug-in Bar by selecting Reset to default.
To import a plugin:
1. Click on the popup control ( ).
2. Click on Import Plugin.
3. Browse to the location of the plugin DLLfile.
4. Click on Open.