Conditionally Routing Phases

by Christina Moore Updated Aug 15, 2019

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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. We’ll create a Legal Approver and a Financial Approver for this example.

Wait to hardcode the Email of the conditionally added Role until you create your Action in the Advanced Designer (which we’ll do in a later step).

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 be using 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 to only become active when a Record enters the Finance Review Phase, so we’ll make sure that 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, 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.

4. Configure Your Condition

Next, we’ll configure our App to conditionally activate our Roles when appropriate. We'll Update our App in the Wizard and 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.

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.

Previous Article Creating Raw Filters
Next Article Using Complex Combo Fields

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