Table of contents

Introduction

Entity schemas define the structure, validation rules, and identifiable information of data. By default, all data flowing through your integrations are assigned to the default entity type. In this case, no structure, validation, or identifiable fields are present. Your Alumio environment will come with a set of standard entity schemas which offer pre-set structures and validation while also allowing you to create your own.


Entity schemas can be created and maintained by navigating to Settings -> Entity schemas.


Creating and maintaining entity schemas

Possible configuration fields:

  • Name -  A name describing the type of entity, i.e. ERP Product
  • Identifier - A unique identifier for this entity type (this field is automatically generated based on the name).
  • Description - Detailed description for the entity type.
  • Disabled - A flag that indicates whether the entity type is disabled. Disabled entity types disable any integration where this entity type is being used.
  • Schema - The schema defining the structure of the data as well as the applicable validation rules.
  • Identifier path - The fields which make up the entity identifier. This is reflected within the tasks and storage.
  • Link - The link in which the documentation of the schema can be found.


Automatically validate incoming data

Within Alumio you can set up a JSON schema (full documentation available here) to automate the validation of incoming data. Entity types allow you to set up a predefined schema that specifies the required structure of the data as well as data types and other validation rules such as the minimum length, the maximum value, or legitimate values. 


On the example image above, the following schema has been defined:

{
"type": "object",
"properties": {
"sku": {
"type": "string"
},
"price": {
"type": "integer",
"minimum": 1
},
"enabled": {
"type": "boolean",
"enum": [true, false]
}
},
"required": ["sku", "price", "enabled"]
}

To understand this schema we have to take a closer look at the contents of the JSON. 

  • type - On the root level, the type attribute is defined with a value of objectThis indicates that the incoming data for this entity type should be an object. 
  • properties - On the same level as the type attribute, the properties attribute is defined. The properties indicate the allowed attributes on the incoming data object.
    • sku - The SKU property indicates that the data within the SKU property should be of the string type.
    • price - The price property indicates that the data within the price property should be of the integer type. It should also have a minimum value of 1.
    • enabled - The enabled property indicates that the data within the enabled property should be of the boolean type. It should be either true or false. Any other value will not be accepted.
  • required - The required attributes indicate which properties must be present on the incoming data.


Once the schema has been defined it is easy to enable automatic data validations. It requires you to configure an entity transformer in two steps:

  1. Assign the correct entity type to the data using the Set the entity type transformer.
  2. Instruct Alumio to validate the data for the entity type using the Validates the entity type transformer.


Depending on the validity of your data, it may be either:

  • passing through this transformer (matches schema)
  • filtered by this transformer (does not match schema)


This concludes the article and should give you all the information that you need in order to make correct use of entity schemas within your integrations.

Video guide