Expression Validation

🕙 8 minute read
Advanced Javascript

Catalytic fields support entry validation, which prevents or restricts a user from submitting a form or task when a field has incorrect data. Different field types have different validation methods, for example, you can set a max or min value for an Integer, and Decimal field types, or pattern validation for Text field types.

Safari browser bar

With expression validation, you can now set even more powerful, complex validation rules for your fields. The expression uses a Javascript syntax similar to the Field: Field formulas action, which means you’ll need familiarity with Javascript.

For example, you could write the expression (startsWith("SKU", this), to restrict entries to anything starting with SKU, or it could be more complex, ((startsWith("SKU", this) or (startsWith("#", this)), which restricts entries to anything starting with SKU or #

screen readers look here

Expression validation is available on all field types. You can add expression validation by selecting Expression next time you add entry validation. To learn more about entry validation, check the Apply entry validation to fields article.

How to use expression validation

The expression validation is based off of the Javascript library Math.js and has access to all basic Math.js calls. Use this as an object in your expression to create statements, such as this > 5

Here are other things to keep in mind when writing expression:

  • Reference the value of the field itself using this. For example, this > 5.
  • Reference other field values by their Display name. Fields are referenced in two ways:
    • If the field has spaces, use field["field name with spaces"].
    • If the field has no spaces, use field.fieldnamewithoutspaces For example, this == field["field name"].
  • Because this is a validator, you cannot create or assign values using an expression. For example, if you set an expression validation on field 1 to: field["field2"] == "Mango"—you cannot assign a value. The expression must include a this.
  • There is no need to use result =, as is common in other languages, as this is just a validator and no result is created.
  • Expression validation works dynamically, so you can set up validation on other fields, even if those fields are configured in the same step. In other words, if you have two fields in a web form, you can set up an expression validation so the second field is dependent on the first, such as this > field.field1.

Expression validation has built in hinting, and syntax highlighting. As you begin typing, suggested calls or elements appear as options in a drop down. At this time, your expressions are not validated for accuracy, so if you’re encountering an issue, double check the syntax.

Custom Catalytic functions

In addition to the basic Math.js calls, you can use custom catalytic functions in your expressions.

Custom Catalytic Functions
Function Description
DateTime Data structure representing a specific date and time
Duration A Duration object represents a period of time, like “2 months” or “1 day, 1 hour”
now Get the current DateTime
day Get the day of the month (1-30).
daysInMonth The number of days in this DateTime’s month
daysInYear Returns the number of days in this DateTime’s year
hour Get the hour of the day (0-23).
millisecond Get the millisecond of the second (0-999).
minute Get the minute of the hour (0-59).
month Get the month (1-12).
monthLong Get the human readable long month name, such as ‘October’.
monthShort Get the human readable short month name, such as ‘Oct’.
offset Get the UTC offset of this DateTime in minutes
quarter Get the quarter
second Get the second of the minute (0-59).
weekNumber Get the week number of the week year (1-52).
weekYear Get the week year
weekday Get the day of the week.
weekdayLong Get the human readable long weekday, such as ‘Monday’.
weekdayShort Get the human readable short weekday, such as ‘Mon’.
weeksInWeekYear Returns the number of weeks in this DateTime’s year
year Get the year
zoneName Get the name of the time zone.
dateAdd Add a period of time to this DateTime and return the resulting DateTime. Duration | number
dateSubtract Subtract a period of time to this DateTime and return the resulting DateTime. Duration | number
ENDS_WITH Checks if string ends with the given target string.
endsWith Checks if string ends with the given target string.
IS_EMPTY Checks if value is an empty object, collection, map, or set.
isEmpty Checks if value is an empty object, collection, map, or set.
IN Checks if value is in collection.
includes Checks if value is in collection.
STARTS_WITH Checks if string starts with the given target string.
startsWith Checks if string starts with the given target string.

Basic patterns

Math.js is a popular Javascript library, so there are many examples that are useful as references, but Math.js and Javascript are complicated languages and there may be unpredictable outcomes when making changes. You can see some common examples of Math.js in action on the Math.js Examples page.

Always test a pattern before using it live, there may be certain entries that unintentionally pass the validation. You can test validation from the configure field page by entering in a default value.

Basic comparison

Examples: this > 5, this > field.field1, field.field1 > this

Description: Compare the values in this field, with another field.

Comparison with a calculation

Pattern: this > (5 + field.field1), this > (5 * field['field 1']), (field.field1 + field.field2) > this

Description: Compare the values in this field, to the result of a calculation. Also, use this field in a calculation, then compare it to another field.

String comparison

Pattern: (startsWith("SKU", this),

Description: Use string specific calls like startsWith() to compare the values in text fields.

Using dates in comparisons

Pattern: DateTime(this) <= weekday(now())

Description: Use date specific calls like DateTime() to compare the values in date or date and time fields.

Pattern: DateTime(this) >= DateTime(now())

Description: Date must be after today.

Pattern: weekday(this) == 1 or weekday(this) == 2 or weekday(this) == 3 or weekday(this) == 4 or weekday(this) == 5

Description Date must be a weekday, Monday through Friday

Pattern: weekday(this) == 6 or weekday(this) == 7

Description Date must be a weekend, Saturday or Friday

Pattern: day(this) >= (day(now())+3)

Description: Date must be 3 or more days after today

Explanation: This expression says “The date entered must be 3 days from now, or later”—in other words, the user can’t choose a date less than 3 days from now. Change the 3 to change how many days from today are allowed.

Pattern: (day(this) >= (day(now())) and (day(this) <= day(now())+2))

Description: Date must be between today and 3 days from today.

Explanation: This expression uses an and operator to create a multi-part condition. The first section, (day(this) >= (day(now())) says “The date entered must be greater than or equal to the date today”—in other words, the user can’t choose a date in the past. The second section, (day(this) <= day(now())+2)), says “The date entered must be no more than 2 days from today”—in other words, the user can’t choose a date more than 2 days from now. Change the 2 to change how many days from today are allowed. The and operator combines the two conditions, so it says “The date entered must be between today and 2 days from today.”

Multiple comparisons using operators

Examples: ((this > 5) and (this < 2)), ((startsWith("SKU", this) or (startsWith("#", this))

Description: Link multiple comparisons together using and and or to compare the values in this field, with another field,

How to add entry validation to a field

You can add entry validation from the configure field page, such as an Instance Field or form field. Expression validation works for any field type.

  1. From the Workflow Builder page, click open the Triggers and Fields section to head to your Instance Fields.

  2. Select Add a Field. Scroll to the middle and look for Entry Validation.

    screen readers look here
  3. Select Add a Validation under the Entry Validation section.
  4. Select the entry validation type from the drop down list, then enter the value.
  5. Optionally add an error message under the Error Message section.

Here’s an example of the process for a text field:

Safari browser bar

To learn more about testing validation, adding other types of validation, or how to test validation, check the full Apply entry validation to fields article.

Get help with a problem or question

If something’s not working as expected, or you’re looking for suggestions, check through the options below.

My expression validation is not working

The first thing to check is if your syntax is correct, such as a missing { or ". The expression validation does not have built in syntax validation, so it will not alert of incorrect formatting like modern IDEs.