|
|
|
|
|
HELIOS ImageServer UB User manual |
||||
HELIOS ImageServer includes a Script Server service, which implements a so-called hot folder mechanism. The idea of a hot folder is that, when files are dropped into this folder, a process is automatically started, acting upon the files according to a given script.
- 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 file can easily be set up, and the log file can easily be monitored in HELIOS Admin
- Custom scripts can be kept short. A few lines of a 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
- Script Server can fully automate processes "behind the scenes", or be used selectively via user interaction with "hot folders"
- Any procedure or command which can be scripted, can be automated via Script Server
- Script Server job monitoring via telnet port 2024
Any folder within a HELIOS volume can act as a hot folder for the Script Server. In the following example, our designated hot folder may be named "for_web". HELIOS provides a variety of sample scripts for different file formats and purposes. The section Example line below shows a line from the sample script "webjpeg.pl" that the Script Server should call.
Start HELIOS Admin and go to Settings > Script Server Configuration to open the scriptsrv.conf window (Fig. 33).
To access the sample scripts, connect to the HELIOS server and mount the volume "Settings". Then select "webjpeg.pl" from "Script Server > Samples" and open it in a text editor.
Important: Make sure that the editor does save files with UNIX line feeds ("LF" only). Windows "LF/CR" or Macintosh "CR" compatible editors will not work for this purpose!
Note: The "Settings" volume is write-protected for everybody but "root". If there is the need to extend write access rights to other users, assign proper permissions to the respective subfolders.
In the editor select the default configuration line. Each of the sample scripts contains default configuration lines which we will use in the Script Server configuration file.
# TIFF,JPEG,EPSF,8BIM,8BPS,PICT,BMP ,PNGf,..CT,PDF :tif,eps,psd,pct,bmp,png,sct,pdf:/demovol/webjpeg:webjpeg.pl:root:OUTDIR=DONE,SCRIPTDEBUG=1
Append the line(s) which you have copied from the sample script to the end of the configuration file in the HELIOS Admin scriptsrv.conf window. Delete the hash mark (#) in the copied line and replace "/demovol/webjpeg" with the hot folder name and its path.
In our example the folder name is "for_web", and its path is "/images". Fig. 34 shows what the scriptsrv.conf window should look like after the lines have been pasted into the document.
As soon as you save your changes your hot folder is working. You can now drop image files into the hot folder. You will notice the 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" becomes "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 the included sample scripts, and on debugging scripts can be found in 7.4 "Configuration".
The Script Server log file lists script actions or Script Server processes, with date and time (Fig. 35).
Script Server log files are arranged by date. Every night at midnight the (host) "cron" program starts automatically in the background and renames the log file information of the last seven days. The file "Today" becomes the file "Yesterday", "Yesterday" is renamed into "Two Days Ago", and so on. You can then select, for instance, the server log file of "Three Days Ago". Log files which are older than seven days are deleted automatically.
You can then read this information into a word processor for further use. HELIOS Admin gets its information from the files "HELIOSDIR/var/adm/scriptsrv.log" ("Today") to "HELIOSDIR/var/adm/scriptsrv.6" ("Seven Days Ago"). See 7.3 "Script Server log file structure" below for more information.
You might be interested in the Script Server log file, e.g. for troubleshooting purposes. It can easily be accessed from within HELIOS Admin.
Each entry in "HELIOSDIR/var/adm/scriptsrv.log" (with the appendices ".0", yesterday to ".6", seven days ago) has the following format:
Note: HELIOS Admin does a live update of the displayed Script Server log files (Lists > Script Server Log Files).
"HELIOSDIR/var/adm/scriptsrv.log" is the log file containing stdout/stderr of all scripts as well as some "scriptsrv" messages.
HELIOS delivers a variety of sample scripts (see also 7.4.3 "Included sample scripts") with the software. They can be accessed after mounting the "Settings" volume.
The Script Server configuration file "scriptsrv.conf" and log file "scriptsrv.log" can be accessed from HELIOS Admin (Settings > Script Server Configuration and Lists > Script Server Log Files).
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 them of the "scriptsrv" service shutdown.
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 HELIOS Admin, reconfiguration is automatically done (see Access from HELIOS Admin). Preferences for the "scriptsrv" service are listed and explained in 8.1.6 "Script Server preferences".
Note: If parts of the configuration lines are invalid a detailed error message is written to the system messages file.
The configuration file "scriptsrv.conf" includes one or more lines to specify the hot folder with its associated 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!). It is possible to specify the file types in a comma-separated list.
File extension, e.g. "tif". Only files matching this extension will be processed (always "xyz" syntax!). It is possible to specify the extensions in a comma-separated list.
A host 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/var/settings/Script Server/Samples". Customized scripts should be saved to
"HELIOSDIR/var/settings/Script Server" in order to allow migration to the different server platforms. The Perl script should rececive the extension ".pl" , e.g. ABCDEF.pl
Note: Alternatively, paths to customized scripts can be stated either absolute or relative in respect to "HELIOSDIR".
The host user name under which the script is executed, e.g. "root", "demouser", etc.. If not specified, the user "root" is used.
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.
SCRIPT_TIMEOUT If set, it overrides the global preference RunTime (see 8.1.6 "Script Server preferences").
SCRIPT_OLDNAME Is set by the server and can be evaluated in the script containing the old name, if the event is move or dirmove.
# if type and extension are empty, any file
# is monitored if type contains the keyword
# DIRECTORY, suffix is ignored and directory
# events are monitored
# script is the program to be called for the hot
# folder, e.g. scriptname or
# /path/to/scriptname. If 'script' is not a
# fully specified path (starting with /), it
# is searched in HELIOSDIR and in
# "HELIOSDIR/var/settings/Script Server".
# It is recommended that you save all scripts
# in "HELIOSDIR/var/settings/Script Server".
# 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 (\:).
#PDF ,TIFF,JPEG,EPSF,8BIM,8BPS,PICT,BMP,PNGf,..CT:pdf,
tif,jpg,eps,psd,pct,bmp,png,sct,pdf:/demovol/webpicts:webpicts.pl:root:OUTDIR=DONE,SCRIPTDEBUG=1
We provide the following sample scripts for the Script Server functionality with our software (each sample script is listed with the respective configuration lines for the entry in "scriptsrv.conf"). Note that in the following examples "out" is used for the OUTDIR parameter:
Note: The following five scripts require that PDF HandShake be installed on the same host:
PDF :pdf:/inspectPDFHotFolder:/usr/local/helios/etc/callas/scripts/inspectpdf.pl:root:OUTDIR=DONE,PROOFPROFILE=/usr/local/helios/callas/Profiles/test.profile,SCRIPTDEBUG=0
Split a PDF file into single pages and move final PDF files into a directory specified in the OUTDIR parameter:
Convert a PDF page to an EPSF file and move final EPSF files into a directory specified in the OUTDIR parameter:
Note: In the following scripts, image conversion of PDF files does require PDF HandShake.
Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.
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:
Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.
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:
Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.
We recommend to copy all scripts into the "Script Server" directory in the "Settings" volume. The benefits of the HELIOS default script location 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/settings/Script Server" is automatically exported as a Macintosh and a Windows volume to allow easy viewing of scripts.
- The "Settings" volume simplifies the installation of new customized scripts by users, just copy the new script into the directory "Script Server".
- There is no need to specify the absolute path to the script. The script name(s) specified in "scriptsrv.conf" will automatically be searched in the "Settings" volume.
- All scripts will automatically be changed to be executable (the executable flag will be set for this script)
Note: By default, the Script Server service port can only be reached from localhost. See RemoteAccess in 8.1.6 "Script Server preferences".
Show validated and active configuration lines and statistics:
Hold How many jobs are queued for this script
Run How many jobs are currently running
Done How man jobs are done by this script
Ftype:Suffix:Path:Script:User:Environment
- Hold time (see HoldTime in 8.1.6 "Script Server preferences")
- Default script timeout (see RunTime in 8.1.6 "Script Server preferences")
- Total jobs done (since the service has started)
Status field is filled by script writing Status:- to "stdout" or "stderr", see also 7.5.2 "Status (shown on service port 2024)".
Script Server is started automatically by the Service Controller. Please make sure via "srvutil status" that the "scriptsrv" service is running and there are no error messages in the system messages file.
Every time a custom script is called, the "scriptsrv.log" file contains a information similar to the following:
All standard output, as well as error output of the script is automatically redirected into the "scriptsrv.log" file. Each line is prefixed by time stamp and script name.
Scripts are called with the file name as the first argument, e.g. a host shell script will contain the file name in $1, a Perl script will contain it in $ARGV[0].
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 using it for different hot folders by using different parameters (e.g. printer, ICC profiles, color spaces, etc.).
Script output starting with Status: is not written to "scriptsrv.log" but displayed in the "showq" command output on service port 2024. Intention: if a job takes long time to finish, the script can tell the user (who is monitoring the process on the service port) what is actually done by the script.
It is a good idea to test your scripts first manually in a host terminal session to verify that they work. The Script Server calls all scripts with the current directory set to the HELIOS product directory. Therefore it is required that you first change into the HELIOSDIR before executing a script manually.
cd /usr/local/helios
chmod +x var/settings/Script Server/printps.pl
export HELIOSDIR="/usr/local/helios"
export PRINTER="lw"
export SCRIPTDEBUG=1
export PRINT_TIMEOUT=60
export SCRIPT_EVENT=close
var/scripts/printps "/data/demovol/TestFolder/test.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 a host debugger for C/C++ applications. Simple debugging by printing messages will work as well within the automated Script Server environment. All script output will later 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 scripts required).
An alternative option to test your scripts in a different directory is to create the runperl link in your script directory.
To inspect "holdQueue" and "runQueue", and the configuration of the running "scriptsrv" daemon, connect to service port 2024, and use "showq" for inspecting the queue and "showconf" for inspecting the configuration.
If the configuration line is not displayed this may be due to a syntax error. Detailed error messages are written to the system messages.
If a job matches more than one configuration line, the first matching configuration line is considered.
To switch on the script debug variable SCRIPTDEBUG it is required to set the value to 1 either in the configuration file. You may also set the global debug preference scriptdebug:
Important: The global preference scriptdebug activates debugging for all scripts. Thus, 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!
| © 2005 HELIOS Software GmbH |
|
|
|
|
|
