TM1 object naming conventions

As a developer, you are responsible for creating and naming many objects in IBM® Planning Analytics. TM1 enforces some restrictions on naming while other guidelines offer best practices. Observe the following conventions when you name TM1 objects.

Although some of these characters are not reserved, it is a good practice to avoid the use of these special characters in most cases when you name objects and elements. For more information, see Element names and MDX expressions.

Table 1. Special characters to avoid in object and element names

Character

Description

apostrophe

*

asterisk

@

at sign - see Object names in TM1 rules.

\

back-slash

:

colon

,

comma

{

curly brace - see The curly brace in object names.

"

double-quote

!

exclamation mark - see Object names in TM1 rules.

>

greater-than

<

less-than

-

minus sign - in element names. See Element names and MDX expressions.

| or ¦

pipe or broken pipe

+

plus sign - in element names. See Element names and MDX expressions.

?

question-mark

;

semicolon

/

slash

~

tilde - see Object names in TM1 rules.

^

caret - see Element names and MDX expressions.

& ampersand

Reserved characters per component

The following characters are explicitly reserved for the following components and must never be used when you name objects in these contexts:

  • TM1 Architect reserves the following characters:

    \ / : * ? " < > | } 
  • TM1 Server reserves these characters in these objects: Cube, Dimension, Subset, View, Process, Chores.
    \ / : * ? " < > | ' ; ,
  • For process variable name, the identifier cannot contain any special characters except for:

    AllowableChars[] = ".$%_`";

The curly brace in object names

It is a good practice to avoid the use of the right curly brace (}) as the first character in any user-created TM1 object name. TM1 control object names always begin with the right curly brace. If a user-created object name begins with a right curly brace, the object becomes hidden if the Display Control Objects parameter is turned off.

Element names and MDX expressions

Do not use + or - as the first character of an element name. Although only the first element in a subset when slicing to active form cannot use + or - as the first character in the element name, it is a good practice to never use + or - as the first character of an element name.

Do not use a ^ in an element name. The ^ character can be used as the delimiter between the ancestor and multi-parent element's name but when an element name that contains this character is referenced in an MDX expression, it cannot be escaped.

Although all the other characters available for use in element names are technically not restricted, it is good practice to avoid the special characters that are listed in the previous table when you name elements.

An element name can contain a right square bracket ( ] ) but when an element name that contains this character is referenced in an MDX expression, the character needs to be escaped by doubling it. For example, an element that is named Array[N] Elements, can be referred to in an MDX expression as [Array[N]] Elements].

Object names in TM1 rules

Although technically allowed, it is a good practice to avoid using these special characters in object names because they may conflict when used in a rules expression. This guideline protects you if the objects or elements ever become part of a rule statement where those special characters are not permitted.

  • For example, ) | ~ ; @ \ / : * ? " < > are all often found in rules statements and should not be used in object names.
  • The @ is technically not restricted, however it is a good practice to avoid using the @ character in object names or element names because the @ character is also a string comparison operator in TM1 rules. If you reference any object with a name that contains the @ character in rules, the object name must be enclosed in single quotation marks. For example, a dimension named products@location must be referenced as 'products@location' in rules. Escaping the name with quotation marks does not work in all cases, so it is best to avoid the use of @ in all cases when naming objects.
  • Escaping the special character using quotation marks does not work for ! or in certain rule expressions.
  • The exclamation point ! character must not be used in object names because it is also used in rules expressions. For example:
    DB('MarketExchange',!market,!date)

Element names and Attribute names

The name given to an attribute for a dimension must be unique from any element names in that dimension.

If a dimension includes a dimension attribute and an element with identical names, then Planning Analytics for Excel will fail to handle that dimension in Exploration views. The dimension might disappear from context in an Exploration view, and System.IndexOutOfRangeException or System.NotSupportedException errors can occur .

Note: For a view to work, the dimension attribute names must follow these guidelines:
  • The name must not be longer than 128 characters.
  • The name must start with either an alphabetical character, a unicode character from the categories L or Nl, or an underscore.
  • The name must only contain alphanumeric characters, unicode characters from the category L, Nl, Nd, Mn, Mc, Pc, Cf, or an underscore.

    For more information, see TM1 object naming conventions.

Maximum string length for data directory and object names

The entire string that is represented by the combination of the TM1® Server data directory name and the object name is limited to 128 bytes. For example, if your data directory is C:\Financial data\TM1\ (22 bytes), object names are limited to 106 bytes, inclusive of a file extension such as .cub or .rux.

Some TM1 objects, such as views, subsets, and applications, are stored in subdirectories of the TM1 Server data directory. In this case, the 128-byte limit is applied to the combination of the TM1 Server data directory, the subdirectory, and the object name.

Case sensitivity

Object names are not case-sensitive. For example, the dimension name actvsbud is equivalent to ActVsBud.

Spaces in object names

Spaces are allowed in all object names, but spaces are ignored by the TM1 Server. The TM1 Server considers the dimension name Act Vs Bud to be equivalent to ActVsBud (or actvsbud).

User names

User names that include reserved characters cannot save private objects.