Onit Documentation

A Contextual Guide to Accessing Variables from Different Business Rules

by David Goldfarb Updated on

When it comes to Onit app building, context is king! The Liquid syntax required to access any particular Onit object may change based on location in which it is used. For example, to access a Record’s Field value, the Liquid syntax within a Condition would be different if it lives in a Transaction Created versus a Participant Added Business Rule. Always keep context in mind when constructing your Liquid.

In this tutorial, we’ll provide a contextually-focused breakdown of all Business Rules, explaining which objects each Rule has access to and the specific syntax that you should use.

Before We Start ...

A few important points to be aware of before reading this tutorial:

  • Available Contexts: For each Business Rule below, we’ve identified its available contextsThat said, the concept of a context may be somewhat confusing without an example. For instance, a Condition that lives within a Participant Added Business Rule has a default context of: the Participant. In other words, Liquid in a Condition that fires under a Participant Added Business Rule assumes that you want to extract data off of the Participant – not the Record. If, in this example, you want to instead extract data off of the Record that the Participant was added to, you must use atom. in front of the Record property (e.g., the Field name) that you want to access, to change the Liquid expression's context (e.g., {% if atom.name %}true{% endif %}). In this example, the Participant is the primary context and the Record is the alternate context.

  • Condition versus Action: Interestingly, if you have a Condition and an Action tied to the same Business Rule, they may have different default contexts, depending on the Business Rule's type. For example, a Condition assigned to Participant Added Business Rule has a default context of: the Participant; an Action associated with the same Business Rule, on the other hand, has a default context of: the Record. As a result, where relevant, below we've listed both the Action's contexts and the Condition's contexts.

  • Simple versus Complex: Business Rules that are triggered by Record-related events (e.g., Transaction Initiated, Transaction Created, Transaction Phase Change, etc.) are generally simpler and more straight-forward with respect to contexts: they offer a single context, which is the Record. Alternatively, non-Record-related Business Rules (e.g., Participant Added, Comment Added, Email Received) are more complex, as they provide multiple contexts to choose from. This (somewhat reductive) classification may be helpful to keep in mind.

  • Current User: In addition to the contexts explicitly mentioned below, all Business Rules have perpetual access to current_user. This is a one-dimensional array that returns properties about the Onit user that triggered the Business Rule to fire (e.g., current_user.name and current_user.email).

  • Conditional Compound Actions (CCAs): CCAs can have their very own condition. If the CCA is fired by a Participant-related Business Rule, an Email Received Business Rule, or a Comment Added Business Rule the context of the CCA's condition is the participant, email, or comment respectively.

    Placing an Action inside a CCA will (in most cases) force the context of the child Action to always become that of the Record. It is important to realize that the context of the CCA’s condition and the Action(s) inside the CCA may be different.

  • Not Exhaustive: This tutorial does not list every possible context that is available to any given Business Rule. If you come across a missing object/context, please let us know!

Business Rule: Transaction Initiated

  • Business Rule Description: Occurs during Record creation before the Record enters any workflow and before the Transaction Created Business Rule. This Business Rule is primarily used to populate the Record with Participants before it traverses through any Phases.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Transaction Created

  • Business Rule Description: Occurs during Record Creation immediately after the Transaction Initiated Business Rule. By the time this Business Rule fires the Record may have already traversed through one or more Phases.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Transaction Phase Change

  • Business Rule Description: Occurs when a Record undergoes a Phase change.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Transaction Updated

  • Business Rule Description: Occurs when a Record is updated.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Note: The atom.changed_values array, available to you with the Transaction Updated Business Rule, changes between each execution of any Business Rule even if the Record has not been updated between calls. When hanging logic off an atom.changed_values array you must reference the first instance of the array directly after the Record updates. 

For example: a Record is updated and a Transaction Phase Change Business Rule fires to send a notification, then a Transaction Updated Business Rule fires to check the atom.changed_values array for specific changes. The Transaction Updated Business Rule will not return the correct results because the atom.changed_values array has been mutated between the two calls, even though the Record was not updated twice. If the atom.changed_values array must be referenced after another Business Rule fires you should park the returned array in a hidden Field, then reference the Field.

For more information on the atom.changed_values array see this reference material.

Business Rule: Transaction Completed

  • Business Rule Description: Occurs when a Record is completed. This occurs whenever a user clicks the Record’s Close Project Button or when a Close Action fires on a Record.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Transaction Reopened

  • Business Rule Description: Occurs when a closed Record has been reopened. This occurs whenever a user clicks the Record’s Reopen Button or when a Reopen Action fires on a Record.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Transaction Deleted

  • Business Rule Description: Occurs when a Record is deleted.

  • Available Context(s) for Actions: The Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: The Record. For example, a Condition assigned to this Business Rule could retrieve the record's name using: {% if name contains "foo" %}true{% endif %}.

Business Rule: Participant Added

  • Business Rule Description: Occurs when a Participant is added to a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions:
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.


  • Available Object(s) for the Action:
    • Endorsement. A special object called endorsement is available for use in this Business Rule. Note it is endorsement singular, not plural. Endorsement allows you to write Liquid like the following:
{{endorsement.email}} has disputed invoice {{name}}

by providing access to the most recent endorser of the Record. The catch is endorsement is only available on a Send Notification Action.

Business Rule: Participant Activated

  • Business Rule Description: Occurs when a Participant is activated on a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.
  • Available Object(s) for the Action:
    • Endorsement. A special object called endorsement is available for use in this Business Rule. Note it is endorsement singular, not plural. Endorsement allows you to write Liquid like the following:
{{endorsement.email}} has disputed invoice {{name}}

by providing access to the most recent endorser of the Record. The catch is endorsement is only available on a Send Notification Action.

Business Rule: Participant Deleted

  • Business Rule Description: Occurs when a Participant is deleted from a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: 
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.

Business Rule: Participant Approved

  • Business Rule Description: Occurs when a Participant approves a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions: 
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.
  • Available Object(s) for the Action:
    • Endorsement. A special object called endorsement is available for use in this Business Rule. Note it is endorsement singular, not plural. Endorsement allows you to write Liquid like the following:
{{endorsement.email}} has disputed invoice {{name}}

by providing access to the most recent endorser of the Record. The catch is endorsement is only available on a Send Notification Action.

Business Rule: Participant Rejected

  • Business Rule Description: Occurs when a Participant rejects a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions:
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.
  • Available Object(s) for the Action:
    • Endorsement. A special object called endorsement is available for use in this Business Rule. Note it is endorsement singular, not plural. Endorsement allows you to write Liquid like the following:
{{endorsement.email}} has disputed invoice {{name}}

by providing access to the most recent endorser of the Record. The catch is endorsement is only available on a Send Notification Action.

Business Rule: Participant Approved by Proxy

  • Business Rule Description: Occurs when a Participant approves a Record by proxy.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.

Business Rule: Participant Reset

  • Business Rule Description: Occurs when a Participant's approval or rejection is reset back to "pending."

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions
    • The Participant. For example, after the Business Rule runs, a Condition checks to see if the Participant in question's Role is Matter Manager. If so the Condition returns a value of true. The Condition should use the following Liquid:{% if role == "Matter Manager" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.

Business Rule: Comment Added

  • Business Rule Description: Occurs when a comment is added to a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions
    • The Comment. For example, after a comment is made on a Record, a Send Notification Action should only fire if the comment contains the string foo. To build such a Condition,  use the following Liquid: {% if message contains "Foo" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.

Business Rule: Email Received

  • Business Rule Description: Occurs when an email is received by a Record.

  • Available Context(s) for ActionsThe Record. For example, an Action assigned to this Business Rule could retrieve the record's name using: {{name}}.

  • Available Context(s) for Conditions
    • The Email. For example, after an email is received by the Record a Condition will check to see if the subject contains foo -- if it does then the Action will fire. This Condition would use the following Liquid:{% if subject contains "foo" %}true{% endif %}.

    • The Record. To access any property on the Record prepend atom. in front of the property. For example, after this Business Rule runs, you want to fire a Send Notification Action, but only if the Record's phase equals Onboarding. The Condition should use the following Liquid: {% if atom.phase == "Onboarding" %}true{% endif %}.

Any action tied to an Email Received Business Rule should always be backgrounded so it can run asynchronously. The email service that facilitates receiving emails in Onit expects actions fired by the Email Received to perform asynchronously. If you do not fire an async action off of Email Received Business Rules, you will run into unintended and unexpected behavior.

Business Rule: Daily Schedule

  • Business Rule Description: Runs automatically every day at 3am (while the time zone is CST for most clients, this will differ for clients not in Onit’s US-based data center). Daily Schedule Business Rules can have either a user Filter (which returns users) or a transaction Filter (which returns Records). If the Daily Schedule fires a Multi Report or Send Report Action, the Filter on the Daily Schedule must be a user Filter (to define who should receive the email-based report).

  • Available Contexts & Examples: Daily Schedule’s are different from normal Business Rules, in that they act on many Records at once. The default context changes depending on whether the Daily Schedule has been assigned a user Filter or a transaction Filter:

    • User Filter: As mentioned above, this Filter should only be used when firing a Multi Report or a Send Report Action. For both of these Actions, an object named atoms will be available – this object contains all of the Record within an app that match the criteria defined in a second transaction Filter that lives on the Action (in other words, there is one user Filter assigned to the Daily Schedule and a second transaction Filter that lives on the Action). You can loop over atoms to access each Record. For example: {% for a in atoms %}a.name{% endfor %}.

    • Transaction Filter: When firing any non-Multi Report or non-Send Report Action from a Daily Schedule, the Action has a context of the Record in question. For example, let’s say that you have an Update Transaction Action that fires from a Daily Schedule. In this situation, the Daily Schedule can be assigned a transaction Filter – the Update Transaction Action will fire on each Record returned by the Filter (one by one) and that Action will have a default context of the Record in question.

Note: For the Daily Schedule examples above, Actions and Conditions share the same available contexts.

Previous Article Onit System Limits
Next Article App Builder Objects Interactive Diagram

© 2024 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.