Working with Related Records

by Christina Moore Updated Aug 19, 2019

It is often helpful and necessary to relate two or more Records to each other. As explained in other tutorials -- Creating a Sibling Relationship and Creating a Parent-Child Relationship -- you can create both parent/child and sibling relationships in Onit.

In this tutorial, we will discuss various actions that Onit offers which take advantage of these relationships. Firing these Actions achieve all kinds of helpful solutions, such as:

  • How to keep two different Records (in two different apps) in sync from a Phase-standpoint. For example, when Record A changes to Phase 2, change the Phase of related Record B.
  • When a Record in one App closes, use this as a trigger to close a related Record in a different App.
  • When an event occurs on Record A, use this as a trigger to create one or more Records in a related app.
  • When an event occurs on Record A in App X, perform a lookup into App B for a Record that matches certain properties. If a match is found, relate Record A with the matching Record in App B. If no match is found, create a new Record in App B.
  • And more…

Use Case for this Action: Remotely changes the Phase of a related Record. For example, once a Record in App A reaches the “Done” phase a Business Rule will fire a Change Phase for Related Transactions to change the phase of the Record in App B to “Done”.

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties:

  • Relation Property: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App (i.e., the App containing the Record whose Phase you want to change).
  • Phase: Name of the phase you want to change the related Record to (e.g., Review).

FYIs:

  • The Record you are changing the Phase on must already be related to the Record you are changing the Phase from.
  • The Phase you are changing the related Record to must already exist on the related App.

Use Case for this Action: Used to close related Records. For example, once a Record in App A reaches the closed phase a Close Related Transactions Action will change the Record in App B to closed.

Note: When a Record is closed, it can no longer be edited by any user. In addition, closed records have a status value of Completed. You can offer users a Button to both close and re-open a Record.

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties:

  • Related Atom Field: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App (i.e., the App containing the Record whose Phase you want to close).

Use Case for this Action: Creates one or more related Record based on the configuration defined in a List. For example, once a Project Record is created in App A a related budget Record will be created in App B. For more information about this Action, see Automatically Creating Child Records.

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties:

  • Related Atom Field: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App (i.e., the App in which you want to create new records).
  • List Name: A List uploaded to Onit to query the parent Record's Fields and input the values into the child Record’s Fields. For more information on how to format this List see Automatically Creating Child Records.
  • Copy Documents: Check this box to copy existing documents on the parent Record to the child Record. The child Record must have an attachment Field with the same name as the parent Field to receive the file.

Use Case for this Action: The Find or Create Related Transaction Action searches for related Records that match a specified criterion. If a Record is found it is related to the source Record and optionally may be updated with no metadata. If no Record is found then a new Record will be automatically created and populated with metadata. If you are familiar with databases, this works similar to an upsert. For example, a budget Record in App A is created with the same name as a matter Record in App A. The Find or Create Related Transaction searches for the budget Record in App B and relates it to the matter Record in App A of the same name.  

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties: 

  • Related Property Name: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App (i.e., the App in which you want to perform the upsert).
  • Relation Field Name: The name of the Field in the target App against which the lookup will be performed. For any custom created Field (i.e., any Field other than namerequester_name, or requester_email), you must prepend the Field’s name with p_ (e.g., p_country or p_amount).
  • Relation Field Value: The lookup value. This value must be in the Field specified directly above. You can hardcode a value into this Field or use a Liquid expression. Using Liquid allows you to variablize the lookup value, potentially using data that lives on the source Record (i.e., the Record that triggered the Find or Create Related Transaction Action to run).
    • Example #1: Let’s say that you want the Find or Create Related Transaction Action to look in App B for a Record with a value of Foo in the bar field. To achieve this, when configuring the Action, the Relation Field Name property should be p_bar and the Relation Field Value property should be Foo.
  • Example #2: Consider Example #1 above  but with a twist! Instead of the lookup value being a hardcoded value, let’s say that the lookup value should instead be whatever the value is within a field named baz on the source Record (i.e., the Record that triggered the Find or Create Related Transaction Action to run). To achieve this, when configuring the Action, the Relation Field Name property should be p_bar and the Relation Field Value property should be {{baz}}.
  • Params Liquid: Values to be updated on or inserted into the upserted Record. Values must be written in the following format field_name_on_target_app:{{ value_from_current_app }}. When specifying the Field name (on the left-side of the colon), any custom created Field (i.e., any Field other than name, requester_name, or requester_email) must be prepended with p_ (e.g., p_country or p_amount). Any field names referenced in Liquid expressions (to the right of the colon) do not need p_ to be prepended to them. To update multiple Fields at once each Field should be separated by a carriage return (as seen below).

FYIs: 

  • The lookup performed into the target App will only return a SINGLE Record. If multiple matches are found, only the oldest Record will be returned. As a result, as a best practice it is recommended that your lookup be configured to run against a Field (in the target App) that is guaranteed to be unique.
  • Any new Record that is created by this Action must provide a value for the namerequester_name, and requester_email Fields, otherwise an error will thrown. The obvious exception is if other configuration logic (outside of this Action) is being used to populate these Fields (e.g., default values in the target App’s Wizard).
  • If you are using this action across a HasMany - BelongsTo relation, make sure that the BelongsTo Field has a name that is not plural, or the Action will fail.

Relate to Transaction Action

Use Case for this Action: Relate the current Record (in a source App) to another existing Record (usually in a different App). For example a budget Record in App A will be related to a matter Record in App B through the budget Field. 

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties: 

  • Related Transaction Id: Atom ID of the Record to be related. You can use a Liquid expression to set this value - the ID can be retrieved by calling {{id}} on a Record.
  • Related Property Name: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App.

Use Case for this Action: Update an existing related Record with new metadata. For example, a budget Record in App A is updated with new totals, then the Update Related Transaction(s) Action updates the related matter Record in App B with the new budget total.

Type of Relation: HasMany / BelongsTo or ManytoMany

Configuration Properties:

  • Relation Property: A dropdown list of relational Fields on the current App. Choose the Field that relates to the target App.
  • Filter: A Raw Transaction Filter that returns the Records that you want to update. This Filter is optional  if you don’t provide a Filter then all related Records will be updated.
  • Params Liquid: Values to be updated on the related Record. Values must be written in the following format field_name_on_target_app:{{ value_from_current_app }}. When specifying the Field name (on the left-side of the colon), any custom created Field (i.e., any Field other than name, requester_name, or requester_email) must be prepended with p_ (e.g., p_country or p_amount). Any field names referenced in Liquid expressions (to the right of the colon) do not need p_ to be prepended to them. To update multiple Fields at once each Field should be separated by a carriage return.

Relating Records using the Update Transaction Action

Using the Update Transaction Action (not described above), you can update a Record’s Field values. While this Action is technically designed to only update the source Record (i.e., the Record that triggered the Action to run), below is a handy configuration trick to relate the source Record to a (different) target Record. Note that this trick only works when the target Record is a child of a parent (i.e., the target Record has a BelongsTo field).

To achieve this, in the Update Transaction Action, configure the Params Liquid property using this pattern: r_[belongs_to_field]_id:123456. Let’s break this down:

  • The value to the left of the colon is the name of BelongsTo field, prepended with r_ and appended with _id. For example, if the actual BelongsTo Field is named invoices, you would use r_invoices_id.
  • The value to the right of the colon is the ID number of the Record that you want to relate the source Record to. You can hardcode the ID number (as seen above with 123456), or this can be a Liquid expression (the ID that you need is the same one that is retrieved by calling {{id}} on a Record).

This trick shown above would achieve the same result as if you had instead used the Relate to Transaction Action (explained earlier in this tutorial). The extra benefit that you get with Relate to Transaction is that it can also set other Field values on the source Record (in addition to the BelongsTo field).

How to Unrelate Two Records

To unrelate two Records from one another fire an Update Transaction Action and set the Params Liquid property to r_belongsTo field name_id: with nothing after the colon. This will break the relationship between the two Records. 

Previous Article Automatically Creating Child Records
Next Article Configuring a Create Related Transaction Button

© 2020 Onit, Inc.

docs.onit.com contains proprietary and confidential information owned by Onit, Inc. that is subject to copyright. Onit presents it exclusively to you for your sole use in conjunction with using Onit products. No portion of the materials contained herein may be used for any other purpose. No portion of the materials contained herein may be shared with third parties or reproduced in any form.