HELIOS ImageServer 2.5 includes a Script Server service which implements a hot folder mechanism. You simply drop files into the hot folder. The idea of a hot folder is that, when files are dropped into this folder, a process is automatically started converting the files according to a given script.
Major benefits of the Script Server are:
- It is event-driven instead of folder polling
- Script Server limits the number of concurrent scripts to avoid overloading the server
- A central Script Server configuration and log file can easily be configured in EtherShare Admin
- Fail safety of the Script Server is provided by the HELIOS Base Service Controller
- Custom scripts can be kept short. A few lines of a UNIX shell script or Perl script are sufficient to automate server processing tasks, e.g. converting all input images to a color-matched TIFF format which is tagged with ICC profiles
7.1 Introduction and example
Any folder on your EtherShare server can act as hot folder for the Script Server. In the following example, our designated hot folder may be named "For the Web". We will be setting up the Script Server so that it converts all allowed file formats into JPEG format when dropped into the hot folder.
HELIOS provides a variety of sample scripts for different file formats and purposes. Here we use lines from the sample script "webjpeg" that the Script Server must call to make our hot folder work. All you have to do is add these lines to the Script Server configuration file:
-> Start EtherShare Admin and open
Lists > Script Server > Configuration to open the
scriptsrv.conf window (Fig.
36).
Fig. 36: scriptsrv.conf window in EtherShare Admin
|
|
-> In order to access the sample scripts connect to your HELIOS server and mount the volume "Scripts". Then select the "webjpeg" file and drag it onto a text editor, e.g. BBEdit (Fig.
37).
Important: Be sure that the used editor does save files with UNIX line feeds ("LF" only). Macintosh "CR" or Windows "LF/CR" compatible editors will not work for this purpose!
Fig. 37: Opening the script file in a text editor
|
|
Note: By default, the "Scripts" volume is write-protected for everybody but "root". Adjust write access rights if you want to edit scripts in that volume, or if you want to store your own customized scripts there.
-> In the editor select the default configuration lines as shown in Fig.
38. Each of the sample scripts contains default configuration lines which we will use in the Script Server configuration file.
-> Copy the configuration lines (highlighted in Fig.
38) from within the editor window.
Fig. 38: Selecting default configuration line in BBEdit
|
|
-> Append the lines which you have copied from the sample script to the end of the configuration file in EtherShare Admin's
scriptsrv.conf window. Delete the first character ("# ") in each edited line and replace "demovol/webjpeg" with the hot folder name and its path.
In our example the folder name is "For the Web", and its path is "/images" (compare Fig
38 and
39).
Fig.
39 shows what the
scriptsrv.conf window should look like after the lines have been pasted into the document.
-> Now close the
scriptsrv.conf window and save your changes.
Fig. 39: Edited scriptsrv.conf window in EtherShare Admin
|
|
As soon as you save your changes, the Script Server will be notified and your hot folder is working. You can now drop image files into the hot folder. You will notice a new folder "DONE" inside the hot folder. This folder contains the converted JPEG images whose file name automatically has an "N" appended (e.g. "image.tif" became "imageN.jpg"), as well as your original images.
A detailed description of the Script Server configuration file, on starting/stopping and refreshing the Script Server process, on included sample scripts, and on debugging scripts can be found in
7.2 "Configuration".
Fig.
40 shows "For the Web" (hot folder) before files have been dropped into it (
1), and after files have been dropped into it and then processed (
2).
Fig. 40: Hot folder before and after Script Server processing
|
|
You might be interested in the Script Server's log file, e.g. for troubleshooting purposes. It can easily be accessed from within EtherShare Admin:
-> In EtherShare Admin and open
Lists > Script Server > Log File to open the
scriptsrv.log window (Fig.
41)
Fig. 41: The scriptsrv.log window in EtherShare Admin
|
|
.
Note: Log output can be interleaved from concurrently running scripts.
"HELIOSDIR/var/conf/scriptsrv.conf" is the main configuration file.
"HELIOSDIR/var/adm/scriptsrv.log" is the log file containing stdout/stderr of all scripts as well as all "scriptsrv" messages.
HELIOS delivers a variety of sample scripts (see also
7.2.3 "Included sample scripts") with the software. They can be accessed after mounting the "Scripts" volume.
Access from EtherShare Admin
Both "scriptsrv.conf" and "scriptsrv.log" can be accessed from EtherShare Admin (
Lists > Script Server).
7.2.1 Starting, stopping and refreshing the Script Server process
The "scriptsrv" process will automatically be started using the "start-helios" and "stop-helios" commands. The status of the "scriptsrv" service can be changed via "srvutil":
Note: The "srvutil" utility can be found in "HELIOSDIR/bin".
Stops the "scriptsrv" services, new events will not be processed. All queued events will be processed up to 30 seconds after receiving the stop event. All executed scripts will receive a TERM signal to notify the "scriptsrv" service shutdown.
# srvutil start scriptsrv
Starts the "scriptsrv" services.
Reconfiguring "scriptsrv"
# srvutil reconf scriptsrv
Will update its hot folder configuration from the "scriptsrv.conf" file as well as the preference settings for the "scriptsrv" service. When modifying "scriptsrv.conf" in EtherShare Admin, an automatic reconfiguration is done (see
Access from EtherShare Admin).
Preferences for the "scriptsrv" service are listed and explained in
8.1.5 "Script Server preferences".
7.2.2 The Script Server configuration file
The configuration file
"scriptsrv.conf" includes one or more lines to specify the hot folder with its allocated scripts to be executed:
Note: A colon is the separator between the fields, so if you use a colon in a field, it must be quoted by a preceding "backslash" character (\:).
Macintosh file type, e.g. EPSF or TIFF. Only files matching this file type will be processed (always 4 characters!).
Windows file type extension, e.g. ".tif". Only files matching this file type will be processed (always ".xyz" syntax!).
All files in this folder will be processed recursively (i.e. subfolders are also processed).
A UNIX shell script or a Perl script to be called to process a file. The first argument of this script is a file name, additional parameters will be passed via environment variables. Read-only sample scripts can be found in
"HELIOSDIR/etc/scriptsrv". Customized scripts should be saved to "HELIOSDIR/var/scripts" in order to allow migration to the different server platforms.
The UNIX user name under which the script is executed, e.g. "root", "demouser", -
A list of comma-separated environment variables can be specified to be passed to the script, e.g.
PRINTER=Laser,SCRIPTDEBUG=1. This allows having a general purpose script to be used with different parameters.
# HELIOS Script Server configuration file
#
# Lines in this file have the form
#
# type:extension:dirpath:script:scriptuser:scriptenv
#
# type is the Macintosh Type, e.g. TIFF
# extension is the Windows extension e.g. .tif
# script is the program to be called for the hot
# folder, e.g. var/scripts/scriptname. If
# 'script' is not a fully specified path
# (starting with /), it is searched in
# HELIOSDIR and in HELIOSDIR/var/scripts.
# It is recommended that you save all scripts
# in HELIOSDIR/var/scripts.
# scriptuser is the user under which the script is
# getting called, e.g. root.
# scriptenv is a comma separated list of key=value
# items which are exported as environment
# variables for the script.
#
# The fields are separated by colons. Colons used within
# a field must be quoted with a backslash (\:).
#
#Examples:
#TEXT:.ps:/demovol:printps:root:PRINTER=lw,SCRIPTDEBUG=1
#PDF :.pdf:/demovol:printpdf:demouser:
#
#Wildcard registration for all file types/extensions:
#\0\0\0\0:\0:/demovol:printps:root:
7.2.3 Included sample scripts
We provide the following sample scripts for the Script Server functionality with our software (each sample script is listed with the respective line(s) for the entry in "scriptsrv.conf"). Note that in the following examples "out" is used for the OUTDIR parameter:
Print PostScript files to a specified printer:
TEXT:.ps:/demovol/printps:printps:root:PRINTER=lw,SCRIPTDEBUG=1
EPSF:.eps:/demovol/printps:printps:root:PRINTER=lw,SCRIPTDEBUG=1
Print text files to a specified printer:
TEXT:.txt:/demovol/printtext:printtext:root:PRINTER=lw,SCRIPTDEBUG=1
Print a PDF file to a specified PostScript printer:
PDF :.pdf:/demovol/printpdf:printpdf:root:PRINTER=lw,SCRIPTDEBUG=1
Split a PDF file into single pages and move final PDF files into a directory specified in the OUTDIR parameter:
PDF :.pdf:/demovol/splitPDF:splitPDF:root:OUTDIR=out,SCRIPTDEBUG=1
Convert a PDF page to an EPSF file and move final EPSF files into a directory specified in the OUTDIR parameter:
PDF :.pdf:/demovol/convpdf2eps:convpdf2eps:root:OUTDIR=out,SCRIPTDEBUG=1
Convert all supported ImageServer file types into TIFF CIE-Lab and move converted files to OUTDIR:
PDF :.pdf:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
TIFF:.tif:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
EPSF:.eps:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
JPEG:.jpg:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
PNGf:.png:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
BMP :.bmp:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
8BPS:.psd:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
8BIM:.psd:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
PICT:.pct:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
..CT:.ct:/demovol/convert2Lab:convert2Lab:root:OUTDIR=out,SCRIPTDEBUG=1
Generate a 128x128 pixel Internet PNG file and move final PNG file into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB:
PDF :.pdf:/demovol/webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
TIFF:.tif:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
EPSF:.eps:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
JPEG:.jpg:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
PNGf:.png:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
BMP :.bmp:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
8BPS:.psd:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
8BIM:.psd:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
PICT:.pct:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
..CT:.ct:/demovol/webpicts:webpicts:root:OUTDIR=out,SCRIPTDEBUG=1
Generate a 128x128 pixel Internet JPEG file and move final JPEG files into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB:
PDF :.pdf:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
TIFF:.tif:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
EPSF:.eps:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
JPEG:.jpg:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
PNGf:.png:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
BMP :.bmp:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
8BPS:.psd:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
8BIM:.psd:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
PICT:.pct:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
..CT:.ct:/demovol/webjpeg:webjpeg:root:OUTDIR=out,SCRIPTDEBUG=1
7.2.4 HELIOS default scripts location
By default, we recommend to copy all scripts into the "Scripts" volume. The benefits of the HELIOS default script location "HELIOSDIR/var/scripts" are:
- All scripts will automatically be migrated in case of a server change by moving the "var" folder to the new server
- The folder "HELIOSDIR/var/scripts" is automatically exported as a Macintosh and a Windows volume to allow easy editing, e.g. using BBEdit. Custom permissions can be specified to allow a user or group write permission to this folder
- The "Scripts" volume simplifies the installation of new customized scripts by users, just copy the new script into the volume
- The script name(s) specified in "scriptsrv.conf" will automatically be searched in the "Scripts" volume, there is no need to specify the complete path name to the script
- All scripts will automatically be changed to be executable (the executable flag will be set for this script)
7.3 Developing and debugging scripts
The "scriptsrv" startup message can be found in the "scriptsrv.log" message file, which is also available from within EtherShare Admin. Please make sure via "srvutil status" that the "scriptsrv" service is running and there are no error messages in the "scriptsrv.log" file.
All registrations for different scripts must be displayed in the "scriptsrv.log" file startup message: "Config line xx: -".
If not, the configuration file is empty or you will find other error messages.
Every time a custom script is called, the "scriptsrv.log"
file contains a "Start scriptname -" line and a "Done scriptname -" line. All standard output, as well as error output of the script is automatically redirected into the "scriptsrv.log" file.
7.3.1 Parameters for the scripts
Scripts are called with the file name as the first argument, e.g. a UNIX shell script will contain the file name in
$1, a Perl script will contain it in
$ARGV[0].
Additional default parameters are provided via environment variables. "HELIOSDIR" will always be set to the directory where the HELIOS products are installed.
Additional custom parameters can be specified in the "scriptsrv.conf" file as the last argument of each configuration line, e.g.
SCRIPTDEBUG=1,PRINTER=lw. The custom environment will be available as environment variables in the script. This allows developing one script and use it for different hot folders by using different parameters (e.g. printer, ICC profiles, color spaces, etc.).
7.3.2 Debugging scripts stand-alone (without Script Server)
It is a good idea to test your scripts first manually in a UNIX terminal session to verify that they work. By default, the Script Server calls all scripts with the current directory set to the HELIOS product directory. Therefore it is required that you change first into the HELIOSDIR before executing a script manually:
Calling a stand-alone script manually, e.g. the "printps" script, using a bash or Bourne shell:
# cd /usr/local/helios
# chmod +x var/scripts/printps
# export HELIOSDIR="/usr/local/helios"
# export PRINTER="lw"
# export SCRIPTDEBUG=1
# var/scripts/printps "/data/demovol/TestFolder
/samplefile.ps"
If this produces error messages or the script does not do what it is expected to do, it needs to be solved before using it in the automatically event-driven Script Server.
Calling standalone scripts allows debugging, using the Perl debugger or UNIX "gdb/dbx" debugger for C/C++ applications. Simple debugging by printing messages will work as well within the automated Script Server environment. All output of the script will automatically be redirected into the "scriptsrv.log" file.
Note: Every HELIOS Perl sample contains the following file magic:
This means the script is executable just by calling it. It always needs to be called from the HELIOS directory (e.g. "/usr/local/helios"), otherwise "var/run/runperl" cannot be found. The file "runperl" will be a symbolic link to your Perl runtime, e.g. "/usr/bin/perl" on Mac OS X or Linux systems.
Whenever "start-helios" is issued, the "runperl" link will automatically be created. This might be helpful if Perl is installed at a later time (no changes in the script required).
An alternative option to test your scripts in a different directory is to create the runperl link in your script directory.
Example (e.g. on Mac OS X or Linux):
# cd /home/myhome
# mkdir -p var/run
# ln -s /usr/bin/perl var/run/runperl
7.3.3 Debugging scripts in the Script Server environment
To inspect the current "runQueue" and the configuration of the running "scriptsrv" daemon, the UNIX signal USR1 can be issued to the "scriptsrv" daemon (e.g. finding the
PID via "srvutil status"). The command
kill -USR1 pid will output the configuration into the "scriptsrv.log" file. Another option to turn on debug messages for the "scriptsrv" process is by setting the debug preference, e.g:
# prefvalue -k Programs/scriptsrv/debug -t int 1
-> Delete the debug preference via:
# prefvalue -d -k Programs/scriptsrv/debug
Important: We do not recommend to turn on the debug preference for production servers because it will produce heavy load on the server and can cause significant slow-down of the server!
7.4 Additional considerations
"opisrv" will send events for each file of the registered type/extension on any HELIOS volume, independant whether layouting has been enabled or not for that volume, or directory.
"scriptsrv" then has to process each event and sort out files and directories which do not require further processing. For the remaining files it has to verify whether the file is already queued.
Therefore you should restrict the registered types/extensions and directories to those that are really processed by your scripts, so that the communication and processing overhead does not become too large.
When using scripts for layout generation (with "layout" in normal or convert mode) you should deactivate automatic layout generation for the hot folder, or the complete volume where the hot folder resides.
