Object Definition Commands Reference

Overview

Object Definition Commands manage dynamic form templates that can be attached to business entities (Loans, Customers, Accounts, Transactions). These templates define structured data schemas with validation rules, conditional visibility, and client-side scripting capabilities.

What are Object Definitions?

Object Definitions are reusable form templates that define:

Schema Structure - Field definitions and data types
Validation Rules - Required fields, formats, constraints
Conditional Logic - When the form should appear
Client Scripts - Dynamic behavior and calculations
Entity Association - Which business entity types can use this template
Multiple Instances - Whether multiple forms can be created per entity

Common Use Cases

✅ Loan Application Forms - Capture loan-specific data
✅ KYC Documents - Customer verification information
✅ Credit Assessment Forms - Credit scoring and risk analysis
✅ Approval Checklists - Review and approval tracking
✅ Custom Questionnaires - Dynamic data collection
✅ Compliance Forms - Regulatory compliance data
✅ Collateral Details - Asset and collateral information

Commands Reference

CreateObjectDefinitionCommand

Create a new Object Definition template.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "code": "loan_credit_assessment",
  "name": "Loan Credit Assessment Form",
  "entityType": 3,
  "formId": 25,
  "description": "Credit scoring and assessment template for loan applications",
  "schemaJson": "{\"type\":\"object\",\"properties\":{\"creditScore\":{\"type\":\"number\",\"minimum\":300,\"maximum\":850},\"riskRating\":{\"type\":\"string\",\"enum\":[\"Low\",\"Medium\",\"High\"]}},\"required\":[\"creditScore\",\"riskRating\"]}",
  "condition": "loan.amount > 10000",
  "clientScript": "if (data.creditScore < 600) { showWarning('High Risk Customer'); }",
  "allowsMultipleInstances": false,
  "maxInstancesAllowed": null
}

Request Fields

Field	Type	Required	Default	Description
`code`	string	Yes	-	Unique identifier code
`name`	string	Yes	-	Display name
`entityType`	int	Yes	-	Entity type (see Entity Types Reference below)
`formId`	long	No	null	Associated form template ID
`description`	string	No	null	Description of purpose
`schemaJson`	string	No	null	JSON Schema defining fields
`condition`	string	No	null	JavaScript expression for conditional display
`clientScript`	string	No	null	JavaScript code for dynamic behavior
`allowsMultipleInstances`	bool	No	false	Allow multiple instances per entity
`maxInstancesAllowed`	int	No	null	Maximum instances allowed

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinition created successfully",
  "data": {
    "id": 45,
    "code": "loan_credit_assessment",
    "name": "Loan Credit Assessment Form",
    "uniqueIdentifier": "obj_def_abc123xyz",
    "entityType": 3,
    "entityTypeDesc": "Loan",
    "formId": 25,
    "description": "Credit scoring and assessment template for loan applications",
    "schemaJson": "...",
    "condition": "loan.amount > 10000",
    "clientScript": "...",
    "allowsMultipleInstances": false,
    "maxInstancesAllowed": null,
    "version": 1,
    "isActive": true,
    "createdAt": "2026-01-19T10:30:00Z"
  }
}

Error - Duplicate Code:

{
  "isSuccessful": false,
  "message": "ObjectDefinition with code 'loan_credit_assessment' already exists."
}

UpdateObjectDefinitionCommand

Update an existing Object Definition.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "id": 45,
  "code": "loan_credit_assessment_v2",
  "name": "Loan Credit Assessment Form (Enhanced)",
  "description": "Enhanced credit scoring template with additional fields",
  "schemaJson": "{\"type\":\"object\",\"properties\":{\"creditScore\":{\"type\":\"number\"},\"riskRating\":{\"type\":\"string\"},\"comments\":{\"type\":\"string\"}}}",
  "condition": "loan.amount > 5000",
  "clientScript": "if (data.creditScore < 600) { showWarning('High Risk'); highlightField('riskRating'); }",
  "allowsMultipleInstances": true,
  "maxInstancesAllowed": 3,
  "isActive": true
}

Request Fields

Field	Type	Required	Description
`id`	long	Yes	ID of Object Definition to update
`code`	string	No	Updated unique code
`name`	string	No	Updated display name
`formId`	long	No	Updated form template ID
`description`	string	No	Updated description
`schemaJson`	string	No	Updated JSON Schema
`condition`	string	No	Updated conditional logic
`clientScript`	string	No	Updated client script
`allowsMultipleInstances`	bool	No	Updated multiple instances flag
`maxInstancesAllowed`	int	No	Updated maximum instances
`isActive`	bool	No	Updated active status

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinition updated successfully",
  "data": {
    "id": 45,
    "code": "loan_credit_assessment_v2",
    "name": "Loan Credit Assessment Form (Enhanced)",
    "version": 2,
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

DeleteObjectDefinitionCommand

Delete an Object Definition.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "id": 45,
  "deleteInstances": false
}

Request Fields

Field	Type	Required	Default	Description
`id`	long	Yes	-	ID of Object Definition to delete
`deleteInstances`	bool	No	false	Also delete all instances

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinition deleted successfully"
}

Error - Has Active Instances:

{
  "isSuccessful": false,
  "message": "Cannot delete ObjectDefinition with active instances. Set deleteInstances=true to force delete."
}

GetObjectDefinitionByIdQuery

Retrieve a specific Object Definition by ID.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "id": 45
}

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinition retrieved successfully",
  "data": {
    "id": 45,
    "code": "loan_credit_assessment",
    "name": "Loan Credit Assessment Form",
    "uniqueIdentifier": "obj_def_abc123xyz",
    "entityType": 3,
    "entityTypeDesc": "Loan",
    "formId": 25,
    "description": "Credit scoring and assessment template",
    "schemaJson": "{...}",
    "condition": "loan.amount > 10000",
    "clientScript": "if (data.creditScore < 600) { showWarning('High Risk'); }",
    "allowsMultipleInstances": false,
    "maxInstancesAllowed": null,
    "version": 1,
    "isActive": true,
    "createdAt": "2026-01-19T10:30:00Z",
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

GetObjectDefinitionByCodeQuery

Retrieve a specific Object Definition by its unique code.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "code": "loan_credit_assessment"
}

Response

Same format as GetObjectDefinitionByIdQuery.

ListObjectDefinitionsQuery

Retrieve a filtered and paginated list of Object Definitions.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "entityType": 3,
  "isActive": true,
  "pageIndex": 0,
  "pageSize": 20
}

Request Fields

Field	Type	Required	Default	Description
`entityType`	int	No	null	Filter by entity type
`isActive`	bool	No	null	Filter by active status
`pageIndex`	int	No	0	Page index (0-based)
`pageSize`	int	No	20	Results per page

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitions retrieved successfully",
  "data": {
    "items": [
      {
        "id": 45,
        "code": "loan_credit_assessment",
        "name": "Loan Credit Assessment Form",
        "entityType": 3,
        "entityTypeDesc": "Loan",
        "description": "Credit scoring template",
        "allowsMultipleInstances": false,
        "isActive": true,
        "createdAt": "2026-01-19T10:30:00Z"
      },
      {
        "id": 46,
        "code": "loan_collateral_checklist",
        "name": "Collateral Verification Checklist",
        "entityType": 3,
        "entityTypeDesc": "Loan",
        "description": "Collateral verification template",
        "allowsMultipleInstances": true,
        "isActive": true,
        "createdAt": "2026-01-19T09:15:00Z"
      }
    ],
    "totalCount": 42,
    "pageIndex": 0,
    "pageSize": 20,
    "totalPages": 3
  }
}

GetAvailableObjectDefinitionsForEntityQuery

Get Object Definitions available for a specific entity based on conditions.

File: CB.Administration.Api/Commands/BPM/ObjectDefinition/ObjectDefinitionCommands.cs

Request

{
  "entityType": 3,
  "entityId": 12345,
  "entityContext": {
    "amount": 1500000,
    "currency": "NGN",
    "loanType": "personal",
    "status": "pending"
  }
}

Request Fields

Field	Type	Required	Description
`entityType`	int	Yes	Entity type
`entityId`	long	Yes	Entity ID
`entityContext`	object	Yes	Entity data for condition evaluation

Response

Success:

{
  "isSuccessful": true,
  "message": "Available ObjectDefinitions retrieved successfully",
  "data": [
    {
      "id": 45,
      "code": "loan_credit_assessment",
      "name": "Loan Credit Assessment Form",
      "description": "Credit scoring template",
      "conditionMet": true,
      "condition": "loan.amount > 10000"
    },
    {
      "id": 47,
      "code": "high_value_loan_checklist",
      "name": "High Value Loan Checklist",
      "description": "Additional checks for high value loans",
      "conditionMet": true,
      "condition": "loan.amount > 1000000"
    }
  ]
}

Entity Types

Type	Value	Description	Common Forms
Customer	1	Customer/Client entities	KYC forms, Identity verification, Credit assessment
Account	2	Account entities	Account opening forms, Maintenance checklists
Loan	3	Loan applications	Credit assessment, Collateral forms, Approval checklists
Transaction	4	Transaction data	Transaction verification, Audit forms

JSON Schema Format

Object Definitions use JSON Schema for field structure:

Simple Example

{
  "type": "object",
  "properties": {
    "creditScore": {
      "type": "number",
      "minimum": 300,
      "maximum": 850,
      "description": "FICO credit score"
    },
    "riskRating": {
      "type": "string",
      "enum": ["Low", "Medium", "High", "Critical"],
      "description": "Risk assessment rating"
    },
    "assessmentDate": {
      "type": "string",
      "format": "date",
      "description": "Date of assessment"
    }
  },
  "required": ["creditScore", "riskRating"]
}

Complex Example

{
  "type": "object",
  "properties": {
    "personalInfo": {
      "type": "object",
      "properties": {
        "firstName": {"type": "string", "minLength": 2},
        "lastName": {"type": "string", "minLength": 2},
        "dateOfBirth": {"type": "string", "format": "date"}
      },
      "required": ["firstName", "lastName"]
    },
    "employmentInfo": {
      "type": "object",
      "properties": {
        "employer": {"type": "string"},
        "position": {"type": "string"},
        "monthlyIncome": {"type": "number", "minimum": 0}
      }
    },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "documentType": {"type": "string"},
          "documentNumber": {"type": "string"},
          "expiryDate": {"type": "string", "format": "date"}
        }
      }
    }
  }
}

Supported Field Types

string - Text fields
number - Numeric values (decimal)
integer - Whole numbers
boolean - True/false
array - Lists of values
object - Nested structures
null - Nullable fields

Conditional Visibility

Object Definitions can be shown/hidden based on runtime conditions.

Examples

Show for High Value Loans:

{
  "code": "high_value_loan_assessment",
  "condition": "loan.amount > 1000000 && loan.currency === 'NGN'"
}

Show for Low Credit Score:

{
  "code": "additional_guarantor_form",
  "condition": "customer.creditScore < 600"
}

Complex Conditions:

{
  "code": "corporate_loan_checklist",
  "condition": "(loan.loanType === 'corporate' || loan.amount > 5000000) && loan.collateral !== null"
}

Evaluation Context

The entity object is available in conditions:

// For Loan entities
loan.amount
loan.currency
loan.loanType
loan.status
loan.customerId

// For Customer entities
customer.firstName
customer.creditScore
customer.kycStatus
customer.accountAge

// For Account entities
account.balance
account.accountType
account.status

// For Transaction entities
transaction.amount
transaction.transactionType
transaction.status

Client Scripts

Add dynamic behavior to forms with JavaScript.

Available Functions

// Field visibility
showField('fieldName')
hideField('fieldName')

// Field requirements
requireField('fieldName')
optionalField('fieldName')

// User feedback
showWarning('message')
showError('message')
showInfo('message')

// Field highlighting
highlightField('fieldName')
unhighlightField('fieldName')

// Data access
data.fieldName  // Current form values

Examples

Dynamic Field Visibility:

if (data.loanType === 'mortgage') {
  showField('propertyValue');
  showField('propertyAddress');
  requireField('propertyValue');
} else {
  hideField('propertyValue');
  hideField('propertyAddress');
}

Calculations:

// Calculate monthly payment
if (data.loanAmount && data.interestRate && data.loanTerm) {
  var monthlyRate = data.interestRate / 12 / 100;
  var numPayments = data.loanTerm * 12;
  data.monthlyPayment = (data.loanAmount * monthlyRate * Math.pow(1 + monthlyRate, numPayments)) / 
                        (Math.pow(1 + monthlyRate, numPayments) - 1);
}

Validation:

if (data.creditScore < 600) {
  showWarning('Customer has low credit score - additional guarantor required');
  requireField('guarantorDetails');
  highlightField('guarantorDetails');
}

if (data.debtToIncomeRatio > 0.43) {
  showError('Debt-to-income ratio exceeds maximum allowed (43%)');
  requireField('additionalIncomeSource');
}

Multiple Instances

Allow multiple instances of the same definition per entity.

Configuration

{
  "code": "loan_guarantor",
  "name": "Loan Guarantor Information",
  "allowsMultipleInstances": true,
  "maxInstancesAllowed": 3
}

Use Cases

Multiple Guarantors - Up to 3 guarantors per loan
Multiple Collateral Items - Multiple assets as collateral
Multiple References - Several personal/professional references
Multiple Addresses - Multiple contact addresses

Entity Types Reference

The entityType field determines which business entity an Object Definition can be attached to. Use the integer value when creating or filtering definitions.

Core Banking Entities

Value	Alias	Description	Use Cases
`0`	`none`	Not Associated	System-level or unattached forms
`1`	`entity`	Generic Entity	Basic entity type when no specific type needed
`2`	`contact`	Contact	Customer contact information, KYC forms
`3`	`loan`	Loan	Loan applications, credit assessments, collateral
`4`	`deposit`	Deposit	Account opening forms, deposit agreements
`5`	`insurancePolicy`	Insurance Policy	Policy forms, coverage details
`6`	`insuranceClaim`	Insurance Claims	Claim submission, assessment forms
`11`	`transaction`	Transaction	Transaction approvals, audit trails

Channel Entities

Value	Alias	Description	Use Cases
`100`	`customerRegistration`	Customer	Customer onboarding, registration forms
`101`	`loanRequest`	Loan Request	Online loan applications, quote requests
`102`	`transferRequest`	Transfer Request	Transfer approvals, verification
`103`	`billsPaymentRequest`	Bills Payment Request	Payment confirmations, receipts
`104`	`airtimeRechargeRequest`	Airtime Recharge Request	Recharge transactions
`105`	`dataRechargeRequest`	Data Recharge Request	Data bundle purchases

Operations Entities

Value	Alias	Description	Use Cases
`200`	`reconciliation`	Reconciliation	Reconciliation reports, variance forms
`13`	`teller`	Teller Transaction	Teller approval forms, transaction logs
`14`	`inwardTransaction`	Inward Transaction	Incoming transaction processing

System Entities

Value	Alias	Description	Use Cases
`15`	`scheduledProcess`	Scheduled Process	Automated process forms, scheduled tasks

Examples

Loan Credit Assessment:

{
  "code": "loan_credit_assessment",
  "name": "Loan Credit Assessment Form",
  "entityType": 3,  // Loan entity
  "description": "Credit scoring and risk assessment for loan applications"
}

Customer KYC:

{
  "code": "customer_kyc_verification",
  "name": "Customer KYC Verification",
  "entityType": 2,  // Contact entity
  "description": "Know Your Customer verification form"
}

Transfer Approval:

{
  "code": "transfer_approval_checklist",
  "name": "Transfer Approval Checklist",
  "entityType": 102,  // Transfer Request entity
  "description": "Approval checklist for transfer requests"
}

Best Practices

1. Code Naming Convention

Use hierarchical, descriptive codes:

entity_category_purpose

Examples:

loan_kyc_identity_verification
customer_credit_score_card
account_compliance_audit_checklist

2. Schema Design

✅ DO:

Use clear, descriptive field names
Add description to all fields
Set appropriate validation rules
Use enums for fixed value lists

❌ DON'T:

Use abbreviations without context
Skip required field definitions
Create overly nested structures

3. Conditional Logic

✅ DO:

Keep conditions simple and readable
Test conditions thoroughly
Document condition logic

❌ DON'T:

Create complex nested conditions
Use conditions for business logic (use workflows instead)
Reference unavailable properties

4. Client Scripts

✅ DO:

Keep scripts focused and modular
Handle errors gracefully
Test all code paths

❌ DON'T:

Make API calls from client scripts
Modify system data directly
Create performance bottlenecks

Error Handling

Common Errors

Duplicate Code:

{
  "isSuccessful": false,
  "message": "ObjectDefinition with code 'loan_credit_assessment' already exists."
}

Invalid Entity Type:

{
  "isSuccessful": false,
  "message": "Invalid entity type: 99. See Entity Types Reference for valid values."
}

Invalid JSON Schema:

{
  "isSuccessful": false,
  "message": "Invalid JSON Schema: Expected 'properties' field"
}

Form Not Found:

{
  "isSuccessful": false,
  "message": "Form with ID 25 not found."
}

Overview​

What are Object Definitions?​

Common Use Cases​

Commands Reference​

CreateObjectDefinitionCommand​

Request​

Request Fields​

Response​

UpdateObjectDefinitionCommand​

Request​

Request Fields​

Response​

DeleteObjectDefinitionCommand​

Request​

Request Fields​

Response​

GetObjectDefinitionByIdQuery​

Request​

Response​

GetObjectDefinitionByCodeQuery​

Request​

Response​

ListObjectDefinitionsQuery​

Request​

Request Fields​

Response​

GetAvailableObjectDefinitionsForEntityQuery​

Request​

Request Fields​

Response​

Entity Types​

JSON Schema Format​

Simple Example​

Complex Example​

Supported Field Types​

Conditional Visibility​

Examples​

Evaluation Context​

Client Scripts​

Available Functions​

Examples​

Multiple Instances​

Configuration​

Use Cases​

Entity Types Reference​

Core Banking Entities​

Channel Entities​

Operations Entities​

System Entities​

Examples​

Best Practices​

1. Code Naming Convention​

2. Schema Design​

3. Conditional Logic​

4. Client Scripts​

Error Handling​

Common Errors​

See Also​

Overview

What are Object Definitions?

Common Use Cases

Commands Reference

CreateObjectDefinitionCommand

Request

Request Fields

Response

UpdateObjectDefinitionCommand

Request

Request Fields

Response

DeleteObjectDefinitionCommand

Request

Request Fields

Response

GetObjectDefinitionByIdQuery

Request

Response

GetObjectDefinitionByCodeQuery

Request

Response

ListObjectDefinitionsQuery

Request

Request Fields

Response

GetAvailableObjectDefinitionsForEntityQuery

Request

Request Fields

Response

Entity Types

JSON Schema Format

Simple Example

Complex Example

Supported Field Types

Conditional Visibility

Examples

Evaluation Context

Client Scripts

Available Functions

Examples

Multiple Instances

Configuration

Use Cases

Entity Types Reference

Core Banking Entities

Channel Entities

Operations Entities

System Entities

Examples

Best Practices

1. Code Naming Convention

2. Schema Design

3. Conditional Logic

4. Client Scripts

Error Handling

Common Errors

See Also