Using Entities

Introduction

So far, you've worked with separate input and rules. But Rulecube has Entities into which data and rules acting on that data can be integrated. Using entities improves the manageability of your rulesets and is the most natural/logical way to implement a business rule in a ruleset.

By the end of this tutorial, you'll know:

What entities are.
How to apply entities in Rulecube.

Some background on entities

Let's look at an example to illustrate the working and power of entities. By the way, implementing this example is your target for this tutorial. Assume you want to implement a ruleset that calculates the maximum loan amount based on the applicant's yearly income and age.

You could create a ruleset with income and age as input, an age-based reduction rate as constant, and a rule that calculates the maximum loan based on income and possible reduction rate. Nothing wrong with that, but you could do better by integrating this into an entity where input and rules become so-called properties of the entity.

Properties come in two types:

Regular properties that correspond to input. Rulecube calls these properties.
Calculated properties that correspond to rules.

With this in mind, let's call the entity, LoanApplicant. Next, LoanApplicant gets these properties:

Name
DateOfBirth
YearlyIncome

And these calculated properties:

Age
MaximumLoanAmount

Now, data and its rules are encapsulated into a single entity, which adheres to the principals of object-oriented programming. All you have to do then is provide the ruleset with input for the entity, such as a JSON object with the input properties filled, and the entity determines the calculated properties and returns these as ruleset output.

The input object looks something like this:

{
  "LoanApplicant": {
    "Name": "Jane Foo",
    "DateOfBirth": "1968-03-10",
    "YearlyIncome": 95000
  }
}

And the output object like:

{
  "LoanApplicant": {
    "Name": "Jane Foo",
    "DateOfBirth": "1968-03-10",
    "YearlyIncome": 95000,
    "Age": 55,
    "MaximumLoanAmount": 38000
  }
}

Note that Rulecube adds the calculated properties to the input object and returns that as the result and that all properties of a loan applicant are logically combined into one object/entity.

To distinguish rules at the entity and ruleset level, Rulecube speaks of entity rules and global rules.

Apply entities in your ruleset

Okay, so much for the background on entities. Now, it's time to apply them in Rulecube.

Task: Create input and entity

Note: If this step doesn't work for you, skip to the next task (The manual way)

{
  "LoanApplicant": {
    "Name": "Jane Foo",
    "DateOfBirth": "1968-03-10",
    "YearlyIncome": 95000
  }
}

Create a ruleset named Loan application.
Copy the entirety of the JSON object in the code block above.
Open the ruleset
Press Ctrl+V or Command+V on your keyboard to paste it
This will display a dialog, pick the first option ("As input properties")
After this, you will have a new input named LoanApplicant and an entity named LoanApplicantType with 3 properties: Name, DateOfBirth, YearlyIncome. Additionally, the Type of the LoanApplication input should be LoanApplicantType.

Task: Create the base entity (The manual way)

If the automatic way did not work, you can create the entity manually this way. Otherwise, skip to the next Task.

Create an entity named LoanApplicantType. This entity represents a loan applicant, and the Type suffix distinguishes this entity from the input that will be based on the entity. This is needed because Rulecube doesn't allow using the same name for different components.
Create a new input in the ruleset named LoanApplicant and set its Type to LoanApplicationType
Select the LoanApplicantType entity again and click Add property. ↳ The Input/Property page opens.
In The Name field, enter Name. And in the Type list, select string.
Now, select the LoanApplicantType entity again, and add properties for DateOfBirth (Type=date) and YearlyIncome (Type=number).

The data part of the entity is ready now. Next, you're going to define the entity rules as calculated properties.

Task: Add entity rules as calculated properties

Select the LoanApplicantType entity and click Add calculated property.
In The Name field, enter Age. And in the Type list, select number.
Now, define the rule for calculating the Age property by entering the following Expression:
```
AGE(DateOfBirth)
```
Next, create a calculated property named MaximumLoanAmount with Type=number. And sets its Expression to this code:

if (Age < 18) return 0;
if (Age >= 18 && Age <= 50) return YearlyIncome / 2;
if (Age > 50) return YearlyIncome / 3;

Create a final calculated property named NameUpper with the following Expression:
```
Name.toUpperCase()
```

The entity is completed now. To apply it, you need to create an input that's based on the entity.

Task: Add LoanApplicant input to the output

Select the input LoanApplicant.
Enable the Output checkbox. ↳ This makes the input object also available as output (including the calculated properties) of your ruleset.

You have now finished the ruleset and are ready to try it out.

Task: Try out the entity ruleset

Click Try it out. ↳ The Sandbox page opens, set the Input object to this:

{
  "LoanApplicant": {
    "Name": "Jane Foo",
    "DateOfBirth": "1973-03-10",
    "YearlyIncome": 95000
  }
}

Enter values for Name, DateOfBirth, and YearlyIncome.
And click Execute. ↳ The content of the LoanApplicant object in the Result section depends on the values you entered in the input object (and the current date), but the structure should be like this:
```
{
  "Name": "Jane Foo",
  "DateOfBirth": "1973-03-10T00:00:00.000Z",
  "YearlyIncome": 95000,
  "Age": 50,
  "MaximumLoanAmount": 47500,
  "NameUpper": "JANE FOO"
}
```

Age and MaximumLoanAmount are both calculated now and logically tied to the LoanApplicant object.

Recap

You've taken another big step because you now know how to integrate data and rules into entities to implement business rules in Rulecube optimally.

What's next?

There is one more step for you in these tutorials: using your ruleset from within your software, such as a web application.

PreviousUsing Lookup Tables NextHow-to Guides