How to: Manually Register PerformancePoint Services Extensions

Article
07/24/2014

The process of deploying an extension for PerformancePoint Services in Microsoft SharePoint Server 2010 includes registering your extension and custom DLLs on the application server, which is the computer that is running PerformancePoint Services, and then copying any supporting files to their target locations.

Applies to: SharePoint Server 2010

You must register your extension in the PerformancePoint Services web.config file (either manually or by using a script or custom timer job) for every instance of PerformancePoint Services in the farm. However, you can package and deploy the components of a PerformancePoint Services extension as a solution to the whole farm. For information about how to deploy SharePoint solutions, see Using Solutions in SharePoint Foundation.

Note

Editing the web.config file requires sufficient administrative permissions on the application server.

This topic describes how to manually register your extension in the PerformancePoint Services web.config file after you have added your custom DLLs to the global assembly cache. The modifications that you make depend on your extension type, as shown in Table 1.

Table 1. Modifications that can be made by extension type

Extension type	Modification in the web.config file
Report	Adding Metadata for a Custom Object
Filter	Adding Metadata for a Custom Object Adding a Key for a Provider or Transform
Data source	Adding Metadata for a Custom Object Adding a Key for a Provider or Transform
Scorecard transform	Adding a Key for a Provider or Transform

Adding Metadata for a Custom Object

You must add metadata for your custom report, filter, or data source object to the web.config file. PerformancePoint Services uses this metadata to create and display custom objects and to open custom editors. Metadata attributes map to properties in the CustomFCODefinition class.

To add metadata for a custom report, filter, or data source object

Navigate to the PerformancePoint Services web.config file in the default path C:\Program Files\Microsoft Office Servers\14.0\WebServices\PpsMonitoringServer on the application server.

Important

As a best practice, make a copy of the web.config file before you edit it.
Open the PerformancePoint Services web.config file in a text editor, such as Notepad.
If your extension is the first custom extension for PerformancePoint Services to be registered on the server, you must register the configuration section handlers and then add the CustomFCOGroup element, as follows:
1. Paste the following code into the sectionGroup element.
```
<section name="CustomFCOGroup" type="Microsoft.PerformancePoint.Scorecards.Common.Extensions.CustomFCOSection,

    Microsoft.PerformancePoint.Scorecards.Common, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"
    allowLocation="true" allowDefinition="Everywhere" />
```
2. If the public key token for your version of Microsoft.PerformancePoint.Scorecards.Common.dll differs from the version in the example, replace the value for the PublicKeyToken attribute with the actual public key token. You can find this property in the assembly cache.
3. Paste the following code into the Bpm element at the same level as the CustomDataSourceProviders, FCODaoProviders, CustomParameterDataProviders, and CustomViewTransforms elements.
```
<CustomFCOGroup></CustomFCOGroup>
```

Paste the following code into the CustomFCOGroup element.

<CustomFCO type="[The object type: ReportView, Filter, or DataSource.]"
    subType="[The unique identifier for your custom ReportView, Filter, or DataSource object.]" >
    <Resources assemblyName="[The fully qualified name of the resources assembly.]"
        resourcesName="[The fully qualified name of the resources file.]"
        FCOName="[The display name for the custom object.]"
        FCODescription="[The description for the custom object.]"
        FCOTemplateIcon="[The image resource to use as the icon for the custom object.]"/>
    <RendererClass name="[The fully qualified name of the renderer class in the format: 
        Namespace.Class name, DLL name, DLL version number, DLL culture, DLL public key token. 
        Applies to ReportView and Filter objects only.]"/>
    <EditorURI uri="[The URI of the custom editor.]"/>
</CustomFCO>

In steps 5 through 13, you replace the placeholder values with actual values for your object. Be sure to remove the square brackets but do not remove the quotation marks.

Note

For instructions about how to install the PerformancePoint Services sample, see PerformancePoint Services Code Sample: Custom Report, Filter, and Tabular Data Source Objects and PerformancePoint Services Code Sample: Custom Scorecard Transforms.

For the type attribute, enter your custom object's type. Valid values are ReportView, Filter, or DataSource. PerformancePoint Services uses this value to categorize the object in PerformancePoint Dashboard Designer, SharePoint Server 2010, and in the PerformancePoint Services repository.
For the subType attribute, enter the unique identifier for your object as a string. For example, the sample data source uses the following entry: subType="WSTabularDataSource".

When a user creates a custom object from Dashboard Designer, the subType value in the web.config file is used as the SubTypeId property of the object. PerformancePoint Services uses this value to determine whether an object is custom.

Note

If your custom editor also specifies the object's SubTypeId property, it must match the subType attribute in the web.config file. As a best practice, editors should specify the SubTypeId property only when creating a custom object outside of Dashboard Designer. For more information, see Editors for Custom PerformancePoint Services Objects.
For the assemblyName attribute, enter the fully qualified name of the assembly that contains the resources file by using the following format.

assemblyName="[DLL name], Version=[version number], Culture=[culture type], PublicKeyToken=[public key token]"

If you are not providing project resources in your extension, remove the assemblyName and resourcesName attributes. (The resourcesName attribute is described in the next step.)

Note

For instructions about how to add resources to your extension, see How to: Add Resources to a PerformancePoint Services Extension.
For the resourcesName attribute, enter the fully qualified name of the resources file. You must provide a value if you specify a value for the assemblyName attribute. If you are not providing project resources in your extension, remove the assemblyName and resourcesName attributes.
For the FCOName attribute, enter the name of the custom object. If you specified a resources assembly, enter the resource key for the name; otherwise, enter the name as a string. This name is displayed in Dashboard Designer, SharePoint Server 2010, and in the PerformancePoint Services repository.
For the FCODescription attribute, enter the description of the custom object. If you specified a resources assembly, enter the resource key for the description; otherwise, enter the description as a string. This description is displayed in the template selection dialog box in Dashboard Designer.
For the FCOTemplateIcon attribute, enter the resource key for the icon. If your extension does not provide a custom icon, remove the FCOTemplateIcon attribute. The icon is displayed in the template selection dialog box in Dashboard Designer.

Note

To use a custom icon, your extension must include a 32 x 32 pixel bitmap image resource for the icon. For more information, see How to: Add Resources to a PerformancePoint Services Extension.
For the name attribute of the RendererClass element, enter the fully qualified name of the renderer class, which is the default web server control that renders the custom report or filter selection control. Use the format Namespace.Class name, DLL name, DLL version number, DLL culture, DLL public key token. For example, the renderer class for the sample report is registered as follows.
```
<RendererClass name="Microsoft.PerformancePoint.SDK.Samples.SampleReport.SampleReportRenderer,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52" />
```
This value is required for ReportView and Filter types. If you are registering a custom data source object, remove the RendererClass element and name attribute.

Note

You can enable users to override this value by exposing the RendererClassName property in the user interface of the custom editor.
For the EditorURI attribute, enter the URI of the custom editor. PerformancePoint Services appends the object's type and subType to this path and then uses it to open the editor from Dashboard Designer or SharePoint Server 2010.

Optionally, you can append a parameter to the editor URI. The parameter is passed to the editor every time that it is opened. The value is static—it cannot be dynamically generated. One scenario for appending a parameter is for an editor that supports both reports and filters. To inform your editor which type of object it is working with, you can pass the type in the editor URI. For this scenario, you would append ?type=ReportView to the editor path for your report extension and ?type=Filter for your filter extension. These parameters do not affect the parameters that are appended by PerformancePoint Services. For more information about the parameters that PerformancePoint Services appends, see Editors for Custom PerformancePoint Services Objects.
Depending on your object type, close the file or register a provider.
- If you are registering a ReportView type, save and then close the web.config file.
- If you are registering a Filter or DataSource type, you must also register your provider. Proceed to step 2 in the following procedure.

Adding a Key for a Provider or Transform

You must register a provider or scorecard transform if your extension defines a data source provider, data provider for a filter, or scorecard transform.

To add a key for a provider or transform

Make a copy of the PerformancePoint Services web.config file. The default path of the web.config file on the application server is C:\Program Files\Microsoft Office Servers\14.0\WebServices\PpsMonitoringServer.
Open the PerformancePoint Services web.config file in a text editor, such as Notepad.
Add a key for the provider or transform DLL, as follows:

Note

To improve readability, line breaks are added to the following examples. You can remove the line breaks after you paste the entry into the web.config file.
- To register a data source provider, add a key in the CustomDataSourceProviders element by using the following format:
  
  <add key="[data source provider ID]" value="[namespace name.class name], [DLL name], Version=[version number], Culture=[culture type], PublicKeyToken=[public key token]" />
  
  For example, to register the data source provider from the data source extension in the PerformancePoint Services sample, add the following key.
```
<add key="WSTabularDataSource"
    value="Microsoft.PerformancePoint.SDK.Samples.SampleDataSource.WSTabularDataSourceProvider,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52" />
```
  The data source provider ID (WSTabularDataSource) must match the subType attribute that you specified for the custom data source object in the CustomFCOGroup element, and it must match the value that is returned by the GetId() method, which is implemented by the TabularDataSourceProvider class. In addition, it must match the SubTypeId property if your editor defines it.
- To register a data provider for a filter, add a key in the CustomParameterDataProviders element by using the following format: <add key="[data provider ID]" value="[namespace name.class name], [DLL name], Version=[version number], Culture=[culture type], PublicKeyToken=[public key token]" />
  
  Note
  
  The value of the key attribute must be returned by the GetId() method in the filter's data provider and by the ParameterProviderId property, which is returned by the filter's BeginPoints property.
  
  For example, to register the data provider from the filter extension in the PerformancePoint Services sample, add the following key.
```
<add key="SampleFilterDataProvider"
    value="Microsoft.PerformancePoint.SDK.Samples.SampleFilter.SampleFilterDataProvider,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52" />
```
- To register a scorecard transform, add a key in the CustomViewTransforms element by using the following format:
  
  <add key="[unique transform ID]" value="[namespace name.class name], [DLL name], Version=[version number], Culture=[culture type], PublicKeyToken=[public key token]" />
  
  For example, to register all the transforms from the PerformancePoint Services sample, add the following keys.
```
<add key="AddColumn"
    value="Microsoft.PerformancePoint.SDK.Samples.ScorecardTransforms.PreQuery.AddColumnTransform,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52"/>
<add key="NumberScaling"
    value="Microsoft.PerformancePoint.SDK.Samples.ScorecardTransforms.PostQuery.NumberScalingTransform,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52"/>
<add key="ShowAnnotationDate"
    value="Microsoft.PerformancePoint.SDK.Samples.ScorecardTransforms.PreRender.ShowAnnotationDate,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52"/>
<add key="FormattingTransform"
    value="Microsoft.PerformancePoint.SDK.Samples.ScorecardTransforms.PreRender.FormattingTransform,
    Microsoft.PerformancePoint.SDK.Samples, Version=14.0.0.0, Culture=neutral,
    PublicKeyToken=fa525c8383a44a52"/>
```
Save and then close the web.config file.

How to: Manually Register PerformancePoint Services Extensions

Adding Metadata for a Custom Object

To add metadata for a custom report, filter, or data source object

Adding a Key for a Provider or Transform

To add a key for a provider or transform

See Also

Concepts

Other Resources

Additional resources