Planning Analytics Spreadsheet Services/TM1 Web configuration parameters

The configuration parameters for Planning Analytics Spreadsheet Services are stored in the tm1web_config.xml file.

The tm1web_config.xml file is located in the following location:

<TM1 install location>\webapps\tm1web\WEB-INF\configuration\

The following parameters are available.

ActionButtonFullRecalculationEnabled

Determines the level of recalculation that occurs as part of the execution of an action button. This parameter is only applicable to action buttons that use Automatically Recalculate Sheet as the Calculation type.

If set to true, a full recalculation occurs on the target workbook.

If set to false, a partial recalculation occurs on the target workbook. Only the visible portions of the target workbook are recalculated. This recalculation includes any Active Forms, DBS/DBSW/DBR/DBRW/DBRA/DBSA formulas, and dependencies of cells in the visible area. Any portions beyond the scrolling boundary of the target workbook are not recalculated. False is the default value, which can result in improved performance, especially in large workbooks.

AdminHostName
If set, users are not asked to enter a value for Admin Host during login.

See Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters.

AdminHostPort
If set, the client tries to use this port instead of the default Admin Host port.
AdminHostSSLPort
If set, the client tries to use this port instead of the default Admin SSL Host port.
CamLoginApiRedirectEnabled

Default value is false.

When enabled, CAM authentication from the TM1 Web API (either URL API or JavaScript Library) performs a redirect to the CAM login page of Cognos® Analytics. This behavior differs from the default behavior of showing CAM login page of Cognos Analytics in a dialog box. This parameter must be enabled in cases where Cognos Analytics includes an X-Frame-Options header with a value of SAMEORIGIN or DENY, which is used to improve protection against Click-jacking attacks.

CleanDimensionMetaDataCache

During websheet calculation, the CleanDimensionMetaDataCache parameter specifies whether dimension elements are retrieved from the TM1 Server or by using cached elements from TM1 Web.

Default value: false

  • If CleanDimensionMetaDataCache is set to false, elements from the tm1web cache are used.
  • If CleanDimensionMetaDataCache is set to true: tm1web dimension elements are cleaned from the cache and the elements are retrieved directly from the TM1 Server.
CrossDomainAccessList

Specifies a list of cross-domain URLs that are allowed to access TM1 Web.

You can use this parameter to specify the domain where IBM Cognos Workspace is running, if it's running on a domain separate from TM1 Web.

Use an asterisk (*) to allow any domain to access TM1 Web.

If you specify multiple URLs, separate each one by using a comma.

If this parameter is not set or the parameter value is empty, no cross-domain access to TM1 Web is allowed.

CubeViewerColumnPageSize
Specifies the number of columns to fetch in a page of Cubeviewer.

See Changing the Cube Viewer page size.

CubeViewerHiddenDimensionsEnabled
Hides dimensions in the TM1 Web cube viewer.

Hidden dimensions are part of the context of a view, but do not show up as context dimensions in the TM1 Web cube viewer. Instead, they reside in a region of the dimension bar labeled Hidden.

To use hidden dimensions in the TM1 Web cube viewer, you must set CubeViewerHiddenDimensionsEnabled" ="true" in the tm1web_config.xml file. When the feature is enabled, the Hidden region appears on the cube viewer.

You can drag dimensions to and from the Hidden region just as you can for the Rows, Columns, and Context regions.

When a view includes hidden dimensions, the number of hidden dimensions is displayed below the Hidden label. When you click the Hidden region, you can see which dimensions and elements are hidden.

You cannot change the element for a hidden dimension. If you want to change an element, you must show the dimensions by dragging it to the Rows, Columns, or Context region, and then change the element. You can then return the dimension to the hidden region.

CubeViewerRowPageSize
Specifies the number of rows to fetch in a page of Cubeviewer.

See Changing the Cube Viewer page size.

CubeviewerStringWrap
Settings for string cell wrapping in the Cubeviewer.

See Wrapping string values in cube views.

CustomCAMLogoutUrl

Specifies the URL of a dedicated Logout page for CA SiteMinder when TM1 Server is configured to use CAM security (mode 4 or 5). This Logout page must be accessed on logout so that the SiteMinder session cookie can be invalidated.

When a user clicks Logoff in TM1 Web, the CAM logout occurs first. Then, the SiteMinder Logout page is called.

EvaluationServiceURL
Specifies the location of the evaluation service. The evaluation service is included with IBM Planning Analytics Spreadsheet Services. It is used for rendering quick reports within TM1 Web and Planning Analytics websheets.

Valid value is hostname:port_number.

If no value is assigned, the default value is assumed to be http://localhost:9510.

ExportCellsThreshold
Specifies the maximum number of cells that an export of a websheet or a cube view can contain. If the number of selected cells exceeds the threshold, a warning message is displayed and the export does not start.

As of IBM Planning Analytics version 2.0.7, the default value is 1000000.

Edit the ExportCellsThreshold parameter in the tm1web_config.xml file by using the following format:

<add key="ExportCellsThreshold" value="CellsThreshold" />

where CellsThreshold is the cell count threshold that is determined by multiplying the number of rows by the number of columns per sheet, and then multiplying that result by the number of iterations and context members that the export is selected for.

For example, if a websheet has two sheets and each sheet has 1000 rows and 25 columns, and the export is selected for four context members, the cell count is calculated as 25,000 * 2 sheets * 4 context members = 200,000 cells. If the <CellsThreshold> is 150, 000, this websheet export would be rejected.

ExternalUrl

Set the ExternalUrl parameter if you are using TM1 Web and Cognos security (CAM) authentication with an external load balancer that modifies the original startup URL for TM1 Web. The ExternalUrl parameter provides the correct URL so that Cognos security can successfully redirect back to TM1 Web.

Set the value to the same URL that you use to start TM1 Web, for example

 <add key="ExternalUrl" value="http://mycomputer/TM1Web" />
GzipCompressionEnabled
Determines whether the web server responses will be compressed. Valid values are true/false.
HideCubeviewerToolBar
If set to true, all Cubeviewer toolbars are not displayed.

See HideCubeviewerToolBar parameter.

HideTabBar
If set to true, multiple tabs are not displayed.

See HideTabBar parameter.

HideWebsheetToolBar
If set to true, all websheet toolbars are not displayed.

See HideWebsheetToolBar parameter.

HomePageObject
If set, the object of type of websheet, Cubeviewer, or URL will be displayed after a user logs in.

See Configuring a global homepage for all users.

HttpSessionTimeout
This parameter defines the session timeout (in minutes) of the HTTP session for TM1 Web. If the parameter is missing, the value is less than 1, blank, or not a numerical value, the default session timeout that is defined for TM1 Web in the web.xml file is used.

See Setting the TM1 Web session timeout.

Note: As of IBM Planning Analytics Local version 2.0.6, you should not change the session-timeout value in the web.xml file.
LegacyUrlApiSessionDiscoveryEnabled
Use the LegacyUrlApiSessionDiscoveryEnabled configuration parameter to control how the TM1 Web URL API handles login sessions. Configure this parameter to specify whether the URL API tracks separate unique login sessions.

This parameter enables the URL API session to be reused based on the specified admin host, TM1 Server, and (optional) user name.

If you are using the session token login approach with the URL API, you must set the LegacyUrlApiSessionDiscoveryEnabled configuration parameter in the tm1web_config.xml file to False.

See TM1 Web API session login.

Use this format:

<add key="LegacyUrlApiSessionDiscoveryEnabled" value=True or False/>

For example:

<add key="LegacyUrlApiSessionDiscoveryEnabled" value="False"/>

The default value is True.

  • True

    TM1 Web tries to match new login request with an existing login session based on the provided information (TM1 Admin host, TM1 Server, user name).

    This parameter should be set to True only if a single login will occur for a unique TM1 Admin Host, TM1 Server, and user name combination.

  • False

    Specifies that a session token must be provided every time that you open a TM1 Web object with the TM1 Web URL API. Otherwise, the user is prompted.

    Set this parameter to False if you plan to use multiple login sessions with TM1 Web URL API. You also use this configuration if you are using multiple login sessions with the URL API and other TM1 Web clients such as TM1 Web and TM1 Application Web. This configuration uses the session token to keep the user sessions separate and unique.

MaximumConcurrentExports
Specifies the maximum number of concurrent exports that can be executed from TM1 Web. The default value is 5.

Before IBM Planning Analytics version 2.0.7, the default value is 5.

As of IBM Planning Analytics version 2.0.7, the default value is 4.

You can set MaximumConcurrentExports to 0 to allow an unlimited number of concurrent exports. This setting is analogous to export behavior in TM1 Web before version 10.3.

If the maximum number of concurrent exports is reached, and more exports are then initiated, the additional exports are queued until an export slot is available. The initiator of a queued export does not receive notification of queuing.

The optimal parameter setting depends on your RAM capacity and your user requirements. Generally, the more RAM you have available to TM1 Web, the higher the parameter setting can be. Increasing the value results in increased memory consumption, but reduces export queuing. (Setting the parameter to 0 eliminates export queuing.) Conversely, decreasing the parameter value reduces memory consumption that results from exports, but can result in more frequent export queuing.

MaximumSheetsForExport
Specifies the maximum number of sheets that are allowed to export.

Before IBM Planning Analytics version 2.0.7, the default value is 100.

As of IBM Planning Analytics version 2.0.7, the default value is 50.

See Setting the maximum number of sheets to export from a websheet.

MixedCellPaste

If the MixedCellPaste parameter is set to true, when you copy values to a mixed range of leaves and consolidated values in a websheet, the pasted values match exactly. The default value is False.

Note: This parameter applies to websheets only; it does not apply to CubeViewer.
NavTreeCollapsedOnStart
Determines whether the navigation panel will be collapsed or expanded after a user logs in.

See NavTreeCollapsedOnStart parameter.

NavTreeDisplayServerView
Specifies whether to display the Server View node in the navigation tree. Valid values are Y and N.

See Displaying or hiding the Views node in the navigation pane.

NavTreeHidden
Determines whether the navigation panel will be displayed after a user logs in.

See NavTreeHidden parameter.

RecalcOnActivate

If RecalcOnActivate is set to true, a recalculation is performed each time a websheet or cubeview is activated in TM1 Web, for example, when you switch tabs.

Valid values are true or false.
RecalcOnDataValidationChange

Specifies whether the default recalculation behavior will be overridden when you change the value of a data validation list.

If set to true, a recalculation will be triggered when a value in a data validation list is changed.

If set to false, a recalculation will not be triggered when a value in a data validation list is changed.

RecalcOnPicklistChange

Specifies whether the default recalculation behavior will be overridden when you change the value of a picklist.

If set to true, a recalculation will be triggered when a value in a picklist is changed.

If set to false, a recalculation will not be triggered when a value in a picklist is changed.

RelationalResultMaxRows
If a value greater than -1 is specified, then relational query ResultSets are limited to returning the specified number of rows.
TM1DatabaseLabel
If set to "Y", the name of the database is displayed with the user on the TM1 Web banner. For example, "Welcome: Admin / Planning Sample". The default is "N". When this option is set to "N", nothing is displayed with the user.

See TM1DatabaseLabel parameter in Configuring IBM TM1 Web Startup and Appearance Settings.

TM1ServerName
If set, users will not be asked to select a TM1 Server to connect to during login.

See Configuring the TM1 Web login page using AdminHostName and TM1ServerName parameters.

UseBookRecalcSetting

The UseBookRecalcSetting parameter is included in the tm1web_config.xml file. When set to true, the web server honors the mode in which the Excel sheet was published. If the Excel sheet was published in Manual recalc mode, websheet data is not resent to the client until a recalculation is performed.

The UseBookRecalcSetting parameter uses the following format in the tm1web_config.xml file: 

<add key="UseBookRecalcSetting" value="false" />

where value is either "false" or "true"

If you set UseBookRecalcSetting to true, TM1 Web honors the recalculation settings in the Excel worksheet.

When Calculation Options is set to Automatic:

  • If you set UseBookRecalcSetting = "true", the websheet is recalculated automatically when you change the SUBNM function.
  • If you set UseBookRecalcSetting = "false", the websheet is recalculated automatically when you change the SUBNM function.

When Calculation Options is set to Manual:

  • If you set UseBookRecalcSetting = "true", the websheet is not recalculated automatically. To recalculate, you must manually click the recalc button.
  • If you set UseBookRecalcSetting = "false", the websheet is recalculated automatically when you change the SUBNM function.
WebsheetBackgroundRecalculationMode

Specifies the level of background recalculation that occurs for a websheet.

WebSheetService.scrollWebSheet calls can take several seconds because the data is not readily available. Use the WebsheetBackgroundRecalculationMode parameter to recalculate the book in the background so that the necessary data is ready when it is requested.

If set to 0 (default value), only the buffered (visible) area is calculated on a refresh of a sheet.

If set to 1, the area that is adjacent to the buffered area is calculated, in addition to the buffered area. This improves wait times if the user scrolls slightly away from the initially visible area.

If set to 2, the entire current worksheet is calculated. This improves wait times if the user scrolls to any area of the current sheet.

If set to 3, the entire current workbook is calculated. This improves wait times if the user moves to any area of the current worksheet or to another worksheet.

Note: The higher the setting number, the more cells are calculated meaning that there would be a higher load on the web server.
WorkbookMaxCellCount

Specifies the maximum cell count of a workbook as a number with no thousands separators.

The TM1Web application server validates the size of a workbook that is published to TM1 Server. Workbooks that contain ActiveForms might be uploaded only with their control row. At publish time, the workbook can have multiple rows but when it is opened and rebuilt it can display many more rows. You can use WorkbookMaxCellCount to avoid issues when you open workbooks with many cells.

If this parameter is present in tm1web_config.xml and it is not the default, when the user opens a workbook, the server validates its cell count against WorkbookMaxCellCount. If the cell count of the workbook exceeds WorkbookMaxCellCount, an error message is logged and the workbook is not opened. The user sees the <book_name> exceeds maximum cell count error message in the tm1web.log file.

See Using IBM Planning Analytics TM1 Web Logging.

  • Leaving this parameter blank or setting it to 0 or less indicates that an unlimited cell count for workbooks is allowed.
  • Before IBM Planning Analytics version 2.0.7, the default value is -1, which indicates an unlimited number of cells are allowed in a workbook.
  • As of IBM Planning Analytics version 2.0.7, the default value is 500000.
Note: Changes to this parameter require a restart of the application server.
X-Frame-Options

The X-Frame-Options parameter sets the X-Frame-Options response header value. The parameter (and the response header value) specifies whether a browser should be allowed to render a TM1 Web page in a <frame>, <iframe>, or <object>. Use this parameter to prevent Click-jacking attacks and ensure that TM1 Web content is not embedded into other sites. There are three possible parameter values.

  • 0 corresponds to the DENY response header value, which prevents any domain from framing TM1 Web content.
  • 1 corresponds to the SAMEORIGIN response header value, which allows only the current domain to frame TM1 Web content.
  • 2 corresponds to the ALLOW-FROM response header value. In this case, TM1 Web checks the CrossDomainAccessList parameter in tm1web_config.xml for the list of cross-domain URLs that are allowed to access and frame TM1Web content.

    The ALLOW-FROM response header does not have universal browser support. TM1 Web uses the values in CrossDomainAccessList to determine whether the domain is allowed or not. If not, TM1 Web includes the DENY response header value, which prevents framing. In certain circumstances, TM1 Web might be unable to determine the requesting domain. In this case, the SAMEORIGIN response header value is included.

If the X-Frame-Options parameter is missing or empty, 2 is the default value.

The .jsp files in TM1Web include the response header X-Frame-Options only for the DENY and SAMEORIGIN values. If the domain is confirmed to be allowed, then no X-Frame-Options header is included.