Persisted Entities

Introduction

Persisted Entities are Entities that can be stored in a database.

These entities have a defined lifecycle that typically includes creation, updates, and eventual deletion. Persisted Entities are crucial in applications where permanent data storage is necessary, enabling data retrieval and management across ruleset executions.

Enabling persistency

Before you can use Persisted Entities, the Ruleset you're working in must be a Library and must have persistency enabled.

1. Open a new Ruleset and go to the Ruleset's Version Settings in the left menu

2. Check the 'Library' box

3. Check the 'Allow persistency' box

This will not automatically make any Entity a persisted one.

1. Create a new Entity

2. Check the 'Allow persistency' box

3. Save the Ruleset

This will change the Entity into a Persisted Entity.

How to use

There are a few ways to store, retrieve, update and delete Persisted Entities:

• Programmatically

  • Within a Ruleset

  • Through the API (api/persisted-entity)

• Form data table (See Create a Data table)

In this guide we will look at how to use Persisted Entities within a Ruleset.

Saving an Entity

Let's start with creating a simple 'Person' entity.

Creating the Person Entity

1. Create a new Ruleset

   1. Check the 'Library' and 'Allow persistency' boxes under Version Settings

2. Create a new Entity named 'Person'

3. Add a 'FirstName' property of type string

4. Add a 'LastName' property of type string

5. Add a 'Birthdate' property of type date

6. Now, add a new Calculated Property named 'Age' with the following expression: AGE(Birthdate)

7. Finally, check the 'Allow persistency' box and save the Ruleset

Saving an instance of the Person entity

1. Create a Rule named 'Test' with the following expression:

let person1 = new Person({ FirstName: 'John', LastName: 'Doe', Birthdate: '1980-01-01' })
person1.save()
return Person.getAll().items

Let's analyze what this code does.

The first line creates a new instance of the Person Entity. This only creates an Entity as usual and does not yet save it to the database.

The second line actually stores the Person entity in the database.

The final line returns all Person entities currently in the database.

If we were to save the Ruleset and open it in the sandbox ("Try it out"), each time we will execute the Ruleset, it will create a new Person and the 'Test' rule's output will keep growing in size.

Before we do that, let's make it so the user can enter Person's name and birthdate via the Ruleset's input.

1. Create an Input named 'person1' of type 'Person'

2. Change the expression of the 'Test' Rule to:

person1.save()
return Person.getAll().items

1. Save the Ruleset and click on "Try it out" at the top.

2. Enter some data into the input on the left

3. Execute the Ruleset

If you repeat steps 4-5, you will will notice how the output of the Test rule will increase until a size of 20 is reached.

This is because the .getAll() method is paginated and will only return 20 items each time it is called. To get to the other items we can either:

• Use a different page number (page 1, page 2, etc.)

• Use a different page size (return more items per page)

See the Static Methods section for more details on how to use getAll().

Also note how the Age property is properly calculated for each entry in Test.

Language reference

These are the methods available when using Persisted Entities programmatically. These are divided into: Instance Methods and Static Methods.

Instance Methods

Instance methods are called on an instance of a Persisted Entity. These methods allow you to interact with the data and perform actions specific to a particular instance, such as saving changes, deleting the entity, or retrieving specific attributes.

Method	Description
save()	Saves the instances. Can be used on new instances or to update an existing instance. For instance, calling it twice in a row on a new instance will first create a new entry in the database, followed by updating it.
delete()	Deletes the instance from the database. Only works on entities that already exist in the database.
setId(guid)	Sets the ID of the entity. Only useful in certain circumstances. Saving or fetching entities will automatically set the ID.
getId()	Returns the ID of the entity.

Static Methods

Static methods are called on the Entity class itself, not on a specific instance. These methods are useful for actions that do not pertain to a particular entity instance, such as creating a new entity, listing all entities, finding entities by certain criteria, or deleting multiple entities.

Method	Description
getAll(meta, entityFilter) meta: { pageIndex: number, pageSize: number, sortBy: string } entityFilter: { type: 'Equals' | 'And' | 'Or', field: string, value: any }	Gets all entity instances or filtered. To get the first page of all instances: Person.getAll() To get up to 9999 instances at once: Person.getAll({ pageSize: 9999 }) To get everybody named 'John': Person.getAll({}, { type: 'Equals', field: 'FirstName', value: 'John' })
get(id)	Gets a single instance by ID
save(entities)	Saves an array of entities and returns the saved instances.
delete(meta, entityFilter) meta: { createdFrom: date, createdTo: date, modifiedFrom: date, modifiedTo: date } entityFilter: { type: 'Equals' | 'And' | 'Or', field: string, value: any }	Deletes one or more instances. To delete all instances: Person.delete() To delete all instances created after a certain date: Person.delete({ createdFrom: '2025-01-01' }) To delete everybody named 'Doe': Person.delete({}, { type: 'Equals', field: 'LastName', value: 'Doe' })