Data Out
The returned column value will not be formatted by the lookup function unless it’s one of the following SharePoint types:
For Example: Given a SharePoint Person column, the displayed value of a Person column in SharePoint may appear as “User A”, but the underlying SharePoint text is of the format “1;#UserA”.
If a lookup function is configured to return a Person column’s value, it will convert it into text, using the internal format of “1;#UserA”.
By default, the data returned from this function is for a single column in a list. You may want to return multiple column values: For example, where multiple list items matched a given query. To do this, append ‘true’, without the quotes, as the last parameter of the function. For multiple output values, they are returned inside an Array.An array is of the format [value1,value2].
Inserting an existing control, property or variable
You can use a Named Control, Item Property, Form Variable, Workflow Variable or a pre-defined property as the input value of a lookup function. All types of data to insert are listed in the Formula Builder dialog.
Note: Quotes are not necessary when inserting a control, property or variable.
Runtime behavior
The lookup function is dynamic; if any parameters that are passed into the function change during runtime, the lookup function re-fetches the data and triggers the formula to re-evaluate.
All lookup data is cached for 2 minutes to reduce network traffic.
All lookup functions are evaluated on load of a form, unless they are configured to not recalculate on view mode. This option is per control in the control property window.
Lookup functions are processed asynchronously, meaning they do not halt the form from operating while they fetch the SharePoint data and evaluate. This helps in scenarios where the network between you and the data is slow or physically far apart.
Lookup functions currently do not work in Nintex Mobile or Nintex Live Forms.
Dependent formulae
Formulae that depend on other formulae containing a lookup function will not wait before evaluating. Consider the following scenario of two Form Variables:
Variable A has the formula: Variable B + 1
Variable B has the formula: lookup(“listA”, “Title”, “Task1”, “ID”)
Variable A depends upon Variable B, however an individual formula only waits until all endogenous lookup functions are complete before evaluating. The result is that Variable A will momentarily evaluate to ‘1’, as Variable B has not yet completed. When Variable B does complete, it notifies Variable A to re-calculate, at which time Variable A displays the complete value of: ‘<Variable B’s lookup value> + 1’.
If you have multiple, dependent lookup formulae and require all lookup functions to be complete before displaying a result to the user, utilize a single formula with nested or chained lookup functions.
Security Considerations
The lookup function will perform the lookup of SharePoint data as the current user. Therefore, if the user filling out a Nintex Form does not have the necessary SharePoint access to the list or list item(s), the lookup function will not return any data.
Nested Functions
Lookup functions can be nested inside of other lookup functions. Lookup functions will evaluate inside out, (for example, a lookup function inside another lookup function will evaluate first) to maintain formula correctness.
Circular Reference
As a form designer, be mindful not to construct a formula which contains a circular reference. A circular reference is where a formula is dependent on another formula to complete, but that formula depends upon the original formula completing.
If a circular reference is accidentally configured, the lookup function will stop evaluating after a fixed number of cycles.
Troubleshooting
To help with troubleshooting issues, preview your Nintex Form and press F12 to open the IE developer toolbar. Next, click on the Script tab and ensure that the Console tab on the right is selected. Refresh your preview window by right clicking and selecting Refresh. Logging will appear in the window, and help you to troubleshoot common misconfiguration/data access issues.