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

• 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.

• This extension is limited to UserRequest.
• An other extension could be written using approval_base to define a similar mechanism for Change

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

Use the Standard installation process for this extension.

The following settings are available to configure the module:

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

• email_asynchronous
• email_transport

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 as well as 3 default actions with body in English, French and German.

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

You must create the linkage between trigger and action of the language you want to use.

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 Automatically approved if no answer at Level 1/2 of the approval rule.

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

From the Service Management menu, click on Approval rules:

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

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

The fields Approval level 1 and 2 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 Automatically approved if no answer determines if the request will be approved or rejected if there is no answer after the defined delay.

The field approval delay (hours) 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.

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:

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:

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

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.

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.

From the user request, open the Other actions menu and select Approve or Reject:

The approval form is displayed:

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

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

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

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.

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:

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:

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: 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 after a given delay?
Answer: There is no easy way to do this today.

• 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 (assuming there is an accessible PHP function to trigger this 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”.