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 a lot of 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 huge benefits, as it allows your users to connect their data in meaningful and flexible ways.
When users need to create a child Record, in many cases they will do so manually, by clicking a button that lives on the parent Record and then filling out the child App’s Launch Page form.
In some cases, however, you can automate this process for your users. That is, if your workflow requires a child Record to be created every time a parent Record is created (or any time any specific event occurs), you can configure a Create Related Transaction Action to run, which will automatically create 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? Not to worry, as you don’t need to be. We could be working with any parent/child relationship here -- 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 that 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 to insert them into the new child transaction’s reserve_date and reserve_amount Fields.
While the configuration above is straight-forward, there are several less obvious 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 to other apps that are 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 necessary. This is controlled by adding new rows to the spreadsheet. For example, if we wanted to create 10 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 such row could use entirely different Liquid to insert completely 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 that is 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 up 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 out 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 in the screenshot below, Row 2 is a duplicate of Row 1 except for the cell in Column A.
