Manage Entity Types
In this developer guide, you will learn about creating Entity Types in the Entity Service. An Entity is an object or a concept, such as a vehicle or a box, for which data is stored and operations are performed.
An Entity Category represents the type of object or concept for storing and manipulating data. It provides a high-level classification for entities. For example, in the context of a Vehicle entity, four-wheeler or two-wheeler can be considered entity categories.
An Entity Sub-category is a further subdivision of an Entity Category. It allows for a more granular classification of entities within a specific category. Continuing with the Vehicle entity example, if a four-wheeler is an entity category, then a truck or car can be considered an entity sub-category.
To create a new Entity Type, call the CreateEntityType endpoint and provide the entity type parameters. See the following request below:
In this example:
- The Entity Type has a plural name "vehicles" and a singular name "vehicle". Entities are identified by their pluralName which must be unique per customer and app.
- It has aliases for both plural and singular names.
- It belongs to two categories: "FourWheeler" and "TwoWheeler".
- “FourWeeler” has subcategories of “Car” and “Truck, and “TwoWheeler” has subcategories of “Motorcycle” and “Scooter”
- It has two attributes: "model” and "color".
- "model" is a required attribute.
- "color" is an optional attribute with predefined allowed values.
- It has a core attribute "uniqueCode" with an alias "UCode".
- It specifies a callback URL to notify the outcome of the request.
- State machine is enabled
- It has three events: "created", "updated", and "deleted".
- It has an entity code "1234".
- The terminal TTL is set to 90 days.
Time-to-live (TTL) in the Entity Service allows developers to automatically manage deletion or removal of the entity instance by specifying a time duration after which they should be considered expired and eligible for removal. This feature helps optimize storage utilization, and ensure that outdated or irrelevant entity instances are efficiently removed from the system.
Setting the terminalTTL for an entity type is required. Set the terminalTTL field in the entity type request. The terminalTTL specifies the time duration, in days, after which an entity instance should be considered expired.
Here’s an example of setting the terminalTTL in the entity type request for 90 days..
Callout: TTL records can take up to 48 hours to expire.
When working with TTL, keep the following validations and constraints in mind:
- No Direct TTL Manipulation: TTL cannot be configured or set for an entity instance. It is derived from the TTL set of the Entity type from which the instance is created. manipulated on individual entity instances. It is automatically set based on the terminalTTL defined in the Entity Type.
- TTL Unit: The terminalTTL value must be specified in days. Other time units, such as hours or minutes, are not supported.
- Maximum TTL Value: The maximum allowed value for terminalTTL is 90 days. Setting a value greater than 90 days will result in an error.
- Terminal State Transition: Developers must define at least one valid transition to a terminal state for entities with a state machine. Failure to do so will result in an error while configuring the state machine. This ensures that entities can reach a terminal state and become eligible for expiration based on the TTL..
- When an entity instance is created, the TTL countdown begins based on the terminalTTL defined in the Entity Type.
- Only after an entity instance transitions to a terminal state, the TTL countdown starts from that point for entities with a state machine.
- Once the TTL is reached, the entity instance will be automatically deleted from the system.
- When an entity instance is updated, the TTL is recalculated using the following formula: TTL = current timestamp + terminal TTL. In this formula, the current timestamp represents the time at which the update operation is performed, and the terminal TTL is the value specified in the Entity Type configuration.