> For the complete documentation index, see [llms.txt](https://docs.rulecube.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rulecube.com/v2.5/tutorial/using-entities.md).
# 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:
```json
{
"LoanApplicant": {
"Name": "Jane Foo",
"DateOfBirth": "1968-03-10",
"YearlyIncome": 95000
}
}
```
And the output object like:
```json
{
"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.
{% hint style="info" %}
To distinguish rules at the entity and ruleset level, Rulecube speaks of **entity rules** and **global rules**.
{% endhint %}
## 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)
```json
{
"LoanApplicant": {
"Name": "Jane Foo",
"DateOfBirth": "1968-03-10",
"YearlyIncome": 95000
}
}
```
1. Create a ruleset named `Loan application`.
2. Copy the entirety of the JSON object in the code block above.
3. Open the ruleset
4. Press Ctrl+V or Command+V on your keyboard to paste it
5. This will display a dialog, pick the first option ("As input properties")
6. 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.
1. 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.
2. Create a new input in the ruleset named LoanApplicant and set its **Type** to `LoanApplicationType`
3. Select the LoanApplicantType entity again and click **Add property**.\
↳ The **Input/Property** page opens.
4. In The **Name** field, enter `Name`. And in the **Type** list, select `string`.
5. 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
1. Select the `LoanApplicantType` entity and click **Add calculated property**.
2. In The **Name** field, enter `Age`. And in the **Type** list, select `number`.
3. Now, define the rule for calculating the `Age` property by entering the following **Expression**:
```javascript
AGE(DateOfBirth)
```
4. Next, create a calculated property named `MaximumLoanAmount` with Type=`number`. And sets its **Expression** to this code:
```javascript
if (Age < 18) return 0;
if (Age >= 18 && Age <= 50) return YearlyIncome / 2;
if (Age > 50) return YearlyIncome / 3;
```
5. Create a final calculated property named `NameUpper` with the following **Expression**:
```javascript
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
1. Select the input LoanApplicant.
2. 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
1. Click **Try it out**.\
↳ The **Sandbox** page opens, set the **Input** object to this:
```json
{
"LoanApplicant": {
"Name": "Jane Foo",
"DateOfBirth": "1973-03-10",
"YearlyIncome": 95000
}
}
```
2. Enter values for `Name`, `DateOfBirth`, and `YearlyIncome`.
3. 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:
```json
{
"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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.rulecube.com/v2.5/tutorial/using-entities.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.