API reference

createEntityDef() — Schema Manager

Purpose : Creates a new entity type data table in the system. When to use : Defining new data structures Creating database tables Establishing entity re…

Contract source@gsb-core/mcp-docs:createEntityDef

General Description

The createEntityDef operation creates a new entity definition in the system.

Detailed Description

This operation allows you to define a new entity type in the GSB system. An entity definition represents a data table and includes metadata about the table itself as well as definitions for all of its properties (columns). When an entity definition is created, the corresponding database table is automatically generated.

Input Parameters

Parameter	Type	Required	Description
entityDef	object	Yes	The entity definition object.
token	string	No	Authentication token for your request. If not provided, the system will use the default API key from environment variables.
tenantCode	string	No	Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables.

Entity Definition Object Structure

Property	Type	Required	Description
id	string	No	Unique identifier (auto-generated if not provided).
name	string	Yes	Entity name (must be unique, PascalCase recommended).
title	string	Yes	Display title for the entity.
description	string	No	Description of the entity.
dbTableName	string	No	Database table name (generated from entity name if not provided).
publicAccess	boolean	No	Whether entity is publicly accessible.
activityLogLevel	number	No	Level of activity logging (0=None, 1=Changes, 2=All).
properties	array	No	Array of property definitions (columns).
permissions	array	No	Array of permission objects controlling access to the entity. If not provided, all users can read and write.
propertyPermissions	array	No	Base permissions applied to all properties unless overridden. If set, these permissions are applied to all properties that don't have their own permissions defined.
workflowTriggers	array	No	Array of workflow trigger objects for the entity.
isActive	boolean	No	Whether the entity is active.

Property Object Structure

Property	Type	Required	Description
id	string	No	Unique identifier for the property (auto-generated if not provided).
name	string	Yes	Name of the property (must be unique within the entity).
title	string	Yes	Human-readable title for the property.
description	string	No	Description of the property.
definition_id	string	Yes	Reference to the property definition (data type).
orderNumber	number	No	Display order for the property.
isRequired	boolean	No	Whether the property is required.
isSearchable	boolean	No	Whether the property should be searchable.
isUnique	boolean	No	Whether the property value must be unique across all entities.
isPrimaryKey	boolean	No	Whether the property is a primary key.
isIndexed	boolean	No	Whether the property should be indexed for faster queries.
maxLength	number	No	Maximum length for string properties.
defaultValue	any	No	Default value for the property if not specified when creating an entity.
regex	string	No	Validation regex pattern.
refEntDef_id	string	No	Referenced entity definition ID (for reference properties).
refEntPropName	string	No	Property name in referenced entity (for reference properties).
refType	number	No	Reference type (OneToOne, OneToMany, etc.).
isEncrypted	boolean	No	Whether the property value should be encrypted.
isMultiLingual	boolean	No	Whether the property supports multiple languages.
fullTextIndex	boolean	No	Whether to create a vector index for full text search (for RichText properties).
cascadeReference	boolean	No	Whether to cascade delete and include in copy operations (for reference properties).
permissions	array	No	Array of permission objects controlling access to the property.
formModes	number	No	Form modes where property is visible.
listScreens	number	No	List screens where property is visible.

Response

Success Response

{
    "success": true,
    "entityDef": // created entity definition object including id and properties with id
}

Error Response

{
    "success": false,
    "error": "Error message describing what went wrong"
}

Example Usage

Create a Simple Entity Definition with Property Permissions

const result = await createEntityDef({
  entityDef: {
    name: "User",
    title: "User Information",
    description: "User profile data",
    publicAccess: false,
    // Set base permissions for all properties - only admins can access
    propertyPermissions: [
      {id: "admin-only-permission-id"}
    ],
    properties: [
      {
        name: "username",
        title: "Username",
        description: "User's login name",
        definition_id: "c6c34bf3-f51b-4e69-a689-b09847be74b9", // String type
        isRequired: true,
        isSearchable: true,
        orderNumber: 10,
        // Override propertyPermissions for this specific property
        permissions: [
          {id: "all-users-read-permission-id"},
          {id: "self-write-permission-id"}
        ]
      },
      {
        name: "email",
        title: "Email Address",
        description: "User's email address",
        definition_id: "df7ce94b-d59c-4b67-8519-aa4c98ab477c", // Email type
        isRequired: true,
        isUnique: true,
        orderNumber: 20
        // No permissions specified, will use propertyPermissions (admin-only)
      },
      {
        name: "password",
        title: "Password",
        description: "User's password",
        definition_id: "7291fbc2-a7cf-4713-a876-0cff085cc035", // Password type
        isRequired: true,
        isEncrypted: true,
        orderNumber: 30,
        // Override propertyPermissions for this specific property
        permissions: [
          {id: "self-only-permission-id"}
        ]
      }
    ]
  },
  token: "your-auth-token"
});

Create an Entity with Reference Properties

const result = await createEntityDef({
  entityDef: {
    name: "Order",
    title: "Customer Order",
    description: "Order information",
    properties: [
      {
        name: "orderNumber",
        title: "Order Number",
        description: "Unique order identifier",
        definition_id: "c6c34bf3-f51b-4e69-a689-b09847be74b9", // String type
        isRequired: true,
        isSearchable: true,
        isUnique: true,
        orderNumber: 10
      },
      {
        name: "customer",
        title: "Customer",
        description: "Customer who placed the order",
        definition_id: "924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
        refEntDef_id: "customer-def-id", // ID of the Customer entity definition
        refEntPropName: "orders", // Property name in Customer entity for back-reference
        refType: 3, // ManyToOne
        isRequired: true,
        orderNumber: 20
      },
      {
        name: "notes",
        title: "Notes",
        description: "Order notes",
        definition_id: "e07f578e-2705-49c1-b97f-3ca5963c67c0", // RichText type
        isSearchable: true,
        fullTextIndex: true, // Enable full text search
        orderNumber: 30
      },
      {
        name: "items",
        title: "Items",
        description: "Items in the order",
        definition_id: "924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
        refEntDef_id: "item-def-id",
        refEntPropName: "order",
        refType: 3, // ManyToOne
        cascadeReference: true, // Cascade delete and include in copy
        orderNumber: 40
      }
    ]
  },
  token: "your-auth-token"
});

Additional Information

The createEntityDef operation is used to define new data tables in the system.
Entity names must be unique across the entire system.
Entity names should follow PascalCase convention (e.g., "Customer", "ProductCategory").
Property names should follow camelCase convention (e.g., "firstName", "orderDate").

Default Properties

Default properties are automatically added to every entity definition:

id - Primary key (UUID), Required
title - Display title, better to define automated form builders use this field
createdBy - User who created the record (If a property with this name is defined GSB will automatically set its value)
lastUpdatedBy - User who last updated the record (If a property with this name is defined GSB will automatically set its value)
createDate - Creation timestamp (If a property with this name is defined GSB will automatically set its value)
lastUpdateDate - Last update timestamp (If a property with this name is defined GSB will automatically set its value)

Common Property Types

Common property definition IDs:

String: c6c34bf3-f51b-4e69-a689-b09847be74b9
Number: 35efcf9c-fff0-44d4-8972-73a9a32b93fa
Boolean: 7868afdf-2709-45be-87e3-87de8d35f30f
DateTime: 12e647e0-ebd2-4ec2-a4e3-82c1dfe07da2
Reference: 924acba8-58c5-4881-940d-472ec01eba5f
Enum: 7bf08f4f-7de0-469e-bbfb-f4c43762f4d7
RichText: e07f578e-2705-49c1-b97f-3ca5963c67c0
Email: df7ce94b-d59c-4b67-8519-aa4c98ab477c
Password: 7291fbc2-a7cf-4713-a876-0cff085cc035
ID: 5c0aa76f-9c32-4e7e-a4bc-b56e93877883

Reference Properties

For reference properties, you must specify:

refEntDef_id: The ID of the referenced entity definition
refEntPropName: The name of the property in the referenced entity that will hold the back-reference
refType: The type of relationship:
- 1 = OneToOne
- 2 = OneToMany
- 3 = ManyToOne
- 4 = ManyToMany

Permissions

Entity-level permissions control overall access to the entity
Property-level permissions can be set in two ways:
1. Using propertyPermissions at the entity level to set base permissions for all properties
2. Using permissions on individual properties to override the base permissions
If propertyPermissions is set:
- It applies to all properties that don't have their own permissions defined
- Properties with their own permissions ignore propertyPermissions completely
- This is useful for setting default access restrictions and then opening up specific properties
Example use cases:
- Restricting all properties to admin-only access except for specific public fields
- Setting stricter default permissions and selectively allowing access to certain properties
- Implementing privacy controls where most data is protected but some fields are public

Caching and Availability

Upon creation of an entity definition, the system initiates a cache update process across all redundant servers
The cache update process is asynchronous and may take up to 5 seconds to complete
During this time, the new entity definition may not be immediately available for use
It's important to wait for the cache update process to complete before adding new properties or referencing the new entity definition

System Behavior

When creating an entity definition:

The system will automatically create the corresponding database table
Default properties will be added if not explicitly defined
Indexes will be created for searchable and unique properties
For reference properties, appropriate foreign key fields and back-references are created automatically
Access permissions are enforced based on the provided token

For updating existing entity definitions, use the updateEntityDef operation
For adding new properties to an existing entity, use the addProperty operation
For creating multiple related entities at once, use the createOrUpdateSchema operation