Building Custom Report Views for Microsoft Business Scorecard Manager 2005

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein. The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication. This white paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in, or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation. Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property. 2005 Microsoft Corporation. All rights reserved. The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Microsoft, MSDN, and the Office Logo are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Table of Contents
Building Custom Report Views for Microsoft Business Scorecard Manager 2005.......................................1 Building Custom Report Views for Microsoft Business Scorecard Manager 2005.......................................1 Table of Contents.................................................................................................................................3 Introduction..............................................................................................................................................4 Introduction..................................................................................................................................................4 About Custom Report Views....................................................................................................................4 About Custom Report Views........................................................................................................................4 Creating a Sample Custom Report View..................................................................................................4 Creating a Sample Custom Report View.....................................................................................................4 Creating the Configuration Component................................................................................................4 Creating the Configuration Component....................................................................................................4 Using the Configuration Component.....................................................................................................8 Using the Configuration Component........................................................................................................8 Creating the Web Component..............................................................................................................9 Creating the Web Component..................................................................................................................9 Using the Web Component.................................................................................................................11 Using the Web Component....................................................................................................................11

Introduction
A core feature of Microsoft Office Business Scorecard Manager 2005 is the ability to associate heterogeneous reports with a scorecard or KPI in the form of a report view. These reports provide supplemental data and additional tools to help decision makers analyze and act on performance information. Business Scorecard Manager supports several types of report views, including Office Web Components (OWC), PivotCharts, PivotTables, spreadsheets, Microsoft SQL Server Reporting Services-based reports, Scorecard Views, and Web pages. In addition, developers and third-party Independent Software Vendors (ISVs) can build custom .NET-based report view types that seamlessly integrate with Business Scorecard Manager. This paper describes the following: About Custom Report Views. Creating a sample Custom Report View, including: Creating the configuration component. Using the configuration component. Creating the Web component. Using the Web component.

About Custom Report Views

In order to create a custom report view, you must build the following two components: 1. A configuration component, which is hosted in Business Scorecard Builder. 2. A Web component that is used to display the custom report view hosted on a Microsoft Windows SharePoint Services-based or Microsoft Office SharePoint Portal Server-based Web page. The configuration component is a Windows Forms user control that is derived from the CustomReportViewWinControlBase class. This component is shown in the Report View Editor in the Business Scorecard Builder and allows the user to configure the custom report view. The custom report view Web component is hosted in the Report View Web Part on a Windows SharePoint Services-based or SharePoint Portal Server-based Web page.

Creating a Sample Custom Report View

This section describes the steps for creating a sample custom report view. You will build a component that displays the current state and selection information of the scorecard onto the screen.

Creating the Configuration Component

The first step in creating the sample custom report view is to create the configuration component. The configuration pane of the report view will have a text box you can use to pass data to the Web component and a check box to test that the validation checking is functioning. You will also add controls for setting the preferred height and width as well as the report view group, as shown in

Figure 1 (a group represents the physical areas that are available for displaying report views in the Report View Web Part on a Windows SharePoint Servicesbased or SharePoint Portal Server-based Web site).

Figure 1
The completed sample configuration component

The following is the sample code for the configuration component:

using using using using using using System; System.Windows.Forms; System.ComponentModel; System.Drawing; Microsoft.PerformanceManagement.Scorecards.Client; Microsoft.PerformanceManagement.Scorecards.Extensions;

namespace CustomReportViewSample { /// <summary> /// Sample custom Report View authoring control /// </summary> public class SampleCustomReportViewWinControl : CustomReportViewWinControlBase { CustomReportView customReportView; CheckBox validate = new CheckBox(); TextBox customDataTextBox = new TextBox(); ErrorProvider validationErrorProvider = new ErrorProvider(); ComboBox groupComboBox = new ComboBox(); TextBox preferredHeight = new TextBox(); TextBox preferredWidth = new TextBox(); const int MaxReportViewZones = 30; public SampleCustomReportViewWinControl() { // Add the custom data control

Label label = new Label(); label.Left = 10; label.Top = 10; label.Text = "&Custom Data:"; label.Height = label.PreferredHeight; label.Width = label.PreferredWidth; this.Controls.Add(label); customDataTextBox.Left = 10; customDataTextBox.Top = label.Bottom + 10; customDataTextBox.Height = 50; customDataTextBox.Width = 200; customDataTextBox.Multiline = true; this.Controls.Add(customDataTextBox); // Add the pass-validation control validate.Left = 10; validate.Top = customDataTextBox.Bottom + 10; validate.Height = 50; validate.Width = 200; validate.Text = "Pass &validation"; validate.Checked = true; this.Controls.Add(validate); // Add the preferred height control Label preferredHeightLabel = new Label(); preferredHeightLabel.Top = validate.Bottom + 10; this.Controls.Add(preferredHeightLabel); preferredHeightLabel.Text = "Preferred &height:"; preferredHeightLabel.TextAlign = ContentAlignment.MiddleRight; preferredHeight.Top = preferredHeightLabel.Top; preferredHeight.Left = preferredHeightLabel.Right + 5; preferredHeight.Width = 40; this.Controls.Add(preferredHeight); preferredHeight.Name = "preferredHeight"; preferredHeight.MaxLength = 5; // Add the preferred width control Label preferredWidthLabel = new Label(); preferredWidthLabel.Top = preferredHeightLabel.Bottom + 10; this.Controls.Add(preferredWidthLabel); preferredWidthLabel.Text = "Preferred &width:"; preferredWidthLabel.TextAlign = ContentAlignment.MiddleRight; preferredWidth.Top = preferredWidthLabel.Top; preferredWidth.Left = preferredWidthLabel.Right + 5; preferredWidth.Width = 40; this.Controls.Add(preferredWidth); preferredWidth.Name = "preferredWidth"; preferredWidth.MaxLength = 5; // Add the group drop down Label groupLabel = new Label(); groupLabel.Top = preferredWidthLabel.Bottom + 10; this.Controls.Add(groupLabel); groupLabel.Text = "&Group:"; groupLabel.TextAlign = ContentAlignment.MiddleRight; for (int i=1; i<=MaxReportViewZones; i++) { groupComboBox.Items.Add(i); } groupComboBox.DropDownStyle = ComboBoxStyle.DropDownList; groupComboBox.Left = groupLabel.Right + 5;

groupComboBox.Top = groupLabel.Top; groupComboBox.Height = groupComboBox.PreferredHeight; groupComboBox.Width = 40; this.Controls.Add(groupComboBox); } public override void SetCustomReportView( CustomReportView customReportView) { this.customReportView = customReportView; customDataTextBox.Text = customReportView.Data; if (customReportView.PreferredHeight > 0) preferredHeight.Text = customReportView.PreferredHeight.ToString(); if (customReportView.PreferredWidth > 0) preferredWidth.Text = customReportView.PreferredWidth.ToString(); if (customReportView.Zone >= 0 && customReportView.Zone < groupComboBox.Items.Count) groupComboBox.SelectedIndex = customReportView.Zone; else groupComboBox.SelectedIndex = 0; } public override string GetCustomType() { return "SampleCustomReportView"; } public override string GetDisplayName() { return "Custom Report View Sample"; } public override bool ValidateData() { if (!validate.Checked) { // This check is just to demonstrate the validation mechanism // In actual code, you would validate your custom data here this.validationErrorProvider.SetError( this.validate, "This box must be checked"); } return validate.Checked; } public override void UpdateData() { // Update data from UI customReportView.Data = customDataTextBox.Text; if (preferredHeight.Text.Length > 0) customReportView.PreferredHeight = int.Parse( preferredHeight.Text); else customReportView.PreferredHeight = int.MinValue; if (preferredWidth.Text.Length > 0) customReportView.PreferredWidth = int.Parse(preferredWidth.Text); else customReportView.PreferredWidth = int.MinValue; customReportView.Zone = groupComboBox.SelectedIndex;

} } }

Using the Configuration Component

In order to use the configuration component, you must first register it. Then, to verify that it is ready for use, you can check for it in Business Scorecard Builder. To use the configuration component 1. Register the configuration component in the global assembly cache (GAC) on the server on which Business Scorecard Builder is running. To register it in the GAC, run the following command on the command prompt:
gacutil /f /i CustomReportViewSample.dll

2. Register the configuration component with Business Scorecard Builder. To do this, create a new configuration file named pmbuilder.exe.config in the same folder as pmbuilder.exe (by default, this is installed to \Program Files\Microsoft Office Business Scorecard Manager 2005\Builder). The configuration file for the sample report view extension has the following contents:
<configura t i on> <conf igSect i ons> <sect ionGroup name="Bpm"> <sect ion name="CustomReportV iews" type="System.Conf igura t i on .D ic t i ona rySect i onHandler , System, Vers ion=1.0 .5000.0 , Culture=neutra l , Publ i cKeyToken=b77a5c561934e089"/> </sect ionGroup> </conf igSect i ons> <Bpm> <CustomReportV iews> <add key="SampleCustomReportV iew" value="CustomReportV iewSample.SampleCustomReportV iewWinContro l , CustomReportV iewSample, Vers ion=1.0 .0 .0 , Culture=neutra l , </CustomReportV iews> </Bpm> </conf igura t i on>

3. 4. 5. 6. 7.

When you build your custom report views, you must change the assembly reference value and the PublicKeyToken value to that of your assembly. After the component is registered, you can verify that it is now ready for use. Open Business Scorecard Builder and open a new workspace. In Workspace Browser, click any scorecard or KPI. In the right pane of the window, on the Report Views tab, click Add. The Create Report View wizard opens. Click New definition, and then click Next. In the Report view type drop-down list, the custom report view you created is now in the list of available report views, as shown in Figure 2.

Figure 2
Custom report view type selection

The user interface (UI) of the custom report view configuration pane contains a text box to enter an arbitrary string and a check box to test the validation interface. Clearing the pass-validation check box causes the Business Scorecard Builder to show an error if the user clicks OK. The contents of the custom data text box are passed to the custom report view. In an actual implementation, you can use the CustomData property to pass configuration data to your view control, such as in the form of a serialized object.

Creating the Web Component

This section describes how to build the view-time component of the custom report view that is used to render content to the user on a Windows SharePoint Services-based or SharePoint Portal Server-based Web page. In this sample all the useful state data that is available to the control at run-time is displayed. This data, which is illustrated in Figure 3, includes: 1. The custom data set in the authoring component. 2. The linked scorecard. 3. The selected Scorecard View. 4. The selected scorecard node (KpiGroup object). 5. The selected actual or target (KpiMeasure object). 7. The active page filters. 8. The row slice of the selected cell. 9. The column slice of the selected cell.

Figure 3
Sample custom report view Web control

Figure 4 shows how the KPIGroupID, the KPIMeasureID,and the Column slices change in response to the user selecting a cell.

Figure 4
Sample custom report view Web component with cell selection

The Web component of the custom report view is derived from the CustomReportViewControlBase class. The following is the sample code for the report view Web component:

10

using using using using using using using

System; System.Web; System.Web.UI; System.Web.UI.WebControls; System.ComponentModel; Microsoft.PerformanceManagement.Scorecards.Extensions; Microsoft.PerformanceManagement.Scorecards.Client;

namespace CustomReportViewSample { /// <summary> /// A sample custom report view control /// </summary> public class SampleCustomReportViewControl : CustomReportViewControlBase { /// <summary> /// Render this control to the output parameter specified. /// </summary> /// <param name="output"> The HTML writer to write out to </param> protected override void Render(HtmlTextWriter output) { // Show the context information available to the control output.Write("<br/><b>Custom Data:</b> " + HttpUtility.HtmlEncode(this.CustomData)); output.Write("<br/><b>Scorecard Name:</b> " + HttpUtility.HtmlEncode(this.ContextData.Scorecard.Name.Text)); output.Write("<br/><b>Scorecard View Name:</b> " + HttpUtility.HtmlEncode(this.ContextData.ConfiguredView.Name.Text)); output.Write("<br/><b>selected KpiGroupId:</b> " + HttpUtility.HtmlEncode(this.ContextData.SelectedKpiGroupId.ToString())); output.Write("<br/><b>selected KpiMeasureId:</b> " + HttpUtility.HtmlEncode(this.ContextData.SelectedKpiMeasureId.ToString())); output.Write("<br/><b>Active page filters:</b>"); output.Write(GetMemberCollectionHtml(this.ContextData.PageFilters)); output.Write("<br/><b>Column slices of the selected cell:</b>"); output.Write(GetMemberCollectionHtml(this.ContextData.ColumnSlices)); output.Write("<br/><b>Row slices of the selected cell:</b>"); output.Write(GetMemberCollectionHtml(this.ContextData.RowSlices)); } private string GetMemberCollectionHtml(MemberCollection members) { string html = ""; foreach (Member member in members) { html += "<br/>&nbsp;&nbsp;" + HttpUtility.HtmlEncode(member.UniqueName); } return html; } } }

Using the Web Component

Before custom report views can be rendered, the Web component extension must be registered in the GAC on the server as well as in the web.config file of

11

the Windows SharePoint Services-based or SharePoint Portal Server-based Web site. To use the Web component 1. Register the Web component in the global assembly cache (GAC) on the server on which Business Scorecard Manager Server is running. To register it in the GAC, run the following command on the command prompt:
gacutil /f /i CustomReportViewSample.dll

2. The sample has both the configuration control and the Web control in a single assembly. To register the component with the Business Scorecard Manager Server, you must edit the web.config file for the Windows SharePoint Servicesbased or SharePoint Portal Server-based Web site that hosts the scorecard view pages. As shown in the following code sample, under <configuration>\<configSections>, add a new <sectionGroup> node named Bpm:
<configuration> <configSections> <sectionGroup name="Bpm"> <section name="CustomReportViews" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/> </sectionGroup> </configSections> Then, add a <CustomReportViews> section for the custom report view under a new <Bpm> node (under <configuration>). <Bpm> <CustomReportViews> <add key="SampleCustomReportView" value="CustomReportViewSample.SampleCustomReportViewControl, CustomReportViewSample, Version=1.0.0.0, Culture=neutral, PublicKeyToken=7efb1627d6df9743"/> </CustomReportViews> </Bpm>

When you build your custom report views, you must change the assembly reference value and the PublicKeyToken value to that of your assembly. You will now be able to see the new sample report view Web component displayed on the Web page alongside other report views.

12