PlanetPress Workflow User Guide Planet Press 8.8 Ug
User Manual: Pdf PlanetPress Workflow - 8.8 - User Guide User Guide for Objectif Lune PlanetPress Software, Free Instruction Manual
Open the PDF directly: View PDF 
.
Page Count: 796
| Download | |
| Open PDF In Browser | View PDF |
User Guide
Version: 8.8
User Guide
Version 8.8
Last Revision: 4/9/2018
Objectif Lune, Inc.
2030 Pie-IX, Suite 500
Montréal, QC, Canada, H1V 2C8
+1 (514) 875-5863
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 8.8
10
Icons used in this guide
System Requirements
10
12
Operating System (64-bit only)
Minimum Hardware Requirements
Known Issues
Basics
12
12
12
16
Setting Up the Working Environment
Setting Up Preferences
Create a New Process
Considerations
Send your Configuration
Features
16
16
16
17
17
20
The Nature of PlanetPress Workflow
About Branches and Conditions
Branches
Conditions
Configuration Components
Connect Resources
Available Resources
Resource Save Location
Resource Archives
About Data
Data File and Job File
Job File Names and Output File Names
Data selections
About Data Emulation
Using the File Viewer
Sample Data
Metadata
Data Repository
Structure
20
20
21
21
21
21
22
22
23
23
24
25
26
35
36
36
38
51
52
Page 4
Accessing the Data Repository
Where to find the Data Repository
About Documents
Import Documents
Import PrintShop Mail Documents
Debugging and Error Handling
About Error Handling
Using the On Error tab
Creating and Using Error Processes
Accessing the Logs
Resubmit Backed Up Input Files to a Process
Knowing What to Resubmit
Debugging your PlanetPress Workflow Process
The Plug-in Bar
Categories
Settings & Customization
About Printing
PlanetPress Workflow Printer Queues
Shared Printer Queue Properties
Windows Output Printer Queue
LPR Output Printer Queue
FTP Output Printer Queue
Send to Folder Printer Queue
Triggers
Load Balancing
Objectif Lune Printer Driver (PS)
About Processes and Subprocesses
Processes
Subprocesses
Process Properties
Activate or Deactivate a Process
Convert a Branch to a Subprocess
Import Processes from Another Configuration File
Toggle the Run on Desktop Property
Using Scripts
The Script Editor and XSLT Editor
SOAP Server API Reference
53
54
54
54
55
55
55
56
57
58
60
62
63
66
66
67
68
69
70
72
73
74
76
77
77
78
81
81
81
82
87
87
88
89
91
92
98
Page 5
The Watch Object
Data Repository API
Stopping Execution
Special Workflow Types
Special Workflows
PlanetPress Capture Workflow
Database Considerations (ODBC)
HTTP Server Workflow
PDF Workflow
Workflow processes in a Connect Send solution
The basic processes involved in the Capture OnTheGo Workflow
About Tasks
Task Properties
Variable Properties
Input Tasks
Action Tasks
Data Splitters
Process Logic Tasks
Connector Tasks
PlanetPress Capture
Metadata Tasks
OL Connect Send
OL Connect tasks
Output Tasks
Working With Variables
Types of Variables
Job Info Variables
Standard Variables
Manipulate Local Variables
Manipulate Global Variables
About Configurations
Create a New Configuration
Open a PlanetPress Workflow Configuration File
Saving and Sending
Exit PlanetPress Workflow Configuration Program
About related programs and services
Available Input services
105
121
141
142
142
143
150
179
186
189
191
196
197
197
203
268
368
396
426
475
509
538
555
619
644
644
645
646
650
652
654
654
655
656
658
658
659
Page 6
Available Output services
Start and Stop PlanetPress Workflow Service
The Interface
Customizing the Workspace
Dock and Undock Areas of the Program Window
Show or Hide Areas of the Program Window
Combine and Attach Areas
Resize the Program Window Areas
Change the Interface Language
PlanetPress Workflow Button
Options
The Configuration Components Pane
Components Area Sections
Processes and Subprocesses
Manipulate Global Variables
Connect Resources
PPS/PSM Documents
Associate Documents and PlanetPress Printer Queues
Using the Clipboard and Drag & Drop
Rename Objects in the Configuration Components Pane
Reorder Objects in the Configuration Components Pane
Grouping Configuration Components
Expand and Collapse Categories and Groups in the Configuration Components Pane
Delete Objects and Groups from the Configuration Components Pane
Other Dialogs
Activate Your Printers
Workflow Services
Process Properties
Advanced SQL Statement Dialog
Access Manager
PDF Viewer
The PlanetPress Workflow Service Console
Update document
Data Repository Manager
Virtual Drive Manager
The Debug Information Pane
The Message Area Pane
660
660
663
664
664
666
666
671
671
672
672
674
674
677
685
687
689
694
695
698
698
699
700
701
701
701
702
704
709
709
717
719
721
721
724
725
726
Page 7
The Object Inspector Pane
The Plug-in Bar
Categories
Settings & Customization
Preferences
Other Preferences and Settings
General appearance preferences
Object Inspector appearance preferences
Configuration Components Pane appearance preferences
Default Configuration behavior preferences
Notification Messages behavior preferences
Sample Data behavior preferences
Network behavior preferences
PlanetPress Capture preferences
OL Connect preferences
PDF Text Extraction Tolerance Factors
General and logging preferences
Messenger plugin preferences
HTTP Server Input 1 plugin preferences
HTTP Server Input 2 plugin preferences
LPD Input plugin preferences
Serial Input plugin preferences
Telnet Input plugin preferences
PlanetPress Fax plugin preferences
FTP Output Service preferences
PlanetPress Image preferences
LPR Output preferences
PrintShop Web Connect Service preferences
Editor Options
The Process Area
Zoom In or Out within Process Area
Adding Tasks
Adding Branches
Edit a Task
Replacing Tasks, Conditions or Branches
Remove Tasks or Branches
Task Properties Dialog
727
728
729
729
730
732
732
733
733
734
735
737
738
739
748
749
751
752
753
756
757
758
759
759
763
764
767
768
769
773
774
774
775
775
776
776
777
Page 8
Cutting, Copying and Pasting Tasks and Branches
Moving a Task or Branch Using Drag-and-Drop
Ignoring Tasks and Branches
Resize Rows and Columns of the Process Area
Selecting Documents in Tasks Links
Highlight a Task or Branch
Undo a Command
Redo a Command
The Quick Access Toolbar
The PlanetPress Workflow Ribbon
The Task Comments Pane
Additional Information
778
781
782
782
783
784
784
784
785
786
788
789
Copyright Information
790
Legal Notices and Acknowledgements
791
Page 9
Welcome to PlanetPress Workflow
8.8
This PDF documentation covers version 8.8. To view the documentation of previous versions
please refer to the PDF files available in the Downloads section of our website:
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 even ERP systems! This data can then be analysed, modified, stored, verified, routed and
used as triggers for other processes from entirely within Workflow. Finally it is passed to one of
our other products (or not) to be outputted in multiple ways (printed, emailed, posted, archived,
sent to third party solutions, etc..).
Consider Workflow as a set of buildings blocks that enable you to build your own customised
automated processes which will fit your environment and not the other way around. Create
processes that will save you time and money!
Icons used in this guide
Icons are used throughout this guide to point your attention to certain information.
Note
Complementary information that is not critical, but may help you better use PlanetPress Workflow.
Tip
Information that is useful or suggests an easier method.
Page 10
Technical
Information that may require specific knowledge to understand.
Warning
Information that is potentially critical to using PlanetPress Workflow. Pay close attention.
Page 11
System Requirements
These are the system requirements for PlanetPress Workflow 8.8.
Operating System (64-bit only)
l
Microsoft Windows 2008/2008 R2 Server
l
Microsoft Windows 2012/2012 R2 Server
l
Microsoft Windows Vista
l
Microsoft Windows 7
l
Microsoft Windows 8.1
l
Microsoft Windows 10 (Pro and Enterprise versions only)
Note
Windows XP, Windows 2003 and older versions of Windows are not supported by PlanetPress
Workflow.
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)
Known Issues
l
l
Anoto Pen Director 2.8 is not supported on Windows Server 2012 and Windows 10.
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.
Page 12
l
l
l
l
l
l
l
l
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)
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.
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.
21465: The SharePoint Output task does not validate the field contents. That's
Sharepoint's responsibility.
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).
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
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.
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.
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.
Page 13
l
l
l
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.
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 config was set up and the moment it was loaded. This is unlikely to occur, but
it could, for instance, happen when importing a Version 7 configuration file into Version 8.
To circumvent the issue, open the output task's properties, make sure you reselect the
proper printer, close the task and send the configuration again.
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.
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
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
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.
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
Page 14
PlanetPress Workflow configuration file from another PC that includes an instance of the
WordToPDF task, you must review the properties of each instance of the task and click
OK to validate its contents. A new printer queue will be created if required and the default
printer will be reset properly. If you do not perform these steps, running the configuration
will result in several error messages being logged and the task failing.
l
l
l
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.
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.
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.
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 15
Basics
PlanetPress Workflow is a tool for the automation of the processing, the distribution and the
printing of your business documents. Once installed on the server, it can be set up to automate
all tasks related to document processing.
Setting Up the Working Environment
Setting up the working environment has to be done the first time you start PlanetPress
Workflow.
1. Defining the printer (see Activate Your Printers).
2. Configure PlanetPress Workflow Services (see Workflow Services).
Setting Up Preferences
PlanetPress Workflow Configuration program lets you configure a variety of options, from how
the application itself looks or behaves, to plugin specific options. For more information about
preferences accessible through the Preferences button in the PlanetPress Workflow Button,
please refer to Preferences.
Create a New Process
You can create a new process in a two different ways:
l
l
In the Ribbon, go to the Home tab and click the Process button in the Processes group.
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 page 734 screen. The same methods can be used to create a new
Startup process.
Page 16
To add a PlanetPress Workflow startup process:
l
l
In the Ribbon, go to the Home tab and click the Startup Process button in the
Processes group.
In the Configuration Components pane, right-click on any process or the Processes
folder and select Insert Startup Process.
Note
You can only have one Startup Process in any given configuration and cannot add more.
Considerations
l
l
l
l
l
While your configuration is limited to a maximum of 512 processes, any given process
can have as many tasks as necessary.
A given process may include output tasks that generate files used by input tasks from
other processes.
When you send a configuration to your PlanetPress Workflow service, all its active
processes are applied.
Each process’ schedule determines when its initial input task can be performed.
Other tasks included in the process are performed regardless of schedule, granted that
the previous task was performed.
Send your Configuration
PlanetPress Workflow Configuration saves entire configurations in the form of a single file. Like
any other file, configuration files may be saved and reopened, as well as rename as desired.
Simply saving a configuration has no effect on the configuration actually used by the
PlanetPress Workflow when it is started. To change any currently active configuration, you
must use the Send Configuration command.
When you use the Send command, the PlanetPress Workflow Configuration program uses the
currently opened configuration (Any_name.OL-workflow) to overwrite PlanetPress Workflow
service's current configuration (ppwatch.cfg).
Page 17
Note
OL-workflow files are equivalent to .pp7 files made with older versions of PlanetPress Workflow.
They contain the processes and such used by Workflow.
If PlanetPress Workflow service is running when you send a new configuration, it stops and
restarts automatically with the new configuration. If the service is stopped, it will not start
automatically.
To send a Configuration to the local server:
1. Open the configuration you want to use as a new configuration.
2. Edit the configuration, if required.
3. When the configuration is ready to be used, from the PlanetPress Workflow button,
choose Send Configuration, then Send Local.
To send a Configuration to a remote server:
1. Open the configuration you want to use as a new configuration.
2. Edit the configuration, if required.
3. When the configuration is ready to be used, from the PlanetPress Workflow button,
choose Send Configuration, then Send Remote.
A list of available servers on the local network appears.
4. Put a checkmark next to each server where the configuration should be sent.
5. Click OK.
If a server is grayed out, this may mean you do not have access to send a configuration
remotely to it. For more information, please see "Access Manager" on page 709.
Note
If PlanetPress Workflow service is paused when you send a new configuration, it will not
stop and restart. Since PlanetPress Workflow service reads its configuration file when it
starts up, when you resume processing, PlanetPress Workflow service will continue
Page 18
using the old configuration.
Page 19
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 Branches and Conditions
While some processes can simply start with an input task, manipulate the data with a few action
tasks and finish with an output task, in some cases you may want to have more control over the
flow of your process. For example, you may want multiple outputs, such as printing to multiple
printers as well as generating a PDF and emailing it. To do this, you will need branches. You
may also want to detect certain criteria in your data and act differently depending on that data,
such as sending a fax only when a fax number is found, or printing to a different printer
depending on who send you a print job. To do this, conditions are used.
Page 20
Branches
A branch is effectively a doubling of your job file. As your job file goes down the process, when
it encounters a branch it will go in that branch, process all tasks up to the output, and return to
the main trunk to continue processes. You can have branches within branches, and all
branches must have an output. For more information on branches, see Branch.
A branch is represented as a crossing
.
Conditions
A condition will either execute the branch it creates or the main trunk, but never both. As your
job file goes down the process, when it encounters a condition it will verify whether that
condition results in a "true" or "false" value. If the result is true, it goes in the branch, processes
all tasks up to the output, and the process finishes. If the result is false, it goes down the main
trunk and continues processing until the process finishes.
A conditional branch (or condition) is shown as a crossing with a red diamond over it
.
For the list of operations you can perform on Branches and Conditions, please refer to The
Process Area.
Configuration Components
The Configuration Components items displayed in the pane are processes, subprocesses,
variables, documents and printer queues. For more information on operations that you can
perform on each component, please refer to The Configuration Components pane.
Connect Resources
Connect resources are visible in The Configuration Components pane and are added by
using the Send to Workflow option from the PlanetPress 's File menu.
Page 21
Available Resources
l
Data Mapping Configurations: Displays a list of data mapping configurations used with
the Execute Data Mapping task. Each of the templates have been sent from PlanetPress
Connect using the Send to Workflow tool. For each template in the list, the following two
items appear within them:
l
l
l
l
l
Data Model: Displays the data model used in the data mapping configuration.
Double-click on the data model to view it in your default XML viewer (generally,
Internet Explorer).
Sample Data File(s): Displays a list of sample files that are included in the data
mapping configuration. Double-click on a file to use it as a sample data file for the
active process.
Document Templates: Displays a list of templates that can be used in content creation
tasks: "Create Email Content" on page 562, "Create Web Content" on page 587 and
"Create Print Content" on page 582.
Job Presets: Displays a list of Job Presets that can be used in the "Create Job" on
page 567 task.
Output Presets: Displays a list of Output Presets that can be used in the "Create Output"
on page 570 task.
Resource Save Location
Any resource sent to PlanetPress Workflow from PlanetPress Connect is saved locally at the
following location: %PROGRAMDATA%\Objectif Lune\PlanetPress Workflow 8\PlanetPress
Watch\OLConnect
Resources are saved in their appropriate folder:
l
DataMapper contains the data mapping configurations (.OL-datamapper)
l
JobCreation contains the Job Presets (.OL-jobpreset)
l
OutputCreation contains the Output Presets (.OL-outputpreset)
l
Template contains the templates (.OL-template)
Page 22
Note
Package Files are not saved anywhere. The individual resources contained within the
package are extracted and placed in the folders noted above.
Resource Archives
From version 8.2, PlanetPress Workflow maintains an archive of previous versions of
resources, in the following location: %PROGRAMDATA%\Objectif Lune\PlanetPress Workflow
8\PlanetPress Watch\OLConnect\Archive , each in their own folder:
l
datamapper contains archives of the data mapping configurations (.OL-datamapper)
l
jobcreation contains archives of the Job Presets (.OL-jobpreset)
l
outputcreation contains archives of the Output Presets (.OL-outputpreset)
l
template contains archives of the templates (.OL-template)
l
workflow contains archives of Workflow configurations received by the server.
The archives are saved using the template named followed by a timestamp. A maximum of 30
of each instance of a resource is kept (meaning if you have 10 different templates, a maximum
of 300 files will be present in the archive\template folder). Older archives are deleted
automatically as new archives are created.
About Data
Data is what drives your business, and our software. We define data as anything that is
obtained through an Input Task and used within the process itself. Once the data is obtained, it
becomes the job file that is passed from one task to another and generally used to generate
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
originates from many different sources (as many as the input tasks support), parts of it can be
stored in variables, and is always accessible by the task that currently handles it.
Data is referred to using Data Selections either from PlanetPress Workflow or a PlanetPress
Design Document that is being merged with the data (for example in a printed output).
Page 23
For more information about Data, please refer to "Sample Data" on page 36.
Note
Null characters present in the data may not be displayed properly when using
PlanetPress Workflow Configuration program, and that they may also be printed
differently by different printers. To ensure consistency, you should consider filtering out
such characters.
Data File and Job File
Whichever source it may come from, a serial port, an e-mail message, or an LPR request, for
instance, and whatever its format, data entering a PlanetPress Workflow process via an input
task is always referred to as a data file. Job file is a more general term, that can refer to data
files as well as other types of files traveling through a process. Image files, for example, can be
passed from task to task in order to be downloaded to a printer. So files traveling within a
process are mostly referred to as job files.
By default, job file names are generated using the %f variable. You may change the
way PlanetPress Workflow names job files by using any combination of static characters,
variables and Job info variables. You could for instance enter Process_%w_Job_%f in the
File name box to add the process name in the name generated by the PlanetPress Workflow
Tools.
A single job file can be the source of multiple job files. This is the case, for example, when a
process includes multiple branches, as each branch is given a duplicate copy of the job file.
This is also the case when a job file is split into multiple smaller files by a Splitter action task,
for instance (See "Data Splitters" on page 368).
It is important to note that job files may be used as a helpful debugging resource (See
"Debugging and Error Handling" on page 55).
Actual Data and Sample Data
The actual data is the dynamic data captured by PlanetPress Workflow at run-time. The sample
data file is a static sampling of the run-time data.
Page 24
In the PlanetPress Workflow Configuration program, you use sample data files to create and
edit PlanetPress Workflow configurations.
Job File Names and Output File Names
When an input task sends a new data file down a process, it gives it an internal file name
referred to as the job file name (associated with the %f variable). The new job file typically
keeps the same name until the end of the process.
l
l
If the job file comes to a branch in the process, PlanetPress Workflow makes a copy of the
job file and give the new file a new job file name.
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 in
%u (unique 13-character string).
When choosing naming schemes for output files, consider the following:
l
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.
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, data selections and static text. You could, for example, use the
following: ClientID_@(1,1,1,1,14,KeepCase,Trim)_StatMonth_%m.
Page 25
One last consideration regarding output file names has to do with standard JPEG and TIFF files
generated by PlanetPress Image. When an output job contains multiple pages, multiple JPEG
or TIFF files are generated (one image per file), each one identified by a sequence number
appended to its name (this is managed by your PlanetPress Workflow). A three page job to be
called Invoice, for example, will generate three JPEGs or TIFFs called Invoice0, Invoice1 and
Invoice2. Note that this does not apply to multiple TIFFs, which can include multiple images in
a single file.
Note
You can change the name of a previously named file using a Rename action task (see "Rename"
on page 334).
Data selections
A data selection could be compared to an address. It indicates a location within a data file or
database (the job file, metadata file, or Data Repository).
Data selections are always evaluated at run-time so they are always dynamic and depend on
the job file that is currently being processed.
There are several types of data selections you can use, depending on which emulation you are
using, whether or not Metadata have been created by a previous task in the process, and
whether or not data have been entered in the Data Repository.
Adding a data selection
A data selection can be used in any task property that may contain a variable. These properties
are recognizable by their colored field label (maroon, by default). Right-click the property field
and choose Get Data Location or Get Metadata Location to open the Data Selector (see "The
Data Selector" on page 31) or Get Repository Location to open the Data Repository Manager
(see "Data Repository Manager" on page 721).
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.
Page 26
After opening a sample of the data and/or metadata, you can easily make a selection.
It is also possible to manually enter a data selection, or to change it after making a selection
with the mouse pointer.
Wild card parameter "?"
Data/metadata selection functions accept a wildcard parameter "?", indicating the function
operates on all nodes (not just one) of a given level.
Examples
l
l
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.
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
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, ASCII and Channel Skip
emulations. The selection refers to a rectangular selection that may contain multiple lines, rows,
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
l
@(): Always surrounds a data selection.
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.
Page 27
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
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.
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
CSV emulations. 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):
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
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.
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.
Page 28
Data Repository lookups
The Data Repository selections are made through the lookup function. Selections are done
from the data located in the "Data Repository Manager" on page 721. 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
l
l
l
group: The name of the group in which to retrieve the value. Does not need to be
surrounded by quotes.
return key: The name of the key where the information you want to retrieve is located.
Does not need to be surrounded by quotes.
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.
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).
Note that when adding a metadata field, if you perform a multi-line data selection on a PDF
region, only the first line of that region will be set to the metadata field.
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 PDF data selections.
l
Page: The page of the PDF from 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.
Page 29
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
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.
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.
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.
Syntax
GetMeta(Field Name [, Option Flags, Metadata Path])
Here is a breakdown of the syntax:
l
l
l
GetMeta(): Always surrounds metadata selections.
Field/Attribute Name: specifies the name of the field (or attribute, if the GetAttribute
option flag is set) to retrieve (see "Metadata" on page 38).
Option Flag (optional): Sets the options for the selection (see table below).
Page 30
l
Metadata Path (optional): Defines the precise path where the Metadata Field is located.
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.
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
page 38.
NoCascade
2
Search only the level specified by the path argument
(defaults to Page level when path argument is empty),
instead of default behavior, going from the Page level to
the Job level.
FailIfNotFound
4
Raise an error and crash the job is the specified name is
not found instead of returning an empty string.
SelectedNodesOnly
8
Returns values from the selected nodes only.
The Data Selector
The Data Selector is the tool you use to choose your sample data and metadata files, to select
the appropriate emulation, to make data selections, and to stabilize your data.
To open it:
Page 31
l
l
l
Choose Debug > Select, on the menu.
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.
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.
Data tab
The Data tab contains the Data Options, which let you select your emulation, and the Selector
Options, which let you personalize the data selector's display options (see Data Selector
Page 32
Display Preferences).
The Data Selector uses the emulation (either the emulation chosen when the sample data file
was selected, or the one chosen in the last Change Emulation action task appearing above
the current task) to format the data. It displays the formatted data to let you make selections
easily using the mouse pointer.
Depending on the chosen emulation and data file, the options in the Data Selector, the Sample
data file section and the Data pane itself may change to accommodate your choice. The Line
Printer, Ascii, Channel Skip and User-Defined emulations will display the default options (see
the Emulation section) and a grid-like display of each character on each line. The following
emulations however, will be slightly different.
Database Emulation
l
l
The Database emulation changes the Browse button (
) for the Database Emulation
Configuration button ( ), which displays the Database Emulation Configuration (see
Database Emulation).
Once a database has been opened and query entered, the Data pane displays the results
of the SQL Query in a grid format, which each line representing a single returned row from
the database. Each column represents a field returned by the query, with its field name as
a row header.
XML Emulation
l
XML data is represented in a tree structure which corresponds to the data in the XML file.
Each node of the XML can be expanded to see the nodes under it. See XML Data
Emulations.
PDF Emulation
l
l
l
If you use a PDF emulation, the Data pane displays the data as you would see it in any
PDF reader.
A new zoom drop-down list is displayed to let you set the zoom in percentage or fit the
PDF to the window or the width of the window.
A new status bar, displaying the (Left, Top) and (Right, Bottom) coordinate pairs, is shown
under the Data pane.
Page 33
Metadata tab
The Metadata tab allows to load a metadata file and make a selection from it.
The Sample metadata filename is the path to the metadata file describing the current sample
data file. Buttons on the right can be used to load metadata from a file or to save the current
metadata to a file.
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
metadata. PlanetPress Design users may therefore generate a metadata file for their active
sample data file, using a PlanetPress Design document: click the Create meta data file button.
The Generated PressTalk Expression shows the expression to retrieve the currently selected
attribute or field. Metadata are retrieved with the GetMeta() function (see "Metadata selections"
on page 30). This expression is editable, which allows you to customize the string returned by
the metadata selector.
Tip
The wildcard parameter '?' indicates that the function operates on all nodes (not just one) of a given
level; see "Wild card parameter "?" " on page 27.
The Enable search on multiple levels option is available when a metadata is selected under
Production information or User defined information. If it is not selected, the option flag includes
NoCascade (+2). For an explanation of option flags in the GetMeta() function, see "Option
flags" on page 31.
Metadata level is a tree view allowing users to select the metadata level from which to display
or select metadata elements.
Page 34
The Production information list displays all metadata fields describing the current
metadata level, as selected in the Metadata Level tree view, for the current data page, as
selected in the Data page box.
The User defined information lists all metadata fields defined by the user on the current
metadata level.
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 8.8.
About Data Emulation
Emulations are like filters that can be used to read the data. When you create a document in
PlanetPress Design, you choose a sample data file and specify the emulation to use for the
chosen data. The emulation setting you choose will typically always be associated with that
document. If you choose a CSV (comma separated values) file and specify the corresponding
emulation, for instance, commas encountered in the data will typically be considered as value
separators.
Within PlanetPress Workflow, the same emulation tools as PlanetPress Design are available
throughout your process, using the Data Selector. One notable exception however is that UserDefined Emulation is not available because it uses PlanetPress Talk code, which is not
available within PlanetPress Workflow Configuration Program.
The emulation that is used in your process can change during the process, and can be different
than the one used in any PlanetPress Design document used in your process. PlanetPress
Design documents use their own emulations, as defined in the document itself from
PlanetPress Design.
Emulations in PlanetPress Workflow:
l
Line Printer
l
ASCII
l
CSV
Page 35
l
Channel Skip
l
Database
l
XML
l
PDF
Warning
PDF Emulation, also called Document Input, is only available in PlanetPress Workflow.
For more information about each emulation and how to use them, please refer to PlanetPress
Design User Guide.
Using the File Viewer
The File Viewer is like a Data Selector without any data related options, such as emulation
settings. It is displayed when doing a data selection from the Generic Splitter task (see
"Generic Splitter" on page 377) with the Use Emulation option unchecked. The only data
formatting codes to which the File Viewer responds are line breaks.
For more information on the selecting data, see "The Data Selector" on page 31.
Sample Data
PlanetPress Workflow is a versatile tool that can capture various types of data files and
dispatch this data to various PlanetPress Design documents. To fully understand PlanetPress
Workflow and how it treats data, you must understand how it is integrated into PlanetPress
Design.
This section covers issues relating to the sample data used to create your PlanetPress
Workflow configuration and to the actual data that PlanetPress Workflow will send to
PlanetPress Design documents. It is an important section which you should fully understand
before you start creating your configuration. Also included in this section are procedures that let
you make data selections as well as get data from the sample data file.
Since many of the concepts and explanations included in this chapter are closely related to
concepts and explanations found in the PlanetPress Design User Guide, we suggest that you
review this document, especially the Selecting an Emulation section.
Page 36
Choosing a Database Type Sample Data File
The procedure for selecting a sample data file that is in fact a database is the same as doing so
in PlanetPress Design. For more information, please see the relevant page in the PlanetPress
Design User Guide.
Note
You can also use the PlanetPress Workflow Database action task to get data form a
database, and output in multiple different formats such as CSV. See "Database Query"
on page 299.
Choosing a Sample Data File
In order to create your PlanetPress Workflow Process, the sample data you are going to use
has to correspond precisely to the job files that will be treated by that process, at least in terms
of structure.
The sample data file should have a relatively small number of pages (generally less than a
hundred) in order to be processed quickly, while your actual data may be much larger and take
more time to process. The sample data file should also contain at least one of every exception
you may want to detect, or data used for a specific condition. For example if you wanted to filter
out any data for clients in Canada, you would want to use a data file that has at least one user
from Canada, to test whether your condition removes it.
To choose a sample data file:
1. Click the Debug tab in the PlanetPress Workflow Ribbon.
2. Click on Select in the Data group.
3. Use the Data Selector to choose your sample data file and emulation options.
4. Click OK on the Data Selector.
PlanetPress Workflow also keeps the last 9 used data files in memory, which you can reopen to
use in the same process, or a different one.
Page 37
To reopen a sample data file used previously:
1. Click the Debug tab in the PlanetPress Workflow Ribbon.
2. Click on Reopen Data File in the Data group.
3. Click on one of the data files in the list.
4. Use the Data Selector to change the emulation options if necessary.
5. Click OK on the Data Selector.
Metadata
Metadata is a hierarchical structure describing a job. Simply put, metadata is data about data
or, in other words, information tagged to data. Metadata includes information about the data file
itself, the document, custom user fields and in some cases page properties and page counts.
PlanetPress Workflow provides a whole series of plugins to create and edit Metadata within
processes (see "Metadata Tasks" on page 509).
Note
Applications or plugins created in PlanetPress Suite 6 and using metadata will need to
be updated for use in version 8.8. No backward compatibility mode is available.
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.
Metadata structure
The hierarchical structure of the metadata is composed of a number of basic levels for adding
information to the job. These levels are, from top to bottom:
Page 38
l
l
l
Job: a file that contains 1 or more groups.
Group: a logical and ordered group of documents (ex: all invoices for a specific customer
number; all documents going to the same address, etc.).
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
page 509) 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:
l
l
l
The job contains only invoices for clients located in Montreal.
Since more than one invoice can go to the same recipient, invoices are grouped by
customer.
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.
Page 39
A single JOB can be composed of GROUPS of DOCUMENTS, which themselves are
composed of physical PAGES produced by executing a PlanetPress Design document on one
or more DATAPAGES.
Metadata elements
Each metadata node (i.e. Job, Group, Document, etc.) is described with a series of elements,
that is, system-defined attributes or user-defined fields holding static or dynamic information
about the node they are attached to. Each element has a name and a value. More specifically,
here is a definition of these 2 types of elements:
l
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).
Attributes are non-repetitive (i.e. name is unique) and do not persist through metadata
recreation.
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.
Page 40
In addition to attributes and fields, each node of type group, document or datapage has a
Boolean property called 'selected' that indicates whether or not to produce the pages under that
node. By default, this property is set to true for all nodes.
Metadata attributes reference
The Metadata attributes are categorized as either Production, Finishing or Index/Count.
Production attributes describe the production of the job and/or metadata (e.g. path and name
of the datafile, date at which metadata was created, etc.)
Finishing attributes describe the finishing intent (e.g. page dimensions, page orientation,
duplex mode, etc.).
Note
The presence of some finishing attributes depends on the PlanetPress Design document and target
device used when producing the job.
Index/Count attributes are not part of the original metadata file. They are evaluated live based
on the content of the metadata.
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 page 30 and Rule Interface).
In the following table, the last 5 columns indicate at which level the corresponding attribute is
available. This also depends on the type of job, however. In the metadata file created for an OL
Connect job, only three levels are filled with actual data about the job: Job, Group and
Document.
Page 41
Attribute
Description
Categor
y
J
o
b
Gro
up
Docum
ent
DataEncoding
(optional)
Name of the
character
encoding.
Producti
on
X
X
X
DataFile
(optional) Path
and name of
the data file
used by the
PlanetPress
Design
Document.
Producti
on
X
X
X
Date
Date the
metadata was
created in ISO
format.
Producti
on
X
X
X
Time
Time the
metadata was
created in ISO
format.
Producti
on
X
X
X
Title
Title of the
source
document.
Producti
on
X
X
X
Producer
Name of the
software that
created the
metadata.
Producti
on
X
X
X
Datap
age
Pa
ge
Page 42
Attribute
Description
Categor
y
J
o
b
Gro
up
Docum
ent
Datap
age
Pa
ge
Creator
Name of the
software that
created the
source of the
metadata.
Producti
on
X
X
X
TargetDevice
Name of the
device for
which the
metadata and
associated
data is
intended.
Producti
on
X
X
X
Dimension
Two floats
separated by a
colon
indicating the
media size in
typographical
points (ex:
612:792).
Finishin
g
X
X
X
X
X
Orientation
"Rotate0",
"Rotate90",
"Rotate180" or
"Rotate270",
indicating
respectively
portrait,
landscape,
rotated portrait
Finishin
g
X
X
X
X
X
Page 43
Attribute
Description
Categor
y
J
o
b
Gro
up
Docum
ent
Datap
age
Pa
ge
and rotated
landscape.
Side
"Front" or
"Back";
indicates
whether the
page is on the
front or the
back of the
paper sheet.
This attribute
is a "best
effort" and is
devicedependent.
Finishin
g
X
Duplex
"None",
"DuplexTumbl
e" or
"DuplexNoTu
mble";
indicates a
change of the
duplex status.
Finishin
g
X
X
X
X
X
InputSlot
Devicedependent
identifier of the
media source.
Finishin
g
X
X
X
X
X
OutputBin
Device-
Finishin
X
X
X
X
X
Page 44
Attribute
Description
Categor
y
J
o
b
Gro
up
Docum
ent
Datap
age
Pa
ge
dependent
identifier of the
media
destination.
g
Weight
Devicedependent
weight of the
media.
Finishin
g
X
X
X
X
X
MediaColor
Devicedepedent
color of the
media.
Finishin
g
X
X
X
X
X
MediaType
Devicedependent
type of the
media.
Finishin
g
X
X
X
X
X
X
X
X
X
X
X
Index
IndexInDocument
Index/C
ount
Returns the
Absolute
index of the
node within all
the nodes
under the
parent
Document.
Index/C
ount
Page 45
Attribute
Description
Categor
y
IndexInGroup
Returns the
Absolute
index of the
node within all
the nodes
under the
parent Group.
Index/C
ount
IndexInJob
Returns the
Absolute
index of the
node within all
the nodes
under the
parent Job.
Index/C
ount
J
o
b
Gro
up
Docum
ent
Datap
age
Pa
ge
X
X
X
X
X
X
X
X
X
X
Count
Index/C
ount
X
DocumentCount
Index/C
ount
X
DatapageCount
Index/C
ount
X
X
PageCount
Index/C
ount
X
X
X
SelectedCount
Index/C
ount
X
X
X
SelectedDocument
Index/C
X
X
Page 46
Attribute
Description
Categor
y
J
o
b
Gro
up
Count
ount
SelectedDatapage
Count
Index/C
ount
X
X
SelectedPageCoun
t
Index/C
ount
X
X
SelectedIndexInDo
cument
Returns the
Absolute
index of the
node within all
the selected
nodes under
the parent
Document.
Index/C
ount
SelectedIndexInGr
oup
Returns the
Absolute
index of the
node within all
the selected
nodes under
the parent
Group.
Index/C
ount
SelectedIndexInJo
b
Returns the
Absolute
index of the
node within all
the selected
nodes under
Index/C
ount
X
Docum
ent
Datap
age
Pa
ge
X
X
X
X
X
X
X
X
X
Page 47
Attribute
Description
Categor
y
J
o
b
Gro
up
Docum
ent
Datap
age
Pa
ge
the parent Job.
NumCopies
Indicates how
many times
the job is set
to execute, as
set when
printing using
a Windows
driver.
Index/C
ount
X
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.
Producti
on
X
Metadata tasks
A set of special Workflow plugins allows to edit the metadata during a Workflow process. See
"Metadata Tasks" on page 509.
Metadata Tools in PlanetPress Design
PlanetPress Design includes a complete set of metadata-related functionality, which can be
referred to as Metadata Tools. These tools can be used to generate metadata, retrieve or define
metadata elements, and build the metadata structure.
Using PlanetPress Design, one can:
Page 48
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.
Firstly, two buttons at the top right corner of this tab allows to load or save a metadata file
generated for the current sample datafile.
Secondly, the metadata tab graphically displays all elements (i.e. attributes and fields)
available at the current level (i.e. Page, Datapage, Document, etc.). More importantly, these
elements are graphically selectable, like any other part of the sample datafile when using the
'Select Data' option inside a Text object, for example.
Page 49
Metadata in document properties
Page 50
The Metadata tab in the properties of a PlanetPress Design document allows to easily define
documents or groups.
Metadata fields
The Metadata Fields in the structure of a PlanetPress Design document allow to easily define
documents or groups, by dragging and dropping data from the Sample Data directly onto the
document's Metadata Fields.
Data Repository
The Data Repository is a permanent structure to store data that can then be reused, modified or
augmented at a later time, by different processes.
This feature was introduced in version 8.5.
The Data Repository is especially useful in situations where data needs to be kept in between
processes. A few examples:
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
Page 51
request is received from an already authenticated user, if the session has expired, what
the user name is, etc.
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.
l
Structure
As can be seen in the "Data Repository Manager" on page 721, the Data Repository consists of
Groups, Keys and KeySets.
Feature Name
Description
Equivalent Database Terminology
Group
A Group is defined by its Keys
(columns), and may contain 0 or
more KeySets (rows) within it.
Table
Key
A Key is defined only by its name.
The Data Repository only supports
STRING values and any data
inserted into it is converted to
string automatically. The maximum
size of a single key is 1 billion
bytes.
Column/Field
KeySet
A group may contain as many
KeySets (rows), which contain
variable data, as necessary. A
KeySet is inserted using the "Push
to Repository" on page 331 task.
Row/Record
Lookup
A method of retrieving one or more
KeySets from a group in the data
repository.
Query
Page 52
Accessing the Data Repository
Via plugins
Storing data in the Data Repository
Data can be stored in the Data Repository using the Push to Repository task (see "Push to
Repository" on page 331).
Retrieving data from the Data Repository
In any Workflow task where variable data is allowed (recognisable by the maroon field labels),
information can be retrieved from the Data Repository using a Lookup function. Right-click a
field with a maroon label and select Get Repository Location. This will bring up the "Data
Repository Manager" on page 721. Select a Group, Key and KeySet entry to determine which
value or values should be retrieved at runtime; then click OK. The Lookup Function Syntax,
displayed at the bottom left of the Data Repository Manager, will be copied into the field.
The syntax is of the Lookup function is:
Lookup(Group_Name, Key_To_Retrieve, Key_To_Match, Value_To_Match)
This function may also be used anywhere else where the contextual menu gives access to it.
You could, for example, use it on the General tab of the Create File task, to fill in the value of a
key/value pair in a JSON string.
Tip
The Data Repository Manager displays, at the bottom left, the syntax used for accessing a specific
value.
Scripts
In a script you can access the Data Repository using the "Data Repository API" on page 121.
For a quick start, turn to this How-to: Interacting with the Data Repository API.
Data Repository Manager
At design-time, the Data Repository Manager may be used to insert or remove Groups, Keys
and KeySets; see "Data Repository Manager" on page 721.
Page 53
Where to find the Data Repository
In case the Repository contains valuable information that must not be lost in case of a hardware
failure, create a backup of the repository.
The Data Repository is located in the following folder:
%ProgramData%\Objectif Lune\PlanetPress Workflow 8\PlanetPress Watch\Repository.
About Documents
A Document is a file sent to PlanetPress Workflow by PlanetPress Design and is used to
produce an output when merged with data. A Document can be an invoice, a report, a receipt or
anything else, but by itself it is empty and without any variable data.
Document are typically selected in Output Tasks, but can also appear in other tasks that
produce formatted data such as the Digital Action task and the Add Document task.
Documents contain static data such as logos, addresses and graphic formatting, as well as
placeholders for data. Documents can also contain conditions and programming logic. For
more information about PlanetPress Design documents, please see the PlanetPress Design
User Guide.
Import Documents
This procedure describes how to import variable content documents created in PlanetPress
Design. Importing documents can be useful when transferring configurations between
PlanetPress Workflow installations.
To import documents into PlanetPress Workflow:
1. Choose File | Import Documents. The Import PlanetPress Design Document dialog
box appears.
2. In the File type box, select the desired file type.
3. Navigate to the document you want to import, select it and click Open.
Page 54
The document is imported and displayed in the Configuration Components pane. This
physically installs the documents to the Documents folder relative to the install folder of
PlanetPress Workflow.
Import PrintShop Mail Documents
This procedure describes how to import variable content documents created in PrintShop Mail.
Importing documents can be useful when transferring configurations between PlanetPress
Workflow installations.
To import documents into PlanetPress Workflow:
1. Click the PlanetPress Workflow button. The Import PrintShop Mail Document dialog
box appears.
2. Choose Import, then PrintShop Mail Documents.
3. Navigate to the document you want to import, select it and click Open. The document is
imported and displayed in the Configuration Components pane. This physically installs
the documents to the Documents folder relative to the install folder of PlanetPress
Workflow.
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
Page 55
does not exist, or printing to a printer that cannot be found.
When such an error occurs, in most cases you would want to be aware of it and to take certain
actions in order to correct or report the error. This is where our error handling features come in
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
the task.
Using the On Error tab
Whenever an error is triggered either during debugging or when a process runs in production,
the settings specified in the On Error tab of the task that generated the error will be used to
determine a course of action.
On Error Tab
The On Error tab is common to all tasks. Details can be found in the" Task Properties Dialog"
on page 777.
By default, any action task, branch, splitter or condition that generates an error will simply be
ignored, and the task just under it (not within a branch) will be given control of the job file
without any modification. Any initial input task that generates an error will stop the process from
running as a whole, and output tasks will not generate output. The On Error tab can be used to
overwrite the default behaviors.
l
l
l
Send to Process: Check this option to send the job file to an error management process.
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.
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
Page 56
the process. When an error occurs in a loop (or in a plugin that acts like a loop), the
loop may log the error, terminate the current iteration and proceed with the next
iteration.
l
l
l
l
l
l
l
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.
Stop Process: The process is stopped and no more processing is done. No further
output is produced.
Log Message: Check this option to enable logging a custom error message in the
PlanetPress Workflow log file and in the Windows Application Events.
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.
Store the message in variable: Select in which jobinfo, local or global variable you
want to store the message content.
ID: Enter an error ID. This ID will be visible in the Windows Event Viewer. However, the
ID is not visible in the PlanetPress Workflow log file.
Store the ID in variable: Select in which jobinfo, local or global variable you want to
store the error ID.
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.
Common Errors
Though some error messages are specific to a task in particular, others may apply to any and
all tasks because they are related more to the system than to PlanetPress itself. Some
examples would be W3813, W3830, W3991, W4005. These correspond to issues such as not
having any space to write files, permission errors on folders or files, etc.
Creating and Using Error Processes
An Error Process is a special type of process that never runs on its own, and cannot be called
using the GoSub or Send to Process tasks. It can only be used in the On Error tab of a task in
Page 57
your process, and will be triggered if the Send to Process option is checked in that tab and an
error process is selected in the drop-down list.
To create an error process, simply replace the initial input task by the InputErrorBin input task,
and that process automatically becomes able to handle error jobs sent to it. It is up to you,
however, to decide how that error job will be handled.
For example, you could place the job file in a specific folder, then send an email to a supervisor
indicating that a job has failed. Or you could update a database with an error status so that it
appears on a customer's online order. You could also zip the order up and send it to an
administrator, while simultaneously advising the person that sent the job that it failed.
You can have as many error processes as you can normal processes - that is, you are limited to
512 processes, subprocesses, startup processes and error processes combined.
The following information is available from within your information process when it is
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
A series of variables containing information about the error, the task that triggered it and
the process that contained it. See "Standard Variables" on page 646
Note
Local variables in the process are not sent to error processes, even if the error process has a variable
of the same name.
Accessing the Logs
If your process is running live in PlanetPress Workflow service, you have two ways of seeing
what is happening, now or in the past.
Page 58
To view what processes are running and processing data as it happens:
1. In the PlanetPress Workflow Ribbon, click on the Tools tab, then select Service Console
in the Services group. The PlanetPress Workflow Service Console opens.
2. Click on the service you want to check, including:
l
PlanetPress Workflow
l
LPD Server
l
Telnet Capture
l
Serial Capture
l
HTTP/SOAP Server
l
LPR Client
l
FTP Client
l
PlanetPress Image
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.
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
page 751.
To view logs for jobs that have already processed
By default, the logs are available in the following folder:
C:\Documents and Settings\All Users\Application Data\Objectif Lune\PlanetPress
7\PlanetPress Watch\Log
You can access this folder more quickly by using this procedure:
Page 59
1. From PlanetPress Workflow Configuration software, press CTRL+SHIFT+ALT+F4
simultaneously. The PlanetPress Workflow working folders are opened.
2. Double-click on the folder called Log.
3. There are multiple logs displayed here, including:
l
l
ppwYYYYMMDD.log - PlanetPress Workflow logs, including the year, month and
day of the log (from midnight to midnight).
FTP, LPD, LPR, ??? (to be verified)
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.
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.
Page 60
The numbers on the left indicate the task index, the folder capture being level 1 and the Text
condition being on level 4.
To resubmit backed up input data files:
1. In the PlanetPress Workflow Ribbon, go to the Tools tab then click Resubmit Job in the
Services group. The File Resubmission dialog box is displayed.
2. From the Process box, select the process for which you want to resubmit the backed up
input files.
3. From the Task index box, select the index level to which you want the data to be sent.
The index is the position in the process where you want to submit the job file.
4. In the list of backed up input files, select the file you want to resubmit.
5. Using the From page and To page boxes, select the data pages that you want to
resubmit. If you want to resubmit all the data pages from the selected input file, enter 0 in
both boxes.
6. Click Send to resubmit the data.
7. To resubmit backed up input files for the same process or for a different one, repeat step 2
to step 6.
8. To close the File Resubmission dialog box, click Close.
Page 61
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.
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
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.
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.
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)'
Page 62
Debugging your PlanetPress Workflow Process
Debugging a process is separated in two parts. The first part is designing the process, which is
to add the different tasks, branches and conditions to the process and configuring them. The
second step is testing whether or not the process and configuration actually work.
Before debugging begins, the following prerequisites must be completed:
l
l
There must not be any Unknown Tasks in the process.
A sample data file must be selected.
To choose a sample data file, click the Select button in the PlanetPress Workflow
Ribbon's Debug tab and browse to a valid sample data file.
Alternatively, if a document present in the configuration contains the necessary data file, it
can be attached to the process easily. For example to use a sample data file included in a
Connect data mapper configuration: select Connect Resources > Data Mapping
Configurations > [your data mapping configuration], right-click a data file and choose
Set as sample data file.
How to do this with Planet Press Suite Design Documents is explained here: Use Data
and Metadata Files Attached to Documents.
When debugging your process, it is important to keep in mind that:
l
l
l
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!
Since the initial input task is not performed, there is no actual job information to be added
at the beginning of a data file. Note that you can use the Object Inspector on your
process to enter sample job information as required.
If any task makes an operation on the system (for example, capturing files, sending data,
printing, etc), it is actually executed, not simulated.
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 page 702 for more details.
Page 63
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. For more
information on how to capture your sample data file properly, please refer to the
PlanetPress Trigger and Data Capture Guide.
Debugging can be run in different ways:
l
l
l
From the Debug tab, click on Step. This executes only the first task in the process and
waits for further action.
From the Debug tab, click on Run. This executes the complete process, step by step,
until it is completed.
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
l
l
l
l
l
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).
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.
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).
Click on View as PDF to view the current job file in Adobe Acrobat if it is present (this will
work only for PDF job files).
Click on View Metadata to open the data selector and see the current state of the
process' Metadata.
Click on View as Hex to view the current job file in the internal Hex editor.
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.
Page 64
l
l
l
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.
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.
Look at the Messages Area pane to see any message generated by the tasks that run
(See " The Message Area Pane" on page 726).
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
page 725.
Debugging and Emulation changes
One of the most useful case where debugging is crucial is whenever the job file is converted to
another type of emulation, or if a new data file of a different emulation is used within the
process. For example, if a process starts with a Line Printer data file and the converts it into a
PDF, it is not possible to do any data selection on the PDF because the Line Printer emulation
is active by default. The debugging features can easily resolve this limitation.
The first method is used if your process has all the required tasks, but data selections after an
emulation change are necessary.
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.
l
l
Step through the process in debug mode until you reach the emulation or data change.
Click on View as Text (or View as PDF if 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.
Page 65
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 7.4 and higher also has an option that can be used in conjunction
with the previous to avoid skipping through large processes:
l
l
l
Step through the process until the emulation or data change, as in the first method.
Save the data file locally and then select it as your sample data file, as with the second
method.
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" on page 656.
The Plug-in Bar
PlanetPress Workflow offers a constantly increasing number of plugins, while always allowing
third party plugins to be installed and set up to be used by PlanetPress Workflow. The
PlanetPress Workflow Plug-in Bar lists all plugins available in PlanetPress Workflow, and is
divided into categories, which users can customize at will.
Most of the PlanetPress plugins are installed by default, but other plugins may be added.
Because the plugins are always expected to execute some sort of task, they are always
referred to, in this documentation, as tasks, except in the specific case of importing a new
plugin or customizing the Plug-in Bar.
Categories
The default categories list plugins according to what type of task they achieve. When first
starting your PlanetPress Workflow program, the following categories are used:
Page 66
l
Inputs
l
Actions
l
Data splitters
l
Process logic
l
Connectors
l
PlanetPress Capture
l
Metadata Related
l
OL Connect Send
l
OL Connect
l
Outputs
Note
An Uncategorized category is dynamically created if your PlanetPress Workflow finds any plugin
that would not be part of the existing Plug-in Bar. User-defined plugins and third party application
plugins falls into such a category.
Settings & Customization
The Plug-in Bar can be customized according to your needs and the plugins you most
frequently used.
You can use the horizontal dark blue bar separating the plugin area and the list of categories to
change how many plugin categories are displayed as the full-width bar with the title, and how
much are displayed as icon only. Move the bar up to display more full-width categories, or
down to display them more as icons.
Furthermore, the Plug-in Bar can be customized using the popup indicator control ( ).
Customizing the Plug-in Bar is mostly used for third party or legacy plugins.
Using the contextual menu displayed by the popup indicator, you can:
l
Insert, delete and rename custom categories.
l
Move categories up or down.
l
Import third party or legacy plugins.
Page 67
l
Move plugins from one custom category to another (that you cannot move default plugins
from the default categories, you can only copy them)
l
Copy plugins from one custom category to another by holding the CTRL key.
l
Delete plugins from any custom category by using the Delete key.
l
Revert to the default Plug-in Bar by selecting Reset to default.
To import a plugin:
1. Click on the popup control ( ).
2. Click on Import Plugin.
3. Browse to the location of the plugin DLL file.
4. Click on Open.
5. New plugins appear in the Uncategorized category.
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
l
l
Windows output queues let you send jobs to a local printer. See "Windows Output
Printer Queue" on page 72.
Send to Folder output queues let you save jobs to a local or network folder from
which they can be picked up and printed. See "Send to Folder Printer Queue" on
page 76.
Remote printing:
l
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 page 74.
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 page 73.
Page 68
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
page 629.
PlanetPress Workflow provides you with three main printing scenarios:
l
l
Send output data to be printed as is: PlanetPress Workflow sends a file containing only
the data to the selected queue.
Send output data to be merged with a document on the printer: PlanetPress
Workflow sends one of two things:
l
l
l
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.
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.
In both cases, the document+data merging process takes place inside the printer.
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.
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
balancing or not (See "Load Balancing" on page 77).
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:
Page 69
l
l
l
l
Windows Output printer queues are used to send print jobs to local or network printers.
See "Windows Output Printer Queue" on page 72.
LPR Output printer queues are used to send print jobs to printers via the LPR/LPD
protocol. See "LPR Output Printer Queue" on page 73.
FTP Output printer queues are typically used to send print jobs to FTP sites. See "FTP
Output Printer Queue" on page 74.
Send to Folder printer queues are typically used to send print jobs to local or network
folders. See "Send to Folder Printer Queue" on page 76.
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.
Properties
Advanced tab
l
l
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.
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.
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.
Page 70
l
l
l
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.
Delete: Click to remove a command from the Commands box.
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
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
code:
Typical use in printing context:
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
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
(CRLF)
\n
Goes to a new line
Page 71
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
l
l
Printer queue: Select the Windows printer queue to which you want to send print jobs.
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.
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.
Advanced tab
l
l
l
l
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.
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.
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.
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.
Delete: Click to remove a command from the Commands box.
Page 72
l
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
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 page 767).
Properties
General tab
l
l
l
l
l
Printer address: Enter the IP address or host name of the printer receiving LPR jobs.
Queue name: Enter the printer queue name. Based on printer and network requirements,
this property may not be required.
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
data in the TeX DVI format. Select (o) PostScript file if the job file is a PostScript file.
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.
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.
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.
Page 73
l
l
l
l
l
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.
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.
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.
Delete: Click to remove a command from the Commands box.
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
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.
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
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.
Page 74
l
l
l
l
l
l
Password: Enter a password associated with the FTP server user name entered above.
Use FTP Client default port number: Forces the FTP connection on port 21, the default
FTP port.
FTP Port: Enter the FTP port to use. This option is disabled if Use FTP Client default port
number is checked. The port should always correspond with the server's port number.
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.
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.
Connection mode group
l
l
Active: Select to prompt the ftp client to use the active mode when sending files to
the FTP server.
Passive: Select to prompt the ftp client to use the passive mode when sending files
to the FTP server.
Advanced tab
l
l
l
l
l
l
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.
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.
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.
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.
Delete: Click to remove a command from the Commands box.
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
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 75
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
l
l
l
Folder: Enter the path of the folder to which the print jobs are to be saved.
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.
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.
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
l
l
l
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.
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.
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.
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.
Delete: Click to remove a command from the Commands box.
Page 76
l
l
Command description: Use this box to edit the description of the command currently
selected in the Commands box.
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
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
(trigger+document+data).
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.
Page 77
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).
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.
Page 78
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:
l
This will create a PostScript data file when the option Create Composed Document
Stream (with Medatada) is unchecked.
l
l
This format can be obtained using PlanetPress Workflow.
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.
Page 79
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.
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.
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.
Page 80
About Processes and Subprocesses
Processes
A process is a single workflow within the configuration. A process 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 "The
Configuration Components Pane" on page 674. Processes in a configuration will always run
concurrently. You can schedule processes to run only at certain times or intervals (see "
Process Properties" on page 704).
There are three types of processes available to you:
l
l
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.
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.
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.
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.
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
Page 81
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.
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.
Note
Subprocesses do not have the "General Tab" which is only used for scheduling, but they
do have the Information Tab.
Options
General tab
l
l
l
Active: Select to make the process active. Clear to prevent this process from running
when you send the configuration to PlanetPress Workflow.
Startup process: Select to make this process a startup process.
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 82
l
l
l
l
l
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 page 752. For example if the
maximum number of thread is 10 and you specify 50% here, a maximum of 5 replications
will occur (the original process + 4 copies).
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.
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.
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.
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.
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
l
l
Select First, Second, Third or Fourth to have the process run on the first, second,
third or fourth week.
Select Last to have the process run only on the last week.
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 83
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.
While blocks mean the process will not be active.
Page 84
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 85
l
l
l
To select all of the time segments for a given day or date, click the day or date on the top
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.
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.
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.
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.
Technical
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.
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
l
Description: A one-line box to give a title or short description to your process.
Comments: A multi-line box to give more detailed information, for example the file format
expected, explanation of the system in general.
Page 86
Activate or Deactivate 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 "Send your Configuration" on page 17).
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.
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).
Convert 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
process, the branch is removed and replaced with a GoSub action task referring to the newly
created subprocess.
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.
Page 87
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 to be usable in the newly
created subprocess.
Import Processes from Another Configuration File
You can import individual processes or groups of processes from a PlanetPress Workflow
configuration file without having to import the contents of the entire configuration file.
PlanetPress Workflow Configuration 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:
l
l
Complete PlanetPress Watch 4 to 6 configurations, as well as PlanetPress
Workflow 7 configurations.
Specific processes from Version 6 and 7 configurations, including their local
variables.
l
Specific subprocesses from any PlanetPress Workflow 7 Tools configurations.
l
Specific global variables from PlanetPress Workflow 7 Tools configurations.
l
Specific PlanetPress 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
Page 88
configurations both include a startup process, the one in the imported configuration will
become a standard process.
Important considerations
l
l
When importing a PlanetPress Workflow configuration file, your PlanetPress Design and
PrintShop Mail document 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).
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.
Generally this will happen only when calling a third-party software using the Run External
Program plugin, but is also valid if using a Script that generates a dialog that someone must
click or interact with.
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.
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 89
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.
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.
Languages
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.
By default, the Run Script task expects VBScript. You can select another language via the
Language menu in the Script Editor that opens when you add the Run Script task to a process.
You can also set another language as the default for the Run Script task, in the Workflow
preferences (go to Behavior > Default Configuration).
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.
Page 91
Condition or Action
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 page 119
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 page 110
function. The same goes for any job info, local or global variables, unless you use the
"Watch.SetJobInfo" on page 114 or "Watch.SetVariable" on page 116 functions to modify them.
APIs
Multiple APIs (methods of communicating with PlanetPress Workflow scripting tools) are
available through the scripting engine, in all languages.
l
l
l
l
l
l
l
The Watch object is used to communicate with your current process and configuration.
See "The Watch Object" on page 105.
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.
You can manipulate PDF files using the PlanetPress Alambic API. See AlambicEdit
Library Reference. Note that the PlanetPress Alambic API is part of the PDF Tools.
You can manipulate the metadata in your process using the Metadata API. See Metadata
API Reference.
You can communicate with a SOAP server using the SOAP API. See "SOAP Server API
Reference" on page 98.
You can communicate with the PlanetPress Capture Database using the Capture API.
See Capture API Reference.
You can communicate the with the Data Repository using the Data Repository API. See:
"Data Repository API" on page 121.
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,
Page 92
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).
Use 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 page 769.
Import and Export Scripts
Both the Script Editor and XSLT Editor let you import and export scripts.
Note
When you import a script, it replaces any script currently displayed in the editor.
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.
Page 93
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,
make a selection in the Save as type drop-down list.
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:
Note
If you only want to search a particular section of the script, you should select it before performing
the following procedure.
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
l
l
Text to find: Enter a new search string or select a previous search from the dropdown list.
Case sensitive: Select to limit the search to instances of text with the same case as
the text in the Text to find box.
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.
Page 94
l
l
l
l
l
l
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.
Global: Select to search the entire content of the script.
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.
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.
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.
From cursor: Select to start the search from the position of the cursor.
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.
Page 95
l
l
l
l
l
l
l
l
l
l
l
Text to find: Enter a new search string or select a previous search from the dropdown list.
Replace with: Enter the string that will replace the string displayed in the Text to
find box.
Case sensitive: Select to limit the search to instances of text with the same case as
the text in the Text to find box.
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.
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.
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.
Global: Select to search the entire content of the script.
Selected text: Select to find matching text only within a text block you select. The
text must be selected before you run the search.
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.
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.
From cursor: Select to start the search from the position of the cursor.
Page 96
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
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.
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.
Once again, if you selected Prompt on replace, a dialog box opens to ask you whether
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 page 769).
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,
Page 97
bookmarks may be harder to see. To control line number and gutter display, see "Editor
Options" on page 769.
Note
Bookmarks are not preserved when you close the editor.
To toggle bookmarks:
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
Page 98
implements five methods that will allow SOAP clients to submit jobs and get information from
PlanetPress Workflow executing them.
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.
Since the SOAP Server API Reference is primarily targeted at programmers or systems
engineers, it is rather technical.
SOAP API - SubmitJob
Syntax
SubmitJob (File, SubmitJobInfStruc , ReturnJobFile, user name,
Password) : SubmitJobResult
Description
The SubmitJob method allows users to remotely submit files to their PlanetPress Workflow from
a SOAP client. The SOAP client has the option to wait for a response file from PlanetPress
Workflow SOAP server.
Arguments
l
l
l
File – base64Binary. This is an array of byte base64 encoded (see
http://en.wikipedia.org/wiki/Base64).
SubmitJobInfStruc – Structure containing any required information to prepare the file for
a valid insertion into a PlanetPress Workflow process.
ReturnJobFile – Boolean value. When true, PlanetPress Workflow SOAP server returns
the job file. When false, there no file is returned to the SOAP client. (For example: when
submitting a job for print, there is no need to return a file)
l
user name – String containing the user name.
l
Password – String containing the password. This value is case sensitive.
Page 99
Return Value
l
l
SubmitJobResult - Structure containing the following information:
Success – Integer indicating the Success/Error level of the operation. A result of 0 means
the operation was successful.
l
Message – String containing text information about the Success/Failure status.
l
SubmitJobInfStruc – See point SubmitJobInfStruc for details.
l
ResultFile – base64Binary. If Success is different than 0 or the ReturnJobFile was set to
False in the initial call, no file is returned. Otherwise, ResultFile contains the job file, as it
existed at the completion of the PlanetPress Workflow process (for instance, if the
process creates a PDF and sets it as the current job file, the PDF is the file that gets
returned to the calling SOAP client).
Note
The SubmitJob method only returns a file if the PlanetPress Workflow process contains a SOAP
Input task.
Note
If ReturnJobFile is set to true, the schedule options of the process should be set to a pooling lower
than four seconds, so the client application gets a timely response.
Note
To return the file, the process must be completed before the timeout of the server occurs. The
Timeout option can be set in your PlanetPress Workflow preferences.
SOAP API - PostJob
Syntax
PostJob (File, PostJobInfStruc , user name, Password) :
PostJobResult
Page 100
Description
The PostJob method allows users to remotely submit files to PlanetPress Workflow by using
the Resubmit from here feature. The main advantage of this feature is that it allows a user to
specify a starting task index from which the File is to be processed.
Parameters
l
l
File – base64Binary. This is an array of byte base64 encoded (see
http://en.wikipedia.org/wiki/Base64).
PostJobInfStruc – Structure containing any required information to prepare the file for
resubmission into a PlanetPress Workflow process.
l
user name – String containing the user name.
l
Password – String containing the password. This value is case sensitive.
Return Value
l
l
PostjobResult - Structure containing the following information:
Success – Integer indicating the Success/Error level of the operation. A result of 0 means
that the operation was successful.
l
Message – String containing text information about the Success status.
l
PostjobInfStruc – See point PostJobInfoStruct for details.
Note
The task index can be retrieved by using the GetProcessTaskList method. See point
GetProcessTaskList for details.
Note
The PostJob method can never return a file to the calling application.
Page 101
SOAP API - GetProcessList
Syntax
GetProcessList (user name, Password) : GetProcessListResult
Description
The GetProcessList function allows SOAP clients to request the list of available PlanetPress
Workflow processes, based on their authentication credentials.
Parameters
l
user name – String containing the user name.
l
Password – String containing the password. This value is case sensitive.
Return Value
l
l
GetProcessListResult - Structure containing the following information:
Success – Integer indicating the system-defined Success/Error level of the operation. A
result of 0 means that the operation was successful.
l
Message – String containing text information about the Success status.
l
ProcessList – Structure containing the following information details.
l
ProcessName – String containing the process name
l
Active – Boolean value specifying whether the process is currently active.
Note
To obtain access to the complete list of processes for all users, the end-user must have administrator
privileges.
SOAP API - GetProcessTaskList
Syntax
GetProcessTaskList (ProcessName, user name, Password) :
GetProcessTaskListResult
Page 102
Description
The GetProcessTaskList function will allow a user to remotely request the tasks list of a
process. This will be useful with the PostJob API since it needs a TaskIndex.
Parameters
l
ProcessName – The Name of the PlanetPress Workflow process.
l
user name – String containing the user name.
l
Password – String containing the password. This is case sensitive.
Return Value
l
l
GetProcessTaskListResult – Structure containing the following information:
Success – Integer indicating the system-defined Success/Error level of the operation. A
result of 0 means that the operation was successful.
l
Message – String containing text information about the Success status.
l
TaskNames – Structure containing the following information details.
l
TaskName – String containing the name of the task
l
TaskIndex – Integer : 1 based index of the task.
l
TaskDepth – Integer : 1 based depth of the task.
Note
The TaskNames array will be sorted by the execution order of the process with the primary input of
the process having an index of 1.
SOAP API - GetSOAPProcessList
Syntax
GetSOAPProcessList (user name, Password) : GetSOAPProcessListResult
Page 103
Description
The GetSOAPProcessList function will allow users to request the list of PlanetPress Workflow
processes that contain a SOAP Input plugin with the SOAP action name. This is useful when
working with the SubmitJob API since it requires a SOAPActionName.
Parameters
l
user name – String containing the user name.
l
Password – String containing the password. This is case sensitive.
Return Value
l
l
GetSOAPProcessListResult – Structure containing the following information:
Success – Integer indicating the system-defined Success/Error level of the operation. A
result of 0 means that the operation was successful.
l
Message – String containing text information about the Success status.
l
ProcessList – Structure containing the following information details.
l
l
SOAPActionName – String containing the name of the process as seen in your
PlanetPress Workflow.
Active – Boolean value indicating if the process is active in your PlanetPress Workflow.
Note
If a user has administrator privilege, he will have access to all processes and therefore he will see all
the processes.
SOAP API - PostJobInfoStruc
PostJobInfStruc
Structure containing any required information to prepare the file for resubmission into a
PlanetPress Workflow process.
l
VariableList – Array of complex type, containing pairs of variable names and variables
value. The list also contains the JobInfo variables.
Page 104
l
VariableName – String
l
VariableValue – String
l
ProcessName – String - Name of the PlanetPress Workflow process.
l
TaskIndex – Integer - 1 based index of the task where the resubmission should start.
l
FirstPage – Integer - First page of data to process.
l
LastPage – Integer - Last page of data to process.
Note
If both FirstPage and LastPage are set to 0, the entire data file is used.
SOAP API - SubmitJobInfStruc
SubmitJobInfStruc
Structure containing any required information to prepare the file for a valid insertion into a
PlanetPress Workflow process.
l
l
VariableList – Array of complex type, containing pairs of variable name and variable
value. The list also contains the JobInfo variables
l
VariableName – String
l
VariableValue – String
OAPActionName – String containing the name of the Input SOAP task’s action name.
The Watch Object
PlanetPress Workflow scripting offers a number of methods of communicating with your
process by means of PlanetPress Workflow automation object's methods and functions. The
automation object is available in all 4 languages through their own syntax - the examples
provided here are for VBScript.
Note
While the functions here are in mixed case to simplify reading, it's important to note that
Page 105
some languages (especially JavaScript) are case-sensitive and will require the proper
case. Examples in this chapter will always use the proper case when relevant.
Here is a list of the methods and functions that are available to you through the automation
object (or "Watch" object). While these examples are all in VBScript, you can click on any
variable name to open a page to see examples for each supported language.
Variable Name
Description
Example Usage (VBScript)
"Watch.GetJobFileName" on
page 110
Retrieves a string containing the job path and file
name located in the job spool folder.
Example Usage:
str = Watch.getjobfilename
"Watch.GetOriginalFileName" on
page 111
Retrieves a string containing the job's original path
and filename. Note: this filename is generally no
longer available if it has been captured by Watch.
Example Usage:
str = Watch.getoriginalfilename
"Watch.GetMetadataFilename"
on page 112
Retrieves a string containing the job's metadata path
and filename. This is useful when using the Metadata
API in your script.
Example Usage:
str = Watch.getmetadatafilename
"Watch.GetJobInfo" on page 113
Retrieves the content of a numbered job info (%1 to
%9).
Example Usage:
str = Watch.getjobinfo(9)
"Watch.GetVariable" on page 115
Retrieves the content of a local or global variable by
name.
Page 106
Variable Name
Description
Example Usage (VBScript)
Example Usage:
str = Watch.getvariable("Varname")
"Watch.ExpandString" on
page 116
Retrieves the content of any Workflow string,
containing any variable available to Watch, including
data selections.
Example Usage:
watchDate = Watch.expandstring("%y-%m-%d")
"Watch.Log" on page 117
Writes to the Workflow log file, or the message window
when in debug - can accept multiple log levels from 1
(red) to 4 (gray).
Example Usage:
Watch.log "Hello, World!",1
"Watch.ShowMessage" on the
next page
Displays a popup dialog box to the user (user has to
be logged on).
Example Usage:
Watch.showmessage("Hello, World!")
"Watch.InputBox" on page 112
Prompts the user for a string and returns the value (will
not work when running as a service)
Example Usage:
str = Watch.inputbox
("Caption","Message","default")
"Watch.SetJobInfo" on page 114
Writes the value of a string to a numbered job info.
Example Usage:
Watch.setjobinfo 9, "String"
"Watch.SetVariable" on page 116
Writes the value of a string to a local or global variable
by name.
Example Usage:
Watch.setvariable "global.GlobalVar", "Hello
Page 107
Variable Name
Description
Example Usage (VBScript)
World!"
"Watch.Sleep" on page 119
Pauses all processing for X milliseconds.
Example Usage:
Watch.sleep(1000)
"Watch.ExecuteExternalProgram"
on the facing page
Calls and executes an external program in the
command line.
Example Usage:
Watch.executeexternalprogram "del *.ps" "c:\" 0
true
"Script.ReturnValue" on
page 119
Returns a boolean True or False value to a Workflow
scripted condition
Example Usage:
Script.returnvalue = 1
Watch.GetPDFEditObject
Is used to manipulate PDF files using the AlambicEdit
API.
See the AlambicEdit API for more information.
Watch.ShowMessage
Displays a message to the user. This method is the same as PW_ShowMessage. Use this
method to show the current message displayed whether or not a user is logged in. Note that for
this method to work, the "Run on Desktop" option must be enabled and you must be logged on
as the same user as the PlanetPress Watch Service.
Examples
In the following example, showmessage() displays a dialog box saying “test message”.
Page 108
VBScript
Watch.ShowMessage("test message")
JavaScript
Watch.ShowMessage("test message");
Python
Watch.ShowMessage("test message")
Perl
$Watch->ShowMessage("test message");
Watch.ExecuteExternalProgram
Calls and executes an external program through a specified command line. The program's
execution will be directed by the appropriate flags specified as this method's parameters.
Syntax
Watch.ExecuteExternalProgram const CommandLine: WideString; const WorkingDir:
WideString; ShowFlags: Integer;
WaitForTerminate: WordBool: integer;
const CommandLine: The command line to execute as a widestring.
const WorkingDir: The working directory for the execution of the command line as a
widestring.
ShowFlags: Integer value representing the flag to use during the execution of the command
line. These flags have an effect on the execution window opened by the
ExecuteExternalProgram procedure.
Flag
Effect
0
Hide the execution window.
1
Display the window normally.
Page 109
Flag
Effect
2
Display the window minimized.
3
Display the window maximized.
4
Makes the window visible and brings it to the top, but does not make it the active
window.
WaitForTerminate : A Boolean value that, if true, pauses the script until the command line has
been fully executed.
Examples
VBScript
Watch.ExecuteExternalProgram "lpr -S 192.168.100.001 -P auto
c:\myfile.ps", "c:\", 0, true
JavaScript
Watch.ExecuteExternalProgram("lpr -S 192.168.100.001 -P auto
c:\\myfile.ps", "c:\\", 0, true);
Python
Watch.ExecuteExternalProgram("lpr -S 192.168.100.001 -P auto
c:\\myfile.ps", "c:\\", 0, True)
Perl
$Watch->ExecuteExternalProgram("lpr -S 192.168.100.001 -P auto
c:\myfile.ps", "c:\", 0, true);
Watch.GetJobFileName
Returns the complete path and file name of the job. This method is the same as PW_
GetJobFileName. getjobfilename() obtains the file name of a PlanetPress Workflow process.
This is useful for manipulating the job file, for example to replace data within it. If your script
writes to this file, the modified contents will be used by the next plugin in your process.
Page 110
Example
In the following example, GetJobFileName() retrieves the name of the job file, which is then
logged using "Watch.Log" on page 117.
VBScript
Dim s
s = Watch.GetJobFileName
Watch.Log "The job filename is: " + s, 3
JavaScript
var s;
s = Watch.GetJobFilename();
Watch.Log("The job filename is: " + s, 3);
Python
s = Watch.GetJobFileName()
Watch.Log("The job filename is: " + s, 3)
Perl
$s = $Watch->GetJobFileName;
$Watch->Log("The job filename is: " + $s, 3);
Watch.GetOriginalFileName
Returns the original name of the file, when it was captured. This method is the same as PW_
GetOriginalFileName.
Example
VBScript
Watch.GetOriginalFileName
JavaScript
Watch.GetOriginalFileName();
Python
Watch.GetOriginalFileName()
Page 111
Perl
$Watch->GetOriginalFileName();
Watch.GetMetadataFilename
Returns the complete path and file name of the metadata file associated with the current job file.
Example
VBScript
Watch.GetMetadataFileName
JavaScript
Watch.GetMetadataFileName();
Python
Watch.GetMetadataFileName()
Perl
$Watch->GetMetadataFileName();
Watch.InputBox
Warning
Starting version 7.0, the Watch.InputBox function is deprecated and may no longer work
due to changes in the way in which the Watch Service functions. This function is
completely disabled in PlanetPress Workflow 7.3 and higher.
Prompts the user to enter a string. The string is displayed as the window caption. You can
specify a message that is displayed above the text box. This method is the same as PW_
InputBox.
Clicking OK returns the value entered by the user. If no value was entered the default value is
returned. Clicking Cancel returns the default value.
Page 112
You must enable the “Run on desktop” option for the PlanetPress Workflow process whose
script calls Watch.InputBox. Otherwise PlanetPress Workflow application may stop working
and require a reboot.
Example
s = watch.inputbox("caption", "message", "default")
watch.showmessage(s)
Examples
In the following example,Watch.InputBox requires the user to enter a line of text. The script the
displays a pop-up of the message contents using "Watch.ShowMessage" on page 108.
VBScript
s = Watch.InputBox("Your Name", "Please enter your name", "John
Doe")
Watch.ShowMessage("Will the real " + s + " please stand up?")
JavaScript
s = Watch.InputBox("Your Name", "Please enter your name", "John
Doe");
Watch.ShowMessage("Will the real " + s + " please stand up?");
Python
s = Watch.InputBox("Your Name", "Please enter your name", "John
Doe")
Watch.ShowMessage("Will the real " + s + " please stand up?")
Perl
s = Watch->InputBox("Your Name", "Please enter your name", "John
Doe");
Watch->ShowMessage("Will the real " + $s + " please stand up?");
Watch.GetJobInfo
Returns job information corresponding to the specified index. Index is an integer from 1 to 9.
Page 113
Syntax
Watch.GetJobInfo(Index: integer): string
Example
VBScript
Dim s
s = Watch.GetJobInfo(3)
Watch.Log "Jobinfo 3's value is: " + s, 2
JavaScript
var s;
s = Watch.GetJobInfo(3);
Watch.Log("Jobinfo 3's value is: " + s, 2);
Python
s = Watch.GetJobInfo(3)
Watch.Log("Jobinfo 3's value is: " + s, 2)
Perl
$s = $Watch->GetJobInfo(3);
$Watch->ShowMessage("Jobinfo 3's value is: " . $s, 2);
Watch.SetJobInfo
Sets the job information index to a specified string value.
Syntax
Watch.SetJobInfo(Index: Integer; Value: String)
Example
VBScript
Watch.SetJobInfo 3, "Job info 3 Value"
JavaScript
Watch.SetJobInfo(3, "Job info 3 Value");
Page 114
Python
Watch.SetJobInfo(3, "Job info 3 Value")
Perl
$Watch->SetJobInfo(3, "Job info 3 Value");
Watch.GetVariable
Returns the string value of the corresponding variable name. Note that if an undeclared
variable is called using this method, an error will be generated.
Syntax
Watch.GetVariable(Name: String): String
Example
VBScript
Dim s
s = Watch.GetVariable("MyVariable")
Watch.Log "MyVariable's value is: " + s, 2
s = Watch.GetVariable("global.MyVariable")
Watch.Log "global.MyVariable's value is: " + s, 2
JavaScript
var s;
s = Watch.GetVariable("MyVariable");
Watch.Log("MyVariable's value is: " + s, 2);
s = Watch.GetVariable("global.MyVariable");
Watch.Log("Jobinfo 3's value is: " + s, 2);
Python
s = Watch.GetVariable("MyVariable")
Watch.Log("global.MyVariable's value is: " + s, 2)
Perl
$s = $Watch->GetJobInfo(3);
$Watch->ShowMessage("global.MyVariable's value is: " . $s, 2);
Page 115
Watch.SetVariable
Sets the variable to a specified string value. Note that if an undeclared variable is called using
this method, an error will be generated.
Syntax
Watch.SetVariable Name: String; Value: String
Example
VBScript
Watch.SetVariable "MyVariable", "Desired value"
Watch.SetVariable "global.MyVariable", "Desired value"/
JavaScript
Watch.SetVariable("MyVariable", "Desired value");
Watch.SetVariable("global.MyVariable", "Desired value");
Python
Watch.SetVariable("MyVariable", "Desired value")
Watch.SetVariable("global.MyVariable", "Desired value")
Perl
$Watch->SetVariable("MyVariable", "Desired value");
$Watch->SetVariable("global.MyVariable", "Desired value");
Watch.ExpandString
Provides access to the emulated job file and to all variables. This function returns a string that
is the expanded version of the input string.
Syntax
Watch.ExpandString(StringToExpand) -> string
Arguments
StringToExpand —A regular parseable string that may contain system variables (%u, %f), user
variables (%1 to %9), octal codes, and data selections.
Page 116
Example
This example results in expanding the string of the variables to the date value in the following
format: “YYYY-MM-DD”.
VBScript
Dim s
s= Watch.ExpandString("%y-%m-%d")
Watch.Log "Current Date is: " + s, 2
JavaScript
var s;
s= Watch.ExpandString("%y-%m-%d");
Watch.Log("Current Date is: " + s, 2);
Python
s= Watch.ExpandString("%y-%m-%d")
Watch.Log("Current Date is: " + s, 2)
Perl
$s = $Watch->ExpandString("%y-%m-%d");
$Watch->Log("Current Date is: " . $s,2);
Watch.Log
Creates messages that are added to PlanetPress Workflowwatch.log file. PlanetPress
Workflow watch.log file is located in ...\Program Files\PlanetPress Workflow 7\PlanetPress
Watch\Log\ppw[log date].log.
View error messages in the Services Console while PlanetPress Workflow is in Run mode by
choosing Tools | Services | Service Console. In the Service Console, error messages appear
with colors that correspond to the message level.
Level
Type
Text Color in Service Console
1
Error
Red
2
Warning
Orange
Page 117
Level
Type
Text Color in Service Console
3
Information
Black
4
Debug
Grey
Arguments
Message—A string representing the message that is logged in the log file. Note that the text of
the message must use the locale encoding of the system where the PlanetPress Workflow
software will be running, otherwise it will be unreadable.
Level—An integer between 1 and 4, specifying the severity level of the error message. Set
message levels as follows:
Level
Description
1
The message is logged as an Error in the log file.
2
The message is logged as a Warning in the log file.
3
The message is logged as Information in the log file.
4
The message only appears when the application runs in Debug mode.
Examples
In the following example, log() will write an information entry in the watch log that says "this is a
log"
VBScript
Watch.Log "this is a log", 3
JavaScript
Watch.Log("this is a log", 3);
Page 118
Python
Watch.Log("this is a log",3)
Perl
$Watch->Log("this is a log",3);
Watch.Sleep
Pauses the process for the specified number of milliseconds. This can be used while waiting
for something else to happen when the delay is known.
Syntax
Watch.Sleep Milliseconds: integer
Example
In the following example, sleep() pauses the process for 1 second (1000 milliseconds)
VBScript
Watch.Sleep 1000
JavaScript
Watch.Sleep(1000);
Python
Watch.Sleep(1000)
Perl
$Watch->Sleep(1000);
Script.ReturnValue
Set this variable to 1 (true) or 0 (false) in order to return a true or false status to PlanetPress
Workflow, when using your script as a conditional branch. This variable will have no effect if the
script is run as an action.
Page 119
Example
This example will always return true, as the condition is static. It is, after all, simply an example.
You get the idea.
VBScript
Dim everythingOK
everythingOK = true
if (everythingOK = true) then
Script.ReturnValue = 1
else
Script.ReturnValue = 0
end if
JavaScript
var everythingOK;
everythingOK = true;
if(everythingOK = true){
Script.ReturnValue = 1;
} else {
Script.ReturnValue = 0
}
Python
everythingOK = True
if everythingOK == True:
Script.ReturnValue = 1
else:
Script.ReturnValue = 0
Perl
$everythingOK = true;
if (everythingOK = true) {
$Script->{ReturnValue} = 1;
} else {
$Script->{ReturnValue} = 0;
}
Page 120
Data Repository API
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.
The Data Repository can be accessed at runtime by the Push To Repository plugin and other
tasks (see "Data Repository" on page 51) and at design time via the "Data Repository
Manager" on page 721.
This topic explains how to access the Data Repository in script.
For a quick start, turn to this How-to: Interacting with the Data Repository API.
Warning
All operations on the Repository must be performed through this API - rather than directly
accessing the physical file - since the Repository's underlying file structure may change over time.
This API is guaranteed to remain compatible with future versions of the Data Repository. It is used
by all Workflow tasks dealing with the Repository.
Data repository structure
The table below lists the different levels in the repository and what their names corresponds to:
The term ...
... is the same as an Excel ...
... is the same as a Database ...
Group
Sheet
Table
Key
Column
Field
KeySet
Row
Record
Note
Group and key names are case-insensitive.
Page 121
API Reference
Obtaining an instance of the Repository Object
The Data Repository is accessed via a COM object that exposes methods to store and retrieve
data within the Repository.
JavaScript
var repoObject = new ActiveXObject
("RepositoryLib.WorkflowRepository");
VB Script
set repoObject = CreateObject("RepositoryLib.WorkflowRepository")
In each example in this documentation, the object repoObject is deemed having been obtained
through the above call to the COM object.
Using a JSON parameter or return value
Whenever a parameter or return value is defined as a JSONStringArray type, that JSON array
is itself a string. Since a JSON array internally defines double quotes as the delimiter for each
element, you must enclose the entire string in single quotes. Alternatively, you can escape the
double quotes inside the JSON Array.
For instance, the following calls to AddGroup() are correct:
RepoObject.AddGroup("MyGroup",'["FirstKey", "SecondKey"]');
RepoObject.AddGroup("MyGroup","[\"FirstKey\", \"SecondKey\"]");
But the following is incorrect:
RepoObject.AddGroup("MyGroup","['FirstKey', 'SecondKey']");
Many methods require using the JSONStringArray type but JSON is not natively supported in
VB Script. Therefore, for those methods, only JavaScript sample code is provided. There are
many resources on the Web that propose ways of implementing JSON parsing in VB Script so
you can implement whichever you see fit. However, using JavaScript is highly recommended.
Page 122
Group methods
Name
Description
AddGroup
Creates a group named GroupName and optionally creates
keys listed in keyNames. The keyNames parameter may be
empty.
RemoveGroup
Deletes the group named GroupName, along with all its
keysets and keys.
ListGroups
Retrieves the list of all group names in the Repository,
stored in a JSONStringArray..
RenameGroup
Renames group oldName to newName. While this
operation has no impact on the data stored in the specified
group, it does require any plugin and/or script that uses
oldName to be modified to refer to newName.
Key Methods
Name
Description
AddKey
Adds key KeyName to group GroupName. KeyName must
not already exist in the specified group. Note that this method
only adds a key name to the group, not a key value. See
AddValue() for information on how to set a value for a key.
RemoveKey
Removes existing key KeyName from group GroupName.
The key to remove must exist in the group, otherwise an error
is raised. All values for the key, in all keysets for the group,
are removed. Note that when the Group contains a large
number of KeySets, this operation may take a while.
ListKeys
Retrieves the list of all Key names and data types in Group
GroupName, stored in a JSONStringObject. You should use
Page 123
Name
Description
JSON.Parse() to convert the string into an actual JavaScript
object. You can then use the for…in construct to list the
different properties for that object (i.e. the keys in the group).
RenameKey
Renames key oldName to newName in group GroupName.
While this operation has no impact on the data stored in that
Group, it does require any plugin and/or script that uses
oldName to be modified to refer to newName.
Value Methods
Name
Description
GetValue
Performs a lookup in group GroupName and retrieves the
first value for key KeyName that matches Condition. The
condition is specified using basic SQL WHERE syntax. The
Condition may be left empty in which case the very first
value found for the specified KeyName is returned.
AddValue
Creates a new KeySet by assigning Value to the key
KeyName in Group GroupName. Note that KeyName must
exist in GroupName, otherwise an error is raised. See
AddKey() for information on adding a key to a group. Upon
successful completion, the method returns the ID of the
newly created KeySet.
SetValue
Updates multiple keysets in group GroupName by setting
the key KeyName to Value for all keysets that match
Condition. The condition is specified using basic SQL
WHERE syntax. The Condition may be left empty in which
case all keysets in GroupName are updated. Note that
KeyName must exist in GroupName, otherwise an error is
raised. The method returns an array of the keyset ID's that
were updated ( [1,2] ), or an empty array ( [] ) if no keysets
Page 124
Name
Description
were updated.
SetValueByID
Updates KeyName with Value in group GroupName, where
the keyset's ID matches the ID parameter. KeyName must
exist in GroupName, otherwise an error is raised. The
method returns the ID of the keyset that was updated or -1 if
the keyset was not updated.
Note that this method is functionally equivalent to using
SetValue() with its Condition parameter set to "ID=ID".
KeySet methods
Name
Description
GetKeySets
Retrieves Keys values in GroupName for keysets that
match Condition. When Keys is left empty, all keys are
retrieved. When Condition is left empty, all keysets are
retrieved.
AddKeySets
Inserts a new keyset inside GroupName and assigns
values to keys as specified in KeyValues. Every key
specified in KeyValues must exist otherwise an error is
raised. However, it is not required to specify all
available keys in KeyValues. Only the keys specified
are updated in GroupName while unspecified keys are
set to an empty string.
RemoveKeySets
Deletes all keysets in GroupName that match
Condition. The condition is specified using basic SQL
WHERE syntax. Condition may be left empty, in which
case all keysets in GroupName are deleted. The
method returns the number of keysets that were deleted.
Page 125
Name
Description
RemoveKeySetByID
Deletes the keyset whose ID equals ID from
GroupName. Returns 1 if successful, 0 otherwise.
Note that this method is functionally equivalent to using
RemoveKeySets() with its Condition parameter set to
"ID=ID".
Repository management methods
Name
Description
ClearRepository
Deletes all groups, keys and keysets from the repository,
returning it to a blank state. Use with caution!
ClearGroupData
Deletes all keysets inside GroupName while retaining the
existing key structure.
ClearAllData
Delete all keysets in all groups, while retaining the
existing key structure.
CheckRepository
Verifies the integrity of the repository and recovers unused
space left by deleted keysets. Similar to packing a
database, the operation is non-destructive but it does
require exclusive access to the Repository. You should
therefore only perform this operation when you know for
sure no other process is accessing the Data Repository.
Version
Returns the version of the DLL library used by the
Repository.
AddGroup
Creates a group named GroupName and optionally creates keys listed in keyNames. The
keyNames parameter may be empty.
Page 126
Syntax
AddGroup(GroupName: string, keyNames: JSONStringArray)
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.AddGroup("Users", '["FirstName", "LastName"]');
repoObject.AddGroup("Users", '');
VB Script
repoObject.AddGroup "Users", "[""FirstName"", ""LastName""]"
repoObject.AddGroup "Users", ""
AddKey
Adds key KeyName to group GroupName. KeyName must not already exist in the specified
group. Note that this method only adds a key name to the group, not a key value. See
AddValue() for information on how to set a value for a key.
Syntax
AddKey(GroupName: string, KeyName: string)
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.AddKey("Users", "email");
VB Script
repoObject.AddKey "Users", "email"
Page 127
AddKeySets
Inserts a new keyset inside GroupName and assigns values to keys as specified in
KeyValues. Every key specified in KeyValues must exist otherwise an error is raised.
However, it is not required to specify all available keys in KeyValues. Only the keys specified
are updated in GroupName while unspecified keys are set to an empty string.
Syntax
AddKeySets(GroupName: string, KeyValues: JSONObjectArray):
JSONIntegerArray
Examples
Basic examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.AddKeySets("Users", '[{"FirstName": "John","LastName":
"Smith"},{"FirstName": "Richard", "LastName": "Doe"}]');
VB Script
repoObject.AddKeySets "Users","
[{""FirstName"":""John"",""LastName"":""Smith""},
{""FirstName"":""Richard"",""LastName"": ""Doe""}]"
Inserting a row
In most cases, you won't need to insert or update a row in a script, as this can be easily done
through the the Push to Repository action task. However, in some cases you might want to
script it for simplicity's sake.
This JavaScript example inserts 2 different rows into the Users group.
var Repo = new ActiveXObject("RepositoryLib.WorkflowRepository");
Repo.AddKeySets("customers", '[{"CustomerID": "CUJS123456",
"FirstName": "John","LastName": "Smith"},
{"CustomerID": "CURD654321", "FirstName": "Richard", "LastName":
"Doe"}]');
Page 128
Tip: to update a row instead of adding it, use the GetValue() function to get the KeySet ID; then
update each individual value using SetValueByID() (see "GetValue" on page 132 and
"SetValueByID" on page 139).
Sample return value
The method returns a JSONIntegerArray containing the ID's of all keysets inserted into
GroupName:
'[131,132]'
AddValue
Creates a new KeySet by assigning Value to the key KeyName in Group GroupName. Note
that KeyName must exist in GroupName, otherwise an error is raised. See AddKey() for
information on adding a key to a group. Upon successful completion, the method returns the ID
of the newly created KeySet.
Syntax
AddValue(GroupName: string, KeyName: string, Value: string):
integer64
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.AddValue("Users", "LastName", "Smith");
VB Script
repoObject.AddValue "Users", "LastName", "Smith"
CheckRepository
Verifies the integrity of the repository and recovers unused space left by deleted keysets.
Similar to packing a database, the operation is non-destructive but it does require exclusive
Page 129
access to the Repository. You should therefore only perform this operation when you know for
sure no other process is accessing the Data Repository.
Syntax
CheckRepository()
ClearAllData
Delete all keysets in all groups, while retaining the existing key structure.
Syntax
ClearAllData()
ClearGroupData
Deletes all keysets inside GroupName while retaining the existing key structure.
Syntax
ClearGroupData(GroupName: string)
ClearRepository
Deletes all groups, keys and keysets from the repository, returning it to a blank state. Use with
caution!
Syntax
ClearRepository()
GetKeySets
Retrieves Keys values in GroupName for keysets that match Condition. When Keys is left
empty, all keys are retrieved. When Condition is left empty, all keysets are retrieved, which is
useful for reports, cleanup, or custom filters based on more complex conditions.
Syntax
GetKeySets(GroupName: string, Keys: JSONStringArray, Condition:
string): JSONStringArray
Page 130
Examples
Basic examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.GetKeySets("Users", '["FirstName","LastName"]',
"Gender='M'");
VB Script
myKeySet = repoObject.GetKeySets("Users", "
[""FirstName"",""LastName""]", "Gender='M'")
Querying a single row
This JavaScript example shows how to get one or more rows from the repository and use them
in the process. The script gets 3 fields ("firstname", "lastname" and "email") from the
CustomerID field. It assumes there's a local variable called %{CustomerID} set in the workflow
process.
var CustomerID = Watch.GetVariable("CustomerID");
var Repo = new ActiveXObject("RepositoryLib.WorkflowRepository");
var customer = Repo.GetKeySets("customers",'
["firstname","lastname", "customerID"]',"customerID = '" +
CustomerID + "'");
Watch.SetJobInfo(9,customer);
By omitting the last option from GetKeySets (the filter on CustomerID) you can get all the rows
from the data repository.
Return value: JSONStringArray
The method returns a JSONStringArray of key-value pairs, for example:
'[{"FirstName": "John","LastName": "Smith"},{"FirstName":
"Richard", "LastName": "Doe"}]'
Page 131
The return value (saved for example in the %9 JobInfo variable, as the above example does)
can be used in a number of ways:
l
l
l
It can be returned to a web page that's making an HTTP request to Workflow. JSON is the
simplest way to transfer information between any system that supports JavaScript.
It can be passed to Designer and loaded up directly as an object in a script there.
The JSON can be converted to XML, which makes it useable in the DataMapper module.
This can be easily done in a preprocessor script in the DataMapper (see DataMapper
online help).
GetValue
Performs a lookup in group GroupName and retrieves the first value for key KeyName that
matches Condition. The condition is specified using basic SQL WHERE syntax. The
Condition may be left empty in which case the very first value found for the specified
KeyName is returned.
Syntax
GetValue(GroupName: string, KeyName: string, Condition: string)
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
var myValue = repoObject.GetValue("Users", "email", "
LastName='Smith' AND FirstName='John' "); /* retrieves email for
John Smith */
var myValue = repoObject.GetValue("Users", "email", "
LastName='Smith' "); /* retrieves email for first user named Smith
*/
var myValue = repoObject.GetValue("Users", "email", ""); /*
retrieves email for first user */
VB Script
myValue = repoObject.GetValue("Users", "email", "
LastName=""Smith"" AND FirstName=""John"" ") /* retrieves email for
Page 132
John Smith */
myValue = repoObject.GetValue("Users", "email", "
LastName=""Smith"" ") /* retrieves email for first user named Smith
*/
myValue = repoObject.GetValue("Users", "email", "") /* retrieves
email for first user */
Retrieving a KeySet ID
This JavaScript example retrieves the KeySet ID, which is then used to update values in the
row.
/* Get KeySet ID */
var Repo = new ActiveXObject("RepositoryLib.WorkflowRepository");
var keySetID = Repo.GetValue("customers", "ID",
"CustomerID='CURD654321'");
/* Update Values */
Repo.SetValueByID("customers", "FormOfAddress", "Mr.", keySetID);
Repo.SetValueByID("customers", "Country", "US", keySetID);
Repo.SetValueByID("customers", "Language", "EN", keySetID);
ListGroups
Retrieves the list of all group names in the Repository, stored in a JSONStringArray.
Syntax
ListGroups(): JSONStringArray
Example
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
var repoObject = new ActiveXObject
("RepositoryLib.WorkflowRepository");
var myList = JSON.parse(repoObject.ListGroups());
for (var i=0; i 0) ? "true" : "false";
Watch.SetJobInfo(9, answer);
RenameGroup
Renames group oldName to newName. While this operation has no impact on the data stored
in the specified group, it does require any plugin and/or script that uses oldName to be
modified to refer to newName.
Syntax
RenameGroup(oldName, newName: string)
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
Page 137
JavaScript
repoObject.RenameGroup("Users", "Customers");
VB Script
repoObject.RenameGroup "Users", "Customers"
RenameKey
Renames key oldName to newName in group GroupName. While this operation has no
impact on the data stored in that Group, it does require any plugin and/or script that uses
oldName to be modified to refer to newName.
Syntax
RenameKey(GroupName: string, oldName: string, newName: string)
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.RenameKey("Users", "LastName", "SurName");
VB Script
repoObject.RenameGroup "Users", "LastName", "SurName"
SetValue
Updates multiple keysets in group GroupName by setting the key KeyName to Value for all
keysets that match Condition. The condition is specified using basic SQL WHERE syntax. The
Condition may be left empty in which case all keysets in GroupName are updated. Note that
KeyName must exist in GroupName, otherwise an error is raised. The method returns an array
of the keyset ID's that were updated ( [1,2] ), or an empty array ( [] ) if no keysets were updated.
Syntax
SetValue(GroupName: string, KeyName: string, Value: string,
Condition: string): string
Page 138
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
repoObject.SetValue("Users",
);
repoObject.SetValue("Users",
AND MaritalStatus='Married'"
repoObject.SetValue("Users",
AND MaritalStatus=''" );
"FormOfAddress", "Mr.",
"Gender='M'"
"FormOfAddress", "Ms.", "Gender='F'
);
"FormOfAddress", "Miss", "Gender='F'
VB Script
repoObject.SetValue "Users", "FormOfAddress", "Mr.", "
Gender=""M"" "
repoObject.SetValue "Users", "FormOfAddress", "Ms.", "
Gender=""F"" AND MaritalStatus=""Married"" "
repoObject.SetValue "Users", "FormOfAddress", "Miss", "
Gender=""F"" AND MaritalStatus="""" "
SetValueByID
Updates KeyName with Value in group GroupName, where the KeySet's ID matches the ID
parameter. KeyName must exist in GroupName, otherwise an error is raised. The method
returns the ID of the keyset that was updated or -1 if the keyset was not updated.
The KeySet ID can be retrieved with GetValue() ("GetValue" on page 132).
Syntax
SetValueByID(GroupName: string, KeyName: string, Value: string, ID:
integer): integer64
Note
This method is functionally equivalent to using "SetValue" on the previous page with its Condition
parameter set to "ID=ID".
Page 139
Examples
In each of these examples, the object repoObject is deemed having been obtained through a
call to the COM object "RepositoryLib.WorkflowRepository" (see "Obtaining an instance of the
Repository Object" on page 122).
JavaScript
/* both methods perform the same task */
repoObject.SetValueByID("Users", "FormOfAddress", "Mr.", 10);
repoObject.SetValue("Users", "FormOfAddress", "Mr.", "ID=10" );
VB Script
/* both methods perform the same task */
repoObject.SetValueByID "Users", "FormOfAddress", "Mr.", 10
repoObject.SetValue "Users", "FormOfAddress", "Mr.", "ID=10"
Updating a row
There is currently no 'update' feature in the API for a whole KeySet. This JavaScript example
retrieves the KeySet ID, which is then used to update values in the row.
/* Get KeySet ID */
var Repo = new ActiveXObject("RepositoryLib.WorkflowRepository");
var keySetID = Repo.GetValue("customers", "ID",
"CustomerID='CURD654321'");
/* Update Values */
Repo.SetValueByID("customers", "FormOfAddress", "Mr.", keySetID);
Repo.SetValueByID("customers", "Country", "US", keySetID);
Repo.SetValueByID("customers", "Language", "EN", keySetID);
Version
Returns the version of the DLL library used by the Repository.
Syntax
Version(): string
Page 140
Stopping Execution
When using a script, you may come to a point where you'd like the task to fail (raise an
error) and trigger your On Error tab under certain conditions. This can be done by using the
scripting language's built-in error features, described here.
Note that the value or description of the error will not be available to your error process if one is
used. However, when available, a description of the error message will be logged in the Watch
log.
VBScript
In VBSCript, the Err.Raise method will halt the execution of the script and trigger the On Error
tab. When using On Error Resume Next, raising an error will not stop execution. See MSDN for
the Raise method properties and this page for a list of available errors to raise. In the case of
VBScript, the error number used will determine the message shown in the log.
Dim s
s = Watch.GetJobInfo(9)
If (s = "") Then
Err.Raise 449 ' Raises Error #449: "Argument is not optional"
Else
' Do somethign with Job Info 9!
Watch.Log "Job Info 9's value is: " + s, 4
End If
JavaScript
JavaScript uses the throw statement within try to create an exception which, if not caught
using catch() , will cause the script execution to stop and the On Error tab to be triggered. See
this page on W3Schools.
var s;
s = Watch.GetJobInfo(9);
if (s == "") {
throw "Value Cannot be empty";
} else {
// Do something with Job Info 9!
Watch.Log("Job Info 9's value is: " + s,4);
}
Page 141
Python
In Python, the raise statement is similar to JavaScript and will stop processing unless an
except statement is used. See the python documentation.
s = Watch.GetJobInfo(9)
if not s:
raise NameError('Value cannot be empty')
else:
# Do something with Job Info 9!
Watch.Log("Job Info 9's value is: " + s,5)
Perl
In PERL, die() raises an exception and triggers the On Error tab, unless the unless command
is used. See the perl documentation.
$s = $Watch->GetJobInfo(9);
if (s = "") {
die "Value cannot be empty";
} else {
# Do something with Job Info 9!
$Watch->Log("Job Info 9's value is: " . $s,4);
}
Special Workflow Types
PlanetPress Workflow supports multiple input and output types, in so many different
combinations that it would be hard to give example processes for each possibility. However,
some types of processes like PDF, HTTP and SOAP are important enough to pay some
attention to them.
This chapter will describe each of these special workflow types and give at least one example
of an implementation that uses them.
Special Workflows
PDF Workflow
A PDF workflow uses a PDF as it's job file and manipulations are generally made in the
Metadata instead of the PDF itself, since PDF files are much larger than most other data files
Page 142
compatible with PlanetPress Suite. The Metadata Tools are extensively used in the example
presented, which is a weekly sales report sent to all the sales associates of a particular
company branch. See the "PDF Workflow" on page 186 for more details.
PlanetPress Capture Workflow
A Capture workflow is divided in two steps: Creating an output of documents containing the
PlanetPress Capture Fields, and retrieving the information from the Anoto Digital Pen to merge
it with the original documents. See "PlanetPress Capture Workflow" below for more details.
HTTP Server workflow
An HTTP workflow receives requests from a client via a GET or POST request, sometimes only
with information, sometimes with attached files. An HTTP workflow is basically an
XML workflow since that is the type of file created by the HTTP Server Input action task. See
the "HTTP Server Workflow" on page 179 page for more details.
SOAP Workflow
As SOAP can be either a client or a server, two workflows will be presented. The SOAP Client
workflow presents PlanetPress Workflow as the client and will explore how to retrieve
WSDL information and how to make a SOAP request as a client. The SOAP Server workflow
will show how to create a process that responds to SOAP requests, and where our own
WSDL is located.
PlanetPress Capture Workflow
PlanetPress Capture, introduced in PlanetPress 7.2 and enhanced ever since, is a set of tools
that is used to simplify digital archiving processes by capturing information from a special pen
which records everything it writes on paper, as long as this paper contains special Anoto
Patterns.
Warning
There are important considerations to keep in mind when dealing with PlanetPress
Capture. Please review them in "PlanetPress Capture Implementation Restrictions" on
page 161.
Page 143
In order to properly build a PlanetPress Capture workflow, it is very important to understand the
terminology, implications and limitations of the technology. This is the first part of this section:
l
"Capture Information" on page 146
l
"Database Considerations (ODBC)" on page 150
l
"Security Considerations" on page 152
l
"20,000 Patterns" on page 153
l
"PlanetPress Capture Implementation Restrictions" on page 161
There are also 2 external tools that are used to communicate the pen's data to PlanetPress
Workflow:
l
"Anoto penDirector" on page 159
l
"PlanetPress Mobile Application" on page 160
Creating a Capture-Ready document
This is done when creating your PlanetPress Design document. Adding one or more
PlanetPress Capture fields to a PlanetPress Design document creates a capture-ready
document, which can be used in the workflow. For more information, see the PlanetPress
Design User Guide.
Generating the Capture Patterns
Once your document is created, the Capture Fields Generator action task is used to apply the
capture patterns to each of your documents and send them to the printer. This printing process
will consist of:
l
Retrieving your data file.
l
Creating metadata (See "Create Metadata" on page 509).
l
l
l
Separating each individual document in the metadata (this can be done in your Design
document or through the "Metadata Level Creation" on page 524 action task).
Using the "Capture Fields Generator" on page 482 action task to generate the capture
patterns
Printing your documents.
Page 144
Capturing and Archiving
After the printed documents have been inked with the Anoto Digital Pen, the PGC files from the
pen must be processed and merged with the appropriate documents in the PlanetPress
Capture Database. A workflow process that receives PGC files and reads them in turn consists
of the following actions:
l
l
l
l
l
An "HTTP Server Input" on page 228 task or "Folder Capture" on page 213 task that
receives the PGC.
The "Capture Fields Processor" on page 486, which converts each PGC in an EPS layer,
adds this layer to the PDF in the database, releases patterns and closes documents.
Optionally, a "Capture Condition" on page 476 task to do post-processing using the
Capture Fields data.
A "Get Capture Document" on page 502 action task to retrieve each document in the
database and output a PDF file
Any existing output such as Output to Folder, email, ftp, etc.
Technical
Because of timeout limitations, it is generally a good idea to use the Send immediate
response to client option of the HTTP Server Input task, especially when processing a
large amount of documents from the pen. Additionally, HTTP Server Processes should
always be self-replicating and have a short polling interval set in their properties.
Managing and Post-Processing
There are a couple of things that can be done even after documents have been inked. As long
as a document remains open, it is still present in the Capture database and be used in a
process:
l
l
The "Find Capture Documents" on page 497 input task is used to retrieve a list of
documents under specific criteria.
The Capture Condition and Get Capture Document tasks are used to effect postprocessing and retrieve document from the Capture database.
Page 145
Error Handling
Whenever an error occurs during the Capture Field Processor phase, it is of course important to
be able to handles these errors. For this purpose, the "PGC to PDF Converter" on page 506
task was added with PlanetPress 7.4, adding the ability to quickly and directly convert a
PGC file to a blank PDF file containing the ink data as an EPS layer. This is useful when, for
example, data is received for a document that's already been closed.
l
The "Input Error Bin" on page 233 input task is triggered when the process sends data to
the error process.
l
A "PGC to PDF Converter" on page 506 task converts the PGC to a PDF
l
Any existing output is used here, for example an email notification.
The Examples
l
"Basic Functional Capture Workflow" on page 173
l
"Capture Post Processing Workflow" on page 174
l
"Capture Web Manager Workflow" on page 178
Capture Information
PlanetPress Capture Glossary
This topic describes the specific terms used in the PlanetPress Capture set of tools within
PlanetPress Workflow.
Anoto Digital Pen
A digital pen compatible with the Anoto system. These pens contain a camera, processor and
memory chip which record each stroke of the pen on a printed Anoto Pattern, and are able to
send this information back to PlanetPress Workflow. This document specifically refers to the
Anoto DP-201 Digital Pen, not other equipment has been tested.
Anoto Functionality Statement
Statement ('Paper featuring Anoto functionnality') that is automatically placed on the page when
a PlanetPress Capture field is present. The statement can also include the Trace Code
Page 146
Anoto Pattern
A series of dots placed in a pattern that is unique to each page where the pattern is printed. The
Anoto Digital Pen identifies this pattern and its location on the page. PlanetPress Capture
contains 20,000 patterns (8 in demo mode, See "PlanetPress Capture License Management"
on page 747) which can be used to generate documents.
Capture Condition
PlanetPress Workflow task that is used for post-processing of documents after they have been
processed by the Capture Fields Processor. Conditions can be made on the document status
or the presence (or absence) of ink on any of the Capture Fields on the document.
Capture-Ready Document
A PlanetPress Connect document (*.pp7) that contains at least one Capture Field on at least
one page.
Capture Document Manager
A tool that lets a user search through the available documents in the Capture Database. The
documents can be search through a few different criteria and can be displayed as PDF files,
individually or as a group. Documents can also be closed or deleted from this interface.
Capture Field
The PlanetPress Connect object that acts as a placeholder for the Anoto Pattern. The pattern is
only applied when using the Capture Field Generator in Workflow.
Client/Server Architecture
A multi-server setup where more then one PlanetPress Workflow server are connected as
clients to a single PlanetPress Workflow server which has a Capture Database. In this
architecture, the Server contains the licenses for the pens, however the Client contains the
database of documents and patterns. The Clients communicate with the server to authenticate
pens. This architecture is only provided to simplify pen licensing for users with a large number
of pens.
Page 147
Closed Document
A document still within the PlanetPress Capture Database of which all the required fields have
been filled by the Capture Field Processor from a PGC. A closed document will only remain in
the database until it is retrieved with the Get Capture Document task, after which it is deleted.
Contamination
The act of writing on a "wrong" document, aka one that has a Pattern Sequence different that
the one for which it was produced.. This can happen in architectures with more than one
sequence being used such as when a pen is docked in the wrong location or if two pens are
swapped.
ICR (Intelligent Character Recognition)
Recognizing text that has been hand-written with the Anoto Digital Pen. This feature is currently
not implemented in PlanetPress Capture, but will be in the (near) future.
Ink Data
The pen stroke information contained within the PGC file. This is the actual data applied to the
document (lines, signatures, text, etc).
Open Document
A document in the Capture Database that does not yet have any ink data on it, or of which not
all mandatory fields (or final field) have ink present on them. Such a document is waiting for a
new PGC file to complete it so it can be closed.
Pattern ID
The ID of the Anoto pattern. Represents the pattern on the page. Can be used to retrace the
document to which the pattern belong.
Pattern Sequence
Pattern Sequences enable the multiplication of the number of available pattern by adding an
extra identification to the document. A Pattern Sequence is also attributed to each Anoto Digital
Pen, such as an incoming PGC file will contain the Pattern, on which the Pattern Sequence is
added from the pen database. The pattern and pattern sequence refer to a specific document in
the database. Signing a document with a pen of which the Pattern Sequence does not match
Page 148
that of the document causes Contamination, which can cause errors or ink to be placed on the
wrong document.
Pen ID
The serial number of the Anoto Digital Pen. It is registered in the PlanetPress Capture
database and is present in each PGC file.
PGC File
Pen Generated Coordinates; PGC File containing all ink processed while the pen was
undocked along with the Pen ID. It is possible that a single document requires multiple PGC,
just as it is possible that a single PGC have multiple documents.
Pidget
Type of PlanetPress Capture object. Page element used to give instructions to the Anoto pen,
as opposed to recording ink.
PlanetPress Capture Database
A database containing the list of patterns, sequences, registered pens and documents. The
Capture Database can be used by a single server, or by multiple servers in a Client/Server
architecture.
Session
The time spent by the pen between events that trigger a new session. Generally a session
refers to any ink in a single page containing a Capture Pattern. A session can contain ink from
multiple fields in any order. A new session starts whenever a PGC is sent for processing (which
erases the data from the pen).
General Considerations
Here are some general considerations in regards to PlanetPress Capture, its environment, the
hardware and the software that interacts with it. Please review these considerations carefully as
they may impact PlanetPress Capture and its functionality.
Page 149
Warning
PlanetPress Capture Fields cannot simply be inserted into an existing document as-is
and expected to work properly, efficiently or consistently. In order to design a document
with Capture Fields, you must review and understand the Critical PlanetPress Capture
Implementation Restrictions.
Database Considerations (ODBC)
Technical
On 64-bit operating systems, the ODBC Data Sources created by the Data Source
(ODBC) icon in the Administrative Tools will not appear here, as PlanetPress Suite is 32bit and cannot access the 64-bit data sources. In order to create an ODBC connection
visible by PlanetPress, you will need to access the 32-bit version of the ODBC manager,
available in C:\Windows\SysWOW64\odbcad32.exe .
The following considerations should be kept in mind while working with ODBC Databases in
PlanetPress Suite.
l
All databases
l
l
l
l
l
l
User Rights: During normal operation, Read/Write to tables should be sufficient.
However, during the initial setup, the Create/Drop tables rights is necessary.
Minimum 100MB of database size is required as a minimum, but the space
requirement depends on the implementation. The more active documents in the
database, the more space is used - note that this progression is rather linear.
Regular database maintenance is required, such as database compacting, is
required by a system administrator.
It is recommended to create an IT process that backs up the database regularly.
The recommended ideal setup is a dedicated SQL Server PC, accessed by
PlanetPress Workflow through an ODBC connection on the local network.
Microsoft Access
l
Database file (mdb) must be local to the PlanetPress Workflow computer. It cannot
be located on a network drive or another server.
Page 150
l
l
Total database size is limited to 4GB of data.
l
Total size of a single table is 2GB.
l
May be unstable in large implementations.
MySQL
l
l
l
l
l
Database can be in any location, but performance will depend on the speed of the
connection between PlanetPress and the MySQL server.
MySQL's performance has been slower than SQL Server and SQL Server Express
during our tests.
By default, MySQL is configured not to allow any SQL request larger than 16 megs.
In the event where 2 requests are made simultaneously on the same record,
MySQL will queue one of the requests and execute it once the first one is done. In
extremely rare cases this may cause a timeout on very large requests.
MSSQL (Microsoft SQL Server)
l
l
l
l
All versions of the SQL Server are supported, including all Express versions.
Database can be in any location, but performance will depend on the speed of the
connection between PlanetPress Production and the SQL server.
In the event where 2 requests are made simultaneously on the same record,
SQL Server will drop the most complex request. Resubmitting the PGC for
processing should resolve this issue. This, however, should happen only rarely.
When configuring the ODBC connection, your must use the Microsoft version of the
driver, and not the Native SQL version of the driver. This is due to a technical
limitation of the native driver that interferes with the PlanetPress Suite database
requests.
Specifically for PlanetPress Capture, these considerations mean the following:
l
l
l
In Microsoft Access, the total size of stored document cannot be larger than 2GB and
this database will be very unstable in implementation with more than a few thousand
pattern sequences being used simultaneously. It is only suggested for small
implementation with less than 10 pens, or for demos.
In MySQL, the 16 megs packet size limit can be an issue if the PDFs created by Capture
are larger than this size; An error saying "MySQL Server has gone away" would appear in
this case. This can be fixed by configuring the max_allowed_packet setting in the
MySQL Configuration (Reference).
Also in MySQL, if a timeout occurs on simultaneous record access, resubmitting the
PGC for processing should resolve the issue.
Page 151
l
In SQL Server, if one of your requests is dropped because of simultaneous accesses,
resubmitting the PGC should resolve the issue.
Security Considerations
PlanetPress Capture introduces new and efficient methods for digitally capturing the contents
of ink laded out on physical paper. However, because of its nature, some end users may voice
concerns about security and privacy. Are signatures secure? Could their transmission be
intercepted? How can the contents of the Anoto digital pen be protected from malicious users?
Before addressing these concerns, it must be pointed out that these security issues are not
introduced by this new technology. In fact, they are essentially the same concerns that arise
with plain pen and paper: if the signed document can be scanned, then any markings on the
page can be extracted and reused by anyone with even limited technical skills. In addition, the
signed document has, by definition, a longer life span than the temporary storage location of the
digital pen. Consequently, it is still the most vulnerable piece of the workflow and as such, it
should be the first objective of any security effort.
In other words, as long as the physical piece of paper bearing markings is accessible to
malicious users, no amount of security protocols can protect the signed contents. It is only after
the paper trail has been secured that the security and privacy issues specific to PlanetPress
Capture should be addressed.
Because PlanetPress Capture relies on external data and communication and because it may
be used to process sensitive and legal information, it is important to understand the security
implications of any PlanetPress Capture implementation. Most of the security concerns
regarding Capture are external to it. This means the security that is implemented both on your
network and physical premises are critical to the security of your PlanetPress Workflow
implementation.
Here are a few notable points with the security of PlanetPress Capture on a network:
l
PGC Files, while not written in plain text, are not encrypted and are readable through
either PlanetPress Workflow (even a server that did not generate the document
associated with it), or through third-party applications using the Anoto SDK. This means if
someone gains access to your PGC storage folder, they may be able to read the
signatures, checkmarks and other information contained in it and reproduce them on a
document of their choice. It is always better to secure this folder properly. You could also
use third-party encryption software to secure the files, and decrypt them as necessary for
reprocessing.
Page 152
l
l
l
l
The transfer between the Anoto penDirector and PlanetPress Workflow is not encrypted
due to a limitation of penDirector which does not support SSL connections. This means
someone located anywhere between penDirector and PlanetPress Workflow could use
software such as a packet sniffer to retrieve its parts and recreate the PGC files. This may
be resolvable by create a secure VPN tunnel for each location where penDirector is
installed instead of going through regular remote HTTP server.
The PlanetPress Capture database, since it can be external to PlanetPress Workflow
such as on a MySQL server, will be dependent on your own database security.
The Anoto Digital Pens, since they may contain critical information, are just like physical
sheets of signed paper and must be kept secured. This is best done through training
employees handling the pens to be aware of its value and contents and act accordingly.
This means that the security of the pen is just as important as the security of any existing
physical documents you may handle at the moment.
The same rules apply to PDF files as with PGC files, especially when they contain a
signature from the pen. If you are already securing digital scanned copies of signed
documents, the PDFs should be secured in similar ways.
However, remember that as with most security concerns, in order to be a “threat”, someone
would have to have a high level or working knowledge of either the Anoto SDK (which is not
easily obtainable) or PlanetPress Workflow and PlanetPress Capture. In some situations this
may be enough (security through obscurity) but we always recommend having the same level
of security for Capture files and documents as you would the rest of your sensitive information.
In most cases, the procedures in place are enough for this purpose.
20,000 Patterns
When reading or learning about PlanetPress Capture, you may have seen a number pop up
here and there: "20,000 Patterns". In order to better understand what this number means and
what it entails for you, the user, this document will first present an overview of a typical
PlanetPress Capture implementation and then explain how the 20,000 patterns limitation can
be circumvented in some cases. We will also touch upon the potential pitfalls of these
workarounds as they are used.
The Numbers
First and foremost, the 20,000 patterns is a fixed number - PlanetPress can only generate
20,000 unique patterns as this is the number of patterns that we license through Anoto.
The 20,000 patterns are, however, not all available when generating documents. There are 8
"demo" patterns that are used to generate documents when PlanetPress Capture is in demo
Page 153
mode (no license activated), and react the same way that the bulk of the 20,000 patterns.
Another single pattern is used to register pens in the database, and one last single pattern is
used when printing a "Preview" from PlanetPress Design. So in reality, the number of available
patterns for document generation is 19990, but for simplicity's sake this FAQ uses the round
number "20,000".
In a typical PlanetPress Capture implementation, a process in PlanetPress Workflow generates
output (generally, this output is directly printed) and, at the same time, will "lock" one pattern for
each page that it generates, if that page contains a pattern. PlanetPress Workflow also stores a
copy of each document in the Capture Database, in PDF format.
While a document is printed, and while this printed document has not received any ink or
signature, the document is deemed "open", the pattern it uses remains locked in the database
and cannot be re-used. Then, when someone writes on the document and sends the pen data
to PlanetPress Workflow (through a docking station or through Bluetooth), if the required
conditions have been met, the document will be "closed", its pattern released and available to
be used immediately.
An open document can also be called a "live" document, in the sense that it is only active
between the time where it is printed and the time where ink from the Anoto Digital Pen is
processed and the document is closed. This duration is called "time to live" or "TTL", and it is
the second very important number: how long is the pattern actually needed.
The third important number is based on your actual output needs. In other words, how many
documents do you intend to print on a regular basis that will contain a pattern?
These three numbers, together, represent an easy way to determine if the 20,000 patterns are
actually enough for you. Basically, if you generate X documents within a specific time frame but
N of these documents are closed through regular process (writing on them with a pen and
docking it) during that period, does the difference between both ever reach 20,000?
Example
Say you print 19,000 pages containing a pattern, every day. You may think you'll "run out of
patterns" after a single day. But if 18,900 of these documents are being written to and
processed within the day, at the end of the day you only have a 100 page difference, possibly
due to mistakes, lost pages, or errors during processing. In this specific example, you would run
out of patterns only after 10 days, assuming the numbers remained completely static. Since
there are easy ways to deal with these remainders (a simple automated process that, once a
day, closes any document that is older than 48 hours, for example), a correct implementation
Page 154
like this one would be perfectly functional and not be affected by the 20,000 page limit.
Remember however that this means that 19,000 physical sheets of paper are printed every day,
and those 19,000 documents are written on using one or more Anoto Digital Pens, which are
then processed back into the system.
The example above actually uses numbers that are much higher than our typical PlanetPress
Capture user. That is to say, a vast majority of our users will never have to worry about reaching
the pattern limitation, unless their implementation is missing important parts, such as the
"cleanup" process. But this also means a smaller minority of our users may require more than
20,000 patterns, so let's deal with this now.
Extending
There are actually 2 ways of dealing with extending the number of patterns using the currently
available tools, each with its own advantages and disadvantages.
Using separate PlanetPress Workflow servers and licenses.
In a scenario where there are multiple locations that use PlanetPress Capture and where
neither pen nor paper has any risk of being moved from one location to another, the easiest (but
costlier) solution is to have a separate installation of PlanetPress Workflow in each location.
Each installation would be responsible for its own documents and pens. The limitation here is
that it would not be directly possible to send a page with an existing pattern to another location
(either via email in PDF or via courier), sign it there and send it back - this would cause errors
that would be hard to prevent and correct. In this scenario however, it's possible to centralize
the activation of pen licenses to one server, while keeping the pattern generation systems
separate.
Using Pattern Sequences
In the event where a single location generates all the patterns and this output *can* be split into
multiple logical zones, Pattern Sequences can be used. A Pattern Sequence is basically a
"tag" that is added after the pattern's identification (Pattern ID). When a Pattern Sequence is
used, each Pattern Sequence can re-use each of the 20,000 available patterns. "Zones", in this
case, could refer to a specific region within a city, or a whole city or a province, whatever fits
your needs.
Pattern Sequences can be handled in 2 different ways: by attaching a Pattern Sequence to a
specific pen, or by attaching it to a specific PlanetPress Workflow process. Here is an example
Page 155
for each cases, using a typical situation of a shipping company that uses PlanetPress Capture
to simplify the archiving of the client's signature on a "Confirmation of Reception" slip.
l
Pen-Based Sequences: In this case, each pen is attributed a specific pattern sequence.
When documents are printed, they are set to attribute a pattern sequence to each
document in relation to which pen it will be signed on. For example, the shipping
company may have decided to print each "route" using the route number as a pattern
sequence, and each pen is tagged (with a label) as being for use with a specific pattern
sequence also. Each morning, as drivers are attributed a route, they pick up the correct
pen and stack of paper that belong to their route before leaving.
Note
It's very important to note here that the Anoto Digital Pen has absolutely no concept of Pattern
Sequences. When "attributing" a sequence to a pen, this is fully on the PlanetPress Workflow side,
in the Capture Database. This means that if a pen is mislabeled or someone picks up the wrong pen,
this pen has absolutely no way to know that it is writing on the wrong paper. more about this in the
Contamination section below.
l
Process-Based Sequences: In this case, while documents are still printed and their
route number attributed to their pattern sequence, the pens do not have this distinction.
However, the docking station where the pens are placed at the end of the day are set to
send the pen's data to a specific process which will only handle processing for that
specific route number. In this case, one physical computer (and, presumably, printer) is
used for each route, and the driver must dock the pen in the proper docking station which
corresponds to his router number, at the end of the day.
As you may have figured out by now, we are still not actually printing more than 20,000
patterns. The only distinction here is that we are re-using patterns in separate "zones" (or, well,
sequences) and as long as pens and pages using capture patterns are not exchanged between
these zones, they act independently with their own 20,000 pattern limitation.
Note
The mobile phone application, "PlanetPress Mobile", which uses Bluetooth communication to
receive pen data and transmit it to PlanetPress Workflow, can still be used with both pattern
sequence methods, as it is the equivalent of a docking station on the web. PlanetPress Mobile was
Page 156
added to PlanetPress Capture in version 7.4.
Contamination
The single but critical danger with any implementation that deals with PlanetPress Capture is
"Contamination". Basically, contamination happens when an Anoto Digital Pen writes on a
"wrong" document or is docked in the wrong location. This can happen any number of ways
and in different situations, and can have devastating effects in some of those cases so please
pay special attention to this section.
First, contamination is not limited to implementations that extend their patterns through
methods 1) and 2) above. Any time that a pen writes on a "wrong" document, it is considered
contamination. A simple example in a basic implementation would be to print a document with
a pattern on it, put this paper aside (or lose it on a desk somewhere) and forget about it.
Assuming proper processes were put in place, this document would eventually be closed by a
manual or automatic procedure. However, the physical document with the pattern still exists
even if it is closed in regards to the PlanetPress Capture database. Contamination would
happen if a new document is printed with the same pattern, but somehow the "old" document
re-surfaces and someone writes ink on it and docks the pen. When this happens, neither the
pen nor PlanetPress Workflow can understand that the data does not belong on that document
and will happily update the "current" document, possibly closing it. Because the "old" document
relates (presumably) to a different client, this means the "current" document has invalid
information.
This can be prevented through simple methods such as printing a date on each sheet and
ensuring that users never sign a document that is older than a certain time, for example 48
hours. These sheets should simply be destroyed.
Second, contamination can happen in method 1) above if a pen or paper is moved from one
location to another. Similarly to the previous contamination example, if there exists a document
in the Capture Database where the "wrong" data is processed, it will update a document where
it does not belong. Again, neither the pen nor PlanetPress Workflow have any idea that this
causes an error until it's too late.
Third, contamination (the most common one) can happen if pattern sequences get mixed up, if
pens or paper gets swapped between users, etc. For example, again using a shipping
company (with example 2-A), if two of the drivers were to meet for a coffee and exchange their
Page 157
pens inadvertently (we hope, anyways), the pens would be signing the "wrong" documents all
day and, when docked, would update the wrong documents in the database.
In all of these cases, the errors often do not appear when the wrong document is updated - it
actually occurs when the "right" data is processed. This happens precisely because the Pen
and Production have no idea that the wrong data is received and will generally close the
document after that "wrong" data has been processed - this often works with no error. However,
when the "right" data is processed, then it tries to update a document that has already been
closed by the "wrong" data, and thus fails.
Safeguards
There are certain safeguards against contamination:
l
l
PlanetPress Capture checks for pattern size and placement. If the data contains ink for a
specific pattern but the ink location does not correspond to the Capture Fields of the
document it's updating, it will fail.
Errors can be set to stop and revert the whole current batch. If a single error occurs during
the pen data processing, it is possible for this processing to be stopped and all changes
the Capture Database reverted. In implementations where the pen signs high number of
documents, this can especially be an easy way to do this, as chances are the data will not
match in at least one case.
Conclusion
l
PlanetPress Workflow can only generate 20,000 unique patterns
l
One pattern is used (locked) for each page containing a pattern.
l
Processing the ink data from a pen and closing the document releases the pattern
l
Most implementations will not need more than 20,000 patterns
l
l
l
When necessary, patterns can be extended using multiple servers or Pattern Sequences
(as long as these are used in separate physical locations).
It is extremely critical that contamination be avoided at all costs.
Whenever possible, always avoid using pattern sequences unless it is absolutely
necessary to do so.
Page 158
Anoto penDirector
The Anoto penDirector is a software driver provided as a download by Objectif Lune Inc. The
penDirector creates a bridge between the Anoto Digital Pen and a PlanetPress Capture
workflow in PlanetPress Workflow.
In order to use penDirector, it needs to be downloaded from the Objectif Lune website, on this
page. This software must be installed after PlanetPress Workflow. The setup will install a preconfigured version of penDirector which can be immediately used with PlanetPress Capture.
The communication between penDirector and PlanetPress Workflow is either through a folder
transfer or HTTP Post communication.
To configure this communication:
1. Open penDirector setup by right-clicking on its icon in the Windows System Tray, and
selecting penDispatcher.
2. Double-click on the PlanetPress Capture entry.
3. Change the PGC Storage folder or PGC POST URL settings to your liking.
4. Click OK, then OK again.
The PGC POST URL should correspond to your server name or IP, Port and the HTTP Action
task of your HTTP Input, if that is what you are using.
Example: http://127.0.0.1:8080/ProcessPGC
Bluetooth Connectivity
The Anoto penDirector program can also connect directly to the pen via wireless Bluetooth and
receive PGC files directly through the Bluetooth link, without needing to dock the pen.
To pair penDirector with an Anoto Digital Pen:
1. Make sure that a Bluetooth dongle is present and enabled on the computer where
penDirector is installed.
2. Note down the PIN of the Anoto Digital Pen, by docking the pen and going in the Pen
settings tab of penDirector and looking at the Pen access group at the bottom of the
dialog. The default PIN is 0000.
Page 159
3. Undock the pen, or remove its protective cap if it is not docked. Make sure the power light
on the pen is turned on and green in color.
4. Go in the Bluetooth tab of penDirector and click on Add Pen.
5. Click on Search while the cap is off on the pen.
6. When the pen is found, click on it and then click Add.
7. When asked for the PIN, enter the one noted above.
8. Click OK to save the settings.
The settings for Bluetooth PGC handling are separate from the ones used when docking.
Through Bluetooth, only a single storage and PGC Post URL location can be set for all PGCs.
Warning
Because the Bluetooth configuration only handles a single route, it is not possible to use
the Design preview patter, or the special registration pattern, using Bluetooth
connectivity. To use the preview Pattern in PlanetPress Design or use the special
registration pattern, the pen's docking station must be used.
To specify where to send the PGC files received through Bluetooth:
1. Open penDirector.
2. Go to the Bluetooth tab
3. Click on the paired pen that you want to configure
4. Specify a PGC Storage folder
5. Check the PGC POST URL option
6. Enter the URL of your PGC handling process in the box
7. Click OK to save.
PlanetPress Mobile Application
The PlanetPress Mobile application can be installed on some mobile phones and enable fast
and direct connectivity between the Anoto Digital Pen and PlanetPress Workflow. The
connectivity between the pen and the mobile phone is done through Bluetooth, while the
connectivity between the mobile phone and PlanetPress Workflow is through the currently
active data plan (either wifi or the cell phone company's data plan, such as 3G).
Page 160
PlanetPress Capture Implementation Restrictions
This document describes the limitations of the Anoto Digital Pen & Paper Technology,
especially in regards to using it within a PlanetPress Workflow implementation. Note that these
limitations apply to any Anoto technology implementation and not just our own.
Printer limitations
Any document printed with Capture Fields (aka Anoto Patterns) must be sent through a Laser
printer. Bubble jet printers are not supported and will most likely cause reading errors with
Anoto Digital Pens. Thermal printers will not work either due to the low quality printout and the
absence of actual blank ink on the paper.
Black ink close to patterns
Because the Anoto Pen & Paper technology relies on infrared to read pure-black dots on the
paper, it is imperative that no other black ink interfere with this reading. Though it is possible to
print Capture documents on a black & white laser printer as long as there is no other ink on top
of, or close to, the patterns, this is not recommended. A color laser printer should be used, and
any elements placed close to, or on top of, the Capture Patterns should be printed in color.
Black ink can be simulated using composite colors, but should never be pure black.
Page 161
Paper quality
The PlanetPress Capture technology, when generating the Anoto Pattern, already accounts for
ink dispersion on laser printers and on general-use laser paper. Therefore, using paper that is
not of the same quality (for example, one where the dispersion rate is much higher) or the same
type (reflective paper) may not permit the pen's camera to read the pattern properly.
Pattern sizes
The absolute minimum required for an Anoto Digital Pen to read the pattern and know it's
position on the page is 7mm (1/4"). Any pattern smaller than this will not be readable. However,
at 7mm width and height, the pen can only recognize a single dot within that pattern, at the top
of the field.
Page 162
This is because the pen's camera (which captures the position of the pen) is located under the
pen tip and must fully see the pattern. The following image illustrates how the pen reads its
position:
Page 163
Knowing this, the best practice when creating fields is that they have, at the very least, a 7mm
margin on each size of the actual area you want to capture from. For example, an effective
30mm wide pattern will actually be 44mm wide using these margins. The margin should be for
both the vertical size and the horizontal size.
Distance between patterns
In implementations where a lot of patterns need to be close together (a questionnaire, multiple
choice question, checkmarks, etc) it is important to understand the risk of then pen writing
across multiple fields on the paper. People using the pen may, for example, make a very broad
checkmark which would bleed over to the next field. This can cause PlanetPress Capture to
detect the ink as being present, and thus trigger whatever that field does.
Page 164
PlanetPress Capture ICR
The term "ICR", which means "Intelligent Character Recognition" is an evolution on the
popularly-known "OCR", which is "Optical Character Recognition". The difference between the
two is easily explained: While OCR can only recognize characters using the finished shape (for
example, in scanned documents and pictures), ICR relies on much more data which is provided
by the Anoto Digital Pen: the path that the pen takes, the exact timing of this path, start and stop
points, etc. This extra information boosts the recognition rates of characters by a wide margin.
It's important to note that both OCR and ICR are relatively loose terms - that is to say, they can
have different specific meanings depending on the technology used, but in their general sense
mean the same thing. When using the term ICR, we use the above definition for convenience.
Note
The PlanetPress Capture ICR engine is only available with PlanetPress Workflow
version 7.5 and higher.
An ICR Workflow
The ICR engine in PlanetPress Workflow is used in conjunction with PlanetPress Capture,
translating the ink from the Anoto Digital Pen into separate characters, or text, that is readable
by the suite. Multiple components are required in order for the ICR to work:
l
In PlanetPress Design, a Capture Field Object must be added and the Perform
ICR option must be activated (See the Capture Field page in the PlanetPress Design
Page 165
User Guide). This must be either a Multi-Area Field or a Text Field.
l
l
l
The Capture Fields Processor must have the Perform ICR Recognition option checked,
and language needs to be selected.
Once the ICR data is available, do something with it. This is done by reading the ICR data
that is available in the metadata generated by the Get Capture Document task.
The metadata is also readable by the Capture Condition task, including the captured text
and the reliability of this text.
The Workflow as such is the following:
l
A Capture field is setup for ICR in a PlanetPress Design document.
l
The document is sent to PlanetPress Production
l
The Capture Field Generator is used to produce one or more print-outs using this
document.
l
The physical sheets are written on using an Anoto Digital Pen
l
The pen is docked and the data is sent to PlanetPress Production
l
l
l
The pen data goes through the Capture Field Processor, where the Capture Field ink is
sent through the ICR engine.
The captured ICR data is retrieved with the document using the Get Capture Document
task.
Conditions are applied if necessary with the Capture Condition task.
Warning
ICR, just like OCR, has its limitations. Please refer to the PlanetPress Capture ICR Best
Practices page for more information.
Terminology and Definitions
In regards to our ICR technology specifically, the following terminology applies:
l
ICR: "Intelligent Character Recognition", or the engine that will read the pen data and
attempt to recognize the text written using the pen itself. The ICR engine uses the path of
the pen, its movement speed as well as the overall shape of each character to determine
which character was written.
Page 166
l
l
l
ICR Value: The alpha, numeric or alphanumeric value that was determined by the
ICR engine.
ICR Confidence: A percentage value that the ICR engine gives to any specific value,
when comparing the pen data with it's character database.
ICR Resemblance: A percentage value that defines how closely the value resembles the
"average" character shape. Both the Confidence and Resemblance can be used together
to make an informed decision on the contents received by ICR.
PlanetPress Capture ICR Best Practices
From Workflow 7.5 onwards, PlanetPress Capture supports Intelligent Character Recognition
(ICR). However, this technology comes with certain limitations. A successful integration of ICR
within a business requires the application of best practices by all parties involved: Form
designer, Workflow designer and User.
Here we present a list of recommended best practices. Each of these guidelines aim at
maximizing the likelihood that the characters are recognized; and minimize the risk of errors
due to an incorrect analysis.
You will find the following information, when applicable, for each best practice:
l
l
Target: The targeted audience. There are 3 possibilities: Form designer, Workflow
designer and User.
What: A brief description of the best practice. This could include an explanation of the
concepts that are addressed.
l
Why: A brief explanation of the reasoning behind the relevance of this guideline.
l
How: How to apply this best practice.
This section describes a list of the best practices to implement. They are listed in no particular
order of importance. Pay attention to the targeted audience to know if this rule applies to you.
Using the Most Restrictive Mask
l
l
Target: Form designer.
What: In the Capture Options tab of a Capture object, the mask type indicates the type of
character to be recognized. There are 3 possible selections: numeric, alphabet and
alphanumeric. The alphabetic mask type allows you to select the letter case.
Page 167
The following guidelines are applicable when configuring a PlanetPress Capture object
that utilizes ICR:
l
l
l
l
l
l
l
The collected data is expected to be a number, therefore the numeric mask type must be
selected, or
The collected data is expected to be a letter, therefore the alphabet mask type must be
selected,
If upper case letters are expected, select Upper case in the Case option menu. The
captured characters would be immediately converted to capital letter i.e. the ICR engine
will recognize a lower case a but will display it in upper case.
If lower case letters are expected, select Lower case in the Case option menu. Same as
for upper case letters, the captured characters would be converted to lower case and
displayed as such.
If proper names or nouns are expected (i.e. only the first letter must be a capital letter),
select Capitalization in the Case option menu. Only the first letter would be converted to
a capital letter.
If no specific format is expected, select None in the Case option menu. The letters will be
interpreted as written, no conversion will be done i.e. characters in lower case will be
displayed as such.
The collected data is expected to be a combination of numbers and letters, therefore the
alphanumeric mask type must be selected.
Why: Reducing the number of expected characters increases the probability that the correct
one is matched. This allows us to avoid that the letter l (a lowercase L) is not recognized as the
numeric value 1 (one) and vice versa. Or, if the mask type is identified as alphanumeric, there’s
a possibility that the letter a is recognized as 2; since Capture will also interpret how the
movement was traced.
How: Use the following options from the Capture options tab under Mask Type and Case
option to filter the expected data.
Page 168
The following diagram illustrates the available mask types. It is recommended to select the
mask type that is the closest to the desired result. An alphanumeric field should be used as a
last resort.
Guidelines for Capture-Ready Fields
l
l
Target: Form designer
What: Only one character per Capture field can be recognized. When expecting multiple
characters making up a word or phrase, you must make sure that the user only writes one
character per field. In order to do so, you must make sure that the fields are big enough
and have enough space between each one. The best practice is to make sure that there
is a boundary surrounding the field where ink marks are to be written.
Page 169
Why: To avoid any ink marks that would spill over from one field to another. If both fields A and
B are to close in proximity and the ink marks from field A spill over to field B, then the marks
captured on field B would be considered as being part of a character written on field B. For
example, if a number spills over and is written over two fields like numbers 9, 1 or 7; then the
bottom tip of these numbers could be considered as number 1 in the second field. (Refer to the
example below)
Page 170
How: Make sure there’s enough space between each field. You must re-design the document if
that’s the case. There’s no minimum value that is required as the distance between 2 fields,
except for the 7mm border that is required in order for the Anoto digital pen to recognize the
pattern being used.
Writing in a Legible Way
l
l
Target: User.
What: It is important to write in a legible way i.e. applying yourself by writing well defined
numbers and letter that are easily interpreted.
Warning
You must write on a flat and smooth surface i.e. a delivery person should use a clipboard.
Why: Some numbers can create some confusion, like numbers 7 and 1. 7 can be interpreted as
a 1 and vice versa. The letter i, where the dot on top is a circle, can possibly cause a conflict
because the dot can be considered as an o.
How:
l
Write an additional line under the number 1.
l
Write an additional line across the number 7.
l
l
l
The ICR functionality of PlanetPress Capture cannot recognize dotted letters where there
are circles instead of dots (like i , j). This would be analyzed as an i AND o. Therefore,
dots should be as such and not circles.
In French, the ç is somewhat sensitive. You must apply yourself and draw the letter
carefully. In most cases, it is recognized, but attention must be paid.
Number 8 is also sensitive. It is recommended that the number is traced as one
movement instead of drawing 2 circles on top of each other.
Selecting the Correct Language When Using the Capture Field Processor Task
l
l
Target: Workflow designer.
What: It is crucial that the correct language is selected when using the ICR recognition
option. This will affect how the captured data is interpreted.
Page 171
Why: The available filters to interpret the ink marks done with the Anoto digital pen, allow you
to select the engine language to be used. Doing so will give you results that are the closest
match to the captured data. Multiple cultural characters can be interpreted with ICR once the
correct language is selected such as û, à, é, etc.
How: This option is available from the Capture Fields Processor task.
Page 172
Possibility of Interpretation Error in an Automated Process
l
l
Target: Workflow designer
What: We cannot be 100% sure that a character would be recognized by PlanetPress
Capture as it should. Therefore, the analysis of a value interpreted with ICR should only
occur if the level of confidence is superior to a determined level.
Why: An automated process can treat the characters incorrectly due to an incorrect
interpretation of a value. This occurrence should be minimized as much as possible.
How: Allow for a special process (possibly manual handling) in the case the automated
process didn’t reach a high confidence level in its analysis of the ink marks. Use the plugin
Capture condition that includes the ICRContent option. This can be configured to be a true
condition if the confidence level is greater than a certain value.
Basic Functional Capture Workflow
This workflow is the most basic and simple workflow that you can use with PlanetPress
Capture. In small implementations with only one simple document, this may be the only thing
required for a functional workflow since, even in this simple state, it can be enough to automate
the archive of your digital documents.
Generator Process
The workflow requires two separate processes that will be triggered at different times. The first
process, the generator process, produces printable output by merging a data file with a
Capture-Ready PlanetPress Design document. For each document page produced, an Anoto
Pattern is assigned to the document and locked, and a page is produced in the output.
Depending on the setup used, this may produce on or more print jobs or PDFs as an output.
Page 173
l
Any input task
l
"Create Metadata" on page 509
l
"Capture Fields Generator" on page 482
l
Print output
PGC Handling Process
The second process is the PGC Handling process. It receives data from the Anoto Digital pen,
updates the Capture database and releases patterns as appropriate.
l
"HTTP Server Input" on page 228 or "Folder Capture" on page 213 input task
l
"Capture Fields Processor" on page 486
l
"Get Capture Document" on page 502
l
Archive or Print output
Capture Post Processing Workflow
Though the "Basic Functional Capture Workflow" on the previous page is minimal functional
one, it will most likely not be enough for most actual implementations. The goal with
PlanetPress Capture (and PlanetPress Workflow in general) being to automate as much as
possible, there are some tools within the PlanetPress Capture tasks that can greatly help with
this goal.
There are two places where post-processing can happen: after the "Capture Fields Processor"
on page 486 while handling incoming ink data, or after the "Find Capture Documents" on
page 497 task that is part of an automated process or after a user request.
Page 174
Post-Processing is generally done using the "Capture Condition" on page 476 task, which
verifies the presence or state of the ink on the document or on specific fields.
After PGC Handling
Here is an example of a process that receives ink data, updates the database, and then verifies
whether or not a field that indicates manager attention is required (for example, a box noting the
wrong number of items in a delivery slip). If attention is required, the document is sent via email
to the manager. Otherwise, the document is simply archived.
Task Breakdown:
l
The HTTP Server Input receives a POST request sent either by the Anoto penDirector or
the PlanetPress Mobile Application. This requests contains information sent by the pen
as well as a PGC file as an attachment. Because we're only concerned about the PGC,
the task is configured to ignore the XML envelope as well as loop through each
attachments (of which there is only one). So, the output of the task is the PGC file alone.
Page 175
l
l
The Capture Fields Processor then uses the PGC file to update any documents in the
database that the pen wrote on, and closes those documents in the database when they
are complete.
Capture Condition is where we can check whether a specific field (a
"RequireManager" field) has ink contained in it, and if it does, the branch on the right is
triggered.
l
l
In the branch, Get Capture Document retrieves a PDF version of the document and
sends it as an attachment to an email sent directly to a manager using Send Email.
Otherwise, Get Capture Document is used again, but this time the PDF is stored in a
SharePoint Server using the Output to SharePoint connector.
After Retrieving Information from the Capture Database
There are two basic ways in which the Find Capture Document task can be used. First, in an
automated process that runs at specified intervals. For example, the following process which
sends a daily report of all incomplete and "in error" documents to an agent who would
presumably take action on each document through the document manager.
Page 176
Task Breakdown
l
The Find Capture Documents task queries the Capture database for documents that
correspond to certain specific conditions. For example, here we would look for all
documents that are either in an "Error" or a "Partial" state, which means they received ink
but are not completed correctly. To do this, the "Content Status" filter and setting it "Equal
Page 177
to" those states. Two conditions are necessary, and the "Condition is true when" is set to
"all items are met".
l
With this list of documents in the metadata, we Branch off. This is done because we need
to build a report that will be sent to an administrator, and only one email should be sent.
l
l
To build the report, inside of the branch we use the Metadata Sequencer to create
one sequence for each document, by splitting at the Document level, by 1
occurrence of the level for each sequence.
The Capture Condition task then
Capture Web Manager Workflow
This example is both a more involved workflow for Capture, and an interesting implementation
of an HTTP Workflow. Before looking at this example, it would be best to become familiar with
both "PlanetPress Capture Workflow" on page 143 and "HTTP Server Workflow" on the facing
page.
The example is too complex to display as images in this guide, so it is rather available for
download. It infers two different files:
l
Capture Web Manager Workflow Configuration (PW7)
l
Capture Web Manager PlanetPress Design Document (PP7)
Technical
This example is compatible with PlanetPress Workflow 7.4 and higher and will not work
in older versions.
Installation
1. Download both resource files
2. Create a folder on your disk called c:\PlanetPress
3. Open the invoice.pp7 document and send it towards your local PlanetPress Workflow
server (localhost or 127.0.0.1)
4. Open the configuration file CaptureExampleProcess.pw7
5. Click the PlanetPress Workflow button (File menu) and go in Preferences.
6. In the HTTP Server Input 2 section, check the Serve HTTP resources option, change
Page 178
the Resource action name box to static , and the Resource folder to
c:\PlanetPress\http . Then, click OK.
7. Send the configuration to your local PlanetPress Workflow server.
8. Start PlanetPress Workflow services (see "Start and Stop PlanetPress Workflow Service"
on page 660).
9. Open your browser and point it to http://127.0.0.1:8080/documentlist , assuming you have
not changed the default HTTP port in the HTTP Server Input 2 section.
Explanation
You can follow along the process by looking at the comments available in each process of the
workflow file. Each comment explains both what the following plugins do, but also how it
integrates into the workflow in general and what to keep in mind when doing an actual
implementation of such a process.
Considerations
l
l
l
The workflow itself is a standalone system that does not interact with any third-party
systems, which of course does not correspond to real customer implementation. A client
will most likely need to communicate with both an ERP system that generates documents
as well as an archive software to store completed documents.
The HTML, CSS and data file are generated whenever the process starts, in a specified
location, in order to avoid having to distribute multiple static files which would need to be
extracted and moved to a specific folder. In an actual implementation, these files would
probably be edited externally and loaded from a location on the hard drive. However, the
method of using a template to generate output is not so alien to PlanetPress Workflow so
it is not condemned to do so.
The example doesn't use any advanced coding such as JavaScript, Ajax and caching. It's
easier to follow, but is less optimized in its use than a complex workflow that would use
such features.
HTTP Server Workflow
An HTTP Server workflow is one that has one or more processes that always start with the
HTTP Server Input task and returns something to a client using a web browser. Each process
would have a specific task referred to as an "action", called from the browser itself.
HTTP Server Input tasks are typically used in one of the two following situations:
Page 179
l
l
HTML Form Action: An HTML Form in the browser that may contain text and attached
files can be filled and sent to a process with the HTTP Server Input task.
HTTP Data Submission: A custom application or a server sends the request to
PlanetPress Workflow using either a POST or GET command. The application or server
then waits for a response from PlanetPress Workflow Tools.
PlanetPress Workflow can serve both static and dynamic resources to a web browser, however
it is not meant to be used as a fully featured web server, as it is not built for responsiveness nor
guaranteed uptime. It is much better to have a common web server (for example, IIS or
Apache) to serve your contents and to have PlanetPress Workflow available only to process
things only it can do.
Note
You can control access to the PlanetPress Workflow Tools HTTP Server via the Access
Manager.
Important Configuration, Setup and Options
Before starting to work with HTTP workflows, there are few key points to keep in mind in terms
of configuration. First of all, the following options are available in PlanetPress Workflow
Preference screen, under the HTTP Server Input 1 and HTTP Server Input 2 sections:
l
l
Port (default value: 8080 recommended): The port number is the one in which a
browser needs to make a request to PlanetPress Workflow. By default in most web
server, port 80 is used and, when this is the case, it is not necessary to include it. For
example, if I type http://www.objectiflune.com/ in my browser, it is actually accessing the
address http://www.objectiflune.com:80/ , but port 80 is always hidden. The reason port
8080 is used by default is to prevent any interference with existing web servers installed
or activated on the same server as PlanetPress Workflow.
Time-out (seconds): This determines how long the HTTP Server service will wait for the
process to finish, before returning a time out error back to the client browser. This means
that if a process takes more than 120 seconds (by default) to complete, the browser will
time out. While you can change this value, it is recommended to always keep your
processing to a minimum, since both browsers and users generally frown upon being
stopped for more than a minute, unless they are well aware of this processing time (and
even then...)
Page 180
l
l
Enable server for SSL requests: This enables secure communication between the
browser and the server via HTTPS. By enabling this option, you will need to provide for
the proper certificates, key and password. While this configuration is beyond the scope of
this document, there are plenty of resources on the Internet to explain these systems.
Serve HTTP resources: This is where you enable static resources in PlanetPress
Workflow. When enabling this option, the HTTP server will always look in the Resource
Folder for files requested inside of the Resource action name as a folder. This means
that, if your Resource folder is c:\PlanetPress\http and your Resource action
name is static, pointing your browser to
http://127.0.0.1:8080/static/css/style.css will immediately load and
return the file c:\PlanetPress\http\css\style.css . This does not require any
process to work - everything is handled directly by the HTTP Server Input and files are
returned immediately. This feature is very useful when dealing with stylesheets, images,
browser JavaScript, or static html files that do not require any processing.
Technical
As of PlanetPress Workflow 8.1, it is now possible to serve a default HTML file when no
action is specified, for example http://localhost:8080/ . This is done by creating an
index.html file in the Resource Folder defined above. However, resources called by
this index.html must still use the Resource action name, for example a stylesheet
would still point to http://127.0.0.1:8080/static/css/style.css or more simply
static/css/style.css.
You also need to take into consideration the options inside each of your processes that start
with the HTTP Server Input task, as they will greatly impact how this process responds. In the
process' properties, the following options will modify HTTP behavior:
l
l
l
Self-Replicating Process: This option is critically important when dealing with
HTTP processes, so check it now. Basically, this means that when HTTP requests are
received, the process will duplicate itself up to the specified maximum number, in order to
simultaneously (and asynchronously) handle multiple requests. See " Process
Properties" on page 704 for more details.
As soon as possible: This option needs to be checked, otherwise requests will not be
handled as they come in (this option is meant to be used on scheduled processes that run
at intervals).
Polling Interval (sec): This option determines how much time the HTTP Server Input
waits between the moment it finishes processing a request and the moment it picks up a
Page 181
new request. This should be put at 0 in order to process requests as soon as possible,
meaning immediately.
And finally, the HTTP Server Input task properties. While these are described in the "HTTP
Server Input" on page 228 task properties page, here are a few considerations to keep in mind
when using this task:
l
l
l
l
l
The HTTP Action corresponds precisely to the name immediately following the first slash
of your address. That is to say, placing the action myaction here means the process
would be triggered by opening http://127.0.0.1:8080/myaction in your
browser.
The HTTP service accepts both POST and GET requests. Other than the presence of file
attachments, there is little difference in how these are handled. This means that visiting
/myaction?id=12345&q=test would be the same as having a form with two
fields named, respectively, id and q, and submitting them with the information
"12345" and "test". In both cases, this information is located in the XML envelope that is
the original input file.
When doing POST requests and uploading files, always make sure to include the
"multipart" option in the Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.4 Linearized : No Page Count : 796 Page Mode : UseOutlines Page Layout : SinglePage Language : en-us Producer : madbuild Create Date : 2018:04:09 12:13:13-04:00 Modify Date : 2018:04:09 12:13:13-04:00 Title : PlanetPress Workflow User Guide Author : Objectif Lune, Inc. Subject :EXIF Metadata provided by EXIF.tools