Tip of the Iceberg

Category fgoto
It's time for another FGOTO post. Earlier today I had occasion to use an @Function that has been around since version 6 but some of you might not even know exists: @CheckFormulaSyntax. Here's what it does:

• You pass it any string that is supposed to be valid Notes Formula but might not be syntactically correct.
• If it is, in fact, valid Formula, the function simply returns "1".
• Otherwise, it returns a list comprised of the following:
  1. The error message returned by the compiler
  2. Line where the error occurred
  3. The error column (number of character spaces from the first character in the line where the error occurred, beginning with 1)
  4. The error offset (number of character spaces from the first character in the block where the error occurred, beginning with 1)
  5. The length of the text that caused the error
  6. The actual text that caused the error

Where would such a thing be useful? Some of you may actually remember the first time I can recall using this function: it was back when I was playing with XIDED, and added Formula validation to various portions of the IDE. However, it's also useful in at least two "real world" scenarios:

1. Evaluating dynamically generated Formula (for example, constructing Formula based on variable data)
2. Storing Formula within configuration data to allow runtime evaluation of user/admin-maintained code

For example, imagine an application where workflow rules change frequently. One way to minimize the frequency with which the actual codebase must be updated to account for these rule changes is to construct a complex rules engine that accounts for all possible scenarios by allowing a process owner to create documents that define the entire flow. One way to simplify such an engine is to allow concepts such as the actor for each state, the destination state for each action, the description of the action, and so on, to be expressed as Formula that will be evaluated whenever an action is taken. This allows you (or, if you're lucky, a sufficiently savvy "power user") to manage a complex workflow with a comparatively simple rules engine, all without having to touch the underlying code every time the business decides that the application should route documents in drastically different ways.

One challenge this approach presents, however, is the possibility that Formula entered as data will be syntactically incorrect with no warning of its syntactical errors until some "life or death" document fails to route to the correct destination state. You can mitigate this risk, to some extent, simply by adding the following Input Validation to any field intended to store Formula:

syntaxResult := @CheckFormulaSyntax(@ThisValue);

@If(
@Elements(syntaxResult) > 1;

@Failure(
@Implode(("Field " + @ThisName + " contains an invalid formula") : syntaxResult[1] : syntaxResult[6]; ": ")
);

@Success
)

Note the use of @ThisValue and @ThisName to allow the Input Validation to evaluate the value and name, respectively, of the current field, allowing you to use the above Formula without modification in any field.

With this validation in place, if syntactical errors are found (sadly, there is still no reliable way to detect logical errors in advance... but we're working on it), the user populating the Formula field will see something akin to the following: