Onit Documentation

Building Approval Workflows

by Christina Moore Updated on

Perhaps the most common use case for an Onit App is that of an approval process. Whether you’re building a basic approval workflow for expense reports or a super complex contract approval process, the core Onit building blocks that you’ll need (primarily Phases and Roles) all operate based on the same rules.

In this tutorial we’ll build a basic approval process from scratch. Once we’ve finished you’ll have a firm grasp on how to tackle approval processes of all shapes and sizes, from simple to complicated. Let’s get started!

Basic App Creation and Configuration

Start by creating a new App. If you need help, see Building Your First App.

It’s critical that you understand all of the material in the Building Your First App tutorial before proceeding.

Our example workflow will handle contracts that need to be approved by various people. Our approval process will be:

Each colored box above represents a Phase in our App. Here’s a breakdown:

  • The first Phase for a new Record is Financial Approval.
  • The second Phase is CFO Approval.
  • If a Record is rejected (at any point during the workflow) it’s kicked backed to the original requester to fix and resubmit, and its Phase changes to Fix Contract. Upon resubmission the Record’s Phase changes back to Financial Approval.
  • Once a Record is fully approved its Phase changes to Approved.

The Approved phase is terminal when a Record reaches this Phase its lifecycle is complete.

Our App will have three Roles:

  • Requester (of type Requester)
  • Financial Approver (of type Approver)
  • CFO Approver (of type Approver)

In the above screenshot  which shows all of the Roles in our app notice that the Email initial value property (on the right) has been left blank (that’s true for all Roles). 

For more information on Roles see the table at the bottom of this tutorial.

It is only appropriate to hardcode an email address here if the Role will always be filled by the same person (for each Record). When that’s not the case (which is the majority of the time), you should use an Action to dynamically populate Roles, using lookups and rules.

For example, in our situation the Financial Approver should be Jim if the contract_amount Field is below $10,000 and Pam if the contract_amount Field is equal to or greater than $10,000. Later in the tutorial we’ll use Business Rules, Actions, and Conditions (all configured outside of the Wizard) to determine the contract_amount and assign the appropriate Participant.

In the Wizard, browse to the Fields tab. Add a contract_amount Field of type Currency with USD as the currency (as seen in the screenshot below). We’ll use the amount entered into this Field to determine who the Financial Approval Role will be assigned to (Jim or Pam).

Click Next to move to the Phases tab.

When it comes to building approval workflows, much of the heavy lifting is done on the Phases tab. As a result, we’ve dedicated an entire section of this tutorial (up next!) to this tab.

The Phases Tab

First, we’ll create and name all of the new Phases that we need.

It’s important to list Phases in the top-down order in which you want Records to flow. In other words, the first Phase listed in the Wizard is the first Phase that all Records will enter upon their creation. As seen below, there are Up and Down buttons that allow you to set a Phase’s order.

Next, let’s configure our Phases. Onit provides many granular options to control the behavior of each Phase  while this is a good thing from a functionality standpoint, it also means that you have a lot of choices to make.

In the screenshot below we’ve numbered each individual configuration option in the Phases tab.

The configuration options on the left (1-4) control all Phases, whereas the options on the right (5-12) are phase-specific. The Phase that you have selected when configuring 5-12 determines the Phase that you are modifying.

Let’s break down each configuration option by number:

  • On Phase Activation (1) and At Launch (2): Both of these options control when Roles become activated on a Record. At Launch Time activates every Role as soon as the Record is created, regardless of which Phase the Record is in. On Phase Activation defers a Role’s activation until the Record reaches the Phase that the Role is assigned to (we’ll cover how to assign Roles to Phases later). In our example scenario, if we select On Phase Activation, the CFO Approver Role will only get activated once the Record reaches the CFO Approval Phase.

When a Role is activated, all Participants on the Record under the Role in question are, to use a baseball analogy, up to bat! In other words, it’s their turn to “work” on the Record. From a technical perspective, there are a few implications to Role activation. First, in the Onit user interface, on the Record’s View Page, the Participants will no longer be greyed out (Participants are greyed out by default, until they get activated). In addition, if the Role’s type is Approver, activation causes this Participant to see Approve and Reject Buttons on the Record’s View Page.

  • Only Admin can manually change Phase (3): Prevents all non-administrative users from manually changing a Record’s Phase. It is highly recommended that you check this box for every App, as not doing so allows any user (with access to the Record) to manually change Phases, thereby circumventing a predefined workflow path. Below are two screenshots that show how the Phases box (on a Record’s View Page) appears in the Onit UI. The screenshot on top shows the Phases box when Only Admin can manually change Phase is not selected (notice the triangle icon, which acts as a dropdown for the user to select a new Phase). The screenshot on the bottom shows the Phases box when Only Admin can manually change Phase is selected (notice that the triangle icon is gone). Both screenshots are from the point of view of a non-administrative user.

In this context, “non-administrative” refers to any user that is not a System Administrator and also is not a Participant under a Role of type of Administrator.

  • Approve by Phase (4): Controls whether a single Participant who plays multiple Roles must approve the Record multiple times. At first glance this is a little confusing, so let’s break it down. If your App has a user that is an approver under multiple different Roles (each in a different Phase), you have the option to let the user to give one “master” approval for all of their Roles or you can require them to approve the Record once per Role. For example, let’s say that Dylan is both our Financial Approver and our CFO Approver. If the Approve by Phase checkbox is not selected, Dylan must approve the Record once. On the other hand, if Approve by Phase is selected then Dylan must approve the Record multiple times, first as the Financial Approver and then again as the CFO Approver.

Every heard the term “phase-gated”? That phrase refers to Apps where this option is selected. In other words, selecting the Approve by Phase checkbox makes the App phase-gated.

While On Phase Activation and Approve by Phase sound similar these two options do not control the same setting. On Phase Activation controls when a Participant is activated, while Approve by Phase controls how many times a user in multiple Roles must approve a Record.

If you select the Approve by Phase checkbox, all Participants will be visually organized (on the Record’s View Page) under a Phase name. See the example screenshot below.

  • Roles (5): Allows you to assign Roles to the Phase. In many cases, someone has a specific job to complete within a Phase. For example, in our App, the Financial Approver Role has an approval to complete in the Financial Approval Phase  as a result, we need to assign this Role to this Phase.

The most common reason that you assign Roles to Phases is for approval purposes. By doing so, Onit automatically shows Approve and Reject Buttons to Participants under this Role (when the Role is activated). That said, you can assign any Role of any type to a Phase, to indicate that they have work to do.

If Approve by Phase is not selected, you can only assign any given Role to a single Phase. If Approve by Phase is selected then a single Role can be assigned to multiple Phases.

  • Hide from Phase Picker (6): Check this box to prevent the  Phase from appearing in the drop down menu of phases in a Record view page. Users will not be able to set the Record to this Phase manually.

Note that if the Record does reach the phase via automatic processes, users will see the phase name (not the label name); it's up to the App creator to make sure that doesn't happen if it's not wanted.

  • Label (7): Text entered here will display in the Record view page in place of the Phase's name.

Note that this applies only to the display on the view page: the App dashboard grid column "Phase" will still display the phase name (not the label name), and the Liquid variables {{ phase }} and {{ curr_state_name }} will still give the phase name as their output.

  • Auto Advance on Approval Completion (8): When this option is selected Onit will advance the Record into the next Phase automatically and immediately after it has been approved by the applicable Role(s). If this box is not selected the Record will stay in the Phase after it has been approved  in this situation, you must provide end-users with some other way to advance the Record (such as Button that triggers a Change Phase Action).

When Auto Advance on Approval Completion is turned on you need to be careful not to create an infinite loop. These types of loops can happen when a phase change Action moves the Record back to a previous phase were there are no approvers in the phase. Auto advance will then move the Record through the empty phases until it hits the phase change Action again, triggering the loop. To avoid this type of infinite loop be cognizant of your phase change Actions and approval structure. 

  • Require at least one approval to auto advance (9): Only applies if the Auto Advance on Approval Completion (8; above) is selected. If Require at least one approval to auto advance is selected, the Record will automatically advance to the next Phase once approval is provided by exactly one Participant, even if there are other approvers still active in the Phase. On the other hand, if Require at least one approval to auto advance is not selected, all approvers assigned to the Phase must approve the Record before it automatically advances.
  • Reset Participant Endorsements on Rewind (10): Controls what happens to previously submitted approvals once a Record is moved back to a previous Phase. If this option is selected, all previously granted approvals/rejections will be changed back to Pending (i.e., all approvals will be revoked). If this option is not selected, all previously granted approvals/rejections will persist.
  • Stop Notification on Rewind (11): Controls what happens to active Participants when a Record is changed to a previous Phase. If this option is selected, when a Record leaves this Phase  and moves to a previous Phase  all of its Participants become inactive. If this option is not selected, when a Record leaves this Phase  and moves to a previous Phase  all of its Participants remain active.
  • Stop Notification on Forward (12): Very similar to the option above (10), but in the opposite direction (forward instead of backward). If this option is selected, when a Record leaves this Phase  and moves to a future Phase  all of its Participants become inactive. If this option is not selected, when a Record leaves this Phase  and moves to a future Phase  all of its Participants remain active.

Now that you understand each Phase option above, below is a detailed breakdown of how we will configure our example contracts App. 

  • Assign the appropriate Roles to each Phase (e.g., add CFO Approver to the CFO Approval Phase)
  • Select On Phase Activation. We want our users notified only when their Phase is active.
  • Select Only Admin can manually change Phase. This ensures that none of our users can circumvent our intended workflow.
  • Leave Approve by Phase unselected. For our hypothetical business case, one approval is sufficient in the event that a single person plays multiple Roles on the same Record.
  • On the Financial Approval and CFO Approval Phases check every box except for the Require at least one approval to auto advance. We want to leave this box unchecked because we need approval from each user in the Phase before the Record can advance to the appropriate next Phase. The Reset Participant Endorsements on RewindStop Notification on Rewind, and Stop Notification on Forward boxes will all ensure that the appropriate user(s) are activated/deactivated when moving in and out of Phases.
  • On the Approved Phase check every box except for the Auto Advance on Approval Completion and Require at least one approval to auto advance. The Approved Phase is a terminal Phase, so we do not want the Record advancing into the next Phase.
  • On the Fix Contract Phase check every box except for the Auto Advance on Approval Completion and Require at least one approval to auto advance. The Fix Contract Phase is a holding Phase for when changes need to be made to the Record after a rejection. The Record should not automatically advance out of this Phase. Instead, the Record should only leave the Fix Contract Phase once it has been manually resubmitted by the requester (via a Button that we’ll create later on).

When you’re done configuring your App, publish all of your changes and close the Wizard.

Building Workflow in the Advanced Designer

At this point, we’ve configured all of the appropriate settings in the Wizard. Even so, our App doesn’t actually do all that much. In fact, if you were to create a test Record it would fall through all of the Phases to Approved. Why is that the case?

This happens because Onit doesn’t know the specific people that should play each Role. Whenever zero Roles associated with a Phase are populated, Onit skips the Phase entirely.

To fix this, let’s move into the App’s Advanced Designer page. We will begin by writing some Conditions.

In the sections below we’ll create Conditions and Actions, which at first won’t actually do anything. Creating these objects on their own may seem a bit confusing at first  if so, not to worry! Later in the tutorial we’ll tie everything together, assigning the Conditions and Actions to various other objects to provide a holistic solution to the overall business problem. Stick with us!

Creating the Conditions

Create the three Conditions shown in the following screenshots:

Tip: Need help creating Conditions? See our tutorial on this topic.

Creating the Actions

We’ll create Actions that assign Participants and change Phases.

In the steps below, we’ll assume that you are generally familiar with how to create Actions in Onit. If that’s not the case, check out our Creating an Action tutorial before proceeding.

Create one Action to handle what happens when an approver rejects the Record. This should be a Change Phase Action that matches the screenshot below:

Create another Change Phase Action, this one to allow the requester to resubmit a Record after it has been corrected:

Now let’s populate our Roles. By referring to the screenshots below create three new Add Participant Actions.

You may be thinking, “Hey! Wait a minute! All of the Actions above are simply hardcoding email addresses for each Role! Why do we need Actions for this? We could have just hardcoded these Actions into the Builder!” You’re absolutely right! While we’re keeping things simple in this tutorial, in the real world we would replace the hardcoded email addresses shown above with Liquid lookups. These lookups would reach into an Onit App or list to identify the best person perform this approval. In case you need it, here is the syntax to perform a Liquid lookup

Creating the Business Rules

Business Rules allow us to string our Conditions and Actions together into an overall workflow. For our approval process we need two Business Rules to assign the Financial Approver, one to assign the CFO Approver, and one to handle changing the Phase when a Record is rejected.

Create the four Business Rules shown in the following screenshots:

The top-left portion of each screenshot below identifies the Business Rules’ type (e.g., Transaction Initiated, Participant Rejected).

Not familiar with creating Business Rules? See our tutorial on this topic.

Creating the Buttons

When an approver rejects the Record, we want to move it to the Fix Contract Phase. Once the Record has been corrected we want the requester to re-submit the Record for approval. To achieve this we must provide the user with a Button.

Create the Button shown in the following screenshot:

Need help creating a Button? See our Creating a Button to Execute an Action tutorial.

Test Your Workflow

We’re done building out basic workflow. Let’s test it!

To test, you must log into Onit as each active approver (e.g., Financial Approver, CFO Approver)  one by one. If you are not logged in as the active approver you will not see the Approve or Reject Buttons.

  1. Navigate to your App’s dashboard and create a new Record. In contract_amount enter a value over $10,000 and create the Record.
  2. Once the Record is created check to see if Pam has been assigned as the Financial Approver (Pam’s status will be shown as Pending until she has approved or rejected the Record). Also check to see that the Record stopped in the Financial Approval Phase.
  1. Login as Doug Jones’ (i.e., the CFO Approver) and reject the Record. Ensure the Record moves to the Fix Contract Phase.
  1. Log back into the requester’s account and click the Resubmit button. Ensure that the Record moves back to the Financial Review Phase and that Doug’s rejection resets to “pending.”

Approve by Proxy

The ellipses icon next to Pam’s name allows any Participant on the Record to approve by proxy the Record for an approver. The first screenshot below shows the “approve by proxy” pop up that will appear after clicking the ellipses. Once submitted, the proxy approval will be recorded on the Record’s history, with the proxy approver’s name, the intended approver’s name, and any approval comments (see the second screenshot below).



Role Name Role Permissions
Administrator: A participant that needs admin privileges on the Record.
  • Admin privileges at the Record level
  • Change always manually change phase
  • Delete Comments
  • Approve or Reject a Record
  • Edit Record Details
  • Close a Record
  • Edit or Remove Participants
  • Make or see Comments
  • View a Record
Approver: A participant that needs to take action on the Record.
  • Manually change phase when not restricted
  • Approve or Reject a Record
  • Make or see comments
  • Edit Record details
  • Close a Record
  • View a Record
Requester: The participant requesting/submitting the Record.
  • Edit Record details
  • View a Record
  • Make and see comments
  • Approve or reject a Record
Read Only Approver: A participant that needs to take action on the Record, such as approve or reject; but who does not need to edit the details, change the Phase or edit or remove a participant.
  • Approve or reject a Record
  • Add a participant
  • View a Record
Read Only Requester: The participant requesting/submitting the Record. He or she can access the Record and view its details; but cannot edit details, change the phase, add participants, see comments make, make comments, or view the history.
  • Create a Record
  • View a Record
Read Only Reviewer: A participant that will need to review the Record, but does not need to approve, reject, or change the Phase.

  • View a Record

Reviewer: A participant that will need to review the Record, but does not need to approve or reject.

  • Make and see comments
  • View a Record

Requester (Limited): The participant requesting/submitting the Record. However, he or she will not have access to the transaction after submission. This user can still receive email notifications but will not be able to view the transaction details in the application. Note that the Requester will still be added to the corporate user list even though they never access the transaction.

Custom: An App builder can configure a custom role to use in their App. The custom role can have any of the previously discussed permissions (i.e., admin rights, edit rights, read-only rights, etc.).

Once a role is implemented and Records are created, you cannot change the Role Type of an existing role. Instead, you should disable the role and create a new one.

Previous Article Managing Record Participants in Bulk
Next Article Creating a Suite

© 2024 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.