ISV.config

The ISV.config.xml file allows you to integrate custom Web pages into the Microsoft CRM application. By editing the ISV.config file in conjuction with the site map functionality you learned about in Chapter 6, "Entity Customization: Relationships and Custom Entities," you can create a highly customized application navigation for your Microsoft CRM users. Some exciting enhancements in Microsoft CRM 3.0 ISV.config file include the ability to add buttons and action menu links to the grid toolbar, JavaScript code support for menus and buttons, and access to the parent window. Microsoft CRM includes a default ISV.config.xml file in the <web installation path>\_Resources\ folder, but the ISV.config features are disabled by default.

More Info 

You can get more information about the ISV.config in the Client Programming Guide of the SDK.

Integration Areas

Figure 10-10 shows the areas in the main application window that you can customize with the ISV.config file. As you can see in this figure, we added some sample buttons and menu items to illustrate how the ISV.config customizations will appear in the user interface. You may add custom buttons or menus to the following areas of the application navigation:

1. Application menu bar

2. Application toolbar

3. Grid toolbar

4. Grid actions menu

Figure 10-10: Application integration points

In addition to the application navigation, you can also customize the entity form. Figure 10-11 displays the integration areas that the ISV.config offers in an entity form window. You may customize the following:

1. Detail form menu bar

2. Toolbar

3. Navigation pane

Figure 10-11: Entity form integration points

Note 

You can't customize the application navigation pane by using the ISV.config file, but you can customize the entity navigation pane. Chapter 6 explains how to customize the application navigation pane by using the site map.

The following code snippet is from the ISV.config.xml file that ships with Microsoft CRM. We will discuss the meaning of the elements available in this file next.

 <configuration version="3.0.0000.0">  <Root>   <MenuBar>    <CustomMenus>     <Menu Title="ISV">      <MenuItem Title="New Window" Url="http://www.microsoft.com" />     </CustomMenus>    </MenuBar>    <ToolBar>     <Button Title="Test" ToolTip="Info on Test" Icon="/_imgs/ico_18_debug.gif" JavaScript="alert('test');" />    <ToolBarSpacer />   </ToolBar>  </Root>  <!-- Microsoft Customer Relationship Management Entities (Objects) -->  <Entities>   <Entity name="account">    <MenuBar>     <CustomMenus>      <Menu Title="ISV">       <MenuItem Title="Coming Soon..." Url="http://www.microsoft.com" PassParams="0" WinMode="1" />       <MenuSpacer />       <SubMenu Title="Sub Test">        <MenuItem Title="Test Sub 1" Url="http://www.microsoft.com" PassParams="1" />        <MenuSpacer />        <MenuItem Title="Test Sub 2" />       </SubMenu>      </Menu>     </CustomMenus>    </MenuBar>    <ToolBar ValidForCreate="0" ValidForUpdate="1">     <Button Title="asdf" ToolTip="Info on Test" Icon="/_imgs/ico_18_debug.gif" Url="http:// www.microsoft.com" PassParams="1" WinParams="" WinMode="0" />     <ToolBarSpacer />     <Button Title="Test" ToolTip="Info on Test" Icon="/_imgs/ico_18_debug.gif" Url="http:// www.microsoft.com" PassParams="1" WinParams="" WinMode="1" />     <Button Title="Web Only" ToolTip="Web client only. This will not show up in any outlook pages." Icon="/_imgs/ico_18_debug.gif" JavaScript="alert('test');" Client="Web" />     <Button Title="Outlook Only" ToolTip="Outlook Only -  This is available offline also." Icon="/_imgs/ico_18_debug.gif" JavaScript="alert('Test');" Client="Outlook" AvailableOffline="true" />    </ToolBar>    <NavBar>     <NavBarItem Icon="/_imgs/ico_18_debug.gif" Title="ISV Default" Url="http:// www.microsoft.com"  />    </NavBar>    <Grid>     <MenuBar>      <ActionsMenu>       <MenuItem Title="Coming Soon..." Url="http://www.microsoft.com" WinMode="1" />       <MenuSpacer />      </ActionsMenu>      <Buttons>       <Button Title="Test" ToolTip="Info on Test" Icon="/_imgs/ico_18_debug.gif" Url="http://www.microsoft.com" WinParams="" WinMode="2" />       <ToolBarSpacer />     </MenuBar>    </Grid>   </Entity> </configuration> 

Menu Bar

As you just saw, editing the ISV.config.xml file allows you to add menu links to the main application, the entity form, and a grid's Actions menu. As the sample configuration file shows, adding a <MenuBar> node beneath the <Root> node will add custom menus to the application. To create a custom menu on the entity's form, you would need to place a <MenuBar> directly beneath the <Entity> node.

The <MenuBar> node requires a <CustomMenu> node. The <CustomMenu> node can contain <MenuItem> nodes that have the attributes listed in Table 10-9 to further define your custom menu links.

Table 10-9: <MenuItem> Attributes
Open table as spreadsheet

Attribute	Availability	Description
AvailableOffline	Entity and grid only	Defines whether the link should appear in the Outlook client if the client is offline. Valid options are True and False.
Client	All	Defines which client applications the link should appear in. Valid options are Web and Outlook. If you leave this blank or ignore the node, the menu item will display in both client applications.
JavaScript	All	If populated, Microsoft CRM will execute the JavaScript. If populated, the Url attribute will be ignored.
PassParams	Entity and grid only	If set to 1, Microsoft CRM will pass the entityid and enititytypecode of the entity form to the new window. Valid options are 0 (don't pass parameters) and 1 (pass parameters).
Title	All	Displays the label that appears to the user.
Url	All	Microsoft CRM will open a window to the path specified in this attribute. If the JavaScript attribute is populated, the Url attribute will be ignored.
ValidForCreate	Entity and grid only	Displays menu item when the entity form is in create mode. Valid options are 0 (don't display) and 1 (display).
ValidForUpdate	Entity and grid only	Displays menu item when the entity form is in update mode. Valid options are 0 (don't display) and 1 (display).
WinMode	All	Determines the type of window to open. Valid options are: 0 (normal window) 1 (modal dialog box) 2 (modeless dialog box)

The following code snippet from the ISV.config.xml file shows how to add a custom menu that would display within the main application window.

 <Root>  <!-- The main Global Menu Bar located at the top of all root level areas -->  <MenuBar>   <CustomMenus>    <Menu Title="Custom Menu">    <MenuItem Title="Corporate Web Site" Url="http://www.fabrikam.com" />    <MenuSpacer />    <!-- A horizontal drop down menu spacer -->    <SubMenu Title="Sub Menu">     <MenuItem Title="Sub Menu 1" Url="http://www.fabrikam.com/submenu1.aspx" WinMode="2" />     <MenuItem Title="Sub Menu 2" Url="http://www.fabrikam.com/submenu2.aspx" WinMode="1" />    </SubMenu>   </Menu>   </CustomMenus>  </MenuBar> </Root> 

Figure 10-12 displays the result of this configuration.

Figure 10-12: Custom Menu

Likewise, you could add a custom menu to an entity menu bar (instead of the application menu bar) by adding code such as the following under the <Entity> node:

 <Entities>  <Entity name="account">   <MenuBar>    <CustomMenus>     <Menu Title="Custom Menu">      <MenuItem Title="Custom Application Window" Url="http://www.fabrikam.com/ customwindow.aspx" ValidForUpdate="1" ValidForCreate="0" AvailableOffline="false" /> />      </Menu>     </CustomMenus>    </MenuBar>  </Entity> </Entities> 

Navigation Pane

You can also use the ISV.config.xml file to add links in the entity navigation pane. The <NavBar> node of the ISV.config.xml file controls the entity navigation pane, which resides under the <Entities><Entity> nodes. Table 10-10 describes the <NavBarItem> attributes available to you.

Table 10-10: <NavBarItem> Attributes

Attribute	Description
AvailableOffline	Defines whether the link should appear in the Outlook client if the client is offline. Valid options are True and False.
Client	Defines which client applications the link should appear in. Valid options are Web and Outlook. If you leave this blank or ignore the node, the menu item will display in both client applications.
Id	Defines the HTML ID of the link. This string value must be unique and is required.
Icon	Defines a path to an image file. Image size should be 16 x 16.
Title	Displays the label that appears to the user.
Url	Microsoft CRM will open a window to the path specified in this attribute. If the JavaScript attribute is populated, the Url attribute will be ignored.
ValidForCreate	Displays menu item when the entity form is in create mode. Valid options are 0 (don't display) and 1 (display).
ValidForUpdate	Displays menu item when the entity form is in update mode. Valid options are 0 (don't display) and 1 (display).

Note 

Remember that to add links to the application's navigation pane, you will have to use the site map.

Toolbar

The <ToolBar> node contains the <Button> and <ToolBarSpacer /> nodes. These buttons are available from the main application toolbar as well as from an entity form's toolbar. Here's an example of a <ToolBar> node:

 <ToolBar ValidForCreate="0" ValidForUpdate="1">  <Button Title="Custom Button 1" ToolTip="Use this to open a custom window." Icon="/_imgs/ ico_18_debug.gif" Url="http://www.fabrikam.com/intranet/customwindow.aspx" Client="Web" PassParams="1" WinParams="height=350,resizable=0" WinMode="0" />  <ToolBarSpacer /> </ToolBar> 

The <ToolBar> node also contains the ValidForCreate and ValidForUpdate attributes. Just as with menu items, you can apply these attributes selectively at the button level. The <Button> element contains the same attributes as <MenuItem>, plus the Icon and WinParams attributes. The Icon attribute defines an image that will appear with the button. This image size should be 16 x 16 pixels. The WinParams attribute allows you to define additional JavaScript window.open options (see Table 10-11 and Table 10-12) and it's dependent on the WinMode selected. You add options and their values in a comma-separated string, such as the following:

 WinParams="height=350,width=600,toolbars=0,menubar=0,location=0" 

Table 10-11: WinMode = 0 Parameters
Open table as spreadsheet

Parameter	Valid options	Description
Height	Number in pixels	Determines the height of the window
Left	Number in pixels	Determines the horizontal placement of the window relative to the upper-left corner of the screen
Location	Yes or no 1 or 0 Default: yes	Displays the Microsoft Internet Explorer address bar in the browser window
Menubar	Yes or no 1 or 0 Default: yes	Displays the Internet Explorer topmost menu bar in the browser window
Resizable	Yes or no 1 or 0 Default: yes	Allows the window to be resized and will display the corner handles at the bottom of the window
Scrollbars	Yes or no 1 or 0 Default: yes	Allows for the vertical and horizontal scrollbars to appear
Status	Yes or no 1 or 0	Displays the status bar at the bottom of the browser window
Toolbar	Yes or no 1 or 0	Displays the Internet Explorer toolbar in the browser window
Top	Number in pixels	Determines the vertical placement of the window relative to the upper-left corner of the screen
Width	Number in pixels	Determines the width of the window

Table 10-12: WinMode = 1 or 2 Parameters
Open table as spreadsheet

Parameter	Valid options	Description
dialogHeight	Number in pixels	Determines the height of the window
dialogLeft	Number in pixels	Determines the horizontal placement of the window relative to the upper-left corner of the screen
Center	Yes or no 1 or 0 Default: yes	Determines whether the window should open in the center of the screen
Edge	Sunken or raised Default: raised	Determines the type of window edge style to use
Help	Yes or no 1 or 0 Default: yes	Determines whether the Help icon should appear
Resizable	Yes or no 1 or 0 Default: yes	Allows the window to be resized and will display the corner handles at the bottom of the window
Scroll	Yes or no 1 or 0 Default: yes	Allows for the vertical and horizontal scrollbars to appear
Status	Yes or no 1 or 0	Displays the status bar at the bottom of the browser window
Toolbar	Yes or no 1 or 0	Displays the Internet Explorer toolbar in the browser window
dialogTop	Number in pixels	Determines the vertical placement of the window relative to the upper-left corner of the screen
dialogWidth	Number in pixels	Determines the width of the window

Note 

You have to specify parameters only if you want specify different values than the Microsoft CRM default settings.

Grid Toolbar

You can also use the ISV.config to add links to the Actions menu and add buttons to the grid toolbar. The grid configuration merges both the <MenuBar> and <Button> elements, so we won't repeat all the available attributes. You customize the grid toolbar by adding a <Grid> to an <Entity> node, as shown here:

 <Grid>  <MenuBar>   <ActionsMenu>    <MenuItem Title="Custom Grid Action" Url="http://www.fabrikam.com/ customgridwindow.aspx" WinMode="1" />    </ActionsMenu>    <Buttons>     <Button Title="Custom Grid Button" ToolTip="This displays a custom button on a grid tool bar." Icon="/_imgs/ico_18_debug.gif" Url="http://www.fabrikam.com/customgridbutton.aspx" WinParams="" WinMode="2" />   </Buttons>  </MenuBar> </Grid> 

For custom Web pages accessed from a grid toolbar button or menu, you can programmatically access the selected records in the grid by using the windows.dialogArguments method. For example, the following Web page will display the GUIDs of the selected records in a grid back to the user when accessed from the <Grid> node of an entity.

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <title>Custom Grid Page</title> <script language="javascript"> function window.onload() {   if(window.dialogArguments != null)   {     var arr = new Array(window.dialogArguments.length -1);     arr = window.dialogArguments;     for(i=0; i< arr.length; i++)     {       alert(arr[i]);     }   }   else   {     alert("No records were selected");   } } </script> </head> <body> </body> </html> 

Appointment Book

The final area of customization within the ISV.config.xml file relates to the scheduling module. Microsoft CRM allows you to change and customize the colors of the appointment book. Table 10-13 lists the attributes related to the <TimeBlock> attribute within the AppointmentBook node.

Table 10-13: <TimeBlock> Attributes

Attribute	Description
AvailableOffline	Determines whether the link should appear in the Outlook client if the client is offline. Valid options are True and False.
Client	Defines which client applications the link should appear in. Valid options are Web and Outlook. If you leave this blank or ignore the node, the menu item will display in both client applications.
CssClass	Defines the style for the given entity and status. The cascading style sheet is located at: <web installation path>\SM\Gantt\style\ ganttcontrol.css.
EntityType	Defines the entity used in the time block. Valid values are 4201 (Appointment) and 4214 (Service).
StatusCode	Refers to the status code of the entity in the appointment book.

Deploying the ISV.config.xml File

To deploy the ISV.config.xml file, simply copy the file to the Microsoft CRM Web server in the <web installation path>\_Resources directory. You can also import and export the ISV.config file via the Web client interface in the Customization area under Import and Export Customizations.

Tip 

Remember to back up the default ISV.config.xml file before you deploy your version. The default ISV.config.xml file created on installation contains examples of the various nodes. Of course, you can retrieve all the information that you need from the SDK, but sometimes it is useful to review the default example when adding new and unfamiliar node.

Enabling the ISV.config.xml File

After you copy the ISV.config.xml file to the _Resources folder (or import it through the user interface), you must enable it by editing the Web.config file. You can choose from one of the following possible values:

• All Display the customizations in all of the clients (Web client, the Microsoft CRM desktop client for Outlook, and the Microsoft CRM laptop client for Outlook).

• None Disable all customizations. This is the default value.

• Outlook Enable customizations for both versions of the Microsoft CRM client for Outlook, but not the Web client.

• OutlookLaptopClient Enable customizations for the Microsoft CRM laptop client for Outlook (offline-capable).

• OutlookWorkstationClient Enable customizations for the Microsoft CRM desktop client for Outlook (online-only).

• Web Enable customizations for the Web client only.

Updating the Web.config File

1. On the Microsoft CRM Web server, navigate to <web installation path>\ (typically C:\Inetpub\wwwroot\).

2. Open the Web.config file in Notepad (or any text editor).

3. Look for the ISVIntegration key, and change its value to the setting that you need.

4. Save the Web.config file.

Note 

The ISVIntegration key allows you to enter multiple values by entering the values with commas (no spaces), such as "OutlookWorkstationClient,Web" or "OutlookLaptopClient,Web". Including None with any of these values disables ISV.config for all of the clients.

After you enable the ISVIntegration key, you must also make sure that you enable the ISV Extensions privilege for the user's security role so that he or she can see the extensions, as shown in Figure 10-13. The ISV Extensions privilege is listed on the Customizations tab as a miscellaneous privilege.

Figure 10-13: Enabling the ISV Extensions privilege

Caution 

If you configure your extensions for the Microsoft CRM laptop client for Outlook (offline mode), make sure that your users can access those links when they're offline.