Many times, different transactions in your apps will be related to each other from a business perspective. By creating a sibling relationship between the related transactions, you can provide your users with a way to both 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 that we have one Onit app that handles contract approvals and another app 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 a 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 offer 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 especially robust addition to your app building tool belt as it allows your users to connect their data in meaningful and flexible ways. In this tutorial, we’ll explain how to set up sibling relationships similar to the example above.
A note on sibling relationships vs parent-child relationships:
Siblings 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 hierarchy between transactions, while 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 speaking, 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 relationship 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
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 create 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 be associating a Invoices app and a Contract Approval app as siblings. By doing so, we’ll enable our users to relate contracts to legal matters, and vice-versa.
To create a sibling relationship, we’ll use a special Field Type called ManyToMany. We’ll create one Field of this Type in each of the apps that 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 that you want associated as a sibling.
Select Enforce App Type. This is mostly 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 that 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 used 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.
Take a look at your newly configured sibling relationship by visiting either of 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.
