A co-developer recently had a list of document unique ID's. He wanted to look up a value from each of the documents. His first thought was to use @GetDocField, as in @GetDocField(unidList; "Form"). ("Form" wasn't the field he was looking up, but I'll use it here as an example). @GetDocField only works on a single value, so it was only looking up the field from the first UNID in the list.

He had never used @Transform before, but this is a perfect use for that function. It can turn any function that does "single value" processing into a function that does "multi value" processing. @Transform has three parameters. The first is the list of values. The second is a string that will end up being the name of the temporary variable. The third is the function to perform, using the variable name second parameter. So, his function was rewritten:

@Transform(unidList; "x"; @GetDocField(x; "Form"))

The function loops through all the elements in the list (first parameter). For each element in the list, @GetDocField is performed. Notice how the string "x" is used. That's the second parameter, so that's the name of the "variable" inside the formula (third parameter). The result of the function is a list of "transformed" values - each element in the list (each UNID) was transformed into something else (the result of the @GetDocField).

Since the formula is processed for each element in the source list, the formula is processing with a single value each time. So that's how you turn the single-value limitation of @GetDocField into a formula that can now process multiple values.

Note that I'm not doing any error checking in the formula. A more "robust" version of the formula might be:

@Transform(unidList; "x"; @If(@IsError(@GetDocField(x; "Form")); "error"; @GetDocField(x; "Form")))

But the more complicated your formula gets, the more difficult it is to follow and support. So that's why I started with the simple example - it's easier to explain.

You could also use @Do in your formula to perform multiple statements. The key is that the formula results in a value, and that value ends up replacing the original value in the list.

Any function that operates only on a single value can similarly be updated to a function that operates on multiple values using the same technique.