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
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.
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.
Mount the volume "HELIOS Applications", open the "Tool Server" folder and then "Samples".
Map the network drive "HELIOS_APPS" , open the "Tool Server" folder and then "Samples".
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.
Save any of your own custom tools into the "settings/Tool Server" folder.
Using a Terminal window, verify that "toolsrv" is running:
# cd /usr/local/helios# bin/srvutil statusService 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:21Using a Terminal window, reconfigure the "toolsrv" process in order for the newly available scripts to be recognized:
# cd /usr/local/helios# bin/srvutil reconf toolsrvUsing a Terminal window, run toolclient -l to verify available tools:
# bin/toolclient -lServer Info for ankh.local.:currentConnections: 1currentToolJobs: 0cpuMegaFlops: 138.94cpuMegaInts: 524.25cpuCount: 1Type: action-psd-cs2 License: -Type: html2pdf License: PDF HandShakeType: pdf2bmp License: ImageServerType: pdfflatten License: PDF HandShakeType: sharpen-psd-CS2 License: -Type: sharpen-psd License: -Server Info for blade.local.:currentConnections: 1currentToolJobs: 0cpuMegaFlops: 635.93cpuMegaInts: 1048.49cpuCount: 2Type: action-psd-cs2 License: -Type: html2pdf License: PDF HandShakeType: pdf2bmp License: ImageServerType: pdfflatten License: PDF HandShakeType: sharpen-psd License: -1.3 toolclient (tool client application)
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.
Job type. Use toolclient -l to list available job types (see 1.3.1 "Available job types (scripts)").
Write the result file properties to <propfile>. Properties are optional key/value pairs from the tool.
Tool specific options. For applicable options read the tools documentation (1.5.1 "The individual tools").
toolclient -t pdf2bmp -s ankh.helios.de -i 1.pdf -o 1.pngThis 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)
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).
# $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 fileTool=osxhtmlrenderLicense=PDF HandShakeRunAsUser=mikeNote: 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 secret1.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.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.
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.
1.5.2 osxhtmlrender
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.
osxhtmlrender [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxhtmlrender -h (for help info)toolclient -t html2pdf -i test.html -o test.pdf -s localhost -X BottomMargin=20.0 -X TopMargin=10.0Convert 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
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.osxpdfrender [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxpdfrender -h (for help info)AntiAlias (TRUE or FALSE; default is TRUE)
Width of the resulting bitmap image in pixel
E.g.: -X AntiAlias=TRUE
toolclient -t pdf2bmp -i test.pdf -o test.png -s localhost1.5.4 osxpdfflatten
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.osxpdfflatten [-C <dir>] [-i <infile>] [-o <outfile>]
[-O <propfile>] [-X <key>=<value>]...
osxpdfflatten -h (for help info)Profile (str)
Absolute path to a custom PDF preflight profile
E.g.: -X Profile="/Volumes/Profiles/Magazine Ads.kfp"
toolclient -t pdfflatten -s localhost -i test.pdf -o flat.pdfAccept 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
1.5.6 osxapplescript (AppleScript Launcher)
This tool reads "job.in" and launches the specified AppleScript. The resulting file is written to "job.out".
osxapplescript [-C <dir>] [-i <infile>] [-o <outfile>]
[-X <key>=<value>]...
osxapplescript -h (for help info)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
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.
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.
toolclient -v -s ankh.helios.de -t sharpen-psd -i SourceImage.jpg -o DestinationImage.jpg -X JobInSuffix=.jpg -X KeepApplRunning=01.5.8 action-psd-cs2.applescript
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.toolclient -t action-psd-cs2 -i SourceImage.jpg
-o DestinationImage.jpg -X JobInSuffix=.jpg
-X KeepApplRunning=0 -X ActionName=myCustomAction
-X ShowScript=FALSE1.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:
- In the command line context it is not possible to perform any GUI related commands. So e.g. display dialog cannot be used. Make sure that the used commands do not trigger any dialog in the target application. E.g. for Photoshop it is a good idea to use the command set display dialogs to never.
- "toolsrv" needs to clean up all processes after the job is done (or when a used application does hang). Since "toolsrv" does not know about applications started by the AppleScript it is required to write all PIDs of these applications to a log so that the corresponding processes can be killed in case something went wrong. For that the function "WriteChildPID" can be used. See the sample script "sharpen-psd.applescript" for details.
- Target applications may need the correct suffix for the input file. So you have to make sure that the input file "job.in" is renamed properly.
- "sharpen-psd.applescript" contains the function WriteLog to give feedback to "toolclient" when the verbose option is used.
- "toolsrv" and "toolclient" are designed for server processing. Unfortunately some client applications are not designed in that way so that these applications need to be terminated after job processing, e.g. due to memory leaks which would bring the workstation (on which "toolsrv" is installed) down after running many jobs. For debugging/script creation it may be useful to disable this feature since it may take some time to restart the target application(s). "sharpen-psd.applescript" contains an example how this can be achieved via the (KeepApplRunning property).
- When using the toolclient -v option it is possible to show the called AppleScript using the -X ShowScript=TRUE option. This is useful to see the whole script since the script header properties are written by the tool server before the script. This option is for debugging purposes only.
1.6 Develop your own tools
- Each tool needs a configuration file that at least specifies the tool itself. However, it can also contain additional information such as RunAsUser=, License=, etc.
# mytool config fileTool=mytoolRunAsUSer=mikeThe 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").
- A tool needs an input file "job.in" and generates an output file "job.out".
- Messages on stderr will be provided to the tool client application ("toolclient").
- The time-out option (-t value) in seconds (default=180).
- A termination handler to shut down within two seconds after receiving SIGTERM message.
- The -h option to display available parameter options.
- The -C dirpath option to do a "chdir" into the specified job directory.
- The -v option to turn on more verbose error/job information printing to stderr.
- A proper exit code (0 = success).
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 |