ImageServer G8 User manual (Version 6.0.0)  

7 HELIOS Script Server

HELIOS ImageServer includes the 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.

Major features of the Script Server are:

Any folder within a HELIOS volume can act as a hot folder for the Script Server. HELIOS provides a variety of sample scripts for different file formats and purposes.

A detailed description on starting/stopping and refreshing the Script Server process, the included sample scripts, and on debugging scripts can be found in 7.3 “Start, stop and refresh the Script Server process” and 7.4 “Included sample scripts”.

7.1 Script Server settings

The HELIOS Script Server is configured in HELIOS Admin.


From the Settings menu in HELIOS Admin open the “Script Server Settings” window (Fig. 7.1).

The Script Delay field allows specifying the time interval before the script is started after the file event is received. Script Timeout specifies the maximum script runtime. The value 0 may let the script run forever. Simultaneous Scripts determines the maximum number of concurrently executing scripts in order to limit server load. The value for Simultaneous Scripts should be less or equal to the number of physical CPUs. If you leave this field empty Script Server determines an appropriate value by checking the number of CPUs.

HELIOS Admin “Script Server Settings” window

Fig. 7.1: HELIOS Admin “Script Server Settings” window

7.1.1 Configure a script queue

In the Scripts (Fig. 7.2) tab you can set up script queues with different configurations for different purposes.


If the Scripts tab is not available after the first login, activate Scripts in the Lists menu.

All script queues configured on the host are listed in this window. The HELIOS Admin server automatically creates it by inspecting script related entries in the “Preferences” file.

HELIOS Admin <code>Scripts</code> tab

Fig. 7.2: HELIOS Admin Scripts tab

The Name column shows the script queue name, while the used script itself is displayed in the Script column.

Wait, Run and Done list the status of the script queues. Wait means that they are spooled but not yet processed. Run signifies that a script queue is being processed, and Done that the script has finished.

The path to the specified hot folder, the place where the script “looks” for files or directories to be processed, is displayed in the Hot Folder column. Types and Suffixes list all defined file types and file suffixes per queue.

Change script data

Script queue settings for a particular script queue are changed in the Script window (Fig. 7.3):


Select the desired script queue from the list and choose Settings from the Script menu.

HELIOS Admin “Script” window – <code>General</code> tab

Fig. 7.3: HELIOS Admin “Script” window – General tab

The General tab (Fig. 7.3) shows the general settings for the particular queue. The Enable checkbox activates the queue for the Script Server. If a script queue is not enabled the queue name in the Scripts list appears grayed out (see “PDF_print” entry in Fig. 7.2).


Specify a name for the script queue in the Name field and the desired script in the Script field. You may write the script path and name directly into the field or select it by use of the Browse... button.


If two or more script queues use the same hot folder, and do not differ in file type or suffix specification, the scripts are executed in alphabetical order. You may have to rename the script queue names according to your needs.

A click on the icon (see arrow in Fig. 7.3) opens the selected script file for editing. You may also choose Open from the File menu.


Specify the path to the hot folder in the Hot Folder field, either manually or via the Browse... button.


Make sure that the specified path already exists. Otherwise Script Server will ignore the configuration!

The Include Subdirectories checkbox is inactive by default. This avoids subdirectories in the specified path being considered as hot folders as well. However, if it is desired that all subdirectories underneath the specified path are considered, this checkbox must be switched on.

The user name the script should run as can be entered in the User field. If this field is left empty, the script is executed as superuser.


On Windows systems the User field requires setting the existing user password again using the HELIOS “authutil” tool, e.g.: authutil passwd -n user -p passwd. This information will be used to run the script under the specified user account.

The Timeout field determines the maximum script runtime. The value 0 may let the script run forever. If a value is specified in this field, it overrides the global setting (compare to Fig. 7.1).

The Debugging checkbox specifies whether verbose output is written. The value is exported as SCRIPTDEBUG environment to the script.

To make the hot folder react only on certain file types and suffixes, you must define these for the script queue. File types and suffixes are added in the File Types tab (Fig. 7.4).


Enter the 4-character file type code into the respective field and click the Add button. Do likewise for the file suffix.


The file type specification always demands 4 characters, even if blanks are included, e.g. “PDF ”.

HELIOS Admin “Script” window – <code>File Types</code> tab

Fig. 7.4: HELIOS Admin “Script” window – File Types tab

Enable the option Folder Changes if you wish that directory events rather than file events are notified to the Script Server. In this case, file events are ignored and the Types and the Suffixes column in the Scripts list appear grayed out and the settings are ignored. In addition, the leading icon changes from a “files” symbol to a “directory” symbol (see third entry in Fig. 7.2).

Script Server scripts can be formatted in such a way (see 7.1.2 “Automatic Script Server configuration”), that specified variables and their default values are shown in the Environment tab (Fig. 7.5). Such variables can be viewed and edited by double-clicking the variable name, entering the new value, and then clicking Add.

In addition, other variables in the script can be entered here, along with their value. Note that the script must check for (and use) these declared environment values in order for them to have any effect.


Environment variables are handed over to Perl via shell. Therefore, used characters are limited to ASCII. This is because some shells (especially on Windows) as well as Perl are not able to handle all UTF-8 characters.

To remove an entry from the Environment list, highlight it and select Clear from the Edit menu. Another way is to double-click the entry, which makes it disappear from the list, whereas variable and value are displayed in the definition fields.

HELIOS Admin “Script” window – <code>Environment</code> tab

Fig. 7.5: HELIOS Admin “Script” window – Environment tab

Create a script queue

A new script queue is created as follows:


In HELIOS Admin activate the Scripts tab and choose New from the File menu.

If you wish to create a new script queue that should adopt most of the settings of an already existing queue, a very convenient way is to duplicate the script queue data by copying a queue entry from the Scripts list and then pasting it into the list. A script queue data window opens to adjust the settings for the new queue. Instead of copying/pasting the script queue entry you may also highlight it in the Scripts list and drag it with the mouse within the list.

After filling in the script queue data window and confirming the changes, the new script queue is added to the list. If the script queue data window is closed without saving, the new script queue entry is discarded.

Delete a script queue

A script queue is deleted as follows:


In the Scripts list highlight the script queue that you wish to delete and choose Clear from the Edit menu, or just click the toolbar trash can icon.

7.1.2 Automatic Script Server configuration

When setting up a new script queue, HELIOS Admin can read out the configuration from the referenced script and complete the respective fields with default values. For this to work, the script must contain the configuration data in the SETTINGS section. Furthermore, the script must be selected via the Browse... button (compare Fig. 7.3). The following example shows, in a script excerpt for the queue “For_HTML”, the defined default configuration values:

# $Id:

# Sample configuration
my $default_settings = <<'</SETTINGS>'; # Let Perl ignore the settings block

Each time a script has been selected via the Browse... button in the General tab, an additional button – Defaults from Script File – becomes available in both the File Types and Environment tabs (Fig. 7.6 and Fig. 7.7). Defaults from Script File allows restoring the default settings which are defined in the selected script.

HELIOS Admin “Script” window – <code>File Types</code> tab

Fig. 7.6: HELIOS Admin “Script” window – File Types tab

HELIOS Admin “Script” window – <code>Environment</code> tab

Fig. 7.7: HELIOS Admin “Script” window – Environment tab

7.1.3 “Script Jobs” window

The status of a script queue is displayed in the “Script Jobs” window (opened by double-clicking the script queue). As soon as a script starts being spooled, “Waiting” is displayed in the Script Status column. When it is being executed, the status changes to “Running”. The moment the script has been accomplished, “Running” disappears from the Script Status column. The accounting (see arrow in Fig. 7.8) informs about the status of all processed jobs, and additionally counts the accomplished jobs (“Done”).


The accounting is reset if the configuration is changed or the “scriptsrv” process is restarted.

HELIOS Admin “Script Jobs” window

Fig. 7.8: HELIOS Admin “Script Jobs” window

7.2 Script Server log files

The Script Server log file lists script actions or Script Server processes, with date and time (Fig. 7.9).

Script Server log files are arranged by date. Every night at midnight the log files are reset, i.e. the logs of the last seven days are renamed; 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.


Select Script Server Log Files from the Lists menu and specify the required day.

Script Server log file on host “ankh”

Fig. 7.9: Script Server log file on host “ankh”


Choose Save as... from the File menu to save the complete Script Server log file as a text file.

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.log.6” (“Seven Days Ago”).

7.2.1 Script Server log file structure

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:

date time scriptsrv[pid] or script: message

HELIOS Admin does a live update of the displayed Script Server log files (Lists > Script Server Log Files).

7.3 Start, stop and refresh 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”:


The “srvutil” utility can be found in “HELIOSDIR/bin”.

Stop “scriptsrv”
# srvutil stop scriptsrv

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.

Start “scriptsrv”
# srvutil start scriptsrv

Starts the “scriptsrv” services.

7.4 Included sample scripts


HELIOS ScriptAssistant (see 7.6 “ScriptAssistant”) simplifies the creation of standard hot folder setups. It generates scripts for the HELIOS Script Server hot folder automation system, to automate HELIOS server capabilities.

A variety of sample scripts can be accessed after mounting the “Settings” volume:

Call a Photoshop action (CS2)

Print PostScript files to a specified printer.

Print text files to a specified printer.

Applies the Photoshop sharpening filter to an image (CS3).

The following scripts require that PDF HandShake be installed on the same host:

Convert a HTML page to a PDF document.

Analyze and preflight PDF files. Also performs PDF-to-PDF color conversion.

Flatten transparencies in a PDF document.

Replace OPI images and forms in PDF documents. The environment variable RESOLVEOPTION allows specifying additional command line parameters for “”.

Convert a PDF document to a BMP image file.

Print a PDF file to a specified PostScript printer.

A more advanced PDF printing script, which allows specifying common parameters.

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.

In the following scripts, image conversion of PDF files does require PDF HandShake:

Convert all supported ImageServer file types into TIFF CIELab and move converted files to OUTDIR.

Generate a 128x128 pixel PNG file and move final PNG file into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB.

Generate a 128x128 pixel JPEG file and move final JPEG files into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB.

7.4.1 HELIOS default scripts location

We recommend to copy all scripts into the “Script Server” directory in the “Settings” volume. The benefits of the HELIOS default script location are:

7.5 Script Server service port

The Script Server service port is 2024.


Issue the command socket localhost 2024, type help for the command overview and quit to leave.


By default, the Script Server service port can only be reached from localhost. See RemoteAccess in 9.1.7 “Script queue preferences”.


Show validated and active configuration lines.

$ cd /usr/local/helios/
$ bin/socket localhost 2024 
Welcome to the HELIOS Script Server service port 
# Config of scriptsrv 
Hold time: 10 
Default script timeout: 120 
# Queue name:Ftype:Suffix:Hotfolder:Script:User:Environment 

Additional global information:


Show status of current jobs queued for processing in the hold, termination and run syntax:

h File Scriptname User
t File Scriptname User
r File Scriptname User Status
r "/demovol/Hotfolder%0/pdfresolve/PDF-native OPI.pdf" "pdfresolve"
  "hendrik" "Status: Running pdfresolve for file /demovol/Hotfolder%0/
  pdfresolve/PDF-native OPI.pdf"
h "/demovol/Hotfolder%0/pdfresolve/manual.pdf" "pdfresolve" "hendrik"
h "/demovol/Hotfolder%0/pdfresolve/data_sheet.pdf" "pdfresolve"

Status field is filled by script writing Status:... to “stdout” or “stderr”, see also 7.7.2 “Status (shown on service port 2024)”.


Shows waiting, running, and finished jobs since the service has started. This can be used to debug/watch if the script is working correctly.

Total jobs done: 109
# Queue: Hold, Run, Done
HTML2PDF: 3, 0, 50
macpdfflatten: 5, 1, 28
pdfresolve: 0, 1, 14

7.6 ScriptAssistant

HELIOS ScriptAssistant simplifies the creation of standard hot folder setups on Mac and Windows. It generates scripts for the HELIOS Script Server hot folder automation system, to automate server capabilities. Simply select the desired options, and ScriptAssistant will create a Perl script, ready for use by Script Server. No scripting or programming knowledge is needed.

ScriptAssistant helps create custom scripts for image conversion, PDF and PostScript printing, and PDF-native OPI image replacement, as well as automation of client applications via HELIOS Tool Server.

The ScriptAssistant task selection dialog

Fig. 7.10: The ScriptAssistant task selection dialog

7.6.1 Usage


When HELIOS ScriptAssistant is launched, the “Introduction” dialog window automatically opens. Here the preferred language for the manual pages can be specified. Menu items allow opening new ScriptAssistant windows, or opening an existing ScriptAssistant script. The “Help” menu opens a feedback form. On each dialog page, there is a ICON link to the relevant manual page on the HELIOS website. This help describes each option more fully. All HELIOS manuals are also included in PDF format in the “HELIOS Applications” volume.


Each control provides a tooltip which references e.g. the command-line option behind it.

Saving scripts

Once a script configuration is completed, the “Save Script” dialog contains instructions on how to save the script, and copy it to the “Script Server” folder in the “Settings” volume on your HELIOS server. It is suggested that scripts be saved with descriptive file names. It may also be desirable to differentiate ScriptAssistant created scripts from other Script Server scripts, either by file naming convention, or by saving them into a subfolder.

Revising existing scripts using ScriptAssistant

Existing ScriptAssistant scripts can be reopened in ScriptAssistant and revised as needed. For example, on occasion it may be desirable to modify the settings for an existing hot folder. Or, if many hot folders are to be enabled, with only slight differences (e.g. different ICC profiles), a script could be created, then reopened and revised for each different hot folder, with each revised version saved under a new name.

Manually editing ScriptAssistant scripts

For those with Perl scripting know-how, it may on occasion be desirable to manually edit ScriptAssistant created scripts. For example, if many hot folders are to be enabled, with only slight differences (e.g. different ICC profiles), then an environment variable could be added so that users could use HELIOS Admin to easily specify the value for each hot folder (see 7.1.2 “Automatic Script Server configuration”). Thus only one master script would be needed instead of multiple scripts. Or, it may be necessary to manually edit a script in order to add options not available in ScriptAssistant. Note that any manual changes will be lost if a manually revised script is reopened in ScriptAssistant and then saved. A warning dialog alerts the user upon opening such files, and the “Save Script” window provides an additional warning (see Fig. 7.11).

Modified script alert

Fig. 7.11: Modified script alert

ScriptAssistant as a learning tool

ScriptAssistant generated scripts, along with the included sample scripts, can be used to learn the proper syntax of the various HELIOS commands, and to study Perl scripting itself. The actual command line output for each script can be viewed in the Script Server log file if the Debugging checkbox is selected in the Script Server script setup dialog.

7.6.2 The “Tasks”

Image conversion

Generates scripts utilizing the ImageServer “layout” command. The “layout” program is a general purpose image conversion engine, with the highest quality output. With over 100 image conversion options, it is very powerful, but can also be complex. ScriptAssistant simplifies the procedure by allowing the easy selection of conversion options such as image file format, color space, compression, resolution, dimensions, color and channel options, bit-depth, ICC settings, metadata options, and more. As you proceed through the dialogs, ScriptAssistant shows only options that are compatible with the options already selected.

Image preflight

Generates scripts utilizing the ImageServer “oiimginfo” command. It allows checking image resolution, pixel count, color space, ICC profile, etc.

Image tagging

Generates scripts utilizing the HELIOS “layout” command. It allows adding or removing ICC profiles, removing paths and IPTC or XMP metadata, setting or removing a clipping path, and changing image resolution or dimensions.

PDF printing

Generates scripts utilizing the PDF HandShake “pdfprint” command. The “pdfprint” program prints a PDF file to PostScript, with options to specify the printer queue, page setup, color and font options, and ICC settings.

PostScript printing

Generates scripts utilizing the HELIOS “lpr” command. The “lpr” program prints a PostScript or EPS file to a print queue.

PDF-native OPI

Generates scripts utilizing the PDF HandShake “pdfresolve” command. The “pdfresolve” program performs PDF-native OPI image replacement and content repurposing (e.g. ICC color matching) in PDF files, with extensive options, for color and ICC settings, image bit-depth, compression, PDF page box, and more.

Remote Tool Server

Generates scripts utilizing the HELIOS “toolclient” command. The “toolclient” program finds, connects to, and sends/receives files to/from a tool server. Tool Server makes automating remote applications/tools very easy. A click on the ScriptAssistant ICON button allows you to read the Tool Server manual for instructions on how to install the HELIOS Tool Server on each Mac or Windows or UNIX client to work as a tool server, and how to enable the desired tool server script(s) by copying them into the “Tool Server” folder.

7.6.3 Requirements

7.6.4 Installation


Mount the “HELIOS Applications” volume, open the “Windows” folder (Mac: “MacOS”), then “ImageServer Tools” and “HELIOS ScriptAssistant”.

Mac only:


Mount “HELIOS ScriptAssistant.dmg” and copy the application to your local harddisk.

Windows only:


Extract the “HELIOS” archive to your local harddisk. “HELIOS ScriptAssistant.exe” needs the “HELIOS ScriptAssistant Libs” directory. “HELIOS ScriptAssistant.exe” must not be moved alone.

7.6.5 Uninstallation

To uninstall HELIOS ScriptAssistant delete the “HELIOS” (Mac) or the “HELIOS ScriptAssistant” directory (Windows), respectively.

7.7 Developing and debugging scripts

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.

All valid registrations for different scripts are displayed via port 2024.

Every time a custom script is called, the “scriptsrv.log” file contains a information similar to the following:

29.07.2005 18:00:07 scriptsrv [1747]: Create process[1854] job added by tim 
29.07.2005 18:00:17 scriptsrv [1747]: Process[1854] done

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.

7.7.1 Script parameters

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].

These parameters are provided via environment variables:


Verbose output is written.


Is set by the server. Available events are close, rename, dircreate, dirclose, delete, dirdelete, dirrename, and exchange.


Name of the user that triggered the event.


Map script to serial number of the ImageServer installation. This environment variable can be set, e.g. to prevent that a script is distributed.


Absolute path of the hot folder.


Name of the script.


If set, it overrides the global preference RunTime (see 9.1.6 “Script Server preferences”).


Is set by the server and can be evaluated in the script containing the old name, if the event is move or dirmove.

Additional custom parameters can be specified in the Environment tab (Fig. 7.5). 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).

7.7.2 Status (shown on service port 2024)

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.

7.7.3 Debugging scripts stand-alone (without Script Server)

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.

Manual call of a stand-alone script, (“”), with a bash or Bourne shell:

# cd /usr/local/helios 
# chmod +x var/settings/Script Server/ 
# export HELIOSDIR="/usr/local/helios" 
# export PRINTER="lw" 
# export SCRIPTDEBUG=1 
# export PRINT_TIMEOUT=60 
# export SCRIPT_EVENT=close 
# var/settings/Script Server/ "/data/demovol/TestFolder/"

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.


Every HELIOS Perl sample contains the following file magic:

#!var/run/runperl -w

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 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.

 (e.g. on OS X or Linux):
# cd /home/myhome 
# mkdir -p var/run 
# ln -s /usr/bin/perl var/run/runperl

7.7.4 Debugging scripts in the Script Server environment

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 a job matches more than one configuration, only the first matching configuration in alphabetical order is considered.

To switch on the script debug variable SCRIPTDEBUG it is required to set the value to 1. You may also set the global debug preference scriptdebug:

# prefvalue -k Programs/scriptsrv/scriptdebug -t int 1

Delete the scriptdebug preference via:

# prefvalue -k Programs/scriptsrv/scriptdebug -d

Find a description of the “prefvalue” program in the HELIOS Base manual.


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 may produce heavy load on the server and can cause significant slow-down of the server!

7.8 Additional considerations

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 in which the hot folder resides.

HELIOS Website © 2020 HELIOS Software GmbH  
HELIOS Manuals October 14, 2021