A common requirement among form designers is the ability to surface SharePoint data from another list and optionally process that data. Displaying an entire list item or a list view is possible with the List Item and List View controls respectively, however the aforementioned controls render html as their output which cannot be processed in a Nintex formula. In scenarios where you want to obtain a value from a list column, for display or processing in a formula, the lookup function is a viable approach.
An example would be a purchase order form whose list of purchasable items is maintained in a central list within SharePoint.
Henceforth is an example of how to use the Lookup function.
A Purchase Order utilizing the Lookup function
Given a Products list containing the following purchasable items:
We want to create a Nintex form allowing a user to purchase items from a centralized list. The first step is to create our Nintex Form with a Lookup control that is connected to the Products list.
Let’s preview the form. We see that the control displays each item in the Products list as a selectable item in the dropdown:
Next, users should be able to purchase multiple items; let’s put this control inside a repeating section and add a text box to capture the quantity of each item.
Great – users can purchase different types of products and various quantities of each. Next, we want to show to the user the price of each item they select. To do so, we make use of the Lookup function.
The Lookup function
The lookup function allows a form designer to get data from a column within SharePoint.
As mentioned, we want to display the associated price of a given product depending on what the user selects to purchase. To do so, we drag on a calculated value control and configure it as follows:
In the above screenshot you can see the filled out function. The first parameter tells the function to access a list called “Products”. We need to tell the function which item in the products list we are interested in, as we only want column data for one list item, not all of them.
The second and third parameters are for this purpose, it specifies which column to filter on (ID in this case) and the value in that column that should be matched against. You’ll notice that the third parameter is red and underlined. That is because it is a ‘named control’. I.e. the value comes from the lookup control we put on the form to allow users to select a product. This formula is now dynamic. When the ‘Product’ control’s value changes, this formula is re-run.
The last parameter is ‘Price’. This is the column name which we want to bring back and display.
Let’s hit preview and have a look:
In the above animation you can see the behaviour of the lookup function as it fetches the price upon product selection in the dropdown.
The request to SharePoint happens asynchronously, so the form isn’t refreshed or held up while the data is being fetched.
This is the most basic scenario where we can see how powerful the lookup function is. We can now extend our form to show the total cost of products per item in our form, which is the formula Qty*Price, as well as a running total at the bottom of the repeating section:
What happens if a user is trying to order more than what’s in stock? Preferably we want to show that there is insufficient stock based on what’s in the Products list.
We can provide this ability by using the lookup function inside another calculated value control.
Add another Calculated Value control inside the repeater and open up the formula builder. For this control, we want to show the text ‘Insufficient Stock’ if the quantity in stock of a given product is less than the quantity entered by the user:
We’ve named this control ‘InsufficientStock’. Now, this control will read ‘Insufficent Stock’ when the quantity entered is greater than what’s in stock.
Here is the final result with the rule to change the display format of the quantity control:
Once you familiarize yourself with the lookup function, it opens up new possibilities with Nintex Forms. We value feedback so please post your experience using the Lookup function and what type of scenarios you’re using it in. Don’t forget to tell us about capabilities you’d like to see in future releases!
We’ve earmarked querying the user profile service as a next step for this feature, allowing a form designer to surface user profile data on a form 🙂
The Lookup function is available in version 2.2 for SP 2013, and version 1.4 for SP 2010.
Senior Developer at Nintex.