HomeGuidesRecipesAPI
HomeGuidesAPILog In

Approvals

An Approval is a step in a workflow that acts as a gateway, where the responses provided in the form thus far can be reviewed and, if appropriate, altered before progressing. Approvals can be simple and require approval by a single person, or may require multiple stakeholders such as members of a group or a specific user. For example:

  • Two (2) members of the ‘Executive’ Group or the ‘CEO, John Smith’
  • Two (2) members of the ‘HR’ group and 1 member of the ‘Finance’ group

If appropriate communication templates have been configured, Approvals automatically send email notifications when new requests are submitted, comments are provided etc.

Approvals are managed centrally and can be reused across multiple workflows.

Creating an Approval

Approvals must be created in Manage before they can be added to a workflow project in Design.

  1. In Manage, navigate to the Approvals section and select New Approval. These will be added to specific workflows in the steps that follow.
  2. Specify an appropriate name. For example, Line Manager Approval or Executive Approval.
  3. Add a clause to your workflow, by first selecting if the clause is intended for a group or user:
  • For group clauses, you can select from one of the following:
    • Specified – Lets you select from the drop-down list of available user groups.
    • Reference – Lets you specify a reference name that will later be mapped to data in the form. For example, a ‘Manager’ clause might be mapped to a data question that is configured to retrieve the requester’s manager from the HR System or from referenced question and answer values.
    • Additionally, indicate how many members of that group need to approve to satisfy the clause.
  • User clauses require a reference name that will later be mapped to data in the form. For example, a ‘supervisor’ clause might be mapped to a data question that is configured to retrieve the requester’s supervisor from the HR System.
  1. Click Add.

  1. Add more clauses as necessary. See the “All Of, Any Of and Then Clauses“ section below for how to manage approvals with multiple clauses.

📘

Note

If you are editing an existing approval, click the Update button before saving.

  1. (Optional) See the Notifications section below to specify appropriate notifications for new requests, comments etc.
  2. Click the Save button to save changes.

All Of, Any Of and Then Clauses

For Approvals with multiple clauses, All Of, Any of and Then clauses determine how the individual clauses relate. There are three clause group types:

  • All Of – All clauses within the group have to be met in any order. In the example below, the Finance and Human Resource groups have to approve. Who approves first is not important as long as both approve.

  • Any Of – Any Of groups need only one individual clause to be met. In the example below, the first member of Finance or Human Resources to approve will progress the entire approval.

  • Then – Sub clauses need to be met in order. Members of the later sub clauses will not be able to approve before preceding sub clauses are met. Useful for situations where layers of approvals should occur. For example, do not bother the CEO until branch feedback/approvals have been actioned. In the example below, the Field Worker clause has to be met before the Approval can proceed to Finance. Finance will not be notified of the approval until the “Field Worker” clause has been met.

You can also change the following:

  • Convert state by selecting the state you want to change and click the Convert state button to change from All Of to Any Of or vice versa.
  • Change order of priority by selecting the clause and then clicking the up and down arrows to move a clause up or down.

Nesting Then, All Of and Any Of Groups

In the example below, All Of and Any Of are nested within Then. SmartIQ will process the clauses sequentially, starting with number 1 and will only proceed to the next clause if the previous clause has been satisfied. The last Approver would be number 4, or an Executive.

The second example is where Any Of is nested within All Of, which is then nested within Then. All of number 1 has to be satisfied before it proceeds to number 2.

Notifications

Specify communication templates as notifications when the following events occur:

  • Submission – The Requester receives the notification after submitting or starting a form
  • Comment – Only the Requester receives a notification if someone commented on the form
  • Comment Reply – The Requester as well as other active users will receive the notification if someone replied to the comment on the form
  • Approval – Only the Requester receives a notification if the form has been approved
  • Rejection – Only the Requester receives a notification if the form has been rejected
  • Observer – Users and groups designated as Observers will receive a notification with a link to the project
  • Mention – Any user mentioned in an Approval state will receive a notification with a link to the project

For more information, refer to Communication Templates.

After setting up the Approvals, the following buttons will also appear:

  • Version History button to check any changes that have been made and by whom. There is also a Restore link that will appear next to a version if there are more than two changes that have been made. Restoring discards any changes that have been made after that date.
  • Related Projects to see any projects that use this Approval. These are projects that will be affected if you make changes to this Approval.

Workflow

Approvals are a state within a workflow. They enter the state when a request is made and leave once the approval clauses are met, either to go to finish or another state.
A single approval can contain many approvals where transition conditions are used to determine which path is required.

Transitions from an Approval state are either Approved or Rejected transition types, as indicated by green (approved) and red (rejected) transition lines in the canvas. The result of the Approval state will determine which type of transition is taken.

This sample workflow uses two (2) approvals, New Hire - Simple and New Hire - Executive. The transition condition states that:

  • If the answer to the Candidate Selection question of executive is NO, the workflow uses the “New Hire – Simple” approval state and the hiring process will only need the approval of HR.
  • If the answer to the Candidate Selection question of executive is YES, the workflow uses the “New Hire – Executive” approval state and would need the approval of a Senior Executive before it can be processed.
  • From the “New Hire – Executive” and “New Hire – Simple” approval states, if either the HR or a Senior Executive answer to the hired question is YES, the company proceeds to Arrange Onboarding for the New Hire.
  • From the “New Hire – Executive” and “New Hire – Simple” approval states, if either the HR or a Senior Executive answer to the question is NO, the workflow goes back to Candidate Selection and the workflow continues.

Approvers

Approvers are users that can approve/reject the workflow from the Produce home page or a dashboard.

The Approver section will only display if Approvals > Clause Builder type in Manage has been set to User or Group that requires a reference name. These will be mapped to data in the form.

In this example, the ‘Supervisor’ clause is mapped to a data question that retrieves the manager’s name from the system.

Adding an Approval State to a Workflow

  1. Open an appropriate project and navigate to its workflow. Drag and drop the Approval state into the workflow. A popup window will appear and you can select from the drop-down list of available approvals.
  2. Select the workflow from the drop down list.

  1. Configure the State - Approval properties:

a. (Optional) Specify the name of the state.
b. (Optional) Enable the Quick Approval option to give the Approver the ability to quickly approve or reject the request from the dashboard.
c. Select a View type.

  • Form – The form is displayed using pages and the Approver will have to use the next and back buttons to view the request.
  • Summary – Shows all the fields on one page using a form summary view. Useful for small-medium sized forms, where the request can be displayed without too much scrolling. The following minor configurations are available for summary view:
    • Collapsible pages – Group pages in an accordion style tab group
    • Include All Multiple Choice Answers – Displays all the answers and highlights the selected answer.
    • Answered Questions Only - Only include questions that have been answered.
  • Mentions – Gives the option to engage additional users or invite them to a workflow by mentioning them in a comment by using the ‘@’ syntax. Any user mentioned will receive an email notification with a link to the state or comment.
    • Users with State Access – Only users that currently have access to the state can be mentioned.
    • Anyone – Any user can be mentioned and they will be dynamically added as an observer to view the task and make comments.
  1. If a User had been selected as an Approver in Manage, map the reference input to data in the form:

📘

Approvers

This section will only display if Approvals > Clause Builder type in Manage has been set to User.

a. Select the input from the drop-down. In the example below, the User is the Supervisor.
b. Select the type of input and specify the value in the Text Value field.
c. Click Add. Repeat if there is more than one input.

  1. (Optional) Add an Observer.

  2. Validate then Save project.

📘

Note

For both Form and Summary, only the requester will be able to make changes to the fields. However, the Approver can add comments to let the requester know what changes need to be made.

Approving/Rejecting an Approval Request

📘

Interface Feature Availability

Available in web interface Produce only.

When a request is submitted, Approvers are able to access the approval’s content from SmartIQ home, a dashboard or from a direct link received in an email. The Approver will see an overview of the approval together with the content submitted with the request.

📘

Note

It is possible that Approver’s contribution is no longer required, as the approval clauses have already been actioned by another user. However, while an approval is still active, an individual Approver can reject the request or add an extra (redundant) approval.

For approvals with more than one stage, known as “Then Approvals”, extra information about the approval’s current and completed stages will appear in the overview.

Group Task

When workflows states are assigned to a group, only one person can work on the form at a time. This means that when a user opens a workflow, this user locks the form to themselves, but group members can access a read only view. If the Unlock on Exit option is enabled, SmartIQ will attempt to unlock the form when a user leaves or closes the form without finishing, which lets someone else in the group continue working on the form.

However, if the workflow state is locked and someone outside of the group attempts to make changes, a notification will appear at the top of the form indicating that only the mentioned user has edit access to the task. To regain access to the task, an administrator or a group member can unlock it from the home page, allowing the processing to continue.

Comments

Users can also use the comments icon to pass feedback to the requester by selecting Always or Approval Only in each question’s properties.

Quick Approval

Quick Approval is an option that allows an individual approval state to be added to the workflow which enables an Approve/Reject dropdown selection.

If quick approval is enabled, approvers can approve/reject the workflow from a dashboard or home page without actually opening the approval to view its content.

📘

Quick Approval in Dashboard

The Quick Approval feature can also be enabled in a Dashboard if using Data Grids.

The Approver can use the following buttons in the workflow:

  • Approve – Approves the form. If the current user is the last Approver required, the form will move to the next state.
  • Reject – Stops the form from proceeding any further or moves the approval to the previous state if a reject transition has been added.
  • Save and Close – Saves changes and comments without progressing the approval.

Email Approval

Sometimes there is the desire for a simple decision to be made on a form that doesn’t warrant loading the whole form. An example might be an approval step… Sometimes the approver may just want to approve the work without viewing it, perhaps because the work came from a trusted source.

SmartIQ allows the definition of an “email approval” or “choice” in this kind of scenario. A designer can define that an email (or other HTML producing action) can contain this choice, either as a button or a link. When that button/link is clicked, SmartIQwill take the same action as if the person had logged into SmartIQ loaded the form in Produce, made the appropriate action (such as ticked “approve”) and submitted the form.

🚧

Safe Links will prevent the proper use of this feature

Microsoft Outlook's anti-phishing "feature" effectively clicks on every link it finds in an email to check it's safe and SmartIQ has no way to know that the click that comes from Safe Links is not a user. Other email programs or security software may implement similar safe links features.

This will result in the following message: This task has not been found. It may have already been actioned when the email recipient attempts to click on any of the "choice" links in their email.

For this reason, if your users are likely to be using Outlook or have this sort of security enabled on their email, the use of "choice" links is not recommended.

Usage

A choice is defined by a special style of question reference that takes the following form:

[Choice.q1.1]

Where q1.1 is a reference to a multiple choice answer in the form.

This question reference will resolve itself to a button that will have text equal to the display text of the multiple choice answer.

This button can be included in an email or any other action. When clicked, a link behind the button will call SmartIQ and SmartIQ will, behind the scenes, load up the form in its current state, select the reference multiple choice answer and then attempt to “submit” the form.

Therefore, if Conditions that reference the multiple choice answer control workflow from that state, then the form will be moved to that next state without the person who received the email having to interact with SmartIQ at all.

Options

A few options can be used to customise the appearance of a Choice reference. These are applied by adding | separated values to the reference. For example, the following reference will display as a link instead of a button and will have the text “Approve Now” instead of the display text of q1.1:

[Choice.q1.1|type=link|text=Approve Now]

The following options are available:

NameDescription
TypeDefault: buttonValid Types:
  • Button - Displays as a red button
  • Link - Displays as a link
  • URLOnly - Puts in the raw URL, so HTML styling can be put around it to control appearance.
TextApplies only to button and link typeAllows the definition of the text that should be displayed on the button/link
CommentingTrue/FalseDefault: TrueDefines whether or not a comment can be defined for the workflow transition that will occur when the receiver makes a decision. Currently, the comment can only be defined by being passed in on the URL of the link. This is a query string parameter in the form of “comment=XXXX”.

Example using URLOnly Type
Following sample code can be added to the Label to format button

<table width="100%" border="0" cellspacing="0">
<tbody>
<tr>
<td>
<table border="0" cellspacing="0">
<tbody>
<tr><!--Approve-->
<td style="background-color: #4ecdc4; border-color: #4c5764; border: 2px solid #45b7af; padding: 10px; text-align: center;"><a style="display: block; color: #ffffff; font-size: 12px; text-decoration: none; text-transform: uppercase;" href="[Choice.q2.2|type=UrlOnly]&comment=Approved" target="_blank">Approve Request</a></td>
<td></td>
<!--Reject-->
<td style="background-color: #dd5a5a; border-color: #4c5764; border: 2px solid #a03d3d; padding: 10px; text-align: center;"><a style="display: block; color: #ffffff; font-size: 12px; text-decoration: none; text-transform: uppercase;" href="[Choice.q2.3|type=UrlOnly]&comment=Rejected" target="_blank">Reject Request</a></td>
<td></td>
<!--Return-->
<td style="background-color: #e8b04a; border-color: #4c5764; border: 2px solid #a57d35; padding: 10px; text-align: center;"><a style="display: block; color: #ffffff; font-size: 12px; text-decoration: none; text-transform: uppercase;" href="[Choice.q2.4|type=UrlOnly]&comment=Returned" target="_blank">Return to Travel Requester</a></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>

Adding Project Property values

The URLOnly type (or an external integration) can pass query parameters to the URL to set Project Properties in the target form. These can be added in the same format as the comment mentioned above:

[Choice.q2.2|type=UrlOnly]&Property1=value1

The above would set the value of "Property1" to "value1" when running the form, which can drive additional logic.

Ability to Customise Email Approval Features

Approval by emails are now accepting customisable message to be added to the the choice parameters. The Standard format is:

[Choice.{question reference}|type={button, link or urlonly}|message={inline message or question reference}]

Example:
[Choice.q1.1|type=urlonly|message=the request is approved]
[Choice.q1.1|type=link|message=[q2]]

Within the message parameter it is possible to use the special value {{message}} which will be replaced by the contents of the Email Approval Template defined in Communication Templates, if set. If the template is blank, the choice message will be displayed as it is.

Security Implications

Any unauthenticated person can call the URL contained in the email. This will trigger the execution of that choice regardless of who calls it. Therefore the use of this feature has to take into account the security implications.

SmartIQ minimises the security risk by ensuring that there is an id in the URL that cannot be guessed and is unique for each choice, for each form, for each person receiving it. For example, if the same multiple choice reference is used twice in the same action, there will be two different ids, even if both will do the same thing.

All URLs for a particular workflow state will cease to work once one of them has been actioned (or the form submitted via a different means – such as submitting via Produce).