How to: Create Filter Designers

Article
10/16/2013

In PerformancePoint Monitoring Server, filters refine the data that a dashboard shows in its scorecards and reports. You can create your own filter designer and add it to PerformancePoint Dashboard Designer so users can create, edit, and deploy your custom filter.

The template-based designer in this example checks for valid data source types and sets up the wizard pages. The wizard lets users name the filter, select a data source, enter an SQL statement, and select a display method. Then, it creates the filter object and adds it to the dashboard workspace.

The complete code example for the SQL Query Filter template class factory is provided in the Example section. For more information about filter templates, see Filters Overview.

To create the SQL Query Filter template

Create the SqlQueryParameterTemplateFactory class in the SqlQueryParameterProvider namespace.
1. Add the following using directives.
```
using System;
using System.Collections.Generic;
using Microsoft.PerformancePoint.Scorecards;
using Microsoft.PerformancePoint.Scorecards.Modeler.Framework;
using Microsoft.PerformancePoint.Scorecards.Modeler.Framework.Utilities;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Controls;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Dashboards;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.DataSources;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Templates;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Utilities;
using Microsoft.PerformancePoint.Scorecards.ModelerWorkspace;
using Microsoft.PerformancePoint.Scorecards.WizardFramework;
using SqlQueryParameterProvider.Properties;
```
2. Inherit from the ParameterTemplateFactory class.
3. Set custom identifiers for the class and template type.
4. To return the name to display in the template selection dialog box in Dashboard Designer, override the GetTemplateDisplayString method.
5. To return the unique string identifier for the SQL Query Filter, override the GetTemplateTypeId method.
6. To return the System.Type of the SQL Query Filter, override the GetTemplateType method.
7. To integrate your template into Dashboard Designer, override the GetTemplateItems method.
8. To verify that data sources exist and to call the CreateSqlQueryParameter method to open the wizard and return the filter object, override the CreateParameter method.
9. To populate the wizard pages, open the wizard, and return the filter object, implement CreateSqlQueryParameter.
10. To verify that the data source type is ODBC, which is required for a SQL Query Filter, implement the IsDataSourceUsable method.
  
  Note
  
  Be sure to validate data sources for your custom filter type in your template. Do not allow a user to select a data source that is not valid for the enumeration.
To perform lookups and create or edit the filter object, implement the SqlQueryProgressPage class. For more information, see How to: Create the SqlQueryProgressPage Class.
Build your Windows Forms wizard panel and page, and create a resources file. These instructions are beyond the scope of this documentation.

Example

The class in the following code example creates a wizard template that connects to Microsoft SQL Server via an ODBC connection. It returns a filter object that contains the results of an SQL statement, or a stored procedure that returns a table.

Prerequisites

Before you compile the code example, ensure you have met the following prerequisites:

Install Monitoring Server.
Install the SQL Query Filter sample. To download the sample, see Creating a Custom Dashboard Filter for PerformancePoint Server 2007 ~ Code Sample.
Be prepared to sign your DLL with a strong name. In addition, ensure that all assemblies referenced by your DLL have strong names. For information about how to sign an assembly with a strong name and how to create a public/private key pair, see How to: Create a Public/Private KeyPair.

using System;
using System.Collections.Generic;
using Microsoft.PerformancePoint.Scorecards;
using Microsoft.PerformancePoint.Scorecards.Modeler.Framework;
using Microsoft.PerformancePoint.Scorecards.Modeler.Framework.Utilities;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Controls;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Dashboards;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.DataSources;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Templates;
using Microsoft.PerformancePoint.Scorecards.ModelerPlugins.Utilities;
using Microsoft.PerformancePoint.Scorecards.ModelerWorkspace;
using Microsoft.PerformancePoint.Scorecards.WizardFramework;
using SqlQueryParameterProvider.Properties;

namespace SqlQueryParameterProvider
{
    public class SqlQueryParameterTemplateFactory : ParameterTemplateFactory
    {

        #region Set Custom Identifiers
        public const string SqlQueryTemplateId = "SqlQuery";
        public const string SqlQueryTemplateTypeId = "SqlQueryParameterTemplateFactory";
        #endregion 

        #region Override Base Class Methods
        // Return the display name for the template selection dialog box in Dashboard Designer.
        public override string GetTemplateDisplayString(string templateTypeId)
        {
            if (templateTypeId == SqlQueryTemplateId)
            {
                return Resources.TemplateFriendlyName;
            }
            else
            {
                return base.GetTemplateDisplayString(templateTypeId);
            }
        }

        // Return the string ID for this class.
        public override string GetTemplateTypeId()
        {
            return SqlQueryTemplateTypeId;
        }

        // Return the type for this class.
        public override Type GetTemplateType()
        {
            return GetType();
        }

        // Get the SQL Query template for the filter wizard.
        public override List<TemplateItem> GetTemplateItems()
        {
            List<TemplateItem> items = new List<TemplateItem>();
            TemplateItem sqlQueryItem = new TemplateItem();

            // Set the display name for the template item.
            sqlQueryItem.Name = Resources.TemplateFriendlyName;

            // Set the description and image to display in the template selection dialog box.
            sqlQueryItem.Description = Resources.TemplateDescription;
            sqlQueryItem.Image = Resources.ImageSqlQuery;

            // Get the ID strings that identify the template and template type.
            sqlQueryItem.TemplateTypeId = GetTemplateTypeId();
            sqlQueryItem.TemplateId = SqlQueryTemplateId;

            items.Add(sqlQueryItem);
            return items;
        }

        // Create a filter object based on the passed-in template item ID.
        public override ParameterUIElement CreateParameter(string templateItemId, ParameterUIElement existingParameter)
        {
            if (!string.IsNullOrEmpty(templateItemId))
            {

                // Verify that data sources exist.
                if (ScorecardModel.GetInstance().DataSourcesOnServer == null ||
                    ScorecardModel.GetInstance().DataSourcesOnServer.Count == 0)
                {
                    GeneralUtilities.ShowMessageBox(Resources.ErrMsgEmptyDatasourceListParameters);
                    return null;
                }
                switch (templateItemId)
                {
                    case SqlQueryTemplateId:

                        // Create and display the wizard form that configures 
                        // your filter type and creates a ParameterUIElement.
                        return CreateSqlQueryParameter(existingParameter);
                }
            }
            return null;
        }
        #endregion 

        #region Define and Create the Filter
        // Create the SQL Query filter object.
        private ParameterUIElement CreateSqlQueryParameter(ParameterUIElement existingParameter)
        {
            WizardForm form = new WizardForm();
            form.Title = Resources.WizardFormTitle;
            form.Icon = Resources.IconApp;

            // Create the "Name the filter" wizard page.
            ParameterNameWizardPage parameterNamePage = new ParameterNameWizardPage(form);
            parameterNamePage.Logo = Resources.ImageFilter;
            parameterNamePage.HeadlineDescription = Resources.FilterNameHeadlineDescription;
            parameterNamePage.Headline = Resources.FilterNameHeadline;
            parameterNamePage.StepTitle = Resources.FilterNameStepTitle;
            form.AddPage(parameterNamePage);

            // Create the "Select a data source" wizard page.
            SelectElementsWizardPage selectDataSourcePage = new SelectElementsWizardPage(form);
            selectDataSourcePage.Logo = Resources.ImageFilter;
            selectDataSourcePage.HeadlineDescription = Resources.FilterDataSourceHeadlineDescription;
            selectDataSourcePage.Headline = Resources.FilterDataSourceHeadline;
            selectDataSourcePage.StepTitle = Resources.FilterDataSourceStepTitle;

            DataSourcesWorkspaceItemFactory dataSourcesWorkspaceItemFactory =
                (DataSourcesWorkspaceItemFactory)WorkspaceUtilities.GetWorkspaceItemFactory(typeof(DataSource));
            selectDataSourcePage.Initialize(dataSourcesWorkspaceItemFactory,
                delegate(Element element)
                {
                    return IsDataSourceUsable((DataSource)element, SqlQueryTemplateId);
                });

            form.AddPage(selectDataSourcePage);

            // Create the "Enter SQL statement" wizard page.
            SqlQueryWizardPage sqlQueryWizardPage =
                new SqlQueryWizardPage(form);
            sqlQueryWizardPage.Logo = Resources.ImageFilter;
            sqlQueryWizardPage.HeadlineDescription = Resources.FilterSqlHeadlineDescription;
            sqlQueryWizardPage.Headline = Resources.FilterSqlHeadline;
            sqlQueryWizardPage.StepTitle = Resources.FilterSqlStepTitle;
            form.AddPage(sqlQueryWizardPage);

            // Create the "Select a display method" wizard page.
            ParameterDisplayMethodWizardPage displayMethodPage =
                new ParameterDisplayMethodWizardPage(form);
            form.AddPage(displayMethodPage);

            // Create the "Filter creation progress" wizard page.
            SqlQueryProgressPage progressPage =
                new SqlQueryProgressPage(form,
                                          parameterNamePage,
                                          selectDataSourcePage,
                                          sqlQueryWizardPage,
                                          displayMethodPage);
            displayMethodPage.Logo = Resources.ImageFilter;
            form.AddPage(progressPage);

            // Create the "Confirmation" wizard page.
            ConfirmationPage confirmationPage = new ConfirmationPage(form);
            confirmationPage.Logo = Resources.ImageFilter;
            confirmationPage.Headline = Resources.FilterConfirmationHeadline;
            confirmationPage.HeadlineDescription = Resources.FilterConfirmationHeadlineDescription;
            confirmationPage.StepTitle = Resources.FilterConfirmationStepTitle;
            form.AddPage(confirmationPage);

            // Check if the user is editing an existing filter.
            if (existingParameter != null)
            {

                // Read the properties from the existing filter.
                parameterNamePage.ElementName = existingParameter.Name.Text;
                parameterNamePage.ElementDescription = existingParameter.Description.Text;
                selectDataSourcePage.SelectedItems = new Guid[] { existingParameter.DataSourceId };
                SqlParameterDefinition customDefinition = SqlParameterDefinition.Deserialize(existingParameter.BeginPoints[0].CustomDefinition);
                sqlQueryWizardPage.SqlExpression = customDefinition.Expression;
                displayMethodPage.DisplayType = GetVisualizationDisplayString(existingParameter.Visualization);

                progressPage.Parameter = existingParameter;

            }

            // Open the filter wizard.
            form.Start(MainForm.GetInstance());

            // Retrieve the filter that the user created or edited.
            ParameterUIElement parameter = progressPage.Parameter;
            if (parameter != null)
            {
                BpmPropertyText templateType = new BpmPropertyText();
                templateType.Text = SqlQueryTemplateId;
                templateType.UniqueName = "DataSourceType";
                parameter.Properties.Add(templateType);
            }

            // Clean up.
            confirmationPage.Dispose();
            form.Dispose();

            return parameter;
        }

        // Verify that the data source type is ODBC (required for the SQL Query filter).
        private static bool IsDataSourceUsable(DataSource dataSource, string parameterType)
        {
            return (dataSource.SourceName == DataSourceNames.Odbc && parameterType == SqlQueryTemplateId);
        }
        #endregion
    }
}

How to: Create Filter Designers

To create the SQL Query Filter template

Example

See Also

Tasks

Other Resources

Additional resources