CRM 2016 - WEB API CRUD Operations (Part 1)

How to CRUD with the new CRM 2016 Web API in Javascript

In this post I wanted to talk of the new Web API available in CRM 2016. I am not sure about you but I could not find any example, other than the basic Create operation provided by Microsoft, of how to use the new Web API for CRUD operations.
So here it is an example of a RETRIEVE (and the CREATE from the Microsoft example found here) query using the Web API, I will be adding more examples of "Retrieve Multiple, "Update" and "Delete" as I discover how to implement them.

"use strict";
var bd_Utilities = window.bd_Utilities || {};
bd_Utilities.WebAPI = bd_Utilities.WebAPI || {};

(function () {
    this.create = function (entitySetName, entity, successCallback, errorCallback) {
        var req = new XMLHttpRequest();
        req.open("POST", encodeURI(getWebAPIPath() + entitySetName), 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 == 204) {
                    if (successCallback)
                        successCallback(this.getResponseHeader("OData-EntityId"));
                }
                else {
                    if (errorCallback)
                        errorCallback(bd_Utilities.WebAPI.errorHandler(this.response));
                }
            }
        };
        req.send(JSON.stringify(entity));
    };

this.retrieve = function (id, entitySetName, select, expand, successCallback, errorCallback) {
        var req = new XMLHttpRequest();
        req.open("GET", encodeURI(getWebAPIPath() + entitySetName + "(" + id + ")" + select), 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) {
                    if (successCallback)
                        successCallback(JSON.parse(this.responseText, bd_Utilities.WebAPI.dateReviver));
                }
                else {
                    if (errorCallback)
                        errorCallback(bd_Utilities.WebAPI.errorHandler(this.response));
                }
            }
        };
        req.send();
    };
 
//This is the calling function:

search: function () {
        bd_Utilities.WebAPI.retrieve("00000000-0000-0000-0000-000000000090", "contacts", "?$select=firstname,lastname", "",
       
        function (result) {
            var contact = result;
            console.log("Contact retrieved")
        },
        function (error) { console.log(error.message); });
    }

//And these are some helper functions from the CRM SDK

    //Internal supporting functions
    function getClientUrl() {
        //Get the organization URL
        if (typeof GetGlobalContext == "function" &&
            typeof GetGlobalContext().getClientUrl == "function") {
            return GetGlobalContext().getClientUrl();
        }
        else {
            //If GetGlobalContext is not defined check for Xrm.Page.context;
            if (typeof Xrm != "undefined" &&
                typeof Xrm.Page != "undefined" &&
                typeof Xrm.Page.context != "undefined" &&
                typeof Xrm.Page.context.getClientUrl == "function") {
                try {
                    return Xrm.Page.context.getClientUrl();
                } catch (e) {
                    throw new Error("Xrm.Page.context.getClientUrl is not available.");
                }
            }
            else { throw new Error("Context is not available."); }
        }
    }

    function getWebAPIPath() {
        return getClientUrl() + "/api/data/v8.0/";
    }

    //Internal validation functions
    function isString(obj) {
        if (typeof obj === "string") {
            return true;
        }
        return false;

    }

    function isNull(obj) {
        if (obj === null)
        { return true; }
        return false;
    }
    function isUndefined(obj) {
        if (typeof obj === "undefined") {
            return true;
        }
        return false;
    }
    function isFunction(obj) {
        if (typeof obj === "function") {
            return true;
        }
        return false;
    }
    function isNullOrUndefined(obj) {
        if (isNull(obj) || isUndefined(obj)) {
            return true;
        }
        return false;
    }
    function isFunctionOrNull(obj) {
        if (isNull(obj))
        { return true; }
        if (isFunction(obj))
        { return true; }
        return false;
    }

    // This function is called when an error callback parses the JSON response
    // It is a public function because the error callback occurs within the onreadystatechange
    // event handler and an internal function would not be in scope.
    this.errorHandler = function (resp) {
        try {
            return JSON.parse(resp).error;
        } catch (e) {
            return new Error("Unexpected Error")
        }
    }

    this.dateReviver = function (key, value) {
        ///<summary>
        /// Private function to convert matching string values to Date objects.
        ///</summary>
        ///<param name="key" type="String">
        /// The key used to identify the object property
        ///</param>
        ///<param name="value" type="String">
        /// The string value representing a date
        ///</param>
        var a;
        if (typeof value === 'string') {
            a = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2}(?:\.\d*)?)Z$/.exec(value);
            if (a) {
                return new Date(Date.UTC(+a[1], +a[2] - 1, +a[3], +a[4], +a[5], +a[6]));
            }
        }
        return value;
    }

}).call(bd_Utilities.WebAPI);

How to associate a record as Activity Party to an activity.

In this post I will show you how to associate a record to an activity (in this case an email) as an Activity Party using the OData REST end point with Javascript.
Setting the "To", "From", "Cc", "Bcc" fields on an email message is not so straight forward as other lookup fields such as the "Regarding" field. This is because these fields are of Activity Party type.
There are two important steps to follow:

1.  Set the "party" of the ActivityParty (what will be related to the activity) as an EntityReference. activityParty.PartyId = { Id: record.RecordId, LogicalName: "logicalName" }; 
2.  Set the "activity" of the ActivityParty (the e-mail, in this case) as an EntityReference. activityParty.ActivityId = { Id: email.ActivityId, LogicalName: "email" }; 

The third steps is to set the participation type (what role the party has on the activity)

Use: activityParty.ParticipationTypeMask = { Value: 1 };  To set the "From" field
Use: activityParty.ParticipationTypeMask = { Value: 2 };  To set the "To" field
Use: activityParty.ParticipationTypeMask = { Value: 3 };  To set the "Cc" field 
Use: activityParty.ParticipationTypeMask = { Value: 4 };  To set the "Bcc" fiel.

Ultimately perform the REST request.

Here is the complete code:

 createActivityParty: function (object, email, logicalName, recipient) {

        var activityParty = {}, jsonActivityParty;
        switch (logicalName) {
            case "account":
                activityParty.PartyId = {
                    Id: object.AccountId,
                    LogicalName: "account"
                };
                break;

            case "contact":
                activityParty.PartyId = {
                    Id: object.ContactId,
                    LogicalName: "contact"
                };
                break;
            case "systemUser":
                activityParty.PartyId = {
                    Id: object.SystemUserId,
                    LogicalName: "systemuser"
                };
                break;
            default:
        }


        // Set the "activity" of the ActivityParty (the e-mail, in this case) as an EntityReference.
        activityParty.ActivityId = {
            Id: email.ActivityId,
            LogicalName: "email"
        };

        // Set the participation type (what role the party has on the activity). For this
        // example, we'll put the account in the From field (which has a value of 1).
        if (recipient == "sender") {
            activityParty.ParticipationTypeMask = { Value: 1 };
        }
        else if (recipient == "to") {
            activityParty.ParticipationTypeMask = { Value: 2 };
        }
        else if (recipient == "cc") {
            activityParty.ParticipationTypeMask = { Value: 3 };
        }

        //stringify the object to be created
        jsonActivityParty = JSON.stringify(activityParty);

        this._performRequest({
            type: "POST",
            url: this._ODataPath() + "/ActivityPartySet",
            data: jsonActivityParty,
            success: function (request) {

            },
            error: function (request) {
                this._errorHandler(request);

            }
        });
    },

Hope this helps, also don't forget to check the SDK. which is where I learned about this.

How to use the CSDL file generated by the REST endpoint with Silverlight.

In this walk through, I will walk you through the steps needed to download the CSDL file that the REST endpoint generates based on the entities available to your development organization. Later we will see how to create a WCF data service based on the CSDL file.

N.B. Only those entities that are present when you generate the classes will be available for the Silverlight application.
Steps:

1. In CRM 2011 navigate to Settings. Choose Customizations and then Developer Resources.
2. Under Service Endpoints, click the Download CSDL link and save the OrganizationData.csdl file to your computer.

Now that we have our file generated and downloaded to our computer, we can use it to create a WCF data service, so from Visual Studio:

1. In your Visual Studio Silverlight application project, right-click References, and then click Add Service Reference.
2. Type the path of the location where you saved the OrganizationData.csdl file, and then click Go.
3. Enter an appropriate Namespace and then click OK.

The name of the System.Data.Services.Client context will be "YourOrganizationNameContext".

Well done! Now we have our Silverlight application all set up ready to access the entities in our CRM organization. In another post I will show how to use the REST endpoint with Silverlight.
Stay tuned!