Working with Retrieve Entities

The following operations allow you to work with retrieve entities. Click an operation name to see details on how to use it:

Operation	Description
	To control what data from related entities is returned based on the navigation properties (Single or collection).
	To retrieve individual property values and also to access the values of navigation properties (lookup fields).
	To return (only) the value of a specific property for an entity.
	To limit the properties returned from the entity.

For a sample proxy service that illustrates how to work with retrieve entities, see Sample configuration.

Retrieve Entity

To retrieve data of an entity, use msdynamics365.retrieveEntity.

retrieveEntity

<msdynamics365.retrieveEntity>
    <entityType>{$ctx:entityType}</entityType>
    <primaryKeyValueOrAlternateKey>{$ctx:primaryKeyValueOrAlternateKey}</primaryKeyValueOrAlternateKey>
</msdynamics365.retrieveEntity>

Properties

<entityType>: Mandatory. The type of an entity (i.e accounts, opportunities, contacts and etc).
<primaryKeyValueOrAlternateKey>: Mandatory. The primary key value of an entity or use the alternate key to retrieve the entity instead of the unique identifier ( primary key value).

Sample request

Following is a sample R EST/JSON request that can be handled by the retrieveEntity operation.

Sample Request for Retrieve Entity

{
       
       "apiUrl":"https://wso2.crm5.dynamics.com",
       "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
       "refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
       "clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
       "clientId":"c12ec5be-8356-ed0915a",
       "resource":"https://wso21234.crm5.dynamics.com/",
       "registryPath":"",
       "intervalTime":"",
       "entityType":"accounts",
       "primaryKeyValueOrAlternateKey":"00000000-0000-0000-0000-000000000001"
}

For more information about retrieveEntity, see https://msdn.microsoft.com/en-us/library/mt607871.aspx#bkmk_basicRetrieve.

Retrieve Related Entities by Expanding Navigation Properties

To retrieve related entities for an entity by expanding navigation properties, use msdynamics365. retrieveByExpandingNavigationProperties.

retrieveByExpandingNavigationProperties

<msdynamics365.retrieveByExpandingNavigationProperties>
    <entityType>{$ctx:entityType}</entityType>
    <primaryKeyValue>{$ctx:primaryKeyValue}</primaryKeyValue>
    <queryParam>{$ctx:queryParam}</queryParam>
</msdynamics365.retrieveByExpandingNavigationProperties>

Properties

<entityType>: Mandatory. The type of an entity (i.e., accounts, opportunities, contacts etc).
<primaryKeyValue>: Mandatory. The primary key value of an entity.
<queryParam>: The query option to control what data is returned from related entities. You can use single-valued navigation properties or collection-valued navigation properties here.

Sample request

Following is a sample R EST/JSON request that can be handled by the retrieveByExpandingNavigationProperties operation.

Sample Request for Retrieve By Expanding Navigation Properties

{
           	"apiUrl":"https://wso2.crm5.dynamics.com",
           	"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
           	"refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
           	"clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
           	"clientId":"c12ec5be-8356-ed0915a",
           	"resource":"https://wso21234.crm5.dynamics.com/",
           	"registryPath":"",
           	"intervalTime":"",
           	"entityType":"accounts",
           	"primaryKeyValue":"00000000-0000-0000-0000-000000000001",
    		"queryParam":"$select=name&$expand=primarycontactid($select=contactid,fullname)"
}

For more information on Retrieve Entities by Expanding Navigation Properties, see https://msdn.microsoft.com/en-us/library/mt607871.aspx#bkmk_expandRelated.

Retrieve navigation property values

To retrieve individual property values and also to access the values of navigation properties (lookup fields), use msdynamics365.retrieveNavigationPropertyValues.

retrieveNavigationPropertyValues

<msdynamics365.retrieveNavigationPropertyValues>
    <entityType>{$ctx:entityType}</entityType>
    <primaryKeyValue>{$ctx:primaryKeyValue}</primaryKeyValue>
    <navigationPropertyValue>{$ctx:navigationPropertyValue}</navigationPropertyValue>
    <referenceOrCountOfEntity>{$ctx:referenceOrCountOfEntity}</referenceOrCountOfEntity>
    <queryParam>{$ctx:queryParam}</queryParam>
</msdynamics365.retrieveNavigationPropertyValues>

Properties

<entityType>: Mandatory. The type of an entity (i.e., accounts, opportunities, contacts etc).
<primaryKeyValue>: Mandatory. The primary key value of an entity.
<navigationPropertyValue>: Mandatory. This can be either a single-valued navigation property name or a collection-valued navigation property name.
<referenceOrCountOfEntity>: Mandatory. Use this property if you use the collection-valued navigation property to return only references to the related entities or just a count of the related entities. Possible values are $ref or $count.
<queryParam>: Mandatory. Use this property if you use the single-valued navigation property to retrieve data of an entity.

Sample request

Following is a sample REST/JSON request that can be handled by the retrieveNavigationPropertyValues (collection-valued and single-valued navigation properties) operation.

Sample Request for Retrieve Collecton Valued Properties

{
           	"apiUrl":"https://wso2.crm5.dynamics.com",
           	"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
           	"refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
           	"clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
           	"clientId":"c12ec5be-8356-ed0915a",
           	"resource":"https://wso21234.crm5.dynamics.com/",
           	"registryPath":"",
           	"intervalTime":"",
           	"entityType":"accounts",
           	"primaryKeyValue":"00000000-0000-0000-0000-000000000001",
    		"navigationPropertyValue":"Account_Tasks",
			"referenceOrCountOfEntity":"$ref"
 }

Sample Request for Retrieve Single Valued Properties

{
            "apiUrl":"https://wso2.crm5.dynamics.com",
           	"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
           	"refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
           	"clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
           	"clientId":"c12ec5be-8356-ed0915a",
           	"resource":"https://wso21234.crm5.dynamics.com/",
           	"registryPath":"",
           	"intervalTime":"",
           	"entityType":"accounts",
           	"primaryKeyValue":"00000000-0000-0000-0000-000000000001",
    		"navigationPropertyValue":"primarycontactid",
			"queryParam":"fullname"
 }

For more information on Retrieve Navigation Property Values, see https://msdn.microsoft.com/en-us/library/mt607871.aspx#bkmk_retrieveNavigationPropertyValues.

Retrieve single property value

To retrieve the value of the specific property of an entity, use msdynamics365.retrieveSingleProperty.

retrieveSingleProperty

<msdynamics365.retrieveSingleProperty>
    <entityType>{$ctx:entityType}</entityType>
    <singlePropertyName>{$ctx:singlePropertyName}</singlePropertyName>
    <primaryKeyValue>{$ctx:primaryKeyValue}</primaryKeyValue>
</msdynamics365.retrieveSingleProperty>

Properties

<entityType>: Mandatory. The type of an entity (i.e., accounts, opportunities, contacts etc).
<singlePropertyName>: Mandatory. The name of the property that you want to retrieve.
<primaryKeyValue>: Mandatory. The primary key value of an entity.

Sample request

Following is a sample REST/JSON request that can be handled by the retrieveSingleProperty operation.

Sample Request for Retrieve Single Property Value

{
           	"apiUrl":"https://wso2.crm5.dynamics.com",
           	"accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
           	"refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
           	"clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
           	"clientId":"c12ec5be-8356-ed0915a",
           	"resource":"https://wso21234.crm5.dynamics.com/",
           	"registryPath":"",
           	"intervalTime":"",
           	"entityType":"accounts",
           	"primaryKeyValue":"00000000-0000-0000-0000-000000000001",
    		"singlePropertyName":"name"
}

For more information on Retrieve Single Property Value, see https://msdn.microsoft.com/en-us/library/mt607871.aspx#bkmk_retrieveSingleValue.

Retrieve Specific Properties of an Entity

To retrieve specific properties of an entity, use msdynamics365.retrieveSpecificProperties.

retrieveSpecificProperties

<msdynamics365.retrieveSpecificProperties>
    <entityType>{$ctx:entityType}</entityType>
    <primaryKeyValue>{$ctx:primaryKeyValue}</primaryKeyValue>
    <queryParam>{$ctx:queryParam}</queryParam>
</msdynamics365.retrieveSpecificProperties>

Properties

<entityType>: Mandatory. The type of an entity (i.e., accounts, opportunities, contacts etc).
<primaryKeyValue>: Mandatory. The primary key value of an entity.
<queryParam>: Mandatory. Specify the names of the properties that you want to return.

Sample request

Following is a sample REST/JSON request that can be handled by the retrieveSpecificProperties operation.

Sample Request for Retrieve Specific Properties of an Entity

{
       
           "apiUrl":"https://wso2.crm5.dynamics.com",
           "accessToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjlGWERwYmZNRlQyU3",
           "refreshToken":"AQABAAAAAABnfiG-mA6NTae7CdWW7Qfd0aAk9Jh2jERSJt61ivkdC_8VpI4B75AWvtviJErRhnzKIDvt",
           "clientSecret":"iDJ7gQ81N+JAW9Ql2/ikMzc9og",
           "clientId":"c12ec5be-8356-ed0915a",
           "resource":"https://wso21234.crm5.dynamics.com/",
           "registryPath":"",
           "intervalTime":"",
           "entityType":"accounts",
           "primaryKeyValue":"00000000-0000-0000-0000-000000000001",
    	   "queryParam":"name,revenue"
}

For more information on Retrieve Specific Properties, see https://msdn.microsoft.com/en-us/library/mt607871.aspx#bkmk_requestProperties.

Sample configuration

Following is a sample proxy service that illustrates how to connect to Microsoft Dynamics 365 with the init operation and use the retrieveEntity operation. To view the sample request for this proxy, see Sample Request for the retrieveEntity operation. You can use this sample as a template for the other operations in this category.

Sample Proxy

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="msdynamics_retrieveEntity"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
    <target>
        <inSequence>
           	<property expression="json-eval($.apiUrl)" name="apiUrl"/>
			<property expression="json-eval($.accessToken)" name="accessToken"/>
			<property expression="json-eval($.entityType)" name="entityType"/>
			<property expression="json-eval($.primaryKeyValueOrAlternateKey)" name="primaryKeyValueOrAlternateKey"/>
			<property expression="json-eval($.apiVersion)" name="apiVersion"/>
			<property expression="json-eval($.refreshToken)" name="refreshToken"/>
			<property expression="json-eval($.clientSecret)" name="clientSecret"/>
			<property expression="json-eval($.clientId)" name="clientId"/>
			<property expression="json-eval($.resource)" name="resource"/>
			<property expression="json-eval($.registryPath)" name="registryPath"/>
			<property expression="json-eval($.intervalTime)" name="intervalTime"/>
           	<msdynamics365.init>
    			<apiUrl>{$ctx:apiUrl}</apiUrl>
    			<accessToken>{$ctx:accessToken}</accessToken>
    			<apiVersion>{$ctx:apiVersion}</apiVersion>
    			<refreshToken>{$ctx:refreshToken}</refreshToken>
    			<clientSecret>{$ctx:clientSecret}</clientSecret>
    			<clientId>{$ctx:clientId}</clientId>
    			<resource>{$ctx:resource}</resource>
    			<registryPath>{$ctx:registryPath}</registryPath>
    			<intervalTime>{$ctx:intervalTime}</intervalTime>
			</msdynamics365.init>
           	<msdynamics365.retrieveEntity>
    			<entityType>{$ctx:entityType}</entityType>
    			<primaryKeyValueOrAlternateKey>{$ctx:primaryKeyValueOrAlternateKey}</primaryKeyValueOrAlternateKey>
			</msdynamics365.retrieveEntity>
            <respond/>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
    </target>
    <description/>
</proxy>