In our previous post we learned about Web API Actions in Dynamics CRM 2016. In this blog post we will look at how to execute Web API Functions in Dynamics CRM 2016.
Web API Functions
Functions represent re-usable operations that have no side-effects. Use a GET request with functions listed in Web API Function Reference to perform these operations. They return either a collection or a complex type (Complex types are key-less named structured types consisting of a set of properties). Each Web API function has a corresponding message in the organization service. These functions may be bounded or unbounded.
Bound Functions
When a Function element represents a bound function, it has an IsBound attribute with the value true in CSDL metadata document. 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.
This is an example of bound function in CSDL metadata document.
<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>
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.
Example:
GET [Organization URI]/api/data/v8.0/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
UnBound Functions
Unbounded functions or not bound to any entity or collection. They are defined in CSDL metada document without an Isbound attribute.When invoking an unbound function, just use the function name.
Example:
GET [Organization URI]/api/data/v8.0/WhoAmI()
Passing Parameter To Web API Function
For those functions that require parameters, the best practice is to pass the values using parameters.
Let’s take example of GetValidReferencingEntities function. This function retrieves the set of entities that are valid as the related entity (many) to the specified entity in a one-to-many relationship.
Parameter to be passed to the function is:
We will pass Account as value in ReferencedEntityName parameter as shown below:
[Organization Url]/api/data/v8.0/GetValidReferencingEntities(ReferencedEntityName='Account')
WhoAmI Function
There are many functions available which you can execute. You can find the list of all available functions here at Web API Function Reference. We will execute WhoAmI function here, as an example.
WhoAmI function retrieves the UserId, BusinessUnitId and OrganizationId of the logged on user. This function does not take any parameter. The WhoAmI function is not bound to any entity types.
This function corresponds to the WhoAmIRequest and returns a WhoAmIResponse ComplexType that corresponds to the WhoAmIResponse used by the organization service.
Request
GET [Organization URI]/api/data/v8.0/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.0/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",
"UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",
"OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"
}
To execute this function you can use the following code.
Code
function WhoAmIRequest() {
var clientUrl = Xrm.Page.context.getClientUrl();
var req = new XMLHttpRequest()
req.open("GET", encodeURI(clientUrl + "/api/data/v8.0/WhoAmI()"), true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.onreadystatechange = function () {
if (this.readyState == 4 /* complete */) {
req.onreadystatechange = null;
if (this.status == 200) {
var data = JSON.parse(this.response);
alert("User Id : "+data.UserId+"\nBusiness Unit Id : "+data.BusinessUnitId+ "\nOrganization Id : "+data.OrganizationId);
}
else {
var error = JSON.parse(this.response).error;
alert(error.message);
}
}
};
req.send();
}