Difference between revisions of "OS4X Enterprise text template"

From OS4X
Jump to navigation Jump to search
 
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:OS4X Enterprise]]
 
[[Category:OS4X Enterprise]]
Many OS4X Enterprise solutions (plugins like [[OS4X plugin os4xplugin_transmission_pdf|os4xplugin_transmission_pdf]], [[OS4X plugin os4xplugin_email_files|email files]], [[OS4X plugin os4xplugin_approve|approve]]) use templates to dynamically generate text, often used as email. These templates contain variables, which are dynamically replaced. Variables are introduced by a "<code>$</code>" character. This way, XPath expressions are possible on the actual job state in plugins.
+
Many OS4X Enterprise solutions (plugins like [[OS4X plugin os4xplugin_transmission_pdf|transmission PDF]], [[OS4X plugin os4xplugin_email_files|email files]], [[OS4X plugin os4xplugin_approve|approve]], [[OS4X plugin os4xplugin email templating|email templating]]) use templates to dynamically generate text, often used as email. OS4X supports two types of templates:
 +
*template as a file
 +
*template as a database configuration
 +
 
 +
We will migrate step-by-step as many filesystem based templates to the database where possible.
 +
 
 +
= Template variables =
 +
Templates can contain variables, which are dynamically replaced during processing. Variables are introduced by a "<code>$</code>" character. This way, XPath expressions are possible on the actual job state in plugins.
 +
 
 +
Variables end with the occurance of one of the following characters:
 +
*whitespace
 +
*<code>'</code>
 +
*<code>"</code>
 +
*<code>$</code>
 +
*<code>(</code>
 +
*<code>)</code>
 +
*<code>[</code>
 +
*<code>]</code>
 +
*<code><</code>
 +
*<code>></code>
 +
*<code>:</code>
 +
*<code>;</code>
 +
*<code>{</code>
 +
*<code>}</code>
 +
*<code>,</code>
 +
*<code>.</code>
 +
*<code>`</code>
 +
*<code>%</code>
 +
*newline character (<code>\n</code>)
 +
*<code>\</code>
 +
*<code>&</code>
 +
*<code>|</code>
 +
 
 +
Since OS4X release 2020-07-10, the following characters are also a variable separator:
 +
*<code>?</code>
 +
*<code>#</code>
  
 
= Common variables via XPath =
 
= Common variables via XPath =
 
*Job number: <code>$/OS4X_job/job_information/job_number</code>
 
*Job number: <code>$/OS4X_job/job_information/job_number</code>
 
*Job direction ("incoming" or "outgoing)": <code>$/OS4X_job/job_information/job_direction</code>
 
*Job direction ("incoming" or "outgoing)": <code>$/OS4X_job/job_information/job_direction</code>
*Job command: <code>$/OS4X_job/job_information/job_comment</code>
+
*Job comment: <code>$/OS4X_job/job_information/job_comment</code>
  
 
*Sender:
 
*Sender:
Line 22: Line 57:
 
**City (i.e. "Böblingen"): <code>$/OS4X_job/job_information/recipient/location</code>
 
**City (i.e. "Böblingen"): <code>$/OS4X_job/job_information/recipient/location</code>
 
**ZIP code (i.e. "71034"): <code>$/OS4X_job/job_information/recipient/zip_code</code>
 
**ZIP code (i.e. "71034"): <code>$/OS4X_job/job_information/recipient/zip_code</code>
**Company long name: <code>$/OS4X_job/job_information/recipient/partner_longname</code>
+
**Company long name (i.e. "c-works GmbH"): <code>$/OS4X_job/job_information/recipient/partner_longname</code>
  
 
= Special variables =
 
= Special variables =
 
*<code>$JOBFILES_HTML</code>: Generate a HTML list of all files contained in the job (with "<code>ul</code>" and "<code>li</code>" HTML tags)
 
*<code>$JOBFILES_HTML</code>: Generate a HTML list of all files contained in the job (with "<code>ul</code>" and "<code>li</code>" HTML tags)
*<code>$JOBFILES_TEXT</code>: Generate a textual list of all files contained in the job (with "<code>- </code>" as a prefix before the filename)
+
*<code>$JOBFILES_TEXT</code>: Generate a textual list of all files contained in the job (with "<code>- </code>" as a prefix before each filename)
 +
*<code>$JOBCOMMENT_HTML</code>: Formats the job comment (if any given) with newlines changed to HTML "<code><nowiki><br/></nowiki></code>" equivalents.
 +
*<code>$WEBACCESS_URL</code>: [[OS4X_Core_configuration#Webaccess_URL|The configured OS4X Webaccess URL]]
 +
*<code>$WEBACCESS_RESET_PWD_URL</code>: ''(only available in the "forgot password" functionality issued by OS4X Webaccess)'' [[OS4X_Core_configuration#Webaccess_URL|The configured OS4X Webaccess URL]] including a session token for [[OS4X_Webaccess_installation_and_configuration#Password_reset_functionality|resetting password]].
 +
 
 +
Since OS4X release 2023-05-12, the following template variable is available:
 +
*<code>$JOB_SHARE_EMAIL_LIST</code>: A HTML list of email recipients for this job. This list is extracted from the point of time of validity of exection of the plugin.
 +
 
 +
Since OS4X release 2023-11-13, the following template variable is available:
 +
*<code>$MFA_TOKEN</code>: A dynamically created token for [[OS4X Enterprise Webaccess multi-factor authentication|user multi-factor authentication in OS4X Webaccess]].
 +
 
 +
= Handling text templates =
 +
Text templates (stored in the database) can be configured in "Configuration" -> "OS4X Enterprise" -> "Text templates":
 +
 
 +
[[File:Bildschirmfoto 2020-07-13 um 11.06.47.png]]
 +
 
 +
In the opening panel, you can add and edit an unlimited amount of text templates. Editing templates is done via an interactive HTML editor (which strips the HTML and BODY tag away due to security reasons). You can edit the visual outcome with the contained formatting tools in the top toolbar:
 +
 
 +
[[File:Bildschirmfoto 2020-07-13 um 11.09.19.png]]
 +
 
 +
It is also possible to edit the sourcecode directly, making it easier to edit the content for web developers.
 +
 
 +
A pre-set list of templates to be selected makes it easy to use our defaults. Also, a selectable list of often-used XPath expressions help developers to dynamically let variables be used in the template (where applicable).

Latest revision as of 09:34, 14 November 2023

Many OS4X Enterprise solutions (plugins like transmission PDF, email files, approve, email templating) use templates to dynamically generate text, often used as email. OS4X supports two types of templates:

  • template as a file
  • template as a database configuration

We will migrate step-by-step as many filesystem based templates to the database where possible.

Template variables

Templates can contain variables, which are dynamically replaced during processing. Variables are introduced by a "$" character. This way, XPath expressions are possible on the actual job state in plugins.

Variables end with the occurance of one of the following characters:

  • whitespace
  • '
  • "
  • $
  • (
  • )
  • [
  • ]
  • <
  • >
  • :
  • ;
  • {
  • }
  • ,
  • .
  • `
  • %
  • newline character (\n)
  • \
  • &
  • |

Since OS4X release 2020-07-10, the following characters are also a variable separator:

  • ?
  • #

Common variables via XPath

  • Job number: $/OS4X_job/job_information/job_number
  • Job direction ("incoming" or "outgoing)": $/OS4X_job/job_information/job_direction
  • Job comment: $/OS4X_job/job_information/job_comment
  • Sender:
    • Family name (i.e. "Koch"): $/OS4X_job/job_information/sender/surname
    • Name (i.e. "Harald"): $/OS4X_job/job_information/sender/name
    • Email address (i.e. "h.koch@c-works.de"): $/OS4X_job/job_information/sender/email_address
    • Department (i.e. "Development"): $/OS4X_job/job_information/sender/department
    • City (i.e. "Böblingen"): $/OS4X_job/job_information/sender/location
    • ZIP code (i.e. "71034"): $/OS4X_job/job_information/sender/zip_code
  • Recipient:
    • Family name (i.e. "Koch"): $/OS4X_job/job_information/recipient/surname
    • Name (i.e. "Harald"): $/OS4X_job/job_information/recipient/name
    • Email address (i.e. "h.koch@c-works.de"): $/OS4X_job/job_information/recipient/email_address
    • Department (i.e. "Development"): $/OS4X_job/job_information/recipient/department
    • City (i.e. "Böblingen"): $/OS4X_job/job_information/recipient/location
    • ZIP code (i.e. "71034"): $/OS4X_job/job_information/recipient/zip_code
    • Company long name (i.e. "c-works GmbH"): $/OS4X_job/job_information/recipient/partner_longname

Special variables

  • $JOBFILES_HTML: Generate a HTML list of all files contained in the job (with "ul" and "li" HTML tags)
  • $JOBFILES_TEXT: Generate a textual list of all files contained in the job (with "- " as a prefix before each filename)
  • $JOBCOMMENT_HTML: Formats the job comment (if any given) with newlines changed to HTML "<br/>" equivalents.
  • $WEBACCESS_URL: The configured OS4X Webaccess URL
  • $WEBACCESS_RESET_PWD_URL: (only available in the "forgot password" functionality issued by OS4X Webaccess) The configured OS4X Webaccess URL including a session token for resetting password.

Since OS4X release 2023-05-12, the following template variable is available:

  • $JOB_SHARE_EMAIL_LIST: A HTML list of email recipients for this job. This list is extracted from the point of time of validity of exection of the plugin.

Since OS4X release 2023-11-13, the following template variable is available:

Handling text templates

Text templates (stored in the database) can be configured in "Configuration" -> "OS4X Enterprise" -> "Text templates":

Bildschirmfoto 2020-07-13 um 11.06.47.png

In the opening panel, you can add and edit an unlimited amount of text templates. Editing templates is done via an interactive HTML editor (which strips the HTML and BODY tag away due to security reasons). You can edit the visual outcome with the contained formatting tools in the top toolbar:

Bildschirmfoto 2020-07-13 um 11.09.19.png

It is also possible to edit the sourcecode directly, making it easier to edit the content for web developers.

A pre-set list of templates to be selected makes it easy to use our defaults. Also, a selectable list of often-used XPath expressions help developers to dynamically let variables be used in the template (where applicable).