Sample Application Using Microsoft Dynamics CRM Social Care Framework

Microsoft Corporation

May, 2014

Summary

Do you have the need to identify the social buzz around your brand, product, or service on social channels like Twitter or Facebook? Using the social care generic framework you can route social data obtained from various social channels into your Microsoft Dynamics CRM system.

This article provides detailed information on how to use the social care framework to track social posts in CRM or track a contact's presence in social media. Use this framework to automatically convert social posts to cases, create social profiles and contact records in CRM for the author of the posts, search existing records, and associate social posts and profiles to them. You can configure watch lists to identify the social buzz around your brand, product, or service on social channels like Twitter or Facebook. Then, you can associate a watch list with a Microsoft Dynamics CRM queue, which is set up to automatically create cases from social posts.

Applies To

Microsoft Dynamics CRM Online Spring ‘14 and Microsoft Dynamics CRM 2013 Service Pack 1 (SP1) (on-premises)

Introduction

Microsoft Dynamics CRM Online Spring ‘14 and Microsoft Dynamics CRM 2013 Service Pack 1 (SP1) (on-premises) provide a social care generic framework that you can use to route social data obtained from various social channels into your CRM system. The social care framework provides the general interface, data model, and necessary APIs for integrating social listening applications like Facebook and Twitter with Microsoft Dynamics CRM to track social messages and profile data. Using the social care framework, third-party systems can push social data feed containing posts from the social channels to CRM and can associate a social post with existing CRM records.

The social care framework has the following capabilities:

• Social activity to track social posts in CRM

• Social profile to track a contact’s presence in social media

• Rule-driven manual and automated case creation and attribute values in CRM

You can use this framework to automatically convert social posts to cases, create social profiles and contact records in CRM for the author of the posts, search existing records, and associate social posts and profiles to them. You can configure watch lists with keywords, #tags, and @mentions to identify the social buzz around your brand, product, or service on social channels like Twitter or Facebook. Then, you can associate a watch list with a Microsoft Dynamics CRM queue, which is set up to automatically create cases from social posts. More information:Automatically create cases from email or social monitoring.

Capabilities of this sample

You can download the sample app based on CRM APIs to get visibility into Microsoft Dynamics CRM. This sample demonstrates how you can build an application that will leverage the capabilities of the social care framework. You may use this sample project as a starting point to create an application that service staff can use to link data from social sources with data in Microsoft Dynamics CRM.

This sample uses Twitter to demonstrate these capabilities, but other social sites have public APIs that can be used in a similar manner.

When you run this sample you’ll be able to:

• Sign into a Twitter account.

• View messages sent directly to the account.

• Search for tweets that match a search term.

• Authenticate with the CRM server.

• Create a watch list of keywords, tags, and mentions that identify your brand, product, or service and set up automatic creation of cases.

• Track a tweet as a social activity in CRM and create a case, contact, or social profile out of the social activity.

• View any CRM cases linked to Twitter posts.

The sample contains the following form to create CRM records that are linked to a selected tweet.

Sample implementation

This sample is an ASP.NET MVC 4 web application. The application depends on the following NuGet packages:

• Microsoft.AspNet.WebApi.Client

• Microsoft.Net.Http

• TweetSharp-Unofficial

• Microsoft Azure Authentication Library Beta

When you build this sample these components will be installed in the solution.

Authentication and the OData API

This sample uses the CRM OData endpoint. Since the sample application is a separate application (and not a web resource within CRM), it needs to authenticate explicitly against the OData endpoint. The sample app can use regular domain credentials to talk to the on-premises CRM server. For working against Microsoft Dynamics CRM Online and Internet-facing deployments (IFDs) of CRM, the sample app uses OAuth for authentication.

Sample project components

This sample is organized into the folders shown here.

Content

Contains CSS used by the application.

Controllers

The various controllers used in the sample application are listed in the following table.

Models

The /Models/CrmModel.cs file contains models for the following Microsoft Dynamics CRM entities:

• Contact

• Case

• SocialProfile

• Queue

• SocialActivity

These models don’t describe all the available attributes for these entities, just those required for creating and updating entity attributes used by this sample.

It also includes models for the following data structures used by the entities:

• SocialActivityAdditionalParameters: This class represents the values that will go into the "SocialAdditionalParams" attribute (as a JSON blob) of the social activity record during a create call. This class controls the processing of the social activity on the CRM server.

• OptionSetValue: Because OData doesn’t support labels with options, this class has only an integer Value property.

• AssociatedObject: This model is similar to the EntityReference.

Views

The Views folder contains the display pages and controls for the various scenarios:

• Views/Home: Contains the views and controls for the main landing page. This is the launching point for:

  • Signing in with a Twitter account

  • Searching for tweets

  • Invoking a watch list action

  • Viewing linked CRM cases

  • Launching the CRM integration pages

• Views/Cases: Contains the views and controls for the flow related to searching for cases, creating a case out of a tweet, and associating a tweet to an existing case.

• Views/Contacts: Contains the views and controls for the flow related to searching for a contact, creating a contact for the sender of a tweet, and associating a tweet to an existing contact.

• Views/SocialProfile: Contains the views and controls for searching for a social profile in CRM, and creating a new social profile (and its associated contact) for the selected tweet.

CRM connection

The CRMConnect.cs file contains code for authenticating and communicating with the CRM server. It picks up information about the server from the web.config file and uses it to identify and authenticate to the CRM server.

For authenticating with the on-premises CRM server, it uses a domain account. When communicating with a CRM Online or claims-enabled IFD, it uses OAuth for authentication. The sample application uses the Microsoft Azure Active Directory Authentication Library (ADAL). For more information on using OAuth against CRM, please refer to the Microsoft Dynamics CRM 2013 SDK topic Authenticate the user with the web services.

Once authenticated, the sample application sends HTTP requests to the CRM server to retrieve data (using HTTP GET) and create records (using HTTP POST).

Overview of the social care framework

Knowing the CRM framework for social is a key piece in understanding the sample application. At a high level:

1. The application issues a create request for a social activity record.

2. CRM creates the social activity record with the status reason of “Processing.”

3. An asynchronous plug-in then processes this activity record. The SocialAdditionalParameters attribute plays a special role here:

   1. Its value is a JSON blob.

   2. It has a property with the name targetEntityName that conveys the intent of the social activity creation to the plug-in. Out-of-box supported values are “contact”, “socialactivity”, and “incident”. Any other value will result in the plug-in skipping over the record. As a system customizer, you can author additional plug-ins that can process your additional target types.

   3. The attribute has the following properties that provide information about the author of the social message.

      Properties	Description
      socialHandle	Maps to uniqueprofileid attribute of the Social Profile entity.
      profilename	Maps to the profilename attribute of the Social Profile entity.
      profilelink	Maps to the profilelink attribute of the Social Profile entity.
      customerid	Maps to a customerid lookup attribute (assumes a contact entity reference) of the Social Profile entity.
      community	Maps to the community option set attribute of the Social Profile entity. It indicates whether the profile belongs to Twitter, Facebook, or another social channel.
      influencescore	Maps to the influencescore attribute of the Social Profile entity.
      fullName	Maps to the profilefullname attribute of the Social Profile entity.
      queueId	For targetEntityName “incident”, this parameter is of special significance. The plug-in will add the created or processed social activity record to the specified queue. The active convert rule for social to case settings on this queue will then create a case based on the convert rule settings.

      A sample value of the SocialAdditionalParameters attribute is: {'targetEntityName':'entityNameString', 'socialHandle':'socialHandleString', 'profileName':'profileNameString', 'profilelink':'profilelinkString', customerid:'customeridGuidString', 'community':'communityInt', 'influencescore':'influencescoreFloat', queueId:'queueIdGUID' }

4. While processing the social activity record, the plug-in will:

   1. Try to look up a social profile having the same unique identifier (uniqueprofileid or profilename).

   2. If found, use that social profile and its associated contact.

   3. If not found, a new social profile record will be created. If a value for the customerid is passed in, the newly created social profile will be associated to that contact; otherwise, a new contact will be created.

5. If the processing of the social activity record by the plug-in completes successfully, the status reason of the activity is changed to “Completed.” If any failure is encountered, the status reason is changed to “Failed.” If the value of targetEntityName isn’t recognized, the activity will remain in the processing status.

6. For case conversion flow, the active convert rule will create a case and set the regarding attribute on the social activity appropriately. Note that there will be time delay between the marking of the social activity as “completed” and the update of its regarding attribute. This is due to the case conversion happening asynchronously.

Possible enhancements

As a developer and CRM customizer, there are multiple scenarios you can additionally target. Some of them are:

1. Integrating with a different social platform like Facebook.

2. Authoring plug-ins to support a different entity type, such as lead, or a custom entity.

3. Pushing notifications related to case resolution from CRM (via plug-ins on the case entity) into the sample application about updates to cases created via the application.

This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

© 2014 Microsoft. All rights reserved.

Microsoft, Microsoft Dynamics, and Visual Studio are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.