ShoreTel Microsoft Dynamics CRM Integration Application Version 5.x for CRM Versions 2011 and 2013 Installation and Usage Documentation ShoreTel Advanced Applications 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 1 of 40
ShoreTel Microsoft Dynamics CRM Integration Application Introduction... 3 Requirements... 3 Limitations... 3 Installation... 4 User interface settings... 4 ToolTips... 4 Login... 4 Application Startup... 6 Application Running on the Tray... 8 Tray Popup Menu... 9 Operation Overview... 10 Client Default Settings... 10 Popup Window... 12 ShoreTel CRM Client Main Window... 13 Main Menu Commands... 14 Client Call Tab Call Pane... 17 Call Pane Call Types... 18 Call Menu... 19 Client Call Tab Entity Pane... 20 Client Log Tab... 21 Query MS CRM with Test Call Dialog... 22 User Settings Dialog... 23 CRM Entity Settings Dialog... 27 Creating CRM Entities... 29 Creating Phone Call Records... 30 Appendix A: Using the CRM Entity Settings to handle a custom attribute... 33 Appendix B: ShoreTel CRM Call Properties... 38 Appendix C: Copying CRM Entity (Search) Settings... 40 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 2 of 40
Introduction The ShoreTel CRM Client provides automatic lookup of the telephone numbers of calls made and received by the customer in their Microsoft Dynamics CRM versions 2011 and 2013 (aka CRM) data store and based on the results, can provide screen pop notification to allow CRM users to navigate to associated records at the click of a mouse. It provides an easy configuration of the search settings to allow lookup of both standard and custom CRM entities and attributes. A rich set of user settings combine to allow each user control over exactly how his client responds to calls and lookup results. For outbound click-to-call support from CRM web forms, customers are advised to install the ShoreTel Web Dialer which, with some limitations, functions well with CRM and other Web based applications. Requirements Current MS Windows Web Browser such as Internet Explorer, Firefox or Chrome. Unlike the previous version of this client which only used Internet Explorer, version 5.x uses the configured default browser to open related records. Microsoft.NET 4.0 Runtime Framework The client uses the.net 4.0 framework. This may already be installed on the user's machine but if not, the user will be prompted at the time of the install to go to the Microsoft Web site to first install the.net runtime before continuing. ShoreTel TAPI Service Provider The client uses the services of the ShoreTel TAPI interface to monitor for calls. Starting with ShoreTel version 13, this needs to be explicitly installed. In prior ShoreTel versions, it is installed when the ShoreTel Communicator is installed. A Microsoft Dynamics CRM 2011 or 2013 By definition, the ShoreTel CRM Client application requires the user to have access to his Microsoft CRM account. The ShoreTel Licensing Server and an Associated License This is a licensed product that used the ShoreTel Application Licensing server and associated web site. For testing a trial license is available. For permanent use, a license must be purchased for each user. Limitations No Screen Pop for Hunt Group Calls When hunt group calls present to agent s phones, they are not marked as external. Because this client only screen pops external calls, there will be no screen pop. However, if the hunt group call is answered then the call becomes a true external call and the screen pop will occur. To avoid this issue, Workgroup calls can be used instead. Workgroup calls will present as external and will cause a screen pop without requiring that the call be answered first. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 3 of 40
Installation To install the client software, unzip STMSCRM2011Setup_5.x.x.zip file which should contain setup.exe and the STMSCRM2011Setup_5.x.x.msi file. Once the files are unzipped, run the setup.exe. NOTE: Do not run the setup.exe directly from the zip file! This can cause problems related to the.net software later attempting to reinstall the application if installed for multiple users. The installation is straightforward. The user must only decide at what location to store the files. Unless a user has a reason to store them somewhere other then the defaults provided, he should simply respond OK at all prompts until done. User interface settings The positions and sizes of all of the ShoreTel CRM client windows are saved as part of the user settings. In addition, the width of the columns in the ShoreTel CRM Client s Main window call tab calls and entities panes as well as the position of the splitter which divides the panes are also remembered. The Main window is described in more detail in the section entitled Main Window below. ToolTips All dialog controls and menus display tool tip help seen when a user hovers over the control or pauses when displaying a menu. Login The login dialog is shown if a user either fails to automatically login based on current or default settings or if a user explicitly logs out and then back in. This screenshot below shows the dialog: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 4 of 40
The top section is used to select the user s Authentication Type. This can be one of the following: Online using Office 365 North America Online using Office 365 EMEA Online using Office 365 APAC On-Premise with Provided User Credentials On-Premise with Provided User Credentials with HTTPS On-Premise with Windows Integrated Security On-Premise with Windows Integrated Security with HTTPS On-Premise (IFD) with Claims On-Premise (IFD) with Claims with HTTPS Custom Select the appropriate mode depending on which version of MS Dynamics the user is using. Appropriate entry fields will be available based on the selected authentication type. For example, this shows the fields for the Office 365 authentication: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 5 of 40
For online using a Windows Live ID, select Custom and fill in a Connection String similar to the following: Url=https://contoso.crm.dynamics.com; Username=someone@hotmail.com; Password=password; DeviceID=11hfn41bbqrg580vyvoea05abc; DevicePassword=fuqNIlx%e$.l*+ax_#8O4abc; If the user wants the ShoreTel CRM Client to remember his password (and therefore allow automatic login), check the Save password check box. Note that if the user is not using his default Windows login, he will also be prompted to provide his login credentials when he first opens a CRM form from the MS CRM web interface or from this application. Finally, if the ShoreTel CRM Client is running in a Citrix or Windows Terminal Services environment or (perhaps for testing purposes) on a ShoreTel Server, a unique extension must be specified in the ShoreTel Phone Extension field. For more details, review the Appendix ShoreWare Clients on Citrix and Windows Terminal Servers in the ShoreTel Planning and Installation Guide. Application Startup When started, the client will appear as an icon on the user s tray. While initializing, the icon will appear as an information icon (i). Hovering over the icon will display the current status of the initialization. Normal startup includes: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 6 of 40
Initializing Web Services: This is the first step required to use the MS CRM web services interface. It can last anywhere from several seconds up to 30 seconds depending on the speed of the PC. Logging into MS CRM: CRM does not have an explicit login. Rather, when the client logs in it attempts to verify its account and other settings by requesting information from CRM, specifically the client user s CRM account information. If this fails then the login fails. Users can consult the log tab of the ShoreTel CRM Client Main window for details. Normally, login should only take a few seconds depending on the speed of the user s connection to the CRM Server. Requesting MS CRM Metadata: The first time the client is run, it will load the CRM metadata for the MS CRM site the user is connecting to. Once the metadata has been loaded, it will be cached locally on the user s hard drive. Unless the user setting is changed to not cache metadata, it will not be reloaded. Therefore, if the customer s metadata is changed, the customer administrator should ask all users to explicitly force a recache of the metadata from the CRM menu. Metadata can take up to several minutes to download depending on the speed of a user s connection to the CRM Server. Note: If the client appears to hang in "Requesting MS CRM Metadata" state then the application may have failed trying to retrieve the metadata. If so, this is usually caused by a security limitation. User's must be explicitly allowed to retrieve metadata. To verify that this is the problem, the main application window can be opened and the Log tab selected to view the application's log. If it shows this: *** Soap failure retrieving CRM Metadata Server was unable to process request. SecLib::CheckPrivilege failed. Returned hr = -2147220960 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 7 of 40
Then this is the problem. To enable metadata retrieval you will need to assign read access to Entity, Attribute and Relationship in the customization tab of security role and then it will work fine. Only the System Administrator and the System Customizer role have these privileges set by default. Application Running on the Tray Once the client has started, the tray icon can reflect several states: CRM Failure or Logged Out If the login failed or if the user logs off then the tray icon will show a red (x) icon. Hovering over the icon will show the reason for the status. Viewing the log tab in the Main window may reveal additional details. If the client fails to login to the user s account, the user must manually attempt to login himself. There is no automatic login attempt after the client is first started. Phone connection problem If there is a problem connecting to the user s ShoreTel phone, the icon will display a yellow hazard (!) icon. Hovering over the icon will show the reason for the status. Viewing the log tab in the Main window may reveal additional details. The client should automatically connect to the user s phone when and if the status changes (for example a phone is plugged into the network.) Note that while real phone calls can not be managed if the client is not connected to the phone system, the user is still free to experiment with test calls. Client Running If the client logs into the user s CRM account and is able to connect to the user s phone it will show the running icon (two people): Client Searching While the client is searching for CRM entities the icon will show a magnifying glass: Client Paused 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 8 of 40
When the client is paused, it will show the paused icon ( ). Pausing the client causes it not to take any action as a result of looking up a call s related CRM entities: Tray Popup Menu In addition to seeing details about the status of the client by hovering over the tray icon, the user can access some features of the client by right clicking the client with the mouse and selecting a choice from the popup menu. This shows the menu: Open Main Window This opens the Main window. As indicated by the bolded text, double clicking the tray icon will also open the Main window. The Main window is explained below. Pause (or Resume) Pauses or resumes the client. When the client is paused it will continue to automatically look up calls in CRM but it will not take any automatic actions in response. A user can still manually create and open CRM forms from the Main window using the call and entity menus. Test Call This opens the test call window described below. This is useful for testing the ShoreTel CRM Client s search and user settings. Show pop up This allows a popup to be re-shown for the current call or entity. It is useful for testing user settings. Exit This exits the program. It is the only way to shut down the client. Depending on user settings, it may prompt the user before actually exiting. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 9 of 40
Operation Overview Once the client has started and is running, it monitors the user s phone line for calls, both inbound and outbound. When a call occurs, it is tracked and displayed in the client. Based on the information provided with the call, the client will respond in one of three ways: 1. Don't perform any CRM actions for the call. In this state, calls are displayed and the user can put them on and off hold or drop them via functions within the client Main window. No CRM lookup is performed. 2. Use attached ShoreTel call properties specific to MS CRM to create and submit a query to Microsoft CRM based on the values of the call properties. 3. Use the phone number of the call to create and submit a query to Microsoft CRM to look up entities with matching phone numbers. When a query completes, the client responds by associating any returned entities with the call and, if the results are associated with the currently selected call in the call pane, updating the entity pane in main window. Based on user settings and the results of the search, the client may take action in one of several ways: Provide a toaster pop-up window from the tray area with several choices appropriate to the results of the query. Automatically open the ShoreTel CRM Client Main window. Automatically open or create a CRM entity form and/or a CRM Phone Call form possibly related to a found entity. Even if the client performs no automatic action as a result of the lookup results, the user is always free to open the Main window and double click or select and right click the calls and/or any associated entities to display a context menu to select a specific CRM activity related to the call. How a given user configures the application to behave with regard to automatic display of the toaster pop up window and/or Main window and automatic creation of records within Microsoft CRM will depend upon his or her individual preferences and workflow. Client Default Settings The client has a number of settings which affect how the client responds to inbound and outbound calls. Until or unless the user modifies his settings via the Settings menu items, the client will act in a specific way based principally on the two settings dialogs, the User Settings and the CRM Entity Settings. The various setting dialogs are described in the sections below. The default settings result in the following actions in response to both inbound and outbound calls: Assuming the call is an external and has a valid phone number then the ShoreTel client will search CRM's Contact, Account, Leads and Phone Call tables using the phone number associated with the call. Based on the search, one of three results are possible: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 10 of 40
No matching CRM entities: Toaster popup with four choices: Create new Contact (default entity) Create new Phone Call record without regard to any entity. Create new Contact (default entity) and new Phone Call record regarding the new Contact. One matching CRM entity: Note, due to settings, in addition to matching an entity when only one entity is found, the client will also match to an entity if only one Contact is found or one non-phone Call entity is found. Toaster popup with four choices: Open the entity. Create a new Phone Call record regarding the entity, Open the entity and create a new Phone Call record regarding the entity. Multiple matching CRM entities: The Main Window opens with the call selected in the call pane and the found entities shown in the entity pane. Example 1: Call to internal party If the user running the client makes a call to an internal party, no action will result. This is because the call is recognized as internal and ignored. The call would show up in the client's Main Window and could be held or disconnected. However, no CRM related options would be provided and neither the toaster popup nor the Main window would appear. Example 2: Call from external party which doesn't match any CRM records If the user receives a call from an external party and the client gets no matches when it searches CRM then the No matching CRM entities popup would be shown. Example 3: Call from external party which matches an Account and Contact If the user receives a call from a party whose phone number matches one Account and one Contact then the client would default to selecting the Contact and the One matching CRM entity popup would be shown. Example 4: Call to external party which matches an Account and two Contacts If the user makes a call to a party whose phone number matches one Account and two Contacts then the client would not select any single contact and the Multiple matching CRM entities action would cause the main window to open. Example 5: Call from external party which matches one Lead and five Phone Calls 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 11 of 40
If the user receives a call from a party whose phone number matches one Lead and five Phone Call records then the client would select the Lead and the One matching CRM entity popup would be shown. Popup Window The toaster pop-up window scrolls up from the bottom right corner of the user s display in response to the results of call lookups in CRM. When and if it appears depends on the information provided with the call, the results of the search in CRM, and the user s settings. The pop up will show for the time specified in the user setting Show pop up in seconds. It will then slide back down and disappear automatically. As long as the user s mouse is over the pop up window it will continue to display and only when the mouse moves off will the timer start to count down to remove the popup. If the user moves the mouse back over the pop up the timer will reset and only start to count down when the user again moves the mouse off of the pop up window. The user can also close the pop up without waiting for it to time out by clicking the close box in the upper right corner of the pop up window. At the top of the window, the pop up displays the called or calling party s name (if provided by the phone system) and phone number. This is static text and is not clickable. Below this the pop up will display one or more links which the user can click to automatically create and/or open CRM entities or open the ShoreTel CRM Client Main window. There are three flavors of the pop up depending on how many CRM entities the client matches to the phone call s number, zero, one or multiple: No entities matched This pop up has four links. The main link will create a new default entity (in this case a Contact) when clicked. The second link will create a new phone call record within Microsoft CRM (this Phone Call record will not be marked as regarding any entity). The third link will create a new default entity and a Phone Call record regarding the contact. Finally the last link will open the main window so the user can take action not provided by the pop up: One entity matched This pop up has four links also. The main link opens the matching entity. The second link opens a new Microsoft CRM phone call record regarding this entity. The third link opens the matching entity within Microsoft CRM and creates a new phone call record regarding the entity. Finally the last link will open the Main window so the user can take one or more actions not provided by the pop up: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 12 of 40
Multiple entities matched: This pop up has one link which when clicked will open the Main window so that the user can further process the call from there: ShoreTel CRM Client Main Window The main window is shown in a number of ways: Double clicking the tray icon. Right clicking the tray icon and selecting Open Main Window from the pop up menu. Automatically as a result of searching in CRM for a phone number or property associated with a call. Clicking the Open Main Window choice in the pop up window. The graphic below shows the ShoreTel CRM Client Main window: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 13 of 40
The main window contains a number of areas shown from top to bottom: A Menu Bar containing various commands. The client area containing two tabs: Calls Tab containing two panes: The Call Pane shown on top shows all active calls on the user s phone. In addition, depending on settings, recently disconnected calls may also show for some period of time. The Entity Pane shows any entities associated with the currently selected call in the calls pane. Log Tab showing details of actions and activities carried out by the client as well as errors encountered by the client. A Status Bar showing: The status of the MS CRM connection. The status of the ShoreTel phone connection. If the client is paused, an indication of this status. Main Menu Commands The main menu consists of four drop down menus: MS CRM Login or Logout Logs the user in or out of the Microsoft CRM Server as well as connects to the ShoreTel phone system. Logging out and back in is necessary if the user wants to change his login settings. Reload CRM Metadata Forces the ShoreTel CRM Client to reload the CRM metadata from the CRM Server. Because the CRM metadata can take several minutes to load, the client caches the metadata locally rather then reloading it every time it runs. NOTE: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 14 of 40
This can be changed in the user settings to force the client to reload metadata whenever the client logs in. This request should also be used if the administrator or user modifies entities and or attributes contained in the CRM server. Pause or Resume Pauses or resumes the client. When the client is paused it will continue to automatically look up calls in CRM but it will not take any automatic action in response. Test Call Displays the Query MS CRM with Test Call dialog. This dialog is used to test the various CRM search and user settings with a simulated call. See below for a description of the dialog. Settings Group Entities If this menu option is checked, the entities displayed in the entities pane of the main window are shown under group headings. The following graphic shows how the pane appears with the Group Entities setting enabled: And the graphic below shows how the entities pane appears when the Group Entities setting is disabled. Note that the Entity Name column changes to Entity Type:Name to reflect that the entity type is now included as part of the name 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 15 of 40
field: Information Field Names If checked, the display name of the information field used for the entity pane s Additional Information column is shown along with data from the field. The screens above show the information field names enabled while the screen below shows the information field names disabled: On Top If checked, the ShoreTel Client Main window is shown on top of all other desktop windows. User Settings This displays the User Settings dialog explained in detail below. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 16 of 40
CRM Entity Settings This displays the Microsoft CRM Search Settings dialog explained in detail below. Log Phone Events If checked, details of phone events and requests and responses are also logged in the log view tab. This should be checked only for troubleshooting situations Users will find the log is more readable if this is not checked. Clear Log Clears the current log contents. Call The Call menu is disabled unless a call is selected in the call tab s call pane. Depending on the call selected and any selected CRM entities, a number of options specific to the call are presented. This menu is also shown as a drop down menu by right clicking a call from the list of calls. Note that if the selected call is associated with a single entity then the call menu will also contain the choices from the entity menu. Entity The entity menu is disabled unless a call associated with a specific entity is selected in the call tab s call pane or an entity is selected in the call tab s entity pane. This menu is also shown as a drop down menu by right clicking an entity. Client Call Tab Call Pane This pane, seen in the top of the Calls tab, shows any calls active as well as (depending on settings) recently disconnected calls. The information shown for each call includes the called or calling party s name or related CRM entity name, phone number, state of the 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 17 of 40
call, direction of the call (Inbound or Outbound), type (External or Internal) and the duration. Duration is shown from the time the call is first created, not from the time it connects. When a new outbound call is made or a new inbound call presents, the call will be shown in the call pane and automatically selected. Depending on the type of call and availability of a phone number, the client will perform a lookup in CRM and display any related CRM entities in the entities pane and will also possibly automatically select a specific entity. Call Pane Call Types The call pane shows all active calls. Based on the type of call and the results of any CRM lookup, there are several variations in the call icon and name. The following graphic illustrates several different types of calls: The first entry, Test Call: Multiple, select an entity shows a call whose phone number is associated with multiple entities. Selecting the call would show all of the related entities in the entity pane. Selecting a specific entity would then associate the call with that entity. The second entry, Contact: George Bush shows a call whose phone number either matched a single CRM contact record named George Bush or matched more then one entity but either the client or user selected a specific entity to associate with the call. Note that the icon shown is specific to the type of entity. Also note that all custom entities use the same icon. The third entry, Test Call shown with a green phone icon is a call whose phone number was looked up in CRM but failed to find any matching records. Finally, the fourth entry, also Test Call shown with a yellow phone icon, is a call which the client has not attempted to look up in CRM (at least not yet.) In this case, the test call is an internal call so the client doesn t attempt to perform a lookup. It would also skip the 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 18 of 40
lookup if the caller ID was not provided (for an inbound call) or if the caller ID was blocked or invalid or not yet provided (for an external call.) Call Menu The Call menu is only enabled when a call is selected in the Calls tab s call pane. The call menu is accessed from the main menu or more typically as a drop down menu by right clicking a call in the call pane. The contents of the menu change based on the type of the selected call. The graphic below shows the call menu when a single entity is associated with a call (in this case, a contact named Mary Shelly): The Call menu provides several types of commands: Call control commands Calls can be directly answered, dropped, held or un-held from the call menu. The Remove choice is only available for test calls and real idle calls to force the call to be removed from the user interface right away, ignoring any time set in the User Setting Idle call timeout in seconds. CRM entity commands The associated entity (if any) can be opened and/or a CRM Phone Call record can be created and its form opened. Note that if the call is NOT associated with a single CRM entity that the only command shown here will be the command to create a new Phone Call record. This phone call record will not be automatically associated with any CRM entity. Entity creation commands All of the entities defined in the search settings show up here as submenus. The submenus contain two choices, one to create and open a new CRM record of the specified choice and the other to create a new CRM record and a new CRM Phone Call record related to the new entity record: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 19 of 40
Show pop up command This is useful for displaying or re-displaying a popup which has gone away. While all of the commands available in the popup can also be accessed from the main window, this facility can be useful for testing and confirming settings. Note that the bolded choice is the default choice and can be selected by double clicking the call. Via the User Settings, a user can change the default (double click) menu choice. There is a default setting for the scenario where a call is related to a single CRM entity and a separate default setting for the case where it is not related to any CRM entities. Client Call Tab Entity Pane This pane, seen in the bottom of the Calls tab, shows the results of looking up in MS CRM a phone number associated with a call. Any matching CRM entities are displayed. If an entity is selected either automatically by the client or due to a user selecting an entity then that entity is associated with the call. When an entity is associated with a call, the name shown in the call pane will change to reflect the associated entity. Also, when the call is transferred to another user, this association will be remembered by any other ShoreTel CRM clients handling the call. If a user wants to dissociate the currently selected call with any entity then he can click an empty area of the entity pane. Like the Calls pane, right clicking an entity displays a drop down menu of choices specific to the selected entity. These choices are the same as the entity related choices on the call menu when the call is associated with the same entity: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 20 of 40
Client Log Tab As the client starts up, shuts down, responds to calls by searching CRM and responding to user interactions with Calls and CRM entities, it logs what it is doing to the log pane. Viewing this information is helpful if any problems are encountered or if the user wishes to understand why the client responded in a certain way. Any errors encountered should also be logged here so it may be helpful for understanding login or other issues. In addition to viewing CRM related events, the user can also log call related events and interactions made by the client by enabling the main menu s Settings Log Phone Events command. To clear the log view, the user can use the main menu s Settings Clear Log command. The log is also cleared whenever the client shuts down. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 21 of 40
To make a copy of the log, the user can copy all of the text by right clicking in the Log Pane, selecting Select All from the drop down menu and then right clicking the now selected text and selecting Copy from the drop down menu. Finally, paste the text from the clipboard to the body of an email or text file. Query MS CRM with Test Call Dialog This dialog is displayed by selecting the MS CRM Test Call choice from the main menu. It allows a user to generate a simulated call in order to test the various client settings. The top area allows the user to set basic information which is used to drive the client lookup. This includes the calling or called party number and name as well as the direction and type of the call. In addition to performing a lookup based on caller ID, the client also supports a ShoreTel Call Property based lookup. Note that just as for real calls, any searching based on CRM call properties takes precedence over searching based on the phone number. Microsoft CRM call properties are described in further detail in Appendix B. To set one or more CRM call properties, select the entity and attribute to search on, fill in a value and click the Add button. A user can add more than one CRM call property to search on by adding additional entity/attribute/value sets. If more than one CRM call 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 22 of 40
property is set for a given call then they are and-ed together. In other words, adding additional values makes the search more restrictive. The system itself uses a call property to associate a call to a specific entity so that transferred calls are pre-associated with a specific CRM entity. See the appendix which describes the call property feature in more detail. User Settings Dialog The user settings dialog controls the client s response to looking up CRM entities as well as a number of aspects of the client user interface and operation. This describes each set of controls in the dialog: CRM lookup results actions: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 23 of 40
This group of six drop down lists handle how the client responds to both inbound and outbound calls based on no matching CRM entities, one matching CRM entity or multiple matching CRM entities. Default menu choice: These two drop down lists set the default menu option which is the choice executed if the user double clicks a call in the call tab call pane. The user can set the default for the case where no entity is associated with the call or where multiple entities are associated with the call. Default Entity: This drop down list selects the Default Entity used by the client. The client uses this in two locations: 1. In support of the Default menu choice No matching entities: list box selections. 2. In support of the If multiple entities are found then match one entity if One Default Entity is found check box. If multiple entities are found then match one entity if: These two check boxes control if the client will try to select a single CRM entity to associate with a call if multiple entities are found. One Default Entity is found: If checked, and multiple entities are found as a result of the CRM search but only one entity of the default entity type is found then the client will automatically associate the returned default entity with the call. One entity along with one multiple Phone Call entities are found: If checked, and multiple entities are found as a result of the CRM search but a single non-phone Call entity is found then the client will automatically associate the returned non-phone Call entity with the call. When user opens or creates an entity: These two check boxes control how the client responds when the user clicks on the popup or invokes an option from the main window. Answer ringing calls: If checked and the call the user is responding to is currently ringing the user s phone, then the client will attempt to automatically answer the call. This will only work with analog phones if they are in an off hook idle state. Close main window: If checked then the main window is closed automatically when the user invokes an action involving the call or its related entity. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 24 of 40
Create Phone Call settings: Create without showing the form: If checked, the phone call record will be created but not opened and shown to the user. Checking this option will uncheck the next option, Prompt user for details. Prompt user for details: If checked, the user will be prompted with the Phone Call Details Window (see below) whenever he creates a new Phone Call record. This allows him to explicitly set the subject and description rather then having the client automatically generate them before the CRM record is created and the Microsoft form opened. Checking this option will uncheck the previous option, Create without showing the form. Change to completed on disconnect: If a phone call activity is created, by default it has a status of Open. If this option is checked then when the call disconnects, the corresponding phone call activity will have its status changed to completed. Show pop in seconds: Select how long the tray popup will display before automatically hiding. Idle call timeout in seconds: Select how long calls which have been disconnected and gone to an idle call state should continue to show in the client s main window. Cache CRM metadata: If this is checked then CRM metadata is only reloaded when explicitly requested. If this is not checked then CRM metadata will be reloaded whenever the client restarts. For more information, see the section above Requesting MS CRM Metadata in the Application Startup section above. Automatically run when user logs into Windows: If checked, the client will add itself to the user s Windows registry setting so that it will automatically run whenever the user logs into Windows. Prompt before exiting: If checked, the user is prompted to confirm that he wants to exit the application when he attempts to exit via the tray icon menu s Exit choice. Show pop-up on left vs. default right: If checked then the pop-up window will show on the the left side of the screen. If unchecked then the pop-up will show on the right side of the screen. Country Code: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 25 of 40
This is used when the client is searching for a number. If a number begins with the country code then it is removed from the number before searching. This way we will find associated entities if they are formatted without the user's country code. Auto reload metadata changes at startup: If checked then at startup, if the metadata is determined to have changed, then a new copy of the metadata is automatically downloaded from the CRM server. If unchecked then the previously downloaded copy is used and a message is written to the log. As most users won't care about changes to the metadata and their client will function fine with an older copy making the metadata download optional allows user to decide when and if they want to download metadata. This allows users who are connected via a WAN or other slower speed connection to their CRM server to avoid potentially unnecessary load. OK, Cancel and Apply: Click OK to save changes and hide the dialog. Cancel throws away changes since the last time changes were saved and hides the dialog. Apply saves the changes but continues to show the dialog. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 26 of 40
CRM Entity Settings Dialog This dialog is used to set the specific entities and attributes to be queried to discern if they contain a phone number which matches the phone number associated with a call. All entities defined can also be automatically created by, depending on settings, clicking on a pop up link or via the call menu. Additional properties of the entity used by the ShoreTel client can also be specified. These include the information field shown as part of the details of a retrieved CRM entity and the fields filled in by the client when it is creating a new entity in response to a user-initiated or automatic action involving a call. Note that the search settings are stored in a file separate from the user s other settings. See the appendix for information on how to access this file and copy it for other users to use. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 27 of 40
Entities and phone number attributes to search and create This displays the currently configured CRM entities and phone number attributes which will be searched by the ShoreTel client for a new call in cases where the call does not have a CRM call property set. To add a new entry, select the entity and attribute and click the appropriate add button. Add entity to search Select an entity from the drop down list to add it to the Entities and phone number attributes to search or to edit its properties or add and remove its specific attributes to search for phone numbers. Add phone number attributes to search Select an attribute specific to the selected entity from the drop down list to add or remove it from the attributes to search for phone numbers. NOTE: If a user does not want records of the entity type to be found by the client s search feature then they should not add any phone number attributes for the entity. Entity Properties This section controls the settings specific to the currently selected entity which are used by the ShoreTel client. Show these fields in the Main window and pop up shows the entity attribute used for the entity s name (this comes from CRM and cannot be changed) and the attribute used to display as the entity s information. This is shown in the pop up and in the Additional Information column of the main window call tab entity pane. Fill in these fields when creating a new record specifies the entity attribute fields automatically populated with data when the client creates a new entity. While the phone field will always be filled in, the call may not have any call name available in which case this will be set to an empty string. Note that the fields set by the client when creating new CRM Phone Call records cannot be set and are hard coded within the ShoreTel client. NOTE: A user must set at least the Phone Number if he wants to be able to create instances of the entity from the ShoreTel client interface. Search entity on OUTBOUND calls if checked will cause the entity to be searched on outbound calls. All entities with phone attributes are searched for inbound calls. If the user only wants to create entities of a certain type but never search on these entities then he could remove any phone number attributes. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 28 of 40
OK, Cancel, Apply and Reset Click OK to save changes and hide the dialog. Cancel throws away changes since the last time changes were saved and hides the dialog. Apply saves the changes but continues to show the dialog. Finally, Reset returns the search settings to the values that were established when the program was first installed. Creating CRM Entities For an entity to be creatable by the client (i.e., to appear in menus and the pop up) it needs to be defined in the client s CRM Entity search settings and have its Phone Number field entity property set. A new CRM entity can be created by the ShoreTel CRM Client in a number of ways: Depending on user settings, as a result of a user clicking on a link in the pop up shown when the call s phone number doesn t match any CRM entities. Depending on user settings, as a result of double clicking the call in the main window when the call s phone number doesn t match any CRM entities. Depending on user settings, automatically when the call s phone number doesn t match any CRM entities. As a result of selecting a create Call menu choice for the call from the Main window. The client uses the Microsoft CRM web services interface to create the entity and populates the entity s Phone Number field in the client s search settings and optionally the Name field. Assuming the request is successful, the client then uses the new entity record ID to form a CRM URL for the entity form and opens an Internet Explorer Web Browser to display the form. So, for example, when a call is received from a caller at phone number (203) 222-9876 with a name of Jones, John, depending on configuration we might get a pop up like this: If the user then clicked on the No matching entities: Create a new Contact link then the client would create and open a new CRM contact record: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 29 of 40
Note that the name and phone numbers are set on the General and Contact Information tabs of the contact record: Creating Phone Call Records Phone call records (also referred to herein as simply phone calls ) are special entities in the ShoreTel client and are handled differently then other entities. Specifically, a user can always create a phone call even if they don t have a phone call listed in their search settings. In addition, as an alternative to creating or opening an entity, a user can also create a new phone call entity which is automatically related to the new or opened entity. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 30 of 40
So, for example, if a call s phone number matches a contact, the user has the option of viewing the contact, creating a new phone call related to the contact, or both. This is true for all entity types which can be created or retrieved based on the search settings. When the ShoreTel client creates a new CRM phone call, it first checks the user s settings to see if the Prompt user for details under the Create Phone call settings is checked. If so then the user will be prompted with the Create Phone Call Record dialog: The Subject is set to an auto-generated name consisting of the date (yyyy-mm-dd) followed by the time (HH:MM:SS) and the calling CRM entity name or call name and phone number. The user can enter a new subject or keep the default. They can also enter a description and then click Create to create the new phone call record or Create and Open to first create a new phone call record and then open the corresponding CRM form. Finally, if the user changes his mind and decides he does not want to create the phone call he can click Cancel. If the user s setting Prompt user for details under the Create Phone call settings is not checked then the phone call entity will be automatically created and the subject set to the auto-generated subject with the details left blank. The following graphic shows the phone call record created by a user with the various values set by the client enumerated: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 31 of 40
#1 & #2: The Sender, if the call is outbound, or the Recipient, if the call is inbound, is set to the CRM user name of the user who created the phone call record. If the phone call was created in association with a CRM entity and the type of that entity is: Account Contact Lead System User Then the Sender, if the call in inbound, or the Recipient, if the call is outbound, is set to the name of the related entity. #3: The Phone Number is filled in with the call s phone number. #4: The Direction is set to the direction of the call, either incoming or outgoing #5: The Subject is either auto generated or as set in the Create Phone Call Record dialog. #6: The Description of the phone call is set if the Create Phone Call Record dialog was used and the Description filled in. #7: Regarding is set to the related CRM entity assuming the phone call was created regarding an entity. #8: The Owner is set to the user creating the phone call. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 32 of 40
#9: The Duration is set to the length of the phone call. Note that this is only set once the call disconnects and will only be seen if the Phone Call form is reopened or if an open form is refreshed. Appendix A: Using the CRM Entity Settings to handle a custom attribute Assume for this example that an organization added phone numbers to the CRM Case (schema name incident ) and would like to be able to also find these records. They also want to be able to create new cases directly from the client in response to calls and have the phone number and caller name (if available) set into the new case records automatically. 1) Open the CRM Entity Settings dialog and in the Add entity to search group select Case (incident): 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 33 of 40
2) In the Add phone number attribute to search, select the field name of the field containing the phone number. For this example a field called Installer Phone (CFSdealerphone) is shown : 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 34 of 40
3) Now click the Add button next to the attribute selection. The newly added Case entity and Installer Phone attribute should now appear in the search list: 4) A user can also optionally select one of the Case Fields to show as the information field in the toaster pop up and in the main window s entity pane. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 35 of 40
Select Case Number (ticketnumber): 5) In order to be able to create new cases from the client, a user needs to set the Entity properties, Phone Number field. This controls the field set by the client with the call s phone number when it creates a new entity. Set both the Phone 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 36 of 40
Number and Name fields as shown below and apply the changes: 6) If the user wants to also search for cases on OUTBOUND calls by looking at his Installer Phone fields, he could check the Search entity on OUTBOUND calls. 7) This completes the configuration. Now when a call presents (or is placed) the ShoreTel client will search across all Cases looking for any records which have an Installer Phone which matches the call s phone number. When Cases are shown in the pop up or in the main window, they will also show the value of the Case Number (if any.) Finally, the user will now be provided with choices on the call and user settings menus to create Cases and related phone calls. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 37 of 40
Appendix B: ShoreTel CRM Call Properties When an inbound call presents to the ShoreTel client, before the software checks the caller ID and uses that to search the CRM entities and attributes configured in the search settings, it checks to see if the call has any attached ShoreTel CRM call properties. If there are any CRM call properties, these are used to look up any matching record(s) in Microsoft CRM. The ShoreTel CRM Client uses Call properties in two ways: 1) To remember the association to a single entity that a user makes in case the call is transferred to another client user. For example, if a call presents and is associated with multiple CRM entities, the first agent to handle the call might determine which of several contacts is the caller and by either opening his CRM form or creating a phone call record, would associate the entity with the call. Internally, whenever an entity is associated with a call, the CRM client sets or clears the corresponding call property on the call. 2) To support integration with other applications as a way to allow users to use the client to show a specific page or set of pages. A call property consists of a name and a value. Because call properties are used by other applications including some ShoreTel system applications, this client follows the following format to recognize and parse the names of the CRM call properties: The name must start with the prefix _ST_CRM. This is followed by a dot. Next must be the CRM database schema name of a valid CRM entity in the user s CRM server. For example, contact or incident. This is followed also by a dot. The last part of the name is the CRM database schema name of a valid CRM attribute for the entity in the user s server. For example, contactid. So, as an example, if a call is associated with a single entity then it will have a call property set with a name of: _ST_CRM.contact.contactid The value of the property is always a text string. The CRM lookup is based on searching for all entities which have a matching value for the specified attribute. For example, for _ST_CRM.contact.contactid call property, the value would be a text representation of the contact ID from CRM, for example: 9806482f-7e25-dc11-8648-0030f10c7d87 ShoreTel CRM Call properties are a feature of the ShoreTel phone system. Any application which uses the ShoreTel telephony interface and the ShoreTel Developer Network SDK is free to attach and view call properties attached to calls. For example, an interactive voice response system (IVR) could be built to run on a 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 38 of 40
ShoreTel server. It could handle inbound callers, interact with them by soliciting information and then, based on some kind of lookup using Microsoft s CRM SDK and Microsoft s web services interface could set a ShoreTel CRM Call property on the call to associate the call to a specific CRM entity, for example, a contact record. Then when the IVR transfers the call to an agent s phone, if that agent is running the ShoreTel CRM Client then the client will not search based on the caller ID but instead will display the results of a search using the call properties. Note that if multiple call properties are set on a call that that any entities returned must have all of the properties set to same values as the call properties. Note that the Test Call feature can be used to simulate a call with attached call properties. For example, this test call shows a query where we are asking to get back all contacts which have donotcall set to False AND donotmail also set to False: 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 39 of 40
Appendix C: Copying CRM Entity (Search) Settings The CRM Entity (Search) settings are stored in a location separate from other user settings. This is done in a way so as to facilitate copying of the search settings from one user to another. These instructions detail how to find the search settings file written by one client user and copy it to replace another client user s search settings. This procedure is a one time process which would have to be repeated every time the search settings need to be updated. 1. On the machine whose settings you wish to copy, locate the file named PhoneSearch.crm stored in the ShoreTel directory of the user s application data directory. In Windows, this is stored in the Application Data directory which is contained in a directory with Windows user name in the Document and Settings directory, usually stored on the C: drive. For example, for user name MARYJONES the file would be located at: C:\Documents and Settings\MARYJONES\Application Data\ShoreTel\STMSCRMClient\PhoneSearch.crm 2. Either make the file accessible to the user at the destination machine or copy the file to a location where it can be accessed. 3. From the destination user, stop the ShoreTel CRM Client if it is running, then copy the file to the equivalent location as described in step 1 for the destination user. 4. Start the ShoreTel CRM Client. The client s search settings should now reflect the search setting of the source user s file. 2/3/2014 ShoreTel MS Dynamics CRM Integration (V5.x) Page 40 of 40