Procedural commands

Print Friendly, PDF & Email

◷ Reading Time: 20 minutes

Commands in procedural rules may fall into different categories. They will be available in Procedural logic that your application can create an instance of and execute the rules. These commands are suitable for implementing low-level functionality, algorithms implementation, complex logic validation, communication to external resources, object creation, and variable value manipulation, object and class level method invocation, accomplishing repetitive tasks, implementing modular rules and logic, database access and so on. Also, it is possible to extend the commands in this Procedural logic and define your required behavior.

Declaration and Assignment commands

This group of commands are responsible for declaring and defining the rule structure and available commands on the rule.

Procedure

This command defines a procedure that is executable in the procedural logic. The entire rule logic must be placed inside this command. A procedure is a low level of functionality or behaviour that can handle complex rules or logic. It is also a reusable part of flow logic. It may have calculations, conditions, assignments, etc. A procedure is an executable routine of a rule or logic. It may have input, output or local parameters from different CLR types. In order for a procedure to execute different commands, it must include a Handlers command. Handlers define what commands are available inside a procedure. Procedures can be divided into different sections named Scope. Each Scope will also be able to accept some parameters.

Summary
This command defines a procedure that is executable in the procedural engine. The entire rule logic must be placed inside this command.
Parameters

  1. name
    • DESCRIPTION: defines the name of the procedure.
    • MANDATORY: YES
    • TYPE: string
  2. enabled
    • DESCRIPTION: indicates whether the procedure is enabled or not. If the procedure is not enabled during execution, the engine would throw an exception.
    • MANDATORY: YES
    • TYPE: Boolean (true/false)

Samples

<Procedure name="check customer rate" enabled="true">
</Procedure>

Handlers

This is the section that contains all of the command handlers. This section of a rule will be loaded automatically and is responsible for registering all of the other handlers of the rule. Each command in the rule must be introduced by a handler.

Summary
Each procedure must have a section for handlers in which factories create an ActiveElement from the defined model that will be registered. This section will be a container for all activators.
Internal Commands
This command requires more Handlers in its scope.
Samples

<Handlers>
</Handlers>

Handler

A handler is a factory that provides all the command execution and definition mechanisms in the rule. This is the command extension points of the procedural logic. If you want to conduct any specific task for which we do not provide a command at the procedural rule level then you need to create a handler and register it using this command. All out-of-the-box commands also follow the same pattern to be registered in the rule logic and allow the rules to behave in a defined way using a particular command (e.g., If, While, Database, etc.).

Summary
This command defines the activator using the assembly name and type.
Parameters

  1. assembly
    1. Description: Defines the name of the assembly; must include the file extension
    2. Mandatory: Yes
    3. Type: String
  2. handler
    1. Description: Full name of the type, including the namespace
    2. Mandatory: Yes
    3. Type: String

Samples

<Handlers>
    <Handler assembly="FlexRule.Procedure.dll" handler="FlexRule.Procedural.FlowControlFactory"/>
</Handlers>

Declaration

Each rule has a specific signature that defines all of the rule parameters. These rule parameters can be defined in different modes: Input, Output, and Local. And their parameters can be in any internal or custom CLR types. That allows the calling application to be able to send any type of value to rules for processing and then retrieve any types of result from the engine when the processing is finished or even during the execution. Also, Usings can be defined in this section of a rule.

Summary
This section is a container for the referencing types and defining parameters in all logic (e.g., Procedural, Flow, Validation, etc.).
Internal Commands
This command requires Define in its scope.
Samples

<Declaration>
   <Define name="minAge" value="18i" direction="local" />
</Declaration>

Define

This command defines the rule parameters. It can be in different directions: Input, Output and local. There is no limitation on the numbers or types of the defining parameters. It can either have none or as many parameters as required. The input parameters must be passed through with the executing applications.

Summary
Every single variable to be used in the rule body must be defined first, from which it can be used as a part of the rule logic.
Parameters

  1. name
    1. Description: Sets the name of each variable
    2. Mandatory: Yes
    3. Type: String
  2. type
    1. Description: Sets the type of each variable
    2. Mandatory: No
    3. Type: Type
      1. friendly name: a string representing default primitive types (e.g., int, double, string, DateTime, etc.)
      2. full type name: a Namespace and Type name combination (e.g., System.DateTime)
  3. assembly
    1. Description: Defines the assembly name holding the type
    2. Mandatory: No
    3. Type: String
  4. direction
    1. Description: Defines how each variable’s direction can be used
    2. Mandatory: Yes
    3. Types
      1. In: The variables assigned will be given a value before execution.
      2. Out: The result of the procedure will be accessed by the values.
      3. Local: Intended for internal calculation and accessible only inside the procedure that defined it
      4. InOut: Allows input and output for the parameter.
  5. value
    1. Description: Sets the default value for a primitive type of variable
    2. Mandatory: No
    3. Type: Any (string, Int, double, or Boolean); accepts values of primitive types

Samples

Defining parameters, there is no need generally to define the type of any parameters.

<Declaration>
    <Define name="order" direction="in"/>
    <Define name="settings" direction="in"/>
</Declaration>

Define with specifying type:

<Declaration>
   <!-- 
     Imports the System.Console class to be used
     In the procedure as a method call
   -->
    <Using path="System.Console"/>
 
    <Define name="itemNo" type="System.Int32" direction="local"/>
</Declaration>

Define parameter with default value of an empty array:

<Declaration>
    <Define name="orders" type="expression" value="array()" direction="out"/>
</Declaration>

Using

If there is a type whose static members are required during the evaluation, it has to be registered by this command

Summary
A signature may contain some Type parameters that can be defined by this command.
This command can be used in all logic: Procedural, Decision Table, Flow, Workflow, Natural Language, Validation and Decision.
Parameters

  1. path
    1. Description: Full address of a type including namespace and type name. Or a ruleset address to a model.
    2. Mandatory: Yes
    3. Type: String
  2. name
    1. Description: If not specified, the last part of the path will be used, otherwise this can override the name of the type.
    2. Mandatory: No (it’s better to specify an assembly)
    3. Type: String
  3. assembly
    1. Description: Assembly name (including .dll) that has the type of implementation
    2. Mandatory: No
    3. Type: String
  4. function
    1. Description: Indicates if the path is an address to type holding multiple functions
    2. Mandatory: No
    3. Type: Boolean (true/false)

Samples

<Declaration>
    <Using path="System.DateTime"/>
</Declaration>

Custom Type and Assembly

The following, will register type Entities.Publications.PublicationCollection in an assembly named entities.dll with a new name of List.

<Declaration>
    <Using assembly="Entities.dll" path="Entities.Publications.PublicationCollection" name="List"/>
</Declaration>

The following will import a type MyNamespace.MyType in an assembly named MyAssembly.dll:

<Declaration>
    <Using assembly="MyAssembly.dll" path="MyNamespace.MyType" />
</Declaration>

Which then allows you to call static members by referring to MyType in your logic.

Logic as Function

The following sample registers a procedural logic as a function in some other model.

<Declaration>
    <Using path="DataAccessLogicProcedure.xml" function="true" return="list" name="loadDataFromDb" />
</Declaration>

This registers logic in the model called “DataAccessLogicProcedure” that has an output parameter named “list” as a function. So in the current context, you can use it as shown in the following format:

 <Var value="result = loadDataFromDb('Select * from cars')" />

Var

This command will manage a defined parameter’s value. It can access the value and manipulate it. The value can be in any type and the command is able to read and write the value or properties of a value.

Summary
This command can be used to evaluate all expressions (i.e., normal, monadic, functions, etc.). Or, when the name attribute is specified, it updates the parameter. For example, it assigns a value to a variable, which can be a simple primitive value such as an integer or a double type, or a computational formula, and (b) accepts nested addressing as the variable name in order to access other scope variables.

When the name is not defined, it evaluates the entire expression that is defined in the value attribute. In this case, all the variables that are used in the expression must refer to defined parameters in the declaration section.
Parameters

  1. name
    1. Description: Name of the target variable affected by the calculation or assignment, or alternatively the nested address. This name must be defined in the declaration section of the model.
    2. Mandatory: No
    3. Type: String
  2. ref
    1. Description: Reference to the variable name
    2. Mandatory: Yes (either value of ref is required)
    3. Type: String
  3. value
    1. Description: Contains the value or formula
    2. Mandatory: Yes (either value of ref is required)
    3. Type: String
  4. process
    1. Description: Defines whether the value is direct or it needs to be computed
    2. Mandatory: No (Default is True)
    3. Type: Boolean (true/false)
  5. source
    1. Description: If an extension exists for this variable assignment, it defines the source of the value on which the computation is based. For example, an XML source would be passed to the extension to calculate an XPath.
    2. Mandatory: No
    3. Type: String (name of another variable)
  6. path
    1. Description: Enables a set value, not insider properties, on the target object by referencing the properties using a dot or an element of an array using brackets, such as [3] and [index] (index can be an integer variable defined in running context). When the variable you are referencing in name has got some inner properties and you want to target them to update, you can use this setting.
    2. Mandatory: No
    3. Type: String (referencing object property of array index)

Internal Commands

Extension

This command defines an extension point in the variable value assignment/calculation process. It must supply two parameters – assembly and handler – and the extension type must implement an interface named IExecutionExtension.

Value

Sometimes, the value cannot be assigned with a setting attribute of value to the Var command, but it can be assigned with the Value command as an internal element.

Sample

Change an variable named ‘age’ value to ’10’

<Var name="age" value="10">

Or

Change a property ‘FirstName’ of variable named ‘person’ value to ‘Joe’

<Var name="person" path="FirstName" value='"Joe"'>

Or

<Var name="Menswear">
   <Value>
     <![CDATA[
      This is a multi line text!
      Line 1
      Line 2
      Line 3
   ]]>
   </Value>
</Var>

Or

<Var name="StarTotalPrice" value="(StarQty * StarPrice) - ((StarQty * StarPrice) * StarQtyDiscount)" />

Or

In this case item must be defined in the declaration section of the model.

<Var value="item.StarTotalPrice = (StarQty * StarPrice) - ((StarQty * StarPrice) * StarQtyDiscount)" />

Or

<Var name="StatementResult" source="xmlData" value="StatementAmount" process="true">
   <!-- 
     We want to handle the assignment inside our assembly
     if in this case it is an xpath value.
   -->
   <Extension assembly="Sample.Advert.dll" handler="Sample.XPathValue"/>
</Var>

Flow Control commands

This group of commands is responsible for managing the execution flow inside the running rule.

Do

This command creates a loop and all the child commands inside it get executed until you ask it to exit the loop by using ExitDo. The ‘do’ statement executes a statement or a block of statements repeatedly.

Summary
This command creates a scope of iteration in which the execution flow iterates until it receives an ExitDo command. A more conditional (i.e., controlled) iteration command is made available by the While functionality.
Internal Commands
ExitDo
This command sends a break command to the execution flow iterating inside the Do command (i.e., a command to end the iteration).
Samples

<Do>
   <Var name="i" value="i+1" />
   <If condition="i==2">
      <ExitDo/>
   </If>
</Do>

While

While this is similar to Do, this involves entering a condition which will be evaluated in every iteration of the loop. The engine will exit the execution of the loop when the condition is evaluated as a false value or it reaches the ExitWhile command.

Summary
This acts as the Do command, but the execution flow iterates inside the scope only if the condition parameter equals true.
Parameters

  1. condition
    1. Description: Name of a Boolean variable that checks the continuation of the iteration condition
    2. Mandatory: Yes
    3. Type: String (name of variable)

Internal Commands

ExitWhile

This command sends a break command to the execution flow iterating inside the While command.

Sample

<While condition="count!=3">
   <Var name="i" value="0"/>
   <Var name="count" value="count+1" process="true"/>
</While>

Iterate

This command can be used when iterating a collection or list. The engine exits the iteration when it reaches the end of the collection or ExitIterate command.

Summary
This command allows the iteration of a collection or array of objects. The execution flow iterates until it receives an ExitIterate command. A more conditional (i.e., controlled) iteration command is made available by the While functionality.
Parameters

  1. on
    1. Description: Variable name of the collection
    2. Mandatory: Yes
    3. Type: String (name of variable)
  2. name
    1. Description: This defines a variable inside the iterator and then allows the executing rule to access each element of the iterator via this naming.
    2. Mandatory: Yes
    3. Type: String

Internal Commands

ExitIterate

This command sends a break command to the execution flow iterating inside the Iterate command.

Sample

<Iterate name="x" on="officers">
   <If condition="x.Subordinate.Count == 0">
      <ExitIterate/>
   </If>
</Iterate>

If

When a direct evaluation of a condition is required inside a rule, this command can be utilized. For more complex logic ElseIf and Else can be used to complete the decision.

Summary
This command checks a condition and makes a decision based on it. The command has two internal commands – ElseIf and Else, which are used in an If-ElseIf-Else sequence.
Parameters

  1. condition
    1. Description: Name of a Boolean variable that checks the continuation of the iteration condition
    2. Mandatory: Yes
    3. Type: String (name of the variable)

Internal Commands

ElseIf

This command (if used) must follow the If command; it has a parameter like that of If that is mandatory.

Else

This command must be placed at the last part of the If command, and no parameter for it exists. The execution flow would be trapped here if neither of the conditions for If and ElseIf were met.

Condition

As a condition, you may use Validation Engine to create a structured condition as well by using “Condition” command. In this case you have to pass a variable reference to the “Condition” command using “ref” parameter.

Sample

<If condition="i==2">
      <CallMethod method="Console.WriteLine("inside If")"/>
      <ElseIf condition="i==1">
           <CallMethod method="Console.WriteLine("inside ElseIf")"/>
      </ElseIf>
      <Else>
           <CallMethod method="Console.WriteLine("inside Else!")"/>
      </Else>
</If>

Try

This command will handle any exception occurring inside its execution block. If any exception occurs during the execution, it will go to its Catch block.

Summary
This command controls the exception handling of the execution flow in its own defined scope. If an exception occurred during definition, the execution flow would be diverted to the Catch command.
Internal Commands

Catch

The exception will be assigned to the command’s ref parameter, which will refer to the local variable defined in the procedure.

Sample

<Try>
  <!-- 
   Do something... and if it throws exception (Error)
   it will continue the execution process from the 
   catch scope.
   -->
   <Catch ref="ex">
     <Var name="i" value="0"/>
   </Catch>
</Try>

Catch

When an exception occurs, the execution path will come to this block. Then it is time for processing what has gone wrong.

Summary
Parameters
Internal Commands
Samples

Throw

For any conditions for which you may want to halt the rule execution. In this case, this command can throw an exception and halt the rule execution. Your calling application will then receive a signal because of the thrown exception.

Summary
This command throws a necessary exception in the procedure and halts the execution.
Parameters

  1. message
    1. Description: Sets a message for the exception
    2. Mandatory: No
    3. Type: String
  2. ref
    1. Description: Name of the variable with a type of exception that is initialized before being thrown
    2. Mandatory: No
    3. Type: String (name of variable)

Sample

<If condition="StatementAmount>20">
     <Throw/>
</If>

Scope

When you need to group similar logic inside a rule so that you avoid duplicating these all over your code, this command will be useful. The other parts of the rule can then Call to a specifically named scope and pass some input parameters and retrieve some results. Also, the scope can be a reusable module between different procedural rules.

Summary
This command is a container in which to group the conditions. When no container command exists in the main body of the procedure, it also plays the role of the initialized container.
Note that the name defined for a level of scope must be unique.
A scope can be defined but not executed until it gets called by a Call command, which means that you are able to create modules and reuse them.
Parameters

  1. name
    1. Description: Sets the name for a scope
    2. Mandatory: No, unless the enabled parameter is undefined
    3. Type: String
  2. enabled
    1. Description: Indicates whether the scope will be an active part of the execution process or will be disabled
    2. Mandatory: No
    3. Type: Boolean (true/false) or string (name of Boolean variable)
  3. mode
    1. Description: Indicates whether scope behavior will be executed during the execution process or by the Call command
    2. Mandatory: No (Default value is Routine.)
    3. Type: Module, Routine

Internal Commands
The commands Declaration and Define can be used to define scope variables.
Samples

<Scope>
</Scope>
 
<Scope name="just a section">
</Scope>
 
<Scope name="test1" enabled="true">
</Scope>
 
<!-- 
     ‘en’ must be a defined Boolean variable and cannot be null when
     the execution process reaches the scope
-->
 
<Scope name="test2" enabled="en">
</Scope>

Object Creation commands

When dynamic creation of objects is required, this set of commands can be used.

New

If instantiation of a type is required in the rule execution, this command can be used. It allows the creation of objects from any type using their constructors.

Summary
This command enables you to start instantiating a Common Language Runtime (CLR) type or to initialize an array reference. To create a new instance of a type, the constructor of the type should be called.
When only name parameter with no Constructor is provided, it creates a new dynamic object.
Parameters

  1. name
    1. Description: Reference of an object to a defined variable of the type
    2. Mandatory: Yes
    3. Type: String (name of variable)
  2. arraySize
    1. Description: Array size should be initialized.
    2. Mandatory: No
    3. Type: Integer (number)
  3. typeId
    1. Description: Type address of the type to be created
    2. Mandatory: No
    3. Type: Name that is registered by ExecutorSetup.TypeIdRegistry.Register
  4. assembly
    1. Description: Assembly name that has the type to be created
    2. Mandatory: No
    3. Type: Name of assembly including its extension
  5. type
    1. Description: Full type name that is going to be created
    2. Mandatory: No
    3. Type: Full type name

Internal Commands

Constructor

This command, which defines the constructor of the type to be used, must be placed inside the New command when a new instance of Type is being created.

Param

This command, which defines parameters passed to the type constructor, must be placed inside the Constructor command.

Parameters

  1. type
    1. Description: Defines parameter type
    2. Mandatory: Yes
    3. Type: String
  2. value
    1. Description: Directly sets the value for the parameter
    2. Mandatory: No
    3. Type: Any
  3. ref
    1. Description: Sets the value for the parameter by referencing a variable
    2. Mandatory: No (No constructor command is required yet.)
    3. Type: String (variable name)

Sample

Creating a new object from a type by providing Constructor and Constructor’s Parameter:

<New name="dataInfo">
   <Constructor>
      <Param value="-1" type="System.Int32"/>
   </Constructor>
</New>

Creating new object and adding properties to it:

<Var value="list = array()"/>
<Add name="list">
   <New name="current">
     <Var value="current.Name='Arash'"/>
     <Var value="current.Family='Aghlara'"/>
   </New>
</Add>

Constructor

This command is a type constructor selector. It selects a suitable constructor of a type to be used to instantiate an object.

Summary
Parameters
Internal Commands
Samples

Array

Creating an array of objects is possible using New command. However, it might be easier to use this command instead to populate the values of the array directly.

Summary
This command initializes an array and enables the assignment of items in an array with other commands.
Parameters

  1. name
    1. Description: Reference of an object to a defined variable of an array type (e.g., System Object)
    2. Mandatory: Yes
    3. Type: String (name of variable)

Internal Commands

Add

Every item is added through this command, inside of which other commands can be placed, such as New, Var, and CallMethod.

Sample 1 – New instance creation

Use New to create a new instance of a type

<Array name="listSensorData">
  <Add>
    <New name="current">
      <Constructor>
        <Param type="System.DateTime" value='DateTime.Parse("2008-10-01 10:00:00")' process="true" />
        <Param type="System.Double" value="123.78"/>
      </Constructor>
    </New>
  </Add>
 
  <Add>
    <New name="current">
      <Constructor>
        <Param type="System.DateTime" value='DateTime.Parse("2008-10-01 10:05:00")' process="true" />
        <Param type="System.Double" value="125.78"/>
      </Constructor>
    </New>
  </Add>
</Array>

Sample 2 – Full rule to add objects into a collection

Use Var command and CallMethod command

<Procedure name="Test Module" enabled="true">
  <Declaration>
    <Using path="System.DateTime"/>
 
    <Define name="CreateInputValues" type="System.Object[]" direction="out" />
  </Declaration>
 
  <Scope name="main">
 
  <Array name="CreateInputValues">
      <Add>
        <Var name="listSensorData" ref="listSensorData" />
      </Add>
 
      <Add>
        <CallMethod method='DateTime.Parse("2008-10-01 10:22:00")'/>
      </Add>
 
      <Add>
        <Var name="testInteger" value="5" process="true"/>
      </Add>
    </Array>
  </Scope>
</Procedure>

Add

This command will be used inside the Array command and will add values for each index of the array.

Summary
Adds values to a list. Each child node inside Add command will be considered as a result to be added to the list.
Parameters

  1. name
    1. Description: Name of the list to be used for appending elements
    2. Mandatory: Yes
    3. Type: String (variable parameter name)

Sample

<Var value="list = array()"/>
<Add name="list">
  <New name="current">
    <Var value="current.Name='John'"/>
    <Var value="current.Family='Smith'"/>
  </New>
</Add>

List

This command creates a list that can act as a collection or set.

Summary
Parameters
Internal Commands
Samples

DataTable

This command allows the building of a template to generate a table of data based on a set of inputs.

Summary
Parameters
Internal Commands
Samples

Task Commands

CallREST

Calls out to any REST API and returns the results.

Summary
Parameters
Internal Commands
Samples

CallMethod

When there are objects defined inside a rule, this command can make a call to the object methods.

Summary
This command enables you to make a method call on a CLR object. You can pass the object reference to the procedure from the application or create the object using object creation commands. Either way, this command enables a method call on the instantiated object.

The method parameter can be passed directly as part of the method signature or in a more controlled form through the Param command.
Parameters

  1. method
    1. Description: Name of the method of the object, which also includes the object reference
    2. Format
      1. objectReference.MethodName(param1, param2, param3)
      2. objectReference.MethodName (In this format, Param commands are mandatory.)
    3. Mandatory: Yes
    4. Type: A string in the given format
  2. return
    1. Description: A variable in which the method result is stored
    2. Mandatory: No
    3. Type: String (name of the variable)

Internal Commands

Param

This command passes a value to the method for referencing.

Sample

<CallMethod method="xmlData.Write(34.3)" />
 
Or
 
<CallMethod method="xmlData.DisplayAdvert">
     <Param ref="Menswear"/>
</CallMethod>

Invoke

Calling a function and method by passing input parameters as embedded elements rather than attribute values.

Summary
Parameters
Internal Commands
Samples

CallProc

If your application logic is complex and requires multiple Procedural rules, this command can call an externally defined rule and return the result to the running execution context.

Summary
In a procedural engine, multiple procedures can be interlinked. This means that a procedural rule can execute another rule; thus, the context of the parent rule can be shared, and the result can be copied back to the root context. Different scenarios can be managed in several ways.
Parameters

  1. contextMode
    1. Description: Sets the context for the called procedure
    2. Mandatory: Yes
    3. Types
      1. New: Creates a new context and uses such context for execution; in this case, the variable of the new context must be registered by the Param command
      2. Shared: Uses the current context for execution and the new procedure after finishing the procedure execution; the current execution variable context (of only out-variables) is copied to the original one
  2. resultCopyMode
    1. Description: This attribute is set when the target procedure has variables that need to be accessed via the root executing procedure.
    2. Mandatory: Yes
    3. Types
      1. None: Does not copy
      2. AddOut: Copies out-variables
      3. AddIn: Copies in-variables
      4. AddBoth: Copies both in- and out-variables
  3. return
    1. Description: Sets a value of a parameter as a return value of the operation/call
    2. Mandatory: No
    3. Types: String (name of a parameter

Internal Commands

Param

This command passes a value to the procedure and registers new variables in a new context if required.

ProcSource

This command provides the rule with a source to be loaded and executed. It can be a relative or absolute file path or a RuleSet address. If it is a relative file path, the location is initiated from your application’s execution folder. If it is a RuleSet address, it should be a valid address, and the engine should be initialized using RuleSet overload.

Sample

<CallProc contextMode="Shared" resultCopyMode="AddOut" >
   <ProcSource uri="Rules/Ver2/CalculatePriceSubTotal.xml" />
   <!-- 
         When we use contextMode="New" we need to pass the
         required parameter for the target procedure, otherwise
         all of the variables are shared in the main procedure and do
         not need to pass <Param .... />
 
   <Param name="StarQty" ref="StarQty"/>
   <Param name="GoldQty" ref="GoldQty"/>
   <Param name="SilverQty" ref="SilverQty"/>
 
  -->
   <Param name="StarQtyDiscount" ref="StarQtyDiscount"/>
   <Param name="GoldQtyDiscount" ref="GoldQtyDiscount"/>
   <Param name="SilverQtyDiscount" ref="SilverQtyDiscount"/>
 
</CallProc>

Call

When your rule has some scopes this command can call to and execute the scope, and then return to its previous execution path.

Summary
Once the modules are defined (i.e., checked for Scope), you can execute them using the Call command.

This command needs only the address of the module, either the name of a scope or a nested address. The module must be in the same scope level as the Call command used.

Parameter values can be passed to the calling module using Param commands, and output direction variables can be read from the called module using the Var command.
Parameters

  1. module
    1. Description: Address of the called module, either a single scope name or a nested address
    2. Mandatory: Yes
    3. Type: String (module name)

Sample

<Scope mode="module" name="calculate">
    <Var name="StarTotalWeight" value="StarQty * StarWeight" process="true"/>
    <Var name="GoldTotalWeight" value="GoldQty * GoldWeight" process="true"/>
    <Var name="SilverTotalWeight" value="SilverQty * SilverWeight" process="true"/>
    <Var name="WeightTotal" value="StarTotalWeight + GoldTotalWeight + SilverTotalWeight" process="true"/>
</Scope>
<Scope>
   <Call module="calculate"/>
</Scope>

HostCallBack

Sometimes the calling application requires signals to be received from the executing rules. This command will send an event to the running engine and then your application and handle the event required to respond to the rule signal.

Summary
This command sends a callback to the application hosting the engine, which can be an actual running application, Windows service, Windows Communication Foundation, web service, or any engine host (container).
Parameters

  1. tagValue
    1. Description: Sends a value to the host
    2. Mandatory: No (Either tagRef or tagValue must be supplied.)
  2. tagRef
    1. Description: Sends a value reference to the host
    2. Mandatory: No (Either tagRef or tagValue must be supplied.)
  3. key
    1. Description: Sends a key to the host to make a decision in a specific channel by key value
    2. Type: String
    3. Mandatory: No
  4. responseRef
    1. Description: Receives a response from the host and sets the value on the running context of the rule
    2. Type: String (name of variable)
    3. Mandatory: No

Samples

<CallMethod method="Console.Write("Enter a number? >")"/>
 
<!-- 
  It sends the request to the user to enter a value
  and stores it back to variable named ‘i’
  So it will be accessible through its rule
  to be used after receiving the value from user input.
-->
<HostCallback tagValue="count!=3" key="askUser" responseRef="i"/>
 
<CallMethod method="Console.Write("You typed:{0}",i)"/>

Include

When scopes are defined on a separate physical layer (different files than the actual rule), this command will load the external scope inside the current loaded rule.

Summary
This command enables you to split your procedural rules into more dynamic scopes and to import each scope to the body of the rule during the execution process. By supplying the source to be imported as a string or IElementModel type, the scope will be considered as part of your rule body.

If the imported scope is a string type, it must be encoded as a valid XML or RuleSet address. If it is an XML, its special characters must be respected. Also, the imported string must be encapsulated with a Scope command. If it is a RuleSet address, it should be a valid address, and the engine should be initialized using RuleSet overload.

The behavior included will not be executed. In order to do so, the Call command must be used. The included source parameter can accept a ruleset address as well (e.g., ruleset://flow/main?parameter:name=CreateCaseOfficer)
Parameters

  1. source
    1. Description: Assigns a source that is imported by the command, as well as a variable name or ruleset address. If it is variable name, the variable type must be defined as a String or IElementModel.
    2. Mandatory: Yes
    3. Type: String (variable name)

Samples

<Include source="src1"/>

or

<Include source="ruleset://flow/main?parameter:name=CreateCaseOfficer" />

Param

For lots of commands, some initialization values are required. This command is responsible for preparing and passing the values to the Rule commands.

Summary
This command passes a parameter for different purposes: calling a scope, instantiating an object, or passing values to a constructor.
Parameters

  1. name
    1. Description: Name of the target object variable
    2. Mandatory: Yes
    3. Type: String
  2. value (either this or a ref must be supplied):
    1. Description: Contains the value or formula
    2. Mandatory: No
    3. Type: String
  3. ref (either this or a value must be supplied):
    1. Description: Contains the reference of the variable name or can be a nested address
    2. Mandatory: No
    3. Type: String
  4. process
    1. Description: Defines whether the value is a direct value or needs to be computed
    2. Mandatory: No
    3. Type: Boolean (true/false). Default value is true.
  5. type
    1. Description: Type of value supplied
    2. Mandatory: Yes
    3. Type: String
  6. assembly
    1. Description: Name of the assembly if the type is custom-built
    2. Mandatory: No
    3. Type: String

Behaviours
This command behaves differently by defining or eliminating different parameters:
1. type: tries to create an object from a provided value without any evaluation of the value
2. eliminating type: tries to evaluate the value provided if the process is set to true, or if no process is found.
Samples

The following Param commands demonstrate the sample. They try to evaluate the value which is going to parse a string as a DateTime.

<Param value="DateTime.Parse('2008-10-01 10:00:00')" process="true" />
<Param value="DateTime.Parse('2008-10-01 10:00:00')"  />

The following sample tries to create value as a double number:

<Param type="double" value="123.78"/>

The following sample tries to create the value as a string. Please note the value is not quoted in ” or ‘.

<Param type="string" value="Hello"/>

The following sample tries to evaluate the value expression. Because the type is not defined and process is true by default, the value becomes an expression and requires evaluation.

<Param value="'Hello'"/>

Database commands

This set of commands enables the rule to communicate with a data source (database) and retrieve a value, single row or multiple rows as part of the rule execution process.

Database

This command defines a connection to a data source: MsAccess, MsSql, Oracle, ODBC.

See this article to read more.

Summary

This command defines the database to execute TSQL or a Stored Procedure against a data store. It supports built-in database types as well as custom databases (e.g., PostgreSQL). If your database is not built-in:

  1. Ms SQL
  2. Access
  3. Oracle
  4. ODBC

then you should provide a type address to IDbconnection and the related assembly.

Parameters

  1. connection
    1. Description: A connection string to the database
    2. Mandatory: Yes
    3. Type: String
  2. connection-ref
    1. Description: A reference to a connection string variable holding a value
    2. Mandatory: Yes
    3. Type: String
  3. type
    1. Description: Type of database
    2. Mandatory: Yes
    3. Type: MsAccess, MsSql, Oracle, Odbc or alternatively, type can be the CLR Type name including namespace that has the IDbConnection implementation.
    4. assembly: The assembly name that has the custom IDbConnection connection.

Samples

Standard Database Type

<Database connection="Data Source=.\SqlExpress;Initial Catalog=Car-Insurance;User ID=sa;Password=123;MultipleActiveResultSets=True" 
          type="MsSql">
    <SelectList command="select ([Made]+'-'+[Model]) Car from [dbo].[HighRiskCars]" return="probList1" multi="True" />
  </Database>

Custom Database Type

<Var name="cnn" value='"Provider=Microsoft.Jet.OLEDB.4.0;Data Source="+ Directory.GetCurrentDirectory()+ "\\DatabaseSample.mdb"' process="true"/>
<Database connection-ref="cnn" 
          type="System.Data.OleDb.OleDbConnection" 
          assembly="system.data.dll">
   <SelectValue command="select FName from person where id = @id" return="name">
     <Param name="id" type="System.Int32" value="1"/>
   </SelectValue>
</Database>

SelectRow

When rows are required to be retrieved from a database table, this command can be used.

Summary
This command selects one or more records from a database table. The return value from the database will be one or multiple rows (i.e., an array of rows). Each row will have a GetValue (string name) method that can be accessed to read the value of the columns of the row; otherwise, its indexer can be used.
Parameters

  1. command
    1. Description: The Select command
    2. Mandatory: Yes
    3. Type: String
  2. return
    1. Description: Name of the variable in which the row will be stored
    2. Mandatory: Yes
    3. Type: String
  3. storedProcedure
    1. Description: Determines whether the command should execute a stored procedure in the database
    2. Mandatory: No
    3. Type: Boolean (true/false)
  4. multi
    1. Description: Indicates whether the Select command will return multiple rows
    2. Mandatory: No
    3. Type: Boolean (true/false)
  5. expando
    1. Description: Indicates whether the Select result will be returned as a single/list of ExpandoObject
    2. Mandatory: No
    3. Type: Boolean (true/false)
  6. dynamicSQL
    1. Description: True when the ‘command’ is going to be evaluated against the current execution context, otherwise false.
    2. Mandatory: No
    3. Type: Boolean (true/false)

Internal Commands

Param

This command sends a Break command to the execution flow iterating inside a Do command.

Samples

<Database connection-ref="cnn" type="MsAccess">
  <SelectRow command="select * from person where id = @id" multi="true" return="list">
    <Param name="id" type="System.Int32" value="1"/>
  </SelectRow>
</Database>
<Var name="name" value='(list[0]).GetValue("FName")' process="true"/>

SelectList

When rows are required to be retrieved from a database table this command can be used to create a list of values, either simple primitive values or complex object values.

Summary
This command is very similar to SelectRow command the difference is it builds a list for values based on the return result from the query. If one column is selected from SELECT command, then the list contains all the values for that selected column only. If multiple columns are selected, then the list contains a complex object that the values of the column can be accessed by object properties.
Parameters

  1. command
    1. Description: The Select command
    2. Mandatory: Yes
    3. Type: String
  2. return
    1. Description: Name of the variable in which the row will be stored
    2. Mandatory: Yes
    3. Type: String
  3. storedProcedure
    1. Description: Determines whether the command should execute a stored procedure in the database
    2. Mandatory: No
    3. Type: Boolean (true/false). Default is true.
  4. multi
    1. Description: Indicates whether the Select command will return multiple rows
    2. Mandatory: No
    3. Type: Boolean (true/false)

Internal Commands

Param

This command sends a Break command to the execution flow iterating inside a Do command.

Samples

Return list is a list of string values:

<Database connection-ref="cnn" type="MsSql">
  <SelectList command="select ([Made]+'-'+[Model]) as Car from [dbo].[HighRiskCars]" return="listResults"/>
</Database>
 
<!-- This will read the first value which is a string -->
<Var name="firstItem" value="listResults[0]"/>

Return list is a list of objects that have tow properties: made and model

<Database connection-ref="cnn" type="MsSql">
  <SelectList command="select [Made] as made, [Model] as model from [dbo].[HighRiskCars]" return="listResults"/>
</Database>
 
<!-- This will read the 'made' property of the first item in the list -->
<Var name="firstItem" value="listResults[0].made"/>

SelectValue

When a single value (cell value) is required to be selected from a database table, this command can be used.

Summary
This command returns a single value from the database.
Parameters

  1. command
    1. Description: The Select command
    2. Mandatory: Yes
    3. Type: String
  2. return
    1. Description: Name of the variable in which the row will be stored
    2. Mandatory: Yes
    3. Type: String
  3. storedProcedure
    1. Description: Determines whether the command should execute a stored procedure in the database
    2. Mandatory: False
    3. Type: Boolean (true/false)

Samples

<Database connection-ref="cnn" type="MsSql">
  <SelectValue command="select FName from person where id = @id" return="name">
    <Param name="id" type="System.Int32" value="1"/>
  </SelectValue>
</Database>

ExecuteNonQuery

When the Insert, Delete or Update command is required, this command can be used.

Summary
Database commands such as Insert, Delete and Update can be performed using this rule command.
Parameters

  1. command
    1. Description: The TSQL command
    2. Mandatory: Yes
    3. Type: String
  2. return
    1. Description: Name of the variable in which the row will be stored
    2. Mandatory: Yes
    3. Type: String
  3. storedProcedure
    1. Description: Determines whether the command should execute a stored procedure in the database
    2. Mandatory: False
    3. Type: Boolean (true/false)

Samples

<While condition="index lt 2">
  <Var name="index" value="index+1"/>
  <ExecuteNonQuery command="INSERT INTO person ([fname],[lname]) VALUES (@name, @family)" return="count">
    <Param name="name" value='"name"+(index.ToString())'/>
    <Param name="family" value='"family"+(index.ToString())'/>
  </ExecuteNonQuery>  
</While>

ExecuteScalar

If the result of executing a query returns a value, this command should be used.

Summary
This command can be used when you wish to run a query command result (or more likely a stored procedure) that returns data.
Parameters

  1. command
    1. Description: The TSQL command that returns a single cell column value
    2. Mandatory: Yes
    3. Type: String
  2. return
    1. Description: Name of the variable in which the row will be stored
    2. Mandatory: Yes
    3. Type: String
  3. storedProcedure
    1. Description: Determines whether the command should execute a stored procedure in the database
    2. Mandatory: False
    3. Type: Boolean (true/false)

Sample

<Database connection-ref="cnn" type="MsSql">
    <ExecuteScalar command="SELECT count(*) from person" return="count"/>
</Database>

Updated on July 31, 2019

Was this article helpful?

Related Articles