Entity

Introduction to Entity Service

An Entity is an object or a concept for which data is stored, and operations are performed. For example, Vehicle, Box, User, etc.

Entity Category and Sub-category

Entity Category: The type of object or concept about which data is stored and manipulated. For example, four-wheeler or two-wheeler is a category of entity vehicle.

Entity Sub-category: The type of Entity Category for which data is stored and manipulated. For example, a truck or a car is an entity sub-category for the entity category four-wheeler whose entity is vehicle.

Entity Template

An Entity Template is created based on an entity category-sub-category pair. The attributes created in the entity template override the attributes created for the entity.

Entity Instance

An instance of an entity is created either by instantiating an entity or by instantiating an entity template.

🚧

NOTE

Lifecycle rules governing the state of an entity are not in the scope of this document and are covered separately in the State Machine Documentation.

What is the Entity Service and its features?

The Entity service exposes API endpoints that allow you to store the data and perform operations on the data for an Entity. It is responsible for managing the availability, latency, consistency, and replication of the data stored.

Features of Entity Service

Using the Entity Service you can:

• Create multiple entities per App. For example, for a ticketing system (App), entities could be users, tickets, vendors, etc.
• Define entities by creating Attributes.
• Expose CRUD APIs.
• Search or filter the stored data.
• Search or filter the changes in attributes and data.
• The batch creates or updates the data.
• Perform templatization of entities and creation of templates based on entity category and sub-category.
• Configure data warehouse capability.
• Configure life cycle management using the Sate Machine Service.

📘

Entity Service new attribute addition

Updates to existing Attributes and the addition of new Attributes take effect after the creation of a new Entity instance and are not backward compatible.

Entities per app

The create, read, and update endpoints are used to define the Entities per app. Note that, the app name is mandatory when defining an entity.

Entities are identified by their pluralName which must be unique per tenant and app. The Entity pluralName is created as a separate resource so that you can create separate Entity instances. Allowed owners should be an enum that contains the owning entity pluralNames (it is validated during entity creation). If empty, then no validation is performed.

Attributes per Entity

A Tenant can define Custom Attributes for an Entity. The service allows you to:

• Define the name and data type of the attribute.
• Provide optional default value of the attribute.
• Define validations on the attribute. The following validations are allowed:
  • Range- Defining min-max.
  • ValueOneOf- Homogenous enum (values of the enum should be of the same data type).
  • Required- Whether the attribute is required or not.

Attributes of an Entity

An Entity is defined by Base and Custom Attributes:

Base Attributes: These are the attributes pre-defined by the platform for the Entity. Some of these attributes are obligatory.
Custom Attributes: These are the attributes that the Tenant defines for the Entities, to enhance their usability.

*isActive, isDeleted, createdAt, createdBy, updatedAt, updatedBy, or any such database columns should be automatically created by the developers.

To create an Entity Type that has Custom Attributes, call the Create Entity Type endpoint.
To update an Entity Type, call the Update Entity Type endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating an Entity Type and a request body for updating an Entity Type:

{
    "name": {
        "plural": "abcdes",
        "singular": "abcss"
    },
    "category":[
        {
            "name":"catones",
            "description": "djdhjs",
            "subCategory":[
                "car",
                "bus"
            ]
        }
    ],
    "attributes": [
        {
            "name": "att",
            "dataType": "string",
            "indexed": false,
            "validation": {
                "required": true
            }
        }
    ],
    "isStateMachineEnabled": true,
    "events": [
        "E-022",
        "E-023",
        "E-024"
    ]
}

{
   "attributes":[
      {
         "name":"mileage",
         "description":"Mileage of the vehicle",
         "dataType":"number",
         "indexed":true
      }
   ]
}

Filter and Search endpoints

Filter and search GET endpoints are provided for retrieving entity instances based on various filters like match, multi-match, term, range, regex, exists, prefix, wildcard, etc. The results of the call are paginated. To configure the result set, use the following options: limit, offset, from(time), and to(time).

Changelog API

Changelog endpoints are provided for Entity attribute updates and Entity instance updates. The results of the call are paginated. To configure the result set, use the following options: limit, offset, from(time), and to(time).

Batch endpoints

Batch endpoints are provided to create and update Entities in batches. The Batch endpoints support two methods to supply the Entity data:

• JSON
• CSV file upload

To register a Batch Entity request, call the Create Batch Request endpoint.
To update a Batch Entity request, call the Update Batch Request. endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating a Batch Entity request and a request body for updating a Batch Entity request:

{
   "payload":[
      {
         "uniqueCode":"QK6A-JI6S-7ETR",
         "name":"car1",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"red"
         }
      },
      {
         "uniqueCode":"XNSS-HSJW-3NGU",
         "name":"car2",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"blue"
         }
      },
      {
         "uniqueCode":"NHLE-L6MI-4GE4",
         "name":"car3",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"black"
         }
      },
      {
         "uniqueCode":"6ETI-UIL2-9WAX",
         "name":"car4",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "cole":"silver"
         }
      },
      {
         "uniqueCode":"2E62-E3SR-33FI",
         "name":"car5",
         "owner":"worldlogistics",
         "category":"four-wheeler",
         "subCategory":"truck",
         "properties":{
            "color":"white"
         }
      }
   ],
   "callback":"https://examplecallbackurl.com"
}

{
   "payload":[
      {
         "properties":{
            "color":"black"
         }
      },
      {
         "properties":{
            "color":"silver"
         }
      },
      {
         "properties":{
            "color":"white"
         }
      },
      {
         "properties":{
            "color":"blue"
         }
      },
      {
         "properties":{
            "color":"red"
         }
      }
   ],
   "callback":"https://examplecallbackurl.com"
}

Templatization

You can create templates that you can use to simplify the creation of Entity instances.

The process to create a template:

• Define an Entity by creating the Base and Custom Attributes.
• Create an Entity template based on an Entity-category and an Entity sub-category.
• The Entity instance is created using the Entity Template. The Entity instance has the superset of all the attributes defined in the Entity template and Entity. If attributes with the same name exist in the Entity template and Entity definition, then the Attributes of the Entity template will override the attributes of the Entity.
• If the attributes of the Entity or the Attributes of the Entity template are updated, Entity instances created after the update is complete will have the updated values. Previously created Entity instances are not updated with new Attributes or Attribute updates.

Templatization Example

Let's understand how you can use Templatization in a real-world example:

• Create an Entity: We created an entity named vehicle with base and custom attributes. Suppose, vehicle has two custom attributes mileage and manufacturer with default values 15 and Toyota, respectively.
• Create Entity-category and Entity-subcategory: We defined Entity-category for the entity vehicle as four-wheeler and Entity-subcategory is categorized as car.
• Create a template based on the Entity category and the Entity subcategory: We create a template called vehicleTemplate1 for Entity-category four-wheeler and entity-subcategory car.
• Defining Attributes for the Entity Template vehicleTemplate1: We defined two custom Attributes mileage and manufacturer with default values 50 and Suzuki, respectively.
• Now, we have 3 cases for creating Entity instances:

Case 1: When the Entity instance is created using Entity.
For example, car123 is created using the entity vehicle. The values of mileage and manufacturer are provided during instance creation hence mileage: 35 and manufacturer: Volkswagen.

Case 2: When the Entity instance is created using Entity.
For example, car123 is created using the Entity vehicle. The values for custom Attributes mileage and manufacturer are not provided. In that case, the default values of 15 and Toyota are picked up while creating the instance.

Case 3: When the Entity instance is created using the Entity template vehicleTemplate1.
If the values for custom Attributes, mileage, and manufacturer, are provided during instance creation, those values are associated with the instance. However, if the values of mileage and manufacturer are not provided, the default values of vehicleTemplate1 Attributes are picked up overriding the entity values of mileage and manufacturer. In this case, the instance has amileage: 50 and manufacturer: Suzuki stored across the instance.

To create an Entity Template, call the Create Template endpoint.
To update an Entity Template, call the Update Template endpoint.

👍

Entity Batch Processing

Entity can be created and updated in batch using Batch Processing API.

Here are the sample CSV files for Batch Creation & Updation of Entity. Note: While uploading CSV file for Entity Batch Creation ownerID can be human readable name as well.

Request bodies are specified in JSON format. The following examples show a request body for creating an Entity Template and a request body for updating an Entity Template:

{
   "name":"vehicleTemplate1",
   "subCategory":"car",
   "attributes":[
      {
         "name":"mileage",
         "description":"Mileage of the car",
         "dataType":"number",
         "indexed":true,
         "defaultValue":50,
         "validation":{
            "required":false
         }
      }
   ],
   "callback":"https://examplecallbackurl.com"
}

{
   "attributes":[
      {
         "name":"manufacturingCompany",
         "description":"Manufacturing company of the car",
         "dataType":"string",
         "indexed":true,
         "defaultValue":"Toyota",
         "validation":{
            "required":false
         }
      }
   ],
   "callback":"https://examplecallbackurl.com"
}

To create an Entity Instance, call the Create Entity endpoint.
To update an Entity Instance, call the Update Entity endpoint.

Request bodies are specified in JSON format. The following examples show a request body for creating an Entity Instance and a request body for updating an Entity Instance:

{
   "uniqueCode":"N9TT9G0AB7FQ",
   "name":"Vehicle DWH",
   "owner":"worldlogistics",
   "category":"four-wheeler",
   "subCategory":"truck",
   "properties":{
      "color":"blue",
      "dataobject":{
         "time":3
      },
      "seat":5
   },
   "callback":"https://examplecallbackurl.com"
}

{
   "properties":{
      "color":"red"
   },
   "callback":"https://examplecallbackurl.com"
}

Lifecycle

The lifecycle for the Entities defined in the Entity service is managed separately using the State Machine Service. To use/not use the state machine service for lifecycle management is dependent on the Tenant’s business use case.

Data Warehouse

Storing the data in the data warehouse is Tenant configurable. By default, the data is only stored in the transactional database. When the data warehouse feature is enabled, the data becomes available in the data warehouse becomes available immediately. It is advisable to build reporting dashboards in the data warehouse.

The Tenant can configure a terminal TTL that governs the availability of data in the transactional database. If the value is not provided, the data is deleted from the transactional database after 30 days. If the data warehouse feature is enabled, then the data is available to query from the DWH after the deletion from the transactional database. If it is not enabled the data is permanently deleted.