You might want custom extensions to Corticon in .NET execution environments. For example, you might need to apply a complex mathematical formula in your business rules, or you need to retrieve data from an external web service. When creating your extensions, you’d like to re-use existing .NET code, or create new code that you want to program in .NET, your preferred development environment.
How can the capabilities of Corticon be extended?
In Corticon, there are two ways of extending Corticon functionality:
Extended operators - Used when defining conditions and actions in a Rulesheet. While Corticon has a large built-in set of operators, you can expand that set by adding custom operators. Operators can operate on individual attributes, collections or sequences.
Service callouts - Callouts can be used in a Ruleflow to retrieve, modify, or store data that is being processed by the rules. The most common use is to access data in a database or external web service. For example, if your Ruleflow needs to look up an applicant's credit rating, the service callout can have a step in the Ruleflow processing that calls out to a trusted real time ratings provider, and then adds the response back into the decision processing.
Note: Writing extensions for Corticon is described in detail in the Corticon Extensions
Guide which discusses the sample extension projects included in your Studio installation that shows you how extensions are built. As the Java and .NET languages are very similar,you can easily see how .NET extensions function. This topic shows how to use extended operators in Corticon for IIS.
.NET compatibility with Corticon
Corticon at its core is developed in Java. However, it offers a Corticon Server for .NET rules execution component, which facilitates deployment on Windows .NET framework and Microsoft Internet Information Services (IIS) that are packaged in supported Windows operating systems. At deployment time, the Corticon Server for .NET dynamically transforms the deployed Ruleflow asset from Java byte code into .NET Common Intermediate Language (CIL), the object-oriented assembly language for .NET runtime environments. In other words, Corticon Server will natively execute your business rules in .NET without needing a Java Runtime Environment (JRE) by leveraging the .NET framework.
Corticon supplies an open source utility, IKVM.NET (included in the Corticon Server for .NET installation) that is an essential component of the Corticon Server for .NET runtime architecture enabling it to seamlessly operate in .NET environments.
IKVM.NET is an implementation of Java for Mono and the Microsoft .NET Framework. It includes the following components:
A Java Virtual Machine implemented in .NET
A .NET implementation of the Java class libraries
Tools that enable Java and .NET interoperability
In writing the Corticon extensions for .NET, you use these IVKM.NET utilities to successfully integrate your .NET extensions with Corticon.
Creating and Integrating .NET extensions
The steps required to create and integrate your .NET extensions with Corticon, are, in summary:
1. Write your .NET class file(s) containing the C# code that you require in your extension(s) – such as transform data, calculate a value, or retrieve data through a REST callout.
2. Compile a Java stub file from your .NET DLL using an IVKM utility.
3. Create your Corticon extension skeleton using minimal Java code. Insert the call(s) to your C# methods/functions from your .NET DLL using the Java stub file.
4. Export your extension as a JAR file.
5. In the Corticon rules project properties, reference your extension JAR file, and your .NET class compiled to a Java stub file.
6. Copy your extension DLL to the Corticon Server for .NET.
7. Deploy your Ruleflow to a Corticon Server for .NET instance.
8. Test your deployed decision service in Corticon Studio Tester.
Let’s go through all these steps using a sample extended operator.
1. WRITE YOUR .NET CLASS FILE(S)
First, create a C# Class project in Microsoft Visual Studio. In this e xample, the Corticon extension will determine, based on an arbitrary string of characters, whether your string has an odd or even number of characters.
Example:
Value 1 = “What’s up!” = 10 characters
Value 2 = Value 1 assessed by our extended operator = Even
Below is the C# code that we have used in our class file.
using System; namespace CorticonFunctions { public class DataHandler { public String IsOddOrEven(String astrInput) { String variableValue = null; switch ((astrInput.Length) % 2) { case 0: variableValue = "Even"; break; default: variableValue = "Odd"; break; }
return variableValue; } } }
Build your project in Visual Studio. That provides you with a DLL. Name it CorticonFunctions.dll.
2. COMPILE A JAVA STUB FILE
You can only integrate Java components with Corticon Studio to build your rules. To leverage your C# class file in the extension which you need to integrate with Corticon to create a Java stub file – a wrapper around your C# class file that contains only the metadata or references to our original compiled class file.
To create our Java stub from your CorticonFunctions.dll, you will use an IVKM utility packaged in the Corticon Server for .NET installation to generate Java JAR files from .NET DLLs. The JAR files generated by IKVM contain Java classes and interfaces that correspond to .NET classes, but don't contain any real code. They contain just enough to satisfy the Studio Java compiler, and allow it to type check the Java application. In your Corticon installation, navigate to:
Copy it and rename the copy to, for example, GenStubs_CorticonFunctions.bat
Open GenStubs_CorticonFunctions.bat with a text editor of your choice. Edit the INPUT_DLL_NAME to point to your generated CorticonFunctions.dll and the OUTPUT_JAR_NAME to CorticonStubFunctions.jar and save.
Save the file, and then double-click it to launch and execute the compilation process:
As a result, a new stub file gets created in the same folder, CorticonStubFunctions.jar:
Now you can work on your Corticon Extension.
3. CREATE YOUR CORTICON EXTENSION
Corticon Studio can create the Java extension that you will include (or reference) and use in your .NET code.
To use your C# code, you need to reference the CorticonStubFunctions.jar so you get access to the methods in your C# class.
Corticon Studio's Eclipse environment provides a Java perspective as well as the Corticon Designer perspective. You need to get your Corticon Studio into the Java perspective.
\
Chose the Java perspective: Choose File > New > Java Project. Enter the Project NameCorticonExtensionsNew. Click Finish. Right-click on the project name, and then choose Properties. Choose Java Build Path, and then click its Libraries tab. Click Add External JARs. Locate and add your CorticonStubFunctions.jar
Now let’s write our extension code based on what is described in the extensions guide.
@TopLevelFolder("Extended Operators") public class StringExtensions implements ICcStringExtension{
@OperatorFolder(lang = { "en" }, values = { "String" }) @Description(lang = { "en" }, values = { "returns string value even or odd based on the" + "number of characters in an input string." })
public static String IsOddOrEven(String strInput) { String strRetVal = null;
You need to do an import (USING in C#) to reference the .NET package where you developed your code. Since Java compilers can only compile applications that use Java API's, not .NET API's, we have to trick the Java compiler into believing that there is really a Java package named cli.Corticonfunctions.
The DataHandler class and its embedded method IsOddOrEven pass in an input value, run the C# code against that input value, and return an output value.
The amount of Java code is modest. This is a simple .NET example where your .NET code might encompass hundreds of program lines, and contain references to other .NET assemblies. The Corticon extension simply invokes your code and is unaware of its complexity. That is all the coding needed.
4. EXPORT YOUR EXTENSION AS JAR FILE
You want to export this Java project as executable Java code. Right-click on the project, choose Export, and then Java > JAR file. Click Next, and select the export destination (such as [CORTICON_HOME]\Corticon 5.7\addons\CorticonFunctions.jar). Click FINISH.
Your JAR is now available to be used in your rule project.
5. REFERENCE YOUR JAR FILES IN THE CORTICON RULE PROJECT PROPERTIES
You want a Corticon rule project to be aware of the new Extended Operator you just created by referencing the created JARs so they can be packaged with the compiled Decision Services on deployment to the Corticon Server for .NET.
Change to the Corticon perspective by clicking Corticon Designer:
Choose File > New > Rule Project. Enter the Project NameCorticon Extensions .NET. Click Finish.
Right-click on the rule project, choose Properties, and then choose Corticon Extensions.
Click Add to include CorticonFunctions.jar and CorticonStubFunctions.jar in the project.
Click OK.
Look at the Operators tab. Your extension is listed under Strings:
It is available for rule modeling.
Create a simple Vocabulary, an Entity with two String attributes:
Then a Rulesheet with a single action:
And a Ruleflow that will carry your Rulesheet to deployment.
6. COPY YOUR EXTENSION DLL TO THE CORTICON SERVER FOR .NET
You cannot test these rules in Corticon Studio's tester against a local Rulesheet. Corticon Studio is a Java application, and does not know how to execute your C# natively. Only Corticon server for .NET can do this as it contains the required peripheral IKVM open source utilities to do this. And you cannot pre-compile the Ruleflow into a Decision Service for the same reasons.
You need to deploy your Ruleflow to the Corticon Server for .NET, and then make it aware of your C# code compiled to a DLL. The Ruleflow will be deployed to Corticon Server running inside the Application Server IIS, so IIS needs to know where to find the executable .NET code contained in your new extended operator.
Copy your CorticonFunctions.dll toC:\inetpub\wwwroot\axis\bin\ (the default IIS location on Windows).
7. DEPLOY YOUR RULEFLOW TO A CORTICON SERVER FOR .NET INSTANCE
Create a text file named Determine Odd or Even.cdd. Adjust the path appropriately.
<?xml version="1.0" encoding="UTF-8"?> <cdd soap_server_binding_url="http://localhost:8850/axis"> <decisionservice> <name>Determine Odd or Even</name> <path>../Rule Projects/Determine Odd or Even/ Rules/Determine Odd or Even.erf</path> <options/> </decisionservice> </cdd>
Save the CDD file, and then copy it to the IIS cdd folder, C:\inetpub\wwwroot\axis\cdd. You do not need to restart IIS.
8. TEST YOUR DEPLOYED DECISION SERVICE IN CORTICON STUDIO TESTER
Edit your Studio's properties files, [WORK_DIR]\brms.properties to add the line com.corticon.studio.client.soap.clienttype=IIS. Save all your files, and then restart Studio.
Open your Ruletest file, and then choose Ruletest >Testsheet > Change Test Subject. Choose the Run against Server tab, and then enter the IIS server URL for Corticon, typically http://localhost:80/axis.
Click Refresh, and then choose Determine Odd or Even in the list:
Click OK. Run the Ruletest.
Your .NET extension behaves as expected when tested on an IIS server from Corticon Studio.
Extended operators - Used when defining conditions and actions in a Rulesheet. While Corticon has a large built-in set of operators, you can expand that set by adding custom operators. Operators can operate on individual attributes, collections or sequences.
Choose File > New > Java Project. Enter the Project Name CorticonExtensionsNew. Click Finish. Right-click on the project name, and then choose Properties. Choose Java Build Path, and then click its Libraries tab. Click Add External JARs. Locate and add your CorticonStubFunctions.jar
