Dynamics CRM - List entity

 

Declaration

<AMDYNAMICSCRM ENTITY="text" RESULTDATASET="text" PROTOCOL="text (options)" SERVER="text" USERNAME="text" PASSWORD="encrypted text" DOMAIN="text" ORGANIZATION="text" AUTODISCOVER="yes/no" DISCOVERYURI="text" ORGANIZATIONURI="text" HOMEREALMURI="text" AUTHTYPE="text (options)" TIMEOUT="number" PROXYTYPE="text (options)" PROXYSERVER="text" PROXYPORT="number" PROXYUSERNAME="text" PROXYPASSWORD="encrypted text" />

Related Topics   

Description

The List entity activity returns a list of entities from a Dynamics CRM server that match a specified condition.

NOTE: To function properly, this activity requires a Microsoft Dynamics CRM System Administrator or System Customizer security role or equivalent permissions.

Practical Usage

Use the List entity activity to retrieve a list of records of the specified entity type from a Dynamics CRM server and display them as shown in the examples below.

Parameters

connection

Property

Type

Required

Default

Markup

Description

Connection

        

Indicates where Dynamics CRM user credentials, connection properties and other preferences should originate from. This is a design mode parameter used only during task construction and configuration, thus, comprises no markup. 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 earlierstep with the use of the Dynamics CRM - 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.

Session

Text

Yes if connection is session-based

DynamicsCrmSession1

SESSION="DynamicsCrmSession1"

The name of an existing session to attach this activity to. This parameter is active only if the Connection parameter is set to Session. The default session name is 'DynamicsCrmSession1'.

Server (protocol)

Text (options)

Yes

HTTPS

  1. PROTOCOL="HTTPS"

  2. PROTOCOL="HTTP"

Specifies the protocol used to connect to the Dynamics CRM server. The URL can be HTTP or HTTPS and the port is optional if it is HTTP over port 80 or HTTPS over port 443. The available options are:

  • HTTPS (default) - Hypertext Transfer Protocol Secure, which adds security capabilities of SSL/TLS to standard HTTP communications.

  • HTTP - Hypertext Transfer Protocol

Server

Text

Yes

(Empty)

  1. SERVER="crm.dynamics.com"

  2. SERVER="209.223.157.106"

The URL or IP address of the Dynamics CRM server to establish a connection with. If entering a URL, the port is optional if it is http over port 80 or https over port 443. (i.e. crm-server:port). The server URL is typically in the format of:

http://crm-server:port/organization-name

Or for Microsoft Dynamics CRM Online:

https://organization-name.crm.dynamics.com

Username or Windows Live ID

Text

Yes

(Empty)

  1. USERNAME="bware"

  2. USERNAME="bwareh@live-int.com

The username of the service account that is used to connect using AD, SPLA, or Passport authentication types. The format for this is specific to the authentication type: domain\username for AD and SPLA authentication types and a Windows Live ID for Passport authentication.

Password

Text

Yes

(Empty)

PASSWORD="encrypted"

The password of the service account that is used to connect using AD, SPLA, or Passport authentication.

Domain name (optional)

Text

No

(Empty)

DOMAIN="netauto.com"

The name of the domain that will verify user credentials (optional).

Organization name

Text

Yes

(Empty)

ORGANIZATION="Network Automation"

 The name of the organization associated with the account. To query organization names and Dynamics CRM server URIs that exist on the system, click the Discover button.

Microsoft Office 365

Yes/No

No

No

OFFICE365="YES"

If selected, connection will be established by way of Office365 account. Set this option to YES if using  Microsoft Dynamics CRM Online through Microsoft Outlook. Disabled by default.

Auto discover

Yes/No

No

No

AUTODISCOVER="YES"

Auto-discovery helps you detect where the Dynamics CRM components are installed, whether locally or remotely. If selected, Automate will use CrmDiscoveryService to obtain a name and URL endpoint for a target organization (disabled by default). The CrmDiscoveryService Web service is accessed through a global URL of an on-premise Microsoft Dynamics CRM server. Each Microsoft Dynamics CRM server hosts the CrmDiscoveryService Web service, which is located here: http://<server:port>/MSCRMServices/2007/AD/CrmDiscoveryService.asm.

NOTE: Setting this parameter to YES inactivates various settings.

Discovery URI

Text

No

(Empty)

DISCOVERYURI="crm.disco.com"

The Discovery URL used by your site if you are connecting to a Microsoft Dynamics CRM Online organization. To connect to Microsoft Dynamics CRM Online, the discovery service is first hit to retrieve a passport authentication ticket. This ticket indicates that a Live ID user is, in fact, authenticated to use the Microsoft Dynamics CRM Online instance.

Organization URI

Text

No

(Empty)

ORGANIZATIONURI="crm.org.com"

The URL of the organization service. If the Auto discover parameter is selected, this parameter becomes inactive.

Home realm URI

Text

No

(Empty)

HOMEREALMURI="crm.home.com"

The URL of the home realm. This is the address of the identity provider. If the Auto discover parameter is selected, this parameter becomes inactive.

Authentication type

Text (options)

No

LiveID

  1. AUTHTYPE="ActiveDirectory"

  2. AUTHTYPE="Federation"

  3. AUTHTYPE="LiveId"

  4. AUTHTYPE="OnlineFederation"

The type of authentication used to connect to the Dynamics CRM server. If the Auto discover parameter is selected, this parameter becomes inactive. The available options are:

  • None - Authenticates with Dynamics CRM using the current Windows credentials of the application. This is typically used in development environments and only works with on-premises deployments in the same Active Directory domain (or trusted domain) as the Microsoft Dynamics CRM server.

  • Active Directory - Authenticates using Active Directory credentials of a specific service account. This is mainly used for on-premises deployments.

  • Federation - Establishes an authentication gateway using a combination of IAG and Active Directory Federation Services (ADFS) in order to provide external users with access to the sensitive information that is stored in the CRM system without having to create Active Directory trusts.

  • Live ID - Authenticates using the Windows Live ID authentication mechanism (previously known as Passport authentication). Mainly used for Microsoft Dynamics CRM Online deployments.

  • Online Federation - Contains the available identity providers for the Microsoft Dynamics CRM Online service.

Timeout (seconds)

Number

No

120

TIMEOUT="120"

The total amount of time (in seconds) to allow for a synchronous connection request to the CRM server to complete. If this value is surpassed, a timeout error will occur. The default value is 120 seconds (3 minutes).

Proxy type

Text (options)

No

System default

  1. PROXYTYPE="none"

  2. PROXYTYPE="http"

The type of proxy in which to connect to. The available options are:

  • System default - Connect to the default proxy server currently recognized by the system.

  • None - No proxy connection required.

  • HTTP - Connect to an HTTP proxy.

Use authentication

        

If enabled, specifies that the proxy requires authentication before granting access to resources. If disabled (default), specifies that no authentication is required. This is a visual mode parameter only used during design time, therefore, it contains no properties or markup. This parameter is active only if the Proxy Type parameter is set to HTTP.

Proxy server

Text

Yes if proxy type is HTTP

(Empty)

PROXYSERVER="proxy.server.com"

The hostname or IP address of the proxy server to connect to. This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy port

Number

No

808

PROXYPORT="1028"

The port that should be used to connect to the proxy server. The default value is 808. This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy username

Text

No

(Empty)

PROXYUSER="username"

The username used to authenticate connection with the proxy server (if required). This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy password

Text

No

(Empty)

PROXYPWD="encrypted"

The password used to authenticate connection with the proxy server (if required).  This parameter is active only if the Proxy type parameter is set to HTTP.

Entity

Property

Type

Required

Default

Markup

Description

Entity logical name (i.e. account)

Text

Yes

(Empty)

ENTITY="myaccount"

The logical name of the entity to get information from. Click the folder icon to open the CRM Browser which can aid in browsing for entities that exist within the server.

Query type

    

 

  

The type of query to perform. This is a design-time parameter only used during task construction, therefore, does not contain parameters or markups. The available options are:

  • Expression - A query containing data filters and search conditions that define the scope of a database search.

  • FetchXML - A proprietary query language that is used in Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online. The FetchXML language supports similar query capabilities as query expressions. In addition it is used as a serialized form of query, used to save a query as a user-owned saved view.

Query

Text

Yes if query type set to FetchXML

(Empty)

QUERY="theFetchXMLQuery"

Indicates the FetchXML query to perform. This parameter is active only if the Query type parameter is set to FetchXML.

All columns

        

If enabled, all columns of the dataset will be populated with retrieved data (enabled by default). This is a design-time parameter only used during task construction, therefore, does not contain parameters or markups. This parameter is active only if the Query type parameter is set to Expression.

Specified columns

Text

No

 (Empty)

COLUMNS="name,ownerid"

If enabled, only specified columns of the dataset will be populated. To specify more than one value, use a comma (,) to delimit each entry (i.e. address1_city,createdby,name,ownerid). Click the folder icon to open the CRM 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.

 

Description

Error Causes

On Error

Examples

NOTE:
  • The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
  • Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.

 

Sample 1: A sample session-based task that displays the List entity activity. It uses a FetchXML statement that retrieves all accounts.

<AMDYNAMICSCRM ACTIVITY="create_session" PROTOCOL="http" SERVER="209.223.157.106" USERNAME="administrator" PASSWORD="AM2gvUWJwwypS+Z9QcnFzL2L9z1QydMMsQpaME" DOMAIN="netautoinc" ORGANIZATION="netautodyn" AUTODISCOVER="no" DISCOVERYURI="http://209.223.157.106/XRMServices/2011/Discovery.svc" ORGANIZATIONURI="http://dynamicscrm2011/netautodyn/XRMServices/2011/Organization.svc" AUTHTYPE="ActiveDirectory" SESSION="DynamicsCrmSession1" />

<AMDYNAMICSCRM SESSION="DynamicsCrmSession1" ENTITY="account" RESULTDATASET="test">&lt;fetch mapping='logical'&gt;

   &lt;entity name='account'&gt;

      &lt;attribute name='accountid'/&gt;

      &lt;attribute name='name'/&gt;

&lt;/entitygt;

&lt;/fetch&gt;</AMDYNAMICSCRM>

<AMDYNAMICSCRM ACTIVITY="end_session" SESSION="DynamicsCrmSession1" />

 

Sample 2: A sample session-based task that displays the List entity activity. It uses a FetchXML statement that retrieves all accounts where the last name of the owning user is not equal to Cannon.

<AMDYNAMICSCRM ACTIVITY="create_session" PROTOCOL="http" SERVER="209.223.157.106" USERNAME="administrator" PASSWORD="AM2gvUWJwwypS+Z9QcnFzL2L9z1QydMMsQpaME" DOMAIN="netautoinc" ORGANIZATION="netautodyn" AUTODISCOVER="no" DISCOVERYURI="http://209.223.157.106/XRMServices/2011/Discovery.svc" ORGANIZATIONURI="http://dynamicscrm2011/netautodyn/XRMServices/2011/Organization.svc" AUTHTYPE="ActiveDirectory" SESSION="DynamicsCrmSession1" />

<AMDYNAMICSCRM SESSION="DynamicsCrmSession1" ENTITY="account" RESULTDATASET="test">&lt;fetch mapping='logical'&gt;

   &lt;entity name='account'&gt;

      &lt;attribute name='accountid'/&gt;

      &lt;attribute name='name'/&gt;

      &lt;link-entity name='systemuser' to='owninguser'&gt;

         &lt;filter type='and'&gt;

            &lt;condition attribute='lastname' operator='ne' value='Cannon' /&gt;

          &lt;/filter&gt;

      &lt;/link-entity&gt;

   &lt;/entity&gt;

&lt;/fetch&gt;  </AMDYNAMICSCRM>

<AMDYNAMICSCRM ACTIVITY="end_session" SESSION="DynamicsCrmSession1" />