This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Working with Retrieve Entities

Owned by Former user (Deleted)
Last updated: Jun 23, 2017 by Former user (Deleted)
6 min read

Overview

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

OperationDescription

retrieveEntity

Returns data of an entity.
retrieveByExpandingNavigationPropertiesTo control what data from related entities is returned based on the navigation properties (Single or collection).
retrieveNavigationPropertyValuesTo retrieve individual property values and also to access the values of navigation properties (lookup fields).
retrieveSinglePropertyTo return (only) the value of a specific property for an entity.
retrieveSpecificPropertiesTo 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.

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 control what data from related entities is returned based on the navigation properties (Single or collection), 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>