Favorite Views for Microsoft Dynamics CRM 4.0

Transcription

1 Favorite Views for Microsoft Dynamics CRM 4.0 Setup Guide, Version August 6, 2009 Copyright Stunnware GmbH 2009 Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 1

2 This document guides you through the steps required to successfully install and configure the Favorite Views for Microsoft Dynamics CRM 4.0 add-on. CONTENTS Download the setup files... 3 Installation... 3 Installing the Favorite Views Web... 3 Adding additional languages... 3 Installing the Configuration Tools... 4 Installing on the Offline Client... 4 Configuring an organization... 5 Importing Customizations... 5 Registering the Favorite Views Plug-In... 7 Adjusting the CRM security to allow access to the Favorite Views custom entity... 9 Importing licenses Updating installations Updating the Favorite Views Web Updating the Plug-In Updating Customizations Removing the Favorite Views add-on from an organization Removing the Favorite Views Plug-In Removing Customizations Uninstalling the add-on Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 2

3 DOWNLOAD THE SETUP FILES If you haven't done so already go to the Stunnware web site at and download the latest setup packages. There are two separate downloads and you need both of them to continue: The Favorite Views.zip file contains the setup for the Favorite Views Web. It has to be installed on each CRM application server. The Favorite Views Configuration.zip file contains the CRM customizations that have to be added to any organization where you want to enable the add-on. It also contains commandline tools for automated configurations. INSTALLATION Installation is supported on the CRM Server and the CRM Outlook Offline Client. Please read the information carefully if you plan to deploy the add-on to the clients though, as you need to change some configuration settings. The add-on is designed to run on-premise, in hosted installations accessed over the Internet and offline. CRM Online is not supported. Installing the Favorite Views Web The Favorite Views Web is an add-on that integrates into the ISV folder of the CRM Application Server. If you have multiple CRM Application Servers then you must install it on each of them separately. Extract the Favorite Views.zip file into a directory on the CRM Application Server. There are three files contained therein: setup.exe contains the code to start the installation on a 32-bit machine. setup64.exe contains the code to start the installation on a 64-bit machine. Stunnware Favorite Views.msi is the installer package. Start setup64.exe when installing on a 64-bit CRM Application Server. Use setup.exe on a 32-bit CRM Application Server. The setup procedure consists of a few dialogs. Just accept the default values to install the application. To verify a successful installation, please open the CRM Web after setup has finished. You should see the Stunnware.Crm4.FavoriteViews.Web.dll file in the bin folder and the Stunnware/FavoriteViews folder structure beneath the ISV folder. If you don't see these files, then you can manually copy these files. They are located in the CrmWeb folder of the installation folder, usually C:\Program Files\Stunnware\Favorite Views for Microsoft Dynamics CRM 4.0\CrmWeb. Adding additional languages The Favorite Views Web supports multiple languages, but only German (locale identifier 1031) and US English (locale identifier 1033) are included in the product. To add additional languages do the following: Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 3

4 1. Open the /ISV/stunnware/FavoriteViews/resources folder. Create a copy of one of the existing XML files and rename it to <Locale Id>.xml, where "Local Id" is the locale identifier of the language. Please refer to for a complete list. 2. Open the file in a text editor and translate the strings. The language file used by the Favorite Views add-on is based on the user's language settings in CRM. We welcome any translated files to include them in an update. Feel free to send them to michael.hoehne@stunnware.com. Installing the Configuration Tools The configuration tools can be installed on any machine having the Microsoft.NET Framework 3.0 installed. They can be used to configure any CRM organization in your local environment. Internet connections and the HTTPS protocol are not supported in the command line tools, but you can still configure these systems manually. Extract the Favorite Views Configuration.zip file into a directory on the machine you want to use to configure the Favorite Views add-on. There are two files contained in the zip package: setup.exe contains the code to start the installation. Stunnware Favorite Views Configuration.msi is the installer package. Start setup.exe to install the configuration tools. Installing on the Offline Client You can install the Favorite Views Web on machines running the Microsoft CRM Outlook Offline client to let users change their settings in offline mode. The installation process is identical to the server installation. To show the Favorite Views menu in the Workplace area you have to change the sitemap though. <SubArea Id="navSwFavoriteViewsWeb" Url="/isv/stunnware/favoriteviews/settingsFrame.aspx" Icon="/isv/stunnware/favoriteviews/img/favoriteViews.png" PassParams="1" Client="Web,OutlookWorkstationClient"> Change Client="Web,OutlookWorkstationClient" to Client="All" if you want to use the Favorite Views web offline. The plug-in (see next chapter) is registered to run online only by default. Be sure to read the Notes section in the Registering the Favorite Views Plug-In chapter if you are planning to use the plug-in offline. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 4

5 CONFIGURING AN ORGANIZATION The tasks in this chapter have to be performed per CRM organization where you want to use the Favorite Views add-on. Importing Customizations The Favorite Views add-on needs a custom entity to store the user settings. You also need to make the Favorite Views Web accessible to the user in an easy way. Both actions can be done manually or with a command line tool. All files mentioned in this chapter are located in installation folder of the Configuration Tools, usually C:\Program Files (x86)\stunnware\favorite Views for Microsoft Dynamics CRM 4.0 Configuration. Manual Import Importing the Favorite Views custom entity Open the Microsoft Dynamics CRM 4.0 Web Client and navigate to the Settings area, then click Import Customizations. Select the FavoriteViewsCustomizations.zip file from the Configuration Tools folder. Upload the import file and import the Favorite View entity. In the Microsoft Dynamics CRM 4.0 Web Client navigate to the Settings area, then click Customize Entities. Select the Favorite View entity and publish it. Modifying the Sitemap to display the Favorite Views Settings page Navigate to the Configuration Tools folder and open the Sitemap.xml file: <SiteMap> <Area Id="Workplace" ResourceId="Area_Workplace" ShowGroups="true" Icon="/_imgs/workplace_24x24.gif" DescriptionResourceId="Workplace_Description"> <Group Id="Extensions" ResourceId="Group_Extensions"> <SubArea Id="navSwFavoriteViewsWeb" Url="/isv/stunnware/favoriteviews/settingsFrame.aspx" Icon="/isv/stunnware/favoriteviews/img/favoriteViews.png" PassParams="1" Client="Web,OutlookWorkstationClient"> <Titles> <Title LCID="1033" Title="Favorite Views"/> </Titles> <Privilege Entity="sw_favoriteview" Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 5

6 Privilege="Create,Read,Write"/> </SubArea> </Group> </Area> </SiteMap> The framed part defines a new subarea displaying the Favorite Views menu. The above sample places it into the Extensions section of the user's workplace, but you can put it wherever it makes sense. For more information on how to edit the CRM Sitemap please refer to the Microsoft Dynamics CRM SDK documentation. The Client="Web,OutlookWorkstationClient" value in the SubArea node enables the new item only when online. Set it to Client="All" if you plan to install the Favorite Views Web on the offline clients. Using the ImportCustomizations command-line tool Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to import the custom entity, add the sitemap extensions and publish the changes: ImportCustomizations mode=import server=crmserver:5555 org=crm Modify the server name, port and organization as needed. Note that the server must point to a CRM Platform Server. You can specify additional parameters, which are described in the console when starting the ImportCustomizations tool without or with wrong or insufficient parameters: ============================================================================= Usage: ImportCustomizations parameters Parameters Parameters are specified in the following format: key=value Sample: org=crm server=crmserver:5555 Mandatory Parameters org: Unique name of the CRM organization server: Name and Port of the CRM Platform Server mode: Either Import or Remove. Optional Parameters user: The account to use. If not specified the currently logged on user is used. password: The password of the user account specified in the user parameter. Ignored when the user parameter is not specified. sitemap: Specify Yes to change the sitemap or No to leave it unchanged. The default is Yes. Sample Import Command Line ImportCustomizations mode=import server=crmserver:5555 org=crm Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 6

7 Sample Remove Command Line ImportCustomizations mode=remove server=crmserver:5555 org=crm Registering the Favorite Views Plug-In A plug-in is required to filter the available views based on the user settings. It can be registered manually or with a command line tool. All files mentioned in this chapter are located in installation folder of the Configuration Tools, usually C:\Program Files (x86)\stunnware\favorite Views for Microsoft Dynamics CRM 4.0 Configuration. Manual Registration Start the Plugin Registration Tool from the Microsoft Dynamics CRM 4.0 SDK and connect to the organization you want to configure. Click on the Import Solution button and select the Favorite Views Registration.xml file from the Configuration Tools folder and import the file. Using the InstallPlugin command-line tool Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to register the plug-in in the CRM database: InstallPlugin mode=register server=crmserver:5555 org=crm Modify the server name, port and organization as needed. Note that the server must point to a CRM Platform Server. You can specify additional parameters, which are described in the console when starting the InstallPlugin tool without or with wrong or insufficient parameters: ============================================================================= Usage: InstallPlugin parameters Parameters Parameters are specified in the following format: key=value Sample: org=crm server=crmserver:5555 Mandatory Parameters org: Unique name of the CRM organization server: Name and Port of the CRM Platform Server mode: Either Register, Unregister or Update. Optional Parameters user: The account to use. If not specified the currently logged on user is used. password: The password of the user account specified in the user parameter. Ignored when the user parameter is not specified. deployment: Database (default), Disk or GAC. When choosing Disk, you have to Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 7

8 clients: copy the stunnware.crm4.favoriteviews.dll assembly into the server/bin/assembly subfolder of the Microsoft Dynamics CRM installation directory. Use the database deployment to support offline clients. Online (default), Offline or Both. Online enables the Favorite views only when connected to the CRM Server, while Offline enables it only in the Outlook Offline Client. Both enables it online and offline. Sample Register Command Line InstallPlugin mode=register server=crmserver:5555 org=crm Sample Update Command Line InstallPlugin mode=update server=crmserver:5555 org=crm Sample Unregister Command Line InstallPlugin mode=unregister server=crmserver:5555 org=crm Notes Microsoft has implemented a special offline security for plug-ins. If you want to use the plug-in offline then you have to add the registry key HKCU\Software\Microsoft\MSCRMClient\AllowList\1a5ae06f73e74860 to the client machines, as shown in this picture: CRM will not function properly if register the plug-in for offline use but don't add this key. CRM will deny loading the plug-in and throw an exception, causing the CRM views to fail loading. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 8

9 Adjusting the CRM security to allow access to the Favorite Views custom entity To use the Favorite Views add-on, a user must have read, create and write privileges on the Favorite Views entity and read access to the CRM Metadata. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 9

10 IMPORTING LICENSES You need a license for each CRM Application Server hosting the Favorite Views Web and for each CRM Platform Server running the Favorite Views Plug-in. If your CRM Server has both the Application Server and Platform Server role then only a single license file is required. If you don't have a license file then you can request a 60-day evaluation. Please visit the product page on the Stunnware web site at for more information. Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to import the license: ImportLicense "Path to license file" Don't forget to put quotes around the filename if it contains spaces. The license is validated during the import process and any problems are written to the console window. Licenses are not required in offline mode. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 10

11 UPDATING INSTALLATIONS New versions of the Favorite Views add-on may be made available by Stunnware. Follow these instructions to apply them to your system. Also look for additional information on the Stunnware web site. Updating the Favorite Views Web Download the Favorite Views setup package from the Stunnware web site and follow the instructions in the Installation is supported on the CRM Server and the CRM Outlook Offline Client. Please read the information carefully if you plan to deploy the add-on to the clients though, as you need to change some configuration settings. The add-on is designed to run on-premise, in hosted installations accessed over the Internet and offline. CRM Online is not supported. Installing the Favorite Views Web chapter. The installer will update an existing installation automatically. Updating the Plug-In Download the Favorite Views Configuration setup package from the Stunnware web site and follow the instructions in the Installing the Configuration Tools chapter. The installer will update an existing installation automatically. For a manual update please follow the steps to remove the plug-in from an organization and configure the plug-in as described in the Registering the Favorite Views Plug-In chapter. We recommend using the Configuration Tools to perform the update though. Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to update the plug-in in the CRM database: InstallPlugin mode=update server=crmserver:5555 org=crm Modify the server name, port and organization as needed. Note that the server must point to a CRM Platform Server. You can specify additional parameters, which are described in the console when starting the InstallPlugin tool without or with wrong or insufficient parameters. For more information about the parameters please refer to the Configuring an organization chapter. Updating Customizations Newer customizations are imported in the same way as described in the Importing Customizations chapter. There is no update switch in the ImportCustomizations command-line tool. Just use the same command line as used when configuring the organization for the first time. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 11

12 REMOVING THE FAVORITE VIEWS ADD-ON FROM AN ORGANIZATION Remove the customizations from an organization can be done manually or by using the Configuration Tools. Removing the Favorite Views Plug-In All files mentioned in this chapter are located in installation folder of the Configuration Tools, usually C:\Program Files (x86)\stunnware\favorite Views for Microsoft Dynamics CRM 4.0 Configuration. Manual Removal Start the Plugin Registration Tool from the Microsoft Dynamics CRM 4.0 SDK and connect to the organization you want to configure. From the list of registered plug-ins select the Stunnware.Crm4.FavoriteViews.Plugin assembly and click the Unregister button. Using the InstallPlugin command-line tool Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to register the plug-in in the CRM database: InstallPlugin mode=unregister server=crmserver:5555 org=crm Modify the server name, port and organization as needed. Note that the server must point to a CRM Platform Server. You can specify additional parameters, which are described in the console when starting the InstallPlugin tool without or with wrong or insufficient parameters. For more information about the parameters please refer to the Configuring an organization chapter. Removing Customizations All files mentioned in this chapter are located in installation folder of the Configuration Tools, usually C:\Program Files (x86)\stunnware\favorite Views for Microsoft Dynamics CRM 4.0 Configuration. Note: Removing the entity will also remove stored user settings. Manual Removal Removing the Favorite Views custom entity Open the Microsoft Dynamics CRM 4.0 Web Client and navigate to the Settings area, then click Customizations. Select the Favorite View entity and delete it. Modifying the Sitemap to display the Favorite Views Settings page Export the sitemap and open the exported XML file in a text editor. Remove the extensions you made when configuring the organization. Upload and import the modified sitemap. For more information on how to edit the CRM Sitemap please refer to the Microsoft Dynamics CRM SDK documentation. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 12

13 Using the ImportCustomizations command-line tool Open a Command Window and change the directory to the folder containing the Configuration Tools. Run the following command to import the custom entity, add the sitemap extensions and publish the changes: ImportCustomizations mode=remove server=crmserver:5555 org=crm Modify the server name, port and organization as needed. Note that the server must point to a CRM Platform Server. You can specify additional parameters, which are described in the console when starting the ImportCustomizations tool without or with wrong or insufficient parameters. For more information about the parameters please refer to the Configuring an organization chapter. UNINSTALLING THE ADD-ON Follow these steps to completely remove the Favorite Views add-on from your environment: 1. Remove the customizations from all organizations. Please refer to the Removing the Favorite Views add-on from an organization chapter for more information. 2. Remove the Favorite Views Web on the CRM Application Server. Open the Control Panel and select Add/Remove Programs or Programs and Features. Select the Favorite Views for Microsoft Dynamics CRM 4.0 and click the Uninstall button. Repeat this step on all CRM Application Servers where you have installed the add-on. 3. Remove the Favorite Views Configuration Tools. They can also be uninstalled through the Control Panel. Favorite Views for Microsoft Dynamics CRM 4.0 P a g e 13