Use Web API functions

Article
11/28/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Functions and actions represent re-usable operations you can perform using the Web API. There are two types of functions in the Web API:

Functions
Use a GET request with functions listed in Web API Function Reference to perform operations that have no side-effects. These functions generally retrieve data. They return either a collection or a complex type. Each of these functions has a corresponding message in the organization service.
Query Functions
Use the functions listed in Web API Query Function Reference to evaluate properties and values in the composition of a query. Each of these functions has a corresponding ConditionOperator value.

In this topic

Passing parameters to a function

Pass reference to an entity to a function

Bound and unbound functions

Compose a query with functions

Passing parameters to a function

For those functions that require parameters, the best practice is to pass the values using parameters. For example, when you use the GetTimeZoneCodeByLocalizedName Function, you must include the LocalizedStandardName and LocaleId parameter values. So, you could use the following inline syntax as shown here.

GET [Organization URI]/api/data/v8.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

However, there’s an open issue using DateTimeOffset values with the inline syntax, as explained in the following article: DateTimeOffset as query parameter #204.

Therefore, the best practice is to pass the values in as parameters as shown in the following code sample. If you use this best practice, you can avoid the open issue that applies to DateTimeOffset.

GET [Organization URI]/api/data/v8.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

Parameter aliases also allow you to re-use parameter values to reduce the total length of the URL when the parameter value is used multiple times.

Pass reference to an entity to a function

Certain functions will require passing a reference to an existing entity. For example, the following functions have a parameter that requires a crmbaseentity EntityType:

CalculateRollupField Function	IncrementKnowledgeArticleViewCount Function	InitializeFrom Function
IsValidStateTransition Function	RetrieveDuplicates Function	RetrieveLocLabels Function
RetrievePrincipalAccess Function	RetrieveRecordWall Function	ValidateRecurrenceRule Function

When you pass a reference to an existing entity, use the @odata.id annotation to the Uri for the entity. For example if you are using the RetrievePrincipalAccess Function you can use the following Uri to specify retrieving access to a specific contact:

GET [Organization URI]/api/data/v8.2/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}

The @odata.id annotation can be the full Uri, but a relative Uri works too.

Bound and unbound functions

Only those functions found in Web API Function Reference may be bound. Query functions are never bound.

Bound functions

In the CSDL metadata document, when a Function element represents a bound function, it has an IsBound attribute with the value true. The first Parameter element defined in the function represents the entity that the function is bound to. When the Type attribute of the parameter is a collection, the function is bound to an entity collection. As an example, the following is the definition of the CalculateTotalTimeIncident Function and CalculateTotalTimeIncidentResponse ComplexType in the CSDL.

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

This bound function is equivalent to the CalculateTotalTimeIncidentRequest used by the organization service. In the Web API this function is bound to the incident EntityType that represents the CalculateTotalTimeIncidentRequest.IncidentId property. Instead of returning a CalculateTotalTimeIncidentResponse, this function returns a CalculateTotalTimeIncidentResponse ComplexType. When a function returns a complex type, its definition appears directly above the definition of the function in the CSDL.

To invoke a bound function, append the full name of the function to the URL and include any named parameters within the parentheses following the function name. The full function name includes the namespace Microsoft.Dynamics.CRM. Functions that aren’t bound must not use the full name.

Important

A bound function must be invoked using a URI to set the first parameter value. You can’t set it as a named parameter value.

The following example shows an example using the CalculateTotalTimeIncident Function, which is bound to the incident entity.

Request

GET [Organization URI]/api/data/v8.2/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30
}

Unbound functions

The WhoAmI Function isn’t bound to an entity. It is defined in the CSDL without an IsBound attribute.

<ComplexType Name="WhoAmIResponse">
  <Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
  <Property Name="UserId" Type="Edm.Guid" Nullable="false" />
  <Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>

This function corresponds to the WhoAmIRequest and returns a WhoAmIResponse ComplexType that corresponds to the WhoAmIResponse used by the organization service. This function doesn’t have any parameters.

When invoking an unbound function, use just the function name as shown in the following example.

Request

GET [Organization URI]/api/data/v8.2/WhoAmI() HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Response

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
{
 "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
 "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
 "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
 "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
}

Compose a query with functions

There are two ways that functions can be used to control data returned with queries. Certain functions allow for control over the columns or conditions that they return and you use query functions to evaluate conditions in a query.

Composable functions

Some functions listed in Web API Function Reference will return a collection of entities. A subset of these functions are composable, which means that you can include an additional $select or $filter system query option to control which columns are returned in the results. These functions have an IsComposable attribute in the CSDL. Each of these functions has a companion message in the organization service that accept either a ColumnSet or QueryBase type parameter. The OData system query options provide the same functionality so these functions do not have the same parameters as their companion messages in the organization service. The following table shows a list of those composable functions in this release.

GetDefaultPriceLevel Function	RetrieveAllChildUsersSystemUser Function	RetrieveBusinessHierarchyBusinessUnit Function
RetrieveByGroupResource Function	RetrieveByResourceResourceGroup Function	RetrieveMembersBulkOperation Function
RetrieveParentGroupsResourceGroup Function	RetrieveSubGroupsResourceGroup Function	RetrieveUnpublishedMultiple Function
SearchByBodyKbArticle Function	SearchByKeywordsKbArticle Function	SearchByTitleKbArticle Function

Query functions

Functions listed in Web API Query Function Reference are intended to be used to compose a query. These functions can be used in a manner similar to the Standard query functions, but there are some important differences.

You must use the full name of the function and include the names of the parameters. The following example shows how to use the LastXHours Function to return all account entities modified in the past 12 hours.

GET [Organization URI]/api/data/v8.2/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Use Web API functions

In this topic

Passing parameters to a function

Pass reference to an entity to a function

Bound and unbound functions

Bound functions

Unbound functions

Compose a query with functions

Composable functions

Query functions

See Also

Additional resources