For many Apps you’ll define Phases, which represent different stages in the App’s overall workflow. For example, for a contract approval App, you might create one stage for each step in a contract’s overall review and approval process. Perhaps those stages would be: Pending, Approved by Legal, Approved by Finance, 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 instead need conditional Phase routing.
For instance, perhaps your company only requires a particular department’s approval when an amount Field is over a certain number. To accommodate this, you can define conditional logic that will only allow 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 to only route transactions to a Finance Review Phase if a contract_amount Field is over a certain value. In the event that this Phase is needed, we'll have a Financial Approver Role assigned so they can review the transaction and either approver or reject it.
During this tutorial, we’ll create a handful of different elements for our app, including Roles, Phases, a Condition, an Action, and a Business Rule. If this is the first time that 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 will create a new transaction by filling out our app’s Launch Page form. When doing so, one of the Fields they will provide a value for is a contract_amount Field.
- When the user submits the form, a Business Rule will fire. 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 Phases
Proceed to the Form Builder's Phases page. In our example, we’ll be using three Phases: Finance Review, Legal Review, and Approved.
Create the Legal Review Phase, noting that the two checkboxes for the On Exiting Phase section are enabled.
If you are starting with a new app, update Phase 1 to be the Legal Review Phase because it already has the Approver and Requestor Roles assigned to it.
Add the Finance Review and Approved Phases, noting that the two checkboxes for the On Exiting Phase section are not enabled.
2. 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, and 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! Just make sure each Phase’s Auto Advance on Approval Completion property is enabled.
3. Configure Your Roles and Assign the Appropriate Phase
Roles are required to have an assigned Phase. Phases do not require an assigned Role.
Proceed to the Roles page in Forms Builder to configure the Roles needed for your application. We’ll create a Legal Approver and a Financial Approver for this example.
Assign each Role to the appropriate Phase (as seen in the screenshot below). In our example, we want our Financial Approver to only become active when a Record enters the Finance Review Phase, so we’ll add that Phase to this Role.
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:
Want to double-check that your Roles and Phases are correctly assigned? Go back to the Phases page and confirm that the Legal Review Phase has the Legal Approver and Requester Roles assigned to it and that the Finance Review Phase has the Financial Approver assigned to it.
Need help creating Roles? Check out the Step 5: “Roles” section of our Building Your First App with Forms Builder tutorial.
4. Configure Your Condition
Next, we’ll configure our App to conditionally activate our Roles when appropriate. We'll move over to the App's Advanced Designer.
Browse to 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 it to be added to in the Wizard. In our example, we mapped our Financial Approver Role to our Financial Review Phase. By choosing App Configured for this property, we're telling our Action to honor this configuration.
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 instead 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 that we created above to fire when the transaction is first submitted.
Add the Condition and Action we created by selecting it from the drop-down options.
The distinction between a Transaction Initiated Business Rule and a Transaction Created Business Rule is slight, but it’s important to understand when to use one over the other.
A Transaction Initiated Business Rule fires right when you hit the Submit Button on your Launch Page. A Transaction Created Business Rule, however, 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.
You would alternatively use a Transaction Created Business Rule when you needed to run an Action that evaluate 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 is now quite a bit more powerful and flexible when it comes to tackling real-world business problems.