As you’ve likely learned in other tutorials, a big part of Onit App building revolves around Actions. Most Actions are designed to accomplish one (and only one) task. For example, a Send Notification Action sends an email; an Add Participant Action adds a participant to a Record.
Many times, running a single Action won’t solve your larger business problem. Instead, you’ll need to string a series of individual Actions together to accomplish your goal. For instance, let’s say that when a user clicks a Button, your App should do the following:
- Generate a document
- Edit a field value
- Add a participant to the Record
Since each of these things are handled via different Actions, you’ll need to configure Onit to run these Actions as a sequence in a specific order, one immediately after the other. How can you do this?
That’s where Conditional Compound Actions come into play. This special Action contains other sub-Actions, and runs them in a specific order. As a result, if you have a list of Actions that all need to run when a user clicks a Button (or a Business Rule fires), you can add those Actions into a Conditional Compound Action. When the Conditional Compound Action runs, it will run its contained sub-Actions.
Packaging Actions together like this reduces the redundancy of elements and keeps your Actions organized around business problems. Additionally, this is the only way to configure a Button or Business Rule to fire more than one Action.
In this tutorial, we’ll explain how to create and configure Conditional Compound Actions.
Before We Start ...
Let's Get Started!
In this tutorial, our Conditional Compound Action will accomplish the following tasks:
- Generate a document
- Edit a field value
- Add a participant to the transaction
Each of these tasks will be accomplished by a different sub-Action, all of which will be assigned to the same Conditional Compound Action. Let’s start configuring!
1. Create Your Sub-Actions
Although our sub-Actions will eventually be grouped together into a Conditional Compound Action, we’ll start by creating each sub-Action individually.
We’ll create the following sub-Actions:
- Generate Document Action
- Update Transaction Action
- Add Participant Action
Note: Since the focal point of this tutorial is Conditional Compound Actions, we won’t cover how to configure each of the individual sub-Actions listed above. Feel free to set these up however you like.
Now that these three sub-Actions have been created and configured, we’ll group them into a single Conditional Compound Action.
2. Create a Conditional Compound Action
On the App’s Advanced Designer Page, select the Actions node from the sidebar on the left, click Add, and select Conditional Compound Action.
Name your Conditional Compound Action. We recommend providing some indication that this is a Conditional Compound Action in your name so it's easier to distinguish from other Actions down the road; We prepend the abbreviation CCA for each of our Conditional Compound Actions.
Next, add your sub-Actions to the Conditional Compound Action by selecting them from the Actions dropdown property. Your sub-Actions will run in the left-to-right order in which they are listed (you can drag and drop the sub-Actions to change their order).
We’ll order our sub-Actions so that our document is generated first, our field value is updated second, and our participant is added last.
Note: Any given sub-Action will not run until all previous sub-Actions are 100% complete. If necessary, this means that any state change made by a previous sub-Action (e.g., a Field value change) should be considered when configuring the following sub-Actions.
We’re not quite done yet. There are a few optional configuration properties to consider:
- Condition: If necessary, you can configure the Conditional Compound Action to only run when certain conditions are satisfied. For more information, see Creating a Condition.
- Run In Background: This advanced option is only relevant if the Conditional Compound Action will be fired via a Button (not a Business Rule). This checkbox controls what a user will see in the Onit user interface when the Conditional Compound Action is actively running. If this option is not selected, the user will see a “spinning wheel” until all sub-Actions have completed -- during this time, certain portions of the Onit user interface will not be editable to the user (i.e., they’ll be prevented from doing some work on the transaction). On the other hand, if you select this option, the user will only see the “spinning wheel” for a moment, as Onit passes the Conditional Compound Action’s work into a server-side background task -- once the work has been passed over (which typically takes a second or two), the user will not be locked out from any portion of the user interface (the user will not receive any UI indication when all sub-Actions have completed). There are pros and cons to both approaches, and covering each one is outside the scope of this tutorial. The best approach here is to experiment with both options, and select the one that works best for your use case.
- Action to execute in case of background failure: If one of your sub-Actions errors out, you may want to fire an Action to perform some sort of clean up or notification work. This is somewhat of an advanced feature, but can be very handy in the right situations.
Phew! That’s all of the configuration work needed on the Conditional Compound Actions. Save this Action by selecting OK.
3. Create a Button/Business Rule
Like any other Action, you can use either a Business Rule or an Button to fire your Conditional Compound Action. In this tutorial, we’ll use an Action Button. Navigate to the Buttons node, click the Plus button, then select Action Button.
Give your button a name and attach the CCA: General, Update, Add Legal Action under the Action property.
Note: Need help configuring an Action Button? See Creating a Button to Execute an Action.
Hit Save to save this Button.
Test It Out
You’re done! Take your Conditional Compound Action on a test run. Make sure it fires all the sub-Actions included in it.