Overview
You can use the priint:comet pdf renderer for rendering pages, exporting PDF documents, create
previews and several more rendering tasks.
Connecting publishing server with priint:comet pdf renderer requires some additional setup steps, which
are described in this document.
Installation hints for priint:pdf renderer
Requirements
These are the minimal versions required to use priint:pdf renderer with the publishing server:
- PublishingServer Version 4.1 >= Build 205
- priint:pdf renderer Version 4.1 >= R10502
Basic Installation
Please follow the installation instruction delivered with your priint:pdf renderer release. This contains detailed information about licensing, configuring fonts and pdf presets ("joboptions") and additional requirements.
For a quick test ater installation, you can just open a terminal or a command prompt, change into the installation directory and type
comet_pdf -s hello
If the basic installation works, this will generate a PDF welcome page and open the system default PDF viewer.
System privileges
Please make sure, that the Java Application Server user (service account or local system account) can access the priint:pdf renderer installation directory. Minimal requirement is read the directory content and run the comet_pdf.exe resp. comet_pdf programm.Depending on the path configuration (see below), you may also have to grant write privileges on this directory (or subdirectories) to this user.
Connecting publishing server to priint:pdf renderer instances
To use the priint:pdf renderer with the publishing server, it first must be configured in the comet_admin database resp. priint:suite administration console.
During installation, you can choose whether to support priint:pdf renderer or not, and choose the number of instances, installation path etc. You can change this configuration later, however some of these settings can only be edited directly in the database and will require a server restart.
Basic configuration
The priint:pdf renderer instances need to connect back to the publishing server (actually to the Comet3 WebService provided by the CometBridge PubServer Plugin), this is a SOAP over HTTP connection.
The callback address and credentials can be configured in priint:suite > Administration > Preferences > AdminDB property.
Furthermore, you can configure some basic settings for all priint.pdf renderers connected to the publishing server.
Settings in this panel:
- Bridge Address: this is the IP or name plus port of the publishing server. This IP or name must be resolveable from the priint:pdf renderer host. The port must accept requests from the priint:pdf renderer host, but should deny requests from other hosts.
- Bridge User: global user name for callback connections. The user must have sufficient privileges to connect to any required Comet project, but should not have any UI privileges.
- Bridge Password: global password for callback connections
- Working Directory: relative or absolute path for log files and cache folders used by priint:pdf renderer, see comments on paths below. This setting applies for local instances only.
- Log Renderer Calls: log commands sent to the priint:pdf renderer and stdout / stderr in the server applicaiton log.
- Write Renderer Logs: let the priint:pdf renderer write log files (comet.log and api.log). Location of the log files is defined by the Working Directory setting. This setting applies for local instances only.
- Synchronize Using PID Files: use this option only, if you encounter synchronization problems (such as priint:pdf renderer has finished a task, but the result files are not accessible for publishing server yet). This setting applies for local instances only.
- Renderer File Type: the type of documents supported on this server. This is a system wide setting and can be either InDesign® Document (.indd) or Comet Interchange Format (.w2ml). For the priint:pdf renderer, this value must be set to Comet Interchange Format (.w2ml).
- Check Renderer File Type: check the renderer file type before processing documents with a certain renderer. Usually this should be set to false.
Note: the latter two settings will most probably be obsolete in the final 4.1 Release. Handling of heterogenous document types is currently being developed, in later versions this will not require any extra configuration.
Note II: by setting Check Renderer File Type to true and configuring both priint:pdf renderer and InDesignServer instances, you can process different document types on the same server at the same time. The alpha and beta Releases of the 4.1 version only support one document type - either InDesign® or W2ML - at the same time, so using different document types is an inofficial feature, which might help you in certain situation, but is not suppoerted by Werk II.
priint:pdf renderer configuration
There should be at least two preconfigured server entries in the priint:suite > Administration > Preferences > AdminDB property > Indesign servers node. Actually we do not configure physical servers here, but only server types (LOCAL, REMOTE). For PDF Renderer, we need a third entry with type PDFRENDERER.
You can check, which server types are configured in the indesignserver table in the comet_admin database (e.g. using MySQL Workbench, Microsoft SQL Server Management Studio or similar tools).
SELECT * FROM comet_admin.indesignserver;should output something like
+----------+----------------+----------------+ | SERVERID | SERVERNAME | SERVERPROTOCOL | +----------+----------------+----------------+ | 2 | Remote Server | REMOTE | | 3 | Offline Server | COMETOFFLINE | | 4 | PDF Renderer | PDFRENDERER | +----------+----------------+----------------+If the PDFRENDERER entry is missing, add it, e.g. using this SQL statement:
INSERT INTO comet_admin.indesignserver (SERVERID, SERVERNAME, SERVERPROTOCOL)
VALUES (4, 'PDF Renderer', 'PDFRENDERER');
You must restart glassfish / publishing servers to see the changes.
priint:pdf renderer instance configuration
By opening the PDFRENDERER server node, you should see instances configured for this server type (see screenshot).
If there are no or not enough instances, you have to add them to the comet_admin.indesignserverinstance table (e.g. using MySQL Workbench, Microsoft SQL Server Management Studio or similar tools).
SELECT * FROM comet_admin.indesignserverinstance;should output something like
+------------+----------+--------------+-------------------+--------+------- | INSTANCEID | SERVERID | INSTANCENAME | ENDPOINT | ACTIVE | TYPEID ... +------------+----------+--------------+-------------------+--------+------- | 7 | 4 | Renderer_01 | local://C:\pdf_.. | 1 | 2 ... | ... | | | | | +------------+----------+--------------+-------------------+--------+-------
To add an instance, type something like
INSERT INTO comet_admin.indesignserverinstance
(INSTANCEID, SERVERID, INSTANCENAME, ENDPOINT, ACTIVE, TYPEID, LOGIN, PASSWORD)
VALUES
(8, 4, 'Renderer_02', 'local://C:\\pdf_renderer\\', 1, 2, '', '');
INSTANCEID must be unique (e.g. SELECT MAX(INSTANCEID) + 1)
SERVERID must be the ID of the PDFRENDERER entry in the indesignserver table.
INSTANCENAME must be unique (see path information above)
Once created, the priint:pdf renderer instances can be configured in the priint:suite administration console.
Settings for each instance are
- Instance name: UI name for this instance, this name must be unique for all renderers running on the same host, because cache and log path are derived from this name
- Endpoint: Service endpoint
The publishing server connects to priint:pdf renderer by executing system calls. Optionally, the publishing server can also connect to a WebService component to call renderers installed on remote hosts. To call priint:pdf renderer, the publishing server needs to know the installation path and the host. This is configured with the serviceendpoint property for each pdf renderer instance:
- Local connections: local://Absolute\installation\path
- Example Windows: local://C:\\comet_pdf\\
- Example Mac: local:///Applications/comet_pdf/
- Remote connections: http://server[:port]/
- Example Windows: http://192.168.130.217:4711/
- Example Mac: http://192.168.130.217:4711/
- Local connections: local://Absolute\installation\path
- Active: whether this instance is active (i.e. should be used) or not
- Type: type / purpose of this instance, see description below
- Login: optional, override the global login (Bridge User) for callback connections.
- Password: optional, override the global password (Bridge Password) for callback connections
Note: using dedicated credentials for each priint:pdf renderer instance can be very useful when tracking problems in the Glassfish / publishing server log file.
priint:pdf renderer instance type or purpose
To seperate long running tasks like generating pages from tasks, which require fast response times, priint:pdf renderer instances can be assigned to a certain type.
- MIXED: this is the default type and allows the instance to be used for any purpose
- JOB: this instance can be used for server jobs, such as page generation and server workflow steps
- WHITEBOARD: this instance can be used for online editing e.g. using the Whiteboard Spread Editor
- PRINTONDEMAND: this instance can be used for API calls from a Java / SOAP client
Which configuration best fits your requirements, depends on the usage scenario: the number of concurrent Whiteboard users, the kind of jobs executed in your system, the number and type of Java clients etc.
You should avoid instances of type MIXED, unless in small installations (only one or two InDesignServer instances) or for testing purposes.
Installation and configuration of remote pdf renderers
Connecting to remote priint:pdf renderers requires an additional server component. This is a very tiny WebService component delivered as an EJB jar file called CometPdfRemote.pdf.
Installation
The WebService component requires a Java EE 6 compliant application server. It's recommended using the same application server like for the PubServer installation.
At the time, this is the Glassfish 3.1.2 Java EE 6 reference implementation.
You can either
- download and install an installation package from the Oracle web site
- use the PubServer installer, choose a minimal setup and remove all installed applications (jars, wars and ears) after installation
- PubServerSDK.jar (shipped with PubServer)
- CometServer4SDK.jar (shipped with PubServer)
- logback-classic-1.1.0.jar
- logback-core-1.1.0.jar
- shiro-all-1.2.1.jar
- slf4j-api-1.7.5.jar
After installing the application server and additional domain libraries, deploy the CometPdfRemote.jar application (using the web administration UI or autodeploy folder).
Configuration
A couple of system properties must be configurd, before you can connect to this pdf remote service.
To do so, open the application server administration UI and navigate to Configurations > server-config > System properties:
At least the following two properties must be set:
- COMETPDF_INSTALLATIONPATH: absolute installation path of PDF renderer, e.g. C\comet_pdf\ or /Applications/comet_pdf/
- COMETPDF_WORKINGDIRECTORY: relative (to installation path) or absolute path for priint:pdf renderer log and cache files, see Sections 5.1 to 5.3 below.
The following two properties are optional:
- COMETPDF_WRITELOGFILES: (true or false), write log files or not. In a productive environment you should disable logging for performance reasons. Default is true.
- COMETPDF_USELOCKFILES: (true or false), whether to use additional files to synchronize pdf renderer program start and termination. Use this option only, if you encounter timing problems in certain envrionments. Default is false.
Paths and folders
You must setup the following paths and folders to use the priint:pdf renderer
Cache Path
This path is used by the priint:pdf renderer to store temporary data (downloaded templates, actions etc.). The name of this folder is derived fromthe instance name and the base Working Directory (relative to the installation directory or absolute path), which you configure in the priint:suite administration panel (see screen shot below).
Directory layout, when using a relative Working Directory path (e.g. "var"):
<PDF renderer Installation directory>
+ var
+ InstanceName
+ XCache
Directory layout, when using a relative Working Directory path (e.g. "D:\data\pdf_renderer\"):
D:\data\pdf_renderer\
+ var
+ InstanceName
+ XCache
InstanceName, in both cases, is the name of this priint:pdf renderer instance as configured in the priint:suite adminstration panel, see Section 3.3 (pdf renderer instance configuration) above. Therefore it is mandatory, that the instance name is unique, otherwise cache and other output of several instances might get mixed up.
Requirements
- must be a folder on the local filesystem
- full read and write access for the priint:pdf renderer user
- must be unique for each priint:pdf renderer instance
- must be excluded from real time virus scanning and the like
Example: var or D:\data\pdf_renderer\
Comet Log
This is the file comet log messages are written to. The name of this file is derived from the instance name and the base Working Directory (relative to the installation directory or absolute path), which you configure in the priint:suite administration panel (see screen shot below).
Directory layout, when using a relative Working Directory path (e.g. "var"):
<PDF renderer Installation directory>
+ var
+ InstanceName
+ comet.log
Directory layout, when using a relative Working Directory path (e.g. "D:\data\pdf_renderer\"):
D:\data\pdf_renderer\
+ var
+ InstanceName
+ comet.log
InstanceName, in both cases, is the name of this priint:pdf renderer instance as configured in the priint:suite adminstration panel, see Section 3.3 (configuring pdf renderer instances) above. Therefore it is mandatory, that the instance name is unique, otherwise log messages of several instances might get mixed up.
Requirements
- must be a file on the local filesystem
- full read and write access for the priint:pdf renderer user
- must be unique for each priint:pdf renderer instance
- must be excluded from real time virus scanning and the like
Example: var or D:\data\pdf_renderer\
Comet API Log
This is the file comet API log messages are written to. The name of this file is derived from the instance name and the base Working Directory (relative to the installation directory or absolute path), which you configure in the priint:suite administration panel (see screen shot below).
Directory layout, when using a relative Working Directory path (e.g. "var"):
<PDF renderer Installation directory>
+ var
+ InstanceName
+ api.log
Directory layout, when using a relative Working Directory path (e.g. "D:\data\pdf_renderer\"):
D:\data\pdf_renderer\
+ var
+ InstanceName
+ api.log
InstanceName, in both cases, is the name of this priint:pdf renderer instance as configured in the priint:suite adminstration panel, see Section 3.3 (configuring pdf renderer instances) above. Therefore it is mandatory, that the instance name is unique, otherwise log messages of several instances might get mixed up.
Requirements
- must be a file on the local filesystem
- full read and write access for the priint:pdf renderer user
- must be unique for each priint:pdf renderer instance
- must be excluded from real time virus scanning and the like
Example: var or D:\data\pdf_renderer\
Temporary Session Files
This is the folder, temporary session data is written to and read from. Typically this is a network mount, because other components (publishing server / CometServer) access this folder too.
Requirements
- the folder must exist
- full read and write access for the priint:pdf renderer user and full read and write access for the Glassfish / publishing server user
- system wide setting for all priint:pdf renderer instances and other components
- must be excluded from real time virus scanning and the like
Example: \\Shared\publishing_server\tmp
Document Files
This is the folder, documents (e.g. publication documents) are written to and read from. Typically this is a network mount, because other components (publishing server / CometServer) access this folder too.
Requirements
- the folder must exist
- full read and write access for the priint:pdf renderer user and full read and write access for the Glassfish / publishing server user
- system wide setting for all priint:pdf renderer instances and other components
- must be excluded from real time virus scanning and the like
Configuration: priint:suite adminstration, variable documentRoot. See screenshot below. Don't forget to click the "save" button after changing this value!
Example: \\Shared\publishing_server\documents
Screenshot Temporary Session Files and Document Files configuration:
Monitoring priint:pdf renderer instances
Under priint:suite > Administration > InDesign® instances you find a list of configured InDesignServer instances and information about the current status, whether it's currently processing a job or not, the number of opened documents on this instance, usage statistics etc. (again: for historical reasons this is still called InDesign® instances in the UI, though this view refers to all type of renderers).
Double-clicking an entry opens a separate panel, which shows the documents currently opened on this instance.
- Status: can be running or not available. If an instance stays not available for a long time, you should check for server crashes, network problems or misconfiguration.
- Busy: can be idle or busy. Idle means: this instance currently does not process anything and can accept requests. Busy means: this instance is currently processing a rewuest and cannot accept further requests, until this task is finished.
If an instance stays busy for a very long time, you should check this instances log files for crashes or hangs. - Requests: the total number of requests sent to this instance. In a well balanced system, the number of requests should be about the same for all instances of the same type.
- Opened documents: the number of documents currently opend on this instance. In a well balanced system, the number of opened documents should be about the same for all instances of the same type.
- Documents to close: documents currently scheduled to be closed on this instance. This should be a low number (2, 1 or zero).
Example configurations
This section describes some typical path configurations for PubServer / priint:pdf renderer running on the same or on dedicated hosts.
Please note:
- if running on the same host, the publishing server and priint:pdf renderer process should be started under the same user account
- if running on different hosts, files and folders created by the publishing server user must be readable and writeable for the priint:pdf renderer user and vice versa
Publishing server and priint:pdf renderer on the same physical machine (Windows)
- set documentRootPath to a local folder (e.g. C:\pubserver\userdocuments\, see Section 5.5 Document Files)
- set tmpPath to a local folder (e.g. C:\pubserver\tmp\, see Section 5.4 Temporary Session Files)
Publishing server and priint:pdf renderer on dedicated Windows machines
- assign the target volume (local drive on one of the machines or network mount) for document files to a drive letter on the publishing server host, e.g. F:
- assign the target volume (local drive on one of the machines or network mount) for temporary session files to a drive letter on the publishing server host, e.g. T:
- do the same on the priint:pdf renderer host using the same drive letters
- set documentRootPath and tmpPath in the priint:suite administration using the same drive letters (e.g. F:\\documents\ resp. T:\\tempfiles\, see Section 5.5 Document Files and Section 5.4 Temporary Session Files)
Publishing server on Windows, priint:pdf renderer on Mac
- Document and temporary files on the Windows host
- set documentRootPath to a local folder (e.g. C:\pubserver\userdocuments\, see Section 5.5 Document Files)
- set tmpPath to a local folder (e.g. C:\pubserver\tmp\, see Section 5.4 Temporary Session Files)
- mount this volume or folder on the Mac server
- create a symbolic link on root level to respect the folder hierarchy:
sudo ln -s /Volumes/pubserver /pubserver
-
Document and temporary files on the Mac host
- mount and assign the volume for Document Files to a drive letter on the publishing server host, e.g. F:
- mount and assign the volume for temporary session files to a drive letter on the publishing server host, e.g. T:
- set documentRootPath and tmpPath in the priint:suite administration using the same drive letters (e.g. F:\\documents\ resp. T:\\tempfiles\, see Section 5.5 Document Files and Section 5.4 Temporary Session Files)
- create symbolic links on root level to respect the folder hierarchy:
sudo ln -s /Volumes/Data/appserver/documents /documents sudo ln -s /Volumes/Data/appserver/tempfiles /tempfiles