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