Dynamics® API

See how easily Chime can provide enterprise click to chat leveraging Microsoft Dynamics® CRM.

Join the Beta Request a Demo Try Cloud Version

Note: The Virtual Agent can be downloaded here » Virtual Agent SDK (zip) (VirtualAgentSDK\Samples\DynamicsCRM)

Overview

The Dynamics CRM Virtual Agent SDK sample includes two Virtual Agents that work together to create and update Case records. The Pre-Conversation Virtual Agent creates a Case record in Dynamics and fills out the following fields:

The Post-Conversation Virtual Agent updates the Case record with the following information:

Dynamics® CRM customizations for Virtual Agent sample

This sample creates a new Case in Dynamics CRM and fills out some fields with information from Chime. For example, it sets the Case Origin field to "Chime-chat", which is a customization of the Dynamics CRM application. The pre-conversation Virtual Agent sets the "caseorigincode" field of the Case record to "100,000,004". The Virtual Agent sample uses this small customization to the Dynamics service. To make this customization in Dynamics go to Settings, Customize the System, then choose Entities from the left-side navigation bar. Double-click the Case entity to open and edit, then choose Fields from the left-side navigation bar under Case. Double-click "caseorigincode" to edit this field, then choose Edit next to Option Set. Add a new option with name "Chime-chat" and value "100,000,004" and finally save the changes.

Before we get started...Check your references!

The following examples use these references. These examples also use a reference to the Microsoft.Crm.Sdk.


using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.ServiceModel.Description;
using System.Text;
using System.Xml.Linq;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Client;
using Microsoft.Xrm.Sdk.Query;

                            

1. Connect to the Dynamics server

The following code shows you how to use your authentication credentials to create a reference to a service proxy object. Once this reference is made, you can make calls directly on the service proxy object to access tables and resources on your Dynamics server. The service proxy must be disposed after use.


var _serverProxy = new OrganizationServiceProxy(new Uri(service_url), null, new ClientCredentials() { UserName = { UserName = username, Password = password } }, null);
    public void ConnectToDynamics()
    {
        using (_serverProxy)
        {
            _serverProxy.Authenticate();
            isConnectedToDynamics = true;
            Console.WriteLine("authenticated with Dynamics");
        }
    }

                        

2. Find or create a Contact record

This example shows you how to retrieve an EntityReference, this is an object that directly references an entity record in Dynamics, from the Contact table. We are going to try to find a Contact record with a given email address, and if we cannot find one, we’re going to create one. Contact records require a first and last name to be created in the system. Notice how we use the QueryByAttribute object to construct the query we will send to the server.


private EntityReference FindContactWithEmail(string email, string firstname, string lastname)
{
    //is there an existing contact with this email address?
    QueryByAttribute querybyexpression = new QueryByAttribute("contact");
    querybyexpression.Attributes.AddRange("emailaddress1");
    querybyexpression.Values.AddRange(email);
    EntityCollection retrieved = _serverProxy.RetrieveMultiple(querybyexpression);
    var contact = retrieved.Entities.FirstOrDefault();
    if (contact != null)
    {
        return contact.ToEntityReference();
    }

    //create new contact with this email address?
    Entity newContact = new Entity("contact");
    newContact.Attributes["firstname"] = firstname;
    newContact.Attributes["lastname"] = lastname;
    newContact.Attributes["emailaddress1"] = email;
    Guid newContactGuid = _serverProxy.Create(newContact);

    //fetch the entity of the newly created contact
    Entity foundnewContact = _serverProxy.Retrieve("contact", newContactGuid, new ColumnSet(true));
    if (foundnewContact != null)
    {
        return foundnewContact.ToEntityReference();
    }
    throw new Exception("unable to create new contact in Dynamics for " + firstname + " " + lastname + " " + email);
}

                        

3. Create a case in Dynamics

This example shows you how to create an incident record, or case, in Dynamics. First you create an Entity object and specify what type of Entity you are creating in the constructor, in this case it’s an incident Entity. We’re going to populate the title, description, and customerid fields of this new record before sending it to the server (notice how we use the FindContactWithEmail method from the previous example). We can construct a URL to this new record given the record GUID which is returned from the server on creation.


public void CreateCase(string firstname, string lastname, string email, string question)
{
    using (_serverProxy)
    {
        //create the new case/incident/ticket
        Entity entity = new Entity("incident");
        entity.Attributes["title"] = question;
        entity.Attributes["caseorigincode"] = new OptionSetValue() { Value = 100000004 }; //100,000,004
        entity.Attributes["description"] = "Inbounded chat by Chime on " + DateTime.Now;
        entity.Attributes["customerid"] = FindContactWithEmail(email, firstname, lastname);

        Guid newRecordGuid = _serverProxy.Create(entity);
        newRecordURL = instance_url + @"main.aspx?etn=incident&id=" + newRecordGuid + @"&pagetype=entityrecord";
    }
}

                        

4. Update a case in Dynamics

This example shows how you can update a record in Dynamics, given that record’s system GUID. This sample will add new text to any existing text of the description field of the case. When it retrieves the record it retrieves all columns. Note, the description field has a 2,000 character limit.


public void UpdateCase(string comment, Guid recordGuid)
{
    using (_serverProxy)
    {
        Entity entity = _serverProxy.Retrieve("incident", recordGuid, new ColumnSet(true));
        var olddescription = entity.Attributes["description"];
        var newdescription = olddescription + "\n" + comment;
        if (newdescription.Length < 2001)
        {
            entity.Attributes["description"] = newdescription;
            _serverProxy.Update(entity);
        }
    }
}

                        

Questions?

Have a question about Chime integration with Microsoft Dynamics® CRM? Ask one of our developers at InstantDev@instant-tech.com.