Welcome to the official getting started guide for the Zendesk for Microsoft Dynamics CRM 2011 integration. The Zendesk for Microsoft Dynamics CRM 2011 closes the loop between your sales and support teams by enhancing visibility into customer information and support activity between Microsoft Dynamics CRM 2011 and Zendesk. Use this guide to start configuring and using Zendesk for Microsoft Dynamics CRM 2011.
Zendesk for Microsoft Dynamics CRM 2011 is an application that your Microsoft Dynamics administrator installs in your Microsoft Dynamics CRM 2011 application. It contains a Zendesk module that gives you access to Zendesk tickets in Microsoft Dynamics and displays key Microsoft Dynamics fields in Zendesk user profiles.
Microsoft Dynamics CRM editions supported
Microsoft Dynamics CRM 2011 online (cloud based) using Microsoft LIve ID or Office365 as the primary authentication method.
Microsoft Dynamics CRM 2011 On Premise Solutions (self-hosted, IFD self-hosted) are currently in beta. If you are interested, please shoot me an email to firstname.lastname@example.org with the subject line "On-Premise Dynamics CRM Beta". Include your Zendesk subdomain and we will make sure the on-premise setting is enabled. You will receive additional information to get set up once enabled.
Follow these steps to begin using Zendesk for Microsoft Dynamics CRM 2011:
Install Zendesk for Microsoft Dynamics CRM 2011 as a module in Microsoft Dynamics CRM 2011 and set up user credentials for the Zendesk account you want to connect to.
Set up new security roles. The Zendesk integration introduces two new Microsoft Dynamics CRM 2011 security roles to give you more granular control over who can access and enter their individual Zendesk credentials and who can access Zendesk configuration pages.
Set up user data lookup in Zendesk and Microsoft Dynamics CRM 2011 to view Microsoft Dynamics CRM 2011 data within Zendesk.
Configure the ticket-to-case capabilities in Zendesk and Microsoft Dynamics CRM 2011 to convert tickets into Microsoft Dynamics CRM 2011 cases.
Add the Zendesk Configuration page to a your existing customized site map.
Add the Zendesk ticketing panel to a custom area in your Accounts, Contacts, and Leads pages in Microsoft Dynamics CRM 2011.
Configure your IIS server with the Zendesk/Microsoft Dynamics web service that provides user data lookup and ticket-to-case functionality. This step is optional. Zendesk does provide a shared hosted web service for its customers on the Windows Azure platform.
Install Zendesk for Microsoft Dynamics CRM 2011
The first part of this article covers uploading the Zendesk Silverlight module to your Microsoft Dynamics CRM 2011 instance. This is followed by configuring the plug-in.
Click the Settings section in the left-hand navigation (1), then click Solutions (under Customization) (2). Finally, click the Import button (3).
In the Import Solution dialog box, click the Browse button to select the "ZendeskConnector_1_0_0_2_managed.zip" file you saved in Step 1, then click OK. Click the Next button when you are ready to continue.
You can ignore the following warning, and click Next to start the upload process.
When the upload is complete, you'll see confirmation that the upload was successful. Click the Close button. This part of the setup is complete! Look for a new entry in the list of solutions for the Zendesk - MS CRM 2011 Connector. Stay on this page for the next phase. Note: You may need to re-log into your instance of Dynamics for the Zendesk configuration page to show.
Setting up new security roles
The Zendesk integration introduces two new security roles to Microsoft Dynamics CRM 2011 that must be assigned before you can proceed to the next step:
Zendesk - Read configuration settings - grants access to the configuration settings for an individual Zendesk user so they can enter their personal Zendesk credentials to create and edit Zendesk tickets directly from Microsoft Dynamics CRM 2011.
Zendesk administrator - grants access to the global Zendesk Configuration page (step #3).
By default, all users can view Zendesk ticket information in Microsoft Dynamics CRM 2011 if the panels are enabled. To edit tickets, the appropriate role must be assigned to a user. To enable the roles, do the following:
In Microsoft Dynamics CRM 2011, select Settings (1) > System > Administration (2) > Users(3).
In the Users page, click New if you need to add new users. If you are editing a list of existing users, select the user you want to modify and click on the Manage Roles button.
In the Add Users dialog box, select the role for the group you want to configure. The two new roles created by the Zendesk integration are at the bottom. Click Next to select and assign the users to a particular role and to send email invitations.
Users are now configured to use the Zendesk for Microsoft Dynamics CRM 2011 integration! If you have pre-existing users, you can simply add the appropriate roles to each of your uses.
Adding the Zendesk Configuration page to your existing site map
To edit the site map of your Microsoft Dynamics CRM 2011, please follow the steps below. Alternatively, you can use a tool like http://sitemapeditor.codeplex.com/ to make this a bit easier.
If you do not have the SiteMap solution available in your list of Solutions, please follow steps 2-5. If you do have the Sitemap, proceed to step 6.
Click the New button in the Solutions section.
Give the solution a Display Name (for example, "Sitemap"), select the Default Publisher, and specify a Version (for example, "1"), then save the solution.
In the Sitemap page, click Components (1) in the left-hand navigation. Click the Add Existing button (2) and select Site Map from the list of options (3). Click Ok.
Click Save and Close.
In the Solutions page, select SiteMap in your list of available Solutions (1), then click the Export button (2).
Click Next through the series of Export options (and possible warning) presented. Don't worry about changing any of the settings. When you reach the final page you'll see an Export button. On the final page, make sure the Unmanaged option is selected, then click the Export button.
When prompted, download a zip file of the SiteMap and save the file where you can easily find it.
Locate the file you just downloaded and extract its contents. Open customizations.xml in a text editor to make changes.
Add the following code snippet to customizations.xml. You can put the code anywhere, as long as it's under an existing <Group> element (for example, under the Group ID of Customizations).
Save the file and repackage the zip file. Be sure to include the other two original files ([Content_Types].xml and solution.xml) as well as your new customizations.xml file.
Navigate back to the Microsoft Dynamics CRM 2011 Solutions page.
Click the Import button, then browse to the updated zip file and click Next. Continue to click Next.
On the final page, click Publish All Customizations. When the import is complete, refresh your Microsoft Dynamics CRM 2011 page and look for a new entry in Settings called Zendesk Configuration Page.
Adding the Zendesk for Microsoft Dynamics CRM 2011 panel
Now you are ready to add the Zendesk ticketing panel to your Accounts/Contacts/Leads pages. You need to repeat the steps below for each type of record type you want the panel displayed on.
In Microsoft Dynamics, select the Sales section in the left-hand navigation panel. Select the record type where you want to add the panel (Accounts, Contacts, or Leads ). For this example, we'll refer to a Contact record.
Select any contact in your list and, in the Contact page, click the Customize tab.
Click the Form button in the menu bar. This starts the Form Editor and opens another window.
In the Form Editor, click the Insert tab (1), then click the Web Resource button (2).
In the Add Web Resource page, click the magnifying glass next to Web resource to find the Zendesk Silverlight plug-in.
In the next page, select the check box next to new_SilverLight/TicketLister, then click OK.
Back in the Add Web Resource dialog box you should see new_SilverLight/TicketLister in the Web resource field. Enter a Name and Label you can easily recognize (consider naming it Zendesk Ticket Panel), then click OK.
You now have a Zendesk ticket panel in the form layout that you can drag anywhere you'd like on the page. You can even create a special subsection for it if you'd like.
After you place the panel, navigate to the Home tab, click Save, then click Publish.
Refresh the contact page you had open and you should see the new Zendesk ticket panel where you placed it! Note: You may experience an error that pops up when closing a record in CRM and Zendesk tickets will not be pulled. This should disappear once you complete the next section "Setting up Zendesk Credentials".
Repeat these steps for the Accounts and Leads tabs if you want to display the panel on those pages.
Note: The Go To Configuration Page link allows Microsoft Dynamics users to create their individual settings for their Zendesk account. By authenticating with their Zendesk account, Dynamics users can create and edit tickets directly from Microsoft Dynamics CRM 2011 and they can set their personal filtering preferences.
Setting up Zendesk credentials
You now need to set up your Zendesk credentials so that the system can authenticate to the appropriate Zendesk instance.
Open the newly created Zendesk Configuration page in your Microsoft Dynamics CRM 2011 instance.
In the Authentication section of the configuration page, enter your Zendesk subdomain (make sure you specify HTTP vs. HTTPS if you have SSL enabled) and login credentials (you need administrator credentials). This gives your Microsoft Dynamics CRM 2011 users read-only access to available tickets. To create or edit tickets from Microsoft Dynamics CRM 2011, your Dynamics users must have a Zendesk license, and they will need to enter their own credentials (explained later in this article). Make sure you end the Zendesk URL with a forward slash ("/").
Optionally, you can configure the other settings now, if you want:
Ticket view defaults - global default settings for ticket views in the Zendesk ticket panel. This sets the defaults at the account level, but can be overwritten by individual preferences by each user.
Filtering - sets the default values for filters in the Zendesk ticket panel.
Sorting - sets the default sort order for tickets in the Zendesk ticket panel.
Advanced - if you select Show Account tickets by Zendesk Organization, and the Zendesk ticket panel is enabled on the Accounts object, then Zendesk tickets will be matched based on the Account Name matching the Zendesk Organization the ticket is associated with. By default, the Zendesk ticket panel on the Accounts object will match on all email addresses associated with an account.
Mapped record types - enables you to modify the data elements that display in a Zendesk user profile when a ticket is loaded. You can choose from Lead, Contact, and Account. All fields are available, including custom fields.
Ticket-to-case mapping - identifies data items that should be mapped from standard Zendesk ticket fields into Microsoft Dynamics CRM 2011 cases. The three Zendesk fields that are supported are Status, Priority, and Type.
Setting up user data lookup for data display in Zendesk
Now that the Microsoft Dynamics CRM 2011 section is complete, it's time to configure the Zendesk data display of Microsoft Dynamics CRM 2011 information.
Once again, in your Microsoft Dynamics CRM 2011 instance, open your newly created Zendesk Configuration page.
In the Zendesk Configuration page, find the Mapped record types section and select the Microsoft Dynamics CRM 2011 fields that you want to appear in a Zendesk user profile. To do so, select a field from Microsoft Dynamics CRM (1) and click the arrow (2). The fields that appear on the right (3) are the ones that will be in each Zendesk user profile.
Now log in to your Zendesk portal. (You need administrator access for the remaining steps.)
In Zendesk, click the Manage cog in the sidebar, then select Extensions.
Select the CRM tab.
In the Select CRM option, select Microsoft Dynamics 2011.
Fill out the following pieces of information:
Web service address - stores the address of the web service required for the user profile lookup. If you are not hosting your own IIS server, enter URL: http://zendeskadaptor.cloudapp.net/. If you are hosting your own IIS server, enter the address where the IIS server is running (details for setting up your own IIS server are at the end of this article).
CRM server address - stores the actual address of your Microsoft Dynamics CRM 2011 online instance. Make sure you enter the full URL, including "https" if SSL is enabled.
Username - is your Microsoft Dynamics CRM 2011 online username. Typically, this is your email address.
Password - is your Microsoft Dynamics CRM 2011 online password.
Discovery URI - you can locate this information in Microsoft Dynamics by selecting Settings > Customizations > Developer Resources.
Organization Name - you can locate this information in Microsoft Dynamics by selecting Settings > Customizations > Developer Resources. This is located under the Organization Unique Name.
Organization URI - you can locate this information in Microsoft Dynamics by selecting Settings > Customizations > Developer Resources. Make sure you select Organization Service for the SOAP protocol.
User data lookup - enables the user profile lookup in Zendesk.
Click SaveTab. The connection is tested, and, if successful, the page refreshes and your settings are complete. If the test fails, you receive an error message. If you get an error, review your settings. Note: If you are experiencing issues saving the information and are sure the information is correct, add a contact record using the email address provided for user name.
Once this portion is set up, you now need to add the Microsoft Dynamics CRM 2011 application to your ticket pages. Simply navigate back to Manage > Browse, locate the application tile for Microsoft Dynamics, click the Install button, and give the application a name.
Now, once on a ticket page, simply expand the Apps panel on the right hand side of the page and you will see your information from Microsoft Dynamics pulled in.
Configure the ticket-to-case capabilities
Zendesk allows you to send core ticket information to Microsoft Dynamics CRM 2011 cases using a target. This is useful for including Zendesk tickets in support analytics generated through the Microsoft Dynamics CRM 2011 reporting module. This feature is designed to send basic ticket information for reporting. Ticket comments are not replicated in the Microsoft Dynamics CRM 2011 case.
Here are the key rules for case creation from a Zendesk ticket:
Ticket-to-case is a one-way push of Zendesk ticket data to a case.
If the case is modified in Microsoft Dynamics CRM 2011, the Zendesk ticket is not updated.
If a case is created from a Zendesk ticket, a subsequent push of the same Zendesk ticket will create another case.
A case will always be associated with a contact, where the contact's email address matches the Zendesk ticket requester's email address. If no contact with a matching email exists, a new contact is created and associated with the case.
There are two steps leading to the provisioning of this feature:
In Zendesk, create a trigger based on the criteria you want a ticket to meet for it to create a case in Microsoft Dynamics CRM 2011. A target is automatically created when the Microsoft Dynamics CRM 2011 setup is complete in Zendesk.
In Microsoft Dynamics CRM 2011, open the Zendesk Configuration page. In the Mapped record types section, map the standard Zendesk ticket field values to the corresponding field and field values in Microsoft Dynamics CRM 2011 cases.
Configuring your own IIS server with the Zendesk/Microsoft Dynamics Web Service
As part of the integration between Zendesk and Microsoft Dynamics CRM 2011, Zendesk provides a shared web service that handles the following functionality:
User profile lookup in Zendesk
If you do not want to use the shared web service, Zendesk provides the code for the web service so you can host your own Internet Information Service (IIS) environment. To do so, use the instructions below. It is recommended that this deployment be completed by an IIS administrator or someone with a good understanding of IIS and credentials to IIS Manager. The following screenshots use Windows Server 2008 and IIS 7.0.
Download the Crm2011AdapterForZendesk.zip file attached to the bottom of this article.
Extract the Crm2011AdapterForZendesk.zip file and import the project into Visual Studio.
After the project is imported, publish the web services via the options provided by Visual Studio under the Build Menu to configure your personal settings.
From the Windows Start menu, select Run. In the prompt, enter "inetmgr". This opens the IIS Manager.
In the left-hand panel, right-click the Sites folder and select Add Web Site. Alternatively, the web application can be added to an existing site by right-clicking the site you want to add it to and selecting Add application.
In the Add Web Site dialog box, complete the following fields, then click OK.
Site Name - a name for the site you are configuring.
Physical Path - physical location on the machine of the published files from Step 3.
Port - port number where you want the service to be hosted.
Host Name - the actual domain where you want the service to reside.
In the next dialog box, select the path where you want the service to reside, give it an Alias and enter the Physical path, then click OK.
This completes the configuration of the web service. You can access the service at: http://[<server-address>>:<<port>>]/<<web- application-path>>/ MSCRMAdapter.asmx (Note: "server-address:port" can be replaced by the alias set up in Step 7.)