You’ll define Phases for many Apps, representing different stages in the App’s overall workflow. For example, in a contract approval App, you might create one stage for each step in the contract’s overall review and approval process. Perhaps those stages would be Pending, Approved by Legal, Approved by Finance, and Complete.
Some Apps simply need unconditional Phase routing. That is, all Records always go through the same Phases no matter what. For most Apps, however, this approach is too simple, and you’ll need conditional Phase routing instead.
For instance, perhaps your company only requires a particular department’s approval when an amount Field exceeds a certain number. To accommodate this, you can define conditional logic that only allows a Record to be routed through a particular Phase when necessary.
In this tutorial, we’ll explain how to set up conditional Phase routing.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In the steps below, we’ll configure an app only to route transactions to a Finance Review Phase if a contract_amount Field is over a certain value. If this Phase is needed, we'll have a Financial Approver Role assigned so they can review the transaction and either approve or reject it.
During this tutorial, we’ll create a handful of elements for our app, including Roles, Phases, a Condition, an Action, and a Business Rule. If this is the first time you’ve built something like this in Onit, it might be a little difficult to understand how all of the different pieces of this puzzle fit together. Before we start setting things up, here's a quick chronological breakdown of how our app will work once everything is wired up:
- A requester creates a new transaction by filling out our app’s Launch Page form. One of the Fields they provide a value for is the contract_amount Field.
- A Business Rule will fire When the user submits the form. If its associated Condition (which will check if the contract_amount Field value is over a certain number) evaluates to true, an Add Participant Action will be triggered.
- If the Add Participant Action is triggered, it will activate a Financial Approver Role within the Finance Review Phase. The Financial Approver can review and approve or reject the transaction and the transaction will proceed accordingly.
- If the Action is not triggered, no Role will be activated for the Finance Review Phase and the transaction will essentially skip through that Phase and on to the next.
Alright, now let's jump in!
1. Configure Your Roles
In the Wizard, configure the Roles needed for your application. For this example, we’ll create a Legal and a Financial Approver.
Wait to hardcode the Email of the conditionally added Role until you create your Action in the Advanced Designer (which we’ll do later).
Need help creating Roles? Check out the Step 3: “Roles” section of our Building Your First App tutorial.
2. Assign Your Roles to the Appropriate Phases
Proceed to the Wizard’s Phases tab. In our example, we’ll use three Phases: Finance Review, Legal Review, and Approved.
Assign each Role to the appropriate Phase (as seen in the screenshot below). In our example, we want our Financial Approver only to become active when a Record enters the Finance Review Phase, so we’ll ensure this Role is assigned to that Phase.
We'll want to wait until our Records enter our Legal Review Phase for our remaining roles to become active, so we'll assign them as such:
3. Enable Auto Advance
We’ll need to configure each Phase to do the following:
- If the Phase’s Role has been activated, the Phase should hold onto the transaction, force it to stop, and wait until the Role in question has provided approval (before it moves the transaction on to the next Phase).
- Alternatively, if the Phase’s Role has not been activated, the Phase should push the transaction on to the next Phase, effectively skipping it.
Configuring our Phases to work in this way is easy! Ensure each Phase’s Auto Advance on Approval Completion property is enabled.
4. Configure Your Condition
Next, we’ll configure our App to activate our Roles when appropriate conditionally. We'll Update our App in the Wizard and move to the App's Advanced Designer.
Browse the App’s Advanced Designer page and select the Conditions node from the left-hand pane.
Add a new Condition to evaluate the value of a Field. In this example, we’re evaluating a contract_amount Field’s value to see if it’s over $10,000.
Need help writing a Condition? Check our our Creating a Condition tutorial.
5. Configure an Add Participant Action
Browse to Actions and Add a new Add Participant Action. This Action should specify the Role that you want to conditionally activate (in this context, “adding” a role to a transaction means that it has been “activated”).
Note that you can either hardcode this Role's email address in the Action's Email property or, alternatively, use Liquid in the Liquid Role property to set the email address, perhaps based on an "if/then" statement.
Within the Add Participant action, note that there is a Phase property, which can be set to either App Configured or Current.
We want our participant activated under the Phase we configured to be added to in the Wizard. In our example, we mapped our Financial Approver Role to our Financial Review Phase. We're telling our Action to honor this configuration by choosing App Configured for this property.
Alternatively, if we choose Current from the dropdown instead, we’re telling the Action to ignore the Role-to-Phase assignment defined in the wizard and to simply add the Role to whatever Phase the transaction is currently in when the Action fires.
Set the Action's Phase property to App Configured and save your Action.
For help writing an Action, see our Creating an Action tutorial.
6. Create a Transaction Initiated Business Rule
Tie your Condition and Action to a Transaction-Initiated Business Rule. This will cause the Add Participant Action we created above to fire when the transaction is first submitted.
The distinction between a Transaction-Initiated Business Rule and a Transaction-Created Business Rule is slight, but it’s essential to understand when to use one over the other.
A Transaction Initiated Business Rule fires when you hit the Submit Button on your Launch Page. However, a Transaction Created Business Rule fires after the transaction has been fully created, meaning the transaction's participants have been added, its Phase is set, and any other background operations have run.
We want to use a Transaction Initiated Business Rule because we need our Condition to evaluate our contract_amount Field before it sets the transaction’s Phase.
Alternatively, You would use a Transaction Created Business Rule when you need to run an Action that evaluates something about a transaction that’s already been created, such as what Phase it's in.
For help configuring a Business Rule, see our Creating a Business Rule tutorial.
Save your Business Rule.
Test Out Your Workflow
Congrats! You’ve just learned an essential skill used in building dynamic apps.
Take your app on a test run and ensure that transactions only advance to a specific Phase when relevant. If so, your app will be much more powerful and flexible in tackling real-world business problems.