OS4X internet job sharing

OS4X Enterprise offers a functionality to share OS4X jobs via a simple "share" function. With this function enabled, an OS4X Webaccess user may share an OS4X job via email to a given destination for a given timeframe, optionally secured with a password.

Requirements

For this feature, you need:

• OS4X Enterprise license
• OS4X Release 2015-03-19 or newer installed
• properly configured mail transfer agent for mailing purposes (for OS4Xvirtual users, see the documentation OS4X VMware virtualized image - mail configuration)
• PHP 5.3.7 or newer for security options
• optionally: Apache webserver module "mod_rewrite" active

Configuration

In order to enable the feature, navigate in the administrative web interface to "Configuration" -> "OS4X Enterprise" -> "Webaccess" and activate "Enable job sharing via internet/email?":

By default, the option is disabled. The configuration options have the following meanings:

• External OS4Xapi URL: OS4X Webaccess offers a secured OS4Xapi implementation (in a seperate directory, "webaccess/os4xapi/index.php"), which needs to be available to external communication partners. Many customers offer OS4X Webaccess to external partners, these may offer the subdirectory without problems. Side note: using Apache & mod_rewrite, you can write specific URL rules which have a nicer name for external partners.
• Mail sender address: With this optional setting, you can define the SMTP "From:" field in the sent mail.
• Mail templates (german & english): Absolute path to a file containing the text for the sent mail. See below for usable variables in this mail text.
• Send as HTML: the generated mail will be sent as HTML email.
• Mail subject (german & english): The mail subject.
• Error page: A valid HTML body code which will be displayed to a user who tries to access the service without proper link or with an invalid password.
• Optional recipient for instant sharing: For instantly shared jobs (say: newly created job without a recipient), the mechanism would by default send a job to the logged in user. If this is not wanted, this configuration gives you the possibility to define a recipient for these newly shared jobs (including a special send plugin group for these jobs).
• Restart instant shared jobs for every new sharing: If an optional recipient for instant sharing is configured, each new interactive sharing of the same job will restart the job, including execution of the send plugin group of this recipient (handy for updated information about shared job members).
• Plugin group after share expiration (fault tolerant): If a job sharing expires, a plugin group can be executed on the shared job with his most actual job XML (i.e. for cleanup services). This executed plugin group is fault tolerant, so if any plugin returns with a returncode not equal to zero, the plugin group will continue its work and finish until the end. An aborted expiration plugin group will not change the state of the job.

mod_rewrite

In order to have nice URL names, you can use "mod_rewrite" to beautify the URL. The following rule defines that all URLs "http(s)://somedomain.tld/share" are forwarded to the API call which delivers the file:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^share /webaccess/os4xapi/index.php/job/shared [R=301,L,QSA]
</IfModule>

Mail templating

For the above mentioned "Mail template file" (available in german and english), the content of the file will be interpreted and variables will be substituted with actual values. The following variables are available:

• #link#: The dynamic http(s) link to the shared job.
• #firstName#: The given name of the user initiating the sharing process.
• #lastName#: The family name of the user initiating the sharing process.
• #desc#: A string combining last name and given name, separated by a comma and a space character (i.e. "Koch, Harald")
• #telephone#: The telephone number of the user initiating the sharing process.
• #fax#: The facsimile number of the user initiating the sharing process.
• #email#: The email address of the user initiating the sharing process.
• #country#: The country name of the user initiating the sharing process.
• #department#: The department name of the user initiating the sharing process.
• #location#: The location name of the user initiating the sharing process.
• #company#: The company name of the user initiating the sharing process: if a longname is configured, the longname will be used, otherwise the shortname will be used.

Since OS4X release 2022-06-28, the following variable exists:

• #expirationDateTime#: Date and time of expiration of link. The format of this date and time is the same according to the naming schema of the target language.

The sent mail will be encoded in UTF-8 characters.

The example for this documentation is based on this mail template:

Sehr geehrter Adressat,

#firstName# #lastName# (#email#) hat Ihnen Daten zur Verfügung gestellt:

#link#

Ihr OS4X Enterprise

User interaction

Users can share any viewable jobs where the files are still available (say: archived jobs cannot be shared, since their data files are not available). If a job is downloadable, it is shareable.

Sharing is done in the job detail view. If sharing is enabled, a button appears in the toolbar:

The language of the shared job depends on the user's language in OS4X Webaccess:

• If the user is using the german web interface, the german mail will be sent.
• If the user is using another language, the english mail will be sent.

After clicking on the button, the following window appears:

The user has to enter a valid email address. Optionally, he can assign a password for this shared job. In this case, both password must be the same. The password is hashed securely and not saved in plain text in the database, so later-on recovery is impossible!

The timeframe for availability of this shared link is configurable, by default a timeframe of 48 hours is selected.

After submitting the shared job, the user gets an informational window:

If a password was supplied, the user is informed that this password must be communicated to the data recipient.

Recipient's view

The job recipient obtains the link to the job via the configured email template. An example could be:

The link in this email contains a hash which represents the shared job.

After clicking on the link, OS4X Enterprise offers the data of the file. If an authentification password is configured, the user must prompt his password into a webbrowser prompt field:

The text "Passwort" depends on the language of the shared job:

• For a german shared shared job (say: user is logged in OS4X Webaccess with german language, the mail is sent in german): the text says "Passwort"
• For all other languages, the text says "Password"

Automatic share expiration

The running send queue daemon takes care about expired job shared and deletes them from the shared list.

Logging

Properly accessed jobs which are downloaded by users are logged in the plugin logs of the job:

The log is dynamically build based on the information if the job is shared with a password or without a password.

The cleanup process of shared jobs is logged in the OS4X's system log:

Administration

If job sharing is active, a new menu entry appears in the administrative web interface in "OS4X Enterprise jobs":

With this menu entry, a list of all shared jobs is available:

The information speak for itself:

• With the trash icon button, you can delete an entry.
• The job number is the referenced job.
• User: the initiator of the shared job. This field is clickable in order to administrate the user directly.
• Valid until: the date of expiration of the job share.
• Hash: the unique share hash, which is also included in the link contained the email.
• Password protected: this read-only checkbox shows if the initiator of the job share has given a password.
• URL: The actually available URL to access this shared job. The link is dynamically build upon the above mentioned configuration URL.
• Email: the addressed email for the share link.
• Language: the initiator's user language.

Deleting an entry will be logged in the job's plugin logs: