////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////
:documentationPath: /pipeline/transforms/
:language: en_US
:description: The rules executor uses Drools to check rows against a rule set

= image:transforms/icons/rules_exec.svg[Rules executor transform Icon, role="image-doc-icon"] Rules executor

[%noheader,cols="3a,1a", role="table-no-borders" ]
|===
|
== Description

The Rules Executor allows fields of incoming rows to be executed against a rule set. This may be useful to determine additional information or route rows onto another transform.

https://www.drools.org/[Drools] is the present rule engine implementation and its https://docs.drools.org/7.68.0.Final/drools-docs/html_single/index.html#_droolslanguagereferencechapter[rule language] can be referenced for use by this transform. https://docs.drools.org/7.68.0.Final/drools-docs/html_single/index.html#_welcome[Drools documentation]

|
== Supported Engines
[%noheader,cols="2,1a",frame=none, role="table-supported-engines"]
!===
!Hop Engine! image:check_mark.svg[Supported, 24]
!Spark! image:question_mark.svg[Maybe Supported, 24]
!Flink! image:question_mark.svg[Maybe Supported, 24]
!Dataflow! image:question_mark.svg[Maybe Supported, 24]
!===
|===

== Details
For each row processed by the Rules Executor transform each column is converted to a _Rules.Column_ then injected into the rule engine and executed against the rules set. _Rules.Column_ contains four properties:

_externalSource_: boolean property indicating if this Rules.Column was injected from an external source (a field from a processed row)

_name_: name of this field

_type_: type of data stored in payload (one of ValueMetaInterface.typeCodes - Number, String, Integer, Date, Boolean, etc...)

_payload_: value of this field

Results are generated by creating Rules.Column objects. The transform is configured to pick up these generated objects by name.

=== Rules Tab

The _Rules_ tab is where you enter your rule definition or a reference to the rule file..

[options="header"]
|===
|Option|Description
|Rules filename|
|Rules script to execute|
|===

=== Rules result Tab

Rules result tab defines the layout of the Rules output fields.

[options="header"]
|===
|Option|Description
|Result column name|
|Result column type|
|===

== Example
All Rule Definitions should contain "import org.apache.hop.pipeline.transforms.drools.Rules.Column;" to give access to the Rules.Column class.

For the input row: fica_seed (Integer), hi (String), fica (Integer); three Rules.Column objects will be created in the Rules Engine:

[options="header"]
|===
|Rules.Row->row (Map)|Type|Payload
|fica_seed|Integer|-3561151667
|hi|String|test
|fica|Integer|bad
|===

Rules can be defined and applied:
[source,drools]
----
rule "Decline"
    dialect "mvel"
    when
        $fica : Column(name == "fica", payload < 550)

    then
        Column approvalStatus = new Column();
        approvalStatus.name = "approvalStatus"
        approvalStatus.type = String.class
        approvalStatus.payload = "declined"

        Column approvalClassification = new Column();
        approvalClassification.name = "approvalClass"
        approvalClassification.type = String.class
        approvalClassification.payload = "Declined: fica too low"

        insert(approvalStatus);
        insert(approvalClassification);

        System.out.println("Declined");
end
----
Rules.Column properties can be checked as in the above's left hand side.

Rules.Column objects can be created for pickup as in the above's right hand side.

The transform can be told to pickup a generated Rules.Column object by defining the Rules.Column name in the transform's Results tab. Type conversions can be applied by setting the Result column type as well.