Data lookups

Use the Data lookup page to create and manage data lookups, which can be used to retrieve data from third-party services.

After you create the data lookup, you can use the Data lookup form control or External data variables on your form to display data from third-party services.

When you configure the Data lookup form control in forms or use the external data variables, your third-party service data will be accessible to form designers and participants (end-users).

With data lookup permissions, you can manage access for other users to use, edit, and delete data lookups. For more information, see Assign data lookup permissions.

Note: Data lookups are not currently supported for embedded forms. For more information, see Find a form URL or snippet.

Jump to:

You can create data lookups for:

Access the Data lookup page

  1. On the top navigation bar, click Automate.

  2. On the left menu, click Data lookup.

Create a connection for your data lookup

You need to add a connection in your Nintex Automation Cloud tenant to configure a data lookup. You can use an existing connection to create a data lookup or if you want to use a new connection you must create the connection before you start configuring a data lookupn. For more information about creating a connection for your data lookup, see Connectors.

Caution:  Deleting a connection will impact all data lookups and forms (with Data lookup form control) using that connection.

Create a data lookup

Note:  As a designer, you should either have Owners or Users permission for the required connection in order to use it to create a data lookup. For information about connection permissions, see Assign User and Owner permissions to connections. By default, users with administrator role will have the same rights as Owners of a connection.

  1. On the Data lookup page, click Add new.
  1. In the Add new section, do the following:
    1. Type a data lookup name and description.

      2. Note: The name must not include any of the following characters: < > " ' ` \ / { } [ ] % $ # * ^ ! @ ~ ? = , ;

    2. Select a connector service and the corresponding operation. For example:
      • Connector: Google Directory
      • Operation: Get groups

      Note:  Once the data lookup is saved, the Connector and Operation fields cannot be edited.

    3. Select a Connection.
    4. Configure the data lookup fields depending on the selected connection. For information about a specific connection, see Connectors.

      Note:  Any of the optional inputs in this section that are unpopulated will be configurable in the Nintex Forms designer Data lookup form control.

    5. Click Save data lookup.

      6. The permissions dialog is displayed.

    6. In the permissions dialog, you can do the following:
      • In the Data lookup owners field, type the name of the user, and select from the list.
      • In the Data lookup users field, type the name of the user, and select from the list.

      For information on user permissions, see Assign data lookup permissions.

    7. Click Save permissions.

      8. The newly added data lookup is listed in the Data lookup page. You can now use a Data lookup form control to display a list of input values from the connected third-party service.

Assign data lookup permissions

Permissions enable you to manage access for other users to use, edit, and delete data lookups.

  Use

Edit

 Delete

Assign
permissions

Connection owners

 ✔ ✔ ✔ ✔

Data lookup editors

 ✔ ✔ ✔ ✘
Data lookup users ✔ ✘ ✘ ✘

Note: By default, users with administrator role will have the same rights as a Connection owner.

Follow these steps to assign data lookup permissions from the Data lookups page:

  1. On the Data lookup page, click for the required data lookup.
  2. From the menu, select Permissions.

    3. The corresponding data lookup permissions window is displayed.

  3. To assign permissions:
    • In the Data lookup editors field, type the name of the user, and select from the list.
    • In the Data lookup users field, type the name of the user, and select from the list.
  1. Click Save Permissions.

Data lookups columns, fields, and selections

Section Field or selection Description
Data lookups Name Name specified when the data lookup is added. Example: Google Directory - Get groups
  Description Description to identify the purpose of the data lookup.
  Connector Connector specified when the data lookup is added. Example: Google Directory.
  Connection Connection used to create the data lookup is added. Example: GoogleDirectoryConnection.
  Date created Date and time when the data lookup is added.
  Created by Name of the data lookup creator.
  Date modified Date and time when the data lookup is edited.
  Modified by Name of the user that last edit the data lookup.
  Options ()

Lists the following options for the selected data lookup:

  • Edit: Allows you to edit the data lookup configuration except for Connector and Operation fields.
  • Permissions: Displays the data lookup permissions dialog where you can edit data lookup permissions.
    • Field Description
    Connector The connector that was selected when the data lookup was created. For example, Google Directory.
    Connection Name of the connection that is given when the connection was created.
    Connection owners List of users with owner access.
    Data lookup editors List of data lookup editors who can use and edit data lookup. Additionally, with connection owner permission, editors can update data lookup permissions.
    Data lookup users

    List of data lookup users who can use an existing data lookup created by another user. Additionally, with connection owner permission, users can update data lookup permissions.

  • Delete: Displays the Deletedata lookup dialog where you can delete a data lookup.
Add new Data lookup name Name of the data lookup to be created.
  Description Description to identify the purpose of the data lookup.
  Connector Lists the available connectors.
  Operation Displays the operation available for the selected Connector. For more information, see Connectors and Xtensions.
  Save data lookup Adds the data lookup in the Data lookups page.
  Cancel Closes the Add new section.

Manage data lookups

Editing data lookups that are used in Data lookup form controls may impact the forms with the associated Data lookup form control.

You may encounter an error when editing a data lookup due to one of the following reasons:

  • It's an old data lookup and the operation for the data lookup may not exist or may have been updated.

  • The output of the Azure Active Directory - Query users action has been updated to include a collection variable named Users to store the properties of the users returned by the query. Existing Azure Active Directory data lookups created before the output of the action was updated will work but you may see an error if you try to edit existing Azure Active Directory data lookup. If you want to leverage the new functionality in your data lookup you must create a new data lookup. If you want to use a new Azure Active Directory data lookup or if you encounter an error when you edit an existing Azure Active Directory data lookup:

    1. Delete the existing Azure Active Directory data lookup.

    2. Create a new Azure Active Directory data lookup.

    3. If you have any Data lookup form controls using the old Azure Active Directory data lookup, reconnect it to the new data lookup.

Before you start 

You can edit a data lookup, if you:

  • are the creator of the data lookup.
  • have Data lookup owners permission.
  • are the owner of the connection that is used in the data lookup. For more information, see Assign data lookup permissions.

    • By default, users with administrator role will have the same rights as an owner of a connection.

By default, if you are the owner of the connection that is used in the data lookup, you can edit data lookup permissions. For more information, see Assign data lookup permissions.

By default, users with administrator role will have the same rights as an owner of a connection.

Note: 

  • Any changes made to a data lookup will impact the forms with the associated Data lookup form control.

  • You cannot edit the Connector and Operation fields. Instead, you can add a new data lookup with the required connector and operation. For field information, see Data lookups columns, fields, and selections.
  1. On the Data lookup page, click to the right of the data lookup that you want to edit.

    2. The Edit data lookup section appears.

  1. Update the configuration as required.
  2. Click Save data lookup.

    3. Once the data lookup is saved, you can configure the Data lookup form control to add a drop-down field to display a list of input values from the connected third-party service.

Before you start 

You can delete, if you:

  • are the creator of the data lookup.
  • have Data lookup owners permissions.
  • are the owner of the connection that is used in the data lookup. For more information, see Assign data lookup permissions.

    • By default, users with administrator role will have the same rights as an owner of a connection.

  1. On the Data lookup page, click for the data lookup that you want to delete.

    2. The Delete data lookup dialog appears.

  1. Click Delete.

    2. Note: Deleting a data lookup will impact the associated forms containing the related Data lookup form control.

  1. Click Save data lookup.

    2. The data lookup is removed from the Data lookups page.

Example: Using a data lookup

In this example we will guide you on how to create a SharePoint Online data lookup to retrieve data from existing SharePoint Online lists.

Let's say you are creating a job application form that lets the applicants:

  • Choose the following field values from a drop-down:
    • Job Location
    • Job Type
    • Job Title

    The field selections will filter down the list of jobs available in another drop-down to select.

  • Add applicant details
  • Submit the form

In this example, we will also set conditions so that when a job applicant selects the Job Location, the Job Type drop-down displays the type that is only available for the selected location and subsequently the Job Title.

Assuming that we have the following:

For this example, we will need to create data lookups to retrieve:

On the Data lookups page, click Add new:

  1. For Data lookup name, type "JobLocations".
  2. For Description, type "Fetch locations".
  3. For Connector, select SharePoint Online.
  4. For Operation, select Query a list.
  5. For Connection, select the SharePoint Online connection created for the data lookup.
  6. Type the SharePoint site URL and click Retrieve lists.
  7. For List name, select the Locations list from the drop-down.
  8. For Columns, select Title and Location ID.
  9. For Item limit, type the maximum number of rows to fetch from the list.
  10. Click Save data lookup.

On the Data lookups page, click Add new:

  1. For Data lookup name, type "JobTypeTitle".
  2. For Description, type "Fetch job type and title".
  3. For Connector, select SharePoint Online.
  4. For Operation, select Query a list.
  5. For Connection, select the SharePoint Online connection created for the data lookupe.
  6. Type the SharePoint site URL and click Retrieve lists.
  7. For List name, select the Jobs list from the drop-down.
  8. For Columns, select Title, Job Location, and Job Type.
  9. For Item limit, type the maximum number of rows to fetch from the list.
  10. Click Save data lookup.

    11. Click to expand

  1. In the dashboard, click Create workflow to open the Workflow designer.
  2. Click the Start event to open the configuration.
  3. Select Form in the Start from field.
  4. Select to make the form available in:
    • URL
    • Nintex Mobile and My Nintex
  5. Click Design Form.

    6. The form designer opens.

In the forms designer:

  1. Drag a Data lookup form control onto the form designer canvas.

    Click to expand

  2. To create data lookup for Job Location: Click on the data lookup form control to open the configuration panel.
    1. For the Title, type "Job Location".
    2. Click Data lookup configuration and do the following:
      1. Select JobLocations for the data lookup.
      2. Click Back to complete configuration.
    3. For Option label, select Title.
    4. For Option value, select Title.
  3. To create a data lookup for Job Type:
    1. Drag and drop a Data lookup form control onto the form designer canvas.
    2. Click on the data lookup form control to open the configuration panel.
    3. For the Title, type Job Type.
    4. Click Data lookup configuration and do the following:
      1. Select JobTypeTitle for the data lookup.
      2. Click Add condition and do the following:
        1. For When, select Job Location.
        2. For Operator, select equals (ignore case).
        3. For Value, click + Variable > Form controls.
        4. Hover over the Job Location variable and then click .
        5. Click Save condition.
      3. Click Back to complete configuration.
    5. For Option label, choose Job Type.
    6. For Option value, choose Job Type.
  4. To create a data lookup for Job Title:
    1. Drag and drop a Data lookup form control onto the form designer canvas.
    2. Click on the Data lookup form control to open the configuration panel.
    3. For the Title, type Job Title.
    4. Click Data lookup configuration and do the following:
      1. Select JobTypeTitle for the data lookup.
      2. Click Add condition and do the following:
        1. For When, select Job Location.
        2. For Operator, select equals (ignore case).
        3. For Value, click + Variable, click Form controls.
        4. Hover over Job Location variable and then click .
        5. Click Save condition.
      3. Click Add condition and do the following:
        1. For When, select Job Type.
        2. For Operator, select equals (ignore case).
        3. For Value, click + Variable, click Form controls.
        4. Hover over Job Type variable and then click .
        5. Click Save condition.
      4. Click Back to complete configuration.
      5. For Option label, select Title.
      6. For Option value, select Title.

  5. Add form controls for the applicant details:
    1. Drag a Text - Short control onto the form designer canvas.
      1. Click on the Text - Short control to open the configuration panel.
      2. Type First name in the Title field.
    2. Drag a Text - Short control onto the form designer canvas.
      1. Click on the Text - Short control to open the configuration panel.
      2. Type Last name in the Title field.
    3. Drag an Email control onto the form designer canvas.
      1. Click on the Email control to open the configuration panel.
      2. Type Email in the Title field.

  6. Click the Preview tab.

    7. A preview version of the form is displayed.

  7. Click Job Location.

    8. List of all the locations is displayed.

  1. Select a location and click on Job Type.

    2. The job types for the selected location is displayed.

  1. Select a job type and click on Job Title.

    2. The job title(s) available for the selected location and type is displayed.

    Click to expand

  1. Click the Designer tab and click Apply changes.

    2. You have now successfully created a form with the Data lookup form controls.

Troubleshooting

If you receive a publish error that states that you do not have permissions for data lookups used in the workflow or that data lookups used in the workflow have been deleted, attempt to resolve the error with these troubleshooting tips:

  • Verify that the relevant data lookups have been created on the tenant where the workflow has been imported. If needed, Create a data lookup in the correct tenant.

    Note: Importing custom Xtensions is not currently supported.

  • Contact your administrator to Assign data lookup permissions.

  • Update the actions and forms where the data lookup has been used and replace it with the new data lookup. If needed, Create a data lookup.