Difference between revisions of "OS4X internet job invitation"

Revision as of 07:27, 13 January 2017

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.

Requirements

For this feature, you need:

OS4X Enterprise license
OS4X Release 2017-01-11 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 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 seperate 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.

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.

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 unfinished transactions are not taken into account.

After having sent the invitation, an informational window appears:

Recipient's view

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

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

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

@@ Line 90: / Line 90: @@
 [[Image:MailScreenSnapz015.png]]
+After clicking on the link, the user will be presented a simple upload form:
+[[Image:Google ChromeScreenSnapz386.png]]
+The upper-left content is being dynamically obtained from the configuration.