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
Syntax
Note
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.
GetMeta(Field Name [, Option Flags, Metadata Path])
Here is a breakdown of the syntax:
l GetMeta():Always surrounds metadata selections.
l Field/Attribute Name:specifies the name of the field (or attribute, if the GetAttribute
option flag is set) to retrieve (see "Metadata" on page39).
l Option Flag (optional):Sets the options for the selection (see table below).
l Metadata Path (optional):Defines the precise path where the Metadata Field is located.
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
page39.
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.
Page 31
Name Value Behavior
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:
l
Choose Debug > Select, on the menu.
l Right-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 ...
options.
l
Debug 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
process.
The Data Selector is divided in two tabs:Data and Metadata.
Page 32
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
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
Page 33
the Emulation section)and a grid-like display of each character on each line. The following
emulations however, will be slightly different.
Database Emulation
l
The Database emulation changes the Browse button( ) for the Database Emulation
Configuration button ( ), which displays the Database Emulation Configuration (see
Database Emulation).
l
Once a database has been opened and query entered, the Data pane displays the results
of the SQLQuery 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.
XMLEmulation
l XMLdata is represented in a tree structure which corresponds to the data in the XMLfile.
Each node of the XMLcan be expanded to see the nodes under it. See XML Data
Emulations.
PDF Emulation
l
If you use a PDF emulation, the Data pane displays the data as you would see it in any
PDFreader.
l A 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.
l A new status bar, displaying the (Left, Top) and (Right, Bottom) coordinate pairs, is shown
under the Data pane.
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 rightcan be usedto load metadata from a file or to save the current
metadata to a file.
Page 34
Tip
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
Tip
The wildcard parameter '?' indicates that the function operates on allnodes (not just one) of a given
level; see "Wild card parameter "?" " on page27.
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 page30). This expression is editable, which allows you to customize the string returned by
the metadata selector.
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 page31.
Metadata level is a tree view allowing users to select the metadata level from which to display
or select metadata elements.
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 theData page box.
The User defined information lists all metadata fields defined by the user on the current
metadata level.
Page 35
Note
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 2018.1.
About data emulation
Note
Even during debugging, selecting a sample data file with a different format will cause the emulation
of a process to change. In order to avoid errors, change the emulation back to the format of the
original input file before using the process again.
An emulation is like a filter that can be used to read data. It specifies how to interpret a data file.
If the emulation is set to CSV (comma separated values), for instance, commas encountered in
the data will typically be considered as value separators.
Every Workflow process has its own data emulation setting, which depends on the sample data
file you choose.
A process's data emulation is only visible in the Workflow configuration tool when using the
Data Selector e.g. to select a sample data file, but it is always set to one.
It can be changed either by choosing another sample data file (see "Choosing a sample data
file" on the next page) or by inserting a "Change Emulation" on page267 task in the process.
Changing the emulation is particularly important if you want to make a data selection in a file
after it has been changed to another format. (See "Data selections" on page26.)
Emulations in PlanetPress Workflow:
l Line Printer
l ASCII
l CSV
l Channel Skip
l Database
l XML
l PDF
Page 36
Emulations in PlanetPress Design
The Data Selector in Workflow is essentially the same as the one used in PlanetPress Design.
When you create a document in PlanetPress Design, you choose a sample data file and
specify the emulation to use for the chosen data. Within PlanetPress Workflow, the same
emulation tools as in 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 the 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.
For more information about emulations in PlanetPress Design see PlanetPress Design User
Guide.
Sample Data
This topic covers issues relating to the sample data used in your PlanetPress Workflow
configuration.
A sample data file makes it possible to:
l Create a process that retrieves dynamic data from a data file. Once a sample data file is
available, you can use it to make data selections in a process (see "Data selections" on
page26).
l Debug a process (see "Debugging your PlanetPress Workflow process" on page63).
To interpret a sample data file correctly, a process must have the corresponding emulation
setting; see "About data emulation" on the previous page. This is particularly important for
selections that have to be made in a data file after it has been changed to another format.
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.
Page 37
The sample data file should have a relatively small number of records (generally less than a
Tip
Double-clicking on the data file does the same thing as right-clicking on it an then selecting Set as
sample data file. Clicking Cancel instead of OK after viewing will prevent this action from being
taken.
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 (see "The
Data Selector" on page32).
4. Click OK on the Data Selector.
Alternatively, if a resource file present in the configuration contains the necessary data file, it
can be attached to the process easily:
1. Expand the relevant resource files folder (Connect Resources or PPS/PSM Documents)
by clicking the button.
2. Expand the file by clicking the button.
3. Right-click on the data file, then click Set as sample data file.
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.
About attached Metadata (PlanetPress Suite)
When a Design document uses Metadata, it can also be attached with the document. One
Metadata file is generated for each data file attached to the Design document. Metadata does
Page 38
not appear in the Configuration Components pane but it follows the data file and can be viewed
Note
Applications or plugins created in PlanetPress Suite 6 and using metadata will need to
be updated for use in version 2018.1. No backward compatibility mode is available.
Warning
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.
from the Metadata tab whenever the data file is viewed through the Data Selector.
Opening a previously used data file
PlanetPress Workflow also keeps the last 9 used data files in memory, which you can reopen to
use in the same process, or in a different one.
To reopen a sample data file:
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
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 page422).
Page 39
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:
l
Job: a file that contains 1 or more groups.
l
Group: a logical and ordered group of documents (ex: all invoices for a specific customer
number; all documents going to the same address, etc.).
l
Document: group of 1 or more ordered datapages intended to the same recipient from the
same source (ex: invoice).
l
Datapage: 1 atomic unit of content that produces zero, one or more pages.
l
Page: 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
refreshed.
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
page422) 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:
Page 40
l The job contains only invoices for clients located in Montreal.
l Since more than one invoice can go to the same recipient, invoices are grouped by
customer.
l Each 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.
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:
l
Attribute: 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).
Page 41
Attributes are non-repetitive (i.e. name is unique) and do not persist through metadata
Note
The presence of some finishing attributes depends on the PlanetPress Design document and target
device used when producing the job.
Note
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 page30 and Rule Interface).
recreation.
l
Field: 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.
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.).
Index/Count attributes are not part of the original metadata file. They are evaluated live based
on the content of the metadata.
Page 42
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
Document.
Attribute Description CategoryJ
DataEncoding (optional)
Name of the
character
encoding.
DataFile (optional) Path
and name of
the data file
used by the
PlanetPress
Design
Document.
ProductionX X X
ProductionX X X
Gro
o
b
up
Docum
ent
Datap
age
Pa
ge
Date Date the
metadata was
created in ISO
format.
Time Time the
metadata was
created in ISO
format.
Title Title of the
source
document.
Producer Name of the Producti X X X
ProductionX X X
ProductionX X X
ProductionX X X
Page 43
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
software that
created the
metadata.
Creator Name of the
software that
created the
source of the
metadata.
TargetDevice Name of the
device for
which the
metadata and
o
b
on
ProductionX X X
ProductionX X X
up
ent
age
ge
associated
data is
intended.
Dimension Two floats
separated by a
colon
indicating the
media size in
typographical
points (ex:
612:792).
Orientation "Rotate0",
"Rotate90",
"Rotate180" or
"Rotate270",
Finishin
g
Finishin
g
X X X X X
X X X X X
indicating
Page 44
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
respectively
portrait,
landscape,
rotated portrait
and rotated
landscape.
Side "Front" or
"Back";
indicates
whether the
page is on the
front or the
back of the
Finishin
g
o
b
up
ent
age
ge
X
paper sheet.
This attribute
is a "best
effort" and is
devicedependent.
Duplex "None",
"DuplexTumbl
e" or
"DuplexNoTu
mble";
indicates a
change of the
duplex status.
InputSlot Device-
Finishin
g
Finishin
X X X X X
X X X X X
dependent
g
Page 45
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
identifier of the
media source.
OutputBin Device-
dependent
identifier of the
media
destination.
Weight Device-
dependent
weight of the
media.
Finishin
g
Finishin
g
o
b
X X X X X
X X X X X
up
ent
age
ge
MediaColor Device-
depedent
color of the
media.
MediaType Device-
dependent
type of the
media.
Index Index/C
IndexInDocument Returns the
Absolute
index of the
node within all
Finishin
g
Finishin
g
ount
Index/C
ount
X X X X X
X X X X X
X X X X
X X
the nodes
Page 46
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
under the
parent
Document.
IndexInGroup Returns the
Absolute
index of the
node within all
the nodes
under the
parent Group.
IndexInJob Returns the
Absolute
Index/C
ount
Index/C
ount
o
b
up
X X X X
ent
X X X
age
ge
index of the
node within all
the nodes
under the
parent Job.
Count Index/C
ount
DocumentCount Index/C
ount
DatapageCount Index/C
ount
PageCount Index/C
ount
X X X X
X
X X
X X X
Page 47
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
SelectedCount Index/C
ount
SelectedDocument
Count
SelectedDatapage
Count
SelectedPageCoun
t
SelectedIndexInDo
cument
Returns the
Absolute
index of the
Index/C
ount
Index/C
ount
Index/C
ount
Index/C
ount
o
b
X X X X
X
X X
X X X
up
ent
age
X X
ge
SelectedIndexInGr
oup
SelectedIndexInJo
b
node within all
the selected
nodes under
the parent
Document.
Returns the
Absolute
index of the
node within all
the selected
nodes under
the parent
Group.
Returns the
Absolute
Index/C
ount
Index/C
ount
X X X
X X X X
Page 48
Attribute Description CategoryJ
Gro
Docum
Datap
Pa
index of the
node within all
the selected
nodes under
the parent Job.
NumCopies Indicates how
many times
the job is set
to execute, as
set when
printing using
a Windows
Index/C
ount
o
b
X
up
ent
age
ge
driver.
Author Name of the
user who
printed the job
initially, as
available in
the spool file,
and as the first
job info of the
Windows
capture input.
Metadata tasks
A set of special Workflow plugins allows to edit the metadata during a Workflow process. See
"Metadata Tasks" on page422.
ProductionX
Page 49
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:
l Generate metadata for any given sample datafile.
l Graphically retrieve the value of a metadata attribute or field for use in any design object.
l Define documents and groups using any condition.
l Define custom metadata fields.
l Manipulate 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.
Page 50
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 51
Metadata in document properties
The Metadata tab in the properties of a PlanetPress Design document allows to easily define
documents or groups.
Metadata fields
Page 52
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:
l An 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
request is received from an already authenticated user, if the session has expired, what
the user name is, etc.
l Data 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.
Structure
As can be seen in the "Data Repository Manager" on page598, 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.
Table
Column/Field
The Data Repository only supports
Page 53
Feature Name Description Equivalent Database Terminology
STRING values and any data
inserted into it is converted to
string automatically. The maximum
size of a single key is 1 billion
bytes.
KeySet Agroup may contain as many
KeySets (rows), which contain
variable data, as necessary. A
KeySet is inserted using the "Push
to Repository" on page301 task.
Lookup A method of retrieving one or more
KeySets from a group in the data
repository.
Row/Record
Query
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 page301).
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 page598. 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')
Page 54
Note
Value_To_Match can be a static string a jobInfo or a variable but not a data selection.
For the Value_To_Match parameter, the single-quotes surrounding the value are
mandatory even if the value is dynamic.
This function may also be used anywhere else where the contextual menu gives access to it.
Tip
The Data Repository Manager displays, at the bottom left, the syntax used for accessing a specific
value.
Note
Lookup()returns NODATA when the group and/or key does not exist.
In previous versions of the software, trying to do a look-up in a non-existent group and/or key
would cause an error. This change in behavior may affect any Workflow configuration that uses an
on error process related to invalid groups/keys.
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.
Scripts
In a script you can access the Data Repository using the "Data Repository API" on page122.
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 page598.
Page 55
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.
By default, the Data Repository is located in the following folder:
%ProgramData%\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Repository.
It is also possible to create a Repository at a custom location; see ConnectionString.
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
production.
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
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
handy.
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
Page 56
the process - which sets the default error handling behavior for all the tasks in that process - or
of an individual 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 and processes. It can be found in the" Task Properties
dialog" on page654.
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.
l Send to Process: Check this option to send the job file to an error management process.
l
Error 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.
l Action: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:
l Default: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
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
iteration.
l Stop 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.
l Stop Process:The process is stopped and no more processing is done. No further
output is produced.
l Log Message:Check this option to enable logging a custom error message in the
PlanetPress Workflow log file and in the Windows Application Events.
Page 57
l
Message: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.
l
Store the message in variable:Select in which jobinfo, local or global variable you
want to store the message content.
l
ID:Enter an error ID. This IDwill be visible in the Windows Event Viewer. However, the
IDis not visible in the PlanetPress Workflow log file.
l
Store the IDin variable:Select in which jobinfo, local or global variable you want to
store the error ID.
l Reset 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.
All error codes are listed in the Connect knowledge base. 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 Workflow 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
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.
Page 58
You can have as many error processes as you can normal processes - that is, you are limited to
Note
Local variables in the process are not sent to error processes, even if the error process has a variable
of the same name.
512 processes, subprocesses, startup processes and error processes combined.
The following information is available from within your information process when it is
triggered:
l Job Information variables (%1 to %9)
l The data file as it was before starting the task
l Global variables (which are, of course, available anywhere)
l Aseries of variables containing information about the error, the task that triggered it and
the process that contained it. See "Standard Variables" on page514
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.
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:
l PlanetPress Workflow
l LPDServer
l Telnet Capture
l Serial Capture
l HTTP/SOAP Server
l LPRClient
l FTPClient
Page 59
l PlanetPress Image
Note
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
page627.
Note
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.
l PlanetPress Fax
l PlanetPress 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.
To view logs for jobs that have already processed
By default, the logs are available in the following folder:
C:\ProgramData\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Log
You can access this folder more quickly by using this procedure:
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:
l ppwYYYYMMDD.log - PlanetPress Workflow logs, including the year, month and
day of the log (from midnight to midnight).
l FTP, LPD, LPR, ??? (to be verified)
Page 60
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
variable).
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.
The numbers on the left indicate the task index, the folder capture being level 1 and the Text
condition being on level 4.
Page 61
To resubmit backed up input data files:
Warning
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.
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.
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:
l The 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.
l The 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.
Page 62
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
following.
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
document.
In PlanetPress Connect:
l Somewhere 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(¤t.datapage)'
Debugging your PlanetPress Workflow process
After designing a process, which is to add the different tasks, branches and conditions to the
process and configuring them, you can test whether or not the process and configuration
actually work.
Before debugging begins, the following prerequisites must be completed:
l There must not be any Unknown Tasks in the process.
l Asample data file must be selected; see "Choosing a sample data file" on page37.
When debugging your process, it is important to keep in mind that:
l
The 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!
Page 63
l Since the initial input task is not performed, there is no actual job information to be added
Note
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.
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.
l If any task makes an operation on the system (for example, capturing files, sending data,
printing, etc), it is actually executed, not simulated.
l Any 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 page582 for more details.
Debugging can be run in different ways:
l
From the Debug tab, click on Step. This executes only the first task in the process and
waits for further action.
l
From the Debug tab, click on Run. This executes the complete process, step by step,
until it is completed.
l Right-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):
l Double-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).
l Click on Skip to ignore the next task or branch and go to the next one. The job file is not
modified in any way.
l Click 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).
Page 64
l Click on View as PDFto view the current job file in Adobe Acrobat if it is present (this will
work only for PDFjob files).
l Click on View Metadata to open the data selector and see the current state of the
process' Metadata.
l Click on View as Hex to view the current job file in the internal Hex editor.
l Click 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.
l Use 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.
l Use 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.
l
Look at the Messages Area pane to see any message generated by the tasks that run
(See " The Message Area Pane" on page603).
l
Use 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
page602.
Debugging and Emulation changes
One of the most useful cases 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 then converts it into a
PDF, it is not possible to do any data selection on the PDFbecause 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.
l Step through the process until you have reached the point after the emulation or data
change.
l Any data selection used in task properties after this point will use the new emulation.
l Continue 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.
Page 65
l Step through the process in debug mode until you reach the emulation or data change.
l
Click on View as Text (or View as PDFif your data is PDF at this point) in the Data group
of the Debug tab.
l In the viewer that appears, save the file to a location on your hard drive.
l Stop the process, and select the file you saved as your process' data file.
l If 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 has an option that can be used in conjunction with the previous to
avoid skipping through large processes:
l Step through the process until the emulation or data change, as in the first method.
l Save the data file locally and then select it as your sample data file, as with the second
method.
l Instead 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
process.
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 a Workflow Configuration" on
page525.
About Printing
To print a document using PlanetPress Workflow, you can either use the Print using a Windows
Driver output task, or use a combination of a printer queue and a Printer Queue output task.
These tasks are created and defined using PlanetPress Workflow Configuration program.
The following types of printer outputs are available in PlanetPress Workflow Configuration
program:
l Local printing:
l Windows output queues let you send jobs to a local printer. See "Windows Output
Printer Queue" on page70.
Page 66
l Send to Folder output queues let you save jobs to a local or network folder from
Technical
In PlanetPress Workflow Configuration, you may associate a single Printer Queue
output task with multiple Printer Queues. If you do so, you have the option of using load
which they can be picked up and printed. See "Send to Folder Printer Queue" on
page74.
l Remote printing:
l FTP output queues let you upload jobs to an FTP site from which they can be
picked up and printed. See "FTP Output Printer Queue" on page73.
l LPR output queues let you send print jobs to remote printers via TCP/IP using the
LPR/LPD protocol. See "LPR Output Printer Queue" on page71.
l Windows Driver Printing:
l The Print using a Windows Driver output task lets you send a job to any printer
installed on the computer, using its own drivers. In this particular case, the printer
does not need to be a PostScript printer. See "Print Using a Windows Driver" on
page502.
PlanetPress Workflow provides you with three main printing scenarios:
l Send output data to be printed as is: PlanetPress Workflow sends a file containing only
the data to the selected queue.
l Send output data to be merged with a document on the printer: PlanetPress
Workflow sends one of two things:
l A file that contains only the data to the selected printer queue. The document with
which the data must be merged must be present on the printer’s hard disk,
otherwise printing will fail.
l A file that contains the data and the document to the selected printer queue. Since
the data and the document with which it must be merged are both sent to the printer,
printing should never fail.
l In both cases, the document+data merging process takes place inside the printer.
l Send output data already merged with a document:PlanetPress Workflow sends a file
that contains the document already merged with the data to the selected printer queue.
The document+data merging process therefore never takes place inside the printer.
Page 67
balancing or not (See "Load Balancing" on page76).
PlanetPress Workflow Printer Queues
The printer queues displayed in the Configuration Components pane of the PlanetPress
Workflow Configuration program are not to be confused with Windows printer queues. When
you start building a PlanetPress Workflow configuration it contains no printer queues so you
have to create queues and set each one’s properties.
The PlanetPress Workflow Configuration program lets you create four types of printer queues:
l Windows Output printer queues are used to send print jobs to local or network printers.
See "Windows Output Printer Queue" on page70.
l LPR Output printer queues are used to send print jobs to printers via the LPR/LPD
protocol. See "LPR Output Printer Queue" on page71.
l FTP Output printer queues are typically used to send print jobs to FTP sites. See "FTP
Output Printer Queue" on page73.
l Send to Folder printer queues are typically used to send print jobs to local or network
folders. See "Send to Folder Printer Queue" on page74.
The properties associated with each queue will differ depending on the queue type. In the case
of an FTP Output printer queue, for example, the properties include the IP address of the FTP
server. In the case of a Windows Output printer queue, on the other hand, you will find the name
of a local or shared Windows printer queue.
To send print jobs to any of those PlanetPress Workflow printer queues, you must use a Printer
Queue output task. Note that with a single task, you can send print jobs to multiple printer
queues, regardless queue types.
Shared Printer Queue Properties
A printer queue’s advanced properties includes the printer’s speed and any special pre- or
post-job commands required for printer specific reasons. Pre-job commands are added right
before the data in the data file, while post-job commands are placed at the end of the data file.
Page 68
Properties
Advanced tab
l
Print speed: Enter the speed, in pages per minute (PPM), of the printer associated with
the printer queue. This value is used to determine how to divide jobs when you use the
Queue Balancing option for load balancing.
l
Commands: The list of available commands appears in this box. Select either Pre-job
commands or Post-job commands in the Selected box, and double-click a command
from this list to add it to the appropriate list.
l
Selected: Select either Pre-job commands or Post-job commands to add new
commands to the appropriate list and to see those commands that have already selected.
Double-click a command to remove it from the selected list.
l
Add: Click to add a new command to the list displayed in the Commands box. You must
then edit the new command’s description and value. Note that new commands are shared
by all printer queues.
l
Delete: Click to remove a command from the Commands box.
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
l
Command value: Use this box to edit the code of the command currently selected in the
Commands box. Use the right-click menu for a list of standard printer control characters.
Frequently Used Printer Control Characters
Character name: Character
Typical use in printing context:
code:
End-Of-Job \004 Indicates the end of a print job
Backspace \b Moves a character space backwards
Horizontal Tab \t Adds a horizontal tab
Line Feed \012 Moves to the next line
Form Feed \f Moves to the next page
Page 69
Character name: Character
Typical use in printing context:
code:
Carriage Return \r Moves to the beginning of the current line
DOS End-Of-File \032 Indicates the end of a print job in a DOS
environment
Escape \033 Adds an escape character
New Line
\n Goes to a new line
(CRLF)
Windows Output Printer Queue
Windows output printer queues send print jobs to local or network printer queues set up in the
Windows session in which PlanetPress Workflow is running. The corresponding Windows
printer driver is used in the printing process.
This type of printer queue does not support the transparency and duo-tone features, so you
should not use it with PlanetPress Design documents that use those features.
Properties
General tab
l
Printer queue: Select the Windows printer queue to which you want to send print jobs.
l
Job name: Enter the job’s file name. By default, the variable %f (Job File Name) is used.
You may use a different variable, but you may not use a data selection. This information
may be used for the printer’s banner page.
l
Job owner name: Enter the job owner name. You may use a PlanetPress Workflow
variable.The field is empty by default, which is equivalent to use the default print job
owner name, i.e. the current logged in user name.
Page 70
Advanced tab
l
Print speed: Enter the speed, in pages per minute (PPM), of the printer associated with
the printer queue. This value is used to determine how to divide jobs when you use the
Queue Balancing option for load balancing.
l
Commands: The list of available commands appears in this box. Select either Pre-job
commands or Post-job commands in the Selected box, and double-click a command
from this list to add it to the appropriate list.
l
Selected: Select either Pre-job commands or Post-job commands to add new
commands to the appropriate list and to see those commands that have already selected.
Double-click a command to remove it from the selected list.
l
Add: Click to add a new command to the list displayed in the Commands box. You must
then edit the new command’s description and value. Note that new commands are shared
by all printer queues.
l
Delete: Click to remove a command from the Commands box.
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
l
Command value: Use this box to edit the code of the command currently selected in the
Commands box. Use the right-click menu for a list of standard printer control characters.
LPR Output Printer Queue
LPR output printer queues send print jobs to LPD-compatible printers using the LPD/LPR
protocol. Note that most of the settings associated with LPR output are configured via the
PlanetPress Workflow user options (See "LPR Output preferences" on page644).
Properties
General tab
l
Printer address: Enter the IP address or host name of the printer receiving LPR jobs.
l
Queue name: Enter the printer queue name. Based on printer and network requirements,
this property may not be required.
l
Data type: Select the proper data type. Select (l) Binary data if the job file is a standard
binary file. Select (f) Formatted text to interpret the first character of each line of text as a
standard FORTRAN carriage control character. Select (d) DVI file if the job file contains
Page 71
data in the TeX DVI format. Select (o) PostScript file if the job file is a PostScript file.
Note
If you plan to use an LPR output printer queue to send PlanetPress Design documents generated
using the Optimized PostScript Stream option, you should not enter data selections in the Printer
Select (n) Ditroff format if the job file contains data in device independent troff. Select (t)
Troff format if the job file contains data in troff. Select (v) Sun raster file if the job file
contains raster images. This ensures that the printer uses the correct filter to interpret the
data.
l
Job name: Enter the job’s file name. By default, the variable %f (Job File Name) is used.
You may use a different variable, but you may not use a data selection. This information
may be used for the printer’s banner page.
l
Job owner name: Enter the job owner name. You may use a PlanetPress Workflow
variable.
Advanced tab
l
Print speed: Enter the speed, in pages per minute (PPM), of the printer associated with
the printer queue. This value is used to determine how to divide jobs when you use the
Queue Balancing option for load balancing.
l
Commands: The list of available commands appears in this box. Select either Pre-job
commands or Post-job commands in the Selected box, and double-click a command
from this list to add it to the appropriate list.
l
Selected: Select either Pre-job commands or Post-job commands to add new
commands to the appropriate list and to see those commands that have already selected.
Double-click a command to remove it from the selected list.
l
Add: Click to add a new command to the list displayed in the Commands box. You must
then edit the new command’s description and value. Note that new commands are shared
by all printer queues.
l
Delete: Click to remove a command from the Commands box.
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
l
Command value: Use this box to edit the code of the command currently selected in the
Commands box. Use the right-click menu for a list of standard printer control characters.
Page 72
address and Queue name variable property boxes. If you do need to use information stored in the
data to configure the LPR output printer queue, you should first use Job info variables to store the
information, and then use these variables in the Printer address and Queue name variable property
boxes.
FTP Output Printer Queue
Unlike FTP output tasks, which are typically used to send data files to FTP sites, FTP output
printer queues are mostly used to send print jobs to FTP sites.
FTP output printer queue properties are as follows:
General tab
l
FTP Server: Enter the IP address or host name of the FTP server.
l
User name: Enter an FTP server user name.
l
Password: Enter a password associated with the FTP server user name entered above.
l Use FTPClient default port number:Forces the FTPconnection on port 21, the default
FTPport.
l FTP Port:Enter the FTPport to use. This option is disabled if Use FTPClient default port
number is checked. The port should always correspond with the server's port number.
l
Directory: Enter the directory to which the print jobs are to be uploaded. If you leave this
box empty, the job files are sent to the root directory of the FTP server.
l
File name: Enter the name under which the print jobs will be saved. Consider using a
dynamic name, since if you use a static name every new file will overwrite the previous
one.
l Connection mode group
l Active: Select to prompt the ftp client to use the active mode when sending files to
the FTP server.
l Passive: Select to prompt the ftp client to use the passive mode when sending files
to the FTP server.
Page 73
Advanced tab
l
Print speed: Enter the speed, in pages per minute (PPM), of the printer associated with
the printer queue. This value is used to determine how to divide jobs when you use the
Queue Balancing option for load balancing.
l
Commands: The list of available commands appears in this box. Select either Pre-job
commands or Post-job commands in the Selected box, and double-click a command
from this list to add it to the appropriate list.
l
Selected: Select either Pre-job commands or Post-job commands to add new
commands to the appropriate list and to see those commands that have already selected.
Double-click a command to remove it from the selected list.
l
Add: Click to add a new command to the list displayed in the Commands box. You must
then edit the new command’s description and value. Note that new commands are shared
by all printer queues.
l
Delete: Click to remove a command from the Commands box.
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
l
Command value: Use this box to edit the code of the command currently selected in the
Commands box. Use the right-click menu for a list of standard printer control characters.
Send to Folder Printer Queue
Unlike Send to Folder output tasks, which are typically used to send data files to local or
network folders, Send to Folder output printer queues are mostly used to send print jobs. The
files generated will always be PostScript files.
Properties
General tab
l
Folder: Enter the path of the folder to which the print jobs are to be saved.
l
File name: Enter the name of the print jobs sent to this queue. To prevent each new file
from overwriting the previous one, you should use variable names. This variable property
box lets you use a combination of text, variables and data selections.
Page 74
l
Concatenate files: If this option is selected, when PlanetPress Workflow tries to save the
print job under an existing name, it appends the content of the new print job file to that of
the existing file, instead of overwriting it.
l
Separator string: This option is used to add a separator string between the content of
each file when the Concatenate files option is selected.
Advanced tab
l
Print speed: Enter the speed, in pages per minute (PPM), of the printer associated with
the printer queue. This value is used to determine how to divide jobs when you use the
Queue Balancing option for load balancing.
l
Commands: The list of available commands appears in this box. Select either Pre-job
commands or Post-job commands in the Selected box, and double-click a command
from this list to add it to the appropriate list.
l
Selected: Select either Pre-job commands or Post-job commands to add new
commands to the appropriate list and to see those commands that have already selected.
Double-click a command to remove it from the selected list.
l
Add: Click to add a new command to the list displayed in the Commands box. You must
then edit the new command’s description and value. Note that new commands are shared
by all printer queues.
l
Delete: Click to remove a command from the Commands box.
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
l
Command value: Use this box to edit the code of the command currently selected in the
Commands box. Use the right-click menu for a list of standard printer control characters.
Triggers
In PlanetPress Workflow, a trigger is typically a two line piece of PostScript code placed just
before the data. Triggers tell the printer to turn on PostScript mode and specify which document
should be used in the merging process (PlanetPress Design document+data).
Triggers are used in two situations:
l When the server running PlanetPress Workflow sends a PlanetPress Design document
along with the data to the printer, it adds a trigger before the document
Page 75
(trigger+document+data).
l When the server running PlanetPress Workflow only sends the data to the printer,
because the document is already present on the printer, it adds a trigger before the data
(trigger+data).
PlanetPress Workflow adds the trigger code automatically, but you may want to use custom
triggers. You would do this, for example, to use special printer functions. For more on custom
triggers, see the Data Capture and Trigger Implementation Guide as well as the PlanetPress
Design User Guide.
Load Balancing
PlanetPress Workflow offers various load balancing options to distribute the printing load and
to make the process faster and more efficient. Print jobs may, for example, be split equally
among several printers, or they may be split according to each printer’s capacity and speed.
Load balancing can only be used for jobs sent to Printer Queue output tasks and it only
applies when multiple queues are selected.
In the General tab of the Printer Queue Output Properties dialog box, you may select multiple
printers, and in the Advanced tab, you can set the load balancing options for the selected
printers.
Objectif Lune Printer Driver (PS)
Introduction
The Objectif Lune Printer Driver (PS) allows end-users to print directly to PlanetPress Workflow
from any Windows application, by using the familiar File|Print option. At the other end,
PlanetPress Workflow specifically can capture the incoming stream and convert it internally into
a PDF file along with its metadata.
Although it is available with every PlanetPress Workflow, this feature becomes even more
useful in environments where the Document Input emulation is available (with PlanetPress
Workflow).
Page 76
Install a Objectif Lune Printer Driver (PS)
The Objectif Lune Printer Driver (PS) is automatically installed during the PlanetPress
Workflow setup, along with a default Windows Printer Queue called PlanetPress Printer.
Install a Windows Printer Queue using the Objectif Lune Printer Driver (PS)
A Windows Printer Queue using the Objectif Lune Printer Driver (PS) can be installed from
PlanetPress Workflow WinQueue Input plugin properties.
Creating a new Windows printer queue from any PlanetPress Workflow:
1. Start your PlanetPress Workflow Configuration program.
2. Insert a WinQueue Input plugin.
3. In the WinQueue Input plugin properties, click New.
4. Enter a Name for the printer queue.
5. Click OK.
Every new Windows printer queue using the Objectif Lune Printer Driver (PS) is shared by
default. Once such a shared queue is created, end-users can install it on their own computer by
going through the same steps they would when installing a new remote printer in their
Operating System. By default, connecting to a shared printer will automatically result in the
Objectif Lune Printer Driver being downloaded to the connecting host.
Printer Properties setup
PlanetPress Workflow WinQueue Input task can be configured to set a Windows printer queue
using Objectif Lune Printer Driver (PS) to produce one of 3 different types of data files: EMF,
PostScript, or PDF. Note that PlanetPress Workflow can only produce EMF or PostScript files.
Possible printer properties settings, along with the data file type it will produce:
Spool Print Jobs in EMF Format:
l This will create an EMF data file.
l This format is usually reserved for use with the Windows Print Converter action plugin.
l This format can be obtained using PlanetPress Workflow.
Spool Print Jobs in RAW Format:
Page 77
l This will create a PostScript data file when the option Create Composed Document
Note
Steps 6-8 can be performed at any time, even if PlanetPress Workflow is not yet started. This is
because every Windows printer queue using Objectif Lune Printer Driver (PS) is paused by default.
Stream (with Medatada) is unchecked.
l This format can be obtained using PlanetPress Workflow.
l This will create a PDF data file when the option Create Composed Document Stream
(with Medatada) is checked.
l This format can be obtained using PlanetPress Workflow.
By default, the Create Composed Document Stream option is:
l Checked if the incoming stream has been produced with the Objectif Lune Printer Driver.
l Unchecked if the incoming stream comes from some other PostScript Driver.
l Grayed out and unchecked if the incoming stream is not PostScript.
Data Capture from PlanetPress Workflow
Once a shared Windows printer queue using Objectif Lune Printer Driver (PS) is installed on
both the server and the client sides, data capture can be achieved the same way as with any
other Windows printer queues.
1. Open your PlanetPress Workflow Configuration program.
2. Insert a new process.
3. Select WinQueue Input from the Plugin Bar and insert it in the new process.
4. In the WinQueue Input properties, select a Windows print queue using the Objectif Lune
Printer Driver (PS) from the drop-down list.
5. Click OK.
6. Send the configuration and start your PlanetPress Workflow service.
7. Start the windows application from which you want to capture data.
8. Open your selected document.
9. Click File | Print.
10. Choose the same Windows print queue as in step 4.
Page 78
Once the service has started, it captures every queued job.
PDF Creation Parameters
PDF files retrieved from a Windows print queue using Objectif Lune Printer Driver (PS)
have the following properties:
l PDF 1.4
l Optimized PDF (subject to change)
l No down-sampling of images
These settings are pre-configured and cannot be changed by the user.
About Metadata
Metadata files are files containing information on the job itself rather than containing the job per
se. A job sent to the Objectif Lune Printer Driver (PS) creates its own metadata, allowing users
to retrieve relevant information, such as, for instance, the time and date the print request was
sent. For more on this, see the Metadata documentation pages.
About Processes and Subprocesses
Processes
Aprocess is a single workflow within the configuration. Aprocess begins with a single input
task, contains one or more tasks and/or branches, and terminates with one or more output
tasks. In its simplest form, a process can simply retrieve data from a given folder and save it in a
different folder. In most cases, though, processes are more elaborate and configurations, which
may include many processes, can be extremely complex.
The available processes in your PlanetPress Workflow Configuration are listed in the
"Configuration Components pane" on page555. Processes in a configuration will always run
concurrently. You can schedule processes to run only at certain times or intervals (see "
Process properties" on page583).
There are three types of processes available to you:
Page 79
l A Normal process will run as soon as an input file is available through its input task or, if
it is scheduled not to run at that time, will start processing as soon as the schedule
permits it.
l Startup processes are processes that run only once before every other process in a
given configuration. They can be used to perform operations that need to be completed
once before the configuration can actually be run, such as to map network drives. You
may only have one single startup process in your configuration.
l Subprocesses are processes which can be called by any other process from any action
task. They can be used to perform and reuse redundant operations that may need to be
executed numerous times.
Process properties
Regular and startup processes can be set to be Active (process runs normally)or Inactive
(process will not run at all). An inactive process will display in the Configuration components as
red and strike-through. Inactive processes can be useful for designing new processes in a live
configuration, since the process does not execute there is no danger is submitting it to a
PlanetPress Workflow Service.
To learn how to set this and other properties of processes, see " Process properties" on
page583.
Subprocesses
Subprocesses are special processes that can be called by any other process. These act
exactly as subroutines in programming languages, allowing users to reuse existing processes
by sharing them to the whole configuration file. They can thus be used to perform redundant
operations that may need to be executed numerous times; for instance, archiving a copy of a
zipped file received as the input job file, then decompressing it before sending the unzipped
version of it back to the calling process .
Whenever a process calls a subprocess, the main process (the caller) will wait for the called
subprocess to finish its execution before carrying on with its own. This means the subprocess
feature is synchronous with the main process. This also means the calling process actually
appends the subprocess to its own workflow.
To enter a description or comments for a subprocess:
l Right-click on the subprocess in the Configuration Components pane.
l Select Properties.
Page 80
Creating a new process
Note
You can only have one startup process in any given configuration and cannot add more.
You can create a new process in a two different ways:
l
In the Ribbon, go to the Home tab and click the Process button in the Processes group.
l
In 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 page611 screen. The same methods can be used to create a new
Startup process.
To add a PlanetPress Workflow startup process:
l
In the Ribbon, go to the Home tab and click the Startup Process button in the
Processes group.
l
In the Configuration Components pane, right-click on any process or the Processes
folder and select Insert Startup Process.
For the list of operations you can perform on a process via the Configuration Components
pane, please refer to "Configuration Components pane" on page555.
Considerations
l While your configuration is limited to a maximum of 512 processes, any given process
can have as many tasks as necessary.
l A given process may include output tasks that generate files used by input tasks from
other processes.
l When you send a configuration to your PlanetPress Workflow service, all its active
processes are applied.
l Each process’ schedule determines when its initial input task can be performed.
Page 81
l Other tasks included in the process are performed regardless of schedule, granted that
the previous task was performed.
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 PDFand 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, conditional branches ("conditions") are
used.
For the list of operations you can perform on Branches and Conditions, please refer to The
Process Area.
Branches
A branch is effectively a doubling of your job file (see "Data file and job file" on page24). As
your job file goes down the process, when a branch is encountered, a copy of the job file will go
in that branch. In the branch, all tasks up to the Output task will be performed, before returning
to the main trunk to continue processes. You can have branches within branches, and all
branches must have an Output task. For more information on branches, see Branch.
A branch is represented as a crossing .
Adding Branches
The PlanetPress Workflow Configuration program offers two different commands when it
comes to adding new branches to a process:
You can add a new branch, by dragging and dropping a branch, from the Process Logic
category of the Plug-in Bar, into your process. Branches can thus be added like a task; see
"Adding tasks" on page203.
You can add a new branch that contains all of the tasks below the point where you insert the
branch. To do this, right-click on the first task that you want to include in the branch, and select
Branch From Here.... An unknown task will be created as an output below the branch.
Page 82
Conditions
Note
Subprocesses do not have the "General Tab" which is only used for scheduling, but they
do have the Information Tab.
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 .
Process properties
To have access to the properties of a process or subprocess:
l Right-Click on the Process in the Configuration Components Area.
l Select Properties.
You can also double-click on the process to show its options.
Options
General tab
l Active: Select to make the process active. Clear to prevent this process from running
when you send the configuration to PlanetPress Workflow.
l Startup process: Select to make this process a startup process.
l Self-Replicating Process:Check this if you want the process to replicate itself in the
background when multiple input files are received simultaneously. When this is checked,
the input task polls its source once, determines the number of files to process, then
replicates itself up to the maximum allowed and treats the files simultaneously. The initial
process runs again once it has completed itself and replicates again as necessary, until
all files have been processed.
Page 83
l Max percentage of threading (%):Determines how many processes you may have
running at the same time. This is a percentage of the maximum number of threads
specified in the "Messenger plugin preferences" on page628. For example if the
maximum number of threads is 10 and you specify 50%here, a maximum of 5 replications
will occur (the original process +4 copies).
l As soon as possible: Select to have the process run continuously. Clear to enable the
Time Grid to fine-tune the schedule of the process.
l Day(s) to keep backup: Indicate the number of days to keep backups of jobs processed
by input tasks. Note that backups will only be kept for those input tasks that have the
Keep backup file option selected and that they are required to resubmit input files.
l Polling interval: Enter the frequency (in seconds)at which the process should verify if
there are new jobs to process. The polling interval also applies to scheduled tasks that
only run on certain times. For example, if your process polls every 30 seconds on a task
that's only scheduled to run one hour per week, it will capture the input 120 times during
that period. Note that the polling interval is ignored when multiple files are present in the
input and will be used only when there are no longer any files to process.
l Month: Select the month of the year when the process should be run or select All months
to have the process run all year long. This option is disabled when "As soon as
possible"is checked.
l Week of month / by date: Select the desired option for the time grid. Note that any
selection you make in this box will be interpreted based on the selection made in the
Month box. If you chose All months in the Month box and Last in the Week of month / by
date box, then the process will run on the last week of every month. If you chose January
in the Month box and First in the Week of month / by date box, then the process will run
only on the first week of January.
l Select Date to display dates on the grid’s top ruler.
l Select any of the other options to display days on the top ruler.
l Select All weeks to have the process run every week.
l Select First, Second, Third or Fourth to have the process run on the first, second,
third or fourth week.
l Select Last to have the process run only on the last week.
l Time division: Select the duration of each daily segment in the time grid. If you select
00:15, each segment will represent only 15 minutes and each day will be made up of 96
blocks (4 blocks per hour times 24 hours). If you select 24:00, each segment will
represent an entire day.
Page 84
l Poll once per activity period: Select to perform this process’ initial input task no more
than once for each set of contiguous blocks (blocks that are on the top of one another).
Choosing this option overrides the polling interval option. By default since the Time Grid
blocks are divided by hours, this option will make your polling happen once every hour.
The Time Grid
The PlanetPress Workflow Process Options dialog box includes a time grid that lets you set
exactly when you want a process to run. The grid is composed of blocks that represent time
periods on a given day. To activate the Time Grid, the "As soon as possible"option must be
unchecked.
In the Time Grid, a blue block will indicate that the process is active within that time block.
White blocks mean the process will not be active.
Page 85
l Click on any block to select / deselect it.
l Click and drag from one block to another to toggle all blocks between the two.
l Shift-click on any block to toggle all blocks from the top-left corner of the grid to the block
you click.
Page 86
l To select all of the time segments for a given day or date, click the day or date on the top
Note
"Toggle" means turn on when it's off and vice versa, when selecting multiple blocks in
one command. This means if you select a certain number of blocks in the Time Grid and
then use the shift+click or drag method, blocks that are on will turn off.
Warning
Changes made to the system time can have adverse effects on the processes managed
by PlanetPress Workflow. When changing from daylight saving time to standard time, for
example, if PlanetPress Workflow starts a given process at 2:00 AM, and if the system
time is then taken back to 1:00AM, the application will start a new instance of the same
process when the system time reaches 2:00 AM for a second time. So, when you
manually change the system time, be aware that it may have an effect on PlanetPress
Workflow and its processes. And for those cases when you know the system time will
change automatically, you may consider creating special schedules.
grid ruler. To deselect all of the time segments for a given day or date, CTRL+click the
day or date on the top grid ruler.
l To select all the days or dates for a given time segment, click the time segment on the left
grid ruler. To deselect all the days or dates for a given time segment, CTRL+click the time
segment on the left grid ruler.
l To select the entire grid, use the Select All button located below the grid. To deselect the
entire grid, use the Clear All button located below the grid.
Information tab
The Information tab lets you enter information that is not critical to your process but may help
others (or yourself in the future)to understand what the process does. It offers two boxes:
l Description: Aone-line box to give a title or short description to your process.
l Comments:A multi-line box to give more detailed information, for example the file format
expected, explanation of the system in general.
Page 87
On Error Tab
Note
If you try to send a configuration that contains only inactive processes, the PlanetPress
Workflow Configuration program will ask you to confirm the operation (this can be
changed in the Notification User Options).
A process’s On Error tab specifies the default values for error handling of all of the tasks in that
process. When a task has its own error handling settings, those settings overwrite the process's
default error handling settings.
The options in the On Error tab of the Process Properties dialog are the same as in the On Error
tab in the Task Properties dialogs; see "Using the On Error tab" on page57.
Activating or deactivating a process
All processes are Active by default, but you may make any PlanetPress Workflow process
Inactive as required. Because making a process active or inactive is a change in the
configuration, to make the change effective you will have to send the edited configuration to
your PlanetPress Workflow service (see "Sending a configuration" on page525).
To activate or deactivate a process:
1.
Right-click the process in question in the Configuration Components pane
2.
Click Active to disable or enable the process.
3. Send your configuration.
Converting a branch to a subprocess
To allow for maximum flexibility and backward compatibility with the subprocess feature, the
Convert to subprocess option lets users transform existing processes easily. This option is
available whenever a Branch task is selected; right-clicking on it will display the contextual
menu, which holds the Convert to subprocess option.
Selecting this option automatically creates a new subprocess, takes the branch and all of its
children tasks and inserts it in the new subprocess, including the branch task itself. In the main
Page 88
process, the branch is removed and replaced with a GoSub action task referring to the newly
Note
The Branch tasks options Backup job file, Backup job information and Backup emulation, are
also automatically passed to the subprocess, which means that, if the subprocess needs to use a
different emulation than the calling process, a Change Emulation task is required.
Note
Connect resource files must be imported separately; see "Connect resources" on page565.
created subprocess.
If any task converted into a subprocess was previously using local variables, these variables
must be removed or transferred to global variables or Job Information variables to be usable in
the newly created subprocess (see "Types of variables" on page512).
Importing processes
You can import individual processes or groups of processes from another PlanetPress
Workflow configuration file without having to import the contents of the entire configuration file.
The PlanetPress Workflow Configuration tool imports everything necessary to run the
processes, including configured tasks and configuration components.
To import components from another configuration file:
1.
From the PlanetPress Workflow Button, choose Import | Configuration Components.
The Import dialog appears.
2. Navigate to the PlanetPress Workflow configuration file containing the processes or
groups of processes you want to import.
3.
Select the file, then click Open. The Import Configuration dialog appears displaying all
the processes and/or process groups, as well as the Subprocesses, Global Variables,
PlanetPress Design documents and Printer Queues in the selected configuration file.
4. In the list, select the components you want to import. The PlanetPress Workflow
Configuration program lets you open and import any of the following:
Page 89
l Complete PlanetPress Watch 4 to 6 configurations, as well as PlanetPress
Workflow 7 and 8 configurations.
l Specific processes from Version 6, 7 and 8 configurations, including their local
variables.
l Specific subprocesses from any PlanetPress Workflow 7 and 8 Tools
configurations.
l Specific global variables from PlanetPress Workflow 7 and 8 Tools configurations.
l Specific PlanetPress Design or PrintShop Mail documents.
l Specific Printer Queues.
5. Check "Overwrite existing components with same name" if you want processes with
existing names to be overwritten by those in the imported configuration, or uncheck it to
duplicate those processes under a new dynamic name.
6. Click OK to start the import.
PlanetPress Workflow Configuration imports the selected objects and automatically
renames duplicate items in the imported configuration. If the current and imported
configurations both include a startup process, the one in the imported configuration will
become a standard process.
Important considerations
l When importing a PlanetPress Workflow configuration file, PlanetPress Design and
PrintShop Mail documents are not physically imported as they are not part of the
configuration file itself. In order for the documents to be available, you will need to send
each document from PlanetPress Design and PrintShop Mail (see their respective
documentation for details).
l
If you import a PlanetPress Workflow configuration that contains a PlanetPress Fax
output task, you must update the task’s properties and refresh the host name. Otherwise,
when PlanetPress Workflow will attempt to output the file, an error will be generated.
Toggle the Run on Desktop property
Since PlanetPress Workflow configurations are typically meant to run without user interaction,
all of their processes are set to run in the background by default. In some cases, such as when
a dialog box must appear or user input is required, you may make any process run on your
desktop instead of as a service.
Page 90
Generally this will happen only when calling a third-party software using the Run External
Note
The term "Desktop"is defined as the desktop of the user logged on to the computer
where PlanetPress Workflow is installed. These dialogs cannot be displayed on any
other computer.
Program plugin, but is also valid if using a Script that generates a dialog that someone must
click or interact with.
To toggle a process’ Run on Desktop property:
1.
Select an active process in the Configuration Components pane.
2.
In the Object Inspector Pane, change the Run on desktop property from False to True,
or vice versa.
Page 91
Executing the Processes (Sending Configuration)
Warning
While this chapter provides some very useful and detailed information about scripting
within PlanetPress Workflow, its focus is to inform you about the features, variables and
functions unique to this environment. This chapter assumes that you have a working
knowledge of the scripting language you wish to use and does not purport to teaching
you anything about this language that you don't already know. Learning any of these
language is beyond the scope of this documentation.
Note
While JavaScript and VBScript are natively available on Windows operating systems.
Python and Perl require third-party tools to be functional. For Perl, ActivePerl can be
installed. For Python ActivePython (version 2.7.13 ) can be installed.
Using Scripts
Scripts can be used to perform various operations, such as to manipulate data, for example.
PlanetPress Workflow can perform scripts written in four different scripting languages and also
provides an interface for editing scripts.
There are four scripting languages available through the Run Script task: JavaScript, VBScript,
Python and Perl. Each language has its own strengths and weaknesses which we will not
cover in this documentation. While VBScript is the most used language at the moment, the
examples provided in this chapter are presented in all supported languages.
When using the Run Script as a condition, you need a way to tell your process whether the
result is true or false. The condition result is returned by the "Script.ReturnValue" on page121
variable. If the return value is zero (the default), the condition is false. Otherwise, it is true.
When using the Run Script as an action task, the job file going out of the Run Script action
task will be the same as the one coming in, unless you have specifically changed it within your
script by writing to the file that is the target of the "Watch.GetJobFileName" on page112
Page 93
function. The same goes for any job info, local or global variables, unless you use the
"Watch.SetJobInfo" on page116 or "Watch.SetVariable" on page117 functions to modify them.
Multiple APIs (methods of communicating with PlanetPress Workflow scripting tools) are
available through the scripting engine, in all languages.
l The Watch object is used to communicate with your current process and configuration.
See "The Watch Object" on page107.
l The PlanetPress Connect REST API consists of many services that expose access to a
number of areas including Workflow, data entity management and file store operations.
See PlanetPress Connect REST API Cookbook.
l You can manipulate PDFfiles using the PlanetPress Alambic API. See AlambicEdit
Library Reference. Note that the PlanetPress Alambic API is part of the PDFTools.
l You can manipulate the metadata in your process using the Metadata API. See Metadata
API Reference.
l You can communicate with a SOAPserver using the SOAPAPI. See "SOAP Server API
Reference" on page100.
l You can communicate with the PlanetPress Capture Database using the Capture API.
See Capture API Reference.
l You can communicate the with the Data Repository using the Data Repository API. See:
"Data Repository API" on page122.
The Script Editor and XSLT Editor
How can I edit scripts and XSLT code?
Scripts can be edited in the Script Editor and the XSLT Editor. Both editors are visually
identical and share almost exactly the same commands. They let you import and export scripts,
perform common editing function, such as search and replace, and feature syntax highlighting
and formatting.
You can use the Script Editor to edit scripts written in VBScript, JavaScript, Perl and Python
(note that the corresponding interpreter must be locally available). You can use the XSLT Editor
to edit scripts written in XSLT 1.0 and 2.0.
For information on how to use both editors, or for a complete description of the Script or XSLT
Editor user options, refer to the Reference Help (English only).
Page 94
Use the Editor
Note
When you import a script, it replaces any script currently displayed in the editor.
The Script Editor and XSLT Editor share most of the same commands and functions. You can
open the Script Editor using the Open Editor button both from the Run Script Properties
dialog box and from the Open XSLT Properties dialog box. When you do so, the script
currently displayed in the dialog box is pasted to the editor’s scripting box.
For information on the available editor options, refer to "Editor Options" on page646.
Import and Export Scripts
Both the Script Editor and XSLT Editor let you import and export scripts.
To import a script:
1.
In the editor, choose File | Import. The Open dialog box appears.
2. To import a script that uses a different scripting language or that was saved under a
different file format, make a selection in the Files of type drop-down list.
3. Navigate to the script you want to import and select it.
4.
Click OK. The script is imported, displayed and formatted according to the syntax of the
language selected in the editor. If the imported file had the extension of a recognized
scripting language (.vbs or .js, for example), the editor language is automatically changed.
To export a script:
1.
In the editor, choose File | Export. The Save As dialog box appears.
2. To save the script using a different scripting language or under a different file format,
make a selection in the Save as type drop-down list.
3. Navigate to the location where you want to save the exported script.
4.
Enter the name of the script in the File name box.
5. To save the script using a different scripting language or under a different file format,
Page 95
make a selection in the Save as type drop-down list.
Note
If you only want to search a particular section of the script, you should select it before performing
the following procedure.
6.
Click OK.
Find Strings in a Script
The Find Text dialog box allows you to search for text strings in the editor. The available
options help you limit the search, making searches quicker and easier.
To find strings in a script:
1.
Choose Search | Find, or press CTRL+F. The Find Text dialog box appears. The last
used string is displayed in the Text to find drop-down list box.
2. Set the search settings and options.
l
Text to find: Enter a new search string or select a previous search from the dropdown list.
l
Case sensitive: Select to limit the search to instances of text with the same case as
the text in the Text to find box.
l
Whole words only: Select to limit the search to complete words matching the text in
the Text to find box. Whole words are defined as strings that have a space or
punctuation before and after the word.
l
Regular expressions: Select to treat the regular expressions of the scripting
language as text to search. If you clear this option, the regular expressions of the
language are not included in the search.
l
Global: Select to search the entire content of the script.
l
Selected text: Select to find matching text within the text block you select. A portion
of text must be selected before you run the search.
l
Forward: Select to search the script forward, from the location of the cursor or from
the beginning of the script, depending on what you choose as the origin (From
cursor begins where the cursor is currently located in the script, Entire scope begins
from the beginning of the script or beginning of script selection). If you limit the
Page 96
scope to selected text, you move forward only within the selection. When the search
reaches the end of the script or script selection, the search finishes. It does not loop
back to the beginning.
l
Backward: Select to search the script backward, from the location of the cursor or
from the end of the script, depending on what you choose for the origin (From cursor
begins where the cursor is currently located in the script, Entire scope begins from
the beginning of the script or beginning of script selection). If you limit the scope to
selected text, you move backward only within the script selection. When the search
reaches the beginning of the script or script selection, the search finishes. It does
not loop back to the beginning.
l
From cursor: Select to start the search from the position of the cursor.
l
Entire scope: Select to search the entire script or a script selection. The scope
croplands to a script selection if you make a selection before executing the Find.
3.
Click OK. The first matching string is highlighted in the script.
4.
To find the next matching string, choose Search | Find Again or press F3.
Find and Replace Strings in a Script
The Replace With dialog box lets you search for and replace text strings in the editor. The
available options help you limit the search, making replacements quicker and easier.
To find and replace strings in a script:
1.
Choose Search | Replace, or press CTRL+R. The Replace With dialog box appears.
The last used strings are displayed in the Text to find and Replace with boxes.
2. Set the replacement settings and options.
l
Text to find: Enter a new search string or select a previous search from the dropdown list.
l
Replace with: Enter the string that will replace the string displayed in the Text to
find box.
l
Case sensitive: Select to limit the search to instances of text with the same case as
the text in the Text to find box.
l
Whole words only: Select to limit the search to complete words that match the text
in the Text to find box. Whole words are defined as strings that have a space or
punctuation before and after the word.
Page 97
l
Regular expressions: Select to treat the regular expressions of the scripting
language as text. If you clear this option, the regular expressions of the language
are blocked from the search.
l
Prompt on replace: Select to have PlanetPress Workflow display a prompt before it
replaces text. When you use the Replace All function, you are prompted each time
matching text is found. The prompt includes an All button for replacing all matching
text. This suppresses any further prompting.
l
Global: Select to search the entire content of the script.
l
Selected text: Select to find matching text only within a text block you select. The
text must be selected before you run the search.
l
Forward: Select to search the script forward, from the location of the cursor or from
the beginning of the script, depending on what you choose as the origin (From
cursor begins where the cursor is currently located in the script, Entire scope begins
from the beginning of the script or beginning of script selection). If you limit the
scope to selected text, you move forward only within the selection. When the search
reaches the end of the script or script selection, the search finishes. It does not loop
back to the beginning.
l
Backward: Select to search the script backward, from the location of the cursor or
from the end of the script, depending on what you choose for the origin (From cursor
begins where the cursor is currently located in the script, Entire scope begins from
the beginning of the script or beginning of script selection). If you limit the scope to
selected text, you move backward only within the script selection. When the search
reaches the beginning of the script or script selection, the search finishes. It does
not loop back to the beginning.
l
From cursor: Select to start the search from the position of the cursor.
l
Entire scope: Select to search either the entire script, or a script selection. The
scope corresponds to a script selection if you make a selection before executing the
Find.
3. Do one of the following:
l
Click OK to replace the first string encountered. If you selected Prompt on replace,
a dialog box opens to ask you whether to proceed with the replacement. You can
OK to replace the first string only, or you can click All to replace that string as well
as every other string that matches the replacement settings.
l
Click Replace All to replace all the strings that match the replacement settings.
4.
To find and replace the next matching string, choose Search | Find Again or press F3.
Page 98
Once again, if you selected Prompt on replace, a dialog box opens to ask you whether
Note
Bookmarks are not preserved when you close the editor.
to proceed with the replacement. You can OK to replace that string only, or you can click
All to replace that string as well as every other string that matches the replacement
settings.
Go to a Line in a Script
The Go To Line dialog box lets you jump to a specific line within your script. It works whether
or not the line number are displayed on the left side of the editor window (to know how to toggle
the line number display settings, See "Editor Options" on page646).
To go to a line in a script:
1.
Click anywhere in the Script Editor, then choose Search | Go To Line, or press Alt+G.
The Go To Line dialog box appears. The last used line numbers are displayed in the
Enter new line number drop-down list box.
2.
Enter a new line number in the Enter new line number box or select one from drop-down
list.
3.
Click OK.
Toggle Bookmarks
Bookmarks help you identify and jump to specific places within your script (see "Jump to
Bookmarks" on the next page).
Bookmarks are displayed in the editor’s gutter, so you will not be able to see them unless the
gutter is both visible and sufficiently wide. If line numbers are also displayed in the gutter,
bookmarks may be harder to see. To control line number and gutter display, see "Editor
Options" on page646.
Page 99
To toggle bookmarks:
Note
PlanetPress Workflow already come with a SOAP Client plugin, which can be used as an input,
action or output; this task was renamed Legacy SOAP Client.
l Place the cursor on a line in your script and, from the editor’s pop-up menu, choose
Toggle Bookmark and a given bookmark number.
If the bookmark you selected was not displayed on any line, it is added to the line where you
placed the cursor. If the bookmark you selected was displayed on the line where you placed the
cursor, it is removed. If the bookmark you selected was displayed on a different line, it is moved
to the line where you placed the cursor.
Jump to Bookmarks
Before you can jump to bookmarks, you must add bookmarks to specific lines in your script
(See "Toggle Bookmarks" on the previous page).
To jump to a bookmark:
l
From the editor’s pop-up menu, choose Go To Bookmark and a given bookmark
number.
If the bookmark you selected was displayed on a line, the cursor jumps to that line.
SOAP Server API Reference
PlanetPress Workflow offers a SOAP server API Reference allowing jobs to be submitted from
third party application using the SOAP protocol. Remember that SOAP stands for Simple
Object Access Protocol.
While there are multiple possibilities for solutions using a SOAP server implementation, the
SOAP Server API Reference is specifically for submitting jobs from a SOAP client. It
implements five methods that will allow SOAP clients to submit jobs and get information from
PlanetPress Workflow executing them.
Page 100
Loading...