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

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

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.

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.

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

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

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

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

• 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 Rewind, Stop 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.

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.

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. By referring to the screenshots below 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 the Record 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 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).