List and Wildcard Functionality in bedrock

The bedrock library has always included support for lists and wildcards in strings passed to parameters. In previous versions of the library, the implementation of list and wildcard support was inconsistent with some bedrock v3 processes allowing users to input a list of objects separated by a delimiter and some included wildcard functionality. However, other processes required a single valid object name and aborted if this was not the case.

The latest version, bedrock v4 consistently includes both options wherever applicable. With the exception of processes which create new objects (where obviously a fully defined name is needed and wildcards are not accepted), you can assume that wherever a delimited “list” string is accepted, then wildcards will also be accepted. Two kinds of wildcard characters are accepted; the single character wildcard “?” and the multi-character wildcard “*”. Wherever lists and wildcards are accepted the process will always include a pDelim parameter where the list delimiter character is defined. If this parameter is set to blank then ampersand “&” is assumed as the default delimiter character. Note that the wildcard characters cannot be substituted as these are standard characters with accepted meaning as wildcards.

Note: it is impossible for object names to include wildcard characters so conflict here is impossible. However, in a circumstance where an element name was to include a wildcard character then although the element in question would certainly be selected, it is possible that other elements matching the same pattern would also be selected. It would, however, be against every accepted best practice to allow such characters in element names. (See here for a detailed guide on naming in TM1.)

To explain how lists and wildcards work we will use the process }bedrock.cube.delete by way of example. Here are the parameters of the process, with default values.

To run the process we will pass in the following parameter values:

• pLogOutput = 1
• pCube = “General Ledger_* & Employee_*”
• pDelim = “&”
• pCtrlObj = 0

Note that we won’t pass in the double-quotes as part of the string, these are just used to indicate that pCube and pDelim are string parameters whereas pLogOutput and pCtrlObj are numeric. Also note the spaces in the value for pCube are for readability, the value could also be passed with the same result as “General Ledger_*&Employee_*”. When you are using bedrock you can include spaces in the string if you like as any spaces will be ignored by TM1 anyway.

So what will the process do? Based on the input we have given we expect all cubes starting with “General Ledger_” and all cubes starting with “Employee_” to be deleted. pLogOutput = 1 tells the process to log the commands to the tm1server.log so there will be a record of which parameters the process ran with and who ran it. The pCtrlObj parameter is an additional safeguard, control objects will only be removed if this parameter is set to 1, even if the names match the defined pattern .

As we can see from the before and after screenshots, the cubes containing the highlighted name matches with the given parameters have been deleted from the system. Note the case insensitivity in the name matches as TM1 is both case and space insensitive in strings. (The message log extract is taken from Pulse for TM1 which presents the log reverse threaded with most recent messages on top.)

Obviously for processes such as }bedrock.cube.delete, }bedrock.dim.delete, }bedrock.hier.delete, }bedrock.cube.view.delete and }bedrock.hier.sub.delete there is a lot of power to affect many objects in one swoop so use with caution!

As an additional example let’s look at }bedrock.dim.attr.delete. This process has also been turbo-charged to accept lists and wildcards. Here are the parameters of the process, with default values.

If we were to run the process with the following parameter values what do we expect to happen?

• pLogOutput = 1
• pDim = “Employee* & Department”
• pAttr = “*City*”
• pDelim = “&”
• pCtrlObj = 0

Now that we understand how the bedrock lists and wildcards function it’s not hard to determine the expected outcome: the process will remove all attributes containing the string “City” from the Department dimension and from any dimension starting with “Employee”.

The multi-character wildcard can also be used as a placeholder for “ALL”. For example, setting:

• pLogOutput = 1
• pDim = “*”
• pAttr = “Description”
• pDelim = “&”
• pCtrlObj = 0

This will remove the Caption attribute from all dimensions where it exists (excluding control dimensions).

Likewise running the same process with the following parameters:

• pLogOutput = 1
• pDim = “Department”
• pAttr = “*”
• pDelim = “&”
• pCtrlObj = 0

Will remove all attributes from the Department dimension!

With great power comes great responsibility! So again as noted above, use with caution!

This process does have a safeguard built-in. Namely only one or the other of pDim and pAttr can be set to “*” (i.e. “ALL”). Thus the process will not obey a command to delete all attributes from all dimensions but will abort if this is attempted. You can only delete either a specified attribute from all dimensions or all attributes from a specified dimension.

The processes }bedrock.hier.consol.delete and }bedrock.hier.element.delete contain similar functionality for removing elements. Please note the usage of the “*” wildcard is the placeholder for “ALL”, this is implemented consistently in bedrock v4 for all parameters specifying either a class of object or an element (e.g. pCube, pDim, pHier, pView, pSub, pEle). This is a departure from bedrock v3 where an empty string was often used to denote “ALL”. This change is both safer and more explicit in terms of the request. For a more expansive discussion of what else is different in the latest version of bedrock please refer to the what’s new page on the bedrock site.