addProperty() — Schema Manager

General Description

The addProperty operation adds a new property to an existing entity definition.

Detailed Description

This operation allows you to extend an entity definition by adding a new property (column). The property can be of various types including primitive types (string, number, boolean, date), reference types (relationships to other entities), or specialized types (email, password, rich text, etc.). When a property is added, the underlying database schema is updated accordingly.

Input Parameters

Parameter	Type	Required	Description
property	object	Yes	The property definition object.
entityDef	object	No	Optional. The entity definition object to modify. Should contain either the id or name of the entity definition. If not provided, the property.ownerEntityDefId must be specified.
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.

Property Object Structure

Property	Type	Required	Description
id	string	No	Unique identifier for the property (auto-generated if not provided).
ownerEntityDefId	string	No	ID of the entity definition that will own this property. Required if entityDef is 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,
    "data": {
        // The updated entity definition with the new property
        "id": "string",
        "name": "string",
        "properties": [
            // All properties including the newly added one
        ]
    }
}

Error Response

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

Example Usage

Add a Simple String Property with Permissions

const result = await addProperty({
  property: {
    name: "phoneNumber",
    title: "Phone Number",
    description: "Customer's contact phone number",
    definition_id: "c6c34bf3-f51b-4e69-a689-b09847be74b9", // String type
    isSearchable: true,
    orderNumber: 10,
    permissions: [
      {id: "sales-team-write-permission-id"},
      {id: "all-users-read-permission-id"}
    ]
  },
  entityDef: { name: "Customer" }, // or { id: "customer-def-123" }
  token: "your-auth-token"
});

if (result.success) {
  console.log("Property added successfully");
} else {
  console.error("Error:", result.error);
}

Add a Required Number Property with Encryption

const result = await addProperty({
  property: {
    name: "price",
    title: "Price",
    description: "Product price in USD",
    definition_id: "35efcf9c-fff0-44d4-8972-73a9a32b93fa", // Number type
    isRequired: true,
    isSearchable: false,
    isEncrypted: true,
    orderNumber: 20,
    permissions: [{id: "finance-team-permission-id"}]
  },
  entityDef: { name: "Product" },
  token: "your-auth-token"
});

Add a Reference Property with Cascade Delete

Using ownerEntityDefId to specify the owner:

const result = await addProperty({
  property: {
    name: "customer",
    title: "Customer",
    description: "Customer who placed the order",
    definition_id: "924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
    refEntDef_id: "customer-def-123",
    refEntPropName: "orders",
    refType: 3, // ManyToOne
    cascadeReference: true, // Enable cascade delete
    isRequired: true,
    orderNumber: 30,
    ownerEntityDefId: "order-def-789"
  },
  token: "your-auth-token"
});

Add a Rich Text Property with Full Text Search

const result = await addProperty({
  property: {
    name: "description",
    title: "Description",
    description: "Detailed product description",
    definition_id: "e07f578e-2705-49c1-b97f-3ca5963c67c0", // RichText type
    isSearchable: true,
    fullTextIndex: true, // Enable full text search
    isMultiLingual: true, // Enable multi-language support
    orderNumber: 40
  },
  entityDef: { name: "Product" },
  token: "your-auth-token"
});

Add Multiple Properties

You can use saveMappedItems to add multiple properties at once. Please refer to the saveMappedItems documentation for more information. Required parameters:

• entityId: The ID of the entity definition
• entityDef: "GsbEntityDef"
• propName: "properties"
• items: Array of property objects to add

Additional Information

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

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

• If you don't specify permissions, the property inherits permissions from its entity definition
• If you specify permissions, they act as additional restrictions on top of entity permissions
• Permissions can be defined in the Admin UI or via API using the "GsbPermission" entity definition
• Don't pass permission IDs that don't exist in the system; instead, pass a fully defined GsbPermission object

Caching and Availability

• Upon adding a property, 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 property may not be immediately available
• It's important to wait for the cache update process to complete before using the new property

Database Impact

When adding a property:

• The system automatically updates the database schema
• Appropriate indexes are created based on property settings
• Existing entities will have null values unless a default value is specified
• For required properties, consider providing a default value
• For encrypted properties, appropriate encryption infrastructure is set up
• For full text search, necessary search indexes are created

System Behavior

• Property names must be unique within an entity definition
• Names should follow camelCase convention
• The system automatically handles database schema updates
• Indexes are created for searchable and unique properties
• Reference properties create appropriate foreign key relationships
• Access permissions are enforced based on the provided token

Best Practices

• Plan property names carefully as they cannot be changed later
• Consider the impact on existing data and queries
• Test new properties in a development environment first
• Document property purposes and relationships
• Use batch operations for adding multiple properties
• Consider default values for required properties
• Plan permissions carefully before implementation

Related Operations

• For updating properties, use the updateProperty operation
• For removing properties, use the removeProperty operation
• For updating multiple properties, use the saveMappedItems operation
• For complete entity updates, use the updateEntityDef operation