The following operations allow you to work with retrieve entities. Click an operation name to see details on how to use it.
| Operation | Description |
|---|---|
| Returns data of an entity. | |
| retrieveByExpandingNavigationProperties | To control what data from related entities is returned based on the navigation properties (Single or collection). |
| retrieveNavigationPropertyValues | To retrieve individual property values and also to access the values of navigation properties (lookup fields). |
| retrieveSingleProperty | To return (only) the value of a specific property for an entity. |
| retrieveSpecificProperties | To limit the properties returned from the entity. |
For a sample proxy service that illustrates how to work with retrieve entities, see Sample configuration.
Operation details
Following is more information about each of the operations.
Retrieve Entity
To retrieve data of an entity, use msdynamics365.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.
{
"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 control what data from related entities is returned based on the navigation properties (Single or collection), use msdynamics365.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.
{
"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.
<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.
{
"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"
}
{
"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.
<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.
{
"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.
<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.
{
"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.
<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>