updateProperty() — Schema Manager

General Description

The updateProperty operation modifies an existing property in an entity definition.

Detailed Description

This operation allows you to update the attributes and settings of an existing property in an entity definition. You can modify aspects such as the title, description, validation rules, permissions, and other metadata. Some structural changes may be limited to preserve data integrity, and certain core attributes like the property name or data type may have restrictions on modifications.

Input Parameters

Parameter	Type	Required	Description
property	object	Yes	The property definition object with updated information. It MUST include either the id of the property, the name of the property, or the ownerEntityDefId to identify which property to update. Other attributes to be updated should be included.
entityDef	object	No	Optional. The entity definition object to modify. Should contain either the id or name of the entity definition. Not required if property.id or property.ownerEntityDefId is provided.
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	ID of the property to update. If provided, entityDef is not required.
ownerEntityDefId	string	No	ID of the entity definition that owns this property. If provided, entityDef is not required.
name	string	No	Name of the property (cannot be changed after creation).
title	string	No	Human-readable title for the property.
description	string	No	Description of the property.
definition_id	string	No	Reference to the property definition (data type).
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.
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 modified property
        "id": "string",
        "name": "string",
        "properties": [
            // All properties including the updated one
        ]
    }
}

Error Response

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

Example Usage

Update Property Title and Description

const result = await updateProperty({
  property: {
    name: "phoneNumber", // Name of the property to update
    title: "Contact Phone",
    description: "Primary contact phone number for the customer",
    permissions: [
      {id: "sales-team-write-permission-id"},
      {id: "all-users-read-permission-id"}
    ]
  },
  entityDef: { id: "customer-def-123" }, // or { name: "Customer" }
  token: "your-auth-token"
});

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

Update Property Validation Rules and Security

Using property.id to identify the property:

const result = await updateProperty({
  property: {
    id: "property-id",
    name: "price",
    regex: "^[0-9]+(\.[0-9]{1,2})?$",
    maxLength: 10,
    isEncrypted: true,
    permissions: [{id: "finance-team-permission-id"}]
  },
  token: "your-auth-token"
});

Update Property with Advanced Features

Using ownerEntityDefId to specify the owner:

const result = await updateProperty({
  property: {
    name: "customerReference",
    title: "Customer Reference Number",
    isRequired: true,
    isSearchable: true,
    isMultiLingual: true,
    description: "Unique reference number provided by the customer",
    ownerEntityDefId: "order-def-789"
  },
  token: "your-auth-token"
});

Update Reference Property Settings

const result = await updateProperty({
  property: {
    name: "assignedTo",
    refEntDef_id: "user-def-id",
    refEntPropName: "assignedTasks",
    refType: 3, // ManyToOne
    cascadeReference: true, // Enable cascade delete
    permissions: [
      {id: "task-managers-permission-id"},
      {id: "assigned-user-permission-id"}
    ]
  },
  entityDef: { name: "Task" },
  token: "your-auth-token"
});

Update Multiple Properties

You can use saveMappedItems to update 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 update

Additional Information

Property Identification

• Properties can be identified using:
  • property.id: Direct property ID
  • property.name + entityDef: Property name within an entity
  • property.name + property.ownerEntityDefId: Property name with owner entity ID

Immutable Attributes

Some property attributes cannot be changed after creation:

• Property name
• Core data type (definition_id)
• Primary key status
• Certain reference property configurations

Permissions

• If you update permissions, the new permissions array completely replaces existing permissions
• If you don't include permissions in the update, existing permissions remain unchanged
• 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 updating 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 updated property configuration may not be immediately available
• It's important to wait for the cache update process to complete before making additional changes

Data Integrity

When updating a property:

• Making a property required may affect existing entities that don't have a value
• Making a property unique will validate that all existing values are unique
• Adding or modifying validation rules will not automatically validate existing data
• Changing the default value only affects new entities created after the change
• Enabling encryption will not automatically encrypt existing values

System Behavior

• Changes to searchability may trigger index updates
• Modifying reference properties may affect related entities
• Enabling full text search will create necessary database indexes
• Permission changes take effect immediately for new operations

Best Practices

• Test changes in a development environment first
• Consider the impact on existing data and queries
• Document significant changes for other developers
• Coordinate updates with related entity definitions
• Use batch updates when modifying multiple properties

Related Operations

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