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.
- The enableOrchestrator is set to true
Time-to-Live (TTL) in the Entity Service allows developers to automatically manage the deletion or removal of entity instances by specifying a time duration after which they should be considered expired and eligible for removal. This feature helps optimize storage utilization and ensures that outdated or irrelevant entity instances are efficiently removed from the system.
For entities with a state machine, follow these guidelines to configure TTL:
- Every entity must define a terminalTTL and terminalStates in the Entity State Machine Config.
- The TTL will be set on the entity when it transitions to one of the terminal state(s) as per the configuration.
- The TTL will be unset from the entity when it transitions away from the terminal state(s) as per the configuration.
Example:
In this example, when an entity transitions to the "inactive" state, which is defined as a terminal state, the TTL of "30d" (30 days) will be set. If the entity transitions away from the "inactive" state, the TTL will be unset.
For entities without a state machine, use the following configuration to apply TTL:
- Implement a new attribute named ttlOnInactive with a default value of false.
- If terminalTTL is not provided in the request body and ttlOnInactive is set to true, the terminalTTL will automatically be set to "90d" (90 days).
- Once ttlOnInactive is set to true, it cannot be reverted to false.
- If ttlOnInactive is false and terminalTTL is set, then in every operation of entity instance creation, the terminalTTL will be updated irrespective of whether the instance's isActive is true or false.
Example:
In this example, the ttlOnInactive attribute is set to true, and the terminalTTL is explicitly set to "60d" (60 days). If terminalTTL was not provided, it would default to "90d" (90 days) since ttlOnInactive is true.
- TTL records can take up to 48 hours to expire.
- The maximum allowed value for terminalTTL is 90 days. Setting a value greater than 90 days will result in an error.
- For entities with a state machine, at least one valid transition to a terminal state must be defined. Failure to do so will result in an error while configuring the state machine.
By configuring TTL for your entities, you can effectively manage the lifecycle of entity instances, optimize storage utilization, and ensure that outdated or irrelevant data is automatically removed.