From a business perspective, different transactions in your apps will often be related to each other. By creating a sibling relationship between the related transactions, you can provide your users with a way to see and leverage these relationships in a meaningful and helpful way.
This may sound too abstract, so let’s look at an example. Let’s say we have one Onit app that handles contract approvals and another that handles invoices. Though these are entirely separate apps with different types of data and workflows, sometimes the information in a contract will be related to information in an invoice. When this is the case, you may want to show this relationship to your users right in the Onit user interface.
Onit offers a simple and intuitive way to accomplish this: On each app’s View Page, you can give users a button to relate a contract to an invoice (or vice-versa).
After using this button to establish a relationship, every user that views either the legal matter transaction or the contract transaction will be able to see this relationship right on each transaction's View Page; when viewing the legal matter, a link to the contract will be visible, and vice-versa. Best of all, the relationship doesn’t have to be one-to-one -- you can relate as many contracts to as many legal matters as necessary.
Implementing sibling relationships can be an incredibly robust addition to your app-building tool belt, allowing users to connect their data in meaningful and flexible ways. In this tutorial, we’ll explain how to set up sibling relationships like the above example.
A note on sibling relationships vs parent-child relationships:
Sibling relationships aren’t the only types of relationships that you can create in Onit. You can also create parent-child relationships. While some aspects of these relationship types are similar, sibling relationships are distinct from parent-child relationships in the following ways:
- Sibling relationships don't create a hierarchy between transactions; parent-child relationships do.
- Both transactions in a sibling relationship can have multiple sibling relationships with other transactions. However, a child transaction can only have a single-parent transaction.
- Sibling relationships are generally a more flexible way of associating transactions; they tend to be easier to configure a workflow or permission structure around.
Whether you use a sibling or parent-child relationship depends entirely on your business case. We recommend that you default to sibling relationships until you find a use case requiring a one-to-one parent-child relationship.
Check out Creating a Parent-Child Relationship for more info.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
There are two different ways to create Sibling relationships in Onit. To develop simple relationships, use the Related Apps node in the Advanced Designer. For more complex relationships, configure the relationship with a ManytoMany 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, choose the appropriate relationship from the dropdown, in this case choose "Sibling".
Click Save to create the relationship.
2. Create using a ManyToMany Field in Your First App
In this tutorial, we’ll associate an Invoices app and a Contract Approval app as siblings. This will enable our users to relate contracts to legal matters and vice versa.
We’ll use a special Field Type called ManyToMany to create a sibling relationship. We’ll create one Field of this Type in each app we want to relate.
Open the Wizard for one of the apps that you want to associate as a sibling. We’ll start with our Invoices App.
Create a new Field with a Type of ManyToMany. The Name of this Field will need to be shared by the ManyToMany Field we created in our sibling app so we'll name this Field contractapproval_invoices.
It’s best to name ManyToMany Fields with words that end in an s. Due to a few technical requirements that exist under the Onit hood, this will ensure that everything works correctly.
From the Target App dropdown, select the app you want to be associated with as a sibling.
Select Enforce App Type. This is primarily a nicety for your users -- it prevents them from having to select which app the related transaction lives in (each time they create a sibling relation between two transactions). If this property is selected, Onit will always assume that the related transaction lives in the app specified by the Target App property you selected above.
Update your app.
Create a ManyToMany Field in Your Second App
Open the Wizard for your other app. In this example, this is our Contract Approval app.
Create another ManyToMany Field. The Name of this Field must be the same as the Name used in your sibling app. (For us, that's contractapproval_invoices.)
Select the app that you want to use as a sibling from the Target App dropdown.
Select Enforce App Type.
Update your app.
Check Out Your Work
Congrats! You’ve now associated two apps as siblings.
Look at your newly configured sibling relationship by visiting the associated apps. Open a transaction’s View Page and notice the new panel.
To crosslink transactions between the two apps, select the More icon in the panel, select Relate, and select a transaction from the Transactions dropdown. Select Ok.
