Organizing and Referencing Business Rules

The Business Rule framework provided organizes business rules to maximize their reuse. You can link business rules and reference one business rule from another. You can also link and call external DLLs from a business rule. This section describes how to reference a shared business rule and an external DLL from another business rule.

Defining a Reference to a Shared Business Rule

When you create a shared business rule is created, its public members can be referenced and run by other shared and item specific business rules. Creating a shared or referenced business rule lets you:

  • Create a list of shared constant values.

  • Create a set of standard helper functions.

  • Centralize the maintenance of shared logic.

Reference Syntax

This section defines the syntax required to reference a shared business rule from another shared or item specific business rule.

Shared business rules referencing other shared business rules
To create a reference from one shared business rule to another, go to the rule calling a Public Method of another shared business rule and make a declaration in the Referenced Assemblies property. The syntax requires a BR\ prefix and the business rule name to reference. A rule may reference either a VB.NET or C# rule.

TIP: Reference multiple business rules 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

Referencing a Shared Business Rule From an Item Specific Business Rule

Finance, Parser, ConditionalRule and DeriviativeRule shared business rules have equivalent item specific business rules. When you create a shared business rule, set the Contains Global Functions For Formulas property to True to make the rule available to I\item specific business rules. Item specific business rules do not have a Referenced Assemblies property so can only reference shared rules of the same engine type with the Contains Global Functions For Formulas property set to True.

In the example below, the SharedForecastSeeding rule can be called from any other Finance rule because its Contains Global Functions For Formulas property is True. 

NOTE: If a Finance business rule has Contains Global Functions For Formulas set to True, changes to the business rule have a metadata status impact and change the Calculation Status to OK, MC.  This dependency must occur because a global rule can be used by a member formula calculation which can impact the status of the Finance Engine’s data (analytic / Cube data).

Using a Code Declaration

Once a reference is made to a shared business rule, its Public Methods (Functions / Subs) can be called. To access the 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 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")

Referencing an External .Net DLL

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

Create a DLL referenced by a business rule to:

  • 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).

Installing and Configuring DLLs

Perform these tasks to enable an external DLL to be referenced from a shared business rule.

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

    This setup is a best practice, but not required. Alternatively, you can reference the external DLL from a folder on each application server. When the DLL is updated, copy it to a standard folder on each application server.

  2. Identify or create the external DLL to be called and copy it to BusinessRuleAssemblyFolder. When a business rule runs and an external DLL reference with the XF\ prefix is found in the Referenced Assemblies property of the rule, the application server looks in the BusinessRuleAssemblyFolder specified in the application server configuration file to find the DLL to reference.

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

Reference Specification

This section defines the syntax required to reference an external DLL using the shared business rule's Referenced Assemblies property. There are three methods to reference 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 on each application server. 

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

You can use a file system path to reference an external DLL that already exists on an application server, as part of the operating system or as an installed 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. To access the shared business rule’s Public Methods, declare an Import to the Namespaces defined by the DLL, then create an instance of the desired class to use 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