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: 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 B 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 name, requester_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).

• Shared Liquid: You can assign values to variables here, then use those values in the Params Liquid or Field Updates section below. If you have a calculation that you want to use more than once, then calculating it here can improve performance. You can also use this section for list_lookup_atom.

• Field Updates: This is an alternate method of populating Fields in your new or updated Record. Each line here lets you select one Field, and populate it with the Liquid you put. One advantage of this section is that colon (:) and comma (,) are not treated as special characters.

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 name, requester_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.

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).

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).

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. 

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.