Entities

📖In Activator, an Entity represents a structured collection of information, where each record (or instance of the Entity) corresponds to a row in a table. It is comparable to a table in a relational database. The columns of the entity are defined by the properties of the Entity, which are based on Data Types. Entities are used to organize and manage data, making it accessible and manipulable within the system.

How To Create An Entity

In Activator Admin, Entities are located within the menu container, among the items listed under ⚙️Entities. As shown at (1) on the image below.

✋NB:

Make sure you are in the Entities main module.

After initiating the creation of the Entity, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields. 

The Meta Data field gathers and provides additional information for the component. Regarding the data present in this field, we will mainly focus on the ui property further down in the Entity UI section. For more information on the other properties contained in this field, please refer to Meta Data for the complete list of additional information related to this component.

Note✍️ that this is where you will be prompted to complete various fields for the creation of an Entity. These fields will be used to define the attributes and their specific properties for the Entity.

{
    "implements": [
        "sys.datatypes.sysEntity"
    ],
    "baseEntity": "",
    "resourceName": "",
    "nameResKey": "",
    "descResKey": "",
    "title": "NewEntity",
    "description": "NewEntity",
    "constraints": [],
    "operations": [],
    "documentDirectories": [],
    "events": [
        {
            "name": "OnBeforeRecordCreated",
            "arguments": [
                {
                    "name": "Model",
                    "dataType": "string",
                    "description": "The new record's model (in JSON format)."
                }
            ]
        },
        {
            "name": "OnRecordCreated",
            "arguments": [
                {
                    "name": "RecordId",
                    "dataType": "guid",
                    "description": "The identifier of the entity record"
                }
            ]
        },
        {
            "name": "OnBeforeRecordUpdated",
            "arguments": [
                {
                    "name": "RecordId",
                    "dataType": "guid",
                    "description": "The identifier of the entity record"
                },
                {
                    "name": "Path",
                    "dataType": "string",
                    "description": "The path being updated."
                },
                {
                    "name": "AttributeValues",
                    "dataType": "string",
                    "description": "The list of name/value pairs (in JSON format)."
                }
            ]
        },
        {
            "name": "OnRecordUpdated",
            "arguments": [
                {
                    "name": "RecordId",
                    "dataType": "guid",
                    "description": "The identifier of the entity record"
                },
                {
                    "name": "Path",
                    "dataType": "string",
                    "description": "The path updated."
                },
                {
                    "name": "AttributeValues",
                    "dataType": "string",
                    "description": "The list of name/value pairs (in JSON format)."
                }
            ]
        }
    ],
    "eventHandlers": []
}

JSON Description

Let's see how each property contributes to the definition and configuration of the Entity in the system.

[
    {
        "name": "OnBeforeRecordCreated",
        "arguments": [
            {
                "name": "Model",
                "dataType": "string",
                "description": "The new record's model (in JSON format)."
            }
        ]
    },
    {
        "name": "OnRecordCreated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            }
        ]
    },
    {
        "name": "OnBeforeRecordUpdated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            },
            {
                "name": "Path",
                "dataType": "string",
                "description": "The path being updated."
            },
            {
                "name": "AttributeValues",
                "dataType": "string",
                "description": "The list of name/value pairs (in JSON format)."
            }
        ]
    },
    {
        "name": "OnRecordUpdated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            },
            {
                "name": "Path",
                "dataType": "string",
                "description": "The path updated."
            },
            {
                "name": "AttributeValues",
                "dataType": "string",
                "description": "The list of name/value pairs (in JSON format)."
            }
        ]
    }
]

"eventHandlers": [
    {
        "eventName": "OnRecordCreated",
        "handler": "activatord.eventhandlers.newEventHandler1"
    }
]

Property constraints

It defines the rules and limitations applied to the fields of the Data Types implemented by the Entity. These constraints are essential for maintaining data integrity and ensuring that the values stored in the fields meet specific conditions. By setting these constraints, you ensure that the data entered into the system is valid, consistent, and compliant with the required standards, helping to prevent errors and maintain data quality.

Add A Constraint

 The definition of a constraint is done using the following format:

{
    "name": "FK_Order_Company",
    "description": "The company recordId",
    "type": "",
    "isActive": "true",
    "definition": { /* Contains the actual definition of the constraint. It varies depending on the type. */}
}

List Of constraint types

1. ForeignKey

   The ForeignKey constraint checks the values of the field it is applied to, ensuring that each value is unique and corresponds to a primary key in another Entity, thus ensuring that the data is correctly linked between Entities.

   Here's an example configuration:

   "constraints": [
       {
           "name": "FK_Order_Company",
           "description": "The company recordId",
           "type": "ForeignKey",
           "isActive": "true",
           "definition": {
               "route": "",
               "attribute": "recordId",
               "reference": "activatord.accounts.company"
           }
       },
       {
           "name": "FK_Order_Products",
           "description": "The order Products",
           "type": "ForeignKey",
           "isActive": "true",
           "definition": {
               "route": "products",
               "attribute": "recordId",
               "reference": "activatord.entities.catalog"
           }
       }
   ]

Property Description🎨 :

2. Unique

   The Unique constraint ensures that the values of a particular field are unique within all the records of the Entity.

   Here's an example of a configuration for a uniqueness constraint:

   "constraints": [
       {
           "name": "Uq_EmailAddress",
           "description": "The company recordId",
           "type": "Unique",
           "isActive": "true",
           "definition": {
               "route": "",
               "attribute": "emailAddress"
           }
       }
   ]

Property Description🎨 :

Property operations

⌛The operations property allows you to define the specific processing and modifications that must be applied to entity records, while ensuring that each action is properly logged for subsequent tracking.

Configuration example for the operations property :

"operations": [
    {
        "name": "UpdateResidenceLocation",
        "title": "Update the member residence location",
        "description": "Used to update the member residence location",
        "handler": "activatord.entityoperationhandlers.updateMemberResidence",
        "arguments": [
            {
                "name": "memberRecordId",
                "title": "The member record id",
                "description": "The member record identification",
                "dataType": "guid"
            },
            {
                "name": "locationModel",
                "title": "The location JSON Model",
                "description": "The new residence location JSON Model",
                "dataType": "activatord.datatypes.localization"
            }
        ]
    }
]

How To Perform An Operation

On Activator, the developer can execute an operation of an Entity by calling the provided API. You can call this API to perform various operations on Entity records. Here are the details for using this API:

{
    "recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "arguments": [
        {
            "name": "string",
            "value": "string"
        }
    ]
}

This API can be called from various forms or interfaces to execute specific operations on Entity records. This allows for dynamic data processing and enables the execution of complex actions directly from the user interface or other system integration points.
 

How To Display An Operation

On Activator the operation data is retrieved and presented to the user to ensure transparency and traceability of the actions performed.
There are two main ways to display an operation:

Via the direct API

The API mentioned below can be used to retrieve operation data directly from the server. The retrieved information can then be displayed to the user via a user interface.

By directly calling the operation driver associated with the Entity

By directly calling the operation driver associated with the Entity
This method allows for integrating the operation UI directly linked to the Entity.
To create an operation driver, you need to access the items listed under Entities and click on (1) as illustrated in the image below👇:

After initiating the creation of the Operation Driver, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields. 

⏳After filling in the name and description fields, let's focus on the Definition and Meta Data fields. 

The Meta Data field gathers and provides additional information for the component, please refer to  Meta Data for the complete list of additional information related to this component.

As for the Definition field, this is where the default code is defined to help you create an operation driver. Here is a detailed description of the code👇:

$activator.ui.jsmodules.define(function () {
    // Called to initialize the driver
    this.initialize = function (context) {
        return new Promise((resolve, reject) => {
            resolve();
        });
    };
    // Render the content
    this.render = function (context) {
        return new Promise((resolve, reject) => {
            resolve();
        });
    };
});

The code uses the define function from $activator.ui.jsmodules to define a new JavaScript module. This module corresponds to an operation driver that will be used to manage and display operations related to an Entity.

Property documentDirectories

The documentDirectories property in an Entity allows for the creation of an organized folder structure to store and manage documents associated with that Entity. This feature is essential for structuring folders  hierarchically, which simplifies the access, management, and display of documents in  the system.

Here is an example of the documentDirectories property and an explanation of its structure:

"documentDirectories": [
    {
        "name": "folder1",
        "title": "Folder 1",
        "description": "Folder 1",
        "nameResKey": "",
        "descResKey": "",
        "subdirectories": []
    },
    {
        "name": "folder2",
        "title": "Folder 2",
        "description": "Folder 2",
        "nameResKey": "",
        "descResKey": "",
        "subdirectories": [
            {
                "name": "subFolder1",
                "title": "Sub Folder 1",
                "description": "Sub Folder 1",
                "nameResKey": "",
                "descResKey": "",
                "subdirectories": []
            },
            {
                "name": "subFolder2",
                "title": "Sub Folder 2",
                "description": "Sub Folder 2",
                "nameResKey": "",
                "descResKey": "",
                "subdirectories": []
            }
        ]
    }
]

Each folder in the documentDirectories property is represented by an object containing information such as:

These folders and subfolders defined in the documentDirectories property can be viewable in Activator Client via the document module.

Property events

This property contains the list of events that this entity can listen to.

✋NOTE:

This field is for documentation purposes only. Its role is to inform the developer about the possible events to listen for, as well as the different arguments/parameters they need to consider.

[
    {
        "name": "OnBeforeRecordCreated",
        "arguments": [
            {
                "name": "Model",
                "dataType": "string",
                "description": "The new record's model (in JSON format)."
            }
        ]
    },
    {
        "name": "OnRecordCreated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            }
        ]
    },
    {
        "name": "OnBeforeRecordUpdated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            },
            {
                "name": "Path",
                "dataType": "string",
                "description": "The path being updated."
            },
            {
                "name": "AttributeValues",
                "dataType": "string",
                "description": "The list of name/value pairs (in JSON format)."
            }
        ]
    },
    {
        "name": "OnRecordUpdated",
        "arguments": [
            {
                "name": "RecordId",
                "dataType": "guid",
                "description": "The identifier of the entity record"
            },
            {
                "name": "Path",
                "dataType": "string",
                "description": "The path updated."
            },
            {
                "name": "AttributeValues",
                "dataType": "string",
                "description": "The list of name/value pairs (in JSON format)."
            }
        ]
    }
]

Description📺:

List Of Native Events For An Entity

Here is the list of native events you can define for an Entity, along with their details:

Event Configuration

Configuring an event for an entity simply involves defining which event handler will be responsible for processing the said event. These event handlers are functions or scripts that respond to the events defined in events.

Here's an example configuration:

"eventHandlers": [
    {
        "eventName": "OnRecordCreated",
        "handler": "activatord.eventhandlers.newEventHandler1"
    }
]

Entity UI

The ui property can be found in the JSON content of the Meta Data field you have at creation time, or in the content of the Additional Info tab.

This property is defined by:

{
    "driver": "",
    "layout": "",
    "icon": ""
}

it defines:

✋NB: In Activator, the layout and driver are not used together and do not need to be defined simultaneously. However, if both are defined, the layout takes precedence over the driver for rendering the record.

The following properties are defined as Meta Data.

How To Create Entity Driver

To create an entity  driver, you need to access the items listed under Entities and click on the highlighted item as illustrated in the image below👇: 

Being a driver-type component, the Entity Driver has all the methods and functionalities available in this component. To learn more about this component, please refer to the Driver.

How To Create Entity Layout

To create an entity  Layout, you need to access the items listed under Entities and click on the highlighted item as illustrated in the image below👇: 

Being a Layout-type component, the Entity Layout has all the properties and functionalities available in this component. To learn more about this component, please refer to the Layout.

Entity APIs

These APIs facilitate entity management by providing endpoints to obtain information about their structure, perform actions on records, and view associated events. Through these interfaces, developers can seamlessly integrate and manipulate entities, ensuring efficient interaction with the data.

Get The Model Of An Entity

This access point retrieves the complete model of the specified entity. This will help you understand the data model to send for creating a new record.

API Details

Get The Type Of An Entity

This API provides information on the type of every field of the datatype impleted by the entity.

API Details

Create Records

• Push a single records

  This operation allows you to create a single record within a specified entity. 

{
    "model": {}
}

• Push many records

  This operation enables you to create multiple records for a specified entity in a single request. It is useful for bulk record creation.

{
    "models": [
        {}
    ]
}

Updates

• Update Entity Record

  Use this endpoint to update a specific record within an entity. 

{
    "path": "string",
    "attributes": [
        {
            "name": "string",
            "value": "string"
        }
    ]
}

• Update Language Resource

  This endpoint updates language resources associated with a specific record. For more details on how to date translations, refer to the Database Translation.

{
    "route": "string",
    "resources": [
        {
            "name": "string",
            "languages": [
                {
                    "name": "string",
                    "value": "string"
                }
            ]
        }
    ]
}

• Update Many Records

  This operation allows you to update multiple records for a specified entity in one request, useful for bulk updates.

{
    "records": [
        {
            "recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "path": "string",
            "attributes": [
                {
                    "name": "string",
                    "value": "string"
                }
            ]
        }
    ]
}

Children

• Create

  This endpoint enables you to create a child record for a specified parent record within an entity. 

{
    "route": "string",
    "model": "string"
}

• Update

{
    "route": "string",
    "attributes": [
        {
            "name": "string",
            "value": "string"
        }
    ]
}

• Delete

{
    "route": "string"
}

Activate Entity

This operation activates an entity record, making it available for use.

Deactivate Entity

Deactivates an entity record, making it inactive and unavailable.

Conclusion

In conclusion, the Entity component in Activator is a robust system for organizing, managing, and manipulating structured data. Entities, comparable to tables in a relational database, form the foundational elements of data storage and offer extensive customization through properties, operations, events, and document directories. The ability to define operations ensures traceability of actions on the data, while events enable dynamic responses to changes occurring within the system. Additionally, the use of APIs allows users to create sophisticated data management solutions tailored to their needs.

With a good understanding of these fundamental elements, you can now explore more specialized entities such as task, business processes, and others, which provide advanced capabilities for managing complex workflows and automating processes within the Activator environment.