Business Rules

Getting Started with Business Rules

Business Rules are the backbone of OneStream customization. They allow you to extend the platform with custom logic written in VB.NET, executed at specific points in the application lifecycle. Each Business Rule is an independent VB.NET class — it can be as simple as a one-line log message or as complex as a full code library with custom classes, methods, and properties.

What Are Business Rules?

A Business Rule is a block of code that OneStream executes in response to a specific event or action. Think of them as hooks into the platform — when something happens (a form loads, data is consolidated, a cube is calculated), your rule runs.
ℹ️Info
Business Rules execute server-side within the OneStream application server. They have access to the full OneStream API through the BRApi namespace.

Types of Business Rules

OneStream organizes Business Rules into three categories based on their purpose and how they are triggered.
diagramBusiness Rule Type Taxonomy

Loading diagram...

Finance Rules

Finance Business Rules execute during cube operations — calculations, translations, and consolidations. They are written as Shared Business Rules and applied to a Cube, or as Member Formulas on individual dimension members. The api.FunctionType property tells you which operation triggered the rule, such as Calculate, Translate, ConsolidateShare, or DynamicCalcAccount.
Most applications primarily use the Calculate function type for stored calculations and DynamicCalcAccount for on-the-fly computed values. OneStream's built-in translation and consolidation algorithms handle the rest automatically in most cases.
💡Tip
Finance Rules are the most common and most detailed rule type. See the Finance Rules guide series for a deep dive into function types, Data Units, calculation techniques, and the Finance Rules API.

Dashboard Rules

Dashboard Business Rules power the UI layer. There are three sub-types:
  • Dashboard DataSet — Returns datasets to dashboard components. Used for populating reports, combo boxes, list boxes, and other data-bound controls. Function types: GetDataSetNames and GetDataSet.
  • Dashboard Extender — Handles dashboard lifecycle events and user interactions. Function types: LoadDashboard, ComponentSelectionChanged, and SqlTableEditorSaveData.
  • Dashboard String Function (XFBR) — Returns string values used in dashboard component parameters and expressions.

Extensibility Rules

Extensibility Rules extend the platform beyond standard cube operations:
  • Extender — Facilitates custom automated tasks. One of only two rule types that can be called directly from a Data Management step. Common use cases include automating GL data imports, FTP file transfers, and custom dataset exports.
  • Connector — Handles data integration, drill-back to source systems, and ETL processes. Actions include GetFieldList, GetData, and drill-back operations.
  • Parser — Custom data parsing logic for transformation rules.
  • CubeView Extender — Extends CubeView behavior with custom logic.
  • Spreadsheet — Enables reading from and writing to database tables within the Spreadsheet tool. Can work with MarketPlace solution tables or custom tables.

Event Handler Rules

Event Handlers are unique — they are the only rule type that does not need to be called from another artifact. OneStream has a built-in Event Engine that listens for specific platform events and triggers your code automatically.
⚠️Warning
Each Event Handler type can only exist once per application, and the rule name is fixed. Be careful when migrating Event Handler rules between applications via XML — loading an XML that contains an Event Handler will replace the existing rule entirely.
There are seven Event Handler types:
Event HandlerTriggered By
TransformationImport, validate, load Cube, and clear Stage data events
JournalJournal submission, approval, posting, and rejection events
Data QualityWorkflow certify, lock, unlock, and data quality check events
Data ManagementData Management sequence step events
FormsForm open, save, and validation events
WorkflowWorkflow state changes (lock, unlock, certify, process)
WCFLow-level service call events
Within each Event Handler, you access specific sub-events using the args.OperationName property and cast the args.Inputs to extract contextual information about the event:
1' Transformation Event Handler example
2If args.OperationName = BREventOperationType.Transformation.EndValidateTransform.Name Then
3  Dim processInfo As ValidationTransformationProcessInfo = DirectCast(args.Inputs(0), ValidationTransformationProcessInfo)
4  Dim wfUnitPk As WorkflowUnitPk = DirectCast(args.Inputs(1), WorkflowUnitPk)
5
6  ' Only run for Actual scenario in _Load workflows
7  If api.Scenario.Name = "Actual" AndAlso api.Workflow.Name.EndsWith("_Load") Then
8      ' Custom validation logic here
9  End If
10End If
💡Tip
In Event Handler Rules, avoid using the user's session info to access Workflow information. Instead, use DirectCast to derive Workflow info from the event's input arguments — this is reliable even in batch and automated processes.

Basic Structure

Every Business Rule follows a similar pattern. The examples below show a Finance Business Rule — the most common type. Other rule types use different api and args parameter types but follow the same overall structure.
Here is a minimal Finance Business Rule:
1If api.FunctionType = FinanceFunctionType.Calculate Then
2  ' Your calculation logic here
3  Dim amount As Decimal = api.Data.GetDataCell("A#Sales").CellAmount
4  api.Data.SetDataCell("A#AdjustedSales", amount * 1.1)
5End If
The api object is your gateway to the OneStream platform. It provides access to data, metadata, and utility functions.

Full Rule Skeleton

The code shown in Basic Structure above is just the inner logic. In the OneStream Business Rule editor, every rule is wrapped in a full VB.NET class with Imports, a Namespace, and a Main function. Here is the complete boilerplate for a Finance Business Rule:
1Imports System
2Imports OneStream.Shared.Common
3Imports OneStream.Shared.Wcf
4Imports OneStream.Finance.Engine
5Imports OneStream.Finance.Database
6
7Namespace OneStream.BusinessRule.Finance.MyRuleName
8  Public Class MainClass
9      Public Function Main(ByVal si As SessionInfo, ByVal globals As BRGlobals, ByVal api As FinanceRulesApi, ByVal args As FinanceRulesArgs) As Object
10          Try
11              ' Your logic here
12
13              Return Nothing
14          Catch ex As Exception
15              Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
16          End Try
17      End Function
18  End Class
19End Namespace
Key elements:
  • si (SessionInfo) — Contains information about the current user session.
  • globals (BRGlobals) — A shared object that persists across Data Unit calculations within a single process (more on this below).
  • api (FinanceRulesApi) — The context-specific API for the current calculation. The type varies by rule type (e.g., DashboardDataSetArgs for Dashboard DataSet rules).
  • args (FinanceRulesArgs) — Contains arguments about what triggered the rule, including FunctionType.
  • ErrorHandler.LogWrite — The standard OneStream pattern for catching and re-throwing exceptions with proper logging.
💡Tip
You don't need to memorize this boilerplate. OneStream pre-populates it when you create a new Business Rule in the application. Focus on the logic you write inside the Try block.

Related Content

Now that you understand the basics, continue with these guides: