As Onit workflows become more complex, it’s can be useful to associate different apps with one another by designating one app as the parent of another.
Creating parent-child relationships allows users to:
- Quickly create a child transaction using data that lives in a parent transaction.
- Display links to related transactions on either app’s View Page.
- Create hierarchy between a single transaction, (serving as the parent), and multiple other transactions (the parent's children).
A common example of a parent-child app relationship is often found within Contract Management workflows, where a contract that has received approval within a Contract Review app needs to now progress into a Contract Administration app so that a company can manage it while it remains active.
In this scenario, we’d make the Contract Review app the parent app of the Contract Administration app. While both manage contracts, they do so using different workflows, and perhaps different participants, and as a result, they are separate but related transactions.
If we set this relationship between apps up, a user could browse to the parent Contract Review transaction and click a button (highlighted in the screenshot below) to create the child transaction in the Contract Administration app without ever having to leave the Contract Review transaction. Additionally, since a lot of the data that the child transaction needs already lives inside the parent transaction (e.g., contract_name, company_name, contract_amount), this information will automatically be populated into the child app’s Launch Page, saving the user from having to manually type it in.
As can you imagine, parent-child relationships turn out to be a very powerful tool in your Onit App Builder toolbelt. Since parents can have many children, you can add lots of different pieces of functionality to parents, all of which can be exposed as different child apps. Maybe your Contract Review app needs Tasks, Key Dates, and Dispositions. All of these could be configured as separate child apps.
A note on parent-child relationships vs sibling relationships:
Note that there is one more relationship type used to relate transactions in Onit: a sibling relationship. While some aspects of these relationship types are similar, sibling relationships are distinct from parent-child relationships in the following key ways:
- Parent-child relationships create hierarchy between transactions, while sibling relationships do not.
- A child transaction can only have a single parent transaction, while both transactions in a sibling relationship can have multiple sibling relationships with other transactions.
- Parent-child relationships are, generally speaking, more restrictive to apps' workflow and permission structures, while sibling relationships are more flexible.
Whether you use a sibling relationships or a parent-child relationship is entirely dependent on your business case. We recommend defaulting to using sibling relationships until you find a use case that requires a one-to-one, parent-child relationship.
To learn more about sibling relationships, see our Creating a Sibling Relationship tutorial.
Before We Start ...
This tutorial will assume you understand the following concepts:
We’ll also assume you’ve already created two Apps. In the steps below, we’ll be using an App named Contract Review as the parent, and Contract Administration as the child.
Let's Get Started!
There are two different ways to create Parent-Child relationships in Onit. To create simple relationships use the Related Apps node in the Advanced Designer. For more complex relationships configure the relationship with a HasMany / BelongsTo Field.
1. Configure the Relationship with Related Apps
Browse to the Related Apps node in the Advanced Designer.
Click the Plus button to create a new relationship. Then, from the dropdown choose the appropriate relationship (in this case either Parent or Child).
Click Save to create the relationship.
2. Configure the Child App with a BelongsTo Field
Start by opening the child’s Wizard and adding a new Field with a Type of BelongsTo.
The Field’s Name should be the same as the name of the parent app, so in this case we’ll use contract_review.
Scroll down in the Field’s Properties and select your parent app from the Target App dropdown.
It’s common to select the BelongsTo Field’s Don’t render on form property to hide this Field on launch.
Update your child app.
Configure the Parent App with a HasMany Field
Now browse to your parent app’s Wizard and add a new Field with a Type of HasMany.
Give this Field a Name that matches your child app’s name; in this case, we’ll use contract_administration.
For the Field’s Inverse Relation, provide the name of the BelongsTo Field you created in the child app (which should also be the name of the parent app).
Take note that when using a BelongsTo Field in some Action types, such as a Generate Spreadsheet Action, you may need to make the Name of that Field plural by appending an ‘S’, even if your child app’s name is not. (Some irregular plurals, such as children, men, women, data and mice, are also accepted.) This will be pointed out in tutorials that cover these Action types but keep this gotcha in mind.
Finally, select the child app from the Target App dropdown.
Update your parent app.
Using Your Related Apps
Congrats! You’ve created your first parent-child app relationship. That wasn’t too hard, was it?
To use your apps, browse to a transaction in your parent app, and you should now see a new panel on your parent app’s View Page. It will be empty at first.
To create a new child transaction, select New from the “more” icon to the right of the panel.
A new Launch Page will open. Any Fields used in both the parent and child app will be prepopulated (both the parent and child Field names must exactly match).
In the example below, the Expiration Field is the only Field that was not shared by the parent app. All other values were pulled in from the parent transaction this child transaction was created from.
Any transactions created from within your parent app’s transactions will appear on your child app’s View Page.
Note that you can also display a grid of a related app's transactions as a tab on you app's View Pages using a Related Atoms Dashboard. See our tutorial Working with Related Atoms Dashboard tutorial to learn how.
Gotchas
- Since values from Fields with matching Names across a parent-child app relationship will automatically be copied to the child transaction on creation, you'll want to be sure you are intentional about how you name your Fields across related apps and match those Fields in Type. A Currency Type Field will not play nicely when the Field's Name matches a MultiCurrency Field Type Field Name causing the value to be copied over into a child transaction.