Dynamics 365 - List entity

Declaration

<AMDYNAMICS365 ACTIVITY="list_entity" SESSION="text" CLIENTID="text (encrypted)" SERVER="text" CLIENTSECRET="text (encrypted)"  CERTIFICATETYPE="text (options)" CERTIFICATE="text" CERTIFICATEPASSWORD="text (options)" CERTIFICATETHUMBPRINT="text" TIMEOUT="number" REDIRECTURI="text" USERNAME="text" PASSWORD="text (encrypted)" AUTODISCOVER="YES/NO" ORGANIZATION="text" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYUSERNAME="text" PROXYPASSWORD="text (options)" QUERYTYPE="text (options)" COLUMNS="text" RESULTDATASET="text" MAXRECORDSPERREQUEST="number" FETCHXML="text" />

Related Topics    

Description

Retrieves a list of entities from a Dynamics 365 server that match a specified condition.

Practical usage

Used to retrieve a list of records of the specified entity type from a Dynamics 365 server.

Parameters

Connection

Property Type Required Default Markup Description
Connection --- --- Host --- Indicates where Dynamics 365 user credentials, connection properties and other preferences should originate from. The available options are:
  • Host (default) - Specifies that user credentials and preferences are configured individually for this activity. This option is normally selected if only a single activity is required to complete an operation.
  • Session - Specifies that user credentials and preferences are obtained from a pre-configured session created in an earlier step with the use of the Dynamics 365 - Create session activity. This option is normally selected if a combination of related activities are required to complete an operation. Consolidating several activities to a single session can make the task more manageable and eliminate redundancy. Moreover, a single task supports simultaneous execution of multiple sessions which can improve efficiency and speed up production.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.

Connect - Session

Property Type Required Default Markup Description
Session Text Yes, if Connection is set to Session Dynamics365Session1 SESSION="Dynamics365Session1" The name of an existing session to attach this activity to. This parameter is active only if the Connection parameter is set to Session.

Connection - Host > Credentials

Property Type Required Default Markup Description
Authentication type Text (options) Yes Client Secret

  • AUTHTYPE="client_secret"

  • AUTHTYPE="certificate"

  • AUTHTYPE="oauth"

 Specifies the authentication to use with the connection. The available options are:

  • Client Secret - Authenticates using a valid Dynamics 365 Client ID and Client Secret value.

  • Certificate - Authenticates using a valid Dynamics 365 Client ID and certificate file/password or certificate thumbprint.

  • OAuth - Authenticates using a valid Client ID, redirect URI, username, and password.
Server Text Yes, if Authentication type is set to Client Secret or Certificate (Empty) SERVER="https://automate.crm.dynamics.com" The URL of the Dynamics 365 server. This parameter is required when the Authentication type parameter is set to Client Secret, or Certificate.
Client ID Text Yes (Empty) CLIENTID="AM5dWi1K9Y1c+vlxOSQG2bjjA==aME" The Client ID associated with the Dynamics 365 account to use for authentication. This parameter is encrypted in Task Builder and required when Authentication type is set to Client Secret, Certificate, or OAuth.
Client Secret Text Yes, if Authentication type is set to Client Secret (Empty) CLIENTSECRET="AM5cXDjUFW9MvyO2/LA==aME" The Client Secret value associated with the Dynamics 365 account to use for authentication. Manually enter a value, or click the icon to select from the list of credentials variables available to you that may correspond with this activity. This parameter is required if the Authentication type parameter is set to Client Secret.
Certificate type Text (options) Yes, if Authentication type is set to Certificate File

  • CERTIFICATETYPE="file"

  • CERTIFICATETYPE="store"

 Specifies the type of Certificate to use for authentication. The available options are:

  • File - The certificate is authenticated using a .pfx file and corresponding password.

  • Store - The certificate is authenticated using a thumbprint value.

This parameter is required when Authentication type is set to Certificate.
Certificate Text Yes, if Authentication type is set to Certificate (Empty) CERTIFICATE="C:\Temp\D365cert.pfx" The (.pfx) certificate file to use for authentication. This parameter is required when Authentication type is set to Certificate.
Certificate password Text No (Empty) CERTIFICATEPASSWORD="AM5gfnsTTJH/gwrenA==aME" The password that corresponds to the file specified in the Certificate parameter. Manually enter a password, or click the icon to select from the list of credentials variables available to you that may correspond with this activity. This parameter is encrypted in the Task Builder.
Certificate thumbprint Text Yes, if Authentication type is set to Certificate and Certificate type is set to Store (Empty) CERTIFICATETHUMBPRINT="128jjdrf2a6d33d548509adf" The thumbprint value for the Certificate parameter. This parameter is required if Authentication type is set to Certificate and Certificate type is set to Store.
Redirect URI Text Yes, if Authentication type is set to OAuth (Empty) REDIRECTURI="rs://my-redirect" The URI to redirect to. This parameter is required if Authentication type is set to OAuth.
Username Text Yes, if Authentication type is set to OAuth (Empty) USERNAME="text" The username to use for authenticating to the Dynamics 365 server. This parameter is required if Authentication type is set to OAuth.
Password Text Yes, if Authentication type is set to OAuth (Empty) PASSWORD="AM5kIJ5IEcPolM4uA==aME" The password to use to authenticate with the Username parameter. Manually enter a password, or click the icon to select from the list of credentials variables available to you that may correspond with this activity. This parameter is required if Authentication type is set to OAuth.
Default/Auto discover Text (options) Yes, if Authentication type is set to OAuth Default AUTODISCOVER="YES" Specifies how to identify an organization in Dynamics 365. Select Default to use the organization's URI or select Auto discover to use the organization's name. This parameter is required if Authentication type is set to OAuth.
Organization URI Text Yes, if Authentication type is set to OAuth and Default is selected (Empty) SERVER="https://automate.crm.dynamics.com" The URI of the organization service. To query organization names and Dynamics 365 server URIs that exist on the system, select Discover. This parameter is required if Authentication type is set to OAuth and Default is selected.
Organization name Text Yes, if Authentication type is set to OAuth and Auto discover is selected (Empty) ORGANIZATION="Fortra" The name of the organization associated with the account. To query organization names and Dynamics 365 server URIs that exist on the system, select Discover. This parameter is required if Authentication type is set to OAuth and Auto discover is selected.

Connection - Host > Advanced

Property Type Required Default Markup Description
Timeout (seconds) Text Yes 120 TIMEOUT="120" The total amount of time (in seconds) to allow for a synchronous connection request to the Dynamics 365 server to complete. If this value is surpassed, a timeout error will occur (default 120).
Proxy type Text (options) Yes Default
  • PROXYTYPE="none"
  • PROXYTYPE="http"
 The type of proxy required for Dynamics 365 connections that pass through a proxy server. The available options are:
  • System default (default) - Points to the default proxy used by the system.
  • None - No proxy authentication required.
  • HTTP - Proxy type is HTTP.
Use authentication --- No --- --- If enabled, specifies proxy authentication is required, enabling authentication-based parameters (disabled by default). It is active only if Proxy type is set to HTTP.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Proxy server Text Yes, if Proxy type is set to HTTP (Empty) PROXYSERVER="proxy.host.com" The hostname (server.domain.com) or IP address (xxx.xxx.xxx.xxx) of the proxy server. This parameter is available only if Proxy type is set to HTTP.
Proxy username Text Yes, if Proxy type is set to HTTP and Use authentication is selected (Empty) PROXYUSERNAME="username" The proxy username to authenticate with. This parameter is available only if Use authentication is enabled.
Proxy port Number Yes, if Proxy type is set to HTTP and Use authentication is selected 808 PROXYPORT="8080" The port number to use to connect to the proxy server. This parameter is available only if Proxy type is set to HTTP. The default value is 808.
Proxy password Text Yes, if Proxy type is set to HTTP and Use authentication is selected (Empty) PROXYPASSWORD="encrypted" The proxy password to authenticate with. Manually enter a password, or click the icon to select from the list of credentials variables available to you that may correspond with this activity. This parameter is available only if Use authentication is enabled.

Entity

Property Type Required Default Markup Description
Entity logical name (e.g., account) Text Yes (Empty) ENTITY="account" The logical name of the entity to get information from. Select the folder icon to open the D365 Browser which aids with browsing through entities that exist on the server.
Query type Text (options) Yes Expression

  • QUERYTYPE="expression"

  • QUERYTYPE="fetchxml"

 The type of query to perform. The available options are:
  • Expression - A query containing data filters and search conditions that define the scope of a database search.
  • FetchXML - The FetchXML language supports query capabilities as query expressions. In addition, it is used as a serialized form of query, and used to save a query as a user-owned saved view.
FetchXML query (unnamed) Text Yes, if Query type is set to FetchXML (Empty) FETCHXML="theFetchXMLQuery" Indicates the FetchXML query to perform. This parameter is only available if the Query type parameter is set to FetchXML.
All columns --- --- --- --- If selected (default), Automate will retrieve information for all of the entity's columns, and then populate a dataset with the results by way of the Create and populate dataset with Entity information parameter. This parameter is active only if the Query type parameter is set to Expression.
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Specified columns Text No (Empty) COLUMNS="name,ownerid" If selected, Automate will only retrieve information for the entity's columns you specify, and then populate a dataset with the results by way of the Create and populate dataset with Entity information parameter. To specify more than one value, use a comma (,) to separate each entry (for example, address1_city,createdby,name,ownerid). Select the icon to open the D365 Browser which can aid in browsing for entities within the server. This parameter is active only if the Query type parameter is set to Expression.
Create and populate dataset with entity information Text Yes (Empty) RESULTDATASET="test45" The name of the dataset in which to populate with entity information. For more information, see Datasets.

Advanced

Property Type Required Default Markup Description
Maximum records per request (1 to 5000) Number Yes 100 MAXRECORDSPERREQUEST="200" The maximum number of entity records to return (default is 100).

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object where every column represents a particular variable, and each row corresponds to a given member of the dataset in question. This activity creates and populates a dataset containing specific fields (rows) in addition to the standard dataset fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

NOTE: Dataset fields for this activity vary based on your Dynamics 365 server.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description

This sample task retrieves a list of records of the contact entity type, and the creates and populates a dataset with the results.

Copy 
<AMDYNAMICS365 AUTHTYPE="client_secret" CLIENTID="00000000-0000-0000-0000-000000000000" SERVER="https://contoso.crm.dynamics.com/" CLIENTSECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" SESSION="Dynamics365Session1" />
<AMDYNAMICS365 ACTIVITY="list_entity" SESSION="Dynamics365Session1" ENTITY="contact" QUERYTYPE="expression" RESULTDATASET="theDataset" MAXRECORDSPERREQUEST="100" />
<AMDYNAMICS365 ACTIVITY="end_session" SESSION="Dynamics365Session1" />