@dhis2/rule-engine


$3

#### Initialization
RuleEngine is initialized in two steps.
- Metadata configuration within RuleEngineContext
- Setting background / contextual data for RuleEngine

``
RuleEngineContext ruleEngineContext = RuleEngineContext.builder(ruleExpressionEvaluator)
.ruleVariables(ruleVariables) // optional
.rules(rules) // at least one rule must be supplied
.build();
`

.builder factory method accepts instance of RuleExpressionEvaluator - something what knows how to evaluate program rule statements. RuleExpressionEvaluator implementation might be specific to certain platform. For example, on JVM it can be backed by JEXL, while on android it can be something like duktape-android.

RuleEngineContext instance is immutable. It means it can be safely shared and reused across multiple threads. Next step will be setting some contextual data to the rule engine, which will be used as a source of data for most variables.

`
RuleEngine ruleEngine = ruleEngineContext.toEngineBuilder()
.enrollment(enrollment) // contextual enrollment
.events(events) // contextual events
.build();
`

RuleEngine is immutable as well. In example above, toEngineBuilder() method returns and instance of RuleEngine.Builder class. All parameters are optional, it means that one can simply call ruleEngineContext.toEngineBuilder().build() to get an instance of engine back.

#### Evaluation
Now we can send target event or enrollment to the engine in order to get some RuleEffects back. Before showing code, there are certain quirks which one should be aware of. You are not allowed to send duplicate events or enrollments to the engine as evaluation targets. In other words, if you have already supplied enrollment or event as a part of the contextual data, you won't be allowed to send it again as evaluation target. For example:

`
RuleEngine ruleEngine = ruleEngineContext.toEngineBuilder()
.enrollment(enrollment) // contextual enrollment
.build();

ruleEngine.evaluate(enrollment); // not allowed!
`

In general, there are a few scenarios in which rule engine can be used. Let's use next notation to declare possible options.

(contextual_data)[evaluation_target]

- (single_events - target_event)[target_event]: applicable for programs without registration.
- (enrollment, enrollment_events - target_event)[target_event]: applicable for programs with registration. In this case, event is under evaluation.
- (enrollment_events)[target_enrollment]: evaluating enrollment. In this case, events which are a part of enrollment, can be used as source of values for program rule variables.

There are two methods for evaluation at the moment:
`
List enrollmentEffects = ruleEngine.evaluate(enrollment);
List eventEffects = ruleEngine.evaluate(event);
`

List of supported environment (contextual) variables:
- current_date
- event_date
- event_count
- due_date
- event_id
- enrollment_date
- enrollment_id
- enrollment_count
- incident_date
- tei_count

Development

$3

This library uses the Binary Compatibility Validator plugin, which verifies that there are no changes in the public API of the library.

The way of work is: there is a file generated by the plugin (api/expression-parser.api) with the binary representation of the expected public API. The plugin has a task (apiCheck) that verifies that the public API of the code matches the expected API in the file.

If there is an intentional change in the public API, this file must be updated to reflect the changes and included as part of the pull request. It can be updated running the task apiDump. This task can be run in the command line (./gradlew apiDump) or using Gradle window in Intellij.

$3


Library version is defined in the file build.gradle.kts. The version must be manually increased
and include the -SNAPSHOT suffix. Please make sure the version is updated before opening the PR.

$3

On merged pull request to main:
- Production release to Maven.
- Production release to NPMJS.

On pull request creation/update:
- Snapshot release to Maven.

On demand:
- Beta releases to NPMJS can be triggered on demand by using the action "Publish NPM beta".
Please make sure you select the right branch in the selector.

Publication can be skipped by adding [skip publish]` to the pull request title.

---
WIP