After you’ve configured an app relationship, you’ll likely need a way to keep some of the Field values of those apps in sync. If you updated a Field on a parent transaction, you wouldn't want to have to go through each child transaction and manually update a related Field's value, for instance.
Instead, you can configure an Update Related Transaction(s) Action to keep specific Field values up-to-date with one another.
When using an Update Related Transactions(s) Action to keep Fields who share the same name, your configuration for this Action will be relatively straightforward. However, if you want the values of Fields who have different names to stay in sync, you'll need to take a couple extra steps to trigger the update.
In this tutorial, we'll first go through setting up an Update Related Transactions(s) Action for Fields in different apps which share the same name. Then we'll walk through how to set up this Action for Fields with different names.
Before We Start...
This tutorial will assume you understand the following concepts:
Configuration for Fields with Shared Names
Let's start by configuring this Action for Fields which share the same name.
In this example, we’ll say we have a parent app named Matter, which has a child app named Invoices. Both of these apps have a Field named matter_id and the values for these Fields should stay in sync; if the matter_id is updated for a transaction in the Matter app, we also want that Field's value to be updated for any of that transaction's children in the Invoices app.
1. Make Child Fields Read Only
If you want your Field values to stay in sync, we recommend allowing only one app's version of that Field to be editable.
In our case, we want a user to be able to update the matter_id Field in the Matter app. But if we allowed a user to edit the matter_id Field in the Invoices app, he/she would be cause that invoice transaction to become out of sync with its parent and the rest of that parent's children.
To prevent from happening, we'll make our matter_id Field in the Invoices app read only. In the App Builder wizard of our Invoices app, we'll select the Read Only property for our matter_id Field.
2. Create an Update Related Transaction(s) Action to Update the Related Field/s
We can now create our Action.
Browse to Actions from your parent app's Advanced Designer.
Add a new Update Related Transaction(s) Action.
Provide this Action with a Name.
Select the name of the Field that draws a relationship to the app you're creating the Action in from the Relation Property dropdown. In our example, that's a HasMany Field named Invoices.
Finally, for the Action's Params Liquid property, use the following format to update the child app's Field with the parent app's Field:
<field_name>:{{field_name}}Our Action will look like this:
Note: If you're updating a custom Field (that is, a Field that is not one of every app's default Fields: name, requester_name, curr_state_name, etc.) in the Params Liquid property, you must prepend p_ to the Field's Name. E.g., p_matter_id
Tip: If you need to keep more than one set of Fields (with the same name) in sync, you can list each Field parameter on separate lines in the Params Liquid property, as seen in the example below:
p_matter_id: {{matter_id}}
p_matter_type: {{matter_type}}
p_vendor: {{vendor}}Select OK to save your Action.
3. Tie Your Action to a Transaction Updated Business Rule
Lastly, attach this Action to a Transaction Updated Business Rule so it will run whenever the parent transaction is updated.
Note: See our Creating a Business Rule tutorial for more help with Business Rules.
Select OK to save your Business Rule.
Test It Out
Good work! You've just configured an Action which will ensure the values of Fields with a shared name on your related apps are always in sync.
To try it out, try updating a shared value in a parent transaction. Check your child transaction to ensure that value has been updated.
Configuration for Fields with Different Names
Let's now walk through how to configure this Action to keep the values of Fields with different names in sync across apps.
When Fields are named differently, this Action's configuration gets a little more complicated; we'll need to use a Field Calculation on our child Field to fetch the updated value from the parent app's Field. To fire this Field Calculation however, we will need to tickle an update on the entire transaction by updating a separate, hidden Field. (Don't worry, this will make more sense after we're done configuring it.)
We're going to use the same apps in this example as we did above, but instead say that, for some reason or another, the Field in our parent Matter app has to have a name of matter_number while the Field in the child Invoices app needs to have a name of matter_id. Let's get started.
1. Make Child Fields Read Only
As above, you'll want to make sure only one version of a Field is editable.
We'll open the App Builder wizard of our Invoices app and make sure our matter_id Field's Read Only property is selected.
2. Create Field Calculations for Child Fields
Next, you'll need to write a Field Calculation for any of the Fields you want to stay in sync with the related transaction. This calculation will be responsible for fetching the related Field's new value.
Still in the wizard, we'll browse to the Advanced properties tab of the matter_id Field and provide a Liquid Field Calculation in the Script property in the following format:
{{name_of_relation_field.name_of_field_to_sync_with}}If you need help writing a Liquid Field Calculation, see our Configuring a Calculated Value for a Field tutorial.
If you're new to Liquid and want to understand why this script works, our Arrays section of the Crash Course on Liquid tutorial will help.
In our case, our relation Field is a BelongsTo Field with a name of matter and the name of the shared Field we want our Invoices transaction to be in sync with is matter_number so our Script will look as follows:
Note: You'll want to provide a Liquid Field Calculation like this for each Field you want kept in sync with the related transaction.
3. Add a Hidden Field to Run the Update Related Transaction(s) Action On
Before leaving the Invoices' App Builder wizard, we need to add a new Field for our Update Related Transaction(s) Action to run on. Since the recalculation of one Field triggers the recalculation of all other Fields in a transaction, this hidden Field will prompt the Fields you provided a calculations for to go fetch any new related Field values.
Add a new Text Field and set this Field to always be hidden. We'll create a Field named hidden_update in this example.
Hint: To set a Field to always be hidden, you can provide a value of true in the Field's Hidden Condition property.
See our Conditionally Hiding a Field tutorial for more information.
We also recommend unselecting the Show on dashboard property for this Field.
Update your app.
4. Create an Update Related Transaction(s) Action to Run on the Hidden Field
Browse to the Advanced Designer of the app where the editable version of your Field lives. For us, that's our Matter app.
Add a new Update Related Transaction(s) Action and provide it with a Name.
As above, select the HasMany of the child app whose Field values you want to stay in sync from the Relation Property dropdown. (For us, that's a HasMany named Invoices.)
For the Action's Params Liquid property, we're going to direct our Action to update the hidden Field we just created in Step 3 above in the following format:
<hidden_field_name>:{{some_value}}It really does not matter what the value for this Field is updated to since it's hidden. It's only job is to trigger the Field Calculations we set up earlier.
Our Action will look something like this:
Save your Action by selecting OK.
5. Tie Your Action to a Business Rule
As above, tie your Action to a Transaction Updated Business Rule and select OK to save it.
Test It Out
Congrats! With a little extra work we've configured an Action which will ensure the values of Fields with different names on related apps are always in sync.
As above, test out your work by updating your matter_number Field's value in a parent transaction. Check one of its child transactions to ensure that its matter_id value has been updated.