Workbook properties

This Workbook class has the following properties.

When instantiating either a CubeViewer or Workbook, the following properties are common between the two objects.

sessionToken: Type: String; Specifies the TM1® Web session to use for this object. Do not use this property with the properties for adminHost, tm1Server, username, password, and camPassport. If this property is not specified, and no additional credentials are provided, the user is prompted with a login dialog during startup.

objectId

Type: String

The ID of the Workbook. A unique identifier that you can use to reference the specific Workbook.

The objectId should be included with a sessionToken to identify the TM1 Web session.

For example:

new Workbook({
    sessionToken: "previousSessionToken",
    objectId: "objectIdOfNewWorkbook"
});

adminHost: Type: String; Default: localhost; The admin host to use when the object is loaded. Do not use this property with the sessionToken property.

tm1Server: Type: String; The TM1 server to use when the object is loaded. Do not use this property with the sessionToken property. If unspecified and no sessionToken is provided, the user is prompted with a login dialog during startup.

username: Type: String; The user name to use when the object is loaded. Do not use this property with the sessionToken or camPassport properties. If unspecified and no sessionToken or camPassport is provided, the user is prompted with a login dialog during startup.

password: Type: String; The password to use when the object is loaded. If unspecified and no sessionToken is provided, the user is prompted with a login dialog during startup.

camPassport: Type: String; The Cognos® Analytics authentication passport (CAM passport) to use when you load an object. Do not use this property with username or sessionToken.

domNode: Type: HTMLElement; The underlying HTML element that represents the widget. This property is automatically defined during object construction and should not be provided during instantiation.; For more information, see Dojo documentation for dijit._WidgetBase (https://dojotoolkit.org/reference-guide/1.10/dijit/_WidgetBase.html).

The following properties are used when you instantiate a Workbook object only.

path: Type: String; The path in the TM1 server application folder tree for the workbook to be loaded.; For example: "Applications/Planning Sample/Bottom Up Input/Budget Input"

replaceOnNavigate: Type: Boolean (default true); If true, during action button navigation to a new workbook, this widget will be replaced with the new workbook and the existing workbook will be closed.; If false, it is the consumer's responsibility to create a new workbook or replace this one using the information provided to the onActionButtonExecution method.

Get properties

All properties that get a value are called with the following format:

get("property_Name").

For example: get("sandboxes");

sandboxes

Retrieves all available sandboxes.

Returns dojo.promise.Promise as a promise that is resolved when the sandboxes are retrieved. When the promise is resolved, an Array of objects that represent the available sandboxes is passed to any callback registered with the promise.

Each object uses the following format:

name: (String) - The name of the sandbox.
active: (Boolean) - True if this sandbox is the active sandbox for the object, else false.
baseSandbox: (Boolean) - True if this sandbox is the base sandbox, else false.
defaultSandbox: (Boolean) - True if this sandbox is the default sandbox, else false.

Set properties

All properties that set a value are called with the following format:

set("property_Name", value)

For example: set("activeSandbox", "theSandbox");

activeSandbox: Sets the specified sandbox as active.; Parameter: (String) sandbox. The name of the sandbox to set as active.; Returns: dojo.promise.Promise as a promise that is resolved when the active sandbox is set.

subset

Sets a subset object.

Parameter: (Object) subset An object that represents the dimension subset object to set. The object uses the following format:

sheetIndex: Type: Integer; The zero-based index of the sheet that contains the SUBNM cell whose dimension subset you want to change.
rowIndex: Type: Integer; The zero-based index of the row that contains the SUBNM cell whose dimension subset you want to change.
columnIndex: Type: Integer; The zero-based index of the column that contains the SUBNM cell whose dimension subset you want to change.
dimension: Type: String; The dimension name. Should not be used in conjunction with sheetIndex, rowIndex, and columnIndex.
setExpression: Type: String; The MDX expression used to define the subset. Not to be used in conjunction with subset. That is, either a setExpression or a subset name is provided from the input.
subset: Type: String; The subset name of the dimension subset to set. Not to be used in conjunction with setExpression.
alias: Type: String; The alias of the dimension subset to set.
element: Type: String; The name of the element. Not to be used with elementIndex.
elementIndex: Type: Integer; The one-based index of the dimension element to set. Not to be used with element.

Returns dojo.promise.Promise as a promise that is resolved when the subset objects are set. Any callbacks that are registered with the promise are passed an object that matches the format of the subset that is passed into this method. A value of null is passed if the subset was not changed.

subsets

Sets multiple subset objects.

Parameter: (Object[]) subsets An array of subset objects to set. Each object uses following format:

sheetIndex: Type: Integer; The zero-based index of the sheet that contains the SUBNM cell whose dimension subset you want to change.
rowIndex: Type: Integer; The zero-based index of the row that contains the SUBNM cell whose dimension subset you want to change.
columnIndex: Type: Integer; The zero-based index of the column that contains the SUBNM cell whose dimension subset you want to change.
dimension: Type: String; The dimension name. Should not be used in conjunction with sheetIndex, rowIndex, and columnIndex.
setExpression: Type: String; The MDX expression used to define the subset. Not to be used in conjunction with subset. That is, either a setExpression or a subset is provided from the input.
subset: Type: String; The subset name of the dimension subset to set. Not to be used in conjunction with setExpression.
alias: Type: String; The alias of the dimension subset to set.
element: Type: String; The name of the element. Not to be used with elementIndex.
elementIndex: Type: Integer; The one-based index of the dimension element to set. Not to be used with element.

Returns dojo.promise.Promise as a promise that is resolved when the subset objects are set. Any callbacks that are registered with the promise are passed an array of objects that match the format of the subset objects that are passed into this method for the subsets that are successfully set.

titleDimensionElement

Sets a title dimension element.

Parameter: (Object) element An object that represents the title dimension elements to set. The object uses the following format:

sheetIndex: Type: Integer; The zero-based index of the sheet that contains the SUBNM cell whose dimension element you want to change.
rowIndex: Type: Integer; The zero-based index of the row that contains the SUBNM cell whose dimension element you want to change.
columnIndex: Type: Integer; The zero-based index of the column that contains the SUBNM cell whose dimension element you want to change.
element: Type: String; The name of the element. Not to be used with elementIndex.
elementIndex: Type: Integer; The one-based index of the dimension element to set. Not to be used with element.

Returns dojo.promise.Promise as a promise that is resolved when the title dimension element is set. Any callbacks that are registered with the promise are passed an object that matches the format of the element that is passed into this method. A value of null is passed if the element was not changed.

titleDimensionElements

Sets multiple title dimension elements.

Parameter: (Object[]) elements An array of the title dimension elements to set. Each object uses following format:

sheetIndex: Type: Integer; The zero-based index of the sheet that contains the SUBNM cell for the dimension element that you want to change. Optional when used with dimension, but required for rowIndex and columnIndex.
rowIndex: Type: Integer; The zero-based index of the row that contains the SUBNM cell for the dimension element that you want to change. Do not use this parameter with the dimension parameter.
columnIndex: Type: Integer; The zero-based index of the column that contains the SUBNM cell for the dimension element that you want to change. Do not use this parameter with the dimension parameter.
dimension: Type: String; The name of the dimension. Do not use this parameter with rowIndex and columnIndex.
element: Type: String; The name of the element. Not to be used with elementIndex.
elementIndex: Type: Integer; The one-based index of the dimension element to set. Not to be used with element.

Returns dojo.promise.Promise as a promise that is resolved when the title dimension elements are set. Any callbacks that are registered with the promise are passed an array of objects that match the format of the element objects that are passed into this method for the elements that are successfully set.