Entity

introduction an entity is an object or a concept for which data is stored, and operations are performed for example, vehicle, box, user, etc key components 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 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 features supported 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 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 state machine service 📘 entity service new attribute addition 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 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 entity docid\ aybe70hu6gdjh5mpverll create an entity docid\ aybe70hu6gdjh5mpverll based on an entity docid\ aybe70hu6gdjh5mpverll the entity docid\ aybe70hu6gdjh5mpverll 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 a mileage 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 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 member description validation data type name template name pattern ^\[a z a z0 9]\[a za z0 9 ]{0,63}$ string subcategory template sub category pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string attributes > name attribute name minlength 1 maxlength 32 pattern ^\[a za z]{1,32}$ string attributes > description attribute description minlength 0 maxlength 256 string attributes > datatype data type valid values string, number, boolean, object, array, address, phone, money string attributes > indexed defines whether to make this attribute indexed or not so that filtering can be provided based on this attribute default false boolean attributes > defaultvalue provide the default value of the attribute the data type of the value should match the data type of the attribute defined number attributes > validation validation rules for a string or number value string attributes > required specifies whether the value is required or optional default false boolean callback url to notify the outcome of the request returns event data for success and failure events pattern https? \\/\\/(www\ )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string create entity template { "name" "sampletemplate", "subcategory" "car", "attributes" \[ { "name" "mileage", "description" "mileage of the car", "datatype" "number", "indexed"\ true, "defaultvalue" 50, "validation" { "required"\ false } } ], "callback" "https //examplecallbackurl com" } update entity template { "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 member description validation data type uniquecode unicode code for the entity instance minlength 1 maxlength 128 pattern ^\[a za z0 9]\[a za z0 9 ]{0,127} string name template name pattern ^\[a z a z0 9]\[a za z0 9 ]{0,63}$ string subcategory template sub category pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string attributes > name attribute name minlength 1 maxlength 32 pattern ^\[a za z]{1,32}$ string attributes > description attribute description minlength 0 maxlength 256 string attributes > datatype data type valid values string, number, boolean, object, array, address, phone, money string attributes > indexed defines whether to make this attribute indexed or not so that filtering can be provided based on this attribute default false boolean attributes > defaultvalue provide the default value of the attribute the data type of the value should match the data type of the attribute defined number attributes > validation validation rules for a string or number value string attributes > required specifies whether the value is required or optional default false boolean callback url to notify the outcome of the request pattern https? \\/\\/(www\ )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string create entity instance { "uniquecode" "n9tt9g0ab7fq", "name" "vehicle", "owner" "worldlogistics", "category" "four wheeler", "subcategory" "truck", "properties" { "color" "blue", "dataobject" { "time" 3 }, "seat" 5 }, "callback" "https //examplecallbackurl com" } update entity instance { "properties" { "color" "red" }, "callback" "https //examplecallbackurl com" } data models 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 entity docid\ aybe70hu6gdjh5mpverll 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 attribute type attribute name description base tenant id the id of the tenant to whose realm the entity belongs base entity id this is a system generated id, expected to be unique within a tenant base category category of an entity base sub category the sub category of an entity base template template based on which entity instance is created custom attributes 1 to n ( indexed ) custom attributes for an entity with indexing custom attributes 1 to n ( non indexed ) custom attributes for an entity without indexing 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 member description validation data type name > plural plural name of the entity type pattern ^\[a za z0 9]{1,16}$ minlength 1 maxlength 16 example vehicles string name > singular singular name of entity type pattern ^\[a za z0 9]{1,16}$ minlength 1 maxlength 16 example vehicle string category > name category name example vehicle pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string category > description category description string category > subcategory sub category pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string attribute > name attribute name minlength 1 maxlength 32 pattern ^\[a za z]{1,32}$ string attribute > description attribute description minlength 0 maxlength 256 string attribute > datatype the data type of the attribute valid values string, number, boolean, object, array, address, phone, money, geo point string attribute > indexed defines whether to make this attribute indexed or not so that filtering can be provided based on this attribute default false boolean isstatemachineenabled default false boolean events events minitems 1 maxitems 999 string entitycode entity code string create entity type { "name" { "plural" "entity", "singular" "entity1" }, "category" \[ { "name" "vehicle", "description" "description for the vehicle", "subcategory" \[ "car", "bus" ] } ], "attributes" \[ { "name" "attribute", "datatype" "string", "indexed" false, "validation" { "required" true } } ], "isstatemachineenabled" true, "events" \[ "e 022", "e 023", "e 024" ] } update entity type { "attributes" \[ { "name" "mileage", "description" "mileage of the vehicle", "datatype" "number", "indexed"\ true } ] } entity type as data type the entity type data type allows you to reference other entities as properties within an entity schema when creating or updating an entity type, you can include entity type as a custom attribute { "name" "\<attributename>", "description" "\<description>", "datatype" "entity type", "defaultvalue" "\<instanceid>", "indexed" true/false "validations" { "valueoneof" \[ "\<appid>##\<entitytypepluralname>" ], "required" \<true/false> } } 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) creating entities in a batch 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 attributes for batch request member description validation data type payload list of valid objects to perform create data in entities maxitems 1024 minitems 1 uniquecode unique code minlength 1 maxlength 128 string name name of the entity minlength 1 maxlength 64 string owner the owner of the entity should be a valid entity id minlength 1 maxlength 64 string category valid entity category example vehicle pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string subcategory valid entity sub category example car pattern ^\[a za z]\[a za z0 9, \\ ]{0,15}$ minlength 1 maxlength 16 string properties key value representation of all core attributes of the entity callback url to notify the outcome of the request pattern https? \\/\\/(www\ )?\[ a za z0 9@ % \\+ #=]{2,256}\\ \[a z]{2,4}\b(\[ a za z0 9@ % \\+ #?&//=] ) string 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 create batch request body { "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" } update batch request body { "payload" \[ { "properties" { "color" "black" } }, { "properties" { "color" "silver" } }, { "properties" { "color" "white" } }, { "properties" { "color" "blue" } }, { "properties" { "color" "red" } } ], "callback" "https //examplecallbackurl com" } 👍 entity batch processing entity batch processing container can be created and updated in batch using batch processing api here are the sample csv files for batch creation & updation of containers 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