Logical Expressions

A logical expression is a way of saying "if this is true, then do that". For example:

If field segment control SEG1 is set to "Yes", then set text field SMT1 to required.

Logical expressions are used to dynamically adjust the display properties of documents, custom fields, and assets/tasks at runtime, as users type and enter data.

We use logical expressions inside Documents within the Visibility properties that are available for every control:

• Hidden If – if the expression evaluates to true, the field will be hidden from display
• Required If – if the expression evaluates to true, mark the field as required by displaying the yellow border and background – otherwise, display the field normally
• Disabled If – if the expression evaluates to true, the field can't be edited
• Invalid If – if the expression evaluates to true, the field will be displayed with a red border and background showing there is an error

We also use logical expressions inside Custom Fields:

• Required If – if the expression evaluates to true, the field will be displayed with the default required yellow border and background

Logical Expression Syntax

Logical expressions can be hand typed or created in our expressions builder. A logical expression looks like:

'A' == 'B'

This expression evaluates the statement "A equals B", which is obviously false.

'A' != 'B'

This means that "A does not equal B", which is obviously true.

Expressions are made up of:

• A left side
• An operator or "condition" to test, such as "="
• A right side

The left side of the expression is compared to the right side of the expression and evaluates to true or false.

NOTE – All quotation marks (double and single) MUST be straight quotes, NOT smart/curly. Beware when copy and pasting from other sources. ie: "task.name" will work, while “task.name” will not.

Operators in Field Squared Expressions

The Operators you can test are taken straight out of JavaScript syntax:

• == means Equals
• != means Does Not Equal
• < means Is Less Than
• <= means Is Less Than Or Equal To
• > means Is Greater Than
• >= means Is Greater Than or Equal To

Logical expressions that compare text (also known as string expressions) can only use the == and != operators.

Logical expressions that compare numbers (numeric expressions) can use all of the operators.

Using Expressions with Document Controls and Custom Fields

String and numeric expressions can also work dynamically with document controls, custom fields, tasks, users etc. just like other expressions. For example:

{document.SLIDER1} > 100

The field that has the expression on it doesn't need to be referenced inside the expression. In fact most won't. For example: "hide this field if segment control SEG1 has a value of 'No'.

Using Expressions to test if a Control is empty (or not)

Both numeric and string expressions can also test if a value exists using the null keyword.

{document.SLIDER1} == null

This means "this expression evaluates to true if the value of Slider 1 does not have a value".

You can also test != null to test if another control has a value.

Dynamic Updates

Expressions are updated dynamically as you type. Try it – it can be cool to watch a logical expression in action.

The exception to this are Hidden If expressions which are only evaluated when the Document, Task, Contact, Asset, User, or Team is first opened.

Logical String Expressions

A logical string expression compares two text values and returns true or false.

For string expressions it's important that both sides of the expression are surrounded by single quotation marks. For example: 'text'

Let's say that you have a segment control called "Inspection Complete" with values of Yes, No, and Partial.  You want to prevent people from signing their signature unless the Inspection Complete segment control is set to Yes. In this case you would add an expression to the Disabled If section of the Signature control as follows:

'{document.SEG1}' != 'Yes'

This means "if the value of SEG1 is not set to Yes, then disable this control".

All tests within logical string expressions are case sensitive at all times.

You can reference objects outside of the current object in logical string expressions. For example, inside of a Document, you could set a Required If field to see if the Task Name of the task that owns this document has the value "My Task Name" using this expression:

'{task.name}' == 'My Task Name'

All the rules for string expressions apply to logical string expressions as well.

Note that BOTH sides of the expression have single quotes around them. You also have to make sure that you're using straight quotes like this ' and not angled quotes like ‛ or ’ and that you're not using "double quotes" either. Expressions will fail unless you use single quotes on both sides.

You can combine expressions together to make complex logical expressions.

'{task.name} – {user.initials}' == 'My Job Name – JD'

The left hand side is evaluated first where task.name is replaced with My Job Name and user.initials is replaced with JD.  The plain text that's in the expression which is ' – ' is copied into the result as is (including any spaces). The final outcome of the left hand side will be 'My Job Name – JD'.  This is then compared to the right hand side. This expression would evaluate to true and hide the control.

Finally, you can compare string expressions to see if they exist or not, by comparing to null. For example, to make a document control SMT1 mandatory, add this expression to the Required If configuration:

'{document.SMT1}' == null

Note that this is case-sensitive and all the rules for string expressions apply.

You can compare the value of two fields with one another.

In summary, a logical string expression:

• compares two pieces of text to one another
• both values must be text (strings) or null
• both sides of the expression need to be surrounded by single quotes
• the supported operators are == and !=
• to test if something has a value, use != null – if something doesn't have a value, use == null

Logical Numeric Expressions

A logical numeric expression can compare number values and do math calculations. A logical numerical expression without using any bindings or dynamic values would be something like this example:

1 < 2

This compares the left side to the right side, and clearly 1 is less than 2, so this will evaluate to true.

You can use logical numeric expressions to compare numbers to one another that come from document controls or custom fields. For example:

{document.SLIDER1} < 100

If SLIDER1 (which is a slider control) has values from 0 to 1,000 and the current value is less than 100, then this expression will evaluate to true.

We can extend this further to compare values from the current document to values that are on other controls or custom fields. For example:

{document.SLIDER1} < {asset.data.MIN_PRESSURE}

In this case, if the value in SLIDER1 is less than the minimum pressure custom field value for this asset, then this expression will evaluate to true.

You can also perform math operations in numeric logical expressions:

{document.SLIDER1} * {document.SMT1} > {task.data.EXPECTED_PRODUCTION}

This would multiply the value in SLIDER1 (a slider) by the value in SMT1 (a smart text field set to a keypad type of decimal), and then see if that value is greater than the EXPECTED_PRODUCTION custom field on the task this document is about.

Math expressions we support include:

• + adds values together
• – subtracts values
• * multiples values
• / divides values (be careful not to divide by zero!)

You can use parentheses ( and ) to group expressions together and perform order of operations calculations on fields:

({document.SLIDER1} + {document.SLIDER2}) * {document.SMT1} < 10

You can chain expressions together from any combination of objects in math expressions within logical numeric expressions, for example to compare daily production (stored in SLIDER1) with the expected production for the current work order (based on the asset the work order was created for) to make sure that production is at least at 90%, you would use the following expression:

{document.SLIDER1} / {task.firstAsset.data.BBL} < 0.9

For more details on math expressions, see our Math Expressions article.

Logical Math Expressions on Lists and Details Tables

Math expressions can also read values from Details Tables and from the asset hierarchy.

To read values from a Details Table in the current document, you can use the standard functions for working with details tables as part of logical numeric expressions.

For example, the expression to calculate the sum of the TOTAL property in a details table is:

{document.DTL1.Sum('TOTAL')}

This expression with add up all the non-null values in the TOTAL column within the details table DTL1.

The functions available on details tables are described in the Math Expressions article.

For example, if you have a rule that the customer signature is required and a waiver needs to be signed if the total job value in a details table is more than $1,000, you would use an expression like the following on both the Signature Control and the Terms Accepted checkbox:

Required If configured as {document.DTL1.Sum('TOTAL')} > 1000

This logic works for other objects that contain lists. If you want to make a field required for documents that are about an asset and has at least 2 child assets, the expression would be created against the children property on the asset object (which is a list of assets):

{asset.children.Count()} >= 2

Always True

There is a special expression you can use to always evaluate a logical expression (math or string) to true, and that is:

{true}

Whenever this expression is encountered within a Required If, Disabled If, Invalid If, or Hidden If expression, the system will evaluate the expression.

Likewise you can make an expression always return false (the default) using the expression:

{false}