OS4X Server-side plugin philosophy
Server-side OS4X plugins are programs which are executed during job processing. Plugins can be any type of executable: compiled programs, Java programs, shell/Perl/PHP/... scripts. Plugins can be put together into so-called plugin groups.
There are two types of plugins:
- Synchronous plugins: will be executed by the plugin handler. The starting process waits until end of plugin execution.
- Asynchronous plugins: will be executed by the plugin handler and job processing instantly stops. The job receives the status 'waiting for asynchronous plugin'. The plugin itself is responsible to start the asynchronous plugin handler at its end. Asynchronous plugins must understand the parameter "
-c" in order to cancel job processing asynchronously.
Plugins receive an XML as parameter which contain all job parameters. The plugin may modify this XML file. The plugin handler starts the plugin with the last actual XML file, afterwards it reads in this XML file and saves is in the database as the actual XML.
The standard output "stdout" and "stderr" will be read in and saved in the plugins logs, attached to the actual job.
The return code of the executed plugin is received by the plugin handler (synchronous or asynchronous). If the return code is zero (0), job processing continues. If it's non-zero, job processing stops and the job receives the status "aborted".
At the end of plugin execution (even successful or unsuccessful), all files contained in the job XML with the attribute "copy" or "ENGDAT" will be deleted from the filesystem.
Plugin parameters
Plugins must understand several combinations of parameters.
normal behaviour
Plugins receive one parameter: the absolute path of an XML file. All job information will be parsed from this XML file.
normal behaviour with configuration
Plugins receive two parameters: the absolute paths of two XML files. All job information will be parsed from the first XML file, the runtime configuration from the second. More information in the plugin configuration documentation.
automatic plugin installation
The only parameter is "-a". The plugin checks its availability in the plugin database table and its configuration parameters. This mode is usually used for automatic updates and installation.
configuration
In order to display configuration possibilities, plugins may support the parameter "-x". The output of the plugin must be a plugin with a special structure. Refer to the plugin configuration documentation for more information.
asynchronous plugin abort
Asynchronous plugins must understand the parameter "-c" as first parameter in order to cancel the job, given as second parameter.
Synchronity
Asynchronous plugin will cause the job to wait for further external notification in order to continue its work. This is done via the program "os4x_async_plugin_handler".
Starting with OS4X release 2016-06-02, a dynamic handling of (a)synchronity is possible. A plugin may send a signal "SIGUSR1" to a process, which handles the plugin execution. This process is given by the environment variable
OS4X_ENTERPRISE_PLUGIN_MGT_PID
The following two situations can occur:
- An asynchronous plugin will switch to synchronous
- A synchronous plugin will switch to asynchronous
A log message in the plugin logs of a job document this behaviour in detail:
