OS4X internet job invitation

OS4X Enterprise offers a mechanism to invite persons via email address to upload data to your OS4X installation, so incoming jobs will be generated. This easy-to-use mechanism is integrated in OS4X Webaccess and is called "ExtUpload".

A little Youtube video demonstrates the functionality: https://youtu.be/5eg871Ib8K8

Requirements

For this feature, you need:

• OS4X Enterprise license
• OS4X Release 2017-01-12 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

On client side, the following webbrowser are supported:

• Internet Explorrer 10 and up
• Firefox 22 and up
• Chrome 21 and up

Any other web browser could (but must not) result into unpredictable results.

Configuration

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

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

• External URL of "ExtUpload": OS4X Enterprise offers a special web application "ExtUpload" (in a separate directory, "ExtUpload" in the web server root directory), which needs to be available to external communication partners. Side note: using Apache & mod_rewrite, you can write specific URL rules which have a nicer name for external partners.
• Temporary upload directory: this is the directory where invited users will create subdirectories containing their uploaded files. Also see "splitting installations" below.
• 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.
• Session timeout: invitation sessions are valid for a configurable time frame. With this value, you can define the maximum validity time.
• Encrypt/Compress session information: the session information of invitations include the expiration date and the invitee numeric database value. This information can optionally be encrypted and/or compressed.
• Intro page: The optional content of this HTML field is being included in the header of the ExtUpload web page. Any valid HTML code is allowed via template.

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/ExtUpload" are forwarded to the corresponding web site:

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteRule ^ExtUpload /ExtUpload [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.
• #durationDays#: The configurable amount of days of validity of the invitation.
• #comment#: The optional comment given by the user of the invitation.

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

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

<html><body>
Sehr geehrter Adressat,<br>
<br>
#firstName# #lastName# (#email#) lädt Sie ein, Daten an ihn/sie hochzuladen. Sie erreichen das bequeme Webinterface unter:<br>
<br>
#link#<br>
<br>
Dieser Link ist für #durationDays# Tage gültig.<br>
<br>
<br>
Ihr OS4X Enterprise<BR>
</body><html>

User interaction

Users can invite any email recipient via OS4X Webaccess. If job invitation is enabled, a button appears in the toolbar of the job list:

The language of the invitation 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, a checkbox defines that the sent invitation only works for exactly one finished transaction. Cancelled or not yet finished transactions are not taken into account.

After having sent the invitation, an informational window appears:

Recipient's view

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

After clicking on the link a simple upload form will be presented to the user:

The upper-left content is being dynamically retrieved from the configuration.

Behaviour

The following rules apply to the upload panel:

• Finishing a job is only possible if:
  • at least one file is successfully uploaded
  • no aborted (say: red) files exist in the upload panel
• Cancelling a job deletes all uploaded files on the webserver
• When finishing a job, the session is being examined if it was configured by the user as "one-time" operation. If yes, the session will be deleted
• After successfully finishing a job, the web page forwards again to itself
• When accessing the upload website multiple times in parallel (and the session is not configured as one-time session), multiple parallel jobs can be created. They will be distinct by each other.
• When accessing the site via link with invalid parameters, the user will receive an error page.
• The default language depends on the web browser's user agent setting. Switching the language on-the-fly is possible by clicking on the flag icon without loosing uploaded files.
• When finishing a job, a new OS4X Enterprise receive job will be created (sender: the newly created recipient; recipient: the user who created the invitation). The resolved plugin group of the recipient will be executed.

Internal OS4X Enterprise

• When creating an invitation link, OS4X checks if an active recipient exists for the given email address.
• If not, a new recipient will be created:
  • Partner: extUpload or the "define own company" setting
  • Location: "extUpload"
  • Department: "extUpload"
  • Recipient: Family name and email address is the given email address. This recipient is not editable by the administrator:

The newly created "extUpload" recipient is not addressable by other users.

Administration

When the feature is enabled, a new menu entry will be available in the administrative web interface in "OS4X Enterprise jobs": "Job invitations".

Via this web interface, you can access all required information. Deleting sessions is possible, too.

Technical considerations

When splitting the ExtUpload web interface to another web server, the following requirements must be fulfilled:

• The main configuration file "/etc/os4x.conf" is being used with all its functionality (i.e. target OS4X client daemon running server, "CLIENTD_OVERRIDDEN_HOST")
• The directory for temporary file upload on the external webserver must be mounted on the server which is running the OS4X client daemon at the same location.
• The web server must be able to communicate via port 60'000 (TCP) to the server running the OS4X client daemon.
• The PHP settings (mainly "upload_max_filesize" & "post_max_size") must be set as in an internal OS4X configuration.
• The directory "ExtUpload" must be presented to the external network.
• Design the executed plugin group of internal recipient of jobs in a way where the uploaded files will be deleted from their original position (i.e. via plugin "Delete initial job directory"). This way, the uploaded file data is available for a very short time in the external network zone.
• The database of OS4X must be (at least in parts) available in the web server instance. The required database tables are (here with default prefix "os4x_":
  • os4x_configuration
  • os4x_extupload_sessions