Object Definition Instance Commands Reference

Overview

Object Definition Instance Commands manage individual form instances attached to business entities. While Object Definitions define the template structure, Object Definition Instances are the actual filled-out forms with data specific to a particular Loan, Customer, Account, or Transaction.

What are Object Definition Instances?

Object Definition Instances are completed forms that:

• Store Entity-Specific Data - Actual values for a specific loan, customer, etc.
• Track Version History - Record which template version was used
• Support Multiple Instances - Multiple forms per entity (e.g., multiple guarantors)
• Maintain Context - Store form data as JSON
• Enable Tracking - Use tracker IDs to group related instances

Relationship

ObjectDefinition (Template)
    ↓
ObjectDefinitionInstance (Filled Form)
    ↓
Entity (Loan #12345)

Example Flow

1. Create Template: loan_guarantor Object Definition
2. Create Instance: Fill out guarantor form for Loan #12345
3. Add Another: Create 2nd guarantor instance (trackerId="guarantor_2")
4. Update: Modify guarantor information
5. Query: Retrieve all guarantors for Loan #12345

---

Commands Reference

CreateObjectDefinitionInstanceCommand

Create a new instance of an Object Definition for a specific entity.

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

Request

{
  "objectDefinitionId": 45,
  "entityId": 12345,
  "context": "{\"creditScore\":720,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\",\"comments\":\"Excellent credit history\"}",
  "notes": "Initial credit assessment completed",
  "trackerId": null
}

Alternative - Using Code:

{
  "objectDefinitionUniqueIdentifier": "loan_credit_assessment",
  "entityId": 12345,
  "context": "{\"creditScore\":720,\"riskRating\":\"Low\"}",
  "notes": "Initial assessment"
}

Request Fields

Field	Type	Required	Default	Description
objectDefinitionId	long	One Required	-	Object Definition ID
objectDefinitionUniqueIdentifier	string	One Required	-	Object Definition code
entityId	long	Yes	-	Entity ID (loan, customer, etc.)
context	string	No	""	JSON string containing form data
notes	string	No	null	Additional notes
trackerId	string	No	null	Tracker ID for grouping instances

Note: Either objectDefinitionId OR objectDefinitionUniqueIdentifier must be provided. trackerId is required when creating multiple instances.

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstance created successfully",
  "data": {
    "id": 501,
    "objectDefinitionId": 45,
    "objectDefinitionCode": "loan_credit_assessment",
    "objectDefinitionName": "Loan Credit Assessment Form",
    "entityId": 12345,
    "context": "{\"creditScore\":720,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\"}",
    "trackerId": null,
    "objectDefinitionVersion": 1,
    "notes": "Initial credit assessment completed",
    "isActive": true,
    "createdByUserId": "user_123",
    "createdAt": "2026-01-19T10:30:00Z"
  }
}

Error - Multiple Instances Not Allowed:

{
  "isSuccessful": false,
  "message": "An active instance already exists for this entity. This ObjectDefinition does not allow multiple instances."
}

Error - Invalid JSON:

{
  "isSuccessful": false,
  "message": "Invalid JSON in context field."
}

---

UpdateObjectDefinitionInstanceCommand

Update an existing Object Definition Instance.

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

Request

{
  "id": 501,
  "context": "{\"creditScore\":730,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\",\"comments\":\"Credit score improved\"}",
  "notes": "Updated after additional income verification",
  "trackerId": "assessment_v2",
  "isActive": true
}

Request Fields

Field	Type	Required	Description
id	long	Yes	Instance ID to update
context	string	No	Updated form data (JSON string)
notes	string	No	Updated notes
trackerId	string	No	Updated tracker ID
isActive	bool	No	Updated active status

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstance updated successfully",
  "data": {
    "id": 501,
    "context": "{\"creditScore\":730,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\",\"comments\":\"Credit score improved\"}",
    "notes": "Updated after additional income verification",
    "trackerId": "assessment_v2",
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

---

DeleteObjectDefinitionInstanceCommand

Delete an Object Definition Instance.

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

Request

{
  "id": 501
}

Response

Success:

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

---

GetObjectDefinitionInstanceByIdQuery

Retrieve a specific instance by ID.

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

Request

{
  "id": 501
}

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstance retrieved successfully",
  "data": {
    "id": 501,
    "objectDefinitionId": 45,
    "objectDefinitionCode": "loan_credit_assessment",
    "objectDefinitionName": "Loan Credit Assessment Form",
    "entityId": 12345,
    "entityType": 3,
    "entityTypeDesc": "Loan",
    "context": "{\"creditScore\":720,\"riskRating\":\"Low\"}",
    "contextParsed": {
      "creditScore": 720,
      "riskRating": "Low",
      "assessmentDate": "2026-01-19",
      "comments": "Excellent credit history"
    },
    "trackerId": null,
    "objectDefinitionVersion": 1,
    "notes": "Initial credit assessment completed",
    "isActive": true,
    "createdByUserId": "user_123",
    "createdAt": "2026-01-19T10:30:00Z",
    "updatedAt": "2026-01-19T11:00:00Z"
  }
}

---

GetObjectDefinitionInstanceByTrackerIdQuery

Retrieve an instance by Tracker ID.

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

Request

{
  "trackerId": "guarantor_1",
  "entityId": 12345,
  "objectDefinitionId": 47
}

Alternative - Using Code:

{
  "trackerId": "guarantor_1",
  "entityId": 12345,
  "objectDefinitionUniqueIdentifier": "loan_guarantor"
}

Request Fields

Field	Type	Required	Description
trackerId	string	Yes	Tracker ID to search for
entityId	long	Yes	Entity ID
objectDefinitionId	long	One Required	Object Definition ID
objectDefinitionUniqueIdentifier	string	One Required	Object Definition code

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstance retrieved successfully",
  "data": {
    "id": 502,
    "objectDefinitionId": 47,
    "entityId": 12345,
    "context": "{\"firstName\":\"John\",\"lastName\":\"Doe\"}",
    "trackerId": "guarantor_1",
    "isActive": true
  }
}

---

GetObjectDefinitionInstancesByEntityQuery

Get all instances for a specific entity.

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

Request

{
  "entityId": 12345,
  "entityType": 3,
  "objectDefinitionId": 47,
  "trackerId": null,
  "includeInactive": false
}

Alternative - Using Code:

{
  "entityId": 12345,
  "entityType": 3,
  "objectDefinitionUniqueIdentifier": "loan_guarantor",
  "includeInactive": false
}

Request Fields

Field	Type	Required	Default	Description
entityId	long	Yes	-	Entity ID
entityType	int	No	null	Filter by entity type
objectDefinitionId	long	No	null	Filter by definition ID
objectDefinitionUniqueIdentifier	string	No	null	Filter by definition code
trackerId	string	No	null	Filter by tracker ID
includeInactive	bool	No	false	Include inactive instances

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstances retrieved successfully",
  "data": [
    {
      "id": 501,
      "objectDefinitionId": 45,
      "objectDefinitionCode": "loan_credit_assessment",
      "objectDefinitionName": "Loan Credit Assessment Form",
      "entityId": 12345,
      "context": "{\"creditScore\":720}",
      "trackerId": null,
      "isActive": true,
      "createdAt": "2026-01-19T10:30:00Z"
    },
    {
      "id": 502,
      "objectDefinitionId": 47,
      "objectDefinitionCode": "loan_guarantor",
      "objectDefinitionName": "Loan Guarantor Information",
      "entityId": 12345,
      "context": "{\"firstName\":\"John\",\"lastName\":\"Doe\"}",
      "trackerId": "guarantor_1",
      "isActive": true,
      "createdAt": "2026-01-19T10:45:00Z"
    },
    {
      "id": 503,
      "objectDefinitionId": 47,
      "objectDefinitionCode": "loan_guarantor",
      "objectDefinitionName": "Loan Guarantor Information",
      "entityId": 12345,
      "context": "{\"firstName\":\"Jane\",\"lastName\":\"Smith\"}",
      "trackerId": "guarantor_2",
      "isActive": true,
      "createdAt": "2026-01-19T11:00:00Z"
    }
  ]
}

---

GetObjectDefinitionInstancesByDefinitionQuery

Get all instances for a specific Object Definition.

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

Request

{
  "objectDefinitionId": 47,
  "trackerId": null,
  "includeInactive": false,
  "pageIndex": 0,
  "pageSize": 20
}

Alternative - Using Code:

{
  "objectDefinitionUniqueIdentifier": "loan_guarantor",
  "includeInactive": false,
  "pageIndex": 0,
  "pageSize": 20
}

Request Fields

Field	Type	Required	Default	Description
objectDefinitionId	long	One Required	-	Object Definition ID
objectDefinitionUniqueIdentifier	string	One Required	-	Object Definition code
trackerId	string	No	null	Filter by tracker ID
includeInactive	bool	No	false	Include inactive instances
pageIndex	int	No	0	Page index (0-based)
pageSize	int	No	20	Results per page

Response

Success:

{
  "isSuccessful": true,
  "message": "ObjectDefinitionInstances retrieved successfully",
  "data": {
    "items": [
      {
        "id": 502,
        "entityId": 12345,
        "entityType": 3,
        "context": "{\"firstName\":\"John\",\"lastName\":\"Doe\"}",
        "trackerId": "guarantor_1",
        "isActive": true,
        "createdAt": "2026-01-19T10:45:00Z"
      },
      {
        "id": 503,
        "entityId": 12345,
        "entityType": 3,
        "context": "{\"firstName\":\"Jane\",\"lastName\":\"Smith\"}",
        "trackerId": "guarantor_2",
        "isActive": true,
        "createdAt": "2026-01-19T11:00:00Z"
      },
      {
        "id": 504,
        "entityId": 67890,
        "entityType": 3,
        "context": "{\"firstName\":\"Bob\",\"lastName\":\"Johnson\"}",
        "trackerId": "guarantor_1",
        "isActive": true,
        "createdAt": "2026-01-19T11:15:00Z"
      }
    ],
    "totalCount": 156,
    "pageIndex": 0,
    "pageSize": 20,
    "totalPages": 8
  }
}

---

Tracker IDs

Tracker IDs help organize multiple instances per entity.

Use Cases

Multiple Guarantors:

{
  "objectDefinitionUniqueIdentifier": "loan_guarantor",
  "entityId": 12345,
  "trackerId": "guarantor_1",
  "context": "{\"firstName\":\"John\",\"lastName\":\"Doe\"}"
}

{
  "objectDefinitionUniqueIdentifier": "loan_guarantor",
  "entityId": 12345,
  "trackerId": "guarantor_2",
  "context": "{\"firstName\":\"Jane\",\"lastName\":\"Smith\"}"
}

Multiple Collateral Items:

{
  "objectDefinitionUniqueIdentifier": "loan_collateral",
  "entityId": 12345,
  "trackerId": "collateral_property",
  "context": "{\"type\":\"Real Estate\",\"value\":5000000}"
}

{
  "objectDefinitionUniqueIdentifier": "loan_collateral",
  "entityId": 12345,
  "trackerId": "collateral_vehicle",
  "context": "{\"type\":\"Vehicle\",\"value\":2000000}"
}

Benefits

• ✅ Easily identify specific instances
• ✅ Group related instances
• ✅ Enable targeted updates
• ✅ Simplify querying

---

Context Format

The context field stores form data as a JSON string.

Simple Context

{
  "context": "{\"creditScore\":720,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\"}"
}

Complex Context

{
  "context": "{\"personalInfo\":{\"firstName\":\"John\",\"lastName\":\"Doe\",\"dateOfBirth\":\"1985-05-15\"},\"employmentInfo\":{\"employer\":\"ABC Corp\",\"position\":\"Manager\",\"monthlyIncome\":500000},\"documents\":[{\"documentType\":\"ID Card\",\"documentNumber\":\"ID123456\",\"expiryDate\":\"2030-12-31\"},{\"documentType\":\"Passport\",\"documentNumber\":\"A1234567\",\"expiryDate\":\"2028-06-30\"}]}"
}

Parsed Context

Responses include contextParsed for easy consumption:

{
  "context": "{\"creditScore\":720}",
  "contextParsed": {
    "creditScore": 720,
    "riskRating": "Low"
  }
}

---

Version Tracking

Instances track which template version was used.

Example

{
  "objectDefinitionVersion": 1,
  "objectDefinitionId": 45,
  "createdAt": "2026-01-19T10:30:00Z"
}

Benefits:

• Data Integrity - Know which template structure was used
• Migration Support - Handle template updates gracefully
• Audit Trail - Track template changes over time

---

Best Practices

1. Use Tracker IDs for Multiple Instances

✅ GOOD:

{
  "trackerId": "guarantor_1",
  "context": "{\"firstName\":\"John\"}"
}

❌ BAD:

{
  "trackerId": null,
  "context": "{\"guarantorNumber\":1,\"firstName\":\"John\"}"
}

2. Structure Context Data Properly

✅ GOOD:

{
  "context": "{\"personalInfo\":{\"firstName\":\"John\",\"lastName\":\"Doe\"},\"contactInfo\":{\"email\":\"john@example.com\"}}"
}

❌ BAD:

{
  "context": "{\"field1\":\"John\",\"field2\":\"Doe\",\"field3\":\"john@example.com\"}"
}

3. Add Meaningful Notes

✅ GOOD:

{
  "notes": "Initial credit assessment - submitted by loan officer Mary Jane on 2026-01-19"
}

❌ BAD:

{
  "notes": "Done"
}

4. Validate JSON Before Submitting

Always validate your context JSON:

// Good practice
try {
  JSON.parse(contextString);
  // Proceed with submission
} catch (error) {
  // Handle invalid JSON
}

---

Integration Examples

Example 1: Create Credit Assessment

POST /api/commands/execute
{
  "commandName": "CreateObjectDefinitionInstanceCommand",
  "data": {
    "objectDefinitionUniqueIdentifier": "loan_credit_assessment",
    "entityId": 12345,
    "context": "{\"creditScore\":720,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\",\"comments\":\"Excellent credit history, approved for high value loans\"}",
    "notes": "Initial assessment completed by credit officer"
  }
}

Example 2: Add Multiple Guarantors

// First guarantor
POST /api/commands/execute
{
  "commandName": "CreateObjectDefinitionInstanceCommand",
  "data": {
    "objectDefinitionUniqueIdentifier": "loan_guarantor",
    "entityId": 12345,
    "trackerId": "guarantor_1",
    "context": "{\"firstName\":\"John\",\"lastName\":\"Doe\",\"relationship\":\"Brother\",\"phoneNumber\":\"08012345678\",\"address\":\"123 Lagos Street\"}",
    "notes": "Primary guarantor"
  }
}

// Second guarantor
POST /api/commands/execute
{
  "commandName": "CreateObjectDefinitionInstanceCommand",
  "data": {
    "objectDefinitionUniqueIdentifier": "loan_guarantor",
    "entityId": 12345,
    "trackerId": "guarantor_2",
    "context": "{\"firstName\":\"Jane\",\"lastName\":\"Smith\",\"relationship\":\"Friend\",\"phoneNumber\":\"08087654321\",\"address\":\"456 Abuja Avenue\"}",
    "notes": "Secondary guarantor"
  }
}

Example 3: Update Instance Data

POST /api/commands/execute
{
  "commandName": "UpdateObjectDefinitionInstanceCommand",
  "data": {
    "id": 501,
    "context": "{\"creditScore\":730,\"riskRating\":\"Low\",\"assessmentDate\":\"2026-01-19\",\"comments\":\"Credit score improved after debt consolidation\"}",
    "notes": "Updated after additional income verification and debt consolidation"
  }
}

Example 4: Query Entity Instances

POST /api/commands/execute
{
  "commandName": "GetObjectDefinitionInstancesByEntityQuery",
  "data": {
    "entityId": 12345,
    "entityType": 3,
    "includeInactive": false
  }
}

---

Error Handling

Common Errors

Instance Not Found:

{
  "isSuccessful": false,
  "message": "ObjectDefinitionInstance with ID 501 not found."
}

Multiple Instances Not Allowed:

{
  "isSuccessful": false,
  "message": "An active instance already exists for this entity. This ObjectDefinition does not allow multiple instances."
}

Max Instances Exceeded:

{
  "isSuccessful": false,
  "message": "Cannot create instance: Maximum of 3 instances allowed for this definition"
}

Invalid JSON in Context:

{
  "isSuccessful": false,
  "message": "Invalid JSON in context field."
}

Object Definition Not Found:

{
  "isSuccessful": false,
  "message": "ObjectDefinition with ID 45 not found."
}

Tracker ID Required:

{
  "isSuccessful": false,
  "message": "TrackerId is required when creating multiple instances of this ObjectDefinition."
}

---

See Also

• Object Definition Commands - Creating and managing templates
• Process Administration - Process definitions
• User Task Configuration - Attaching forms to tasks

---

Last Updated: January 19, 2026
Version: 1.0