createOrUpdateSchema() — Schema Manager

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

{
  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

// 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:

enum RefType {
  OneToOne = 1,
  OneToMany = 2,
  ManyToOne = 3,
  ManyToMany = 4
}