|
1 | 1 | # Rules Framework |
2 | 2 |
|
3 | | -Rules.Framework is a generic rules framework that allows defining and evaluating rules for complex business scenarios. |
4 | | - |
5 | | -Why use rules? Most of us at some point, while developing software to support a business, have come across fast paced business logic changes. Sometimes, business needs change overnight, which requires a fast response to changes by engineering teams. By using rules, changing a calculus formula, a value mapping or simply a toggle configuration no longer requires code changes/endless CI/CD pipelines, QA validation, and so on... Business logic changes can be offloaded to configuration scenarios, instead of development scenarios. |
| 3 | +Rules.Framework is a generic framework that allows defining and evaluating rules for complex business scenarios. |
6 | 4 |
|
7 | 5 | [](https://app.codacy.com/gh/Farfetch/rules-framework?utm_source=github.com&utm_medium=referral&utm_content=Farfetch/rules-framework&utm_campaign=Badge_Grade_Settings) |
8 | 6 | [](https://github.com/luispfgarces/rules-framework/actions/workflows/dotnet-build.yml) |
9 | 7 |
|
| 8 | +## What is a rule? |
| 9 | + |
| 10 | +A rule is a data structure limited in time (`date begin` and `date end`), whose content is categorized by a `content type`. Its applicability is constrained by `conditions`, and a `priority` value is used as untie criteria when there are multiple rules applicable. |
| 11 | + |
| 12 | +## Why use rules? |
| 13 | + |
| 14 | +By using rules, we're able to abstract a multiplicity of business scenarios through rules configurations, instead of heavy code developments. Rules enable a fast response to change and a better control of the business logic by the product owners. |
| 15 | + |
10 | 16 | ## Packages |
11 | 17 |
|
12 | | -|Name |nuget.org|fuget.org| |
13 | | -|---------------------------------|----|---------| |
14 | | -|Rules.Framework|[](https://www.nuget.org/packages/Rules.Framework/)|[](https://www.fuget.org/packages/Rules.Framework)| |
15 | | -|Rules.Framework.Providers.MongoDb|[](https://www.nuget.org/packages/Rules.Framework.Providers.MongoDb/)|[](https://www.fuget.org/packages/Rules.Framework.Providers.MongoDb)| |
16 | | -|Rules.Framework.Providers.InMemory|[](https://www.nuget.org/packages/Rules.Framework.Providers.InMemory/)|[](https://www.fuget.org/packages/Rules.Framework.Providers.InMemory)| |
| 18 | +|Name |nuget.org|downloads|fuget.org| |
| 19 | +|---------------------------------|----|---------|-----| |
| 20 | +|[Rules.Framework](#rulesframework)|[](https://www.nuget.org/packages/Rules.Framework/)|[](https://www.nuget.org/packages/Rules.Framework/)|[](https://www.fuget.org/packages/Rules.Framework) |
| 21 | +|[Rules.Framework.Providers.MongoDB](#rulesframeworkprovidersmongodb)|[](https://www.nuget.org/packages/Rules.Framework.Providers.MongoDB/)|[](https://www.nuget.org/packages/Rules.Framework.Providers.MongoDB/)|[](https://www.fuget.org/packages/Rules.Framework.Providers.MongoDB) |
| 22 | +|[Rules.Framework.WebUI](#rulesframeworkwebui)|[](https://www.nuget.org/packages/Rules.Framework.WebUI/)|[](https://www.nuget.org/packages/Rules.Framework.WebUI/)|[](https://www.fuget.org/packages/Rules.Framework.WebUI) |
17 | 23 |
|
18 | | -## Features |
| 24 | +## Rules.Framework |
| 25 | +[](https://www.nuget.org/packages/Rules.Framework/) |
19 | 26 |
|
20 | | -The following listing presents features implemented and features to be implemented: |
| 27 | +The Rules.Framework package contains the core of the rules engine. It includes an in-memory provider for the rules data source. |
21 | 28 |
|
22 | | -- [x] Rules evaluation (match one) |
23 | | -- [x] Rules evaluation (match many) |
24 | | -- [x] Rules search |
25 | | -- [x] Rules content serializarion |
26 | | -- [ ] Rules data source caching |
27 | | -- [x] Rules management (Create, Read, Update) |
28 | | -- [X] In-memory data source support |
29 | | -- [x] MongoDB data source support |
30 | | -- [ ] SQL Server data source support |
| 29 | +### Basic usage |
| 30 | + |
| 31 | +To set up a `RulesEngine`, define the content types and condition types to be used. |
31 | 32 |
|
32 | | -## How it works |
| 33 | +```csharp |
| 34 | +enum ContentType { FreeSample = 1, ShippingCost = 2 } |
| 35 | +enum ConditionType { ClientType = 1, Country = 2 } |
| 36 | +``` |
33 | 37 |
|
34 | | -Starting with the basics, what are we considering a rule? |
| 38 | +Build the engine with the `RulesEngineBuilder`. |
35 | 39 |
|
36 | | -> A rule is a data structure limited in time (**date begin and date end**) which is categorized by a **content type**. It's match on scenario is constrained by **conditions** which are used to determine if it is applicable, and also defines a **priority** as untie criteria when multiple rules have a match. A rule contains its **content** to be used on a specific business scenario. |
| 40 | +```csharp |
| 41 | +var rulesEngine = RulesEngineBuilder.CreateRulesEngine() |
| 42 | + .WithContentType<ContentType>() |
| 43 | + .WithConditionType<ConditionType>() |
| 44 | + .SetInMemoryDataSource() |
| 45 | + .Configure(c => c.PriorityCriteria = PriorityCriterias.BottommostRuleWins) |
| 46 | + .Build(); |
| 47 | +``` |
| 48 | +Use the `RuleBuilder` to assemble a rule. |
37 | 49 |
|
38 | | -For Rules.Framework, a valid rule accounts for the following conditions: |
| 50 | +```csharp |
| 51 | +var ruleForPremiumFreeSample = RuleBuilder |
| 52 | + .NewRule<ContentType, ConditionType>() |
| 53 | + .WithName("Rule for perfume sample for premium clients.") |
| 54 | + .WithContent(ContentType.FreeSample, "SmallPerfumeSample") |
| 55 | + .WithCondition(c => c |
| 56 | + .AsValued(ConditionType.ClientType) |
| 57 | + .OfDataType<string>() |
| 58 | + .WithComparisonOperator(Operators.Equal) |
| 59 | + .SetOperand("Premium") |
| 60 | + .Build()) |
| 61 | + .WithDateBegin(new DateTime(2020, 01, 01)) |
| 62 | + .Build(); |
| 63 | +``` |
39 | 64 |
|
40 | | -- Categorized by a **content type**, which groups rules by those that will be evaluated together. Rules from different content types won't be evaluated together. Content type is a user defined type, which can be a value type or a object, depending on the requirements of usage. |
41 | | -- Has a **name**, which must be unique by content type. |
42 | | -- Is constrained in time by a **date begin** and a **date end**. Date begin must be always set, and date end can be null (meaning that rule is applied from date begin to _ad eternum_). Please note that date begin threshold is inclusive and date end threshold is exclusive, so if you define a rule with date begin as "2020-01-01" and date end as "2021-01-01", if evaluation date is set to "2020-01-01", rule will match, but if evaluation date is set to "2021-01-01", rule will not match. |
43 | | -- Has a **priority** numeric value, which works as tiebreaker when many rules match on rules interval and given input conditions. Rules.Framework has the ability to configure if tiebreaker criteria is set to highest priority value or lowest priority value. This value must always be positive. |
44 | | -- Also has a set of **conditions** disposed in tree. Conditions can be set combined by AND/OR operators and by using comparison operators to compare values set on rule (integer, boolean, string or decimal) to input conditions. Conditions are categorized by a condition type, which must be one of the user-defined types (either value types or objects). |
45 | | -- And a **content** defined by user and totally up to the user to validate it (can virtually be anything the user wants, as long as the persistence mechanism used as data source supports it). |
| 65 | +Add a rule to the engine with the `AddRuleAsync()`. |
46 | 66 |
|
47 | | -Bellow you can see a simple sample for demonstration purposes: |
| 67 | +```csharp |
| 68 | +rulesEngine.AddRuleAsync(ruleForPremiumFreeSample.Rule, RuleAddPriorityOption.ByPriorityNumber(1)); |
| 69 | +``` |
48 | 70 |
|
49 | | - |
| 71 | +Get a matching rule by using the `MatchOneAsync()` and passing a date and conditions. |
50 | 72 |
|
51 | | -The sample rule presented: |
| 73 | +```csharp |
| 74 | +var matchingRule = rulesEngine.MatchOneAsync( |
| 75 | + ContentType.FreeSample, |
| 76 | + new DateTime(2021, 12, 25), |
| 77 | + new[] |
| 78 | + { |
| 79 | + new Condition<ConditionType>() { Type = ConditionType.ClientType, Value = "Premium" } |
| 80 | + }); |
| 81 | +``` |
52 | 82 |
|
53 | | -- Is described by it's name as "Body Mass default formula" - a simple human-readable description. |
54 | | -- Has a content type "Body Mass formula" that categorizes it. |
55 | | -- Begins at 1st January 2018 and never ends - which means that requesting on a date before 1st January 2018, rule is not matched, but after midnight at the same date, the rule will match. |
56 | | -- Priority is set to 1. This would be used as tiebreaker criteria if there were more rules defined, but since there's only one rule, there's no difference on evaluation. |
57 | | -- Rule has no conditions defined - which means, requesting on a date on rule dates range, it will always match. |
| 83 | +### Complex scenarios |
58 | 84 |
|
59 | | -Simple right? You got the basics covered, let's complicate this a bit by adding a new rule. The formula you saw on the first rule is used to calculate body mass when using kilograms and meters unit of measures, but what if we wanted to calculate using pounds and inches? Let's define a new rule for this: |
| 85 | +For a more thorough explanation of the Rules.Framework and all it enables, check the [Wiki](https://github.com/Farfetch/rules-framework/wiki). |
60 | 86 |
|
61 | | - |
| 87 | +Check also the test scenarios and samples available within the source-code, to see more elaborated examples of its application. |
62 | 88 |
|
63 | | -Newly defined rule (Rule #2): |
| 89 | +## Rules.Framework.Providers.MongoDB |
| 90 | +[](https://www.nuget.org/packages/Rules.Framework.Providers.MongoDb/) |
64 | 91 |
|
65 | | -- Becomes the rule with priority 1. |
66 | | -- Defines a new formula. |
67 | | -- Defines a composed condition node specifying that a AND logical operator must be applied between child nodes conditions results. |
68 | | -- Defines a condition node with data type string, having a condition type of "Mass unit of measure", operator equal and operand "pounds". |
69 | | -- Defines a second condition node with data type string, having a condition type of "Height unit of measure", operator equal and operand "inches". |
| 92 | +To keep rules persisted in a MongoDB database, use the extension method in the Providers.MongoDB package to pass your MongoClient and MongoDbProviderSettings to the `RulesEngineBuilder`. |
70 | 93 |
|
71 | | -If you request a rule for the content type "Body Mass formula" by specifying date 2019-01-01, "Mass unit of measure" as "pounds" and "Height unit of measure" as "inches", both rules will match (remember that Rule #1 has no conditions, so it matches anything). At this point is where priority is used to select the right one (by default, lowest priority values win to highest values, but this is configurable), so Rule #2 is chosen. |
| 94 | +```csharp |
| 95 | +var rulesEngine = RulesEngineBuilder.CreateRulesEngine() |
| 96 | + .SetInMongoDBDataSource(mongoClient, mongoDbProviderSettings) |
| 97 | +``` |
72 | 98 |
|
73 | | -> Remember, when you are defining rules, there are several ways on which you can define rules to match your logic needs. There's simply no silver bullet. If you need to have always a rule match, you need to find a default rule - one that matches on every scenario - and do define it, to ensure you always get a response. |
| 99 | +## Rules.Framework.WebUI |
| 100 | +[](https://www.nuget.org/packages/Rules.Framework.WebUI/) |
| 101 | +
|
| 102 | +The WebUI package offers a way of visualizing the rules in your web service. To configure the UI, pass the rules engine as generic to the `IApplicationBuilder` extension method provided. |
| 103 | + |
| 104 | +```csharp |
| 105 | +app.UseRulesFrameworkWebUI(rulesEngine.CreateGenericEngine()); |
| 106 | +``` |
| 107 | + |
| 108 | +Access is done via the endpoint `{host}/rules/index.html`. |
| 109 | + |
| 110 | + |
| 111 | + |
| 112 | +## Features |
| 113 | + |
| 114 | +The following list presents features already available and others projected: |
| 115 | +- [x] Rules evaluation (match one) |
| 116 | +- [x] Rules evaluation (match many) |
| 117 | +- [x] Rules content serialization |
| 118 | +- [x] Rules management (Create, Read, Update) |
| 119 | +- [x] In-memory data source support |
| 120 | +- [x] MongoDB data source support |
| 121 | +- [ ] SQL Server data source support |
| 122 | +- [ ] Rules data source caching |
| 123 | +- [x] Rules data source compilation |
| 124 | +- [x] WebUI for rules visualization |
74 | 125 |
|
75 | | -## Using the framework |
| 126 | +## Documentation |
76 | 127 |
|
77 | | -1. [Getting started](docs/getting-started.md) |
78 | | -2. [Add rules](docs/add-rules.md) |
79 | | -3. [Update rules](docs/update-rules.md) |
80 | | -4. [Search rules](docs/search-rules.md) |
81 | | -5. [Get Unique Condition Types](get-unique-condition-types.md) |
82 | | -6. [In-memory data source provider](docs/using-in-memory-data-source.md) |
83 | | -7. [MongoDB data source provider](docs/using-mongo-db-data-source.md) |
84 | | -8. [New data source provider - How To](docs/new-data-source-how-to.md) |
| 128 | +See the [Wiki](https://github.com/Farfetch/rules-framework/wiki) for full documentation, short examples and other information. |
85 | 129 |
|
86 | 130 | ## Contributing |
87 | 131 |
|
|
0 commit comments