Query Microsoft Dynamics CRM 2015 data using the OData endpoint

Applies To: Dynamics CRM 2015

To locate and retrieve data with the OData endpoint, manipulate the URI. All actions require that you begin with the service root URI. In Microsoft Dynamics CRM 2015 and Microsoft Dynamics CRM Online 2015 Update the service root URI is in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc

From the service root URI you identify specific resources using a resource path and further refine your query using system query options.

In This Topic

Accessing Microsoft Dynamics CRM entity data

Limitations on number of records returned

Entity properties

Microsoft Dynamics CRM complex types

• EntityReference

• OptionSetValue

• Money

• BooleanManagedProperty

Related entities

Accessing Microsoft Dynamics CRM entity data

Each Microsoft Dynamics CRM entity is represented in the conceptual schema definition language (CSDL) as a collection using the <EntitySet> element. The name of each collection follows the naming convention of [Entity Schema Name]+ Set. This name is used in the URL to access a collection of entity records. A list of all the collections available is listed when you view the service root URI. To create a query you append your criteria to the resource path.

For example, in your browser you can view the ATOM Account entity records (called ”entries”) using the path in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc/AccountSet

After you view the list of account records, you can see how each of them can be referenced individually using the URL syntax in the following example.

[Your Organization Root URL]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')

Limitations on number of records returned

Each time that you retrieve records, only the top 50 records in your query are returned. If there are more than 50 records, there will be a <link rel="next" href="<url to next set of records>" > node in XML or a JSON __next property at the end of the result set. You can use the URL value in that node or property to continue with the next set of records. The URL contains a $skiptoken parameter that provides information about the paging boundary.

To retrieve additional records you must create a method that detects the existence of this node or property and use the URL provided to retrieve the next set of records. For more information, see: Sample: Retrieve multiple records using the OData endpoint with JavaScript

Entity properties

Each conceptual schema definition language (CSDL) <EntitySet> refers to an <EntityType> element that describes the properties and relationships for an entity. Within the <EntityType> elements the <Property> elements correspond to Microsoft Dynamics CRM entity attributes. Each property is assigned a data type that corresponds to one of the primitive Entity Data Model (EDM) data types or a <ComplexType> defined specifically for Microsoft Dynamics CRM. The following table lists the data types.

Microsoft Dynamics CRM complex types

Certain datatypes used by Microsoft Dynamics CRM cannot use the simple EDM datatypes.

EntityReference

The Microsoft.Crm.Sdk.Data.Services.EntityReference type represents a lookup. It corresponds to EntityReference.The following table lists the properties.

The following example is an ATOM XML EntityReference:

<d:PrimaryContactId m:type="Microsoft.Crm.Sdk.Data.Services.EntityReference">
   <d:Id m:type="Edm.Guid">76713858-5e81-df11-afdb-00155dba380a</d:Id>
   <d:LogicalName>contact</d:LogicalName> 
   <d:Name>Cat Francis (sample)</d:Name> 
</d:PrimaryContactId>

The following example is a JSON EntityReference:

"PrimaryContactId" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.EntityReference" },
    "Id": "78713858-5e81-df11-afdb-00155dba380a",
    "LogicalName": "contact",
    "Name": "Cathan Cook (sample)"}

OptionSetValue

The Microsoft.Crm.Sdk.Data.Services.OptionSetValue type represents a picklist attribute. It corresponds to OptionSetValue. The following table lists properties.

The following example is an ATOM XML OptionSetValue.

<d:PreferredContactMethodCode m:type="Microsoft.Crm.Sdk.Data.Services.OptionSetValue">
   <d:Value m:type="Edm.Int32">1</d:Value>
</d:PreferredContactMethodCode>

The following example is a JSON OptionSetValue:

"PreferredContactMethodCode" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue" },
    "Value": 1}

Money

The Microsoft.Crm.Sdk.Data.Services.Money type represents a Money attribute. It corresponds to Money The following table lists the properties.

The following example is an ATOM XML Money.

<d:CreditLimit m:type="Microsoft.Crm.Sdk.Data.Services.Money">
  <d:Value m:type="Edm.Decimal">500.0000</d:Value> 
</d:CreditLimit>

The following example is a JSON Money:

"CreditLimit" :{
    "__metadata": {"type": "Microsoft.Crm.Sdk.Data.Services.Money" },
    "Value": 500.0000}

BooleanManagedProperty

Certain organization-owned entities have records that can be included in a solution, for example WebResource. Examples of managed properties include IsCustomizable, IsHidden, and CanBeDeleted. It corresponds to BooleanManagedProperty These Boolean properties control the behavior of managed solution components. For more information, see Use managed properties. The following table lists the BooleanManagedProperty.

The following example is an ATOM XML BooleanManagedProperty.

<d:IsCustomizable m:type="Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty">
  <d:Value m:type="Edm.Boolean">true</d:Value>
   <d:CanBeChanged m:type="Edm.Boolean">true</d:CanBeChanged>
   <d:ManagedPropertyLogicalName>iscustomizableanddeletable</d:ManagedPropertyLogicalName>   
</d:IsCustomizable>

The following example is a JSON BooleanManagedProperty:

"IsCustomizable" :{
    "__metadata": { "type": "Microsoft.Crm.Sdk.Data.Services.BooleanManagedProperty" },
    "CanBeChanged": true,
    "ManagedPropertyLogicalName": "iscustomizableanddeletable",
    "Value": true}

Related entities

The conceptual schema definition language (CSDL) <NavigationProperty> element includes all the 1:N, and N:N relationships for the entity. If the relationship represents a self-referencing relationship, there will be two <NavigationProperty> elements for this relationship. The name of the relationship uses the prefix Referenced and Referencing to differentiate the role a specific record plays in the relationship. For more information, see Types of entity relationships.

Use the <NavigationProperty> when you want to create a query to retrieve related records. In the following example, if you want to retrieve a list of opportunities where a specific account is the customer, use the opportunity_customer_accounts entity relationship in the context of a specific account:

/AccountSet(guid'[GUID value]')/opportunity_customer_accounts

If you require only the URL addresses to related records you can use the $links query option shown in the following example.

/AccountSet(guid'[GUID value]')/$links/opportunity_customer_accounts

This will return only the URLs to the data for each related record. The results when viewed in the browser would resemble the following example.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<links xmlns="https://schemas.microsoft.com/ado/2007/08/dataservices">
   <uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'a6713858-5e81-df11-afdb-00155dba380a')</uri>
   <uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'1224342F-D024-4B47-A3F5-FB22D236E655')</uri>
   <uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'7AF675A8-4FBE-42E7-8279-C32605D2B49B')</uri>
   <uri>[Your Organization Root URL]/xrmservices/2011/OrganizationData.svc/OpportunitySet(guid'2DD9BA88-2A37-4F53-8946-68ABBDC73FC1')</uri>
</links>

If you want to include data from the related records when you retrieve a record, use the $expand system query option.

See Also

Use the OData endpoint with web resources
OData system query options using the OData endpoint
Perform basic data operations using the OData endpoint
Perform additional data operations using the OData endpoint
Use the OData endpoint with Ajax and JScript web resources
Sample: Create, retrieve, update, and delete using the OData endpoint with JavaScript and jQuery
Sample: Create, retrieve, update, and delete using the OData endpoint with JavaScript
Sample: OData endpoint jQuery contact editor
Open Data Protocol (OData)
Technical Article: Using Option Set Options with the REST Endpoint - JScript

© 2016 Microsoft. All rights reserved. Copyright