Office 365 query list

Use the Office 365 query list action to query a list or document library.

Note: This is an external action and may execute on servers running outside your data center region. Before implementing, consider performance and regional concerns where digital boundaries are an issue. For more information, see In-tenant and external actions.

Before you start

What are variables?

Variables are placeholders that store information that changes each time the workflow runs or even during execution of a single workflow instance.

Data types of variables

Each variable has a type that determines what values can be stored in the variable, such as a date, number, file path or a workflow user name. For example, if you want to save the name of an employee in a variable, you have to create a variable of type Text. The workflow can then store a name of the employee, such as "John," in the variable.

Text: Text string.
Boolean: Yes or No value.
Date/Time: Date and time value.
GUID: Globally unique identifier, often used to reference a list item in SharePoint.
Number: Integer number with decimal value.
Integer: Integer number with no decimal value.
Choice: A value that requests a selection from a list of allowed values.
Person or Group: A value that requests a selection from a user lookup.
Hyperlink: A value that requests a hyperlink URL and description.
Dictionary: A container that holds a single logical unit of variables. For more information, see Dictionary variables.
Collection: An index-based array of values, also known as an ordered list of values. For more information, see Collection variables.

Categories of variables

In NintexOffice 365, the different categories of variables that can be used in a workflow are given below:

Workflow Context: Context variables that represent data related to the current workflow instance, such as current item or site URL and workflow name.
Workflow Variables: User-defined variables that you create to store values such as file paths, dates, workflow outputs and other data for use throughout the workflow.

Start Variables: Workflow variables with the initiation option selected. Start Variables are used to get data from users when a workflow manually starts.

For more information on manually starting a workflow, see .

To configure a variable as a start variable, select the Initiation option when creating a variable.

Variable types that can be configured as Start Variables

Text
Boolean
Date/Time
Number
Choice
Person or Group
Hyperlink

How do I add a variable to my workflow?

You can insert an existing Workflow Variable or Context Variable into the configuration fields of workflow actions and you can create user-defined variables for use throughout your workflow.

Create a user-defined variable

You can create user-defined variables from the Action configuration window when you are configuring a workflow action or from the toolbar of the designer page.

During action configuration

In the Action configuration window, click in a field that accepts variables.
Do one of the following depending on the method available;
- On the drop-down list that appears, Click Create New Variable.
- On the Insert Reference pane that appears, expand the Workflow Variables section and click Create New Variable.
Do the following in the Workflow Variables pane to create the variable:
1. For Name, type the variable name you want to use.
2. Select a Type.
- If you want to display the variable on the start form, select the Show on start form check box.
1. Click Create.

From the designer toolbar

On the toolbar of the Designer page, click Variables. The Variables dialog box appears.
Click New and fill in the following:
1. For Name, type the variable name you want to use.
2. For Type, select a variable type corresponding to the type of data you want to store.
- If you want to specify the variable as a start variable, select the Initiation check box.
- Click to specify the Initiation options.
1. Click Save.

For more information, see User-defined variable types and Initiation options.

User-defined variable types and Initiation options

The following table describes the variable types available in the Variables dialog box as well as their initiation options, which are available when you select Yes for Initiation. Initiation options control the display and behavior of the variable on the start form that is displayed when a workflow is started manually.

Variable type	Description	Initiation Available	Initiation options
Text	Any text value. Underlying .NET data type: System.String.	Yes	Multiple Lines: When selected, allows multiple text lines in the default value. Description: Text to display under the text box on the start form. Example: "Enter new name". Default value: Default value for variable.
Boolean	Yes or No value. Underlying .NET data type: System.Boolean.	Yes	Description: Text to display under the check box on the start form. Example: "Enable?" Default value: Default value for variable: Yes (true) or No (false).
Date/Time	Date and time value. Underlying .NET data type: System.DateTime.	Yes	Description: Text to display under the text box on the start form. Example: "Select the date needed by". Default value: Default value for variable: None or Today's date. Allow blank values?: When selected, allows the start form to be submitted without specifying a value for the variable. Display format: Display format for variable: Date and time or Date only.
GUID	Globally unique identifier, often used to reference a list item in SharePoint. Underlying .NET data type: System.Guid.	No	(n/a)
Number	Numeric with a Decimal value. Underlying .NET data type: System.Double.	Yes	Description: Text to display under the text box on the start form. Example: "Specify quantity". Default value: Default value for variable. Can be selected or entered.
Integer	Numeric without a decimal. Underlying .NET data type: System.Int32.	No	(n/a)
Choice	A value that requests a selection from a list of allowed values. The value selected by the workflow initiator is stored in the variable. Underlying .NET data type: System.String.	Yes	Description: Text to display under the drop-down list on the start form. Example: "Select the product" Choices: Choices available in the variable. Enter each choice on a separate line. Default value: Default value for variable. Enter one of the specified choices.
Person or Group	A value that requests a selection from a user lookup. The item selected by the workflow initiator is stored in the variable. Underlying .NET data type: System.String.	Yes	Description: Text to display under the text box on the start form. Example: "Select your manager" Allow selection of: Scope of allowed selection: People Only or People and Groups. Choose from: Source of selection: All Users or SharePoint Group. Use the drop-down list to select a SharePoint group. Allow blank values?: When selected, allows the start form to be submitted without specifying a value for the variable. Allow multiple values?: When selected, allows entry of multiple values.
Hyperlink	A value that requests a hyperlink URL and description. Two text boxes are provided: Type the Web address Type the description The values entered by the workflow initiator are stored in the variable. Underlying .NET data type: System.String.	Yes	Description: Text to display under the "Type the description" text box on the start form. Example: "Enter a display value for the URL" Allow blank value?: When selected, allows the start form to be submitted without specifying a value for the variable.
Dictionary	A container that holds a single logical unit of variables. For more information, see Dictionary variables. Underlying .NET data type: Microsoft.Activities.DynamicValue.	No	(n/a)
Collection	An index-based array of values, also known as an ordered list of values. For more information, see Collection variables.	No	(n/a)

Insert a variable into an action configuration field

You can insert a Workflow Variable, Reference or a Context Variable into the configuration fields of workflow actions.

Each field that accepts variables accepts one or more methods for inserting variables. The method available differs depending on the field.

Available methods are given below:

Click on the field and select an existing variable from the drop-down list for the field.
Click on the field, click Create New Variable, and fill the following fields in the Workflow Variable pane that appears:
1. For Name, type the variable name you want to use.
2. Select the Show on start form check box if you want to display the variable on the start form.
3. Click Create.
Click on the field, select Workflow Variables or Workflow Context, and select a variable from the corresponding drop-down list.

Click Advanced Lookup, select Workflow Variables or Workflow Context from the drop-down list that appears, and then select a variable from the corresponding drop down and click Insert.

Click on the field that accept references and from the Insert Reference pane that appears on the right, double-click on a reference to select. Available sections and lookup values depend on the options available for the workflow action.

Insert reference pane section and field descriptions

Section	Description
Item Properties	Metadata columns for the item the workflow is associated with. Available only for list workflows.
Workflow Context	Context variables that represent data related to the current workflow instance, such as current item or site URL and workflow name. Current item URL: The URL of the item the workflow is associated item. Available only for list workflow actions. Current site URL: The URL of the site the workflow is associated site. Initiator login name: The login name of the person who started the workflow instance. Initiator display name: The display name of the person who started the workflow instance. Initiator email address: The email address of the person who started the workflow instance. Instance ID: The unique identifier of the workflow instance. List ID: The unique identifier of the list the workflow is associated with. Available only for list workflow actions. List Name: The name of the list the workflow is associated with. Available only for list workflow actions. Manager login name: The login name of the manager of the initiator (the person who started the workflow instance). Manager display name: The display name of the manager of the initiator (the person who started the workflow instance). Manager email address: The email address of the manager of the initiator (the person who started the workflow instance). Publish user: The person who published the workflow. Workflow name: The name of the executing workflow.
Workflow Variables	Workflow variables configured for the workflow.

Section

Description

Item Properties

Metadata columns for the item the workflow is associated with. Available only for list workflows.

Workflow Context

Context variables that represent data related to the current workflow instance, such as current item or site URL and workflow name.

Current item URL: The URL of the item the workflow is associated item. Available only for list workflow actions.
Current site URL: The URL of the site the workflow is associated site.
Initiator login name: The login name of the person who started the workflow instance.
Initiator display name: The display name of the person who started the workflow instance.
Initiator email address: The email address of the person who started the workflow instance.
Instance ID: The unique identifier of the workflow instance.
List ID: The unique identifier of the list the workflow is associated with. Available only for list workflow actions.
List Name: The name of the list the workflow is associated with. Available only for list workflow actions.
Manager login name: The login name of the manager of the initiator (the person who started the workflow instance).
Manager display name: The display name of the manager of the initiator (the person who started the workflow instance).
Manager email address: The email address of the manager of the initiator (the person who started the workflow instance).
Publish user: The person who published the workflow.
Workflow name: The name of the executing workflow.

Workflow Variables

Workflow variables configured for the workflow.

Configure a variable as a start variable

You can configure variables to collect data when a workflow is manually started. These variables will be shown on a start form used to initiate the workflow and allows users to specify a value for the workflow variable before the workflow starts, basically passing values into the workflow before it starts.

Variables displayed on a start form are also known as the "start data" of the workflow and represent data that must be collected when the workflow is started.

Note: If the workflow starts automatically, then default values are used for start data.

To learn how to manually start a workflow, see Start a workflow manually.

Configure a variable to show on a workflow start form:

Open the required workflow. The workflow designer opens.
On the toolbar, click Variables. The Variables window opens.
To edit an existing variable, click the required variable. The row becomes editable.

or

To create a variable, click New on the Variables window toolbar, enter a Name, and select the Type for the variable.

Select the Initiation check box for the required variable.

If you want to configure initiation options, click to open the Initiation options dialog box, make the changes and click OK.

User-defined variable types and Initiation options

Click Save to commit changes.

Add and configure the Office 365 query list action

Click the Libraries and Lists action group in the action toolbox.

or

Type the action name or function in the Search field at the top of the action toolbox.
Drag the Office 365 query list action to the designer canvas.
Open the Action Configuration window. For steps on how to open the Action configuration window, see Action configuration window.
Specify the Destination site URL of the site the list or document library is in.
Select a Connection to connect to the site.
Specify the List name to query.
Build the Query.
Click Save.

For more information about the fields, buttons and settings, see Office 365 query list action fields, buttons and settings.

Office 365 query list action fields, buttons and settings

Section

Field

Description

(n/a)

Destination site URL

URL of the site that the list or document library to query is in.

(n/a)

Connection

(Displayed for new and updated actions.) The connection to connect to the site.

Connection type required: SharePoint Online: List & library. For more information about Connection types, see Connection types and Connector actions.
Permissions required: Query the specified list or document library.

(n/a)

Username / Password

(Displayed for legacy actions not yet updated.) Unmanaged credentials.

Permissions required: Query the specified list or document library.

Note: As a best practice, manage credentials by updating actions to use connections.

(n/a)

List name

Name of the list or document library to query.

(n/a)

Query

Option to build the query. Includes filters and options for subfolders and sorting.

Select one of the following options:

Query builder: Choose fields to build a query to filter items. View the CAML editor for the query at any time by selecting the CAML Editor mode.
CAML editor: Create a more advanced query using XML encoding.

What is CAML?

CAML (Collaborative Markup Language) is an XML based language for querying and updating objects such as Lists and Libraries in SharePoint. CAML retrieves items from a SharePoint object based on the conditions specified.

Query

Fields

(Available only when Query builder is selected.)

Fields (properties) in the list or document library to be queried.

To add a field, click Add field.
To delete a field, click Delete ().

Note: Content type fields are not supported.

Include subfolders

(Available only when Query builder is selected.)

Queries items within subfolders when check box is selected.

Maximum number of results

(Available only when Query builder is selected.)

The maximum number of results to return for the query. If left blank all results will be returned.

Filters

(Available only when Query builder is selected.)

Limits the items used in the query. Select one of the following filter options.

Select all list items: Selects all items in the list or library.

Select items only when the following is true:

Show the items when column : Specify a column, select an operator, and specify a value for the condition.

Condition fields

Field	Description
When (unlabeled)	Column (field) from the selected list or document library.
Operator (unlabeled)	The operator to do the comparison between When and the Value.
Value(unlabeled)	The value to look for in the column (field).

Add filter rule: Add a filter.
Delete (): Delete a filter. Displayed for second and subsequent filters.
And / Or: Used to evaluate two sequential conditions.

Sort

Add one or more sort rules to specify the order in which to return the items.

First sort by column / Then sort by the column: Specify a column.
- Show items in ascending order (A, B, C or 1, 2, 3): Select to sort in ascending order.
- Show items in descending order (C, B, A or 3, 2, 1): Select to sort in descending order.
Add sort rule: Add a sort rule.
Delete (): Delete a sort rule. Displayed for second and subsequent rules.

Result count

Variable to store the total number of results returned.

First column

Collection or dictionary variable to store the values of the first column of the query results.

Fields XML

Collection or dictionary variable to store the item metadata as XML.

For more information about how to use Lookups in configuration fields, see Lookups in action configuration fields.