Skip to main content

Using DimConstants

This document aims to provide OneStream developers with a comprehensive understanding of how to use Dimension Constants within business rules and formulas. Dimension Constants are essential for creating dynamic and reusable calculations that can adapt to different scenarios and dimensions within OneStream applications.

What are Dimension Constants?​

Dimension Constants in OneStream are predefined values that represent specific dimensions or members within those dimensions. These constants allow developers to reference dimensions consistently across various business rules and formulas, ensuring that calculations are accurate and maintainable.

Why Use Dimension Constants?​

  • Consistency: Using constants ensures that the same dimension or member is referenced uniformly across different rules and formulas.
  • Maintainability: Changes to dimension references can be made in one place, reducing the risk of errors.
  • Readability: Constants make the code easier to read and understand, as they provide meaningful names instead of hard-coded values.

Defining Dimension Constants​

Dimension Constants can be defined in the OneStream application by creating a set of constants that represent the dimensions and members you frequently use. These constants can be stored in a configuration file or directly within the business rules.

Example of Defining Dimension Constants​

// Define Dimension Constants
const string ENTITY\_DIMENSION = "Entity";
const string ACCOUNT\_DIMENSION = "Account";
const string TIME\_DIMENSION = "Time";
const string SCENARIO\_DIMENSION = "Scenario";

// Define Member Constants
const string TOTAL\_ENTITY = "TotalEntity";
const string NET\_INCOME\_ACCOUNT = "NetIncome";
const string CURRENT\_YEAR = "2025";
const string ACTUAL\_SCENARIO = "Actual";

Using Dimension Constants in Business Rules​

Once the Dimension Constants are defined, they can be used within business rules to perform calculations. Below are examples of how to use these constants in different scenarios.

Example 1: Calculating Net Income​

This example demonstrates how to calculate the net income for a specific entity and time period using Dimension Constants.

// Business Rule to Calculate Net Income
public void CalculateNetIncome()
{
 // Retrieve data using Dimension Constants
 var netIncome = Api.Data.GetCellData(ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, NET\_INCOME\_ACCOUNT, TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);

 // Perform calculation
 var result = netIncome \* 1.1; // Example calculation

 // Store the result back to the cube
 Api.Data.SetCellData(result, ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, NET\_INCOME\_ACCOUNT, TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);
}

Example 2: Allocating Costs Across Entities​

This example shows how to allocate costs across multiple entities using Dimension Constants.

// Business Rule to Allocate Costs
public void AllocateCosts()
{
 // Define allocation percentage
 const double allocationPercentage = 0.25;

 // Retrieve total costs
 var totalCosts = Api.Data.GetCellData(ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, "TotalCosts", TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);

 // Calculate allocated costs
 var allocatedCosts = totalCosts \* allocationPercentage;

 // Allocate costs to specific entities
 var entities = new string[] { "Entity1", "Entity2", "Entity3", "Entity4" };
 foreach (var entity in entities)
 {
 Api.Data.SetCellData(allocatedCosts, ENTITY\_DIMENSION, entity, ACCOUNT\_DIMENSION, "AllocatedCosts", TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);
 }
}

Error Handling​

Effective error handling is crucial in ensuring that your business rules and formulas run smoothly and provide meaningful feedback when issues arise. Here are some best practices and examples for implementing error handling in OneStream business rules.

Best Practices for Error Handling​

  • Use Try-Catch Blocks: Wrap your code in try-catch blocks to handle exceptions gracefully.
  • Log Errors: Use logging to record errors for troubleshooting and auditing purposes.
  • Provide User-Friendly Messages: Display clear and informative error messages to users.
  • Handle Specific Exceptions: Catch specific exceptions to provide more detailed error handling.

Example of Error Handling in Business Rules​

This example demonstrates how to implement error handling in a business rule that retrieves and processes data.

// Business Rule with Error Handling
public void ProcessData()
{
 try
 {
 // Retrieve data using Dimension Constants
 var data = Api.Data.GetCellData(ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, "SomeAccount", TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);

 // Perform some processing
 var result = data \* 1.1; // Example processing

 // Store the result back to the cube
 Api.Data.SetCellData(result, ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, "ProcessedAccount", TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);
 }
 catch (Exception ex)
 {
 // Log the error
 Api.ApplicationLog.WriteEntry("ProcessData", "Error processing data: " + ex.Message, ApplicationLog.ApplicationLogType.Error);

 // Display a user-friendly message
 throw new XFException("An error occurred while processing data. Please contact your system administrator.");
 }
}

In this example, the try block contains the main logic for retrieving and processing data. If an exception occurs, the catch block logs the error and throws a user-friendly exception message.

Performance Optimization​

Optimizing the performance of your business rules and formulas is essential to ensure efficient and timely processing. Here are some tips and best practices for performance optimization in OneStream.

Best Practices for Performance Optimization​

  • Optimize Cube Design: Ensure that your cube design is efficient and avoids unnecessary complexity.
  • Control Calculation Scope: Limit the scope of calculations to only the necessary data to avoid running unnecessary code.
  • Use Efficient APIs: Utilize efficient APIs like Api.Data.Calculate and avoid using BRApis in finance rules and member formulas.
  • Avoid Code Repetition: Use BRGlobals to avoid code repetition and reduce overhead.
  • Use Custom Calculates: Implement custom calculates to run specific calculations efficiently.
  • Optimize Data Retrieval: Use hybrid source scenario data to copy data quickly and efficiently.

Example of Performance Optimization in Business Rules​

This example demonstrates how to optimize a business rule by controlling the calculation scope and using efficient APIs.

// Optimized Business Rule
public void OptimizedCalculateNetIncome()
{
 try
 {
 // Retrieve data using Dimension Constants
 var netIncome = Api.Data.GetCellData(ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, NET\_INCOME\_ACCOUNT, TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);

 // Perform calculation only if data is not null
 if (netIncome != null)
 {
 var result = netIncome \* 1.1; // Example calculation

 // Store the result back to the cube
 Api.Data.SetCellData(result, ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, NET\_INCOME\_ACCOUNT, TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);
 }
 }
 catch (Exception ex)
 {
 // Log the error
 Api.ApplicationLog.WriteEntry("OptimizedCalculateNetIncome", "Error processing data: " + ex.Message, ApplicationLog.ApplicationLogType.Error);

 // Display a user-friendly message
 throw new XFException("An error occurred while processing data. Please contact your system administrator.");
 }
}

In this example, the business rule retrieves data and performs calculations only if the data is not null, reducing unnecessary processing. Additionally, efficient APIs are used to retrieve and store data.

Security Considerations​

Security is a critical aspect of developing business rules and formulas in OneStream. Ensuring that your code is secure helps protect sensitive data and maintain the integrity of your application. Here are some key security considerations:

Best Practices for Security​

  • Use Role-Based Access Control (RBAC): Implement RBAC to ensure that only authorized users can access and execute specific business rules.
  • Parameterize SQL Queries: Always use parameterized queries to prevent SQL injection attacks.
  • Secure Data Access: Ensure that data access is restricted to authorized users and that sensitive data is encrypted both in transit and at rest.
  • Audit and Monitor: Regularly audit and monitor access to business rules and data to detect and respond to unauthorized access or anomalies.
  • Handle Sensitive Data Carefully: Avoid hardcoding sensitive information such as passwords or API keys in your business rules. Use secure storage mechanisms instead.

Example of Secure Business Rule​

This example demonstrates how to implement a secure business rule that retrieves and processes data with proper access control and parameterized queries.

// Secure Business Rule
public void SecureProcessData()
{
 try
 {
 // Check user permissions
 if (!Api.Security.IsUserInRole("DataProcessor"))
 {
 throw new XFException("Unauthorized access. You do not have permission to execute this rule.");
 }

 // Retrieve data using Dimension Constants and parameterized query
 var query = "SELECT \* FROM FinancialData WHERE Entity = @Entity AND Account = @Account AND Time = @Time AND Scenario = @Scenario";
 var parameters = new Dictionary<string, object>
 {
 { "@Entity", TOTAL\_ENTITY },
 { "@Account", NET\_INCOME\_ACCOUNT },
 { "@Time", CURRENT\_YEAR },
 { "@Scenario", ACTUAL\_SCENARIO }
 };
 var data = Api.Database.ExecuteQuery(query, parameters);

 // Perform some processing
 var result = data \* 1.1; // Example processing

 // Store the result back to the cube
 Api.Data.SetCellData(result, ENTITY\_DIMENSION, TOTAL\_ENTITY, ACCOUNT\_DIMENSION, NET\_INCOME\_ACCOUNT, TIME\_DIMENSION, CURRENT\_YEAR, SCENARIO\_DIMENSION, ACTUAL\_SCENARIO);
 }
 catch (Exception ex)
 {
 // Log the error
 Api.ApplicationLog.WriteEntry("SecureProcessData", "Error processing data: " + ex.Message, ApplicationLog.ApplicationLogType.Error);

 // Display a user-friendly message
 throw new XFException("An error occurred while processing data. Please contact your system administrator.");
 }
}

In this example, the business rule checks user permissions before executing and uses a parameterized query to retrieve data securely. This approach helps prevent unauthorized access and SQL injection attacks.

Conclusion​

Using Dimension Constants in OneStream business rules and formulas enhances the consistency, maintainability, and readability of your code. By following the examples and best practices outlined in this guide, you can create robust and efficient calculations that are easy to manage and understand.

For more detailed information and advanced usage, refer to the OneStream Finance Rules and Calculations Handbook and the Rules And Calculations Optimization and Troubleshooting Tips.

Last updated on by Jeremy Meiss

Was this page helpful?