Earlier this week I showed an easy way to integrate a Node.js application with Dynamics 365 using the Web API. Building on that example, I have created a scheduled workflow runner using Node.js and Azure Functions. Here's how I did it.

First, I created a workflow in Dynamics 365 that creates a note on an account record. The screenshots below shows what it looks like:

Next, I wrote Node.js code to do the following in an Azure Function.

1. Request an OAuth token using a username and password.
2. Query the Dynamics 365 Web API for accounts with names that start with the letter "F."
3. Execute a workflow for each record that was retrieved in the previous step.

Most of this is regular Node.js, but there are a couple of nuances specific to Azure Functions. See the
"Azure Functions NodeJS developer reference" for more information.

var https = require('https');

//set these values to retrieve the oauth token
//see http://alexanderdevelopment.net/post/2016/11/23/dynamics-365-and-node-js-integration-using-the-web-api/ for more details
var _crmorg = 'https://CRMORG...dynamics.crom';  
var _clientid = 'OAUTH CLIENT ID';  
var _username = 'CRM USERNAME';  
var _userpassword = 'CRM PASSWORD';  
var _tokenendpoint = 'OAUTH TOKEN ENDPOINT FROM EARLIER';

//set these values to query your crm data
var _apipath = '/api/data/v8.2'; //web api version
var _workflowid = 'DC8519EC-F3CE-4BC9-BB79-DF2AD70217A1'; //guid for the workflow you want to execute
var _crmwebapihost = 'XXXX.api.crm.dynamics.com'; //crm api url (without https://)
var _crmwebapiquerypath = "/accounts?$select=name,accountid&$filter=startswith(name,'f')"; //web api query

var _counter = 0; //variable to keep track of how many records retrieved and workflows started

module.exports = function (context, myTimer) {
	//remove https from _tokenendpoint url
	_tokenendpoint = _tokenendpoint.toLowerCase().replace('https://','');

	//get the authorization endpoint host name
	var authhost = _tokenendpoint.split('/')[0];

	//get the authorization endpoint path
	var authpath = '/' + _tokenendpoint.split('/').slice(1).join('/');

	//build the authorization request
	var reqstring = 'client_id='+_clientid;
	reqstring+='&resource='+encodeURIComponent(_crmorg);
	reqstring+='&username='+encodeURIComponent(_username);
	reqstring+='&password='+encodeURIComponent(_userpassword);
	reqstring+='&grant_type=password';

	//set the token request parameters
	var tokenrequestoptions = {
		host: authhost,
		path: authpath,
		method: 'POST',
		headers: {
			'Content-Type': 'application/x-www-form-urlencoded',
			'Content-Length': Buffer.byteLength(reqstring)
		}
	};

	//make the token request
	context.log('starting token request');
	var tokenrequest = https.request(tokenrequestoptions, function(response) {
		//make an array to hold the response parts if we get multiple parts
		var responseparts = [];
		response.setEncoding('utf8');
		response.on('data', function(chunk) {
			//add each response chunk to the responseparts array for later
			responseparts.push(chunk);		
		});
		response.on('end', function(){
			//once we have all the response parts, concatenate the parts into a single string
			var completeresponse = responseparts.join('');
			//context.log('Response: ' + completeresponse);
			context.log('token response retrieved');
			
			//parse the response JSON
			var tokenresponse = JSON.parse(completeresponse);
			
			//extract the token
			var token = tokenresponse.access_token;
			//context.log(token);
			
			//pass the token to our data retrieval function
			getData(context, token);
		});
	});
	tokenrequest.on('error', function(e) {
		context.error(e);
		context.done();
	});

	//post the token request data
	tokenrequest.write(reqstring);

	//close the token request
	tokenrequest.end();
}

function getData(context, token){
	//set the web api request headers
	var requestheaders = { 
		'Authorization': 'Bearer ' + token,
		'OData-MaxVersion': '4.0',
		'OData-Version': '4.0',
		'Accept': 'application/json',
		'Content-Type': 'application/json; charset=utf-8',
		'Prefer': 'odata.maxpagesize=500',
		'Prefer': 'odata.include-annotations=OData.Community.Display.V1.FormattedValue'
	};
	
	//set the crm request parameters
	var crmrequestoptions = {
		host: _crmwebapihost,
		path: _apipath+_crmwebapiquerypath,
		method: 'GET',
		headers: requestheaders
	};
	
	//make the web api request
	context.log('starting data request');
	var crmrequest = https.request(crmrequestoptions, function(response) {
		//make an array to hold the response parts if we get multiple parts
		var responseparts = [];
		response.setEncoding('utf8');
		response.on('data', function(chunk) {
			//add each response chunk to the responseparts array for later
			responseparts.push(chunk);		
		});
		response.on('end', function(){
			//once we have all the response parts, concatenate the parts into a single string
			var completeresponse = responseparts.join('');
			
			//parse the response JSON
			var collection = JSON.parse(completeresponse).value;
			
			//set counter length = number of records
			_counter = collection.length;

			//loop through the results and call the workflow for each one
			collection.forEach(function (row, i) {
				callWorkflow(context, token, row['accountid']);
			});
		});
	});
	crmrequest.on('error', function(e) {
		context.error(e);
		context.done();
	});
	//close the web api request
	crmrequest.end();
}

function callWorkflow(context, token, entityid){
	var crmwebapiworkflowpath = _apipath + "/workflows("+_workflowid+")/Microsoft.Dynamics.CRM.ExecuteWorkflow";

	//set the web api request headers
	var requestheaders = { 
		'Authorization': 'Bearer ' + token,
		'OData-MaxVersion': '4.0',
		'OData-Version': '4.0',
		'Accept': 'application/json',
		'Content-Type': 'application/json; charset=utf-8'
	};
	
	//set the crm request parameters
	var crmrequestoptions = {
		host: _crmwebapihost,
		path: crmwebapiworkflowpath,
		method: 'POST',
		headers: requestheaders
	};

	//create an object to post to the executeworkflow action
	var reqobj = {};
	reqobj["EntityId"] = entityid;
	
	//turn it into a string
	var reqjson = JSON.stringify(reqobj);
	
	//calculate the length to set the content-length header
	crmrequestoptions.headers['Content-Length'] = Buffer.byteLength(reqjson);
	
	//make the web api request
	context.log('starting workflow request for ' + entityid);
	var crmrequest = https.request(crmrequestoptions, function(response) {
		//make an array to hold the response parts if we get multiple parts
		var responseparts = [];
		response.setEncoding('utf8');
		response.on('data', function(chunk) {
			//add each response chunk to the responseparts array for later
			responseparts.push(chunk);		
		});
		response.on('end', function(){
			//once we have all the response parts, concatenate the parts into a single string
			var completeresponse = responseparts.join('');
			context.log('success ' + entityid);
			
			//decrement the counter
			_counter = _counter-1;
			
			//if nothing is left to start, we are done
			if(_counter==0){
				context.log('all workflows started');
				context.done();
			}
		});
	});
	crmrequest.on('error', function(e) {
		context.error(e);
		context.done();
	});
	crmrequest.write(reqjson);

	//close the web api request
	crmrequest.end();
}

Then in the Azure Portal, I configured an Azure Function app to query accounts and execute the workflow every five minutes. Here are the detailed steps to replicate that.

1. Create a new Function app via New->Compute->Function App.
2. Set the app name, resource group, etc.
3. Once the new Function app is provisioned, open it.
4. Select "new function" on the left.
5. Set language to "JavaScript" and scenario to "Core." Find the "TimerTrigger-JavaScript" template and select it.
6. Give your function a name and set the schedule options. The schedule value is a CRON expression that includes six fields: {second} {minute} {hour} {day} {month} {day of the week}. You can accept the default value of every five minutes and change it later. Click "create" to create the new function.
7. Copy the Node.js code from above and paste it into the editor window. Set any specifics relative to your Dynamics 365 organization, and click save. (You can also use Git for deploying your code, but that's beyond the scope of today's post.)
8. On the "integrate" tab, you can modify the timer schedule. The schedule shown (0 */5 * * * *) will execute the function every five minutes.
9. The function will automatically execute at the next fifth minute, and the invocation log is available on the monitor tab. Selecting a specific invocation row shows detailed logging output on the right.
10. This screenshot shows the process sessions for when the workflow was executed in Dynamics 365.
11. This screenshot shows the note records that were created by the workflow.

A few notes/caveats:

1. My Node.js code has hardly any error handling right now. If the workflow execution call returns an error, the Node.js code will not recognize it as an error.
2. My CRM record retrieval is set to retrieve a maximum of 500 records. You would need to modify the Web API request logic to handle more.
3. Per the "Best Practices for Azure Functions" guide:

Assume your function could encounter an exception at any time. Design your functions with the ability to continue from a previous fail point during the next execution.

This means you should put logic in your workflow to make sure that duplicate executions are avoided (unless that's what you intend to happen).

This sample just scratches the surface of what's possible with Azure Functions and Dynamics 365, and I'm looking forward to working with Azure Functions more in the future. Have you looked at Azure Functions yet? What do you think? Please let me know in the comments.

I wrote a blog post in early 2015 that showed how to access the Dynamics CRM organization data service from a Node.js application. Today I will show an easy way to retrieve data from a Dynamics 365 Online organization in a Node.js application using the Web API.

Unlike the CRM organization service, the Dynamics 365 Web API does not allow you to authenticate directly with a user name and password. Instead you have to authenticate using OAuth to get a token, and then you pass that token to the Web API. Microsoft has created the "Windows Azure Active Directory Authentication Library (ADAL) for Node.js" that can be used to get an OAuth2 token, but in my sample today, I will be making the token request without using ADAL.

Before you begin, you need to make sure you have registered an application in Azure Active Directory that can access your Dynamics 365 online organization. Follow the instructions on this page to register a new Dynamics 365 application. Scroll down to the "Register an application with Microsoft Azure" section and make sure you register the application as a native client application instead of a web application.

After your application is registered, you need to find the endpoint where you can post an OAuth token request.

1. If you are using the classic Azure management portal, you should click the "develop applications" button in the "I want to" section. Then click the "View authentication and authorization endpoints" link. You should then see a list of various endpoints for your tenant. Copy the OAuth 2.0 token endpoint value.

2. If you are using the new Azure management portal, once you have your tenant selected in the AD management blade, select "app registrations" on the left and "endpoints" on the top. You should then see your tenant's endpoints to the right. Copy the OAuth 2.0 token endpoint value.

The OAuth token endpoint should look like this https://login.windows.net/SOME_GUID_VALUE/oauth2/token.

Once you have your OAuth token endpoint and your application client id, you can prepare a client application. Here's a sample Node.js application I wrote to retrieve contacts from the Web API and display their names.

'use strict';
var https = require('https');

//set these values to retrieve the oauth token
var crmorg = 'https://CRMORG...dynamics.com';
var clientid = 'CLIENT ID FROM EARLIER';
var username = 'CRM USERNAME';
var userpassword = 'CRM PASSWORD';
var tokenendpoint = 'OAUTH TOKEN ENDPOINT FROM EARLIER';

//set these values to query your crm data
var crmwebapihost = 'CRMORG.api.crm.dynamics.com';
var crmwebapipath = '/api/data/v8.2/contacts?$select=fullname,contactid'; //basic query to select contacts

//remove https from tokenendpoint url
tokenendpoint = tokenendpoint.toLowerCase().replace('https://','');

//get the authorization endpoint host name
var authhost = tokenendpoint.split('/')[0];

//get the authorization endpoint path
var authpath = '/' + tokenendpoint.split('/').slice(1).join('/');

//build the authorization request
//if you want to learn more about how tokens work, see IETF RFC 6749 - https://tools.ietf.org/html/rfc6749
var reqstring = 'client_id='+clientid;
reqstring+='&resource='+encodeURIComponent(crmorg);
reqstring+='&username='+encodeURIComponent(username);
reqstring+='&password='+encodeURIComponent(userpassword);
reqstring+='&grant_type=password';

//set the token request parameters
var tokenrequestoptions = {
	host: authhost,
	path: authpath,
	method: 'POST',
	headers: {
		'Content-Type': 'application/x-www-form-urlencoded',
		'Content-Length': Buffer.byteLength(reqstring)
	}
};

//make the token request
var tokenrequest = https.request(tokenrequestoptions, function(response) {
	//make an array to hold the response parts if we get multiple parts
	var responseparts = [];
	response.setEncoding('utf8');
	response.on('data', function(chunk) {
		//add each response chunk to the responseparts array for later
		responseparts.push(chunk);		
	});
	response.on('end', function(){
		//once we have all the response parts, concatenate the parts into a single string
		var completeresponse = responseparts.join('');
		//console.log('Response: ' + completeresponse);
		console.log('Token response retrieved . . . ');
		
		//parse the response JSON
		var tokenresponse = JSON.parse(completeresponse);
		
		//extract the token
		var token = tokenresponse.access_token;
		
		//pass the token to our data retrieval function
		getData(token);
	});
});
tokenrequest.on('error', function(e) {
	console.error(e);
});

//post the token request data
tokenrequest.write(reqstring);

//close the token request
tokenrequest.end();


function getData(token){
	//set the web api request headers
	var requestheaders = { 
		'Authorization': 'Bearer ' + token,
		'OData-MaxVersion': '4.0',
		'OData-Version': '4.0',
		'Accept': 'application/json',
		'Content-Type': 'application/json; charset=utf-8',
		'Prefer': 'odata.maxpagesize=500',
		'Prefer': 'odata.include-annotations=OData.Community.Display.V1.FormattedValue'
	};
	
	//set the crm request parameters
	var crmrequestoptions = {
		host: crmwebapihost,
		path: crmwebapipath,
		method: 'GET',
		headers: requestheaders
	};
	
	//make the web api request
	var crmrequest = https.request(crmrequestoptions, function(response) {
		//make an array to hold the response parts if we get multiple parts
		var responseparts = [];
		response.setEncoding('utf8');
		response.on('data', function(chunk) {
			//add each response chunk to the responseparts array for later
			responseparts.push(chunk);		
		});
		response.on('end', function(){
			//once we have all the response parts, concatenate the parts into a single string
			var completeresponse = responseparts.join('');
			
			//parse the response JSON
			var collection = JSON.parse(completeresponse).value;
			
			//loop through the results and write out the fullname
			collection.forEach(function (row, i) {
				console.log(row['fullname']);
			});
		});
	});
	crmrequest.on('error', function(e) {
		console.error(e);
	});
	//close the web api request
	crmrequest.end();
}

When I run this from my local PC against a my Dynamics 365 org with sample data installed, I get this output:

Although my sample application isn't fancy, it shows that authenticating to Dynamics 365 and retrieving data without requiring special libraries is now much easier than it used to be in the pre-CRM 2016 days, and that is very exciting.

What do you think? Please let me know your thoughts in the comments.

This is the fifth and final post in a five-part series on how I integrated a Raspberry Pi with Microsoft Dynamics CRM to recognize contacts using automobile license plates. Although the code samples are focused on license plate recognition, the solution architecture I used is applicable to any Dynamics CRM + Internet of Things (IoT) integration. In my previous post, I showed how to execute the license plate recognition and contact search with JavaScript directly in the web resource. Today I will show how to set up a streaming interface so the Raspberry Pi can take a picture, parse the plate number and trigger the web resource to search for and display a contact without any input from the end user.

The approach

As I described in part 1 of this series, in this approach the Raspberry Pi takes a picture, parses the plate number and writes it to a streaming interface using Socket.IO. A web page or client application picks up the plate numbers from that interface, and then it queries CRM for a contact with the returned license plate number to display the details to the user. Essentially this is just a variation on what I described in my "Creating a near real-time streaming interface for Dynamics CRM with Node.js" series in late 2014.

Node.js code

In part 2 I showed the complete Node.js code to support all the scenarios in this series, but I did not discuss the streaming interface. Basically the streaming interface behaves almost exactly the same as the non-streaming interface except instead of writing the JSON result object in the HTTP response, it posts the JSON result object to a Socket.IO interface.

app.get('/check_plate_stream', function (req, res) {
	//generate a guid to use in the captured image file name
	var uuid1 = uuid.v1();
	
	//tell the webcam to take a picture and store it in the captures directory using the guid as the name
	exec('fswebcam -r 1280x720 --no-banner --quiet ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});
	
	//now that we have a picture saved, execute parse it with openalpr and return the results as json (the -j switch) 
	exec('alpr -j ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		//create a json object based on the alpr output
		var plateOutput = JSON.parse(stdout.toString());
		
		//add an "image" attribute to the alpr json that has a path to the captured image
		//this is so the client can view the license plage picture to verify alpr parsed it correctly
		plateOutput.image = '/captures/' + uuid1 + '.jpg';

		//write the json to the socket.io interface
		io.emit('message', plateOutput);

		//return a response to the caller that the message was sent
		res.send('message sent');

		//log the response from alpr
		console.log('alpr response: ' + stdout.toString());
		
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});
});

The triggering mechanism is still a web route, so it can be called in a number of different ways without having to modify the base code. I've written a separate Node.js application that uses an HC-SR04 ultrasonic rangefinder to detect when a license plate moves into view and then call the streaming interface URL to trigger the license plate capture and recognition. The motion detection script is available on GitHub here.

I am running the motion detection script on the same Raspberry Pi as the webcam, but it could easily be run on a separate piece of hardware, too. You could also use the same approach to connect it to any sort of other sensor or input.

Here is a picture of my motion detection rig with my unimpressed Great Dane behind it for scale.

The web resource

The web resource loads the Socket.IO library from a CDN.
<script src="https://cdn.socket.io/socket.io-1.2.0.js"></script>

The web resource then connects to the streaming interface and listens for a message. Once it picks up a license plate number from the streaming interface, it then queries CRM to find a contact just like in part 4.

var piRootPath = "http://192.168.1.112:3000";
var socket = io("http://192.168.1.112:3000");

socket.on('message', function(resultObj){
$("#outputdiv").text("");
if(resultObj.results.length > 0) {
	var plateNum = resultObj.results[0].plate;
	var imgUrl = resultObj.image;
	$("#outputdiv").append("Detected plate number: " + plateNum + "
");
	
	$("#outputdiv").append("<img src='" + piRootPath + imgUrl+ "' width='400' />");
	
	var oDataURI = Xrm.Page.context.getClientUrl()
	+ "/XRMServices/2011/OrganizationData.svc/"
	+ "ContactSet?$select=ContactId,FullName&$filter=lpa_Platenumber eq '" + plateNum +"'";
	
	var req = new XMLHttpRequest();
	req.open("GET", encodeURI(oDataURI), true);
	req.setRequestHeader("Accept", "application/json");
	//req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
	req.onreadystatechange = function () {
		if (this.readyState == 4 /* complete */) {
			req.onreadystatechange = null; //avoids memory leaks
			if (this.status == 200) {
				successCrmCallback(JSON.parse(this.responseText).d.results);
			}
			else {
				errorCallback();
			}
		}
	};
	req.send();
}
else {
	$("#outputdiv").append("No plate detected
");
}
});

If a matching contact is found, it's displayed. Otherwise a failure message is displayed instead.

function successCrmCallback(contacts) {
	if(contacts.length > 0) {
		var contactUrl = Xrm.Page.context.getClientUrl() + "/main.aspx?etc=2&extraqs=&pagetype=entityrecord&id=%7b" + contacts[0].ContactId + "%7d";
		$("#outputdiv").prepend("Contact: <a href='" + contactUrl + "' target='_blank'>" + contacts[0].FullName + "</a><br />");	
	}
	else {
		//otherwise display a message that no contact could be found
		$("#outputdiv").prepend("No contact found
");
	}
	$("#checkButton").prop('disabled', false);
}

The web resource (lpa_checkplatestream.htm) is included in my sample CRM solution along with the contact entity configured to store the license plate number. The sample CRM solution is available in my GitHub repository here.

Demo

Here's the CRM web resource open a new tab. Note there's no button to trigger the plate capture and recognition.

This is the web page used to trigger the plate capture and recognition opened in Chrome.
When using my motion detection script, this page is never shown to the end user.

Finally here is the web resource once it gets the message from the stream and looks up the contact details. If the plate recognition is triggered again, the page will update itself.

Wrapping up

I hope you've enjoyed reading this series as much as I've enjoyed writing it. Through the process of working out the various scenarios I've certainly learned a lot about how the Raspberry Pi can be combined with Dynamics CRM to support novel business processes.

Here are links to all the previous posts in this series.

1. Part 1 - Series introduction
2. Part 2 - Node.js application
3. Part 3 - CRM custom assembly trigger
4. Part 4 - JavaScript in CRM web resource trigger

Do you have plans to integrate your Dynamics CRM system with the Internet of Things? If so, how? Let us know in the comments!

This is the fourth post in a five-part series on how I integrated a Raspberry Pi with Microsoft Dynamics CRM to recognize contacts using automobile license plates. Although the code samples are focused on license plate recognition, the solution architecture I used is applicable to any Dynamics CRM + Internet of Things (IoT) integration. In my previous post, I showed how to trigger the license plate recognition process and then use the extracted license plate number to find a contact in my Dynamics CRM organization with a custom workflow activity. Today I'll show how to execute the license plate recognition and contact search with JavaScript directly in the web resource.

The approach

As I described in part 1 of this series, this approach uses JavaScript to call the Raspberry Pi to take a picture and return the parsed license plate number. Once a license plate number is retrieved, the JavaScript code then queries CRM for a contact with the returned license plate number and displays its details to the user. As long as the CRM end user's computer can access the Raspberry Pi, it doesn't matter if the Pi is visible to the CRM server, so this easily works with CRM Online.

The web resource

A web resource is used so the user can interactively trigger the license plate recognition and open the contact record if a match is found. The web resource also displays the image that is captured by the Raspberry Pi so the user can validate that the license plate number extracted by OpenALPR matches the actual license plate number.

Executing the license plate recognition on the Raspberry Pi just requires making a GET request to the Node.js web page described in part 2 and then parsing the JSON response.

//command to start checklplate action call when button is pushed  
function executeCheckplate() { 
	$("#outputdiv").text("");
	$("#checkButton").prop('disabled', true);
	var checkplateURI = piRootPath + "/check_plate";
    var req = new XMLHttpRequest();
    req.open("GET", encodeURI(checkplateURI), true);
    req.setRequestHeader("Accept", "application/json");
    //req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
    req.onreadystatechange = function () {
        //debugger;
        if (this.readyState == 4 /* complete */) {
            req.onreadystatechange = null; //avoids memory leaks
            if (this.status == 200) {
                successPlateCallback(JSON.parse(this.responseText));
            }
            else {
                errorCallback();
            }
        }
    };
    req.send();
}

Once the response is returned from the Raspberry Pi, the web resource then queries CRM to find a contact, unless no plate was detected, in which case it displays a failure message.

function successPlateCallback(resultObj) {
	if(resultObj.results.length > 0) {
		var plateNum = resultObj.results[0].plate;
		var imgUrl = resultObj.image;
		$("#outputdiv").append("Detected plate number: " + plateNum + "
");
		
		//show the captured plate image
		$("#outputdiv").append("<img src='" + piRootPath + imgUrl+ "' width='400' />");
		
		var oDataURI = Xrm.Page.context.getClientUrl()
        + "/XRMServices/2011/OrganizationData.svc/"
        + "ContactSet?$select=ContactId,FullName&$filter=lpa_Platenumber eq '" + plateNum +"'";
		
		var req = new XMLHttpRequest();
		req.open("GET", encodeURI(oDataURI), true);
		req.setRequestHeader("Accept", "application/json");
		//req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
		req.onreadystatechange = function () {
			if (this.readyState == 4 /* complete */) {
				req.onreadystatechange = null; //avoids memory leaks
				if (this.status == 200) {
					successCrmCallback(JSON.parse(this.responseText).d.results);
				}
				else {
					errorCallback();
				}
			}
		};
		req.send();
	}
	else {
		$("#outputdiv").append("No plate detected
");
		$("#checkButton").prop('disabled', false);
	}
}

If a matching contact is found, it's displayed. Otherwise a failure message is displayed instead.

function successCrmCallback(contacts) {
	if(contacts.length > 0) {
		var contactUrl = Xrm.Page.context.getClientUrl() + "/main.aspx?etc=2&extraqs=&pagetype=entityrecord&id=%7b" + contacts[0].ContactId + "%7d";
		$("#outputdiv").prepend("Contact: " + contacts[0].FullName + "
");	
	}
	else {
		//otherwise display a message that no contact could be found
		$("#outputdiv").prepend("No contact found
");
	}
	$("#checkButton").prop('disabled', false);
}

The web resource (lpa_checkplatejs.htm) is included in my sample CRM solution along with the contact entity configured to store the license plate number. The sample CRM solution is available in my GitHub repository here.

Demo

Here's the web resource open a new tab.

Here's the result after I click the "check plate" button. The contact name is a hyperlink that will open the contact record in a new window.

That's it for today. In my next and final post in this series, I'll show how to set up a streaming interface so the Raspberry Pi can take a picture and parse the plate number, which will then trigger the web resource to search for and display a contact without any input from the end user.

This is the third post in a five-part series on how I integrated a Raspberry Pi with Microsoft Dynamics CRM to recognize contacts using automobile license plates. Although the code samples are focused on license plate recognition, the solution architecture I used is applicable to any Dynamics CRM + Internet of Things (IoT) integration. In my previous post, I showed how I set up my Raspberry Pi to capture images and parse them for license plate numbers. In today's post, I will show how to trigger the license plate recognition process and then use the extracted license plate number to find a contact in my Dynamics CRM organization with a custom workflow activity.

The approach

As I described in part 1 of this series, this approach uses a web resource, a dialog or some other interactive mechanism to call a custom workflow activity that instructs the Raspberry Pi to take a picture and return the parsed license plate number. The code hosted in CRM then searches for a contact with the returned license plate number and displays its details to the user. This requires that the CRM server be able to communicate with the Raspberry Pi, which may be challenging for CRM Online deployments.

Today I'll show how to call the custom workflow activity from a web resource, which will require the use of a custom CRM action so that the web resource can execute the functionality with a JavaScript call.

The custom workflow assembly

Interacting with the Node.js web page just requires making a GET request and then parsing the JSON response, so the approach to working with JSON data in custom workflow assemblies that I've used in several other posts will work great for this.

There are only a few changes required to that sample:

1. Modify the JSON response classes to match the JSON object returned by the Node.js application.
2. Modify the web request to be a GET instead of a POST.
3. Add logic to search for contacts by license plate number and return the contact id as a string.
4. Update the input/output parameters to return the contact, license plate and image details.

The code for the custom workflow assembly is available in my Crm-Sample-Code repository on GitHub here

One thing to keep in mind is that because I wanted to register the assembly in isolation, I had to create a hosts entry for my Raspberry Pi on my CRM application server since sandboxed assemblies cannot make web requests to IP address URLs. Alternatively I could have created an entry on my LAN DNS server.

The custom CRM action

A custom CRM action is used to wrap the workflow assembly so that it can be called from a web resource via JavaScript. The action simply passes a request to the workflow assembly and returns its response to the client.

The web resource

Finally a web resource is used so the user can interactively trigger the license plate recognition and open the contact record if a match is found. The web resource also displays the image that is captured by the Raspberry Pi so the user can validate that the license plate number extracted by OpenALPR matches the actual license plate number.

The web resource (lpa_checkplate.htm) is included in my sample CRM solution along with the custom action, compiled plugin and contact entity configured to store the license plate number. The sample CRM solution is available in my GitHub repository here.

Demo

Here's the web resource open a new tab.

Here's the result after I click the "check plate" button. The contact name is a hyperlink that will open the contact record in a new window.

That's it for today. In my next post, I'll show how to execute the license plate recognition and contact search with JavaScript directly in the web resource.

This is the second post in a five-part series on how I integrated a Raspberry Pi with Microsoft Dynamics CRM to recognize contacts using automobile license plates. As I mentioned in the first post of the series, the solution architecture I used is applicable to any Dynamics CRM + Internet of Things (IoT) integration. In today's post I will show how I set up my Raspberry Pi to handle the basic license plate capture and parsing operations.

Tooling

For this demonstration I am using the following tools:

1. Raspberry Pi 2 Model B running Raspbian (Any Linux distribution that runs on the Raspberry Pi should work with the code I'm showing, but the configuration steps later might be different.)
2. Logitech HD Webcam C615 to take photos
3. OpenALPR to recognize license plates
4. Node.js to provide a web-based interface to OpenALPR (and post to Socket.IO in the streaming interface)

OpenALPR and Node.js both run on Windows, so I think it should be possible to create a comparable solution using Windows 10 for IoT on a Raspberry Pi 2. Also, if you don't have a Pi or comparable IoT device, you can try this out on any system where you can run the software.

Basic Raspberry Pi configuration

Configuring the Raspberry Pi is beyond the scope of today's post, but as long as you have a Raspberry Pi running Raspbian with network access you should be good to go. My Pi is on my LAN with an IP address of 192.168.1.112, and all ports are open.

Camera

I am using a Logitech HD Webcam C615 because I just happened to have one available. Theoretically any Raspberry Pi-compatible webcam or the dedicated Raspberry Pi camera module should work. I am using the fswebcam package to interact with my webcam, and I followed the instructions here to get it working. As you'll see from the captured image at the end of this post, the quality of the images I'm capturing leaves something to be desired, but things seem to be working well enough that I haven't explored different configuration options to improve the quality.

OpenALPR

OpenALPR is the tool that parses images to find license plate numbers. You can download it from GitHub, and follow the directions in the "Easy Way" section here to build and install it. I also should be possible to use Docker as described here, but I haven't tried it myself.

Once you have OpenALPR installed, you can test that it's working using sample images like so:

wget http://plates.openalpr.com/ea7the.jpg
alpr -c us ea7the.jpg

wget http://plates.openalpr.com/h786poj.jpg
alpr -c eu h786poj.jpg

OpenALPR can also be run as a daemon that continually checks a camera stream and outputs detected license plates, but I chose not to use it in this case because the open source version never stops. If you put a license plate in front of the webcam, the open source OpenALPR daemon will just keep returning the parsed license plate number over and over again. I believe the commercial version includes a motion detector feature, but to put together this sample on the cheap, I didn't explore it.

Node.js

Having put together a few proof-of-concept interfaces using Node.js in the past, it was the first thing that came to mind to create a web-based interface to OpenALPR. You could use a variety of other options like Python, Perl, PHP or C# if you prefer, but Node.js made setting up this part of the sample extremely easy.

First you need to make sure Node.js is installed:

sudo apt-get install nodejs

Then you need to install the following modules with npm:

1. node-uuid
2. express
3. socket.io

Node.js code

Here is the complete Node.js code to support all the scenarios in this series:

var http = require('http');
var express = require('express'),
    app = module.exports.app = express();
var server = http.createServer(app);
var io = require('socket.io').listen(server, {log:false, origins:'*:*'})
var uuid = require('node-uuid');
var sys = require('sys'),
    exec = require('child_process').exec;

//allow clients to directly view the images in the captures directory
app.use('/captures', express.static('captures'));

//route for the home page
app.get('/', function (req, res) {
	res.send('home page');
});

//route to handle a client calling node to check a plage
app.get('/check_plate', function (req, res) {
	//generate a guid to use in the captured image file name
	var uuid1 = uuid.v1();
	
	//tell the webcam to take a picture and store it in the captures directory using the guid as the name
	exec('fswebcam -r 1280x720 --no-banner --quiet ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});

	//now that we have a picture saved, execute parse it with openalpr and return the results as json (the -j switch) 
	exec('alpr -j ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		//create a json object based on the alpr output
		var plateOutput = JSON.parse(stdout.toString());
		
		//add an "image" attribute to the alpr json that has a path to the captured image
		//this is so the client can view the license plage picture to verify alpr parsed it correctly
		plateOutput.image = '/captures/' + uuid1 + '.jpg';
		
		//set some headers to deal with CORS
		res.header("Access-Control-Allow-Origin", "*");
		res.header("Access-Control-Allow-Headers", "X-Requested-With");
		
		//send the json back to the client
		res.json(plateOutput);
		
		//log the response from alpr
		console.log('alpr response: ' + stdout.toString());
		
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});
});

//route to handle a request for a license plate capture to be written to a socket.io interface
//basically the same as the non-streaming interface except the output gets written somewhere different
app.get('/check_plate_stream', function (req, res) {
	//generate a guid to use in the captured image file name
	var uuid1 = uuid.v1();
	
	//tell the webcam to take a picture and store it in the captures directory using the guid as the name
	exec('fswebcam -r 1280x720 --no-banner --quiet ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});
	
	//now that we have a picture saved, execute parse it with openalpr and return the results as json (the -j switch) 
	exec('alpr -j ./captures/' + uuid1 + '.jpg',
	  function (error, stdout, stderr) {
		//create a json object based on the alpr output
		var plateOutput = JSON.parse(stdout.toString());
		
		//add an "image" attribute to the alpr json that has a path to the captured image
		//this is so the client can view the license plage picture to verify alpr parsed it correctly
		plateOutput.image = '/captures/' + uuid1 + '.jpg';

		//write the json to the socket.io interface
		io.emit('message', plateOutput);

		//return a response to the caller that the message was sent
		res.send('message sent');

		//log the response from alpr
		console.log('alpr response: ' + stdout.toString());
		
		if (error !== null) {
		  //log any errors
		  console.log('exec error: ' + error);
		}
	});
});

//start the server listening on port 3000
server.listen(3000, function () {
	console.log('App listening');
});

If you look at the "check_plate" route starting at line 19, you can see the script does the following things:

1. Generate a new GUID to use in the captured image name.
2. Take a picture with the webcam and save it to the "captures" directory.
3. Execute OpenALPR to parse the image and return the results in a JSON object.
4. Modify the JSON object to include the image path
5. Return the JSON object to the client.

Trying it out

To try out the code, do the following:

1. Save the Node.js script from above as app.js.
2. Upload it to a directory on your Pi.
3. Create a directory called "captures" under that directory.
4. Start the application using the following command: nodejs app.js.
5. Navigate to the URL for the Node.js application from a web browser.

Here's a picture of my testing "studio." The Pi and webcam are sitting on a TV tray in front of an old license plate propped up on a couch in my office.

When I call Node.js from my browser, this is what I see.

This is the JSON response formatted for easier reading.

{
	"version":2,
	"data_type":"alpr_results",
	"epoch_time":1450713975002,
	"img_width":1280,
	"img_height":720,
	"processing_time_ms":2567.216553,
	"regions_of_interest":[],
	"results":[
	{
		"plate":"43C32Y3",
		"confidence":91.097946,
		"matches_template":0,
		"plate_index":0,
		"region":"",
		"region_confidence":0,
		"processing_time_ms":269.342682,
		"requested_topn":10,
		"coordinates":[
		{
			"x":414,
			"y":315
		},
		{
			"x":812,
			"y":319
		},
		{
			"x":812,
			"y":516
		},
		{
			"x":414,
			"y":511
		}],
		"candidates":[
		{
			"plate":"43C32Y3",
			"confidence":91.097946,
			"matches_template":0
		},
		{
			"plate":"43G32Y3",
			"confidence":81.515587,
			"matches_template":0
		},
		{
			"plate":"43C3ZY3",
			"confidence":81.408203,
			"matches_template":0
		},
		{
			"plate":"43C32YS",
			"confidence":80.856506,
			"matches_template":0
		},
		{
			"plate":"43C32Y",
			"confidence":79.70826,
			"matches_template":0
		},
		{
			"plate":"43G3ZY3",
			"confidence":71.825851,
			"matches_template":0
		},
		{
			"plate":"43G32YS",
			"confidence":71.274155,
			"matches_template":0
		},
		{
			"plate":"43C3ZYS",
			"confidence":71.166771,
			"matches_template":0
		},
		{
			"plate":"43G32Y",
			"confidence":70.1259,
			"matches_template":0
		},
		{
			"plate":"43C3ZY",
			"confidence":70.018524,
			"matches_template":0
		}]
	}],
	"image":"/captures/be8da820-a7fc-11e5-a63a-7bb250f23f1c.jpg"
}

Here is the Node.js output from the Raspberry Pi command line.

This is the actual image the webcam captured. The white balance is horrible, but the plate number is clear enough for OpenALPR to recognize.

That's it for now. In my next post, I'll show how to trigger the license plate recognition functionality from a custom assembly in Dynamics CRM.

Today's post is the first in a five-part series on how I integrated a Raspberry Pi with Microsoft Dynamics CRM to recognize contacts using automobile license plates. Although my solution is focused on the use of license plate numbers captured by a webcam, the solution architecture is applicable to any Dynamics CRM + Internet of Things (IoT) integration. Over the course of this series, I will show how I configured my Raspberry Pi and how I built different integrations to use the license plate data in Dynamics CRM.

Background

Last year I was working on a Dynamics CRM project for one of the largest automakers in the world, and I got to thinking about whether it'd be possible to integrate license plate recognition with our CRM system. This would have given dealers a tool so that service advisers could immediately see customer details and service preferences as soon as a car drove into a service bay. My idea never went anywhere, and eventually I moved on to a different company, but I'd still think about it every once in a while.

Then I saw an article last week about open-source license plate reader software called OpenALPR that got me thinking about this again. Because I'd just gotten a Raspberry Pi 2, and I had an old webcam that was just gathering dust in my office, I finally had everything I needed to build a Dynamics CRM license plate reader integration.

The approach

Thinking about this from the perspective of a CRM user who wants to be able to recognize a contact based on a license plate, there are a few obvious elements required:

1. Camera to capture a license plate image
2. Software to parse the license plate number from image (OpenALPR)
3. Code to trigger the license plate number parsing and return results to a consumer
4. Field to store license plate numbers in CRM
5. Code to retrieve and display the CRM contact details

The right way to put these together is less obvious because there are several possible approaches, but none are appropriate in all scenarios. For example, if the CRM user is going to trigger the license plate recognition in CRM, there are at least three potential approaches:

1. CRM custom assembly - Using a web resource, a dialog or some other interactive mechanism, a custom workflow activity or plug-in is called that instructs the Raspberry Pi to take a picture and return the parsed license plate number. The code hosted in CRM then searches for a contact with the returned license plate number and displays its details to the user. This approach requires that the CRM server be able to communicate with the Raspberry Pi, which may be challenging for CRM Online deployments.
2. JavaScript in web resource - Using a web resource, JavaScript is called that instructs the Raspberry Pi to take a picture and return the parsed license plate number. Once a license plate number is retrieved, the JavaScript code then queries CRM for a contact with the returned license plate number and displays its details to the user. As long as the CRM end user's computer can access the Raspberry Pi, it doesn't matter if the Pi is visible to the CRM server, so this easily works with CRM Online.
3. Business logic on the Raspberry Pi - Using a web resource, JavaScript is called that instructs the Raspberry Pi to take a picture and parse the license plate number. Once a license plate number is retrieved, the Raspberry Pi then queries CRM for a contact with the returned license plate number and returns its details to the user. I don't love this approach because it requires extra effort to get the Pi to communicate with CRM, and I prefer to keep the Pi as "dumb" as possible.

If the license plate recognition is triggered via camera motion detection, a physical button or a sensor without direct input from the CRM user, there are at least two potential approaches:

1. Streaming interface - The Raspberry Pi takes a picture, parses the plate number and writes it to a streaming interface using Socket.IO or a similar mechanism. A web page or client application picks up the plate numbers from that interface, and then it queries CRM for a contact with the returned license plate number to display the details to the user. This approach is basically a variation on what I described in my "Creating a near real-time streaming interface for Dynamics CRM with Node.js" series last year.
2. Back-end data post - The Raspberry Pi takes a picture, parses the plate number and posts it to CRM. The data can be posted directly to CRM or use a message queue. This approach is good if a CRM user doesn't need immediate access to the data.

In this series I will show how I built solutions that demonstrate three of the approaches above:

1. CRM custom assembly
2. JavaScript in web resource
3. Streaming interface

As for why I'm not showing the other approaches:

1. I just don't think the business logic on the Raspberry Pi approach is useful here. I'm sure there are times it might make sense, but my hypothetical scenario here isn't one of them.
2. The back-end data post approach is almost the same as the streaming interface, except the Pi posts the data to CRM instead of Socket.IO.

In my next post, I'll show how I set up my Raspberry Pi to handle the basic license plate capture and parsing operations. See you then!

This the final post in my five-part series on creating loosely coupled data interfaces for Dynamics CRM using RabbitMQ. In part 3 and part 4 I showed two approaches for building a Dynamics CRM plug-in that publishes notification messages to a RabbitMQ exchange. In today’s post I will show how to create a Windows console application that reads messages from a queue and writes the data to Dynamics CRM. The code for this application is available on GitHub in the LeadWriterSample project under the LucasCrmMessageQueueTools solution.

The approach

This application is extraordinarily simple. On startup it prompts the user to supply connection information for the RabbitMQ queue that it will monitor as well as a Dynamics CRM connection string. It then monitors the queue for new JSON-formatted messages. When new messages arrive, it attempts to deserialize them into a lightweight "leadtype" object, and then it creates new lead records in CRM. Once a message is successfully processed and a lead is created, the application then sends a confirmation back to RabbitMQ so that the message can be removed from the queue.

The following code shows what happens after a connection to the RabbitMQ is established:

//wait for some messages

var consumer = new QueueingBasicConsumer(channel);

channel.BasicConsume(_queue, false, consumer);

 

Console.WriteLine(" [*] Waiting for messages. To exit press CTRL+C");

 

//instantiate crm org service

using (OrganizationService service = new OrganizationService(_targetConn))

{

   while (true)

   {

     //get the message from the queue

     var ea = (BasicDeliverEventArgs)consumer.Queue.Dequeue();

 

     var body = ea.Body;

     var message = Encoding.UTF8.GetString(body);

 

     try

     {

       //deserialize message json to object

       LeadType lead = JsonConvert.DeserializeObject<LeadType>(message);

 

       try

       {

         //create record in crm

         Entity entity = new Entity("lead");

         entity["firstname"] = lead.FirstName;

         entity["lastname"] = lead.LastName;

         entity["subject"] = lead.Topic;

         entity["companyname"] = lead.Company;

         service.Create(entity);

 

         //write success message to cli

         Console.WriteLine("Created lead: {0} {1}", lead.FirstName, lead.LastName);

 

         //IMPORTANT - tell the queue the message was processed successfully so it doesn't get requeued

         channel.BasicAck(ea.DeliveryTag, false);

       }

       catch (FaultException<Microsoft.Xrm.Sdk.OrganizationServiceFault> ex)

       {

         //return error - note no confirmation is sent to the queue, so the message will be requeued

         Console.WriteLine("Could not create lead: {0} {1}", lead.FirstName, lead.LastName);

         Console.WriteLine("Error: {0}", ex.Message);

       }

     }

     catch(Exception ex)

     {

       //return error - note no confirmation is sent to the queue, so the message will be requeued

       Console.WriteLine("Could not process message from queue");

       Console.WriteLine("Error: {0}", ex.Message);

     }

   }

}

If this were to be used in production, I would have created a Windows service instead of a console application, but I wanted to make it easy to try out different connection parameters.

Verifying the application

The queuewriter.js application in the node-app directory in the GitHub repository contains a sample web page that can be used to publish lead data to the CRM-Leads queue. If the application is running, you can access the web page at http://<YOUR_SERVER_NAME>:3000/leadform. When the form’s submit button is clicked, an AJAX call posts a JSON object to the Node.js POST endpoint I showed in my previous post. If the LeadWriterSample console application is running, it will take the message from the queue and you will see a new lead record created in CRM. The screenshots below show each piece working.

The lead has been submitted via the web form, and a success message has been received from the Node.js endpoint.

The lead has landed in the CRM-Leads queue and is ready to be retrieved.

The console application has retrieved and processed the submitted lead message.

The lead record has been created in CRM.

One caveat about the demo lead form is that it has the RabbitMQ credentials embedded in the HTML source, so this code should not be used in production. My approach was originally formulated with the thought that a server-side process would build the JSON message to post to Node.js, so sensitive information would not be exposed. If you decide to use an AJAX post operation like is shown here, you would want to modify the queuewriter.js application to contain the credentials so they do not need to be passed from the end user’s web browser.

Wrapping up

That does it for this series, but I’ve just barely explored the capabilities of RabbitMQ. There’s so much more you can do with it than what I’ve shown here, and I hope I’ve piqued your interest about how you can use RabbitMQ or any other message broker in your Dynamics CRM projects. If you have any questions or want to continue the discussion, please share your thoughts in the comments.

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

Last week I decided to finally take a look at using OAuth2 as an authentication protocol with Dynamics CRM. I wanted to understand how it could enable non-Windows clients to consume CRM data. As it turns out, I was unable to find any documentation or comprehensive code samples for non-Windows clients, so I put together my own Node.js client, and I've added the code to my Crm-Sample-Code repository on GitHub here: https://github.com/lucasalexander/Crm-Sample-Code/tree/master/NodeClientDemo. Having endured a lot of frustration in getting this to work, I'd like to share some additional notes that might be helpful if you decide to start using OAuth2 with CRM.

If you're not already familiar with OAuth2, I suggest you take a look at this post on the Microsoft Dynamics CRM blog that explains how CRM uses OAuth at a high level: http://blogs.msdn.com/b/crm/archive/2013/12/12/use-oauth-to-authenticate-with-the-crm-service.aspx. Although there's no code in that post, it will help you understand how OAuth authentication works.

Infrastructure and environment prep

I am running Dynamics CRM 2015 and Active Directory Federation Services (AD FS) on a single Windows Server 2012 R2 Azure VM. CRM and AD FS are configured for IFD. The CRM website is running on port 443. AD FS is running on port 444.

Before writing any code, I completed all the prep work outlined in this CRM SDK walkthrough - https://msdn.microsoft.com/en-us/library/dn531010.aspx. Specifically I enabled OAuth2 for CRM, and I registered an OAuth2 client application in AD FS. Although this was all done as part of an on-premise Dynamics CRM deployment, I don't see any reason that it won't work with CRM Online.

The code

Now, let's take a look at the Node.js application. I chose to write a Node.js client instead of something in C# for two main reasons. First, Node.js made it easy for me to inspect and modify all the HTTP headers that are required for getting OAuth2 to work. Second, Node.js is basically server-side JavaScript, so most of the work I've done can be easily ported to a client-side JavaScript implementation.

My Node.js application is written using the Express web framework, and it serves four web pages via routes. They are:

2. / - This is the web application index page. It displays links to the login page and contacts display page.
3. /auth/login - This page handles redirection of the browser to the AD FS login page.
4. /auth/callback - This is the page to which AD FS redirects the user's browser after a successful login.
5. /authenticated/contacts - This page queries the CRM OrganizationData service for contacts using an OAuth token for authentication.

The basic flow of the application is:

2. A user starts on the index page. The page checks for an OAuth token in a session variable. If no token is present, a link to the login page is shown. If a token is present, a link to the contact display page is shown.
3. When a user navigates to the login page, it makes a request to the CRM OrganizationData service to request the correct URL to use for authentication and redirects the browser to that page. The client id, resource name and redirect uri are all included in the query string of the request to AD FS. (See https://github.com/nordvall/TokenClient/wiki/OAuth-2-Authorization-Code-grant-in-ADFS for more information on how this works.)
4. The user authenticates with AD FS, and then AD FS redirects the user to the callback page with an authorization code in the query string.
5. The callback page parses the authorization code from the query string and sends it to AD FS to request a token. The token is stored in a session cookie, and then the user is redirected to the index page, which should now show a link to the contact display page.
6. The contact display page reads the token from the session cookie and makes an Odata request to CRM with the token supplied as the authorization header. The results are then parsed and displayed.

A few caveats:

2. OAuth2 tokens eventually expire. The default AD FS OAuth2 token expiration value is 3600 seconds (one hour). It is possible to request a new token using a refresh token that is provided at the same time as the authorization token. Using the refresh token allows for reauthorization without needing to supply credentials again. My code sample does not demonstrate use of a refresh token.
3. My sample application doesn't have much in the way of error handling, and it has not been extensively tested. If you plan to use OAuth with CRM, I highly recommend you don't just deploy my code in production without any further testing.

Welcome back to my five-part series on creating loosely coupled data interfaces for Dynamics CRM using RabbitMQ. In my last post I showed how to build a Dynamics CRM plug-in that publishes notification messages to a RabbitMQ exchange using the official RabbitMQ .Net client library. Unfortunately, that plug-in can’t successfully communicate with a RabbitMQ server if it’s executed inside the Dynamics CRM sandbox, so in today’s post I will show how to achieve the same results with a sandboxed plug-in. The code for this plug-in is available on GitHub in the MessageQueueSandboxPlugin project under the LucasCrmMessageQueueTools solution.

The approach

As I mentioned in my previous post, last month I wrote a series of blog posts about how to create a near real-time streaming API using plug-ins and Node.js. That plug-in worked fine in the Dynamics CRM sandbox, and Node.js can easily publish messages to a RabbitMQ exchange, so today’s plug-in will post a JSON-formatted message to a Node.js application, and then that Node.js application will do the actual publishing to RabbitMQ. As a result, I only need to make a couple of minor modifications to my earlier Node.js message-posting plug-in so that it can pass the RabbitMQ connection parameters to my Node.js application. Additionally, the Node.js application that I described in my earlier series only needs a few changes to publish the message to a RabbitMQ exchange instead of sending it to Socket.IO clients.

The plug-in

The plug-in is registered for an operation (create, update, delete, etc.) with a FetchXML query in its unsecure configuration. When the plug-in step is triggered, its associated FetchXML query is executed, and then the resulting fields are serialized into a JSON object, which is then sent to a Node.js application called queuewriter.js via an HTTP POST request. The JSON object also needs to contain RabbitMQ connection details, so I pass them as part of the plug-in step’s unsecure configuration. Here’s the configuration XML fragment to enable case notifications:

<nodeendpoint>http://lucas-ajax.cloudapp.net:3000/rabbit_post_endpoint</nodeendpoint>
<endpoint>lucas-ajax.cloudapp.net</endpoint>
<exchange>CRM</exchange>
<routingkey>Case</routingkey>
<user>rabbituser</user>
<password>PASSWORDHERE</password>
<query><![CDATA[
<fetch mapping='logical'>
<entity name='incident'>
 <attribute name='ownerid'/>
 <attribute name='modifiedby'/>
 <attribute name='createdby'/>
 <attribute name='title'/>
 <attribute name='incidentid'/>
 <attribute name='ticketnumber'/>
 <attribute name='createdon'/>
 <attribute name='modifiedon'/>
 <filter type='and'>
  <condition attribute='incidentid' operator='eq' value='{0}' />
 </filter>
</entity>
</fetch>
]]>
</query>
</config>

Just like in my earlier Node.js plug-in, the FetchXML is extracted from the configuration XML, and the query is executed against Dynamics CRM. The results are then serialized to JSON using Json.NET just like before, except the serialized CRM data is included as a "message" object that is part of a parent JSON object that includes the RabbitMQ connection parameters. Here’s an example of the structure:

{

   "endpoint":"lucas-ajax.cloudapp.net",

   "username":"rabbituser",

   "password":"XXXXXXXX",

   "exchange":"CRM",

   "routingkey":"Lead",

   "message":{

     "property1":"value 1",

     "property2":"value 2",

     "property3":"value 3"

   }

}

Because this plug-in uses the Json.NET client library, it has to be merged with the plug-in assembly before registering it in Dynamics CRM. I’ve included a batch script called ilmerge.bat in the project directory on GitHub.

The Node.js application

The Node.js application (queuewriter.js) waits to receive JSON messages via HTTP POST from a client. When it receives a POST request, it checks whether the message is valid JSON. If it is, the RabbitMQ connection parameters are extracted and then the notification "message" object is published to the RabbitMQ exchange. If everything is successful, it sends "success" back as a response to the client. If any errors are encountered, it sends back a descriptive error message. I am using the node-amqp library for communicating with the RabbitMQ server, but the behavior isn’t that different from a .Net client. Here’s an extract with the relevant code:

if (request.method == 'POST') {

   request.on('data', function(chunk) {

     //check if received data is valid json

     if(IsJsonString(chunk.toString())){

       //convert message to json object

       var requestobject = JSON.parse(chunk.toString());

      

       //connect to rabbitmq

       var connection = amqp.createConnection({ host: requestobject.endpoint

       , port: 5672 //assumes default port

       , login: requestobject.username

       , password: requestobject.password

       , connectionTimeout: 0

       , authMechanism: 'AMQPLAIN'

       , vhost: '/' //assumes default vhost

       });

      

       //when connection is ready

       connection.on('ready', function () {

          //get the "message" property of the supplied request

          var message = JSON.stringify(requestobject.message);

         

          //post it to the exchange with the supplied routing key

          connection.exchange = connection.exchange(requestobject.exchange, {passive: true, confirm: true }, function(exchange) {

            exchange.publish(requestobject.routingkey, message, {mandatory: true, deliveryMode: 2}, function () {

              //if successful, write message to console

              console.log('Message published: ' + message);

             

              //send "success" back in response

              response.write('success');

             

              //close the rabbitmq connection and end the response

              connection.end();

              response.end();

            });

          });

       });

      

       //if an error occurs with rabbitmq

       connection.on('error', function () {

          //send error message back in response and end it

          response.write('failure writing message to exchange');

          response.end();

       });

     }

     else {

       //if request contains invalid json

       //send error message back in response and end it

       response.write("invalid JSON");

       response.end();

     }

   });

}

The complete queuewriter.js application is contained in the node-app directory in the GitHub repository.

Wrapping up

In addition to registering the plugin and registering a step to publish a notification message to RabbitMQ, you need to deploy and start the queuewriter.js application to publish messages. Once that’s done, you can verify everything is working as expected either by looking at the Queues tab in the RabbitMQ management web UI or running the CliConsumer sample application I showed in part 2.

Obviously using queuewriter.js as message proxy adds an extra layer of complexity, and you have to make sure that the application is up and running in order to process message, but it also offers a couple of advantages. First, by using queuewriter.js instead of a direct connection, you can easily use this same plug-in with different message brokers like Apache ActiveMQ and Microsoft’s Azure Service Bus. Second, the queuewriter.js application isn’t limited to just handling messages outbound from Dynamics CRM. You can also use it to process inbound messages without any changes. You just have to configure a client application to read messages from the queue and process them accordingly. A good example of this would be writing data submitted through a web form to Dynamics CRM via a RabbitMQ queue, and I will show that exact scenario in my next post!

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

This is the third post of a five-part series on creating loosely coupled data interfaces for Dynamics CRM using RabbitMQ.
Last time I showed how to install and configure a RabbitMQ server to support passing messages to and from Dynamics CRM. Today I will show how to build a Dynamics CRM plug-in that publishes notification messages to a RabbitMQ exchange using the official RabbitMQ .Net client library. The code for this plug-in is available on GitHub in the MessageQueuePlugin project under the LucasCrmMessageQueueTools solution.

Before going any further, let’s get some bad news out of the way. Plug-ins that execute in the Dynamics CRM sandbox cannot use RabbitMQ .Net client library to publish messages to a RabbitMQ server, so you can’t use today’s plug-in approach from a CRM Online organization. In my next post, I will be showing an alternate mechanism for publishing messages that you can use from a sandboxed plug-in, but today I want to focus on the most direct integration method. Now that we’re clear on the limitations of this approach, let’s get started!

The approach

Last month I wrote a series of blog posts about how to create a near real-time streaming API using plug-ins and Node.js. For this plug-in I’m going to basically copy the logic I used for the plug-in in that series.

This post outlines the approach in detail, but if you don’t want to read the entire thing, the basic idea was to create a plug-in that is registered for an operation (create, update, delete, etc.) with a FetchXML query in its unsecure configuration. When the plug-in step is triggered, its associated FetchXML query is executed, and then the resulting fields are serialized into a JSON object, which is then sent to the Node.js application via an HTTP POST request. Today’s plug-in operates in the exact same way, except instead of sending the JSON object to a Node.js endpoint, the JSON object will be published as a message to a RabbitMQ exchange.

Configuring the plug-in

To make the plug-in easily useable in any organization without needing to be recompiled, all the RabbitMQ connection parameters are stored in the unsecure configuration along with the FetchXML query for the data to retrieve. Here’s the configuration XML fragment to enable case notifications:

<config>
<endpoint>lucas-ajax.cloudapp.net</endpoint>
<exchange>CRM</exchange>
<routingkey>Case</routingkey>
<user>rabbituser</user>
<password>PASSWORDHERE</password>
<query><![CDATA[
<fetch mapping='logical'>
<entity name='incident'>
 <attribute name='ownerid'/>
 <attribute name='modifiedby'/>
 <attribute name='createdby'/>
 <attribute name='title'/>
 <attribute name='incidentid'/>
 <attribute name='ticketnumber'/>
 <attribute name='createdon'/>
 <attribute name='modifiedon'/>
 <filter type='and'>
  <condition attribute='incidentid' operator='eq' value='{0}' />
 </filter>
</entity>
</fetch>
]]>
</query>
</config>

Generating the notification message

Just like in my Node.js plug-in, the FetchXML is extracted from the configuration XML, and the query is executed against Dynamics CRM. The results are then serialized to JSON using Json.NET.

Publishing the message

The endpoint, exchange name, RabbitMQ user, RabbitMQ password and routing key values from the configuration XML are then used to establish a connection to RabbitMQ and publish the notification message to the exchange like so:

try
{
     //connect to rabbitmq
     var factory = new ConnectionFactory();
     factory.UserName = \_brokerUser;
     factory.Password = \_brokerPassword;
     factory.VirtualHost = "/";
     factory.Protocol = Protocols.DefaultProtocol;
     factory.HostName = \_brokerEndpoint;
     factory.Port = AmqpTcpEndpoint.UseDefaultPort;
     IConnection conn = factory.CreateConnection();
     using (var connection = factory.CreateConnection())
     {
         using (var channel = connection.CreateModel())
         {
             //tell rabbitmq to send confirmation when messages are successfully published
             channel.ConfirmSelect();
             channel.WaitForConfirmsOrDie();
            
             //prepare message to write to queue
             var body = Encoding.UTF8.GetBytes(jsonMsg);
 
             var properties = channel.CreateBasicProperties();
             properties.SetPersistent(true);
            
             //publish the message to the exchange with the supplied routing key
             channel.BasicPublish(_exchange, _routingKey, properties, body);
         }
     }
}
catch (Exception e)
{
     tracingService.Trace("Exception: {0}", e.ToString());
     throw;
}

If any errors are encountered, the message is captured via the tracing service, and then an exception is thrown.

Because this plug-in uses both the RabbitMQ .Net and Json.NET client libraries, they have to be merged with the plug-in assembly before registering it in Dynamics CRM. I’ve included a batch script called ilmerge.bat in the project directory on GitHub.

Wrapping up

After you register the plugin and register a step to publish a notification message to RabbitMQ, you can verify everything is working as expected either by looking at the Queues tab in the RabbitMQ management web UI or running the CliConsumer sample application I showed in
part 2.

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

Welcome back to this five-part series on creating loosely coupled data interfaces for Dynamics CRM using RabbitMQ. In my last post I discussed why you would want to incorporate a message broker into your Dynamics CRM data interfaces, and today I will show how to install and configure RabbitMQ to support the examples I’ll be presenting in the rest of the series.

Installation

First, you’ll need to download the installation files from here: http://www.rabbitmq.com/download.html. The RabbitMQ server runs on Windows, Linux, UNIX and Mac OS X, and there are installation guides for each supported platform. Because RabbitMQ is written in Erlang, you will need to install an Erlang VM before you can install RabbitMQ, but there is a download link provided in the installation guide. I set up my RabbitMQ server on a Windows 2012 server, and I was up and running in less than 10 minutes.

Once you’ve installed RabbitMQ and started the server, the easiest way to manage it is via the web-based management interface that’s included with the server distribution. You can enable the management interface with the rabbitmq-plugins tool. Run the following command to enable it: rabbitmq-plugins enable rabbitmq_management.

After the management plugin is enabled, you can access the web management UI from your server at http://localhost:15672. The default username is "guest" with "guest" as the password.

You’ll also need to configure any firewall rules necessary to allow access to your RabbitMQ server if it’s running on a server separate from your Dynamics CRM server. The default port is 5672, but that can be changed if you like. This page discusses RabbitMQ configuration in great detail.

Setting up users, queues and exchanges

The first thing you should do after the install is complete is change your default guest user password via the management UI. Then you can add additional users as necessary. For the examples in the rest of this series, you’ll need a user with full permissions on the default "/" virtual host. Here is what my "rabbituser" user account looks like:

Next you need to create the entities required to broker the messages between publishers and consumers. Before continuing, I recommend you take a moment to skim this Advanced Message Queuing Protocol (AMQP) overview document. If nothing else, at least read through the "hello, world" example section because it’s a great introduction to concepts that will be important throughout the rest of this series.

Queues
In the management UI, navigate to the Queues tab, and create two new durable queues named CRM-Cases and CRM-Leads. (You can create any queues you want, but my examples in the rest of this series use queues with those names.) The screenshot below shows the queues in my system.

Exchanges
After your queues are created, you can create an exchange and bindings to your queues so messages get routed correctly. Navigate to the Exchanges tab and create a new, durable exchange named CRM. After your CRM exchange is created, you should see something like the screenshot below.

Next, click on the name of the CRM exchange to open its edit screen. Scroll to the "add binding" section toward the bottom of the page and add a binding to the CRM-Cases queue for a routing key value of "Case" live in the following picture and click "bind."

Do the same for the CRM-Leads queue with "Lead" as the routing key. You should then see the two queues bound to the exchange.

Checking the configuration

At this point you should have everything in place to start publishing and consuming messages. You can verify your configuration works with the CliProvider and CliConsumer sample applications included in my GitHub repository as part of the LucasCrmMessageQueueTools solution.

First, build and run the CliProvider application. You will be prompted to supply basic connection details, and then you can type a message to publish to your RabbitMQ server.

Once the message has been published, you can verify there’s a message waiting in the correct queue on the Queues tab of the management UI.

Next, build and run the CliConsumer application. Once it connects to the CRM-Cases queue, the message will be retrieved and displayed.

When the CliConsumer application processes a message, it sends a confirmation back to queue that triggers removal of the message from the queue. You can check the Queues tab in the management UI to verify that the CRM-Cases queue is empty.

Wrapping up

That’s it for today. Your RabbitMQ server is now fully configured and ready for use with the examples in the rest of this series. Next time I will show how to send messages to a RabbitMQ exchange from a plug-in using the RabbitMQ .Net client library. See you then!

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

One of the things I love about Dynamics CRM is how easy it is to create data interfaces to enable integration with other systems. If you’ve worked with Dynamics CRM for any length of time, you’ve probably seen multiple web service integrations that enable interoperability with other line-of-business and legacy systems. A typical pair of inbound and outbound integrations might look like the picture below.

Using a tightly coupled connection between the source and target systems is usually the easiest (thus the quickest and cheapest) way to establish an integration, but this is often a bad idea. Consider the inbound scenario in which an external application is sending data to Dynamics CRM. What happens if the calling application misbehaves and starts sending thousands of requests per second? This has the potential to overload your CRM server and make it completely unusable. Now consider the outbound scenario in which a CRM plug-in calls an external web service. If the destination application’s web service is offline for a few minutes, the update from the CRM plug-in will not get received unless there’s some sort of error handling and retry logic built into the plug-in

An alternate approach

For these reasons, and lots of others (logging, security, scalability, just to name a few), it’s considered a best practice to create loosely coupled integrations that rely on a message broker that sits between the source and destination systems. Though the formal definition is more complicated, for our purposes a message broker can be thought of as a collection of queues that hold messages. Publishers write messages to queues, and then consumers pick up the messages and process them appropriately. Additionally, the message broker can be configured to keep messages in their queues until the consumers provide confirmation of successful processing.

Here’s an example of what the integrations I showed earlier would look like with a message broker.

For the outbound call from the CRM plug-in, the plug-in writes the message to a broker. The message is routed to a queue where it waits to be processed. A separate processing service application retrieves the message from the queue and sends it to the destination application. For the inbound call to CRM, the process works exactly the same, except the source and destination applications are reversed.

Why is a message broker better?

In the inbound call scenario, an effective message broker would typically be expected to handle a larger volume of inbound messages than Dynamics CRM because all it’s doing is receiving and routing the data without any additional processing. The processing service can then process the messages in the queue at a speed that doesn’t overload the Dynamics CRM server. In the case of the outbound call, the combination of a message broker and processing service can enable complex retry logic and custom logging without having to store it in the plugin layer. As an added bonus to either scenario, a message broker can provide a guarantee that messages don’t get lost between the source and destination systems as long as the message is successfully published to the broker.

Where do we go from here?

Over the course of my next four blog posts, I will show how to use RabbitMQ as a message broker in your Dynamics CRM data interfaces. I chose RabbitMQ for this series for several reasons:

1. It’s open source.
2. It runs on multiple platforms.
3. It’s easy to install and configure.
4. It’s fast at processing messages.

If you already have a different message broker in place in your organization or you would like to try a different message broker like Apache ActiveMQ or Microsoft’s Azure Service Bus, most of the approaches and a lot of the code I’m going to show in this series will still be applicable, with the notable exception of the post that discusses how to install and configure RabbitMQ.

Here’s the roadmap for the rest of the series:

• Part 2 – basic installation and configuration of a RabbitMQ
• Part 3 – creating a Dynamics CRM plug-in that publishes messages using the RabbitMQ .Net client library
• Part 4 – creating a sandboxed Dynamics CRM plug-in that publishes messages to RabbitMQ via Node.js
• Part 5 – reading messages from a queue and writing them to Dynamics CRM

If you just can’t wait to dig into the code, I’ve already posted everything to my repository on GitHub, so you can go ahead and take a look.

See you next time!

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

This is the final post in my four-part series about creating a near real-time streaming interface for Microsoft Dynamics CRM using Node.js and Socket.IO. In my last post I showed how to write the plug-in code to send messages from CRM to the Node.js application. In today’s post I will show how to configure a client to receive and process notifications from the Node.js application, and I’ll also discuss some general considerations related to this solution.

My first post in this series included a video that showed two clients connected to the Node.js application via Socket.IO. One was a web page that displayed notifications using JavaScript, and the other was a simple C# console application. You can find the code for both of the clients from the video in the “client-src” directory in the solution on GitHub.

Web pages

Creating a web page to display notifications received from the Node.js application is incredibly simple. For the web page I demonstrated in the introductory video I first load JavaScript libraries for Socket.IO and JQuery:

<script src="https://cdn.socket.io/socket.io-1.2.0.js"></script>

<script src="http://code.jquery.com/jquery-1.11.1.js"></script>

Then I connect to the Socket.IO endpoint and register a callback function to append the notification text to an element on the page with JQuery:

var socket = io("http://lucas-ajax.cloudapp.net:3000");

socket.on('message', function(msg){

var obj = jQuery.parseJSON( msg );

$('#records').append($('<li>').text(msg));

});

Of course you’re not limited to displaying just raw text. Once you parse the JSON message, it’s a fully-fledged object that you can work with as you like. For example you can create a web page client that lists case updates by displaying the case numbers hyperlinked to the record in Dynamics CRM.

The code for this is only marginally more complicated than the raw stream example above.

var socket = io("http://lucas-ajax.cloudapp.net:3000");

socket.on('message', function(msg){

var obj = jQuery.parseJSON( msg );

if(obj.entity==="incident"){

$('#records').append($('<li>'+obj.operation + ' - <a href="https://lucas-ajax.cloudapp.net/Lucas01/main.aspx?etc=112&pagetype=entityrecord&id='+obj.id+'" target="_blank">'+obj.ticketnumber+'</a>'));

}

});

As before, first the page creates a connection to the Socket.IO endpoint, and then it registers a callback function. This time, however, the callback function includes a check for incident entities, and the append step creates a hyperlinked case number. The code for this example and another one for contact updates is included in the solution source code on GitHub.

Other clients

The C# console application I showed in the introductory video was also incredibly simple to create. First I needed a way to communicate with the Socket.IO endpoint. I used the Socket.IO Client Library for .Net (also available from Nuget -> Install-Package SocketIoClientDotNet). Once I included the library in the project, the code ended up looking a lot like the JavaScript examples above.

var socket = IO.Socket("http://lucas-ajax.cloudapp.net:3000/");

socket.On(Socket.EVENT_CONNECT, () =>

{

socket.On("message", (data) =>

{

Console.WriteLine(data);

//socket.Disconnect();

});

});

In addition to C#, you can create Socket.IO clients in other languages, too. The Socket.IO FAQ has links to client libraries for Java and iOS clients.

Security considerations

As I mentioned in the second post in this series, this solution lacks any mechanism for authenticating or authorizing clients, but I said it was possible. There are two typical approaches to securing Socket.IO interfaces, cookie-based and token-based. This article on "Token-based authentication with Socket.IO" gives a good overview of the problems with the cookie-based approach and goes into some detail about how to implement token-based authentication. In addition to securing the Socket.IO endpoint, you’d also want to consider securing the endpoint where Dynamics CRM posts notifications. You could use the same token-based approach for that, too.

I would also suggest that depending on how you’ve deployed Dynamics CRM and how you need to grant client access, you might not need to worry about security at all. For example, in the case notification example above the only information exposed via the interface is the case number and whether it was created or updated. To see anything else, the end user actually has to open the record, and regular Dynamics CRM security will do the rest.

Wrapping up

I hope you’ve enjoyed this series, and I hope I’ve given you some ideas about how you could implement and use a near real-time streaming API for Dynamics CRM in your own projects. If you have any questions or want to continue the discussion, please share your thoughts in the comments.

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