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

Documentation for GSB MCP implementations

export const createOrUpdateSchema = `
# createOrUpdateSchema

Creates or updates multiple entity definitions and their properties in a single operation, with intelligent handling of reference properties between entities.

## Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| entityDefs | GsbEntityDef[] | Array of entity definitions to create or update |
| token | string | (Optional) Authentication token |
| tenantCode | string | (Optional) Tenant code |

## Returns

\`\`\`typescript
{
  createdEntities: GsbEntityDef[];  // List of entities created
  updatedEntities: GsbEntityDef[];  // List of entities updated
  errors: string[];                 // Any errors that occurred during processing
  success: boolean;                 // Whether the operation succeeded
}
\`\`\`

## Example

\`\`\`typescript
// Define multiple related entities
const customerDef = {
  id: "customer-entity-definition-id",
  name: "Customer",
  title: "Customer Information",
  description: "Stores customer data",
  permissions:[{id:"all-users-read-permission-id"}, {id:"sales-team-write-permission-id"}] // If you don't pass permissions, all users can read and write
  properties: [
    {
      id:"customer-id-property-id",
      name: "id",
      title: "ID",
      description: "Unique identifier for the customer",
      definition_id: "5c0aa76f-9c32-4e7e-a4bc-b56e93877883", // Every definition must have an id property
      isRequired: true,
    },
    {
      id:"customer-name-property-id",
      name: "name",
      title: "Name",
      description: "Customer name",
      definition_id: "c6c34bf3-f51b-4e69-a689-b09847be74b9", // String type
      isRequired: true,
      isSearchable: true
    },
    {
      id:"customer-password-property-id",
      name: "password",
      title: "Password",
      description: "Customer password",
      definition_id: "c6c34bf3-f51b-4e69-a689-b09847be74b9", // String type,
      isEncrypted: true, // Encrypted property
      permissions:[{id:"only-self-read-permission-id"}] // only the owner can read the property
    }
  ]
};

const orderDef = {
  id: "order-entity-definition-id",
  name: "Order",
  title: "Order Information",
  description: "Stores order data",
  permissions:[{id:"all-users-read-permission-id"}, {id:"sales-team-write-permission-id"}] // If you don't pass permissions, all users can read and write
  properties: [
    {
      id:"order-id-property-id",
      name: "id",
      title: "ID",
      description: "Unique identifier for the order",
      definition_id: "5c0aa76f-9c32-4e7e-a4bc-b56e93877883", // Id type
      isRequired: true,
      isSearchable: true
    },
    {
      id:"order-notes-property-id",
      name: "notes",
      title: "Notes",
      description: "Notes of the order",
      definition_id: "e07f578e-2705-49c1-b97f-3ca5963c67c0", // RichText type
      isRequired: true,
      isSearchable: true,
      fullTextIndex: true // Create vector index for full text search
    },
    {
      id:"order-customer-property-id",
      name: "customer",
      title: "Customer",
      description: "Customer who placed the order",
      definition_id: "924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
      refEntDef_id: "customer-entity-definition-id", // Will be replaced with actual Customer entity ID
      refEntPropName: "orders", // Creates a back-reference property in Customer
      refType: 2 // OneToMany relationship
    },
    { 
      id:"order-items-property-id",
      name:"items",
      title:"Items",
      description:"Items in the order",
      definition_id:"924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
      refEntDef_id:"item-entity-definition-id", // Will be replaced with actual Item entity ID
      refEntPropName:"order", // Creates a back-reference property in Item
      refType: 3, // ManyToOne relationship
      cascadeReference: true // Cascade delete, also include in copy operation
     },
     {
      id:"order-tags-property-id",
      name:"tags",
      title:"Tags",
      description:"Tags in the order",
      definition_id:"924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
      refEntDef_id:"tag-entity-definition-id", // Will be replaced with actual Tag entity ID
      refEntPropName:"orders", // Creates a back-reference property in Tag
      refType: 4 // ManyToMany relationship
     },
     {
      id:"order-invoice-property-id",
      name:"invoice",
      title:"Invoice",
      description:"Invoice in the order",
      definition_id:"924acba8-58c5-4881-940d-472ec01eba5f", // Reference type
      refEntDef_id:"invoice-entity-definition-id", // Will be replaced with actual Invoice entity ID
      refEntPropName:"order", // Creates a back-reference property in Invoice
      refType: 1 // OneToOne relationship
     }
  ]
};

// Create or update both entity definitions with reference handling in one operation
const result = await mcp.createOrUpdateSchema({
  entityDefs: [customerDef, orderDef]
});

if (result.success) {
  console.log(\`Created \${result.createdEntities.length} entities\`);
  console.log(\`Updated \${result.updatedEntities.length} entities\`);
} else {
  console.error("Errors:", result.errors);
}
\`\`\`

## Description

The \`createOrUpdateSchema\` tool provides a way to create or update multiple entity definitions in a single operation. This is particularly useful when creating a set of related entities with reference properties between them.

### Schema Creation Best Practices

When creating an initial schema with multiple related entity definitions:

1. **Define all entity definitions in a single operation**:
   - Using createOrUpdateSchema, you can define the entire schema structure at once
   - The service will manage dependency order and relationships automatically
   - İf its first time to create the schema, its essential to pass all entity definitions in a single operation, so GSB can manage the dependencies between entities correctly.
   - If you want to add new entity definitions to the schema, you can use the createEntityDef method.

2. **Reference Property Management**:
   - Specify the correct \`refEntDef_id\`, \`refEntPropName\` and \`refType\`
   - For single relationships (OneToOne, ManyToOne), foreign keys properties(ending with _id) are automatically created
   - For example, adding \`customer\` ref property to an Order as OneToMany relationship(refType: 2) with refentpropname: orders
      *  \`customer_id\` field will be automatically created in the Order entity definition
      *  \`orders\` field will be automatically created in the Customer entity definition

3. **ID management**:
  - Every definition and property must have an id property.
  - If you don't pass an id, it will be generated by the system, and will be included in the response.
  - Its essential that every ID you provide is globally unique.

4. **Caching and availability**:
  - Upon creation or editing of an entity definition, the system will initiate 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 or updated entity definitions may not be immediately available for use.
  - Its also important to wait for the cache update process to complete before adding new properties or referencing the new  entity definitions.

5. **Permissions**:
  - If you don't pass permissions, all users can read and write the entity definitions and properties.
  - If you pass permissions, the permissions will act as policies, if users cridentials match any policy, they will be able to execute the operation of the policy.
  - Permissions can be defined in the Admin UI, or with API by using the entity definition named : "GsbPermission"
  - Dont pass permision ids that dont exist in the system, instead you can pass a fully defined GsbPermission object.

### Reference Types

The \`refType\` property defines the relationship type:

\`\`\`typescript
enum RefType {
  OneToOne = 1,
  OneToMany = 2,
  ManyToOne = 3,
  ManyToMany = 4
}
\`\`\`
`;
/**
 * Returns a brief summary of the createOrUpdateSchema operation.
 * @return {string} A short description of the function.
 */
export function createOrUpdateSchemaSummary() {
    return `
**Purpose**: Creates or updates multiple entity definitions in a single transaction.

**When to use**:
- Setting up initial schema structure
- Creating interconnected entity definitions
- Establishing relationships between entities
- Making coordinated schema changes

**Inputs**:
- entityDefs: Array of entity definitions to create/update
- token (optional)
- tenantCode (optional)

**Returns**: Lists of created/updated entities and any errors.

**Effects**: Creates/modifies database tables, establishes relationships automatically.
`;
}
export default function () {
    return createOrUpdateSchema;
}
//# sourceMappingURL=createOrUpdateSchema.js.map