@gsb-core/mcp-docs/src/docs/createEntityDef.ts

Documentation for GSB MCP implementations

/**
 * Documentation for the createEntityDef operation
 */

/**
 * Returns documentation for the createEntityDef operation
 * @return {string} markdown documentation
 */
export function createEntityDefDocs(): string {
  return `
# CreateEntityDef Operation

## 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

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

### Error Response

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

## Example Usage

### Create a Simple Entity Definition with Property Permissions

\`\`\`typescript
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

\`\`\`typescript
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

### Related Operations
- 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
`;
}

/**
 * Returns a brief summary of the createEntityDef operation.
 * @return {string} A short description of the function.
 */
export function createEntityDefSummary(): string {
  return `
**Purpose**: Creates a new entity type (data table) in the system.

**When to use**:
- Defining new data structures
- Creating database tables
- Establishing entity relationships
- Setting up permission models

**Inputs**:
- entityDef: Object with name, title, properties array, permissions
- token (optional)
- tenantCode (optional)

**Returns**: Created entity definition with generated IDs.

**Effects**: Creates database table, establishes relationships, sets up permissions.
`;
}

export default createEntityDefDocs;