I've been using the completely awesome XrmToolBox to import translations for a large CRM organization, but I kept running into System.TimeoutException errors like the following:
System.TimeoutException: The HTTP request to 'https://XXX/XrmServices/2011/Organization.svc' has exceeded the allotted timeout of 00:02:00. The time allotted to this operation may have been a portion of a longer timeout.

After trying a few different things (running from the CRM app server, only importing translations for one thing at a time, etc.), I kept running into problems, so I decided to modify the source code to add adjustable timeout values to the CRM connections.

This required making changes to the McTools.Xrm.Connection.ConnectionDetail class and the McTools.Xrm.Connection.WinForms.Connection form class. Here is a download link for my modified versions - XrmToolBox-connection-files.zip. To update your copy, do the following:

2. Extract the contents of my attachment and place the files in their respective project folders under the XrmToolBox\Connection Projects directory.
3. Build the McTools.Xrm.Connection.WinForms project.
4. Copy McTools.Xrm.Connection.dll and McTools.Xrm.Connection.WinForms.dll files to your XrmToolbox directory. If prompted to overwrite the existing files, say yes.

You will need to update your existing connections to use the new timeout value. The timeout is entered in the format of HH:MM:SS, so if you want to make the timeout 10 minutes, you would enter 00:10:00 in the timeout value box.

In my last post I provided a detailed walkthrough of how to perform sentiment analysis on incoming emails received in Microsoft Dynamics CRM by parsing them with HP IDOL OnDemand’s sentiment analysis API and then storing the calculated sentiment values on the email records. In today’s post, I will show a similar, but slightly more complex integration that enables "find similar" functionality for emails stored in Dynamics CRM.

Continuing with the scenario from my previous post, let’s assume you manage a Microsoft Dynamics CRM system (online or on-premise) for an organization that provides customer service and support via a variety of channels including phone, email and live chat. In order to help agents resolve inbound email cases more quickly, the operations team has asked you to add an embedded display on the email form that shows conceptually similar email records so the agents can easily view them. Just as before, we’re in luck because IDOL OnDemand has a find similar API.

The solution approach

Unlike the sentiment analysis solution I discussed previously where we used a workflow to retrieve a sentiment score and write it directly to the email record, the find similar email display will require two different calls to the IDOL OnDemand service because to find similar items, IDOL OnDemand needs to have an index of items to search. We’ll need to populate this index with emails as they’re received, and then we’ll run the find similar search against the index when agents view an email record. Thus, the solution I am showing today has two pieces:

1. First, there is a custom workflow activity that adds inbound emails to an IDOL OnDemand text index using the add to text index API.
2. Second, there is an HTML web resource that can be embedded on the email form that uses an AJAX call to the find similar API to retrieve similar emails from the index and then display summary data and a hyperlink to the actual CRM record for each result to the end user.

Creating the index

Before we can populate an index with data, we need to have an index that can be populated. Although IDOL OnDemand offers APIs that can be used to manage indexes programmatically, it’s easier in this case to use the index management tools that are available on the main account screen. On that screen, click the "Create, Manage, Index and Search your own Text Indexes" link, then click the "create text index" button on the next page. Give your index a name, and then just accept the default options for each of the following prompts in the wizard.* Remember the name you selected because you’ll need to use it later. My index name is "lucas-test."

The indexing process

IDOL OnDemand can index JSON documents that contain both standard and custom fields, so we’re going to create a JSON object that contains the email body, the email subject line and the email activity id as the index reference (basically a primary key) field. Because an IDOL OnDemand index has a standard field called title that is, per the index developer documentation, considered "highly relevant," we’ll also set that to the value of the email subject. Our logical mappings will look like this:

• Email "body" (description) -> Index "content"
• Email "subject" -> Index "title"
• Email "subject" -> Index "subject"
• Email "activityid" -> Index "reference"

You can, of course, index lots of other fields like "to," "from," "date," etc., and the more complete your index, the better your search results will be.

In order to populate the index with the fields above, the custom workflow activity needs input parameters for the email body, subject and activity id. Here's how we define them:

[Input("Content")]

public InArgument<String> Content { get; set; }

[Input("Subject")]

public InArgument<String> Subject { get; set; }

[Input("Email")]

[ReferenceTarget("email")]

public InArgument<EntityReference> Email { get; set; }

We also need to set up three variables to help us call IDOL OnDemand. They are the URL for the find similar API, the API key to authorize our requests and the name of the text index that will hold the email data:

//address of the service to which you will post your json messages

private string _webAddress = "https://api.idolondemand.com/1/api/sync/addtotextindex/v1";

//name of the text index

private string _indexName = "lucas-test";

//idol ondemand api key

private string _apiKey = "XXXXXXXXXXXXXXXX";

Now we’re ready to index the inbound email using the following steps:

1. Check whether the email description field contains text.
2. If it does, strip HTML tags using a helper function.
3. Serialize the index request to a JSON object.
4. Pass the index request object to IDOL OnDemand with an HttpWebRequest. (In order to keep this example simple, we’re going to ignore the response from IDOL OnDemand, but you might want to do something with the response if you try this out on your own.)

Here's the code that does all of this:

string inputText = Content.Get(executionContext);
if (inputText != string.Empty)
{
	inputText = HtmlTools.StripHTML(inputText);
	IndexDocument myDoc = new IndexDocument
	{
	 Content = inputText,
	  Reference = (Email.Get(executionContext)).Id.ToString(),
	  Subject = Subject.Get(executionContext),
	  Title = Subject.Get(executionContext)
	};
	DocumentWrapper myWrapper = new DocumentWrapper();
	myWrapper.Document = new List<IndexDocument>();
	myWrapper.Document.Add(myDoc);
	//serialize the myjsonrequest to json
	System.Runtime.Serialization.Json.DataContractJsonSerializer serializer = new System.Runtime.Serialization.Json.DataContractJsonSerializer(myWrapper.GetType());
	MemoryStream ms = new MemoryStream();
	serializer.WriteObject(ms, myWrapper);
	string jsonMsg = Encoding.Default.GetString(ms.ToArray());
	//create the webrequest object and execute it (and post jsonmsg to it)
	HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(\_webAddress);
	//set request content type so it is treated as a regular form post
	req.ContentType = "application/x-www-form-urlencoded";
	//set method to post
	req.Method = "POST";
	StringBuilder postData = new StringBuilder();
	//HttpUtility.UrlEncode
	//set the apikey request value
	postData.Append("apikey=" + System.Uri.EscapeDataString(\_apiKey) + "&");
	//postData.Append("apikey=" + \_apiKey + "&");
	//set the json request value
	postData.Append("json=" + jsonMsg + "&");
	//set the index name request value
	postData.Append("index=" + _indexName);
	//create a stream
	byte[] bytes = System.Text.Encoding.ASCII.GetBytes(postData.ToString());
	req.ContentLength = bytes.Length;
	System.IO.Stream os = req.GetRequestStream();
	os.Write(bytes, 0, bytes.Length);
	os.Close();
	//get the response
	System.Net.WebResponse resp = req.GetResponse();
	//deserialize the response to a ResponseBody object
	ResponseBody myResponse = new ResponseBody();
	System.Runtime.Serialization.Json.DataContractJsonSerializer deserializer = new System.Runtime.Serialization.Json.DataContractJsonSerializer(myResponse.GetType());
	myResponse = deserializer.ReadObject(resp.GetResponseStream()) as ResponseBody;
}

The StripHTML function is the same function from CodeProject that used in my sentiment analysis post, and the code is included in the download at the end of this post.

Here are the classes used for serializing the JSON request and deserializing the JSON response:

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class DocumentWrapper

{

//datamember name value indicates name of json field to which data will be serialized/from which data will be deserialized

[DataMember(Name = "document")]

public List<IndexDocument> Document { get; set; }

}

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class IndexDocument

{

[DataMember(Name = "title")]

public string Title { get; set; }

[DataMember(Name = "reference")]

public string Reference { get; set; }

[DataMember(Name = "subject")]

public string Subject { get; set; }

[DataMember(Name = "content")]

public string Content { get; set; }

}

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class ResponseBody

{

[DataMember(Name = "index")]

public string Index { get; set; }

[DataMember(Name = "references")]

public List<ResponseReference> References { get; set; }

}

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class ResponseReference

{

[DataMember(Name = "reference")]

public string Reference { get; set; }

[DataMember(Name = "id")]

public int Id { get; set; }

}

The results display

The code above takes care of getting the email data into our IDOL OnDemand text index, but now we need an easy way to execute the find similar queries from a web resource on the email form. This is actually incredibly easy to do with a little bit of JavaScript and jQuery.

To keep things simple, we’re going to make an assumption that all CRM emails will be in the IDOL OnDemand index by the time an agent opens one, so we can tell IDOL OnDemand to find similar records using the email’s activityid field, which we are populating as the index reference field in the code above. This also means we can embed the web resource on the email form without having to use any custom code because the Dynamics CRM form designer lets us specify that an iframe will be passed the record id when the form loads.

If turned out that we couldn’t count on the emails always being indexed before the agents viewed them, we could search the index using the relevant fields from an email record instead of using an index reference, but this would require some changes to what I’m showing today.

Our web resource will do the following:

1. Load the jQuery library (in my sample, I’m using the Google CDN).
2. Parse the record id from the value supplied in the query string that is passed to the iframe.
3. Execute a jQuery "getJSON" call to IDOL OnDemand’s find similar API.
4. Loop through the output results and write them to the screen.

Let’s take a look at the code in detail.

First, we load jQuery:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>

Next we need a function that can extract query string values:

function getParameterByName(name) {

name = name.replace(/[[]/, "\[").replace(/[]]/, "\]");

var regex = new RegExp("[\?&]" + name + "=([^&#]*)"),

results = regex.exec(location.search);

return results == null ? "" : decodeURIComponent(results[1].replace(/+/g, " "));

}

Using the getParameterByName function, we parse the email’s activity id and prepare if for querying IDOL OnDemand like so:

var entityId = getParameterByName('id');

//strip brackets because we indexed a string value of the guid without them

entityId = entityId.replace("{","").replace("}","");

Finally we send the find similar request and process the results:

var indexName = "lucas-test";
var apiKey = "f90f3fc7-0e36-40f0-b508-734f45fe9033";
$.getJSON("https://api.idolondemand.com/1/api/sync/findsimilar/v1?indexes="+indexName+"&apikey="+apiKey+"& summary=context&index\_reference="+entityId,function(data){
	var content = "";
	$(content).text("");
	$.each(data.documents, function(i,document){
		content += '<p><a href="/main.aspx?etn=email&id={' + document.reference + '}&newWindow=true&pagetype=entityrecord" target="_blank">' + document.title + '</a>';
		content += '<br />Score: ' + document.weight + '';
		content += '<br />' + document.summary + '</p>';
	});
	$(content).appendTo("#results");
});

This writes the results to a div element on the page with an id of "results." You’ll see that each result shows the email subject (stored as "title" in our index) as a hyperlink to the actual email record, a similarity score value (weight) and a summary of the similar text.

So that’s it for getting started with IDOL OnDemand’s find similar API for Microsoft Dynamics CRM data. Full code for this is in my CRM-IdolOnDemand-Tools repository on GitHub. Does this look like something you could use in your organization? If so, let us know your thoughts in the comments!

* If you want to learn more about IDOL OnDemand text indexes, I suggest you look at the text indexes section of the developer documentation.

A version of this post was originally published on the HP Enterprise Services Application Services blog.

In my last post I provided an overview of HP IDOL OnDemand and discussed a couple of things you can do with it to process and analyze data stored in a Microsoft Dynamics CRM instance. Today I'll provide a detailed walkthrough of how perform sentiment analysis on incoming emails using IDOL OnDemand. First let's consider a typical scenario for sentiment analysis.

Assume you manage a Microsoft Dynamics CRM system (online or on-premise) for an organization that provides customer service and support via a variety of channels including phone, email and live chat. The business manager has asked you to set up a mechanism that will categorize the sentiment of incoming emails sent to the main "support" address so that they can be assigned to different queues for handling by agents. Fortunately for you, IDOL OnDemand offers a sentiment analysis API!

This API parses a body of text and returns a text value for sentiment (positive, neutral or negative) and a decimal sentiment score between 1 and -1 (larger positive scores indicating positivity and larger negative scores indicating negativity)*. Let's look at how we can make use of that API inside Dynamics CRM.

The solution approach

Communicating with IDOL OnDemand from Dynamics CRM obviously requires custom code, but whether that code is called from a plug-in or workflow doesn't materially affect the code. For the purpose of this example, I'll be showing an approach that uses a custom workflow activity called from an asynchronous workflow. When an email is received, the workflow will pass the text of the email to the custom workflow activity, which will then call out to IDOL OnDemand's sentiment analysis API to retrieve the sentiment and score. The workflow will then write these values to custom fields on the email record.

The code

The custom workflow activity needs one input parameter for email text and two output parameters for sentiment and score. Here's how we define them:

[Input("Text Input")]

public InArgument<String> TextInput { get; set; }

[Output("Sentiment")]

public OutArgument<String> Sentiment { get; set; }

[Output("Score")]

public OutArgument<Decimal> Score { get; set; }

We also need to set up two variables to help us call IDOL OnDemand. The first is the URL for the sentiment analysis API:

//address of the service to which you will post your json messages

private string _webAddress = "https://api.idolondemand.com/1/api/sync/analyzesentiment/v1";

The second is the API key to authorize our requests:

//idol ondemand api key

private string _apiKey = "XXXXXXXXXXXXXXXX";

Now that all the inputs and configuration parameters are set, you are ready to process the inbound email. We're going to do the following:

1. Check whether the email description field contains text.
2. If it does, strip HTML tags using a helper function.
3. Pass the "clean" text to IDOL OnDemand with an HttpWebRequest.
4. Deserialize the JSON respsonse returned by IDOL OnDemand to a custom class object (SentimentResponse) using a DataContractJsonSerializer.
5. Return the sentiment value and score to the calling workflow.

Here's the code that does all of this:

//get the text we want to analyze

string inputText = TextInput.Get(executionContext);

if (inputText != string.Empty)

{

//use a helper function to strip out HTML tags

inputText = HtmlTools.StripHTML(inputText);

//create the webrequest object and execute it (and post jsonmsg to it)

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create(_webAddress);

//set request content type so it is treated as a regular form post

req.ContentType = "application/x-www-form-urlencoded";

//set method to post

req.Method = "POST";

//create a stringbuilder to build our request

StringBuilder postData = new StringBuilder();

//set the apikey request value

postData.Append("apikey=" + System.Uri.EscapeDataString(_apiKey) + "&");

//set the text request value

postData.Append("text=" + System.Uri.EscapeDataString(inputText));

//create a stream

byte[] bytes = System.Text.Encoding.ASCII.GetBytes(postData.ToString());

req.ContentLength = bytes.Length;

System.IO.Stream os = req.GetRequestStream();

os.Write(bytes, 0, bytes.Length);

os.Close();

//get the response

System.Net.WebResponse resp = req.GetResponse();

//deserialize the response to a SentimentResponse object

SentimentResponse myResponse = new SentimentResponse();

System.Runtime.Serialization.Json.DataContractJsonSerializer deserializer = new System.Runtime.Serialization.Json.DataContractJsonSerializer(myResponse.GetType());

myResponse = deserializer.ReadObject(resp.GetResponseStream()) as SentimentResponse;

//set output values from the fields of the deserialzed myjsonresponse object

Score.Set(executionContext, myResponse.Aggregate.Score);

Sentiment.Set(executionContext, myResponse.Aggregate.Sentiment);

}

The StripHTML function is taken from a sample on CodeProject.

Here are the classes used for deserializing the JSON response:

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class SentimentResponse

{

//datamember name value indicates name of json field to which data will be serialized/from which data will be deserialized

[DataMember(Name = "positive")]

public List<SentimentEntity> Positive { get; set; }

[DataMember(Name = "negative")]

public List<SentimentEntity> Negative { get; set; }

[DataMember(Name = "aggregate")]

public SentimentAggregate Aggregate { get; set; }

public SentimentResponse() { }

}

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class SentimentAggregate

{

[DataMember(Name = "sentiment")]

public string Sentiment { get; set; }

[DataMember(Name = "score")]

public decimal Score { get; set; }

}

//DataContract decoration necessary for serialization/deserialization to work properly

[DataContract]

public class SentimentEntity

{

[DataMember(Name = "sentiment")]

public string Sentiment { get; set; }

[DataMember(Name = "topic")]

public string Topic { get; set; }

[DataMember(Name = "score")]

public decimal Score { get; set; }

[DataMember(Name = "original_text")]

public string OriginalText { get; set; }

[DataMember(Name = "normalized_text")]

public string NormalizedText { get; set; }

[DataMember(Name = "original_length")]

public int OriginalLength { get; set; }

[DataMember(Name = "normalized_length")]

public int NormalizedLength { get; set; }

}

Although the scenario for this example mentions email, you'll note that nothing in the code is specific to emails, so you can use this same code without modifications to perform sentiment analysis on any record in your Dynamics CRM system. Full code for this is in my CRM-IdolOnDemand-Tools repository on GitHub.

That's all for now. Join me next time to see how you can index Dynamics CRM records and execute "find similar" queries using IDOL OnDemand.

* Actually the sentiment analysis API also returns separate sentiment and score values for different phrases in the text, but we're going to disregard those here and only work with the overall sentiment and score values.

A version of this post was originally published on the HP Enterprise Services Application Services blog.

Inside any organization's Microsoft Dynamics CRM system, there is a wealth of raw data that can be turned into actionable intelligence if it can be effectively analyzed. This data can be found in emails, case notes, attachments and other records that are created and stored in the course of day-to-day business. In this three-part series, I will show how you can unlock this data using HP IDOL OnDemand's powerful text analysis capabilities. Specifically I will show how you can perform sentiment analysis on incoming emails and also how you can index Dynamics CRM records so that agents can easily see similar, relevant records. Before we get into the technical details, let's take a closer look at IDOL OnDemand.

What is HP IDOL OnDemand?

IDOL OnDemand is a collection of web service APIs that expose a subset of the functionality offered by HP Autonomy. These APIs allow developers to write code that can "understand and engage with human information, including text, images, social media, and app data." Currently IDOL OnDemand offers more than 20 different APIs including sentiment analysis, image recognition, face detection and text indexing/searching. A full list of IDOL OnDemand APIs is available here: https://www.idolondemand.com/developer/apis. Despite the breadth of functionality available in IDOL OnDemand, there are definite differences between it and the on-premise HP IDOL version. You can read more about those differences here.

How do we connect Dynamics CRM and IDOL OnDemand?

Because all IDOL OnDemand APIs are RESTful web services that return responses as JSON-formatted messages, custom workflow activities or plug-ins can communicate with IDOL OnDemand via the System.Net.HttpWebRequest class, but first you need to sign up for an IDOL OnDemand developer account at https://www.idolondemand.com/signup.html. Once you sign up for a developer account, you'll be given an API key that grants access to run IDOL OnDemand APIs. I'll be showing detailed code examples in parts two and three of this series, but in the meantime I suggest you go ahead and take a look at the IDOL OnDemand getting started documentation.

That's all for today. In my next post, I'll show how to analyze inbound emails for customer sentiment. See you then!

A version of this post was originally published on the HP Enterprise Services Application Services blog.

When Microsoft Dynamics CRM 2011 was released, the on-premise installation included a set of PowerShell cmdlets for administering configuration and deployments. While these were incredibly powerful, the out-of-the-box cmdlets only worked on the same server that was running CRM. In CRM 2013, these cmdlets have been updated to run from remote systems, so you can use them to administer your on-premise CRM 2013 deployments without needing to be logged on to the actual application server. In this post I will show you how to set up your local system to run the CRM 2013 PowerShell cmdlets and then walk you through an example scenario.

Setting up your system

First, you need to get files that contain the Microsoft.Crm.PowerShell cmdlets. If you have access to the CRM 2013 install media, you can find them in the "\server\amd64\PFiles\MSCRM\Tools" directory. If don't have the install media handy, you can find them in the "\Program Files\Microsoft Dynamics CRM\tools" directory on your CRM application server. You'll need to copy three files to your local system. They are:

1. Microsoft.Crm.PowerShell.dll

#1. Load a local $setting object with the CRM server's "TeamSettings" values.
$setting = Get-Crmsetting -settingtype teamsettings -credential $mycred -dwsserverurl $dwsurl
#2. Print the contents of the $setting object value to the local console window.
$setting
#3. Update the MaxAutoCreatedAccessTeamsPerEntity attribute of the local $setting object to 5.
$setting.MaxAutoCreatedAccessTeamsPerEntity = 5
#4. Update the server TeamSettings values from the local $setting object.
Set-Crmsetting -Setting $setting -credential $mycred -dwsserverurl $dwsurl
#5. Print the CRM server's TeamSettings values to the local console window to make sure the change was successful.
Get-Crmsetting -settingtype teamsettings -credential $mycred -dwsserverurl $dwsurl

In my last post I discussed how key-value pair data can be used to store configuration-related items in Microsoft Dynamics CRM, and I also showed a design for an entity to store key-value pair data. In today's post I will show how to retrieve and consume the data inside a workflow using a custom workflow activity.

The Key-Value Pair entity

As I mentioned previously, I have a custom entity called Key-Value Pair (new_keyvaluepair) that stores the key in the name field (new_name), and it has the following custom fields to store value data:

1. String value (new_stringvalue)
2. Decimal value (new_decimalvalue)
3. Integer value (new_integervalue)
4. Date value (new_datevalue)

The custom workflow activity

I’ve created a custom workflow called GetKeyValue that takes the key name as an input parameter, and it returns all four value fields as output parameters. I would prefer to not have to return all the value fields, but because Dynamics CRM doesn't have a way to consume an output parameter with an object data type, that won't work.

Here are how the parameters are set up in code:

[Input("Key name")]

public InArgument<string> KeyName { get; set; }

[Output("String value")]

public OutArgument<string> StringValue { get; set; }

[Output("Integer value")]

public OutArgument<Int32> IntegerValue { get; set; }

[Output("Decimal value")]

public OutArgument<decimal> DecimalValue { get; set; }

[Output("Date value")]

public OutArgument<DateTime> DateValue { get; set; }

Because we're just doing a simple lookup on the entity name, I've chosen to use a CRM QueryExpression, but you could just as easily use FetchXML or Linq instead if you'd prefer. Here's the code that retrieves the key-value record:

try
{
	string keyName = KeyName.Get(executionContext);
	//look up team template by name
	QueryByAttribute querybyexpression = new QueryByAttribute("new\_keyvaluepair");
	querybyexpression.ColumnSet = new ColumnSet("new\_name",
		"new\_stringvalue",
		"new\_decimalvalue",
		"new\_integervalue",
		"new\_datevalue",
		"new\_valuetype"
		);
querybyexpression.Attributes.AddRange("new\_name");
	querybyexpression.Values.AddRange(keyName);
	EntityCollection retrieved = service.RetrieveMultiple(querybyexpression);
	//if we find something, we're set
	if (retrieved.Entities.Count > 0)
	{
		Entity kvp = retrieved.Entities[0];
		StringValue.Set(executionContext, (string)kvp["new\_stringvalue"]);
		IntegerValue.Set(executionContext, (int)kvp["new\_integervalue"]);
		DecimalValue.Set(executionContext, (decimal)kvp["new\_decimalvalue"]);
		DateValue.Set(executionContext, (DateTime)kvp["new\_datevalue"]);
	}
	else
	{
		//throw exception if unable to find a matching template
		throw new Exception("could not find key-value pair for: " + keyName);
	}
}

Although this example is focused on use in a workflow, you could use this custom workflow activity in a Dynamics CRM action process, or you could use the same business logic inside a plug-in. Full code for this post is available here.

How do you manage and consume data like this in your Dynamics CRM deployments? Does this approach look like it would be something worth using? Please share your thoughts in the comments!

A version of this post was originally published on the HP Enterprise Services Application Services blog.

Dynamics CRM workflows are a great way to enable business processes, and with the real-time capabilities introduced in CRM 2013 they can replace plug-ins in many scenarios. One significant drawback that workflows do have, though, is they lack the ability to easily retrieve and work with data from inside Dynamics CRM that is not related to their primary entities.

For example, let's say I have a workflow that creates a task if a contact's credit limit is greater than $5,000. In a completely custom software application, I would store this threshold value in some sort of configuration data store from which it could be retrieved at runtime, but Dynamics CRM doesn’t support that pattern out of the box. This requires that the $5,000 value be hardcoded in the workflow. If the credit limit threshold is reduced next month to $4,000, the workflow will need to be deactivated, then the value will need to be changed, and the workflow will need to be reactivated. Potentially more troubling, if this credit limit threshold value is used in multiple steps (or even multiple workflows), it's possible for it not to be updated correctly in all of them.

In this two-part series I will show how to create a solution for managing and consuming configuration data that uses a key-value pair data store in Dynamics CRM. In addition to solving workflow-specific issues, this basic approach could easily be leveraged in plug-ins, actions and other custom CRM-interfacing code.

Getting started

First, what exactly is a key-value pair? From the Wikipedia "attribute-value pair" entry:

A name–value pair, key–value pair, field–value pair or attribute–value pair is a fundamental data representation in computing systems and applications. Designers often desire an open-ended data structure that allows for future extension without modifying existing code or data. In such situations, all or part of the data model may be expressed as a collection of tuples <attribute name, value>; each element is an attribute–value pair.

Storing the data

To store key-value pair data in Dynamics CRM, all we need is a custom entity that stores the key in its name field and the value data in a value field. Because CRM doesn't have an "object" data type, we need to create a different value field for every possible data type we want to store. In this example, I have a custom entity called Key-Value Pair (new_keyvaluepair) that has the following custom fields to hold value data:

1. String value (new_stringvalue)
2. Decimal value (new_decimalvalue)
3. Integer value (new_integervalue)
4. Date value (new_datevalue)

Additionally, I have an optionset field called "Value type" (new_valuetype) that indicates what type of value the key represents. When the value type is selected, CRM business rules set the corresponding value field on the form to business required and the other fields to not required.

If I had selected a decimal type instead of a string, the decimal value field would be required instead of the string value field.

That's all for now. In my next post I will show how retrieve and consume the data inside a workflow using a custom workflow activity. See you then!

A version of this post was originally published on the HP Enterprise Services Application Services blog.

Dynamics CRM 2013 includes a great new feature called access teams, which makes ad-hoc sharing of records much easier than in previous versions. The basic idea is that an administrator can create one or more team templates for an entity that function sort of like security roles, but for a specific record. When a user is assigned rights on a record via a team template, if a corresponding access team doesn't already exist, CRM will create one on the fly.

While access teams are a great feature from a security perspective, they don't have the same flexibility as connections for representing different relationships between particular records and users. For example, if you have complex sales opportunities that require multiple users to work together on opportunity-specific sales teams in different roles (team lead, proposal writer, researcher, for example), creating specific connection roles and then creating connections between opportunities and users is the best way to represent those relationships in Dynamics CRM.

Unfortunately, if you use both connections and access teams, the out-of-the-box Dynamics CRM interface will require that each be managed separately. In this post, I will show how you can tie connections and access team membership together using workflows and custom workflow activities so that access team membership is granted and revoked when connections are created and deleted.

The approach

In this example, I have a custom entity called "Important Something" (new_importantsomething). I have created two team templates called "Important Something - Manager" and "Important Something - Member." I have also created two connection roles for Important Somethings and Users. These roles are also called "Important Something - Manager" and "Important Something - Member." We will be creating one real-time workflow that executes when a connection record is created and another real-time workflow that executes when a connection record is deleted. These workflows will check whether the "connected to" role is one of the new "important something" roles, and then they will pass the connection details and the role name to a custom workflow activity to handle the user's addition to or removal from the specific access team. Although a single custom workflow activity could be created to do either the addition or removal based on an input parameter flag, in this example we'll be using two separate ones called AssignUserToAccessTeamByName and RemoveUserFromAccessTeamByName.

The custom workflow activities

To add a user to an access team, the AssignUserToAccessTeamByName custom workflow activity will need to execute an AddUserToRecordTeamRequest via the organization web service. This message requires three input parameters:

1. The user id
2. The entity record id
3. The team template

Here are the input parameters for the custom workflow activity:

[Input("Connection")]
[ReferenceTarget("connection")]
public InArgument<EntityReference> Connection { get; set; }
[Input("Team Template name")]
public InArgument<string> TeamTemplateName { get; set; }

Here's the code that executes the business logic:

Guid connectionId = Connection.Get(executionContext).Id;
Entity connection = service.Retrieve("connection", connectionId, new ColumnSet("record1id", "record2id"));
EntityReference connectedFromId = (EntityReference)connection["record1id"];
EntityReference connectedToId = (EntityReference)connection["record2id"];
//only run this if the connection is to a user record
if (connectedToId.LogicalName.ToUpper() == "SYSTEMUSER")
{
	Guid teamTemplateId;
	string teamTemplateName = TeamTemplateName.Get(executionContext);
	//look up team template by name
	QueryByAttribute querybyexpression = new QueryByAttribute("teamtemplate");
	querybyexpression.ColumnSet = new ColumnSet("teamtemplatename", "teamtemplateid");
	querybyexpression.Attributes.AddRange("teamtemplatename");
	querybyexpression.Values.AddRange(teamTemplateName);
	EntityCollection retrieved = service.RetrieveMultiple(querybyexpression);
	//if we find something, we're set
	if (retrieved.Entities.Count > 0)
	{
		teamTemplateId = retrieved.Entities[0].Id;
	}
	else
	{
		//throw exception if unable to find a matching template
		throw new Exception("could not find team template named: " + teamTemplateName);
	}
	AddUserToRecordTeamRequest teamAddRequest = new AddUserToRecordTeamRequest();
	teamAddRequest.Record = connectedFromId;
	teamAddRequest.SystemUserId = connectedToId.Id;
	teamAddRequest.TeamTemplateId = teamTemplateId;
	AddUserToRecordTeamResponse response = (AddUserToRecordTeamResponse)service.Execute(teamAddRequest);
}

One thing to note is that a connection record in CRM is actually two separate records (the to/from records are reversed in each), so the workflow will actually fire twice. There's no real problem with the workflow firing twice, but just to reduce unnecessary processing, you'll note that there's a check to make sure the custom workflow activity business logic only executes when a user is the "to" record.

The RemoveUserFromAccessTeamByName custom workflow activity is almost identical to the AssignUserToAccessTeamByName activity, except it executes a RemoveUserFromRecordTeamRequest instead of an AddUserToRecordTeamRequest. The parameters for each method are the same. Full code for each method is available here.

The workflows

As mentioned earlier, the workflows for adding and removing access team members first check to see if the created or deleted connection has a particular connection role, and then they executes their corresponding custom workflow activity. Here's a screenshot of the "Add access team member from connection" workflow:

And here's a screenshot of the custom step input properties for the AssignUserToAccessTeamByName activity:

And that's it. Now you can manage access team membership and connections in a way to best represent relationships and provide the right level of data access to your users. Are you using access teams yet? If not, do you plan to? Let us know in the comments.

A version of this post was originally published on the HP Enterprise Services Application Services blog.

In my last post, I talked about what Dynamics CRM 2013 actions are and how I think they're of limited utility in enterprise deployments. I did suggest two scenarios in which I think actions could be useful, and I'm sure other folks may have come up with some ideas of their own. In this post I want to outline some technical considerations to keep in mind when using actions.

Security

First and foremost is security. An action executes in the context of the calling user, so the calling user has to have permission to execute each step in an action. Let's say an action creates a custom entity. Any user can call the action's custom message via the CRM organization web service, but if the user is not a member of a security role with create rights for that entity, an error will be returned. On one hand, this is useful because it keeps administrators from having to worry about who can execute actions. On the other hand, this is a limitation when actions are compared to workflows that can run in the security context of the workflow owner.

Testability

As those of you who read my posts on unit testing already know, automated unit testing is a subject near and dear to my heart. Automated unit testing of plug-ins and custom workflow activities is relatively easy. If business logic is moved from those to actions, it becomes much more difficult to test. In fact, I believe the only way to test actions using Visual Studio's unit testing or NUnit would be to export the XAML definition for an action and then set up a test similar to what I suggested for custom workflow activities.

Interface/interoperability design

Generally speaking, I avoid designing custom interfaces in which an external system interacts directly with the Dynamics CRM organization web service. I find that using a custom intermediate "proxy" service is usually a better approach for several reasons:

1. A custom proxy service allows for a more loosely coupled solution than when calling the organization web service directly.
2. A custom proxy service can execute complex business logic in the interface layer.
3. A custom proxy service supports a variety of authentication options.

Using actions, however, encourages the design of interfaces that rely directly on the organization web service. Also if actions are used for interfaces with external systems, the CRM administrator must consider the impact of potential downtime for editing actions. Like with standard workflows, actions must be deactivated before they can be edited. If custom code attempts to execute a deactivated action, an error message will be returned.

Wrapping it up

So, after thinking about how they can be used and technical considerations to keep in mind when using them, my initial feeling that actions aren't a great tool for enterprise Dynamics CRM 2013 implementations stands. Agree/disagree? Please share your thoughts in the comments.

A version of this post was originally published on the HP Enterprise Services Application Services blog.

I finally set up a personal Dynamics CRM 2013 sandbox a couple of weeks ago so I could start trying out some of its new features. Although I had been waiting for most of the Fall to get a look at real-time workflows, I was also intrigued by the new action process. After a few days of experimenting with actions, my early impression is that they're not terribly useful in enterprise Dynamics CRM implementations. In this post, I'll explain what exactly CRM actions are and how I think they might be useful. In my next post, I'll outline some technical considerations to keep in mind when using them.

What is a Dynamics CRM "action"?

According to the documentation included in the Dynamics CRM 2013 SDK:
You can extend the functionality of Microsoft Dynamics CRM by creating custom messages known as "actions." These actions will have associated request/response classes. Presently, actions are available to business applications and extensions through organization web service calls only. Actions are typically used to add new domain specific functionality to the organization web service or to combine multiple organization web service message requests into a single request. For example, in a support call center, you may want to combine the Create, Assign, and Setstate messages into a single new "Escalate" message.

Basically this means that an action is a real-time workflow that you can call via the CRM organization web service (and only via the CRM organization web service). Unlike a custom workflow activity, you cannot trigger an action from directly inside a workflow or a dialog. You can, however, write a custom workflow activity to trigger the action.

Although actions are essentially workflows, they do differ from actual workflows in a few ways. First, actions do support input and output parameters. Second, plug-ins can be registered to fire for actions just like with stock CRM messages. Finally, global actions can be created that don't correspond to any particular entity.

What's the point?

Based on everything I've read about actions, it seems the underlying rationale is to allow non-programmers to extend the core CRM platform using a variation on the workflow designer. Because the custom action messages will only ever be called from external integrations or custom code embedded in CRM, this seems to be of limited utility. That is to say, custom code is required to use an action, so if you're to that point, why not go ahead and put your business logic in code instead of trying to force it to live inside the CRM platform?

Potential applications

As I mentioned at the beginning of this post, I don't think actions will play a major role in enterprise deployments of Dynamics CRM 2013, but I can think of two potential uses for them:

1. Organizations that don't have programmers with a deep understanding of CRM functionality but do have knowledgeable super users and business analysts who can create actions for the programmers to simply "consume" in their integrating systems could leverage actions to deploy functionality more quickly. The ability for non-programmers to edit actions also allows for business processes to easily evolve over time.
2. An "empty" action could be used to trigger a plug-in in response to a particular custom message.

In my next post, I'll take a look at some technical considerations if you do decide to use actions. In the meantime, what do you think? Have you come up with some good uses for actions? Please let us know in the comments.

A version of this post was originally published on the HP Enterprise Services Application Services blog.