HELIOS Tool Server UB+ User manual

1 HELIOS Tool Server

HELIOS Tool Server allows integrating remote applications/tools to be used by a main server. Certain applications and technologies are only available on a special platform. Instead of reinventing these required applications and technologies, Tool Server makes them remotely available on any major server platform. Tool Server provides the platform and already includes several useful tools - additional tools can be added by the user. HELIOS provided tools and samples are installed in minutes.
The main goal is to make remote applications/tools easy to use, therefore HELIOS Tool Server comes with a dedicated license-free installation which installs on any major platform, i.e. Mac/Windows. The "toolclient" application detects all servers automatically by using mDNS ("Bonjour") and choosing the server that offers the required service and provides best computing performance. Automatic job load balancing, file transfers, processing, auditing, and error handling makes it quite easy.

1.1 The Tool Server concept

Each job basically consists of a job data type and an input file with job options. Both of these will be transferred to the server, which passes this information to a tool that can handle this data type. The custom tool will process the job and creates an output file and a log file. The server monitors the processing tools and transfers the output and log file back to the client (Fig. 1).
Fig. 1: HELIOS Tool Server

1.2 Getting started

Step 1:

Using the Mac or Windows HELIOS Installer on your HELIOS CD or Test Drive download, install the Tool Server on each Mac or Windows system to be used as a Tool Server (see the Base UB+ manual for installation instructions).

Note: Only the "Base" and "Tool Server" modules should be installed, unless other HELIOS products are licensed to be run on this system.
The installer installs several ready-to-use Tool Server tools. These tools and their usage are described in subsequent chapters.
Step 2:
If you want to use the HELIOS provided tools:

Using the Mac Finder or Windows Explorer, navigate to the "HELIOSDIR/var/settings/Tool Server/Samples" folder, and copy the scripts you want to activate into the parent ("Tool Server") folder.

Mac:

Mount the volume "HELIOS Applications", open the "Tool Server" folder and then "Samples".

Windows:

Map the network drive "HELIOS_APPS" , open the "Tool Server" folder and then "Samples".

Terminal:

Using a Terminal window, navigate to the "HELIOSDIR/var/settings/Tool Server/Samples" folder, and copy the scripts you want to activate into the parent ("Tool Server") folder.

Step 3:

Save any of your own custom tools into the "settings/Tool Server" folder.

Step 4:

Using a Terminal window, verify that "toolsrv" is running:

# cd /usr/local/helios
# bin/srvutil status
Service       Status         PID When         Restarts
srvsrv        Running       1535 Mon  11:21
notifysrv     Running       1537 Mon  11:21
authsrv       Running       1538 Mon  11:21
desksrv       Running       1539 Mon  11:21
dhcpsrv       Running       1540 Mon  11:21
heladmsrv     Running       1543 Mon  11:21
lpd           Running       1544 Mon  11:21
mdnsproxysrv  Running       1541 Mon  11:21
toolsrv       Running       1545 Mon  11:21
Step 5:

Using a Terminal window, reconfigure the "toolsrv" process in order for the newly available scripts to be recognized:

# cd /usr/local/helios
# bin/srvutil reconf toolsrv
Step 6:

Using a Terminal window, run toolclient -l to verify available tools:

# bin/toolclient -l
Server Info for ankh.local.:
      currentConnections: 1
      currentToolJobs: 0
      cpuMegaFlops: 138.94
      cpuMegaInts: 524.25
      cpuCount: 1
      Type: action-psd-cs2 License: -
      Type: html2pdf License: PDF HandShake
      Type: pdf2bmp License: ImageServer
      Type: pdfflatten License: PDF HandShake
      Type: sharpen-psd-CS2 License: -
      Type: sharpen-psd License: -
Server Info for blade.local.:
      currentConnections: 1
      currentToolJobs: 0
      cpuMegaFlops: 635.93
      cpuMegaInts: 1048.49
      cpuCount: 2
      Type: action-psd-cs2 License: -
      Type: html2pdf License: PDF HandShake
      Type: pdf2bmp License: ImageServer
      Type: pdfflatten License: PDF HandShake
      Type: sharpen-psd License: -

1.3 toolclient (tool client application)

Usage:
toolclient -t <jobtype> [-i <infile>] [-o <outfile>]
[-O <propfile>] [-s <server>] [-p <port>]
[-T <timeout>] [-B <rwsize>] [-S] [-v] [-V]
[-l] [-L] [-X <key>=<value>]
toolclient -h (for help info)
The "bin/toolclient" application is installed with the HELIOS Base installation and is therefore available on any HELIOS supported server platform. "toolclient" requires a valid ImageServer or PDF HandShake license. The tool client finds the tool server via mDNS ("Bonjour") or via a specified TCP/IP address. It can be integrated in any application by simply calling "toolclient" as an external application. HELIOS provides Script Server scripts for its included tools, this allows hot folder based job processing. The job input and output data are linked to stdin and stdout unless it is otherwise specified via parameters. Error messages are reported on stderr, the exit code represents the success or failure status. An output file can be a binary file. RGBA raw bitmap images are automatically converted to PNG files.
The following options can be used with "toolclient":
-t <jobtype>
Job type. Use toolclient -l to list available job types (see 1.3.1 "Available job types (scripts)").
-i <infile>
Read input from <infile> instead of stdin.
-o <outfile>
Write the result to <outfile> instead of stdout.
-O <propfile>
Write the result file properties to <propfile>. Properties are optional key/value pairs from the tool.
-s <server>
TCP/IP hostname of tool server (if not specified, mDNS ("Bonjour") is used to find a tool server).
-p <port>
Tool server port number, used only if -s <server> is specified.
-T <timeout>
Timeout of "toolsrv" tool in seconds (default = 180).
-B <rwsize>
Read/write block size in bytes (default = 32768).
-S
Suppress result from tool, no output file is written.
-v
Set verbose flags for tools.
-V
Network verbose: show mDNS lookups, connections, etc.
-l
List remote tools, license and CPU information.
-L
Test mode, check calls/sec, e.g.: -v -L 20000.
-X
Tool specific options. For applicable options read the tools documentation (1.5.1 "The individual tools").
-h
Print help file.
Example:
toolclient -t pdf2bmp -s ankh.helios.de -i 1.pdf -o 1.png
This call sends the file "1.pdf" to the server "ankh.helios.de" and expects a bitmap in return, which will be written as PNG to "1.png".

1.3.1 Available job types (scripts)

These job types are included.
html2pdf
Convert an HTML page to a PDF document.
Configuration file: html2pdf.conf
pdfflatten
Flatten transparencies in a PDF document.
Configuration file: pddflatten.conf
pdf2bmp
Convert a PDF document to a bitmap PNG file.
Configuration file: pdf2bmp.conf
sharpen-psd.
applescript
Sharpens images using Photoshop CS3
Configuration file: sharpen-psd.conf
action-psd-cs2.
applescript
Image manipulation using a Photoshop CS2 action Macro
Configuration file: action-psd-cs2.conf
Additional job types can be added as described in 1.6 "Develop your own tools".

1.4 toolsrv (tool server application)

The tool server can be installed, via a separate installation item, on one or more workstations or servers. It registers the server via mDNS, checks what data types are available in "HELIOSDIR/var/settings/Tool Server", measures the computing performance and makes all this information available upon request to the tool client. If a job comes in the server creates a unique job directory in "var/tmp/", saves the input file and spawns the specified tool as a separate process. The server monitors its tools, the tool's stderr output will be logged, and if a time-out occurs the server will shut down the tool and clean up temporary files. After the tool has accomplished the job, the output file and log data will be returned. The tool server is basically "job content" blind, it does not know anything about file formats and job specific parameters. The tool client communicates with the tool server via TCP/IP.
Although there is no direct limitation for the number of concurrent tool server jobs, the optional Script Server hot folder will automatically serialize jobs for a given hot folder, which limits the number of concurrent jobs. The tool client passes the necessary product license information (of the tool client machine) to the tool server, which passes this information via environment variables to the tools. The tool server itself will not check any license availability. There should be no need to change the preferences of the tool server application. The "toolclient" and "toolsrv" applications are designed to hide complex networking and job distribution technologies from users. They offer robust remote automation with very little configuration.
Note: Large or complex jobs may considerably slow down the machine where "toolsrv" is running.

1.4.1 Configuration files

The configuration files contain the tool that is to be called (Tool), the required HELIOS license (License) and the user under which the tool should be executed (RunAsUser).
Example:
Configuration file "html2pdf.conf".
# $Id: toolsrv.html,v 1.7 2008/11/07 10:30:26 hendrik Exp $
#@(#)HeliosVersion 1.0.0 Copyright 2007 HELIOS Software Garbsen
# osxhtmlrender config file
Tool=osxhtmlrender
License=PDF HandShake
RunAsUser=mike
Note: On Windows systems the RunAsUser entry requires setting the existing user password again using the HELIOS "authutil" tool, e.g.:
authutil passwd -n mike -p secret

1.4.2 Tool server preference keys

This section lists all the preference keys that are pertinent to the tool server. Find a description of how to set, view, change or delete preferences, with the HELIOS "prefdump", "prefvalue", and "prefrestore" utility programs in the HELIOS Base UB+ manual, chapter 8, "HELIOS utility programs".
Important: Make sure that preference keys DO NOT start or end with a slash ("/") character, and note that they are case-sensitive! Also, if any preference key or preference value includes spaces, that key or value must be enclosed in quotes.
Preference
Type Default (""=empty string)

Key: Programs/toolsrv/<preference>
TcpPort
int 2019
TCP/IP communication port for the communication between client and server.
ipaccess
str "ipaccess"
Specifies the file name of the IP access list that makes the tool server accessible for clients which have one of the IP addresses on the IP access list.
WorkingDir
str "var/tmp"
Specifies the location where the tool server creates its temporary working directory. The temporary working directory will be deleted as soon as the tool has accomplished its task.

1.5 The tools

The tools are responsible to process an input job for a given data type. HELIOS includes several tools which process certain file types. The idea of the tools is to focus on the job, e.g.: take the input file and parameters, process it and write an output file and print logging information to stderr. The benefit is that you need not worry about client-server communication, load balancing, and multiple platform support.
For example, a tool may run on Windows and the tool client runs on IBM AIX. HELIOS Tool Server delivers the infrastructure to integrate remote applications. The tool itself can be very simple, e.g. a few lines of script (Perl, AppleScript, Visual Basic or any other executable program). The tool must exit with zero if the job processing was successful or with an exit error code and messages to stderr if an error occurs. The tool itself will receive any number of parameters from the tool client via (-X variable=value).
If the tool requires any licenses it must check the availability of the licenses itself. Due to the fact that the tool may run on a remote workstation all license information is provided by the tool client via the tool server to the tool, using environment variables. Each tool will be monitored by the tool server. In case of a job time-out the tool will be asked to stop via a termination signal. If the tool does not quit within two seconds after receiving the termination signal, it will be killed.
After the job is done the tool server will remove all temporary files within the job directory, including the job directory itself. By default all tools run as the system service user. It can be necessary that a tool runs under a special user account to use the settings/context of this specific user. The user name can be specified in a tool configuration file named "<toolname>.conf". See also 1.4.1 "Configuration files". Custom tool configuration files are stored in "HELIOSDIR/var/settings/Tool Server/".

1.5.1 The individual tools

The following tools can also be used stand-alone, i.e. for testing purposes. But it is recommended to use them with the HELIOS tool client because these tools can then also be used remotely and independent of a special platform. In addition, the tool client stays clear of workload.
Platform Function
osxhtmlrender
Mac Convert HTML to PDF utilizing Apple's WebKit technology
osxpdfrender
Mac Create RGB bitmap previews using Mac OS X rendering technologies
osxpdfflatten
Mac Flatten PDF documents by automating Adobe Acrobat 8.1
winpdfflatten
Win Flatten PDF documents by automating Adobe Acrobat 8.1
osxapplescript
Mac Launch a specified AppleScript

1.5.2 osxhtmlrender

If called with "toolclient" use html2pdf as type
This tool utilizes Apple's WebKit technology to process HTML documents and convert them into PDF files. This is a fairly complex task because HTML pages can contain CSS style sheets, JavaScript, and other modern HTML content. The "osxhtmlrender" tool provides similar results compared to Safari HTML to PDF printing. The tool allows optional specification of the page sizes, margins and alignment. There are many web applications/solutions that produce nice HTML lists/reports/documents. The "osxhtmlrender" tool is an excellent solution to turn them into PDF documents. Additional HELIOS PDF tools are available to encrypt these documents.
Usage:
osxhtmlrender [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxhtmlrender -h (for help info)
The following options can be used with "osxhtmlrender":
-C
Set working directory, where the files to be acted upon reside, and the log file is to be saved
-i
Read input from <infile> instead of "job.in"
-o
Write output to <outfile> instead of "job.out"
-O
Write properties of output file to <propfile> instead of "job.outprops"
-X
Tool specific options (paper sizes and margins are specified in points):
LeftMargin (float)
E.g.: -X LeftMargin=10.0
RightMargin (float)
E.g.: -X RightMargin=10.0
TopMargin (float)
E.g.: -X TopMargin=10.0
BottomMargin (float)
E.g.: -X BottomMargin=10.0
ShouldPrintBackgrounds (bool)
E.g.: -X ShouldPrintBackgrounds=TRUE
PrintsHorizontallyCentered (bool)
PrintsVerticallyCentered (bool)
PrintScalingFactor (float 0.0 ... 1.0; default is 1.0)
E.g.: -X PrintScalingFactor=0.5
PaperSize (float, float)
E.g.: PaperSize=300.0,400.0
PaperName (A4, A5, Legal, ..., default is A4)
E.g.: -X PaperName=Letter
Orientation (Portrait or Landscape, default is Portrait)
VerticalPagination (Auto or Fit or Clip)
HorizontalPagination (Auto or Fit or Clip)
Example:
toolclient -t html2pdf -i test.html -o test.pdf -s localhost -X BottomMargin=20.0 -X TopMargin=10.0
Convert the HTML file "test.html" into a PDF file ("job.out") that contains all referenced objects. In addition, a top margin of 10 points and a bottom margin of 20 points is applied.
Note: When using "toolclient" with "html2pdf" to convert an HTML page to a PDF file, the source tags of the referenced images (<img src=...>) must contain the absolute path, otherwise the images cannot be incorporated in the resulting PDF document.
Alternatively you may add the web URL in the first line of the downloaded HTML page.
Note: The data type "html2pdf" processes an HTML page according to the specifications defined in the style sheet for printing (rel="stylesheet" ... media="print"), if available. These might interfere with the custom "osxhtmlrender" options that are set with the -X flag.

1.5.3 osxpdfrender

If called with "toolclient" use pdf2bmp as type
This tool makes use of Apple's Quartz technology, to create an RGB preview bitmap of a given PDF file. It is mainly used to allow the preview generation of PDF files containing Japanese characters. Due to font licensing limits PDF HandShake cannot process Japanese PDFs, so "osxpdfrender" is an alternative solution.
Note: High-quality previews including CMYK colors and proper overprint previews are provided via the HELIOS ImageServer and PDF HandShake products by using the "layout" command.
Usage:
osxpdfrender [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxpdfrender -h (for help info)
The following options can be used with "osxpdfrender":
-C
Set working directory, where the files to be acted upon reside, and the log file is to be saved
-i
Read input from <infile> instead of "job.in"
-o
Write output to <outfile> instead of "job.out"
-O
Write properties of output file to <propfile> instead of "job.outprops"
-X
Tool specific options:
Width (int)
Width of the resulting bitmap image in pixel
E.g.: -X Width=144
Height (int)
Height of the resulting bitmap image in pixel
E.g.: -X Height=144
PageNumber (int; default is 1)
Page number to process
E.g.: -X PageNumber=28
AntiAlias (TRUE or FALSE; default is TRUE)
Width of the resulting bitmap image in pixel
E.g.: -X AntiAlias=TRUE
Example:
toolclient -t pdf2bmp -i test.pdf -o test.png -s localhost
Convert the PDF file "test.pdf" into a bitmap file ("test.png") on localhost.

1.5.4 osxpdfflatten

If called with "toolclient" use pdfflatten as type
This tool accepts a PDF file and uses Adobe Acrobat 8.1 on Mac to flatten transparencies and output a PDF file that does not contain transparencies anymore. This tool uses the Acrobat Professional pdfInspektor technology to flatten PDF files.
Note: On a Mac the "osxpdfflatten" tool automates Acrobat running as user "root". So it is required to log in once as "root", start Acrobat manually and logout again. This ensures that Acrobat preference files are available for "root", otherwise an error message "*** no user interaction is permitted" will be issued.
Note: "osxpdfflatten" requires a dedicated workstation, users cannot work on this machine because the Acrobat automation will start and stop and open and close windows which will confuse users. Clicking into Acrobat Windows will interfere the flattening automation.
Usage:
osxpdfflatten [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxpdfflatten -h (for help info)
The following options can be used with "osxpdfflatten":
-C
Set working directory, where the files to be acted upon reside, and the log file is to be saved
-i
Read input from <infile> instead of "job.in"
-o
Write output to <outfile> instead of "job.out"
-O
Write properties of output file to <propfile> instead of "job.outprops"
-X
Tool specific option:
Profile (str)
Absolute path to a custom PDF preflight profile
E.g.: -X Profile="/Volumes/Profiles/Magazine Ads.kfp"
Example:
toolclient -t pdfflatten -s localhost -i test.pdf -o flat.pdf
Accept the PDF file "test.pdf", which contains transparencies, and flatten it, i.e. convert all transparent objects to non-transparent objects. The file is then output to a flattened PDF file ("flat.pdf").

1.5.5 winpdfflatten

If called with "toolclient" use pdfflatten
Same features as the "osxpdfflatten" tool but it automates Acrobat on Windows.

1.5.6 osxapplescript (AppleScript Launcher)

This tool reads "job.in" and launches the specified AppleScript. The resulting file is written to "job.out".
Usage:
osxapplescript [-C <dir>] [-i <infile>] [-o <outfile>]
[-X <key>=<value>]...
osxapplescript -h (for help info)
The following option can be used with "osxapplescript":
-C
Set working directory, where the files to be acted upon reside, and the log file is to be saved
-i
Read input from <infile> instead of "job.in"
-o
Write output to <outfile> instead of "job.out"
-X
Tool specific options:
ToolScript (str)
The AppleScript to launch. Note that a path relative to "HELIOSDIR" must be specified.
E.g.: -X ToolScript=sharpen-psd.applescript
ShowScript <bool; default is FALSE>
Show the called AppleScript. If "ShowScript" is called with "toolclient" the -v option must also be specified.
Note: The "osxapplescript" tool is a launcher, which is used by the AppleScript automation tool examples:

"sharpen-psd.applescript" and
"action-psd-cs2.applescript"

1.5.7 sharpen-psd.applescript

If called with "toolclient" use sharpen-psd as type
This is an example AppleScript which sharpens a JPEG image using Photoshop CS3. As documented within the script, it can be modified and used with Photoshop CS2.
-X
Tool specific options:
JobInSuffix (str)
The tool only receives the file "job.in". So we need the suffix (including the leading dot ".") of the original file to rename it properly because Photoshop does not open an image with a wrong suffix.
KeepApplRunning (int; default is 0)
The AppleScript needs to quit the target application due to possible memory leaks, etc. when the job is finished. This parameter (when 1 is set) allows keeping the application running for debugging/script writing purposes.
Example:
toolclient -v -s ankh.helios.de -t sharpen-psd -i SourceImage.jpg -o DestinationImage.jpg -X JobInSuffix=.jpg -X KeepApplRunning=0

1.5.8 action-psd-cs2.applescript

If called with "toolclient" use action-psd-cs2 as type
This is an example AppleScript which does image manipulation using a Photoshop CS2 action macro.
-X
Tool specific options:
JobInSuffix (str)
The tool only receives the file "job.in". So we need the suffix (including the leading dot ".") of the original file to rename it properly because Photoshop does not open an image with a wrong suffix.
KeepApplRunning (int; default is 0)
The AppleScript needs to quit the target application due to possible memory leaks, etc. when the job is finished. This parameter (when 1 is set) allows keeping the application running for debugging/script writing purposes.
Note: The tool specific options "JobInSuffix" and "KeepApplRunning" are required options.
ActionName <string>
Name of the called Photoshop action.
Example:
toolclient -t action-psd-cs2 -i SourceImage.jpg
-o DestinationImage.jpg -X JobInSuffix=.jpg
-X KeepApplRunning=0 -X ActionName=myCustomAction
-X ShowScript=FALSE

1.5.9 Notes on AppleScript based tools

AppleScript is a technology which allows using features of any application capable of AppleScript. There are sample scripts included that perform tasks using Adobe Photoshop. However, there are several things to keep in mind:

1.6 Develop your own tools

For example, the tool "mytool" has the configuration file "mytool.conf":
# mytool config file
Tool=mytool
RunAsUSer=mike
The tool and its configuration file must be stored in "HELIOSDIR/var/settings/Tool Server". After that, "toolsrv" must be reconfigured in order to make the script being recognized (see reconfiguration line in 1.2 "Getting started").
Examples for shell scripts, Perl scripts, and Visual Basic scripts can be found here.

1.7 Required licenses

Usually the tool client is used on the main workflow server and requires an ImageServer or a PDF HandShake license.
Although "toolsrv" requires no license, it is only allowed to be installed and used as long the customer owns a valid PDF HandShake or ImageServer license on the host where the "toolclient" application is used. This varies from the actual HELIOS license agreement which you can find in the file "license.txt " on the HELIOS CD, and which is displayed in the HELIOS Installer during the installation.
For the tools no local license is required. They will check with the tool client for a valid license:
Tool License
osxhtmlrender PDF HandShake
osxpdfflatten/winpdfflatten PDF HandShake
osxpdfrender ImageServer
osxapplescript –
© 2007 HELIOS Software GmbH