Create OS4X Enterprise send jobs in batch mode

OS4X Enterprise offers a wide range to automatism, and incoming jobs execute configurable plugins dynamically depending on the recipient. But what about outgoing jobs? That's where this tools fills the gap.

Executing the binary is possible with a valid OS4X Enterprise and OS4X Enterprise Lite license.

Since OS4X release 2021-08-23, this binary can be called as "os4x_create_enterprise_recjob" (which is a symlink to "os4x_create_enterprise_sendjob" to create a receive job instead of a send job.

What you need

As a minimum, you need the following information:

sender of the job
- username (must be unique) - or
- database index value
exactly one recipient
- username (must be unique) - or
- database index value
file(s)

Sender and recipient

Setting a sender or recipient is possible either via the username or the database index value of the person. When used, the username must be unique. If more than one username is found, execution fails. If a numeric index value is given, it will supersede the username information (even is given).

When no valid sender information is given in the XML, the user executing the binary will be searched in the database and set as the actual sender of the job.

When adding the recipient node several times, the toll will send a single to job the first recipient.

File(s)

Files can occur as often as you want. The must-have information are:

filename: The name of the file on the creating side. It may be different than the absolute filename given below. This will give you the chance to handle files with different names in the filesystem logically with another filename in OS4X jobs.
absolute_filename: The absolute path of the readable file in the filesystem.

Optionally, you can add:

file_comment: Any textual comment to the file. This will normally added to the ENGDAT abstract file for outgoing ENGDAT jobs.
compression: depending on your recipient, you may add an information about how the file is being compressed. This attribute may be overwritten by compression plugins in the OS4X job process lifecycle.
plugin_output: Files may be created by plugins or tools, which may create their own output (such as converts, exporters etc.). This node may contain textual information for the file (which may be analyzed by another plugin for further tasks).
os4xeq_params: an optional string containing parameters used for enqueueing files to the OS4X send queue (see parameters of program "os4xeq"). Supported parameters are (generally spoken) all other than "-p", "-f", "-v", "-c", "-i" and "-j".

Formatting the information

The most platform independant and dynamic format is XML. In this case, the tools expects a XML file which contains some well-defined nodes. Example:

<?xml version="1.0" encoding="UTF-8"?>
<OS4X_sendjob>
    <job_comment/>
    <sender>
        <index>3</index>
        <username></username>
    </sender>
    <recipient>
        <index></index>
        <username>test</username>
    </recipient>
    <job_file>
      <filename>os4xlic</filename>
      <absolute_filename>/opt/os4x/bin/os4xlic</absolute_filename>
      <file_comment>filecomment</file_comment>
      <compression/>
      <plugin_output/>
    </job_file>
    <job_file>
      <filename>os4x_licinfo</filename>
      <absolute_filename>/opt/os4x/bin/os4x_licinfo</absolute_filename>
      <file_comment>Filetransmitted with fixed record length of 128 bytes</file_comment>
      <compression/>
      <plugin_output/>
      <os4xeq_params>-F 128</os4xeq_params>
    </job_file>
</OS4X_sendjob>

Execution syntax

When executing the binary without any parameters or with parameter "-h", the parameter help is being displayed:

imac-i7:bin os4x$ ./os4x_create_enterprise_sendjob -h
OS4X create enterprise send job v1.2

usage:
-h: print this help text
-C <configfile>: use given config file (default: /etc/os4x.conf)
-i <serverID>: start as server with ID <serverID> (default: 0)
-x <XML file>: XML file describing a send job, see online help for details
-d: verbose mode (don't daemonize)

The parameters are:

-C: optional config file in case you don't want to use the default "/etc/os4x.con"
-i: the server ID overriding the configured one in "/etc/os4x.conf"
-x: the above described XML file
-d: verbose mode, don't run any program in the background, display more information

Since OS4X release 2021-11-29, running the program in verbose mode with "-d" will display the job number and also all calls of plugins including return code and runtime information.

Examples

These examples are using the XML file from above. The user "test" exists in the databse, also the recipient user with the database index value "3".

Sending two file from user "test" to user "test"

imac-i7:bin os4x$ /opt/os4x/bin/os4x_create_enterprise_sendjob -x /tmp/os4x-1.xml

No more output will be written.

Sending two file from user "test" to user "test" with verbose output

imac-i7:bin os4x$ /opt/os4x/bin/os4x_create_enterprise_sendjob -d -x /tmp/os4x-1.xml
License valid
Enabled verbose mode
parsing XML file '/tmp/os4x-1.xml'
 found file: [os4xlic] -> [/opt/os4x/bin/os4xlic]
 found file: [os4x_licinfo] -> [/opt/os4x/bin/os4x_licinfo]
* OS4X Enterprise job number: 631
* executing plugin [filetype recognizer]... OK
* executing plugin [ENGDAT v2 encode]... OK
* executing plugin [enqueue to OS4X]... OK

Sending two file from user "test" to user a recipient without a configured send plugin group, with verbose output

imac-i7:bin os4x$ /opt/os4x/bin/os4x_create_enterprise_sendjob -d -x /tmp/os4x-3.xml
License valid
Enabled verbose mode
parsing XML file '/tmp/os4x-3.xml'
 found file: [os4xlic] -> [/opt/os4x/bin/os4xlic]
 found file: [os4x_licinfo] -> [/opt/os4x/bin/os4x_licinfo]
* OS4X Enterprise job number: 638
ERROR: No plugin group defined as send plugin group for recipient -> aborting job.

An OS4X send job has been created with the ID 638, but it has reached the status "aborted". You may reconfigure the corresponding recipient (i.e. at company level) and restart the job.

Os4x create enterprise sendjob

Contents