Query Criteria Overview

Article
11/29/2021

Important

This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

Applies To: Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

This topic describes the <QueryCriteria> tag in inbound messages for Application Integration Framework (AIF). The <QueryCriteria> tag occurs in the <Body> tag section of an inbound message. The <QueryCriteria> tag never occurs in outbound messages. For more information, see Message Body.

The purpose of the <QueryCriteria> tag is to provide a flexible way to control which records are returned from an inbound message. The <QueryCriteria> tag is valid only in messages that have Find or FindKeys specified in their <Action> tag. The <QueryCriteria> section is more flexible than the <EntityKeyList> section.

Example <QueryCriteria> Section

The following XML code illustrates an inbound message. The message has an <Action> tag (not shown) which contains the CustomerService service, and the FindKeys service operation. The code shows a <QueryCriteria> section that contains two <CriteriaElement> tags.

The system uses Boolean OR logic to connect all the <CriteriaElement> tags. This means that the record information returned in the outbound message comes from records that satisfy any one of the following <CriteriaElement> conditions.

<QueryCriteria xmlns = "https://schemas.microsoft.com/
  dynamics/2006/02/documents/QueryCriteria">

 <CriteriaElement>
  <DataSourceName>CustTable</DataSourceName>
  <FieldName>Street</FieldName>
  <Operator>Range</Operator>
  <Value1>1</Value1>
  <Value2>5</Value2>
 </CriteriaElement>

 <CriteriaElement>
  <DataSourceName>CustTable</DataSourceName>
  <FieldName>Name</FieldName>
  <Operator>Equal</Operator>
  <Value1>Northwind Traders</Value1>
  <Value2/>
 </CriteriaElement>

</QueryCriteria>

Tags in the <CriteriaElement> Section

The following table lists the tags that occur in the <CriteriaElement> section.

Note

All the tags are required except for <Value2>, which is required only when the Range operator is used.

Tag name	Description
<DataSourceName>	The name of the table that is targeted for the search. The table must be the one that is targeted by the service that is specified in the <Action> tag.
<FieldName>	The name of a field in the table.
<Operator>	One of several recognized operators, such as GreaterOrEqual or Range.
<Value1>	The string representation of any value that is appropriate for the type of field specified.
<Value2>	The second operand, used only when the Range operator is used.

The following sections provide more details about some of the tags in the previous table.

<DataSourceName> Value Aligned with Service

You can determine the correct XML tag name for any service that is specified in the <Action> tag. The determination process is described by the following steps, which use the service CustomerService as a specific example.

Open the Inbound ports form. Click System administration > Setup > Services and Application Integration Framework > Inbound ports.
Click New to create a new port.
On the Service contract customizations FastTab, click Service operations to open the Select service operations form and select the CustCustomerService.create operation.
Click the left arrow button to move selected service operations to the Selected service operations list and close the form.
Select Customize documents and then click Data policies to open the Document data policies form.
Click the View schema button.
In the Schema window that is displayed, the name attribute of the first element is the name that you must use for the first tag under <Body><MessageParts> in your inbound message. The name of the first element in our example is Customer, as is shown in the following schema code.
```
<xs:element name="Customer" type="tns:AxdCustomer" />
```

<Operator> Values

The following table shows all the operators that are recognized as valid <Operator> tag values.

<Operator> value	Analogous X++ operator
Equal	==
NotEqual	!=
Greater	>
GreaterOrEqual	>=
Less	<
LessOrEqual	<=
Range	>= && <=

Note

The Range operator cannot be used to query hidden or locked ranges for a data source or field. For more information about the status property on a query range, see Query Properties.

XSD Validations

The <QueryCriteria> section is validated against an XSD schema. You can retrieve XSDs for common schemas from the following directory where you installed Microsoft Dynamics AX:

Program files\Microsoft Dynamics AX\60\Server\MicrosoftDynamicsAX\bin\Application\Share\Include