@gsb-core/mcp-docs/dist/docs/addProperty.js

Documentation for GSB MCP implementations

/**
 * Documentation for the addProperty operation
 */
/**
 * Returns documentation for the addProperty operation
 * @return {string} markdown documentation
 */
export function addPropertyDocs() {
    return `
# AddProperty Operation

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

\`\`\`json
{
    "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

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

## Example Usage

### Add a Simple String Property with Permissions

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

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

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

\`\`\`typescript
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
`;
}
/**
 * Returns a brief summary of the addProperty operation.
 * @return {string} A short description of the function.
 */
export function addPropertySummary() {
    return `
**Purpose**: Adds a new property (column) to an existing entity definition.

**When to use**:
- Extending entity schemas
- Adding new data fields
- Creating relationships between entities
- Defining searchable/indexable fields

**Inputs**:
- property: Object with name, title, definition_id, and other attributes
- entityDef (optional): Object identifying entity definition
- token (optional)
- tenantCode (optional)

**Returns**: Updated entity definition with new property.

**Effects**: Modifies database schema, creates indexes as specified.
`;
}
export default addPropertyDocs;
//# sourceMappingURL=addProperty.js.map