Walkthrough: Register an Azure-aware plug-in with the CRM plug-in registration tool

Applies To: Dynamics CRM 2013

This walkthrough demonstrates how to configure Microsoft Azure Access Control Service (ACS) and register a service endpoint step using the Plug-in Registration tool. Once configured, Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online can post the execution context of the current operation to a Microsoft Azure solution endpoint. For this walkthrough, the step is registered to post the execution context of the CreateRequest message for an Account entity to the Microsoft Azure Service Bus.

The following prerequisites must be completed before you start this walkthrough:

• Access to the Plug-in Registration tool. You can find the tool’s executable file in the Tools\PluginRegistration folder of the SDK. Download the Microsoft Dynamics CRM SDK package. 

• Obtain an account on Microsoft Dynamics CRM 2013 or Microsoft Dynamics CRM Online.

• Your system user account must have the System Customizer or System Administrator role. For more information, see How role-based security can be used to control access to entities in Microsoft Dynamics CRM 2013.

• Have access to a Microsoft Azure platform service namespace that uses ACS version 2, to which Microsoft Dynamics CRM will post a message. For more information about how to create a namespace see Create a new service namespace.

• If you are using Microsoft Dynamics CRM 2013, the server must be configured for Microsoft Azure integration according to the instructions in the topic Configure Microsoft Azure integration with Microsoft Dynamics CRM 2013.

• There must be a listener application actively listening to the specified solution endpoint for Microsoft Dynamics CRM to successfully post to the Microsoft Azure Service Bus. For more information, see Write a listener for a Microsoft Azure solution.

Steps

This walkthrough contains the following steps:

1. Connect to the Microsoft Dynamics CRM server

2. Create a service endpoint configuration

3. Configure ACS

4. Register a service endpoint step for an event

5. Test the endpoint registration

Connect to the Microsoft Dynamics CRM server

Follow the steps below to connect to the Microsoft Dynamics CRM server using the Plug-in Registration tool.

1. Run the Plug-in Registration tool.

2. Click or tap Create New Connection.

3. In the Login dialog box, select the deployment type radio button corresponding to the Microsoft Dynamics CRM server you intend to register a service endpoint with. The On-premises radio button includes an IFD deployment, the Online button is for the Windows Live provider of Microsoft Dynamics CRM Online, and the Office 365 button is for the Microsoft Online Services provider of Microsoft Dynamics CRM Online.

   Login form for an online deployment

   Login form for an on-premises deployment

4. If you check Always display list of available orgs, you are presented with a list of organizations that you belong to after you click or tap Login. This enables you to choose the organization that you want to register the service endpoint with. Otherwise, your default organization is used.

5. Enter the indicated information about the server and login account, and then click or tap Login.

Create a service endpoint configuration

Follow the steps below to register a Microsoft Azure service endpoint.

1. Select the tab of the organization that you want to register a service endpoint with.

2. In the toolbar of the tab, click or tap Register and then Register New Service Endpoint.

3. Fill out the Service Endpoint Registration dialog box with the information related to your solution as shown in the following figure and described in the table that follows. Make sure the contract you specify is the same contract used by your solution’s listener application.

   

   UI Element	description
   Name (field)	A name for your service endpoint registration.
   Description (field)	A description of this endpoint registration.
   Solution Namespace (field)	The name of the solution’s service namespace.
   Path (field)	The path of your project. For example, given a service endpoint URL of https://crmsdkdemo-sb.accesscontrol.windows.net/TwoWayService/Demo, the path is TwoWayService/Demo.
   Contract (drop-down menu)	The endpoint contract. A listener application must use this contract to read the posted message. For more information, see Write a listener for a Microsoft Azure solution.
   Claim (drop-down menu)	The claims to send to Microsoft Azure. Use None for the standard claim. Specify UserId or UserInfo to send additional information about the logged on user.
   Federated Mode (checkbox)	Check this box to use federated mode.
   ID (field)	Non-writeable field that is filled in automatically with the ID of your endpoint configuration.
   Save & Configure ACS (button)	Saves the configuration you entered and automates the process of configuring ACS for you. Provides an interactive way to accomplish what is described in the topic Walkthrough: Configure Microsoft Azure ACS for integration with Microsoft Dynamics CRM 2013.
   Save & Verify Authentication (button)	Saves the configuration you entered and verifies that ACS is configured correctly.
   Save (button)	Saves the configuration you entered and closes the dialog.

4. If you have not yet configured ACS integration with Microsoft Dynamics CRM, and you would like the Plug-in Registration tool to do the configuration for you, click or tap Save & Configure ACS, and then follow the instructions in the next section of this walkthrough. If you have already configured ACS, click or tap Save & Verify Authentication or Save and continue with the instructions in .

Configure ACS

Follow the steps below to configure Microsoft Azure Access Control Service (ACS).

1. After clicking Save & Configure ACS, the ACS Configuration dialog box appears. Enter the appropriate data values into the form fields as described in the following table.

   Field Name	Description
   Management Key	The management key for your solution. You can obtain this key value from the Microsoft Azure Management Portal. Obtain a Management Key for a Service Bus Namespace Log on to the Sign in to the Azure portal. In the left pane, click or tap Service Bus, and then select the target namespace in the list. At the bottom of the page, click or tap Connection Information. In the Access connection information dialog box, the Default Key is shown. This is the management key.
   Certificate File	The public certificate file that was used to configure Microsoft Dynamics CRM for integration with Microsoft Azure. For Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, you can download this certificate file from the server. In the Microsoft Dynamics CRM web application click or tap Settings > Customizations, and then click or tap Developer Resources. Download and save the certificate file using the link provided below Microsoft Azure Service Bus Issuer Certificate.
   Issuer Name	The name of the issuer. This name must be the same name that was used to configure Microsoft Dynamics CRM for Microsoft Azure integration. You can obtain the issuer name from the Developer Resources webpage mentioned in the previous description. For more information, see Configure Microsoft Azure integration with Microsoft Dynamics CRM 2013.

2. Click or tap Configure ACS. A log of the configuration process is displayed in the output area of the form.

3. Click or tap Close.

4. Click or tap Save & Verify Authentication in the Service Endpoint Registration dialog box. After the verification is finished you can close the dialog boxes.

Register a service endpoint step for an event

Follow the steps below to register a step for an event on the service endpoint.

1. Select the service endpoint that you previously registered in the tree view of the tool.

2. Navigate to the Register menu and click or tap Register New Step.

3. Fill out the Register New Step dialog box for an account create event as shown in the following figure.

   

4. Click or tap Register New Step.

Microsoft Dynamics CRM will now post the current message containing the execution context to the service bus whenever an account is created. The post is performed asynchronously and is not executed immediately.

Test the endpoint registration

After you register the endpoint you can test it. A listener must be running or a queue available on the target endpoint for the service bus post from the plug-in to happen.

1. Open the Microsoft Dynamics CRM web application for the same organization that you registered the service endpoint under.

2. Click or tap the Create button , and then click or tap Account.

3. Enter an account name, for example Adventure Works Cycle, into the Account Name field, and then click or tap Save.

4. Wait about 10 minutes for the Microsoft Azure Service Bus post to occur.

5. Click or tap Settings > System Jobs.

6. Open the system job that has the same name that you specified for your service endpoint. Check the status to see if the post was successful, is waiting, or failed.

You can now unregister the endpoint, if so desired, by selecting it in the tool’s tree view and click or tap Unregister.

See Also

Azure extensions for Microsoft Dynamics CRM 2013
Introduction to Microsoft Azure integration with Microsoft Dynamics CRM 2013
Configuring Azure Service Bus endpoint and CRM Plugin Steps
Active Directory and claims-based authentication