Difference between revisions of "OS4X plugin os4xplugin approve"
| (9 intermediate revisions by the same user not shown) | |||
| Line 16: | Line 16: | ||
*partner | *partner | ||
| − | If no approver is configured, the plugin continues synchronously and the plugin group continues its work. | + | If no approver is configured, the plugin continues synchronously and the plugin group continues its work without the need to ask for permission to continue. |
If an approver is found, the plugin switches to asynchronous mode (see [[OS4X Server-side plugin philosophy]] for more details on synchronity of plugins). | If an approver is found, the plugin switches to asynchronous mode (see [[OS4X Server-side plugin philosophy]] for more details on synchronity of plugins). | ||
The approver receives an email, rendered with the email template (see below). It typically includes an accept and a deny hyperlink. After clicking on the appropriate link, the job does: | The approver receives an email, rendered with the email template (see below). It typically includes an accept and a deny hyperlink. After clicking on the appropriate link, the job does: | ||
| − | *Accept: A log entry will be added to the job's plugin logs with detailled approver information. The job continues its configured plugin group. | + | *Accept: A log entry will be added to the job's plugin logs with detailled approver information. The job continues its configured plugin group with the next step. |
*Deny: A log entry will be added to the job's plugin logs with detailled approver information. The job will be cancelled. | *Deny: A log entry will be added to the job's plugin logs with detailled approver information. The job will be cancelled. | ||
| Line 29: | Line 29: | ||
== Plugin configuration == | == Plugin configuration == | ||
| − | All plugin configuration is done in the administrative web interface OS4Xadmin in "Configuration" -> "Enterprise" -> "Plugins" -> "Approve plugin": | + | All plugin configuration is done in the administrative web interface OS4Xadmin in "Configuration" -> "OS4X Enterprise" -> "Plugins" -> "Approve plugin": |
[[File:Bildschirmfoto 2020-05-08 um 12.46.53.png]] | [[File:Bildschirmfoto 2020-05-08 um 12.46.53.png]] | ||
The meaning of the configuration values is as follows: | The meaning of the configuration values is as follows: | ||
| − | *Alternative mail FROM address: The sender of the approving email. By default, it is "OS4X <os4x>". It may be required to configure a defined value for some MTA | + | *Alternative mail FROM address: The sender of the approving email. By default, it is "OS4X <os4x>". It may be required to configure a defined value for some MTA to work. |
*Mail subject: The subject of the approver email. This configuration option supports XPath expressions on the OS4X Enterprise job's XML. | *Mail subject: The subject of the approver email. This configuration option supports XPath expressions on the OS4X Enterprise job's XML. | ||
**default value: <code>OS4X-Auftrag $/OS4X_job/job_information/job_number an $/OS4X_job/job_information/recipient/partner_longname benötigt Freigabe</code> | **default value: <code>OS4X-Auftrag $/OS4X_job/job_information/job_number an $/OS4X_job/job_information/recipient/partner_longname benötigt Freigabe</code> | ||
*Send subject UTF-8 encoded?: If required, it is possible to send email subject as UTF-8 (with a special email encoding). | *Send subject UTF-8 encoded?: If required, it is possible to send email subject as UTF-8 (with a special email encoding). | ||
*Debug mail execution?: If mailing fails, you can enable debug output for analysis reasons. | *Debug mail execution?: If mailing fails, you can enable debug output for analysis reasons. | ||
| − | *MTA (sendmail) command: | + | *MTA (sendmail) command: An overridden sendmail MTA command can be configured. |
**default: (empty) <code>sendmail</code> | **default: (empty) <code>sendmail</code> | ||
*URL to approve API: A resolvable URL for the approver. This URL is the OS4Xapi part of the approving, so it must be available over network of the approver. | *URL to approve API: A resolvable URL for the approver. This URL is the OS4Xapi part of the approving, so it must be available over network of the approver. | ||
**Example values: http://my-os4x-server/webaccess/os4xapi/index.php/job/approve | **Example values: http://my-os4x-server/webaccess/os4xapi/index.php/job/approve | ||
| − | *Send email as HTML?: For nice layout, HTML emails are possible ( | + | *Send email as HTML?: For nice layout, HTML emails are possible (activated by default). |
| − | + | ||
| + | Templates: | ||
| + | In HTML mode, the leading and closing "HTML" and "BODY" tag will dynamically added by OS4X, since the editor removes them due to security reasons. | ||
| + | |||
| + | *Mail template: content of the email sent to the approver. | ||
| + | *Positive approve page: Page displayed to the approving person after a successful approving process. | ||
| + | *Deny page: Page displayed to the approving person after a successful denying process. | ||
| + | *Error page: Page displayed to the approving person after an unsuccessful process (when approving or denying fails). | ||
== Approver configuration == | == Approver configuration == | ||
| + | Approving person can be defined in all hierarchy levels. The contact can be selected, changed, reverted (to none), and edited: | ||
| + | |||
| + | [[File:Bildschirmfoto 2020-05-08 um 13.25.17.png]] | ||
= Mail template variables = | = Mail template variables = | ||
| + | Beside the typical [[OS4X Enterprise text template|template rules]] for dynamic content generation, the approve plugin contains two specific variables: | ||
| + | *<code>$approveLink</code> | ||
| + | *<code>$denyLink</code> | ||
| + | |||
| + | These links are using the configured "URL to approve API" (see above) for creating dynamically links. These hyperlinks contain the generated dynamic hashes used for approving or denying a job. | ||
| + | |||
| + | Also keep in mind the handy special variables | ||
| + | *<code>JOBFILES_HTML</code>: Generate a HTML list of all files contained in the job (with "ul" and "li" HTML tags) | ||
| + | *<code>JOBFILES_TEXT</code>: Generate a textual list of all files contained in the job (with "- " as a prefix before the filename) | ||
| + | |||
| + | = Mail example = | ||
| + | A sample mail may look like this: | ||
| + | |||
| + | [[File:Bildschirmfoto 2020-05-08 um 13.29.35.png]] | ||
Latest revision as of 14:17, 8 May 2020
Purpose
Job approving means that an OS4X Enterprise job stops processing at a given plugin group position, a configured person is informed via email with two decision options whether to accept or deny the further processing of the job.
Plugin group configuration
In order to make the approve plugin work, you have to add it to your executed plugin group(s) where required. This is typically at a given time before sending data, so before executing the transmission plugins (such as "enqueue to OS4X", "SCP upload", "email files" etc.).
Behaviour
When the "Approve" plugin is being executed, it makes configuration consistency checks. If they succeed, a configured approving person is being searched for in the following order (the first occurance stops further searching):
- recipient
- department
- location
- partner
If no approver is configured, the plugin continues synchronously and the plugin group continues its work without the need to ask for permission to continue.
If an approver is found, the plugin switches to asynchronous mode (see OS4X Server-side plugin philosophy for more details on synchronity of plugins). The approver receives an email, rendered with the email template (see below). It typically includes an accept and a deny hyperlink. After clicking on the appropriate link, the job does:
- Accept: A log entry will be added to the job's plugin logs with detailled approver information. The job continues its configured plugin group with the next step.
- Deny: A log entry will be added to the job's plugin logs with detailled approver information. The job will be cancelled.
Configuration
Configuration is done in two parters:
- Plugin configuration
- Approver configuration
Plugin configuration
All plugin configuration is done in the administrative web interface OS4Xadmin in "Configuration" -> "OS4X Enterprise" -> "Plugins" -> "Approve plugin":
The meaning of the configuration values is as follows:
- Alternative mail FROM address: The sender of the approving email. By default, it is "OS4X <os4x>". It may be required to configure a defined value for some MTA to work.
- Mail subject: The subject of the approver email. This configuration option supports XPath expressions on the OS4X Enterprise job's XML.
- default value:
OS4X-Auftrag $/OS4X_job/job_information/job_number an $/OS4X_job/job_information/recipient/partner_longname benötigt Freigabe
- default value:
- Send subject UTF-8 encoded?: If required, it is possible to send email subject as UTF-8 (with a special email encoding).
- Debug mail execution?: If mailing fails, you can enable debug output for analysis reasons.
- MTA (sendmail) command: An overridden sendmail MTA command can be configured.
- default: (empty)
sendmail
- default: (empty)
- URL to approve API: A resolvable URL for the approver. This URL is the OS4Xapi part of the approving, so it must be available over network of the approver.
- Example values: http://my-os4x-server/webaccess/os4xapi/index.php/job/approve
- Send email as HTML?: For nice layout, HTML emails are possible (activated by default).
Templates: In HTML mode, the leading and closing "HTML" and "BODY" tag will dynamically added by OS4X, since the editor removes them due to security reasons.
- Mail template: content of the email sent to the approver.
- Positive approve page: Page displayed to the approving person after a successful approving process.
- Deny page: Page displayed to the approving person after a successful denying process.
- Error page: Page displayed to the approving person after an unsuccessful process (when approving or denying fails).
Approver configuration
Approving person can be defined in all hierarchy levels. The contact can be selected, changed, reverted (to none), and edited:
Mail template variables
Beside the typical template rules for dynamic content generation, the approve plugin contains two specific variables:
$approveLink$denyLink
These links are using the configured "URL to approve API" (see above) for creating dynamically links. These hyperlinks contain the generated dynamic hashes used for approving or denying a job.
Also keep in mind the handy 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 the filename)
Mail example
A sample mail may look like this:
