Have you built any parent-child relationships yet in Onit? If so, great! This tutorial will expand your skill set in this area. If not, however, this tutorial might not make much sense; in that case, check out Creating a Parent-Child Relationship first.
Onit makes it easy to relate your Apps in meaningful ways, by designating one App as being the parent of another. This feature provides enormous benefits, allowing your users to connect their data in meaningful and flexible ways.
Users often create a child Record manually by clicking a button on the parent Record and filling out the child App’s Launch Page form.
However, you can sometimes automate this process for your users. Suppose your workflow requires a child Record to be created every time a parent Record is made (or any time any specific event occurs). In that case, you can configure a Create Related Transaction Action to run, automatically creating one or more child Records. This Action relies on an Excel spreadsheet, which does all of the heavy lifting in terms of specifying how many child Records to create and what their Field values should be.
This tutorial will cover how to work with the Create Related Transaction Action.
Before We Start ...
This tutorial will assume you understand the following concepts:
Let's Get Started!
In this example, we need a Create Related Transaction Action to create a child transaction in a Reserves app from any parent transaction created in a Matter app. A Matter transaction should also pass its values for two Fields, reserve_date and reserve_amount, to its child Reserves transaction.
Tip: Not familiar with matters or reserves? Don't worry, as you don’t need to be. We could be working with any parent/child relationship here, such as any situation where we have a parent transaction that needs to be related to one or more child transactions.
1. Create Your Spreadsheet
We need to create a simple, three-row spreadsheet, which will query our parent Record's Fields and input their values into our child Record’s Fields.
Review the example spreadsheet below:
This spreadsheet follows the same basic format outlined in Formatting, Importing, and Updating a List.
Additionally, we’re using Liquid in Row 3 to do the following:
- In Cell C3 and D3: We’re retrieving the current user’s name and email address and inserting them into the new child transaction’s requester_name and requester_email fields, respectively. (The current user is the person who triggers the Create Related Transaction Action to run. In our case, that’s the requester of the parent transaction.)
- In Cell E3 and F3: We’re retrieving the parent transaction’s reserve_date and reserve_amount Field values and inserting them into the new child transaction’s reserve_date and reserve_amount Fields.
While the configuration above is straightforward, there are several less apparent concepts that you should be aware of here:
- Field Names: The parent transaction’s Field Names do not have to be the same as the child transaction’s Field Names. Even though they are identical in our example, they can be completely different.
- Context: Context is king when it comes to Liquid. In this case, any Liquid that you insert into the spreadsheet lives at the level of the parent transaction. In other words, {{field_name}} will only work if the Field in question lives within the parent app. That being said, you can insert virtually any type of Liquid expression into the spreadsheet, which means you can use Liquid to traverse other apps related to the parent app to retrieve their Field values. This would be an advanced Liquid expression, but it’s possible to do.
- Number of Child Transactions: In this tutorial, we are configuring our spreadsheet to create only a single child transaction. If necessary, we could create as many child transactions as required. This is controlled by adding new rows to the spreadsheet. For example, if we wanted to create ten child transactions every time the Action runs, we would add nine additional rows to the spreadsheet, each of which would look like Row 3 above. Each row could use an entirely different Liquid to insert different Field values into its child transaction.
2. Import Your Spreadsheet
Follow the steps outlined in Formatting, Importing, and Updating a List to import your spreadsheet.
3. Configure a Create Related Transactions Action
Browse to the Actions node in your parent App’s Advanced Designer. (For us, that’s our Matter App).
Select Create Related Transaction from the Add dropdown.
Give your Action a Name. We’ll name ours Create Related Reserve Transaction.
In the Related Atom Field dropdown, select the HasMany Field used in your parent app to relate the two apps. In this example, that’s Reserves.
Select the name of the List you created and imported above from the List Name dropdown.
Select OK to save your Action.
4. Create a Transaction Created Business Rule
Browse to your parent App’s Business Rules node. Add a new Transaction Created Business Rule.
Give it a Name and link your Create Related Transaction to this Business Rule.
Save it by selecting OK.
Test It Out
Congrats! You’ve just configured the Create Related Transactions Action to expedite your workflow.
You can test it by creating a new transaction in your parent app. Visit your parent transaction’s View Page to see if a transaction has been created in your child app's panel.
Gotchas
- Values from a Field with a Type of Multiselect cannot be passed from a parent to its child transactions.
- It's possible to conditionally create related transactions by adding a new column to your spreadsheet with a fieldLabel of _condition and providing Liquid in the data row of this column. However, for your condition to work, you must also add a new row to your spreadsheet; this row should be a duplicate of the row used to identify the app's Fields (row 1 in the example above) except that the first cell should be changed from fieldLabel to name.
See the screenshot below; Row 2 is a duplicate of Row 1 except for the cell in Column A.
