- 3 minutes to read

Formula - equal

The equal function, one of the Logical functions in the Formula plugin for Search Field Expressions, returns true when the content equals the expression.

Syntax 

equal('expression', content [, content ...] [, matchAllValues])

Parameters

Parameter Required Description
'expression' ✅ Yes The text to compare with, in single quotes, for example 'GMT'.
content ✅ Yes The value or values to check: body, context, or another Formula function such as regex. When you give several content arguments, each of them must match.
matchAllValues ❌ No Unquoted true or false (default). Applies when one content argument returns several values: false means at least one value must match, true means every value must match. A quoted 'true' is not the flag; it is compared as text.

Returns

  • true when the content equals the expression.
  • When it doesn't, there is no value: Test Expression shows Processed with warning: The provided expression yielded no result.
  • When one content argument returns several values, one matching value is enough, unless matchAllValues is true.

Quoting, nesting, and how content is resolved are described in the Formula language rules.

Examples

Example 1: Check the message body

Input

Message Body:

GMT

Formula 

equal('GMT', body)

Result 

true

Test Expression with equal('GMT',body) on the message body GMT, returning true
The message body is exactly GMT, so equal returns true.

Example 2: Check a message context value

Input

Message Context:

Key Value
id GMT

Formula 

equal('GMT', context('id'))

Result 

true

Test Expression with equal('GMT',context('id')) on the context key id with value GMT, returning true
The context value of id is GMT, so equal returns true.

Example 3: Check values extracted by another function

Input

Message Body:

GMT UTC

Formula 

equal('UTC', regex('GMT|UTC', body))

Result 

true

Test Expression with equal('UTC',regex('GMT|UTC',body)) on the message body GMT UTC, returning true
regex extracts GMT and UTC; one of them equals UTC, so equal returns true.

Example 4: Check several message context values

Input

Message Context:

Key Value
id GMT
id2 UTC

Formula 

equal('UTC', context(regex('id.*')))

Result 

true

Test Expression with equal('UTC',context(regex('id.*'))) on the context keys id and id2, returning true
context(regex('id.*')) returns the values of both keys, GMT and UTC; one of them equals UTC, so equal returns true.

Example 5: Require every extracted value to match

Input

Message Body:

<Items>
  <Item>Hello World</Item>
  <Item>Hello World</Item>
</Items>

Formula 

equal('Hello World', xPath('Items/Item', body), true)

Result 

true

The unquoted true is matchAllValues: every Item must equal Hello World. If one Item held another text, the formula would return no value, while the same formula without true would still return true.

Test Expression tab: equal('Hello World', xPath('Items/Item', body), true) on two Hello World items returns true
Both Item values equal Hello World, so the check passes even when every value must match.

Next Steps