Data Types

Using Data Types

📝Data Types in Activator play a central role in various aspects of development, including being used by entities, business processes and much more. They are used not only to validate data structure, but also to model arguments passed to stored functions, handlers and reports. Thanks to this versatility, Data Types ensure that data is consistent and compliant with requirements, facilitating seamless integration and efficient management of information across the entire system.

Create A Data Type

In Activator Admin, Data Type is located in the menu container, as shown in (1) in the image below.

✋NB: You can access it from the System component or Entities main module.

After initiating the creation of the Data Type, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields. 

The Meta Data field gathers and provides additional information for the component, please refer to  Meta Data for the complete list of additional information related to this component

As for the Definition field, let's take a closer look at its Json content in the next point.

JSON Definition Content

Note✍️ that this is where you'll be prompted to fill in various fields for the Data Type component. These fields will be used to define attributes and their properties.

{
    "attributes": [
        {
            "name": "attribute1",
            "required": "true",
            "dataType": "string"
        }
    ]
}

JSON Description

In the JSON definition, we have an attributes property, which is an array containing the various attributes defining the data structure. These attributes are essential for defining the precise structure of the data to be implemented.

✋NB: Attributes can be of several types and may contain several other properties👇.

List Of datatype Types 

When creating a Data Type, additional properties can be added depending on the datatype contained in each attribute, but there are also properties that are common, regardless of the value contained in the datatype. 
These common properties that can be added to each attribute are as follows👇:

{
    "name": "attribute1",
    "required": "true",
    "dataType": "string",
    "nameResKey": "string",
    "descResKey": "string",
    "description": "string",
    "defaultValue": "string",
    "validations": [
        "RequireValue",
        "AttributeName",
        "EmailAddress",
        "Integer",
        "Double",
        "Date",
        "Guid"
    ]
}

More details to better understand each of these properties in the table below👇.

[
    "RequireValue",
    "AttributeName",
    "EmailAddress",
    "Integer",
    "Double",
    "Date",
    "Guid"
]

✋NB: The AttributeName validation format and the dataType name must comply with the following rules:

• Must not start with a number

• Must not contain a special character

• Must not contain a hyphen

• Must be at least 2 characters long

Now for each datatype property value we have the following additional properties✍️:

1. Type string

{
    "name": "name",
    "dataType": "string"
}

This data type is used to represent text or character strings. It is commonly used for fields such as names, descriptions, or any other textual data.

2. Type double

{
    "name": "price",
    "dataType": "double"
}

The double type is used to represent floating-point (decimal) numbers. It is ideal for values requiring decimal precision, such as prices, rates or measurements.

3. Type int

{
    "name": "articleCountNumber",
    "dataType": "int"
}

The int type is used for whole numbers. It is suitable for fields requiring numerical values without decimal places, such as quantities, accounts or numerical identifiers.

4. Type datetime

{
    "name": "expirationDate",
    "dataType": "datetime"
}

This type represents a precise date and time. It is used for fields requiring a date and time indication, such as expiration, creation or modification dates.

5. Type date

{
    "name": "dateOfBirth",
    "dataType": "date"
}

The date type is used to represent a date without a time, such as a date of birth or an event date.

6. Type time

{
    "name": "repeatOn",
    "dataType": "time"
}

This type is used to represent a specific time of day, without date indication. It is useful for appointment times, recurring events or reminders.

7. Type guid

{
    "name": "userRecordId",
    "dataType": "guid"
}

The guid (Globally Unique Identifier) type is a unique value used to identify records globally. It is often used for unique identifiers of records in a database.

8. Type boolean

{
    "name": "isActive",
    "dataType": "boolean"
}

The boolean type is used to represent a binary value, either true or false. It is generally used for status indicators, such as account activation or deactivation.

9. Type datatype

{
    "name": "localization",
    "dataType": "activatord.datatypes.newdatatype1"//This property indicates that the "localization" attribute is not a primitive data type (such as integer, string, date, etc.), but rather a custom data type defined elsewhere in the system.
}

This makes it possible to structure data hierarchically, reusing customized data types for greater modularity.

It’s used⚒️ to reference another Data Type defined in Activator and also to encapsulate complex objects or specific data structures, inheriting the properties of the referenced Data Type.

10. Type enumaration

For the Enumeration<string> type, the values to be returned are in the enumValues array.

{
    "name": "gender",
    "dataType": "Enumeration<string>",
    "enumValues": [
        "male",
        "female"
    ]
}

The Enumeration type is used to define a list of predefined values from which the user can choose. For example, for gender, the available values would be male or female.

11. Type file

It is used to indicate that this attribute must contain a file.

{
    "name": "attachment",
    "dataType": "File",
    "directoryName": "attachments",//Name of the folder where it will be stored in the entity that will implement it.
    "maxMegaByteSize": 20,  //maximum file size
    "validExtensions": [ //List of accepted extensions
        "pdf",
        "docx",
        "doc",
        "png",
        "jpg",
        "jpeg"
    ]
}

This type is used to represent downloaded and uploaded files. It lets you specify the storage directory, maximum file size, and permitted file extensions, such as PDF documents, images, etc.

12. Type List<dataType>

The List<datatype> type is used⚒️ to define a collection of elements of the same type, where each element follows the structure of a specific Data Type.  This type can be used to group multiple instances of a data model into a list. The minItemsCount and maxItemsCount properties play a role in validating this list during model registration. The minItemsCount property specifies the minimum number of items required in the list, ensuring that it cannot be empty or contain an insufficient number of items. Conversely, maxItemsCount imposes an upper limit, preventing the list from containing more elements than the maximum allowed. 📢These properties ensure that the list respects the defined size constraints, while offering the flexibility to manage structured data collections within the application.

To illustrate the use of the List<datatype> type, we'll list several concrete examples, each demonstrating how different data types can be organized into lists👇.

• List<Datatype>

  {
      "name": "friends",
      "dataType": "List<activatord.datatypes.users>",
      "minItemsCount": 2,
      "maxItemsCount": 50
  }

  Represents a list of elements based on another data type, in this case activatord.datatypes.users.

• List<string>

  {
      "name": "keyWords",
      "dataType": "List<string>",
      "maxItemsCount": 10 
  }

  This type represents a list of character strings. It is useful for storing sets of keywords, tags, or other similar textual data.

• List<int>

  {
      "name": "validNumbers",
      "dataType": "List<int>"
  }

  This type represents a list of integers. It is used to store a series of integer numerical values

• List<double>

  {
      "name": "prices",
      "dataType": "List<double>"
  }

  This type represents a list of floating-point (decimal) numbers. It is ideal for storing prices, rates, or other values requiring decimal precision in a collection.

• List<guid>

  {
      "name": "listOfIds",
      "dataType": "List<guid>"
  }

  This type represents a list of globally unique identifiers (GUIDs). It is used to store several unique identifiers

Sequence Implementation

The sequence type in Activator Admin is specifically designed to be implemented on a Data Type to generate values that increment in a systematic and controlled way, following a fixed step defined in advance. When applied to a Data Type, this mechanism ensures that each new value associated with that Data Type is produced by adding a constant step to the previous value. 

How To Create A Sequence

In Activator Admin, Sequence is located in the menu container, as shown in (1) in the image below.

✋NB: You can access it from Entities main module.

After initiating the creation of the Data Type, by clicking on the +Add new button (illustrated at (2) on the image above), you’ll observe a form (illustrated at (3) on the image above) appearing on the right side with some fields.

🔬After filling in the name and description fields, let's focus on the Definition and Meta Data fields. 

The Meta Data field gathers and provides additional information for the component, please refer to  Meta Data for the complete list of additional information related to this component

As for the Definition field, let's take a closer look at its Json content in the next point.

JSON Definition Content

Note✍️ is where you'll be prompted to fill in various fields for the Sequence component. These fields will be used to define the sequence starting point and increment step.

{
    "seed": "1",
    "increament": "1"
}

JSON Description

How To Implement It In A Data Type

A sequence is implemented in a Data Type by integrating a sequence defined in the Data Type structure. For example, consider the following configuration:

{
    "name": "auto_increment",
    "dataType": "int",
    "sequence": "activatord.sequences.newSequence1"
}

sequence: The sequence property associates this field with a specific sequence, here named activatord.sequences.newSequence1

✋NB: A sequence can be implemented on int and double fields within a Data Type. This means you can use a sequence to generate incremental values not only for integers, but also for floating-point numbers.

DataType Inheritance 

Data Type inheritance in Activator allows you to create a new model by reusing the attributes of an existing Data Type. This is done using the extends property, which specifies the Data Types from which the new model inherits. For example, in the following code :

{
    "extends": [
        "activatord.datatypes.person"
    ],
    "attributes": [
        {
            "name": "workPlace",
            "required": "true",
            "dataType": "string"
        },
        {
            "name": "marritalStatus",
            "required": "false",
            "dataType": "Enumeration<string>",
            "enumValues": [
                "single",
                "married",
                "divorced"
            ]
        }
    ]
}

Here, the new Data Type inherits the attributes of Data Type activatord.datatypes.person, while adding its own specific attributes, such as workPlace and marritalStatus. This approach makes it possible to create more complex models while reusing existing data structures, facilitating data maintenance and consistency within the application.

CAUTION🚨:
When a Data Type is extended using the extends property, it's essential to understand that a new definition of an attribute can overwrite the existing one in the parent Data Type. In other words, if an attribute already present in the parent Data Type is redefined with new properties in the extended Data Type, these new properties will replace the inherited ones. For example, in our previous case, if the inherited Data Type activatord.datatypes.person already contained an attribute named workPlace with certain properties, and this attribute is redefined in the new Data Type via "attributes", the new properties defined in the extended Data Type will take over, replacing those of the parent. This mechanism makes it possible to customize or modify inherited attributes to suit the specific needs of the new model, while retaining the general structure of the parent Data Type.

DataType System Extension

On Activator, to extend a System Data Type, you need to access the extends property, which is already defined for each system Data Type.

To understand how to access it, refer to the image below👇:

1. List of system Data Type.
2. Tabs that let you access JSON content to extend a system Data Type.
3. JSON content for system Data Type extension

To extend an already defined system Data Type in Activator Admin, you need to access the Extension(illustrated at (2) on the image above) tab. In this tab, you will find the extends property, which is predefined by the system to manage extension. To customize or enrich this Data Type, simply add the Data Types you wish to extend in the extends property, as illustrated in the following code:

{
    "extends": [
        "activatord.datatypes.newdatatype1",
        "activatord.datatypes.newdatatype2"
    ]
}

By doing so, you combine the attributes and properties of the specified Data Types to create a more comprehensive data model tailored to your specific needs.

When extending📜 a system Data Type in Activator, if the same attribute exists both in the initial definition of the Data Type and in one of the new Data Types specified via the extends property, the attribute from the initial Data Type will be overridden by that of the new Data Type. In other words, the properties defined in the new Data Type will take precedence and replace those in the initial definition.

Get The Model Of A Data Type

The API https://v2_modulesapi_dev.asmlogic.com/api/tenants/{tenantId}/datatypes/{dataTypeName}/model allows you to retrieve the model implemented by a Data Type by making a GET request to this API.

To better understand, let's consider a Data Type activatord.datatypes.member which is structured as follows:

{
    "attributes": [
        {
            "name": "firstname",
            "required": "true",
            "dataType": "string"
        },
        {
            "name": "lastname",
            "required": "true",
            "dataType": "string"
        },
        {
            "name": "gender",
            "required": "false",
            "dataType": "Enumeration<string>",
            "enumValues": [
                "Male",
                "Female"
            ]
        },
        {
            "name": "emailAddress",
            "required": "true",
            "dataType": "string",
            "validations": [
                "RequireValue",
                "EmailAddress"
            ]
        },
        {
            "name": "curriculumVitae",
            "required": "false",
            "dataType": "File",
            "directoryName": "curriculumNew",
            "maxMegaByteSize": 20,
            "validExtensions": [
                "pdf",
                "docx",
                "doc",
                "png",
                "jpg",
                "jpeg"
            ]
        },
        {
            "name": "localization",
            "dataType": "activatord.datatypes.localization",
            "required": "false"
        },
        {
            "name": "certificates",
            "dataType": "List<activatord.datatypes.certificate>",
            "required": "false",
            "minItemsCount": 1
        }
    ]
}

In this Data Type activatord.datatypes.member, two other Data Types are involved, namely activatord.datatypes.localization in the localization attribute and activatord.datatypes.certificate in the certificates attribute. These two Data Types enhance the model by providing specific data structures.

• activatord.datatypes.localization is defined by :

  {
      "attributes": [
          {
              "name": "state",
              "required": "false",
              "dataType": "string"
          },
          {
              "name": "city",
              "required": "false",
              "dataType": "string"
          },
          {
              "name": "addressLine",
              "required": "false",
              "dataType": "string"
          }
      ]
  }

   

• activatord.datatypes.certificate is defined by:

  {
      "attributes": [
          {
              "name": "name",
              "required": "true",
              "dataType": "string"
          },
          {
              "name": "date",
              "required": "false",
              "dataType": "string"
          },
          {
              "name": "school",
              "required": "false",
              "dataType": "string"
          }
      ]
  }

After running a test on Postman to visualize the rendering of the model returned by the API, we have📸:

This👆 is the returned model of the Data type activatord.datatypes.member.

NOTE🚨:
The recordId field is always present in each attribute collection (except for the file type) when the data type is retrieved via the API. Additionally, the _lang_keys field consistently appears for each attribute. This field contains all the translations recorded in the Data Type, allowing for the management of different linguistic versions of the data.

The fields recordId and _lang_keys are native fields.

For more details go to Database Datas.

Conclusion

In conclusion, Data Types in Activator are important for structuring, validating, and managing data in a consistent and flexible way. They allow the definition and extension of data models used by entities, ensuring optimal integrity and adaptability of the information stored and processed within the application. 

Now that we have explored Data Types in detail, let’s move on to the concept of Entities, which are the primary actors in the manipulation and management of structured data within the application.