OS4X plugin os4xplugin approve

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 wo 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
• 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: A specific sendmail MTA command can be configured.
  • default: (empty) sendmail
• 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 (on 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: