Entity Management

Backbase provides APIs for managing entities, fields, and indexes programmatically. These APIs support schema creation and modification operations.

Entity Operations

Create Entity

Create a new entity with fields and configuration:

{
  "code": "product",
  "name": "Product",
  "description": "Product catalog entity",
  "fields": [
    {
      "code": "name",
      "name": "Product Name",
      "fieldType": "TEXT",
      "isRequired": true,
      "isSearchable": true
    },
    {
      "code": "price",
      "name": "Price",
      "fieldType": "AMOUNT",
      "isRequired": true
    }
  ],
  "isTranslatable": false,
  "isAuditable": true
}

Update Entity

Modify existing entity configuration:

{
  "id": "entity_id",
  "name": "Updated Product",
  "description": "Updated description",
  "isAuditable": true
}

Delete Entity

Remove an entity and all its data:

{
  "id": "entity_id"
}

Query Entities

List all entities in your application:

{
  "entities": [
    {
      "id": "entity_id",
      "code": "product",
      "name": "Product",
      "description": "Product catalog entity",
      "isTranslatable": false,
      "isAuditable": true,
      "fields": [
        {
          "id": "field_id",
          "code": "name",
          "name": "Product Name",
          "fieldType": "TEXT",
          "isRequired": true
        }
      ],
      "indexes": [
        {
          "id": "index_id",
          "name": "name_index",
          "fields": ["name"]
        }
      ]
    }
  ]
}

Field Management

Add Field

Add a new field to an existing entity:

{
  "entityId": "entity_id",
  "code": "category",
  "name": "Category",
  "fieldType": "REFERENCE",
  "isRequired": false,
  "reference": {
    "entityCode": "category",
    "displayField": "name"
  }
}

Update Field

Modify existing field configuration:

{
  "id": "field_id",
  "name": "Updated Field Name",
  "isRequired": true,
  "defaultValue": "default"
}

Remove Field

Delete a field from an entity:

{
  "id": "field_id"
}

Index Management

Create Index

Create database indexes for performance optimization:

{
  "entityId": "entity_id",
  "name": "product_category_index",
  "fields": ["category", "status"],
  "unique": false
}

Remove Index

Delete an existing index:

{
  "id": "index_id"
}

Query Indexes

List indexes for an entity:

{
  "indexes": [
    {
      "id": "index_id",
      "name": "product_category_index",
      "fields": ["category", "status"],
      "unique": false
    }
  ]
}

Entity Configuration

Basic Properties

Property	Type	Required	Description
`code`	`string`	Yes	Unique entity identifier
`name`	`string`	Yes	Display name for the entity
`description`	`string`	No	Entity documentation
`fields`	`array`	Yes	Array of field definitions

Advanced Properties

Property	Type	Default	Description
`isTranslatable`	`boolean`	`false`	Enable multi-language support
`isAuditable`	`boolean`	`false`	Enable audit trail logging
`directoryId`	`string`	`null`	Organization directory

UI Configuration

Customize how entities appear in the Studio UI:

{
  ui: {
    displayField: "name"        # Field to show in lists
    icon: "package"            # Icon for the entity
    color: "#3B82F6"          # Color theme
    listView: {
      defaultSort: "name"      # Default sort field
      pageSize: 25            # Items per page
    }
  }
}

Field Definitions

Required Properties

Property	Type	Description
`code`	`string`	Unique field identifier
`name`	`string`	Display name
`fieldType`	`string`	One of the supported field types

Optional Properties

Property	Type	Description
`description`	`string`	Field documentation
`isRequired`	`boolean`	Mandatory field flag
`isUnique`	`boolean`	Uniqueness constraint
`isTranslatable`	`boolean`	Multi-language support
`isSearchable`	`boolean`	Full-text search inclusion
`encrypted`	`boolean`	Encryption at rest
`defaultValue`	`any`	Default value for new records

Reference Configuration

For REFERENCE fields, specify the target entity:

{
  fieldType: "REFERENCE"
  reference: {
    entityCode: "category"     # Target entity code
    displayField: "name"       # Field to display in UI
  }
}

Enum Configuration

For ENUM fields, define allowed values:

{
  fieldType: "ENUM"
  enum: {
    values: ["active", "inactive", "pending"]
  }
}

Index Types

Simple Index

Index on a single field for query optimization:

{
  name: "status_index"
  fields: ["status"]
  unique: false
}

Compound Index

Index on multiple fields for complex queries:

{
  name: "category_status_index"
  fields: ["category", "status"]
  unique: false
}

Unique Index

Enforce uniqueness across field combinations:

{
  name: "unique_code_index"
  fields: ["code"]
  unique: true
}

Validation Rules

Entity Validation

Entity code must be unique within the application
Entity code must follow naming conventions (alphanumeric + underscore)
At least one field must be defined

Field Validation

Field code must be unique within the entity
Field code must follow naming conventions
REFERENCE fields must specify valid target entity
ENUM fields must have at least one value

Index Validation

Index fields must exist in the entity
Compound indexes limited to 5 fields maximum
Unique indexes cannot include nullable fields

Migration Handling

Schema changes are automatically migrated:

Adding Fields

New fields added without data loss
Default values applied to existing records
Indexes updated automatically

Modifying Fields

Compatible changes applied immediately
Breaking changes require manual migration
Data validation runs after changes

Removing Fields

Field data marked for deletion
Cleanup performed during maintenance windows
Dependent references validated

Error Handling

Common error scenarios and responses:

Duplicate Entity Code

{
  "error": "ENTITY_CODE_EXISTS",
  "message": "Entity with code 'product' already exists",
  "details": {
    "code": "product",
    "existingId": "existing_entity_id"
  }
}

Invalid Field Type

{
  "error": "INVALID_FIELD_TYPE",
  "message": "Field type 'INVALID' is not supported",
  "details": {
    "fieldCode": "invalid_field",
    "supportedTypes": ["TEXT", "INT", "BOOLEAN", ...]
  }
}

Reference Not Found

{
  "error": "REFERENCE_ENTITY_NOT_FOUND",
  "message": "Referenced entity 'category' does not exist",
  "details": {
    "fieldCode": "category",
    "referencedEntity": "category"
  }
}

Entity Management

On this page