Making modifications to TM1 rule files can (potentially) affect both the TM1 application and the TM1 server (that the application is running on). Rule modification or reprogramming can cause loss of data, changes in how the application responds (performance) and unexpected changes in memory consumption. In addition, it can be difficult to effectively test an incremental rule change without following a specific, regimented practice for deploying the change.
In this post, I’d like to outline a “best practice” guide for deploying a TM1 Rule change to an identified TM1 Server environment.
It is a best practice recommendation to publish a deployment plan document prior to making any change to any TM1 rule file in an established TM1 Server environment. This document should clearly state all of the required steps in the deployment and also include a proven recovery plan.
For a “working example”, let’s assume we are deploying changes to a TM1 rule that calculates pension costs for certain types of employees. This will involve deploying a modified TM1 rule file (RUX) for a cube and the adding a new numeric attribute on the Position_Type.dim dimension.
The following is the best practice approach for the rule deployment:
The Future of Big Data
With some guidance, you can craft a data platform that is right for your organization’s needs and gets the most return from your data capital.
The first step is to record the current state of the environment you are deploying to. You should never deploy a TM1 rule change without first establishing an environmental baseline. This involves recording the performance statistics of the current TM1 server along with each individual cube running on the TM1 Server. The use of Performance Monitor is recommended. (In the most optimal situations, you have already been monitoring server performance statistics and have a baseline). The following statistics should be recorded both before and after the rule change is made:
- Memory Used for Views
- Number of Stored Views
- Number of Stored Calculated Cells
- Number of Populated String Cells
- Number of Populated Numeric Cells
- Number of Fed Cells
- Memory Used for Calculations
- Memory Used for Feeders
- Memory Used for Input Data
- Total Memory Used
Minimally, the process should be:
- Log all clients (TM1 Users) out of the TM1 server
- Perform a SaveDataAll
- Record base performance statistics
Never proceed with a change to any controlled (TM1 or otherwise) environment without a means for restoring the state of the original environment (backing out the modification). Step 2 involves creating a backup. This is a simple (but critical) process:
Perform a SaveDataAll
- Shut down the TM1 Server
- Perform a backup of the TM1 Server files, labeling and keeping these files available until the deployed change is validated
Finally, once you have established a server performance baseline and created a backup/restore point, you can proceed with any tasks that are required to support the TM1 rule file change. (These should be clearly outlined in the deployment plan document mentioned earlier in this document). These tasks usually involve administrator level changes to TM1 structures like dimensions and data and, optimally are automated.
In this example, we are adding a new dimension attribute – one named “PensionRule”. To add this attribute, you can right-click on the dimension named “Position_Type” and select “Edit Element Attributes…”. From the attribute editor dialog, you can add the new attribute:
- Start the TM1 Server
- Log into the TM1 Server as an Administrator
- Right-click on the dimension and select “Edit Element Attributes…”
- From the Attributes Editor dialog select Edit and then Add New Attribute
- Enter the new attribute name “PensionRule” (all one word) and be sure to select numeric as the attribute type, and then click Ok.
- Since we defined it as numeric, the new attribute should default to 0.000000. Go ahead and set the value of the new attribute for the element “T” to 1.000000. Note that you don’t have to enter all the zeros – TM1 will do that for you!
At this point, you are ready to deploy! The following steps should be followed:
- Stop the TM1 Server
- Examine the Tm1 server folder for .BLB files with names that match the cube and rule files you are updating and delete them. (When you create a rule, TM1 also generates a file called cube_name.blb, which contains format information for the Rules Editor. When copying a RUX (rules file) into a TM1 environment, you should delete the corresponding .blb file. If you do not delete the file, there could be a discrepancy between the contents of the .rux file and what TM1 uses in memory).
- Copy in the new TM1 Rule file (RUX).
- Start the TM1 Server.
- Examine TM1 log (tm1server.txt) for unexpected startup errors or exceptions. If errors or exceptions have occurred, consider stopping the TM1 server and restoring to its original state.
- Log into TM1 Server as a TM1 Administrator.
- Open the appropriate cube or cubes, perform the appropriate tests and review the results of rule change. Record and publish the test results.
- As you did before deploying the changes, record the application performance statistics and compare them to the “before rule change” statistics. If there is a significant difference, consider stopping the TM1 server and restoring to its original state.
At the conclusion of a TM1 rule modification deployment all documentation – deployment plan, performance statistics (before and after changes), server backup and test results should be labeled and archived for future reference.
Following the procedure outlined here will take extra time but will also add structure to your deployments and significantly reduce risk – contributing toward application excellence.
TM1 Server log file name is tm1server.log not tm1server.txt
good catch of my typo. Thanks for reading.