Business Rule Organization and Referencing

Each OneStream Business Rule has a predefined Namespace, a Public Class and a Public Function that the OneStream platform engines invoke when the Business Rule needs to be called.

Predefined Object Names

  • Namespace: OneStream.BusinessRule.<Business Rule Type>.<Unique Business Rule Name>

  • Class: MainClass

  • Function: Main

Example Business Rule Structure

Function Prototypes

Each Business Rule has one standard entry point Function Title called Main. The Function definition below represents the standard prototype used by the Main Function in each OneStream Business Rule. The Main Function always has the same standard parameter layout, but the last two parameters, API and ARGS, contain different object references based on the type of Business Rule being executed.

Public Function Main
    (
    ByVal si As SessionInfo,         à    Connection Object Required to use API    
    ByVal globals As BRGlobals,     à    Global Variable Object Used to Share Values
    ByVal api As Object,         à    Specific API object (Different for each Type)
    ByVal args As ExtenderArgs        à    Specific Arguments (Different for each Type)
    ) 
As Object

Defining a Reference to a Shared Business Rule

The Business Rule framework organizes the Business Rules so that reuse can be maximized. There are many situations where a Business Rule writer may create a standard function that is reused in many other Business Rules. The platform provides a way for Business Rules to be linked and called from other Business Rules. In addition, the platform provides a way for external DLL’s to be linked and called from a Business Rule.

This section describes how to reference a Shared Business Rule from a within a Business Rule and how to reference an external DLL from within a Business Rule.

When a Shared Business Rule is created, its public members can be referenced and executed by other Shared and Item Specific Business Rules.

Common reasons to create a shared or referenced Business Rule:

  • Create a list of shared constant values

  • Create a set of standard helper functions

  • Centralize maintenance of shared logic

Shared Business Rules Referencing Other Shared Business Rules

In order to create a reference from one Shared Business Rule to another, navigate to the rule calling a Public Method of another Shared Business Rule and make a declaration in the Referenced Assemblies property. The syntax used to create a reference to another Shared Business Rule requires a BR\ prefix and the Business Rule name to reference.

NOTE: Reference more than one Business Rule by creating a comma-separated list of reference statements.

Syntax
BR\<Business Rule Name to Reference>

Example (Single Reference)

BR\OPS_PostalServiceHelper

Example (Multiple References)

BR\OPS_PostalServiceHelper; BR\CPP_SolutionHelper

Item Specific Rules Referencing Shared Business Rules

Finance, Parser, ConditionalRule and DeriviativeRule Shared Business Rules all have equivalent Item Specific Business Rules.  When creating a Shared Business Rule, set the Contains Global Functions For Formulas to True in order to make the Shared Business Rule available to Item Specific Business Rules.  Setting this property makes the Shared Business Rule available without having to place a reference on the item using the rule.  Item Specific Business Rules do not have a Referenced Assemblies property and therefore can only reference Shared Rules of the same engine type with the Contains Global Functions For Formulas property set to True.

In the screenshot below, the SharedForecastSeeding Rule can be called from any other Finance Rule because its Contains Global Functions For Formulas property is set to True.

NOTE: When a Finance Business Rule has its Contains Global Functions For Formulas set to True, any changes made to the Business Rule causes a metadata status impact and changes the Calculation Status to OK, MC.  This dependency must occur because a global rule can be used by a Member Formula calculation, and therefore can impact the status of the Finance Engine’s data (analytic / Cube data).

Code Declaration

Once a reference is made to a Shared Business Rule, the Business Rule’s Public Methods (Functions / Subs) can be called. To access the Shared Business Rule’s Public Methods, declare an instance of the rule in the code using the Business Rule’s fully qualified Namespace.  This creates an object variable that references the Shared Business Rule and calls its Public Methods.

Example Declaration

‘Declaring an object variable to reference a Shared Business Rule
Dim opsHelper As New OneStream.BusinessRule.DashboardExtender.OPS_PostalServiceHelper.MainClass

Example Usage

‘Executing a Function on the Reference Business Rule Object Variable
Dim desc As String = opsHelper.GetFieldFromID(si, "Dashboard", "Name", dashName, "Description")

Defining a Reference to an External .Net DLL

Developers can build and reference their own custom Microsoft .Net DLLs from Shared Business Rules. These are written in either VB.Net or C#.  Custom business logic can be encapsulated and protected within an external DLL written in Microsoft Visual Studio.

Common reasons to create a custom DLL referenced by a Business Rule:

  • Protect domain specific intellectual property (hide value programming logic)

  • Separate code with dependencies on other programs (system integration wrappers)

  • Complex logic requiring development tools only available within Microsoft Visual Studio (Web Service Discovery and Interface Development)

DLL Installation and Configuration

This section defines the configuration steps that must be completed before an external DLL can be referenced within a Shared Business Rule. This is a three-step process.

  1. Specify the BusinessRuleAssemblyFolder located in the Application Server configuration file
    This folder should be shared by all application servers meaning the folder must be accessible by the Account Credentials used to configure the IIS Application Pool on the application server.

    This setup process is a best practice but is not required. As an alternative, reference the external DLL from a folder located on each application server and any time the DLL is updated, it needs to be copied to a standard folder on each application server.

  2. Identify or create the external DLL to be called and copy it to the BusinessRuleAssemblyFolder
    When a Business Rule is executed and an external DLL reference containing the XF\ prefix is found in the Referenced Assemblies property of the rule, the application server will look in the BusinessRuleAssemblyFolder defined in the application server configuration file in order to find the DLL to be referenced.

  3. Add a reference specification to the DLL in the Referenced Assemblies property of the Business Rule using it.

Reference Specification

This section defines the syntax required to reference an external DLL by setting the Shared Business Rule’s Referenced Assemblies property.  There are three methods available for referencing an external DLL.

Method 1

This method uses the XF\ prefix to create a reference to an external DLL located in the BusinessRuleAssemblyFolder folder which is specified in the application server configuration file.

Syntax
XF\<External DLL Name to Reference>

Example (Single Reference)
XF\ExternalCode.DLL

Example (Multiple References)
XF\ExternalCode1.DLL;XF\ExternalCode2.DLL

Method 2

This method uses the file system path C:\DLLFolderName\ to create a reference to an external DLL located on each application server.

NOTE: The same folder path and DLL must exist on all application servers.  This referencing method is not a best practice for custom business logic DLLs because it creates a maintenance and update burden. 

Using a file system path reference is a valid method when referencing an external DLL that already exists on an application server. The DLL exists on the application server as part of the operating system or another installed software component.

Syntax
C:\DLLFolderName\<External DLL Name to Reference>

Example (Single Reference)
C:\DLLFolderName\ExternalCode.DLL

Example (Multiple References)
C:\DLLFolderName\ExternalCode1.DLL; C:\DLLFolder\ExternalCode2.DLL

Code Declaration

Once a reference is made to an External DLL from a Shared Business Rule, the Public Methods (Functions / Subs) of that External DLL can be called.  In order to access the Shared Business Rule’s Public Methods, declare an Import to the Namespaces defined by the DLL, and then create an instance of the desired class to utilize in the code.

Example Import

Imports YourNamespace.SubNamespace

Example Declaration 

‘Declaring an object variable to reference a class on the external DLL
Dim extHelper As New YourClass

Example Usage

‘Executing a Function on the external DLL
Dim desc As String = extHelper.YourFunciton(“SomeParameter”)
 

Method 3

This method uses a Windows environment variable to create a reference to an external DLL.  All standard Windows paths are supported, and the name is determined by .NET.

Syntax
%System%\DLLName.DLL

Example
%userprofile%\documents\WindowsBase.DLL