Installing and Using

ScriptServer PDF Broker 5

Software version 5.0

Document revision A April 2015

Copyright 2015 GrayMatter Software Corporation

GrayMatter, the GrayMatter logo, ScriptServer, ScriptServer PAN, and ScriptServer PDF Broker are trademarks of GrayMatter
Software Corporation, Tacoma, Washington, and may be registered in certain jurisdictions. Acrobat and PostScript are trademarks
of Adobe Systems Incorporated, which may be registered in certain jurisdictions. Other brand or product names are trademarks of
their respective holders.
The information in this document is furnished for informational purposes only, is subject to change without notice, and should
not be construed as a commitment by GrayMatter Software Corp. GrayMatter Software Corp. assumes no responsibility or
liability for errors, omissions, or inaccuracies that may appear in the software described by this document or contained in this
document.
The software described in this document is furnished under license and only be used or copied in accordance with the terms of
that license.

Table of Contents
Chapter 1: Introduction

1.1 About ScriptServer PDF Broker Software...................................................5

Chapter 2: Installation

2.1 Before Installing the Software ...........................................................................8

2.2 Installation.........................................................................................................9
Chapter 3: Settings

14

3.1 The PDF Broker Settings Application .............................................................14

3.2 Upgrading From Previous Versions ................................................................15
3.3 Configuring PDF Broker Settings....................................................................16
3.4 Configuring E-mail Settings ............................................................................19
3.5 Configuring PDF Broker Archives Server .......................................................20
3.6 Installing the PDF Broker License ..................................................................22
Chapter 4: Routers

24

4.1 Creating Routers.............................................................................................25

4.2 About Routers .................................................................................................25
4.3 Comment-Based Routers ...............................................................................26
4.4 Dispositions ....................................................................................................27
4.5 Router Options................................................................................................28
4.6 E-Mail Options ................................................................................................28
4.7 Importing and Exporting Routers ....................................................................29
4.8 Placeholders ...................................................................................................29
4.9 The Special-Case Router .............................................................................31
4.10 Using Post-Processing Commands ..............................................................32
4.11 The %%SSV_UserData Comment................................................................32
4.12 TransFormat Split and Passthrough Fields...................................................33
Chapter 5: Archiving

35

5.1 Archive Properties...........................................................................................35

5.2 On-Disk Structure ...........................................................................................36
5.3 Archive Metadata ............................................................................................36
5.4 Creating Archives............................................................................................37
5.5 Browsing the PDF Broker Archives.................................................................38
5.6 Accessing the Archives Remotely ...................................................................39
5.7 Archive Authentication ....................................................................................39
5.8 Removing Documents from the Archives........................................................40
5.9 Moving the Archives to a Different Location ...................................................40

Chapter 6: Security Profiles

41

Chapter 7: PDF Broker Assistant

44

Chapter 8: Data Lookup

46

8.1 Introduction .....................................................................................................46

8.2 Importing Data ................................................................................................47
8.3 Viewing Database Tables ...............................................................................48
8.4 Defining Lookups ............................................................................................50
8.5 Sample Lookups .............................................................................................50
Chapter 9: Administrative Tasks

52

9.1 Controlling ScriptServer PDF Broker with the Services Tool ..........................52
9.2 Viewing ScriptServer PDF Broker Logfiles .....................................................53
9.3 ScriptServer for OpenVMS Compatibility........................................................54
9.4 ScriptServer PAN Compatibility ......................................................................55
Chapter 10: Creating Desktop Printers

58

10.1 Setting Up a Printer on Microsoft Windows XP ............................................58

10.2 Setting Up a Printer on Microsoft Windows 7/8 ............................................65
10.3 Setting Up a Printer on Mac OS X ................................................................71

Chapter 1: Introduction

1
1.1 About ScriptServer PDF Broker Software
The ScriptServer PDF Broker is a software product that allows a network server to provide PDF
conversion services on behalf of network clients. It can also convert PostScript print data
streams and distribute the resulting PDF files via e-mail, copy to folder (whether local or a
network share), and/or post-process either the PostScript or PDF files by executing user-defined
commands.
Printing clients include the ScriptServer PAN Printing System and ScriptServer for OpenVMS,
which are separately licensed products from GrayMatter Software Corp., and virtually any
generic PostScript source over TCP/IP, including printer data streams from all versions of
Windows, and the various flavors of Unix, including Linux. ScriptServer PAN and ScriptServer
for OpenVMS are integrated with the PDF Broker so that information can be passed to it that can
be used to manipulate the PDF file produced.
How It Works

ScriptServer PDF Broker software is implemented as a Windows service that listens for
connections over TCP/IP. It can receive data from any PostScript-compatible printer driver,
which is operating as though it were connected to a network printer. The PostScript data
received is written to a temporary file and Acrobat Distiller or Ghostscript is used to convert the
PostScript language page descriptions to PDF format. The resulting file is then distributed
according to the way the particular routers associated with the conversion are defined.
Routers are used to determine how the PDF file is to be named and distributed. A router can
distribute based on the port over which the PostScript file was received, or based on certain

PostScript comments embedded in the PostScript data streams header. See Chapter 4 for more
information about setting up electronic distribution modes for your documents.
PDF Broker Editions

In order to provide the greatest amount of flexibility for our customers, ScriptServer PDF Broker
is licensed in three editions: Desktop, Standard, and Professional. Throughout the documentation
for PDF Broker software, the following symbols will be used to denote the version required for a
given feature:
The Desktop Edition provides basic PDF conversion functionality at an affordable
entry-level price. It includes support for port-based routing, event logging, emailing
PDFs, and saving PDF files to a folder.
The Standard Edition adds the following feature support to the Desktop Edition:
comment-based routing, job processing with command scripts, placeholder data
substitution, user-defined substitution data, and security profiles for PDFs.
The Professional Edition adds the following feature supported to the Standard
Edition: the Special Case router, data lookup tables, TransFormat support, PDF file
splitting, and TransFormat passthrough fields.
Details on the differences between the three editions, along with pricing information, can be
found in the document EditionComparison.pdf in the PDF Broker installation folder.
Features

Automated distribution using the ScriptServer PDF Broker:

converts and distributes documents to multiple destinations with one simple printing
operation
saves time and money over cumbersome, multi-step processes
instantaneous document delivery via e-mail
works with any desktop application with a File > Print function
is compatible with PostScript printer drivers on virtually any operating system
is compatible with virtually all mail servers (using SMTP)
can be customized to execute third-party applications for document handling
security policies can be defined to prevent unauthorized modification, printing, and/or
viewing of the PDF file
TransFormat support for file-splitting and pass-through data extracted from print files
data lookup capabilities to extract e-mail addresses and other data for determining the
disposition of PDF files
creates archives of data that can be browsed from any Windows computer over the Internet
with the PDF Broker Archives application, which is licensed free of charge

The advantages of using a centralized PDF conversion service include:

a standardized set of parameters creates uniform PDF files since the policy for PDF file
parameters is set by an administrator rather than on a per-user, ad hoc basis
PDF files can be created by applications that do not have a native PDF file creation
capability
simplified, centralized management of PDF creation software
performance benefits by offloading work to a dedicated and/or high-performance server

Minimum System Requirements

ScriptServer PDF Broker has the following minimum system requirements:

Windows Server 2003, Windows Server 2008, Windows Server 2012, Windows XP,
Windows Vista, or Windows 7/8 operating system
20 megabytes of free disk space for installation
recommended 10 megabytes of free disk space for each concurrently active router
TCP/IP networking
One of the following PDF creation tools:
o Adobe Acrobat software, version 4.0 or later, or
o Ghostscript, version 8 or later recommended

Chapter 2: Installation

2
2.1 Before Installing the Software
You must install the PDF conversion software (Adobe Acrobat or Ghostscript) before using the
ScriptServer PDF Broker.
Using Adobe Acrobat

The component of Acrobat that converts PostScript print data to PDF is called Acrobat Distiller.
The name of the program is acrodist.exe, and it is normally installed into the path (in this case,
assuming the Acrobat version is 6.0):
C:\Program Files\Adobe\Acrobat 6.0\Distillr\Acrodist.exe

Acrobat affords extensive control over the PDF file conversion process in the form of job options
files. ScriptServer PDF Broker allows you to specify which job options file is to be used. Acrobat
provides several sample files that create PDF files suitable for particular purposes, such as for
viewing at screen resolution, laser printing, and pre-press applications.
Using Ghostscript

The Ghostscript installers for Microsoft Windows are available for free download from the
GrayMatter Software FTP site at the following URLs:
32-bit: ftp://ftp.graysoft.com/gpl/Ghostscript/win32/gs854w32-gpl.exe
64-bit: ftp://ftp.graysoft.com/gpl/Ghostscript/win64/gs914w64-gpl.exe
The name of the program is gswin32c.exe (for 32-bit) or gswin64c.exe (for 64-bit), and it is
normally installed into the path (in this case, assuming the Ghostscript version is 8.54):
C:\Program Files\gs\gs8.54\bin\gswin32c.exe

2.2 Installation
ScriptServer PDF Broker installer can be downloaded over the Internet with the following URL:
ftp://ftp.graysoft.com/pdfbroker/SPB_V5_0_0.exe

Double-click the installer application to start the installation.

Installer welcome screen

Once the installer has started, you will see the Installers welcome screen. Clicking on Next >
will bring up the license agreement window. You must accept the terms of the agreement to
continue with the installation.

!
License agreement screen

The installer will now display the contents of the ScriptServer PDF Broker ReadMe file.

ReadMe file screen

Review the information that is displayed and click the Next > button to display the installation
location screen.

Installation location screen

Enter, or browse for, the location that the software is to be installed into. The default location of
Program Files\GrayMatter Software\PDF Broker 5 on the boot drive is appropriate for most
installations. If this folder does not exist, you will be prompted for whether it should be created
for you.

If you are upgrading from PDF Broker 4, the installer will check to see if there are PDF Broker
archives in their default location. If it finds them there, it will display the following message:

Important Note for Upgrades

The location of the archives and lookup databases changes to a new default with this release. The
PDF Broker 5 installer will allow you to leave the archives in their current location if you desire,
but the new version will create a new archives database if you choose to leave them in the
previous location. The archives can be placed in a non-default location using two registry keys
(Archives Path and Archives File). These are the registry entries modified when using the
PDF Broker Settings command Data > Archives > Changes Location (V4.4 and later). The new
location is:
C:\ProgramData\GrayMatter Software\PDF Broker Persistent Data\Archives
If you need to run PDF Broker 5 concurrently with a previous version of PDF Broker 4 for
testing purposes, please contact GrayMatter Software for assistance.

The Select Additional Tasks window is then displayed:

Select the installation options desired and click Next to present the Ready to Install screen. If you
are satisfied with the answers you have provided, click on the Install button to proceed.

!
Ready to Install screen

As the installation proceeds, a window will display the installers progress.

!
Installer progress screen

After all of the ScriptServer PDF Broker software files have been copied to their destinations, the
Installer will display the Quick Start Guide. This document is also copied to the installation
directory, so it may be viewed after the installation process has completed (using Start >
Programs > ScriptServer PDF Broker > Quick Start Guide).

Quick Start Guide

The installation is now complete; the installer now displays the following window.

Completing installation window

At this point, the ScriptServer PDF Broker Service is ready to be configured. This is done with
the PDF Broker Settings application and is discussed in the following chapter.

Chapter 3: Settings

3
3.1 The PDF Broker Settings Application
Since ScriptServer PDF Broker software runs as a Windows service, it does not have a user
interface to control its operation. Instead, you use the PDF Broker Settings application to
manipulate the registry settings that control it. The PDF Broker Settings application can be run
from the Programs > ScriptServer PDF Broker > PDF Broker Settings entry in the Start menu.
The first time you run the PDF Broker Settings application, it displays the following welcome
window:

!
PDF Broker Settings application welcome window

This gives you an opportunity to display the on-line reference material by clicking the Help
button.
Clicking the Continue button displays the Settings window, which has three tabs: Settings, Email, and License. When you are setting up ScriptServer PDF Broker software the first time, you
must provide information on each of these tabs.

3.2 Upgrading From Previous Versions

If you are upgrading from version 4 or earlier of ScriptServer PDF Broker software, the first time
you run the PDF Broker Settings application you will be given the opportunity to import your
existing settings, routers, and security profiles:

If you are upgrading from version 4.0 or 4.1 of ScriptServer PDF Broker software, the archives
database must be updated to handle optimizations implemented in version 4.2. When you run the
PDF Broker Settings application the first time after upgrading, you will be prompted to update
the database with the Archives Database Updater utility:

!
Click the Launch Updater button to use the Archives Database Updater utility to update the
archives database to the new format.

3.3 Configuring PDF Broker Settings

To configure PDF Broker general settings, choose Edit > Settings.
The Settings tab controls the overall operation of ScriptServer PDF Broker software. These
settings are discussed in detail below.

PDF Broker Settings application window on Settings tab

Convert to PDF Using

This radio button is used to select the conversion utility: Acrobat Distiller or Ghostscript.
Distiller/Ghostscript Path

The Distiller/Ghostscript path is used to specify the location of either the Acrobat Distiller
application or the Ghostscript program. Click the Browse button to specify the conversion
programs location.

By default, Acrobat is installed in \Program Files\Adobe\Acrobat 6.0\Distillr\AcroDist.exe on the

boot drive (assuming the Acrobat version is 6.0). The default location of the Ghostscript program
is \Program Files\gs\gs8.54\bin\gswin32c.exe on the boot drive (assuming it is version 8.54).
Work Folder

The ScriptServer PDF Broker uses a work folder to hold the temporary files used in the creation
of PDF files. The default value is the folder named Work in the Application Data folder.
However, you may use a different folder provided that the ScriptServer PDF Broker service has
write access to the folder.
Job Options file (Acrobat Distiller only)

Acrobat Distiller uses job options files to control the various aspects of how PDF files are
created. You can select a job options file that is provided with Acrobat that is appropriate for the
type of PDF files you want to be created, or you can create a new job options file with the
Distiller application and provide the path to that file here. The default location for job options
files is in the folder \Program Files\Adobe\Acrobat\Distillr\Settings\.
PDF Settings (Ghostscript only)

This pop-up menu allows you to specify the target medium (Default, Screen, Ebook, Printers, or
Prepress) for the PDF files generated. Screen generates the most compact PDF files, Prepress
provides the greatest fidelity, and Default provides a tradeoff between the two. The following
table summarizes the effect of the PDF Settings on the key individual conversion parameters.
Setting

Default

Screen

Ebook

Printer

Prepress

Auto-rotate pages

PageByPage

PageByPage

All

None

None

Color conversion strategy

Leave unchanged

RGB

RGB

Device
independent

Leave unchanged

Downsample images

no

yes

yes

no

no

Downsampling technique

Subsample

Average

Bicubic

Bicubic

Bicubic

Generate thumbnails

no

no

no

no

yes

Embed fonts

yes

no

yes

yes

yes

Image resolution (color

and grayscale)

72

72

150

300

300

Image resolution (mono)

300

300

300

1200

1200

Auto-Rotate Pages (Ghostscript only)

This menu allows control over the automatic detection of page orientation within a job converted
by Ghostscript: All enables automatic detection, None disables it, and PageByPage handles it on
a page-by-page basis.

E-mail Errors to

When a conversion error (such as a PostScript error) or a routing error (such as an invalid e-mail
address) occurs, ScriptServer PDF Broker sends an e-mail message to the address provided here.
Default Service Port

This determines what port is used to provide the PDF conversion service for client-mode
conversions and comment-based routers. Unless it conflicts with another application or service,
the default value of 8899 should be used, since it is the default value used by clients.
Event Logging Level

This setting controls the amount of logging performed by ScriptServer PDF Broker software to
the error log. For normal operation it should be set to Errors and Information messages.
Job Timeout

This slider allows control of the maximum length of time that the ScriptServer PDF Broker will
wait for a PDF file to be converted and distributed according to the router(s) used by the job. If
the job processing takes longer than the timeout period, the job will be terminated.
Connection Limit

This slider controls of the maximum number of connection that can be active simultaneously on
each router port. This lets you set a ceiling on the amount of load placed on the server during
periods of heavy activity. When the number of active connections reaches this limit, PDF Broker
will stop accepting connections until the active connections drops below this value.

3.4 Configuring E-mail Settings

The E-mail tab is used to control the details of how e-mail messages are sent.

PDF Broker Settings application window on E-mail tab

Server address

Provide the name of the e-mail server to be used to send outgoing (SMTP-based protocol) mail.
You may use either its DNS name or its address in dot-notation.
Port

Provide the port number to be used when connecting to the e-mail server. The default port for
SMTP servers is 25.
Username and Password

If your e-mail server requires authentication information to send messages, provide the username
and passwords to be used here.

Send Test Message

Clicking this button allows you to test that your email setting are properly configured.
E-Mail Message Defaults Fields

These fields allow you to specify default values to be used for Sender, Subject, Cc address(es),
Bcc address(es), and message text for the e-mails sent by the ScriptServer PDF Broker. These
values can be overridden on a per-router basis (for those routers using an e-mail disposition). If
the router-specific value is (use default), the values are taken from those provided here.

3.5 Configuring PDF Broker Archives Server

The PDF Broker Archives Server provides access to documents stored in the archives to
network-connected clients running the PDF Broker Archives application. See chapter 5 for
detailed information regarding the management of the archives.

PDF Broker Settings application window on Archives Server tab

Archives Server Port

Specify a TCP/IP port number over which to provide network access to the archives. Unless it
conflicts with an existing service port, we recommend that you use the default value of 8890,
since it is the default port when configuring servers in the client application.
Session Inactivity Timeout

This setting controls the length of time that a connected client can be inactive before the session
is terminated by the server.
Authentication Settings

PDF Broker Archives Server uses several security features to control access to the contents of
PDF Broker archives. All communications between server and client are encrypted using a
combination of the Shared Secret (similar to the technique used in VPN software) and a sessionspecific seed. When configuring access to a server in the PDF Broker Archives application, the
user must provide the same Shared Secret as that used on the server or the connection will fail
with an Invalid shared secret error.
Once a client has successfully connected (i.e. the shared secret is correct), you can optionally
require that the user provide a valid Windows username and password to access the archives. To
require logon credentials, check the Require Windows-based user authentication checkbox.
The PDF Broker Archives application has the ability to save logon credentials and archives
access passwords on the client computer. These credentials are stored in encrypted format in the
users Preferences file. (The encryption seed is specific to the user, so the credentials in a users
Preferences file cannot be used to gain access if copied to another users account.)
To prevent users from being able to store access credentials in the PDF Broker Archives
application, uncheck the Allow clients to store access credentials checkbox.

Note
If an archive uses the Active Directory security model, the users Windows logon credentials are
required to authenticate the user against the archive. If you use the Active Directory security
model on an archive, you must check the Require Windows-based user authentication
checkbox to allow access to those archives.
Message Logging Level

This setting controls the amount of logging performed by ScriptServer PDF Broker software to
the error log. For normal operation it should be set to Errors and Information messages.
Logfile Rention

This setting controls the length of time PDF Broker software will keep logfiles. Older logfiles
are automatically deleted as new ones are created.

3.6 Installing the PDF Broker License

ScriptServer PDF Broker software is licensed using GrayMatter Softwares SLicKey (Software
License Key) license management system. The license is in the form of an XML file (with a .slky
extension) that must be placed in the application data folder (by default, this is the directory C:
\ProgramData\GrayMatter Software\PDF Broker 5) to be seen by the PDF Broker software.
The License tab is used to display the details of the license in use by the software. The Import
Key button allows you to locate a license key file to be copied to the application data folder.

PDF Broker Settings application window on License tab

Start Date

This is the first day that the ScriptServer PDF Broker software will run.
Expiration Date

This is the last day that the PDF Broker software will run.

MAC Address

This is the hardware address of the Ethernet network interface card.

Units (Routers)

This controls the maximum number of routers that will be enabled by the PDF Broker service.
Modules

This is a list of three-character module codes in the license, separated by commas.

License Key

The license key is an encrypted checksum that verifies the other information on your license key.
Import Key Button

A license key can be entered manually or imported from a license file, which has a .slky
extension.

Chapter 4: Routers

4
The main window of the PDF Broker Settings application displays a summary of the currently
defined routers, which describe how you want PostScript files to be processed as they arrive over
the network.

modified router

selected router

router error

service status

The checkbox in the Enabled column must be checked for a router to be activated. The
Router column provides a brief description of the routers function, and the Using column
indicates the TCP/IP port number or PostScript comment used by this router.

4.1 Creating Routers

To create a new router, choose Add from the Router menu, or right-click in the window and
choose Add. To modify an existing router, click on the router to select it, then choose Edit
from the Router menu (or simply double-click on the router). The routers in the list can be
reordered by selecting a router, then selecting Move Up or Move Down in the Router menu.
Changes to router settings are not saved until you exit the program or use the Save Router
Changes command in the File menu. As a visual reminder that there are unsaved changes, routers
that have been modified are indicated by a small yellow dot in the Status column. If you decide
not to commit changes that you have made before saving changes, use the Revert to Saved
Routers command in the File menu.
The Service menu allows you to manipulate the service state without having to open the Services
administrative tool. The current state of the ScriptServer PDF Broker service is displayed at the
bottom of the window.

4.2 About Routers

Routers are used to describe how you want a particular type of incoming print data to be
manipulated. You can create two types of routers:
port-based routers perform actions based on the port number on which
the PostScript print data is received.
comment-based routers perform actions based on the values of
PostScript comments contained within the PostScript data received. Jobs
of this type are received on the general service port number (8899 by
default)

!
The Edit Router window showing a port-based router

When ScriptServer PDF Broker starts receiving a print job, it parses out the PostScript comments
(if any) that it sees in the PostScript header. It then scans the list of active routers, looking for
those whose criteria match the characteristics of the incoming job. During this process it
constructs a list of the matching routers that will be used once the PostScript data has been
convert to a PDF file.
After the conversion process, the action (called the disposition) associated with each of the
matching routers is performed. Note that any number of routers may match a particular incoming
job, allowing you to set up numerous time-saving steps with a single printing process.

4.3 Comment-Based Routers

When you create comment-based routers, you specify which of the supported comments is used
to constitute a match for the router. These PostScript comments are defined in the Document
Structuring Conventions, a specification published by Adobe Systems for standardizing the
content and format of PostScript files.
The comments supported by the ScriptServer PDF Broker software are:
%%Title (the name of the document)
%%For (the person that created or printed the document)
%%CreationDate (the date that the document was created)
%%Creator (the application that was used to print the document)
%%Routing (routing information)
%%SSV_UserData (not part of the Adobe specification)
%%SSV_SplitField (not part of the Adobe specification)
%%SSV_PassthroughField (not part of the Adobe specification)

 %%SSV_Queue (the ScriptServer queue name; not part of the Adobe specification)
%%SSV_Form (the ScriptServer form name; not part of the Adobe Specification)
These comments define a character string that is used by the ScriptServer PDF Broker software
for comparison to values that you provide when setting up a comment-based router. They are
also provided as placeholders, which may be used in a router definition to use the data provided
by the comment. For example, the $title placeholder refers to the value of the %%Title comment.
See the Placeholder section below for further information.

A Comment-Based Router

In this example, the router will place the PDF files created from PostScript files that have a title
comment (%%Title) that contains Invoice into the archive Invoices.

4.4 Dispositions
After conversion to PDF, the actions associated with the routers that match the job are
performed. First, the PDF file must be given a meaningful name, which can be one of the
following as specified in the router:
document title (from the %%Title comment)
the current date and time
a fixed name
One of the following actions can be associated with a router to be performed on the PDF file:
e-mail
copy to a particular folder
post-processing (using a DOS command or batch file)
archive (see the following chapter)

4.5 Router Options

Clicking the Router Options button at the bottom of the window displays the Router Options
window, allowing you to set advanced properties for this router.

Router Options Window

Generate passthrough data checkbox

This allows you to specify values for passthrough fields that can be referenced using the
$passthrough placeholders. These can be used to extract data from the print job to manage the
disposition of the router. In the example here, it creates the placeholders $passthroughname1
with a value of CustomerName and $passthroughvalue1 with the result of a table lookup of the
documents title. See the discussion of placeholders later in this chapter for more information.
Note that since router-based passthrough data is processed at the start of a job, the file-related
placeholders ($ps, $pslong, $pdf, $pdflong) cannot be used in router-based passthrough
references.
Terminate router scan on match checkbox

This checkbox is used to prevent the PDF Broker service from scanning beyond this router for
further matches.

4.6 E-Mail Options

If you are using an e-mail disposition, you have fine-tuned control over how the message is sent
using the E-Mail Options window allowing you to specify values that will be used for messages
sent using this router, including sender name, subject line, CC, Bcc, and the body of the message.

!
E-Mail Options Window

All fields support placeholder substitution (see below). If a fields value is (use default), the
default broker-wide values are used, which are established in the Edit Settings > Email tab from
the router list window. The example above demonstrates the substitution of a purchase order
number, which is presumed to be the title of the document, for the $title placeholder in both the
subject line and the body of the message.

4.7 Importing and Exporting Routers

Router definitions (of either individual routers or all defined routers) can be exported to an XML
file, which can be used for backup purposes or to transfer routers between PDF Broker
installations. The settings that are exported are those in the current (perhaps unsaved) state of the
routers.
To export all router definitions, use the Router > Export > All Routers command. You will be
prompted for the name and location of the file to be created. To export one router, select the
router you wish to export and use the Router > Export > Selected Router command.

4.8 Placeholders
When creating dispositions for routers, it may be convenient to refer to the values that are used
by ScriptServer PDF Broker software so that they can be used in e-mail messages or MS-DOS
batch command files (see example above).
ScriptServer PDF Broker uses placeholders as a way to refer to these values. The PostScript and
PDF files and each of the comments for a job can be referred to using the appropriate
placeholder:

$ps the PostScript filename in 8.3 format

$pslong the PostScript filename in long format
$pdf the PDF filename in 8.3 format
$pdflong the PDF filename in long format
$for the value of the %%For comment
$title the value of the %%Title comment
$creator the value of the %%Creator comment
$creationdate the value of the %%CreationDate comment
$routing the value of the %%Routing comment
$userdata the value of the %%SSV_UserData comment (see below)
$userfieldn substrings of the $userdata comment, delimited by |
$passthroughfieldn the name of the nth passthrough field
$passthroughvaluen the value of the nth passthrough field
$passthrough(name) a function that returns the value of a placeholder by name
$splitfieldname the name of the TransFormat split field (see below)
$splitfieldvalue the value of the TransFormat split field
$lookup(table,value) the result of a data lookup
$queue the name of the ScriptServer queue that printed the file, if applicable
$form the name of the ScriptServer form that the file was printed on, if applicable
$field a function to extract a substring from a string (see below)

Placeholders can be used to refer to the value they represent in any e-mail field, such as the
subject line or the body of the message. They can also be used in the post-processing command
line.
For example, suppose you want to set up routers that e-mail the PDF file to someone and to print
it to a network printer. You can set up the e-mail router so that the subject line informs its
recipient of the document name using the subject Attached is the $title document. The $title
in the subject line will be replaced with the value of the %%Title comment found in the
PostScript file. The second router that performs the printing could define the post-processing
command as:
lpr P lp S laser1.mydomain.com $ps
The $ps in the command will be replaced by the name of the PostScript file when the
command is executed. The P and S options tell lpr the printer name and address of the server.
The $ps placeholder gives it the name of the file to print.
The Edit menu (in both the Edit Router and Email Options windows) contains an Insert
Placeholder command as a convenience for insert placeholders.
Using the $field placeholder

This placeholder function allows you to extract substrings from another string, such as those
referred to by placeholders. Its format is:
$field(string,delimiter,occurrence)

Where string is the source string, delimiter is the character that separates substrings, and
occurrence is the field number to extract. This is convenient for extracting information encoded
in a filename. For example, suppose a printed document is named PO_180338_73620_1.TXT. In
this example 180338 is a P.O. number and 73620 is a vendor number. The P.O. number
could be extracted from the filename as follows:
$field($title,_,2)

Note that for the placeholder to be parsed correctly, if the string or delimiter contains commas or
parentheses, it should be enclosed in double-quote characters.

4.9 The Special-Case Router

The %%Routing comment is part of the Document Structuring Conventions for exactly such a
purpose as that being used by ScriptServer PDF Broker software: to provide a destination for the
document to be routed to. As such, it can be used to identify the destination e-mail address used
by the ScriptServer PDF Broker with the special-case router.

!
A Special-Case Router

The special-case router is a comment-based router, which is based on the comment %%Routing,
which has a non-blank value. This is the only situation where a comment can be compared to a
non-blank value. When creating a router with these criteria, the e-mail destination of the
disposition becomes the $routing placeholder, indicating that the value of the %%Routing
comment will be used.

4.10 Using Post-Processing Commands

Post-processing commands can be of two general types: an MS-DOS command, such as COPY,
or a command line application that performs a particular task with the files or comment-based
data generated by the ScriptServer PDF Broker, which is available by way of placeholders.
Generally, there will be a command/application name portion of the command and a portion that
specifies the parameters to pass as arguments to the application or command.
If the post-processing command is a command line application whose path contains a space
character, the path must be enclosed in double-quotes to ensure correct parsing. For example, this
command could be used for a command line application that archives the PDF file:
C:\Program Files\Archiver\archivedoc user=$for date=$creationdate $pdf

Note: For security purposes, ScriptServer PDF Broker software does not perform placeholder

substitution on the command or application name portion of the post-processing command; only
the parameters can contain placeholders. Also note that the working directory used during the
processing of the command is the work folder as specified in the PDF Broker Settings
application.

4.11 The %%SSV_UserData Comment

The %%SSV_UserData is a non-DSC compliant comment created by GrayMatter Software for
compatibility with the ScriptServer Printing Systems. It allows users of ScriptServer PAN
(version 1.5.2 and later) and ScriptServer for OpenVMS to pass arbitrary data to ScriptServer
PDF Broker from the command line.
This can be very powerful when used with the routing options supported by these printing
systems in conjunction with the special-case router. It allows you to provide e-mail destination
information (via the routing option) and to provide additional comments (via the userdata
option) in a single command. When coupled with the electronic forms capabilities of these
printing systems, it provides an end-to-end solution for creating business documents (such as
POs and invoices), merging them with text (or PostScript) files, converting them to PDF, and
delivering them to their intended recipients with a single command.
To use the UserData feature using ScriptServer PAN, you use the userdata option on the panpr
print job submission command. For example, suppose you have a text file (named inv11223.txt),
which contains invoice data to be merged with an electronic invoice form (named inv), converted
to PDF, and sent to the address sjones@herdomain.com, and you want to include a phone
number for calling you if there are any questions regarding the invoice. With a special-case
router set up on PAN queue broker, you could use the command (broken into two lines):
# panpr -form=inv -queue=broker -routing=sjones@herdomain.com
-userdata=Please call (206) 555-1001 if you have any questions. inv11223.txt

To use the UserData feature with ScriptServer for OpenVMS, you use the special parameters
ROUTING and USERDATA with the PRINT command on the DCL command line. Using the
previous example, the command would be:

$ PRINT /FORM=INV /QUEUE=BROKER /PARAM=(ROUTING=sjones@herdomain.com, -

$_ USERDATA=Please call (205) 555-1001 if you have any questions.) INV11223.TXT

These examples illustrate the use of a special-case router that has the placeholder $userdata in
the message text definition.
User Data Fields

In some circumstances, it may be necessary to pass multiple strings to be used in various

locations in the disposition of a router. So that multiple pieces of information can be passed using
the %%SSV_UserData comment, it can be broken into up to nine fields using the $userfield1 $userfield9 placeholders. These placeholders are delimited by the vertical bar, or pipe,
character (|).
For example, if the %%SSV_UserData comment contains the string:
Betty Jones|(555)243-7208

then the substitution string for the $userdata placeholder would be the entire string Betty Jones|
(555)243-7208. The substitution string for the $userfield1 placeholder would be Betty Jones,
and the substitution string for the $userfield2 placeholder would be (555)243-7208.

4.12 TransFormat Split and Passthrough Fields

TransFormat Designer is a separately licensed product that allows you to redesign the way that
text oriented business documents are printed. When used in conjunction with TransFormat-based
projects, the PDF Broker allows a single document to be split into multiple PDF files based on
when the value of a particular field on the page changes.
For example, a batch of statements may be printed, creating a single file containing multi-page
statements of arbitrary length. With the TransFormat Designer application, you describe the type
of data on the page, such as: the customer number appears on line 2, starting in column 65 and
ending in column 74. If the CustomerNumber field is defined as a split field, then as this
TransFormat is being processed by ScriptServer PAN or ScriptServer Core, a new print job is
created when the text in this area of the page changes.
The PDF Broker allows use of the split field name and value in router definitions using the
placeholders $splitfieldname and $splitfieldvalue. For example, you can use the value of the
customer number field as the name of the PDF file created, or it could be used to do a table
lookup for an e-mail address in a post-processing script. You can also define comment-based
routers that are invoked when a print job is split on a particular field name.
TransFormat projects also provide the ability to define up to five passthrough fields, which are
fields whose values are passed to PDF Broker and made available through $passthroughnamen
and $passthroughvaluen placeholders, where n is a value from 1 to 5. For example
$passthroughvalue1 is the value of the first passthrough field. Passthrough fields can also be
referenced by name using the $passthrough(name) placeholder function, which may be useful
when you are unsure of the order of passthrough fields.

Both split fields and passthrough fields are handy ways to transfer information to the PDF
Broker to do data lookups in the PDF Broker Lookup Database. See chapter 8 for a discussion of
the data lookup feature in PDF Broker software.
As of version 4.4 of PDF Broker software, you can now associate passthrough data with routers
using the Router Options window.

Chapter 5: Archiving

5
ScriptServer PDF Broker 4 introduces the archiving disposition as a fourth alternative for
electronic distribution of the PDF files created. Archives are created in the PDF Broker Settings
application using the Data > Archives > New... menu command.
To enable archiving, simply create a router that uses the disposition place file in archive, then
select the name of the archive in the pop-up menu.

5.1 Archive Properties

PDF Broker archives can have one of four organizations:
flat - all documents are placed in a single folder
yearly - documents are placed in a subfolder in the archive that is named for the year the
document is archived, e.g. archive-name\2015.
monthly - documents are placed in a subfolder that is named for the month and year the
document is archived, e.g. archive-name\2015\11.
daily - documents are placed in a subfolder that is named for the day, month, and year the
document is archived, e.g. archive-name\2015\11\25.
An archive can be created as read-only, meaning that the documents stored there cannot be
modified in-place. However, documents in a read-only archive can be extracted to a folder
outside the archive and edited there.

5.2 On-Disk Structure

The top of the archives tree is the Archives folder in the PDF Brokers application data folder. In
a default installation on Windows 2003 Server, this will be:
C:\Documents and Settings\All Users\Application Data\GrayMatter Software\PDF Broker Persistent
Data\Archives

On Windows 2008 Server and later, the default archives folder will be:
C:\ProgramData\GrayMatter Software\PDF Broker Persistent Data\Archives

As archives are created, the top level folder for the archive is stored in this folder, and archive
subfolders are created automatically as needed. The database file is Archives.sqlite in the
archives folder.
As documents are archived, they are assigned a unique ID based on the current date. The PDF
files themselves are stored using the unique ID as the filename, and are stored in proper
subfolders in the archives folder. The information associated with the PDF file, known as
metadata, is stored in the archives database along with a preview image of the first page of the
document.
This organization allows the actual documents within archives to be manipulated using standard
file manipulation commands and utilities. The documents can also be backed up based on their
dates, and obsolete documents can be physically deleted.

5.3 Archive Metadata

As documents are archived, the PDF Broker service stores the following information in the
archives database associated with each document:
name - the name the PDF Broker would have given the file if a non-archiving disposition had
been used
title - the value of the %%Title comment, like the $title placeholder
archive date
path - location of the PDF file on disk
preview - a PNG-based image of the first page of the document
creator - the value of the %%Creator comment, like the $creator placeholder
creation date - the value of the %%CreationDate comment, like the $creationdate placeholder
for - the value of the %%For comment, like the $for placeholder
split field name and value, like the $splitfieldname and $splitfieldvalue placeholders
passthrough field names and values, like the $passthroughname and $passthroughvalue
placeholders
IP address - the TCP/IP address of the computer that sent the file to the PDF Broker
router name - the router that was used to archive the document

 user data - the value of the %%SSV_UserData comment, like the $userdata placeholder
routing - the value of the %%Routing comment, like the $routing placeholder
queue - the name of the ScriptServer PAN queue that generated the print data (where
applicable)
form - the name of the ScriptServer PAN form used to generate the print data (where
applicable)

5.4 Creating Archives

Archives are created using the PDF Broker Settings application. Select Archives -> New... from
the Data menu to create an archive. The following window is displayed:

!
With the exception of document previews, the properties on this window cannot be changed once
the archive has been created. To save disk space, document previews can be removed from an
existing archive using the Archives Database Updater utility.
Clicking the Next > button brings up the Archive Security window:

!
Archive Security Models

PDF Broker Archives are created using one of three security models: password-only, local
administrators, and Active Directory. All three security models support password-based access to
the contents of archives. The local administrators security model supports access to local
administrators without having to provide a password. The Active Directory security model
provides access to those Active Directory users and groups that have specifically been
authorized.
To authorize a particular user or group, select the user or group on the left hand pane and click
the Add button. To toggle the display between users and groups, click the Display Users/Groups
button. In the above example, a group named PDF Broker Archive Users has been created by the
Active Directory administrator for the purpose of controlling access to the contents of the PDF
Broker Archives. With a setup like this, users can be added and removed from this group as
needed without having to modify archive security settings.

5.5 Browsing the PDF Broker Archives

The contents of the PDF Broker archives can be browsed using the PDF Broker Archives
application. This application is distributed both with the PDF Broker software and as a
standalone installer that is available free of charge. When installed as part of the PDF Broker
software it is available in the Start menu under the PDF Broker group. When installed using the
standalone installer, it is in its own group in the Start menu.

5.6 Accessing the Archives Remotely

The PDF Broker Archives application can be used to access the contents of archives over a TCP/
IP network.This application is distributed free of charge. It is installed with PDF Broker, and is
also available as a standalone installer for installation on client computers.
The standalone installer is available at:
ftp://ftp.graysoft.com/pdfbroker/PBA_V5_0_0.exe
Documentation for the PDF Broker Archives application is separate from this document and may
be found in the Start Menu in the PDF Broker 5 folder.

5.7 Archive Authentication

All PDF Broker archives have a read and (unless it is a read-only archive) a write password.
When the PDF Broker Archives application starts up, it authenticates the user against each
archive. If the user doesnt authenticate against an archive, the archive name is displayed in gray.
If the user tries to open a grayed-out archive, they will be prompted for a read (and optionally a
write) password. The password prompting window has a checkbox that allows the password to
be stored in the users PDF Broker Archives preferences file. If checked, the password is stored
encrypted using a user-specific encryption key. The next time the PDF Broker Archives
application is run by that user, they will authenticate for the archive automatically.

5.8 Removing Documents from the Archives

To delete a document from an archive, select the document in the documents listing then click
the Locate tool in the toolbar. This will display the contents of the archive directory containing
the document. Delete any unwanted document files by dragging them to the recycle bin or rightclicking and selecting Delete from the popup menu.
The archives database will still contain a reference to the deleted files, called an orphan. To
remove the orphan(s) from the database, select Check for Orphans... from the Data > Archives
submenu. A window will open that contains a list of all documents for which there is no longer
an associated PDF file. Click the Remove button to remove a selected orphan or Remove All
to remove all of the orphans from the database.

5.9 Moving the Archives to a Different Location

In its default configuration, the PDF Brokers Archives folder is located in the application data
folder determined by the version of the operating system. In Windows Server 2008 and later
versions of Windows, this is a subfolder in the (hidden) folder at C:\ProgramData. The full path
is:
C:\ProgramData\GrayMatter Software\PDF Broker Persistent Data\Archives

On earlier versions of Windows, the path to the archives folder is:

C:\Documents and Settings\All Users\Application Data\GrayMatter Software\PDF Broker Persistent
Data\Archives

In some cases, it may be desirable to have the archives reside on a different disk or in some other
location. Moving the archives consists of the following steps:
1.
2.
3.
4.

stopping the Archives Server and the PDF Broker service

copying the archives to the new location
changing the archives location in the PDF Broker Settings application
restarting the Archives Server and the PDF Broker service

To change the location (step 3) of the archives, select Archives > Change Location from the
Data menu in PDF Broker Settings. In the resulting file selection window, navigate to the new
archives folder location, and select the Archives.sqlite database file.

Chapter 6: Security Profiles

6
ScriptServer PDF Broker uses security profiles to control what can be done with the PDF files it
creates. A security profile contains a modify password, an open password, and a set of
permissions that control access to the document when it is opened by a PDF viewing application,
such as Adobe Acrobat, Adobe Reader, or Apples Preview utility.
The modify password can be thought of as the owners password to the file. It is required to
change the permissions associated with the PDF documents created with the profile. It is a
required element of the profile because it is used as part of the encryption key. (ScriptServer PDF
Broker always uses 128-bit encryption when profiles are used.) When a PDF file is accessed with
the modify password, the permissions do not apply.
The open password can be thought of as the end-users password to the file. If present in a
profile, will be required to view the contents of the PDF documents created with the profile.
The permissions apply to end-users (viewers) of the PDF document. They control the access to
the contents of the PDF documents created with the profile as follows:

Permission

Meaning

Allow printing

document can be printed

Allow extraction of text and graphics

text and graphics in the document and be selected

and extracted using operations such as Edit > Copy

Allow modification

the contents of the document can be changed, except

as provided by the permissions below

Modify annotations and form fields

add or modify text annotations (comments), fill in

interactive form fields, and if Allow modification is
enabled, create of modify interactive form fields

Allow interactive form fill-in

fill in existing interactive form fields, even if

Modify annotations and form fields is not allowed

Allow inserting, deleting and rotating allows document assembly changes, including
pages
adding, deleting, and rotating pages, creating
thumbnails, and creating bookmarks, even if Allow
modification is not enabled
Allow access for users with disabilities

allows text and graphics to be extracted in support of

accessibility to users with disabilities or for other
purposes, even if Allow extraction of text and
graphics is not enabled

The PDF Broker Settings utility is used to manage your security profiles. To create a profile, use
the Edit > New Security Profile command. It will prompt you for a profile name, and then
display the profile editing window:


Security Profile Editing Window

Once a profile has been created, it can be associated with a router. To associate a router with the
profile, double-click the desired router, then select the profile from the Security Profile pop-up
menu:

Setting the Security Profile on a Router

Security profiles are stored in the Windows registry. When you change a profile, the registry is
updated immediately. If the ScriptServer PDF Broker service is running and you want the to start
using the new or modified profile immediately, it must be re-initialized using the Service >
Reinitialize command.

Chapter 7: PDF Broker Assistant

7
The PDF Broker Assistant is a Windows taskbar application that provides convenient display of
the status of the PDF Broker service and one-click access to controlling the service and PDF
Broker settings.
The PDF Broker Assistant is an icon in the lower right corner of the display, showing an icon and
a colored bubble that indicates the current service status.

!
Assistant Icon in Task Bar

The PDF Broker Assistant provides a context-sensitive menu that is displayed by right-clicking
on its icon in the task bar. The commands that are available in the menu will change depending
on the current state of the service.

!
The Assistants Contextual Menu

Mousing over the Assistants icon in the taskbar provides a text description of the services status
in a tooltip:

!
Assistants Service Status Tooltip

The icon in the task bar changes according to the current state of the service. The following table
lists the meanings of the various icons:

Service is idle
!

Service is processing a job

!

Service has been paused

!

Service has been stopped

!
!

Service state cannot be determined

Automatically Starting the Assistant

The Assistant program is named pdfbrokerassistant.exe, and is located in the directed created
when the software is installed. By default, the full path is:
C:\Program Files\GrayMatter Software\PDF Broker\pdfbrokerassistant.exe

During installation of ScriptServer PDF Broker software, a shortcut (.lnk file) is automatically
placed in the Startup directory of the installation account, e.g.:
C:\Documents and Settings\Administrator\Start Menu\Programs\Startup

To automatically start the Assistant in another account, make a shortcut in its corresponding
Startup folder using option-drag.

Chapter 8: Data Lookup

8
8.1 Introduction
PDF Broker has the ability to import data into a database for subsequent lookup by router
processing. Comma-separated value files (.csv) can be imported using the PDF Broker Settings
application. The information is saved into a table in the PDF Broker Lookup Database.
You can then define lookups, which identify a table in the database, the column to be used to
lookup a value, and the column containing the value to be returned. This provides a method to
use information contained in a placeholder, such as the username in the %%For comment (the
$for placeholder), to return other information, such as the email address for that user.
Lookups are also very useful when used in conjunction with a TransFormat project that defines a
field, such as Customer ID, that is used as a passthrough field. Up to three passthrough fields can
be made available as placeholders in a PDF Broker router using the $passthroughvalue1,
$passthroughvalue2, and $passthroughvalue3 placeholders.
TransFormat projects can also define a split field, which is used to break a multiple-document
batch print job into individual PDF files with PDF Broker. As with any placeholder, the split
field can also be used as an argument to a lookup using $splitfieldvalue.
Lookups are performed within the PDF Broker using the $lookup placeholder, which is in the
format:
$lookup(lookup-name,key-to-lookup)

where lookup-name is the name of a lookup that has been created in the PDF Broker Settings
application, and key-to-lookup is the value to be looked up in the table, generally a placeholder.

8.2 Importing Data

Comma-separated value (.csv) files can be imported into the PDF Broker Lookup Database using
the PDF Broker Settings application. In the Data menu, select Import from CSV file.... Browse
to the file to import and click the Import button. The first 25 lines from the CSV file will be
loaded and displayed in the Import dialog:

!
Import CSV file Dialog

The CSV file format supports the ability to use the first line of the file as column headings. If this
is the case, check the First row is column headings checkbox.
By selecting a Primary key for the table, you can optimize lookups based on that key. In the
example above, it is likely that the first column, User Name, will be used as the lookup column,
so it is a good candidate for the primary key. The constraints on the Primary Key are established
using the checkboxes Must be unique (can only occur once in the column) and Must not be
null (must have a value).
Constraint handling determines how records that cause errors during import will be handled.

Setting

Behavior

replace and continue

the new record (with a non-unique or null value) supersedes the

existing row in the table and the import continues

ignore and continue

the new record (with a non-unique or null value) is ignored and the
import continues

abort and keep changes

the import is aborted and the records that were imported will be
kept in the table

abort and rollback

the import is aborted and the database is rolled back to its state
before the import

Re-Importing Data

You can re-import data from files that have been updated with modifications since the previous
import. When a file is first imported, the location and name of the file that was imported is stored
in the lookup master database. When you use the Data > Re-Import Lookup Data > {table-name}
command, the application will attempt to open the same file as the original import. If it exists, it
will confirm that you want to re-import the data from the same file, or give you the opportunity
to specify a different file to import. If the original file doesnt exist, you will have a chance to
specify a different file to import, or to cancel the operation.

8.3 Viewing Database Tables

Once a CSV file has been imported into the PDF Broker Lookup Database, you can view the
tables that have been imported with the Data > Tables and Lookups command. This displays a
list of the tables currently in the database.

!
Displaying Tables in the Lookup Database

The data in a table can be reviewed in the Contents tab. Select the table to be viewed in the popup menu at the bottom of the window to view its contents.

!
Lookup Table Contents Display

8.4 Defining Lookups

Once the contents of a CSV file have been imported into a table, you can create lookups that can
be used in routers. Create a new lookup by selecting the Contents tab and clicking the New...
button, which displays the Create Lookup window.

!
Edit Lookup Window

Select the table that the lookup is to be performed on, the Key Column that is searched for the
value, and the Return Column for the value to be returned. The behavior when a lookup error
occurs is controlled at the right of the window.

8.5 Sample Lookups

Example: Email Address from Username

Take an example where the e-mail destination for a router needs to be lookup up in a table
containing user information. The Microsoft Windows printer driver for PostScript printers will
automatically place the username of the user printing a document in the %%For comment of the
PostScript header. This makes it available to routers as the $for placeholder. Once the user
information has been imported into the PDF Broker database, the lookup user-email was created
to return an email address from the username. In the disposition for the router to process these
jobs, the email destination address is set to the value:
$lookup(user-email,$for)

Example: Email Address from TransFormat Project

In this example, consider a batch print job of monthly statements that are created on a legacy
system and printed to a ScriptServer PAN system implementing a TransFormat resource in a
PAN form. This TransFormat project defines a field named CustomerID, which always appears
in a fixed location on the page. Since this is a batch print job, it contains all of the statements for
each of the customers and needs to be split into separate PDF files to be emailed by PDF Broker.
The CustomerID field is defined as the TransFormat split field for this purpose. As it is being
processed by PAN, when the value of the CustomerID field changes (i.e. one customers
statement ends and the next one begins), PAN starts a new print job to the PDF Broker. As with

passthrough fields, split fields are made available to PDF Broker software as a comment in the
PostScript header generated by PAN, which is in turn made available as a placeholder to PDF
Broker routers.
The PDF Broker software must now convert the CustomerID fields value to an email address.
The value of the CustomerID split field is available to the router as the placeholder
$splitfieldvalue, which must be looked up in the Customer table in the PDF Brokers Lookup
Database. In this example, $splitfieldvalue is looked up in the Customer table using the lookup
Customer-email, which returns the email address. In the disposition for the router to process
these jobs, the email destination address is set to the value:
$lookup(Customer-email,$splitfieldvalue)

Chapter 9: Administrative Tasks

9
The ScriptServer PDF Broker is managed using the standard Windows programs in the
Administrative Tools menu. The Services program may be used to view the current state of the
service, and to start, stop, pause, and resume it. (Note that these functions can also be performed
from the Service menu in the PDF Broker Settings application.) The Event Viewer program is
used to view any messages generated by the ScriptServer PDF Broker service.

9.1 Controlling ScriptServer PDF Broker with the Services Tool

The Services administrative program is found in an Administrative Tools sub-menu of the Start
menu. When it is installed, the ScriptServer PDF Broker service is configured to start
automatically on system start-up. If you want to stop, start, pause, or resume the service, start the
Services tool, scroll down to the ScriptServer PDF Broker entry, click on it, and use the tools
at the top of the window (or right click for a pop-up menu) to change its state.

!
The ScriptServer PDF Broker Service in the Services Administrative Tool

9.2 Viewing ScriptServer PDF Broker Logfiles

PDF Broker services creates logfiles in a Logs subdirectory of the PDF Broker application data
folder located at:
C:\ProgramData\GrayMatter Software\PDF Broker 5\Logs
The system creates four logfiles per day:
PDF Broker job log (brokerjobs-yyyy-mm-dd.log where yyyy-mm-dd is the date stamp)
contains contains an entry for each job serviced by the PDF Broker. This log is in CSV
format for easy access by spreadsheet applications.
PDF Broker error log (brokererror-yyyy-mm-dd.log where yyyy-mm-dd is the date
stamp) contains all information logged by the PDF Broker service that was formerly logged
to the Windows Event Log.
PDF Broker Archives error log (archiveerror-yyyy-mm-dd.log where yyyy-mm-dd is the
date stamp) contains all information logged by the PDF Broker Archives server.
PDF Broker Archives access log (archiveaccess-yyyy-mm-dd.log where yyyy-mm-dd is
the date stamp) logs every access to a document in an archive. An access is considered
any operation by a PDF Broker Archives client that allows the contents of a PDF file in the
archives to be viewed, including Open, Extract, and Preview operations. This log is
in CSV format for easy access by spreadsheet applications.

9.3 ScriptServer for OpenVMS Compatibility

Configuring ScriptServer for OpenVMS Queues to Use ScriptServer PDF Broker

ScriptServer PDF Broker software will work with all versions of ScriptServer for OpenVMS
when used with port-based routers. ScriptServer for OpenVMS version 6 has modifications to
generate DSC-compatible PostScript comments and is required to be compatible with commentbased routers.
To create a ScriptServer for OpenVMS queue that sends PostScript data to the ScriptServer PDF
Broker, it must be created:
to send to the port used by the intended router(s) or the default service port (8899 by
default)
backchannel must be disabled
PCL support must be set to none
TCP/IP protocol should be set to HP
Setting Up ScriptServer for OpenVMS V6 Compatibility

In version 6 and later, all of the settings required can be configured with the "BROKER" network
protocol, which will configure all of the above settings with one logical name. For example, to
configure the a queue to send data to a ScriptServer PDF Broker running on a machine at address
10.0.0.1, define the logical name:
$ DEFINE/SYS SSV$10.0.0.1_TCPIP_PROTOCOL BROKER

Version 6 also allows you to specify a port number in the /ON qualifier of the INIT/QUEUE and
START/QUEUE commands. (Prior versions required you to define a TCPIP_PORT logical
name; see below.) For example:
$ INIT/QUEUE/PROC=SSV$SMB/LIBR=SSV$DEVCTL/ON="10.0.0.16:9110" MYQUEUE

Setting Up ScriptServer for OpenVMS V5.1 & Earlier Compatibility

In earlier versions, you must set up the individual logical names to make a queue compatible
with ScriptServer PDF Broker. The following DCL commands show a sample queue named
PDFROUTE1 being created to send data to a router that is setup to listen on port 9112 on the
Windows Server running ScriptServer PDF Broker at IP address 192.1.1.12:
$ DEFINE/SYS SSV$192.1.1.12_BACKCHANNEL_SUPPORT FALSE

$ DEFINE/SYS SSV$192.1.1.12_PCL_SUPPORT NONE

$ DEFINE/SYS SSV$192.1.1.12_TCPIP_PROTOCOL HP

$ DEFINE/SYS SSV$192.1.1.12_TCPIP_PORT 9112

$ INIT/QUEUE/START/ON="192.1.1.12"/PROC=SSV$SMB -

$_ /LIBR=SSV$DEVCTL PDFROUTE1

Using the ScriptServer PDF Broker PRINT Parameters

If you want to be able to use comment-based routers with ScriptServer OpenVMS, version 6 is
required. This version provides the following additional support for ScriptServer PDF Broker:
$ PRINT/PARAM=ROUTING="router-data" myfile.txt

This parameter allows you to pass routing information directly to ScriptServer PDF Broker in the
form of a "%%Routing" PostScript comment. With a suitably configured router (i.e. "Incoming
data has the comment %%Routing which is not blank" and "e-mail the file to [ Routing
destination ]"), you can specify the e-mail address for the ScriptServer PDF Broker to send the
PDF file to.
$ PRINT/PARAM=USERDATA="userdata" myfile.txt

This parameter allows you to pass user-defined information directly to ScriptServer PDF Broker
in the form of a "%%SSV_UserData" PostScript comment. This is a ScriptServer-specific
PostScript comment designed to provide information as a placeholder. The placeholder $userdata
can then be used in e-mail subjects, body text, or as parameters to a post-processing command.
Using Both PRINT Parameters Simultaneously
To conform with DCL parsing rules, when you want to use both the ROUTING and USERDATA
parameters, you must use parentheses to enclose the list and commas to separate. For
example:
$ PRINT/PARAM=(ROUTING="jdoe@mydomain.com",USERDATA="Call me at 555-9876.") myfile.txt

9.4 ScriptServer PAN Compatibility

ScriptServer PAN system can be configured to use ScriptServer PDF Broker software in two
ways: as a document distribution service (router mode) and as the PDF conversion tool (client
mode), .
Configuring PAN Queues to Use ScriptServer PDF Broker (Router Mode)

To create PAN queues for processing by ScriptServer PDF Broker in router mode (PAN version
1.5.2 and later):
Log onto the PAN browser interface (this will require the Administrator privilege).
Navigate to the queue creation screen (PAN Administration > Manage queues > Create
queue).
After providing a name for the new queue, set Communications style to PDF Broker
This has the following effect (which must be set manually on prior versions, as follows):
set Color support to Yes
set Duplex support to No
set PS support to Level 3

 set PCL support to None

uncheck the backchannel enabled checkbox
uncheck the web access supported checkbox
After entering the IP address of the Windows computer running ScriptServer PDF Broker
software, enter the appropriate port number. If you are configuring for a port-based router, enter
its port number in the IP Port field, otherwise use the default service port for ScriptServer PDF
Broker (8899 by default.)
Using ScriptServer PDF Broker to Convert Files for PAN (Client Mode)

The ScriptServer PAN Printing System (version 1.4 and later) has a built-in ScriptServer PDF
Broker client. To configure ScriptServer PAN to use ScriptServer PDF Broker whenever it needs
to create a PDF file, stop ScriptServer PAN in the browser interface (PAN Administration >
Utilities > Start/stop PAN), then open the configuration screen (PAN Administration > Utilities >
Configuration).
Near the bottom of the screen you will find a pop-up menu for PDF Conversion Mode. Select
PDF Broker in this menu, and set the PDF Broker Host field to the TCP/IP address of the
Windows computer running the ScriptServer PDF Broker service. If ScriptServer PDF Broker is
configured to use a non-standard TCP/IP port (in the PDF Broker Settings application), enter the
value in the port number in the PDF Broker port field.

!
ScriptServer PAN Configuration screen

Click the Save button to save the changes to the configuration, then restart ScriptServer PAN.

Chapter 10: Creating Desktop Printers

10
ScriptServer PDF Broker is used by creating printer queues that act as though they are
communicating with a TCP/IP-based PostScript printer. In this chapter we will provide step by
step instructions on how to create queues on Windows and Mac OS X. For details on setting up
print queues with the ScriptServer Printing Systems, please see chapter 5.

10.1 Setting Up a Printer on Microsoft Windows XP

From the Start Menu, select Printers & Faxes and then open the Add Printer Wizard

!
Starting the Add Printer Wizard from Printers & Faxes Window

To start, click on the next button and then select Local printer attached to this computer
(Do not check the Automatically detect ... checkbox.)

!
Select Local Printer Option

Check the Create a new port and select Standard TCP/IP Port from the scroll down menu.

!
Create a New, Standard Port

This will open the Add Standard TCP/IP Printer Port Wizard Window. To continue, click on the
Next button.

!
The Add Standard Port Wizard

At this point you need to enter the ScriptServer PDF Broker IP address and the Port Name. A
descriptive naming convention is recommended if you are planning on using a number of routers
performing different tasks. This example uses Broker as a port name and the port that has been
assigned to the broker.

!
Providing IP Address and Port Name

Select Custom device type and click on Settings.

!
Using Custom Settings for the Port

This will present the Configure Standard TCP/IP Port Monitor. On this window:
Select Raw protocol.
Confirm that the Port Name and IP address you set up earlier (step 6) is correct. In this
example we are using port 9100 as the router setting for the task and Printer name or IP
Address for the location of the ScriptServer PDF Broker installation.
To complete, click on the OK button.

!
Providing the Port Number

This brings you back to the Add Standard TCP/IP Printer Wizard. Click Next.

!
Click Next to Complete the Wizard

You have now set-up a ScriptServer PDF Broker printer driver on your workstation. To complete
the set-up, click on the Finish button.

!
Finishing the Add Port Wizard

This will bring up the Install Printer Software window. Select your printer manufacturer and
printer. Note! Make sure that you install the PostScript (not PCL) driver. Click Next. In the
example below we selected HP as the Manufacturer and the HP LaserJet 4/4M Plus PS 600
printer. This will provide a printer driver that outputs PostScript files for the ScriptServer PDF
Broker to convert to PDF files.

!
Selecting a PostScript Printer Driver

At this point a window called Use Existing Driver will open. Select Keep existing driver (the
default and recommended option). Click Next.

!
Keep Existing Driver Screen

It is now time to name the printer. We recommend using a naming convention that describes the
function provided by ScriptServer PDF Broker. Each driver/router performs a specific task and
the name should communicate this task to the users for easy selection. To proceed, click Next.
Note about Printer Sharing: Unless you are an administrator we recommend that you do not
share this printer. If a printer is set up as Shared on a Windows Server it will be available to users
with auto discovery in the Add printer wizard.
At the Print Test Page screen, select YES or NO and then click on Next.

!
Test Page Screen

To complete the install, click on Finish.

Your new ScriptServer PDF Broker printer on port 9100 should now be available in Printers and
Faxes on the start menu. The ScriptServer PDF Broker router is now ready to perform the
specific task it was set-up to do from any application.

!
Completing the Add Printer Wizard

10.2 Setting Up a Printer on Microsoft Windows 7/8

The procedure for setting up a PDF Broker-compatible printer on Windows 7 and Windows 8 are
virtually identical. The process is started from the Control Panel. From the Control Panel, under
the Hardware and Sound heading, click View devices and printers, then click Add a
printer to start the Add Printer Wizard.

!
Starting the Add Printer Wizard

In the first screen (above) of the Add Printer wizard, select Add a local printer and click the
Next button.

!
Choose Printer Port Option

Select the Create a new port option and select Standard TCP/IP Port from the popup menu.

!
Specify TCP/IP Address

The Add Printer wizard then presents the window to specify the TCP/IP address. Enter the
hostname or IP address of the computer running PDF Broker software. Uncheck the Query the
printer ... checkbox.

Windows will then attempt to detect the TCP/IP port. This procedure will timeout after about a
minute:

!
Attempting to Detect the TCP/IP Port

After the wizard times out, the following screen will ask for further information:

!
Providing IP Address and Port Name

Select Custom device type option and click on Settings....

!
Setting the PDF Broker Port Number

This will present the Configure Standard TCP/IP Port Monitor window. On this window:
Select Raw protocol.
Enter the port number for the PDF Broker router you want this Windows printer to
communicate with. In this example we are using port 9110 (the default PDF Broker router
port) as the router to receive print jobs sent to this printer.
Leave the SNMP Status Enabled checkbox unchecked, and click the OK button.

!
Selecting a Printer Driver

This brings you to the window where you must select a printer driver. Select a print driver for a
color-capable PostScript printer. In this example, we are using an HP Color LaserJet 2800
Series PS driver. The PS indicates that this is a PostScript driver.
Next you will provide a name for the new printer and click Next:

!
Provide a Name for the New Printer

You now have the opportunity to specify sharing options for the new printer. If you plan on
sharing this printers with other workstations in your network. select the Share this printer ...
option and specify a Share name for the printer.

!
Specifying Sharing Options

Finishing up, you can select whether you want to set the new printer as the default, and whether
you want to print a test page. If PDF Broker is running and the router associated with this printer
is configured, you should try to print a test page.

Finishing the Add Port Wizard

You have now set-up a ScriptServer PDF Broker printer driver on your workstation. To complete
the install, click the Finish button.

10.3 Setting Up a Printer on Mac OS X

In Mac OS Xs System Preferences panel (Apple menu > System Preferences), select Print &
Fax. Click on the + button to add a new printer.

!
This will start the Print Setup Utility and display the following window:

!
Select these values for the new printer:
in the Protocol pop-up menu, select HP Jet Direct - Socket
in the Address field, enter the IP address of the computer running ScriptServer PDF
Broker software, followed by a colon (:), followed by the port number to use. If this

printer will be sending data to a comment-based router, use the default service port
(8899, by default), otherwise, use the port number of the port-based router
leave the Queue field blank
in the Name field, enter a descriptive name of the router being used
in the Print Using pop-up menu, select Generic PostScript printer