Query REST Entities

The Query REST Entities activity supports querying list items across different Microsoft Dynamics CRM lists and websites in a specific site collection. This activity supports two modes: FetchXML and OData to query for entities.

General

In the General tab, you can establish a connection to the Microsoft Dynamics CRM server, and specify the type of entity records you want to retrieve.

The following table lists the configurations in the General tab of the Query REST Entities activity:

Field Module Property? Description
Name No Specify the name of the activity in the process definition.
Dynamics CRM REST Connection Yes Specify a shared connection resource.

Click the icon to select a Dynamics CRM REST connection. If no matching Dynamics CRM REST connections are found, click Create Shared Resource in the Select DynamicscrmRestResource Resource Template dialog to create one. See Creating a Dynamics CRM REST Connection for more details.

Dynamics CRM Entity No Specify the type of the entity record(s) you want to retrieve.

Click Fetch Entity to open the Entity Selection Dialog that contains all the available entities. Select an entity from the list and click OK. The selected entity is automatically specified in this field.

Mode No Specify the retrieve mode. Select OData or FetchXML.
  • In OData mode, you can specify Filter and Orderby OData query strings in the Query or Input tab based on which entity records are returned.
  • In FetchXML mode, you can specify the XML query in the Input tab based on which entity records are returned.
    Note: The fields in the Query tab are not displayed if FetchXML is selected.
Select No

Specify the attributes of the entity which you want to be returned.

After selecting the entity, click Select Attributes to open the Attributes Selection Dialog dialog that contains all the available attributes associated with the entity. Select the attributes you want and click OK. The selected attributes are displayed in the Output tab.

Note: If you select OData mode, the chosen attributes will be used as the value for select query string parameter.

Description

In the Description tab, enter a short description for the Query REST Entities activity.

Query

You can specify the criteria in this tab to query the entities or expand on the associated entities.

The following table lists the configurations in the Query tab of the Query REST Entities activity:

Field Module Property? Description
Filter Yes

Specify Searchoperator and attribute names to get the entity records.

Order By Yes

Specify the order in which you want the entity records to be returned.

Entity to Expand No Specify the entity or entities to be associated with the base entity.

Click Select Entity to open the Entity Selection Dialog that contains all the available entities. Select an entity or multiple entities from the list and click OK.

Click Clear Entity to clear the field.

Expand Query No Displays the query based on the output attributes selected for an expanded entity or entities. This is a read-only field.
To have the query displayed in this field, click Build Multiple Entities Schema to open the Attributes Selection Dialog.
  • Select an entity for which you want to configure schema name and output attributes.
  • In Schema Name, select the schema or relationship name for the associated entities.
    Note:
    • If the chosen schema is a single valued navigation property, the Use Ref to expand? check box is enabled, and you can select or clear the check box. If you select the check box, the Choose Output Attributes column is hidden.
    Note: When you select this check box, the odataid is displayed in the Output schema.
  • In Choose Output Attributes, select the output attribute per schema for each associated entity.
    Note: This field is enabled only for collection valued navigation property and for single valued navigation property if the Use Ref to expand? check box is not selected.
Restriction Option No
Select the option from the drop-down based on which you want to restrict the output.
Note: By default, None is selected.
Top Restriction Yes

Specify the number of entity records to be returned in the Output tab.

Note: This field is enabled if you select Top from Restriction Option drop-down.
PageSize Yes

Specify the number of entity records to be displayed in a page.

Note: This field is enabled if you select PageSize from Restriction Option drop-down.
Note: Using a single valued navigation property with Use Ref to expand? along with a collection valued navigation property on a Query REST Entities activity is not supported by Microsoft Dynamics CRM.

Input

The input of this activity varies depending on the selected entity when configuring the General tab.

Note: The values in this tab will be given higher preference over the values that you provide in the Query tab.

The following table lists the possible input elements in the Input tab of the Query REST Entities activity:

Input Item Data Type Description
The following field is displayed in FetchXML mode.
FetchXML String Specify the retrieve criteria in XML format.
Note: The format of the XML string must conform to the FetchXML syntax. See the Microsoft Dynamics CRM documentation for more details about the FetchXML query specification and usage.

The following fields are displayed in OData mode.

FilterQuery String

Specify the attribute names and Searchoperators to get the entity records.

OrderbyQuery String

Specify the order in which you want the entity records to be returned.

NextPageLink String

Specify the URL which the activity uses to get next bunch of data while querying data.

Note: This parameter is displayed in the Input tab when you select PageSize or from the Restriction Option drop-down.
Top String

Specify the number of entity records to be returned.

Note: This parameter is displayed in the Input tab when you select Top from the Restriction Option drop-down.

Output

The elements in the Output tab vary depending on the entity and attributes selected when configuring the General, Query and Input tab. If the mode in General tab is OData and the selected schema to expand is a collection value schema, instead of the @odata.nextLink link now you can see the output attributes that have been selected for the schema.

The following table lists the possible output elements in the Output tab of the Query REST Entities activity:

Output Item Data Type Description
The following fields are displayed along with the entity attributes in FetchXML mode.
nextPageNumber String The next page number.
pagingcookie String The value of paging cookie.
If the Query configuration contains expanding on a single valued navigation property with Use Ref to expand? check box selected, only the following two items are displayed as child elements of an output element. The name of the output element is the attribute name of a single valued navigation property association.
Note: If Use Ref to expand? check box is not selected, instead of the following two output items, all the output attributes that were selected in the Attributes Selection Dialog for that association are displayed as child elements of an output element. The name of the output element is the attribute name of a single valued navigation property association.
entitylogicname String

The attribute names of the associated enity.

Note: This field is displayed when you select Use Ref to expand? check box.
odataid String

The OData ID of the associated entity is displayed.

Note: This field is displayed when you select Use Ref to expand? check box. This parameter will not be displayed if schema name is collection valued.
nextPageLink String

If you select PageSize from the Restriction Option drop-down, the URL is dispalyed in this filed for pagination.

Fault

The error code and error message of the Query REST Entities activity are displayed in the Fault tab. See Error Codes for a more detailed explanation of errors.

The following table lists error schema elements in the Fault tab of the Query REST Entities activity:

Error Schema Element Data Type Description
message String The error message returned by the plug-in.
messageCode String The error code returned by the plug-in.