updateEntityDef() — Schema Manager

General Description

The updateEntityDef operation modifies an existing entity definition with updated schema information.

Detailed Description

This operation allows you to update the metadata and structure of an existing entity definition. You can modify attributes like the title, description, permissions, and other aspects of the entity definition. Some structural changes may be limited to preserve data integrity, and adding or removing properties should be done using the dedicated addProperty and removeProperty operations.

Input Parameters

Parameter	Type	Required	Description
entityDef	object	Yes	The entity definition object with updated information. Must include the ID of the existing entity definition.
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.

EntityDef Object Structure

Property	Type	Required	Description
id	string	Yes	The ID of the existing entity definition to update.
name	string	No	The name of the entity definition (usually cannot be changed after creation).
title	string	No	Display title for the entity definition.
description	string	No	Description of the entity definition.
dbTableName	string	No	Database table name (usually cannot be changed after creation).
publicAccess	boolean	No	Whether entity is publicly accessible.
activityLogLevel	number	No	Level of activity logging (0=None, 1=Changes, 2=All).
isActive	boolean	No	Whether the entity definition is active.
permissions	array	No	Array of permission objects controlling access to the entity.
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.

Response

Success Response

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

Error Response

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

Example Usage

Update Basic Entity Information with Permissions

const result = await updateEntityDef({
  entityDef: {
    id: "product-def-123",
    title: "Product Catalog Item",
    description: "Updated description for product catalog items",
    publicAccess: false,
    permissions: [
      {id: "product-team-write-permission-id"},
      {id: "all-users-read-permission-id"}
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Entity definition updated successfully");
  console.log("Updated title:", result.data.title);
  console.log("Updated description:", result.data.description);
} else {
  console.error("Error:", result.error);
}

Update Entity Activity Logging and Workflow Triggers

const result = await updateEntityDef({
  entityDef: {
    id: "order-def-456",
    activityLogLevel: 2, // Full logging
    title: "Customer Order Record",
    workflowTriggers: [
      {
        id: "notify-on-status-change"
      }
    ]
  },
  token: "your-auth-token"
});

if (result.success) {
  console.log("Entity definition updated with new logging level and workflow triggers");
}

Update Entity Property Permissions with Mixed Access

const result = await updateEntityDef({
  entityDef: {
    id: "employee-def-456",
    propertyPermissions: [
      {id: "hr-team-permission-id"} // HR team can access all properties by default
    ],
    properties: [
      {
        name: "name",
        permissions: [
          {id: "all-users-read-permission-id"} // Everyone can read names
        ]
      },
      {
        name: "salary",
        permissions: [
          {id: "finance-team-permission-id"}, // Only finance team can access salary
          {id: "self-read-permission-id"} // Employees can see their own salary
        ]
      }
      // All other properties will use propertyPermissions (HR team only)
    ]
  },
  token: "your-auth-token"
});

Additional Information

Immutable Properties

Some properties may be immutable after creation, particularly:

• The name of the entity definition
• The database table name
• Core structural elements
• Primary key configurations
• Certain reference property settings

Property Management

• For adding new properties to an entity definition, use the addProperty operation
• For removing properties from an entity definition, use the removeProperty operation
• For updating existing properties, use the updateProperty operation
• Property-level permissions can only be modified through the updateProperty operation

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 you update propertyPermissions:
  • The new permissions apply to all properties that don't have their own permissions defined
  • Properties with their own permissions remain unaffected

System Behavior

• Setting an entity definition as inactive (isActive: false) prevents new entities from being created but preserves existing data
• Changes to activity logging levels take effect immediately for new operations
• Updates to workflow triggers are applied to all subsequent events
• Access permissions are enforced based on the provided token

Best Practices

• Be cautious when updating entity definitions in production environments
• Test changes in a development environment first
• Consider the impact on existing data and integrations
• Document significant changes for other developers
• Coordinate updates with related entity definitions if necessary

Related Operations

• For creating new entity definitions, use the createEntityDef operation
• For retrieving entity definitions, use the getEntityDef operation
• For creating or updating multiple related entities at once, use the createOrUpdateSchema operation