Create a Configuration Block in Spotfire®

Introduction

Parameterizing an analysis means to inject parameters into the process of opening the file, and optionally configure the analysis further before it becomes interactive to the user. Both actions are defined in a configuration block.

A configuration block is a script-like piece of text, containing parameter assignments and configuration statements.

Parameter assignments are used for setting document properties, parameterized analyses, analyses containing data sources, Parameterized Information Links or transformations with parameters.

The parameters come into scope before data is loaded. They can be retrieved via the API at any time.

Configuration statements consist of a method name followed by an argument list. Configuration statements are interpreted after data has been loaded, but before the command history is activated. When the configuration statements have been interpreted, they are discarded.

Configuration statements are always optional. Nothing in an analysis requires configuration statements to be defined.

In the following example, the first two lines are parameter assignments, the following lines are configuration statements:

Region = "West";
Acme.Limits = { 10, 100, 1000 };
SetPage(pageTitle = "Overview");
ApplyBookmark(bookmarkName = "UserRegionOnly");
SetFilter(tableName = "Table 1", columnName = "Column 1", values = { "A", "B" });
SetMarking(tableName = "Table 2", whereClause = "Gender = 'Male' AND GeekFactor = 'High'");

The syntax of a configuration block requires that parameter assignments are placed before configuration statements.

In the API, a configuration block is represented by a text property in DocumentOpenSettings, used by the AnalysisApplication.Open,  and DocumentSaveSettings, used by AnalysisApplication.SaveAs(local file) and AnalysisApplication.SaveAs(library item).

Additional Uses

In addition to opening a file with a configuration block, it is possible to save an analysis with an embedded configuration block. A typical scenario is the automatic generation of a set of similar files for users with slightly different needs, such as sales managers responsible for different regions. When an analysis with an embedded configuration block is opened, the effect is the same as if the block had been passed as a parameter to the Open call.

It is also possible to combine an embedded block with an external block passed as a parameter. The embedded block is interpreted before the external block. In this way the external block can be used to override settings defined by the embedded block. A typical scenario is to open an analysis with a configuration block from an external application, where the values for the parameter assignments are automatically derived in that application. In this case the Open call is done through COM using an automation interface.

Where to Use a Configuration Block

Configuration Blocks can be used in the following in the following places:

Wep page - JavaScript mashup API

You can inject a configuration when embedding a Spotfire analysis In a web page using the Spotfire® JavaScript API.

C# extension or IronPython script

You can include a configuration block as part of the settings when opening or saving an analysis from a Custom C# Extension or IronPython script

In the Spotfire Analyst API, a configuration block is represented by a text property in 

• DocumentOpenSettings class, used by the AnalysisApplication.Open method.

• DocumentSaveSettings class, used by the AnalysisApplication.SaveAs(local file) and AnalysisApplication.SaveAs(library item) methods.

Here's an example of an IronPython script that adds a configuration block when saving a file to a local file:

from Spotfire.Dxp.Application import DocumentSaveSettings
 
settings = DocumentSaveSettings()
settings.ConfigurationBlockText = "testParam=1; SetFilter(tableName="SalesAndMarketing", columnName="Region", values={"NE"});" 
Application.SaveAs("c:tempanalysiswithconfblock.dxp", settings)

URL parameter

You can add a configuration block as a URL parameter when opening a Spotfire analysis in a browser. for example:

 https://spotfire-next.cloud.tibco.com/spotfire/wp/analysis?file=/Samples/Introduction%20to%20Spotfire&configurationBlock=SetPage(pageTitle=%22Filtering%22);SetFilter(tableName=%22World%20Bank%20Data%22,columnName=%22Region%22,values=%7B%22North%20America%22,%22Europe%20%26%20Central%20Asia%22%7D);

Note: Opening an analysis with configuration blocks is currently not supported in the iOS app.

Note: When used in a URL, the configuration block  must be URL encoded (Percent Encoding). Different browsers may handle encoding in different ways.

In particular the following characters should be encoded:

For example:
 

 {"North America","Europe & Central Asia"}

 %7B%22North%20America%22,%22Europe%20%26%20Central%20Asia%22%7D

Read more about URL encoding here. There are also free on-line conversion tools available.

A configuration block used in a URL may contain any number of parameter assignments and configuration statements, each ended by a semicolon.

From the Spotfire Library browser or from the Consumer/Business Author clients it is easy to retrieve a parameterized URL that can be extended by a configuration block. Learn more here.

Command line parameters

When opening the Spotfire Analyst client from a command line script, you can inlcude a configuration block as one of the parameters, for example

• Assigning value "param value" to document property "testParam" when opening a dxp file in the library:

   Spotfire.Dxp.exe /server:http://myserver/ /uri:analysis:/MyFolder/MyTestFile:configurationBlock:testParam=%22param%20value%22;

   

  Note that configuration block must be URL encoded, see details in the "In a URL when opening a Spotfire analysis" example above.

  Automation Services

  You can specify a configuration block In the Automation Services "Open Analysis from Library" task.

  

Parameter Assignments

When opening a parameterized analysis, all mandatory parameters within the analysis must be assigned to values via the API. Any missing mandatory parameters will result in an error. The parameters are also managed by the ParameterManager class, and can be retrieved using the API. The parameter manager is not part of the document, but resides at the application level where it can be retrieved as a service.

The configuration block syntax requires that parameter assignments are placed before configuration statements.

Parameter names are like identifiers in many computer languages. Case is significant, but only in the sense that parameter names are stored the way they were defined. The lookup method in the parameter manager is case insensitive, and all parameter names must be unique even in the case-independent sense to reduce the risk for confusion.

A parameter value is either a string or a list/array of strings. All lists are flat and may not contain other lists. Strings can be written without quotes if they do not contain whitespace or special characters.

Example of a single value parameter:

 Parameter1=Value; Parameter2="Value 1";

 Parameter3={"Value 1", "Value 2", "Value 3"};

Parameters and Document Properties

A configuration block parameter is automatically assigned to a document property, if a document property with the same name and data type is defined in the analysis. This is a convenient way to parameterize many different items in the analysis. One common use is to have document properties values as parameters to IronPython scripts.

Parameterized Information Links

Parameter assignments are commonly and conveniently used with Parameterized Information Links created in the Spotfire Information Designer tool. These Information Links may contain a number of server-defined parameters. Such a parameter is defined by name and type in the Information Designer. The type can be either single-valued or a list type. Information link parameters reference the names in the configuration block using the following syntax: ?param_name.

When data is loaded from a parameterized information link, values for the parameters are retrieved from the ParameterManager. The table below lists the properties in the different information link elements where parameters may be included:

For details on how to create a parameterized Information Link, see the Parameterized Information Links topic in the Spotfire Analyst User Guide.

Configuring Statements

A configuring statement is applied in two steps. First the method name and the ensuing parameter list making up a configuration statement is parsed and used to create an instance of the corresponding configurator class. Then the configurator is validated and executed.

The following list defines the set of available configuration statements:

• SetPage: Specifies the initial page of an analysis
• ApplyBookmark: Applies a bookmark
• SetFilter: Specifies the initial setting of a filter of an arbitrary type
• SetMarking: Initializing a marking

SetPage

The SetPage configuration statement is used to specify the initial page of an analysis. It takes a single parameter which can be a zero-based page index, a page guid, or a page title:

 SetPage(pageIndex = 2);
 SetPage(pageId = "5462f26a-8e02-11dc-8314-0800200c9a66");
 SetPage(pageTitle = "The Intro Page");

The SetPage configurator uses the PageCollection of the document to find a matching page. It will search for a match in the order listed, first using the page index if provided, then the page id, and finally the page title.

If no matching page is found, the configurator will add a note to the issue list, but it will not break.

ApplyBookmark

The ApplyBookmark configuration statement is used to specify the initial state of an analysis. The bookmark is identified by its display name or id:

 ApplyBookmark(bookmarkId = "5462f26a-8e02-11dc-8314-0800200c9a66");
 ApplyBookmark(bookmarkName = "Streamlined");

The ApplyBookmark configurator uses the BookmarkCollection of the document to find a matching bookmark. It will search for a match in the order listed, first id and then name.

If no matching bookmark is found, the configurator will add a note to the issue list, but it will not break.

SetFilter

The SetFilter configuration statement is used to specify the initial setting of a filter of an arbitrary type. The following parameters can be used in various combinations:

Check box filter or list box filter

The settings for a CheckBoxFilter or ListBoxFilter are specified like this:

// Check A and B, uncheck all other values:
SetFilter(columnName = "C", values = { "A", "B" });
 
// Uncheck A, leave other check boxes as is:
SetFilter(columnName = "C", values = { "A" }, operation = Remove);
 
// Uncheck all boxes and exclude empty values:
SetFilter(columnName = "C", operation = RemoveAll, includeEmpty = false);
 
// Reset the filter:
SetFilter(columnName = "C", operation = Reset);
 
// The following applies only to the ListBoxFilter.
// Select A and BA, hide all items not ending with 'A':
SetFilter(columnName = "C", values = { "A", "B" }, searchPattern = "*A");

Item filter or radio button filter

The settings for an ItemFilter or RadioButtonFilter are specified like this:

// Select a specified value:
SetFilter(columnName = "C", values = { "A" });
 
// Select all values, leave includeEmpty as is:
SetFilter(columnName = "C", operation = AddAll);
 
// Select no values, leave includeEmpty as is:
SetFilter(columnName = "C", operation = RemoveAll);

Range filter

The settings for a RangeFilter are specified like this:

SetFilter(columnName = "C", lowValue = "100", highValue = "1000");
 
// Set the upper limit, leave the lower limit as is:
SetFilter(columnName = "C", highValue = "1000");
 
// Select the full range of values:
SetFilter(columnName = "C", operation = AddAll);

Hierarchy filter

The settings for a CheckBoxHierarchyFilter are specified like this:

// Select the May 1988 subtree only:
SetFilter(columnName = "C", path = { "1988" }, values = { "May" });
 
// Add the May 1988 subtree to the included values:
SetFilter(columnName = "C", path = { "1988" }, values = { "May" }, operation = Add);
 
// Remove two days in May from the selection:
SetFilter(columnName = "C", path = { "1988", "May" }, values = { "1", "2" }, operation = Remove);

Text filter

The settings for a TextFilter are specified like this:

 // Select all items ending with 'A':
 SetFilter(columnName = "C", searchPattern = "*A");
 
 // Reset the filter:
 SetFilter(columnName = "C", operation = Reset);

SetMarking

The SetMarking configuration statement is used to initialize a marking. It takes the following parameters:

A SetMarking configuration statement is used like this:

 // Replace the current marking by the one specified:
 SetMarking(tableName = "T1", whereClause = "Region = 'West' and Broker = 'John'");
 
 // Add a set of rows to the current marking:
 SetMarking(tableName = "T1", whereClause = "Region = 'East'", operation = Add);