Onit Documentation

Using a UI Action to Update Fields

by David Goldfarb Updated on

UI Actions are used to dynamically update one or more Fields' values in real-time on an app's Launch Page.

For example, requesters may need to provide a currency amount for three different Fields. Before they submit their requests however, it might be useful for them to see the total of those currency Fields. A UI Action can be used to populate the total of those Fields as the user is entering values.

UI Actions are a simple but powerful way to streamline the request process while limiting data entry errors.

UI Actions differ from Fields Calculations in that the calculation of a Field is done on creation or update of a transaction, whereas UI Actions update Field values in real-time.

Before We Start ...

This tutorial will assume you understand the following concepts:

Let's Get Started!

In this tutorial, we'll create a UI Action to populate the total of three Currency Fields.

1. Create Your Fields

Create three Fields with a Type of Currency. In this example, we’ll name them item_1, item_2 and item_3. These will be the Fields we ask our UI Action to add together.

Create a fourth Field, also with a Type of Currency. Name this Field total and make it a Read Only Field. This will be the Field where the UI Action prints the total of our item Fields as its value.

2. Add an Update Fields UI Action

Browse to the Advanced Designer page. Select UI Actions from the left-hand pane.

Select Update Fields from the UI Action Add dropdown.

Tip: UI Actions can also set the content of a Multiselect Field. You can use a comma-separated list of values, or if your value has a comma in it we also support JSON: ["Acme, Corp.","Onit, Inc."]. 

To generate JSON for your Multiselect Field use the following Liquid guide:

{% assign list  = "Coyote|Acme, Corp.|Roadrunner" %}
{% assign list_split = list | split: "|" %} 
{% assign json = list_split | to_json %} 
{{json}}

This Liquid splits the original list on the delimiter (in this case a pipe, '|'), then converts the split list to JSON using the to_json Liquid filter. Plug in your pipe delineated list in the list variable, and the Liquid will do the rest.

Note: if you want to empty out your Multiselect, you can't do so by just putting an empty string in it. You need to put in an empty JSON array, which looks like this:

[]

3. Configure the UI Action

Provide the new UI Action with a Name. We’ll give our UI Action a name of Get Total.

Select the Add button to add a new Field Update.  

From the Field dropdown, select the Field that should display the result of the UI Action, in this example the Total Field.

In the Liquid property, write your UI Action.

New to Liquid? Check out our Crash Course on Liquid tutorial. Focus on how to write an expression that provides an output.

If you need to reference the value of a parent Record's Field in your UI Action, you must prepend r_ to the Field Name. (e.g., {{r_parent.name}}).

Save the UI Action by selecting Ok.

4. Linking the UI Action to a Field

For our UI Action to work, we need to link it to the Fields that will trigger it to run. In this case, we should link it to each of the item Fields we created so that it runs every time each one of those Field values change.

Return to the Wizard.

Under each item Fields’ Properties, select the UI Action you created from the UI Action dropdown.

Update your app.

See Your UI Action at Work

Congrats! You’ve created your first UI Action!

To see it at work, launch a new transaction. Try entering some currency values in your item Fields. Your Total Field will update as you enter values.

More UI Actions

Run on Launch

You can choose to run a UI Action when the user launches the App to create a new Record. This sort of UI Action is useful in situations where you want the Launch Screen to with certain Fields pre-populated, based on dynamic Liquid calculations. For example, maybe you want to prepopulate a Department Field with the name the department that the current user works in  in this situation you’d build a “run on launch” UI action that performs a lookup into another that returns the current user’s department.

So, when should you use a UI validator versus a Regex Validator? UI validators can make decisions and perform list lookups which Regex validators cannot do. For example, a UI validator could be used to take a value entered by a user and cross check the data with another App. A Regex validator allows for robust pattern matching, for example matching phone numbers or social security numbers. Regex validators cannot perform list lookups. For more information on Regex validators see this tutorial.

Note: Run on Launch UI Actions must be assigned to a Field to function properly.

To build this type of UI action:

  1. Create a UI Action, like you normally would and assign the UI Action to a Field. Our App builders like to create a special hidden Field for this purpose. For more information on assigning a UI Action to a Field see this tutorial.
  2. Go to the App’s Settings page.
  1. Scroll to the bottom of the page and select your created UI Action from the UI Actions to run on launch dropdown.
  1. Click Save.

Using this configuration, when a user opens the App’s Launch Screen, your UI Action will automatically fire!

 

UI Validations

UI Validations are performed on specified Fields in the App’s Launch Screen.

Unlike Validators, UI Validations are not written using regular expressions  they are instead written using Liquid. Validators can be used to show warnings to the user or to prevent the Record from being created when it contains invalid data. They are assigned using an Update Fields UI Action under Field Validations.

In this example a user is first asked to select a Department, and then to enter a Charge Code. Let’s say that all charge codes look like this: XXX-YYYYYY. For all Records in the same department, the XXX value must always be the same, this is the department's identifier number; only the YYYYYY value changes. Our validator’s job is to ensure that the code they enter is valid for the department they selected. To accomplish this, you’ll do a list lookup into a list named Departments that contains a column named Department ID. Your Liquid will cause an error to be thrown if the XXX value doesn't match the select department's ID, as returned by your lookup.

To create a Validator within a UI Action:

  1. Create a new Update Fields UI Action.
  2. Under Field Validations, click the + button.
  3. Choose an appropriate Field and message type for the validation.

Note: Message type of Error will prevent Record creation while Info will not.

Error:

Info:

  1. In Validation Condition, enter your Liquid validation. For this example we will use the following List Lookup to grab the department’s ID from the Departments List:
{% capture entered_department_code %} {{ charge_code | slice: 0, 3 }} {% endcapture %} 
{% assign department_code = department_id | list_lookup: 'Departments', 'department_name', 'department_id' %}
{% if entered_department_code != department_code %} true {% endif %}
  1. Click Save.
  2. Assign the UI Action to the charge_code Field in your App.
  3. Test the validator by trying to create a Record with an incorrect department ID. The launch screen should show errors and prevent Record creation.

Gotchas

  • UI Actions cannot be used to update the same Field they are applied to.
Previous Article Aggregating Related Fields with a Numeric Field Calculation
Next Article Validating Field Values

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