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

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

Our App will have three Roles:

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

The above screenshot, showing all of the Roles in our App, shows that the Email initial value property (on the right) has been left blank (that’s true for all Roles). 

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 populate Roles, using lookups and rules dynamically.

For example, 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 the Wizard) to determine the contract 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 will be assigned to the Financial Approval Role (Jim or Pam).

Click Next to move to the Phases tab.

The Phases tab does much of the heavy lifting when building approval workflows. As a result, we’ve dedicated an entire section of this tutorial (up next!) to this tab.

First, we’ll create and name all the new Phases 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, the Up and Down buttons 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 good from a functionality standpoint, it also means that you have many 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 those on the right (5-12) are phase-specific. The Phase you selected when configuring 5-12 determines the Phase you are modifying.

Let’s break down each configuration option by number:

• On Phase Activation (1) and At Launch (2): 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.

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

• 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 who is an approver under multiple different Roles (each in a different Phase), you have the option to let the user 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.

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

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

If the Record reaches the phase via automatic processes, users will see the phase name (not the label name); it's up to the App creator to ensure this doesn't happen if it is not desired.

• Label (7): The text entered here will replace the phase's name on the Record view page.

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 automatically advance the Record into the next Phase 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 approval. In this situation, you must provide end-users with another way to advance the Record (such as a Button that triggers a Change Phase Action).

• 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 other approvers are still active. 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).  All previously granted approvals/rejections will persist if this option is not selected.
• 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 its Participants become inactive. If this option is not selected, when a Record leaves this Phase and moves to a previous Phase, all 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 its Participants become inactive. If this option is not selected, when a Record leaves this Phase and moves to a future Phase, all its Participants will 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. One approval is sufficient for our hypothetical business case if 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 Rewind, Stop Notification on Rewind, and Stop Notification on Forward boxes will 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 terminal, 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 we’ll create later on).

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

At this point, we’ve configured all the appropriate settings in the Wizard. Even so, our App doesn’t 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 who should play each Role. Whenever zero Roles associated with a Phase are populated, Onit skips the Phase entirely.

To fix this, we will move to the App’s Advanced Designer page and begin by writing some Conditions.

Create the three Conditions shown in the following screenshots:

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

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. Refer to the screenshots below to create three new Add Participant Actions.

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:

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 it for approval. To achieve this, we must provide the user with a Button.

Create the Button shown in the following screenshot:

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

1. Navigate to your App’s dashboard and create a new Record. In contract_amount, enter a value of 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.
    

3. Login as Doug Jones’ (i.e., the CFO Approver) and reject the Record. Ensure the Record moves to the Fix Contract Phase.
    

4. 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.”
    

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