Sidebar

Combodo

iTop Extensions

Approval process automation

name:
Approval process automation
description:
Control your approval process with predefined rules based on service catalog
version:
2.3.1
release:
2023-11-28
itop-version-min:
2.4.0
code:
combodo-approval-process-automation
state:
stable
alternate-name:
Approval Extended
diffusion:
iTop Hub
php-version-max:
PHP 8.1
For iTop versions older than 2.2.0 use 1.1.3.
For iTop 2.2.x or 2.3.x, use 1.2.2 or better 1.3.5
For iTop 2.4.0 or higher, use this version or above

This module provides the capability to handle a two levels approval process for a user request, with several approvers in parallel on each level.

Features

  • Automated, rule based, approval mechanism.
  • The approval rules are applied when the object enter a given status (usually new, but can be another one)
  • Supports passive or active approval and configurable timeout delay.
  • Two levels of approbation with several approvers in parallel at each level.
  • Approvers can approve or reject a request in one click from an email (no need to have an iTop account) or multiple requests pending for their approval in Console or Portal.
  • Graphical view of the approval status on each ticket.
  • Configurable approval email message, with multi-language capabilities.

Limitations

  • This extension is limited to UserRequest.
  • An other extension could be written using Approval Base to define a similar mechanism for Change
Known limitation before version 2.1.1: The user creating a UserRequest must be allowed to see the approvers, otherwise the User Request stays in New status. The issue will occur if the Requestor has allowed organizations but the approver does not belong to one of those organizations

Revision history

Date Version Description
2023-11-28 2.3.1 * N°6578 - Update czech translations (thanks to @Stetinac!)
* N°6827 - Expiration date not working correctly on Approval Rules
2023-07-13 2.3.0 * N°5440 - Add compatibility with iTop 3.1 (Symfony 5.4 and deprecated imports)
* N°3482 - Email approval request : Set sender (from and reply to) display name / label in action email
* N°6180 - Enhancement on approval notification edition
* Fix RecordComment date format
* N°6422 - Improve french dictionary
* Updated german translations by Lars Kaltefleiter
* N°6466 - CS CZ translations (thanks to Stetinac !)
2022-06-27 2.2.1 * Notify Substitutes in case Approvers do not reply in a percent of the approval delay
* update ApprovalRule dictionary entries (EN, FR)
2022-03-14 2.1.1 * Remove deprecated function from iTop Extensions - ajax_page + SetupPage::log_info
* Improve log entry on approval
* version iTop min 2.4.0
* Fix approval with silo
* Portal: fix Approval screen if the approver is not allowed to see the organization of some user requests
2021-12-21 2.1.0 * Remove references to Flash
* Add iTop 3.0 compatibility
2021-12-17 2.0.5 * Update german translations
* Fix coverage created without any hour selected was crashing iTop
2020-12-17 2.0.4 Fix approvers not being able to download attachments in iTop 2.7+
2020-12-02 2.0.3 Fix: Name of bypass user no more displayed in console
2020-10-10 2.0.2 Mail for iTop user validator must contain URL to the portal instead of URL with token
2020-03-18 2.0.1 * Bring compatibility with iTop 2.7
* Fix TWIG template not found when trying to open object form
2020-03-05 2.0.0 * Add compatibility with iTop 2.7+
* Update DE translations
* Enable Notification management delegation
* ActionEmailApprovalRequest : default sender for sample email actions
* Fix: Approval reminder in edit mode : double pop-up
* from and reply_to can be specified in ActionEmailApprovalRequest objects (were only available in approval_base module settings)
* New methods in EnhancedSLAComputation to ease extensibility
* Open Hours mandatory for Coverage Window
2019-03-26 1.4.5 * Fix: Approval reminder in edit mode : double pop-up
2018-12-13 1.4.4 * Fix spanish translation files encoding
* Add missing reconciliation key to the ApprovalScheme class
* Add missing reconciliation key to the ExtendedApprovalScheme class
* Fix UI glitch on approval form
* Improve jQuery compatibility (jQuery 3 since iTop 2.6)
2018-06-27 1.4.3 DE translation update
2018-06-26 1.4.2 - New translations (ES, BR) and fix CSV import of TriggerOnApprovalRequest.
- Fix attachments unavailable in portal when object waiting for approval was not within user's scopes.
2018-01-26 1.4.1 Bug fix: Extension could not be installed if Enhanced Portal was not selected.
2017-11-14 1.4.0 Requires 2.4.0 or higher: Approval in Enhanced Portal
2017-11-14 1.3.5 Bug fix: Tooltips not showing for all comments when several answers of the same user (Typically rejected then accepted an user request)
2017-09-27 1.3.4 fix 2.4 compatibility issue
2017-09-01 1.3.3 - Comments recorded in the log: loosing carriage returns
- Fix Check/Uncheck All on portal summary page
- Do not skip level 2 if there is no approver on level 1
- Missing index, slowing down the display of a ticket
- dishardcoded menu group “Helpdesk” position
- Fix corrupted coverage windows when edited from a browser having a timezone different from the timezone of iTop
2016-11-30 1.3.2 Approval Emails configurable by the mean of triggers/actions with placeholders - Select the step ending condition in each step of the approval rule - Do not ask several times an approval to the same person
2016-08-09 1.2.1 - XML-based implementation in order to ease some customizations - include a library for the support of approvals in the enhanced customer portal (requires further customizations though)
2016-07-11 1.2.0 Now requires iTop 2.2.0! - Bug fix: “Portal users” redirected to the customer portal when trying to approve - Date and time correctly formatted (if iTop version >= 2.3.0) - Hide the shortcut buttons (Assign) on the ticket creation page, ONLY IF there are some approval rules in the DB - Prevent overflow of interval to the next day when dragging/dropping intervals in the calendar
2015-09-30 1.1.3 Disable the standard attributes UserRequest::approver_id and approver_email, as they do not make sense when this module is installed. Removed the “plus” button from the Approval Rule edition form, to workaround a bug in the coverage windows creation form (when shown as a dialog, requires a fix in the core of iTop, related to the component “SLA With Coverage Windows” version >=2.1.0, or the module “combodo-coverage-windows-computation>=2.0.0)
2014-12-18 1.1.2 Manually send a reminder ; Support of several executions on the same ticket (works retroactively with data recorded prior to this version) ; Record something into the log even if the comment is left empty (was already done when bypassing the process) ; If an approver already gave her answer the approve/reject menus must be hidden ; If a user bypasses the process, and if her account has a contact defined, then the identifier of the user (shown in the header of the new log entry) must be the contact friendly name (not the user login) ; Changed the misleading message “is now complete with failure” into “is now complete with result REJECTED” ; Prevent the CRON from creating one CMDBChange record per minute ; Fixed typos in the french dictionary ; Changed the module name (internal)
2014-04-24 1.0.3 Better error reporting when an email address is wrong or missing. In particular when the module has just been installed, the configuration entry sender_email is left empty and this produces a scary error message when the email transport is SMTP
2014-03-07 1.0.2 Integration of the German translation (thanks to ITOMIG GmbH)
2014-03-05 1.0.1 First release (fixes a bug found the prototype: always approve on timeout, whatever the setting in the approval rule)

Requirements

  • Requires at least iTop 2.4.0.
  • cron.php must be running to enable processing of approval timeout and substitutes notifications.

Installation

Use the Standard installation process for this extension.

Configuration

After installing this module, configure a proper email_sender and configure trigger/action to ensure “Approval eMails” delivery.

The following settings are available to configure the module:

Module Parameter Type Description Default Value
approval-base email_sender string Sender eMail address, as seen in the approval email. If left blank, sending the email will fail.
approval-base email_reply_to string Default “reply to” eMail address for the approval email. If empty defaults to email_sender
approval-base comment_attcode string Attribute into which the user comments will be reported. Can be a case log or text. The comments are all aggregated. Note: the comment can also be viewed as a tooltip. (optional)
approval-base list_last_first boolean In case several executions occur, drives the order in which the results of the executions are displayed (vertically). false
approval-base enable_reminder boolean Enable the feature “send a reminder”. true
approval-extended enable-admin-abort boolean Allow defined profiles to bypass the approval process. Profiles allowed to bypass the process are defined in the variable bypass_profiles. true
approval-extended target_state string state that may trigger the approval process. The event ev_wait_for_approval must exist on this state, ending on wait_for_approval state. new
approval-extended bypass_profiles string CSV list of profiles. Having any of the given profiles is sufficient to be allowed to bypass approval processes. Set to an empty string to deny the feature to anybody. Administrator, Service Manager
approval-extended reuse_previous_answers boolean If a person is approver at both level then his level 1 decision is reused at level 2 true

The following standard settings might be of interest when setting up the approval feature:

  • email_asynchronous
  • email_transport

Notification (trigger/action)

Email notification is based on Trigger/Action and email content can be tailored to your need with HTML format and placeholders.

A default trigger is created at installation  Approval process automation trigger as well as 3 default actions with body in English, French and German.  Approval process automation notification

You can of course edit this message to make it yours, here is the english default version for example of possible placeholders:

Dear $approver->html(friendlyname)$,
Please take some time to approve or reject ticket $this->html(ref)$

Caller: $this->html(caller_id_friendlyname)$
Title: $this->html(title)$
Service: $this->html(service_name)$
Service subcategory: $this->html(servicesubcategory_name)$

Description:
$this->html(description)$

Additional information:
$this->html(service_details)$

$approval_link$

 Approval process automation default notification You must create the linkage between trigger and action of the language you want to use.  Approval process automation link approval notification to approval trigger

You can create your own trigger and action
If you need to send different notification depending on the organization of the caller, the service, the service family, or any data available on the Ticket, this can be done by creating multiple trigger/action couples, using a filter on the Trigger.

Using Substitutes

Since version 2.2.1 of the extension, it's possible on any approval level, to add define substitutes (Person) which will be notified and asked to approve on behalf of an official approver if that person has not answered within a configurable delay.

By default Substitutes will receive the same notification email as the initial approver, so addressed to the approver himself. This can be changed, by creating a specific Email approval request

  • the placeholder $:approver…$ always reference the person who approved, so it can be either the approver or the substitute.
  • If the person who approved was the substitute, then to get who should have approved in first place, use the placeholder $:on_behalf_of->…$

Managing the Trigger (when an approval is requested):

  • By default the trigger, Send request to Both approvers and substitutes
  • But you can limit this to Substitutes only or Approvers only

User experience

Cinematics

When a User Request is entering the state new, the approval engine verifies if there is an approval rule defined for the corresponding service subcategory. If yes, then the state of the user request is set to wait for approval and a notification is sent to the approvers defined in the approval rule. Only the approvers corresponding to the first level are notified. Once the request is approved, and if a second level has been defined, then the second level approvers are notified. Should the approval be rejected (by an approver, or on timeout), then the process finishes in any case.

The email contains a web link to display the web page to approve or reject the request:

  • If the approver has an User in iTop he gets a link to a User Portal page to Approve or Reject
  • If the approver has no iTop user, he gets onetime links to directly Approved or Reject

The approvers will have a delay defined in the approval rule to give their answers. This delay takes into account the coverage window defined in the approval rule.

Once the approval delay has expired, the approval process terminates. The result (approved or rejected) is then taken in the property Approved if no answer of the approval rule.

The User Request will then continue its way through its lifecycle, depending on the approval status: rejected or approved.

Create approval rules

From the Service Management menu, click on Approval rules:  Approval process automation menu

The pages show a list of already defined approval rules. Click on the button “new” to create a new one:

 Approval process automation approval rule edition

An approval rule is identifier by it name. The coverage window is used to compute the Approval delay.

The fields Approval level (L1 or L2) define, via an OQL query, the list of approvers for each approval level.

  • These queries must return elements having an email attribute (e.g. Person or Team).
  • It is possible to use the place holders :this->attribute that make reference to the attributes of the user request.
  • For instance :this->caller_id for the caller, :this->service_id for the service …
    All attributes defined in the data model for a service request can be used.

The field Approved if no answer determines if the request will be approved or rejected if there is no answer after the Approval delay.

The field Approval delay defines the delay in hours for each level of approval, only hours within the coverage windows are counted.

  • If you leave it empty or set it to 0, UserRequest will stay forever in waiting for approval state, until one of the approvers accept or reject it.

The field Approval ending is useful with multiple approvers to determine, how to behave with multiple actions:

  1. ends on first approve : All must reject for Request to be rejected.
    • Multiple rejected then one approved ⇒ ends and approved
    • multiple rejects but not all then delay expired ⇒ ends and “reject or approved” depends on field Automatically approved if no answer
  2. ends on first reject previous default behavior: all must approved.
    • Multiple approval then one reject ⇒ ends and reject
    • multiple approvals but not all then delay expired ⇒ ends and “reject or approved” depends on field Automatically approved if no answer
  3. ends on first reply = first to act is the decision maker.

The field Substitute is an OQL which defines for each approver, who can take their role and answer on their behalf.

  • The query should reference the placeholder :approver->xxx with xxx being a Person attribute code.
  • For eg. SELECT Person WHERE id=:approver->manager_id will escalate to the manager of the approver.
  • Substitute can approve User Requests for which they are “substitute” at anytime, even before they are notified.

The field Substitute notification specifies at which percentage of the Approval delay, substitutes will be notified if their approver has not reacted

  • For eg: 80% for a “Approval delay” of 70h means, that 56h after the request was submitted, if the request is still “waiting for approval” then for the approvers who haven't answer, their substitutes will be notified with a link to approve or reject the request.
  • This notification requires the cron.php to run on the iTop server

Once the approval rule has been defined, you can assign it to a service subcategory, either from the approval rule itself (tab Service subcategory) or from the service subcategory:

 Approval process automation service subcategory

Approving process

Approver with an iTop login can connect anytime and check if they have Requests pending their approval. From the Helpdesk menu, click on Ongoing approvals:  Approval process automation approval menu

The page shows a list of the User Requests having an approval process running, and for which your approval is being requested:  Approval process automation approval monitoring

Approver without iTop login, can still approve or reject Request, but they must have received the email notification with the onetime usage links allowing him to approve or reject without being connected to iTop.

Approver without iTop login, giving email delegation, give at the same time iTop approval delegation

If the approver has an iTop login then the email provided link points him to iTop (Console or Portal depending on his access). In that case, the link provided in the email can only be used with the approver iTop login.

Approve or reject

From the user request, open the Other actions menu and select Approve or Reject:  Approval process automation approval menu

The approval form is displayed:  Approval process automation approval reply

After the reply has been given, you are redirected to the user request and a banner reminds you the outcome of your reply.  Approval process automation approval message

Bypass the approval process

If you are an administrator, and if the setup allows it, then you have a menu to bypass the process:  Approval process automation bypass menu

The approval form is then a little different than the standard reply form: it reminds you that bypassing the process is a little different.

 Approval process automation bypass approbation

If you are both an approver and allowed to bypass the process, then both menus are allowed. Using one or the other will just change the way the approval process result gets recorded and further displayed in the status tab.

Status

As soon as a user request has been through an approval process, the tab Approval status shows detailed information about the ongoing or terminated approval.

Ongoing approval

In the above example, the deadline is displayed in bold: 15th of april at 17:32.

Click on the button “send a reminder” to send a new message to the approver (confirmation required). This feature can be disabled by setting the parameter enable_reminder to false.

After the reply has been given, the status appears in clear:

Rejected approval

Move your mouse over the image next to the approver's name, and you will get the date of the answer and her comment if any has been given:

 Rejected comment

The status will be entirely reset anytime the user request enters the state “waiting for approval”.

In the situation below, the Ticket was

  1. first rejected by the Approver,
  2. submitted again by the Requestor,
  3. then finally approved by the Substitute of the Approver (The substitute name appears right shifted, just below their Approver)

Approval in portals

A new menu appears in the Enhanced Portal, which allow an approver to retrieve all User Requests waiting for her approval, and one by one or in bulk mode, accept or reject them.

A comment is required in case of rejection, so the button is disabled as long as the comment is empty. A confirmation is required in both cases.

When clicking on the link to a User Request, the ticket's details are displayed with an extra comment field and two buttons at the bottom of the details to accept or reject it:

Question & Answers

Question: What happen if the approval rule returns zero approvers, on all level of approval?
Answer: The request is never entering the approval cycle.


Question: My approvers are not using the Portal. How to send them a link to approve in the console?
Answer: To get this behavior, create a real link in the notification:

  • Label = “All request waiting for your approval” for example
  • URL = $APP_URL$/pages/exec.php?exec_module=approval-base&exec_page=report.php&class=UserRequest&do_filter_my_approvals=on
  • protocol = <other>.

You may remove or not the $approval_link$ placeholder. Don't remove it if at least one approver has no access to the console.


Question: can we hide the Approbal Brick in the Portal to users based on their Profiles?
Answer: Yes, as any brick in the Portal it supports to specify the Profiles which are allowed or denied to see a given brick

itop_design / module_designs / module_design@itop-portal / bricks
  <brick id="approvals" xsi:type="Combodo\iTop\Portal\Brick\ApprovalBrick" _delta="must_exist">
    <security _delta="define">
      <allowed_profiles>
         <![CDATA[SELECT URP_Profiles WHERE name = 'Portal power user']]>
      </allowed_profiles>
      <denied_profiles/>
    </security>
  </brick>

Here we are allowing only Portal power user but do what makes sense for you


Question: Can I have an approval for New Phone request, only if the price is above a given amount?
Answer: Here we will present an example, where the user is providing in its Request the price of the requested phone in a Customized Request form, and if that price is above a given level, let say 100, then we want a particular person (with id=6) part of the same organization as the caller to approve at the second level.

SELECT Person AS p
  JOIN Organization AS o ON p.org_id=o.id   /* A path is required from Person */
  JOIN UserRequest AS u ON u.org_id=o.id    /* to the UserRequest to set conditions */
  JOIN TemplateFieldValue AS v ON v.obj_key=u.id
WHERE v.template_name="New phone"
  AND v.field_code='price' 
  AND v.field_value > 100  /* Check if the Price is above 100 */
  AND u.id = :this->id     /* We want to use the present UserRequest */
  AND p.id=6               /* We want an identified person, always the same */

This is just an example, the price could be on the phone model typology and the user would just select the phone model.


Question: How to automatically send a reminder to Approvers on a percentage of their approval delay?
Answer: If you are not using any Substitute, you can set the original “approvers” as being their own substitute and set an % of the approval delay, to send them a reminder.

Substitute L1 = "SELECT Person WHERE id=:approver->id"
Substitute notification delay L1 = 50%

Other option, much more cumbersome:

  • add a date field approval-requested-on on the to be approved object class, let say a Ticket.
  • When the Ticket enter the state waiting for approval, on the transition set the approval-requested-on date with now().
  • Create a daily background task, which retrieve Ticket in waiting on approval, since exactly delay*n days, and send a reminder → with delay = 7 this would trigger a reminder every seven days as long as not approved.

Question: Can I have more than 2 levels of approvals?
Answer: Yes, that requires to write an extension.

  • In the class ApprovalRule, add new attributes copied from the level1 and level2 attributes
  • Adapt the presentation of that class to display those new fields.
  • Overwritte the method ExtendedApprovalScheme::GetApprovalScheme, and copy the paragraph about string “2” and replace in the copy, “2” by “3”.

Question: Can I get the approver from a field of a customized request form?
Answer: Yes, but remember that this query returns nothing if no such field as 'approver' was part of an associated request template on the User Request.

SELECT Person AS p
  JOIN TemplateFieldValueLnk AS v ON v.field_target_key=p.id
  JOIN UserRequest AS u ON v.obj_key=u.id
WHERE v.field_code='approver' AND u.id=:this->id
extensions/approval_extended.txt · Last modified: 2024/03/14 09:11 (external edit)
Back to top
Contact us