Microsoft Dynamics CRM 2011 provides this cool new feature called “Windows Azure AppFabric Integration with Microsoft Dynamics CRM” that would help customers integrate their CRM with their other line of business applications without having to deal with the typical issues with polling, opening up firewall etc. Please refer to the Azure Extensions for Microsoft Dynamics CRM topic in the MIcrosoft Dynamics CRM 2011 SDK for more details on this feature.
In this blog, I will guide you step by step to get you started with CRM integration with Azure AppFabric. At the end of this blog, you would know everything to get your first CRM-AppFabric sample up and running.
Pre-Requisite – Only for on-premises and IFD CRM servers:
If you are using Microsoft Dynamics CRM Online, you do not have to do this step. This has already been done for you.
If you are using an on-premises or IFD CRM server, you will need to do your one-time setup for configuring your CRM server for Azure integration. Please refer to the topic “Configure Windows Azure Integration with Microsoft Dynamics CRM” in CRM 2011 SDK to do this.
In this blog, we will start by creating an azure account, and then run the service that listens for messages from CRM, use the plugin registration tool to configure both Azure and CRM and then see it working end to end.
1) Signup for an Azure AppFabric account:
First, let’s start off by going to http://www.microsoft.com/en-us/appfabric/azure/default.aspx and sign up for an Azure account. (At the time of this article, there are trial memberships available which you can take advantage of).
2) Create a ServiceNamespace
Login to the AppFabric Developer Portal (https://appfabric.azure.com/Default.aspx) with your Azure AppFabric account.
In the AppFabric Developer Portal, go to “AppFabric” tab and create a new AppFabric project.
Click on the project and click “Add Service NameSpace”. Provide a string for your service namespace, pick your region, and choose the number of connections you need and click “Create”.
Now you will see “Activating” icon next to your service namespace. It takes a couple of minutes to get your service namespace activated, and then the status of the servicenamespace becomes “Active”.
Click on the service namespace and you can see the “Management Key” which is a secret key to access your service.
3) Create a service that listens for messages from CRM
Now we need to create a service that listens for messages in CRM.
Wondering how to create a service?
CRM 2011 SDK has a set of four sample listeners, each one with a different service contract. Click here for Sample Code for Microsoft Dynamics CRM and AppFabric Integration.
Alternatively, you can download the complete CRM 2011 SDK (available at http://msdn.microsoft.com/en-us/dynamics/crm/default.aspx), and you can compile one of these listeners and use them. For example, compile the TwoWayListener project (under sdk\samplecode\cs\azure\twowaylistener) and create TwoWayListener.exe.
4) Expose your Service in AppFabric and start listening for messages from CRM:
Start the listening Service. (By doing this step, you are actually hosting this service in Azure AppFabric, so that it will start listening for the messages from CRM.).
If you are using the sample listener that ships in the sdk, start TwoWayListener.exe and provide the following details (Please note that the command line parameters are the same for all sample listeners in the sdk):
Service namespace: <name of your AppFabric Service Namespace>
Service namespace issue name: owner
Service namespace issue key: <Management Key of your AppFabric Service Namespace>
Endpoint path: <A subpath where you want to expose your listener. This can be any string. Separate child paths will a “/”>
5) Connect to your organization using Plugin Registration Tool:
Download the CRM 2011 SDK (available at http://msdn.microsoft.com/en-us/dynamics/crm/default.aspx). Compile and launch the using Plugin Registration Tool that ships in the SDK (under sdk\tools\pluginregistration).
In the tool, click “Create New Connection”. Provide the Discovery Url, UserName, and Password, then click “Connect”. Select the target organization in the list and click “Connect”.
6) Create a Service Endpoint:
Now you need to create a service endpoint which contains all the details about the service that is listening to the messages from CRM plugins. Following are the list of fields in service endpoint.
- Name: The name of your Azure AppFabric project.
- Description: A description of this endpoint registration.
- Solution Namespace: The solution namespace of your AppFabric project. Provide the name of the service namespace you created in Azure AppFabric Management Portal here.
- Path: The URL of your AppFabric project. Provide the subpath under the service namespace where your service is listening here.
- Contract: The endpoint contract. An AppFabric listener application must use this contract to read the posted message. You should choose the same contract that the listener is using, which in our example is TwoWay.
- Claim: The claims to send to AppFabric. Use None for the standard claim.
- Federated Mode: Check this box to use federated mode.
7) Configure ACS:
Next, you need to give permission for your CRM organization to post to your endpoint in Azure AppFabric using tools like acm.exe (this command line tool ships with Azure AppFabric Sdk).
How do I give permission? Configuring ACS? Hmm, what does that mean? Do I need to learn a brand new tool for doing all this???
Good news! Rather than using the command line tool acm.exe, plugin registration tool provides you with an easy to use, one- click setup support!
To give permission for your CRM organization to post to your endpoint in Azure AppFabric, all you need is the following information:
- Management Key: This is the management key for your AppFabric solution namespace.
- Certificate File: This is the public certificate that identifies your CRM deployment.
- Issuer Name: This is the name used to identify your CRM deployment in addition with certificate file.
You can get the Issuer Name and can download the certificate under “Windows Azure AppFabric Issuer Certificate” section in the Developer Resources page in your CRM Organization (see the screenshot below), which opens up when you click the “Go to the Developer Resources page…” link in the same “Configure ACS” screen.
You can grant permissions based of one of the many claims that CRM posts to AppFabric.
The various claims posted by CRM are:
- Organization: Name of your CRM organization
- User: User under whose context the plugin is executing
- InitiatingUser: User who triggered the plugin. This would be same as User claim in non-impersonation scenarios.
- PluginAssembly: Full name of the plugin assembly posting to AppFabric. The assembly name is fully qualified if the assembly is strongly signed, otherwise it is the short name.
“Configure ACS” button in PluginRegistrationTool creates issuers, rules (based on organization claim only, since that would be the most widely used scenario), scope, tokenpolicy etc to allow CRM. After configuring, the summary of the configuration done is displayed in the textbox in “Configure ACS” screen.
Note: To create rules based on other types of claims, you need to use the acm.exe tool that ships with Azure AppFabric SDK.
8) Verify Authentication:
This queues up a system job (Async job) which checks whether this CRM organization has access to post to your service in the Azure AppFabric. Since we granted access using “Configure ACS” in the above step, the “Verify Authentication” should succeed now. If there are any failures, System Job Message will display the details.
9) Register a SdkMessageProcessingStep:
Now that we have registered the service endpoint, go ahead and right click the service endpoint and choose “Register New Step” from the context menu. Provide the Message, PrimaryEntity, and any other fields you need and click “Register New Step”. You can also choose to register the pre/post images if applicable.
10) Trigger the plugin:
Now we are all set!
Let’s login the organization using the browser, and trigger the plugin. (For example, if the plugin was registered on create of lead, let’s trigger the plugin by creating a lead).
When the plugin is triggered, it queues up a system job which posts the execution context of the message currently being processed by CRM to the AppFabric endpoint specified in the service namespace.
You can check out the status of the plugin execution in the system jobs grid. In case of external issues (like the listener is not up and running yet), these system jobs have a better reliability story through automatic retry mechanisms etc.
Congratulations! The context data from the plugin is now received at the listener. For the purpose of simplicity the listener in this scenario is a console application that outputs the data in the console. You can implement a more realistic listener that would fit your needs and will also integrate into your other Line of Business Applications.
Uma Maheswari Anbazhagan