RenameProcessDefinitionCommand

Overview

Renames a process definition without creating a new version.

Purpose

Changes the display name of a process definition while keeping the same ID and version. Use this for cosmetic naming changes that don't affect functionality.

Command Type

CB.Administration.Api.Commands.BPM.Process.RenameProcessDefinitiionCommand

Request

{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": {
    "id": 456,
    "newName": "SME Loan Approval Workflow"
  }
}

Request Fields (data object)

Field	Type	Required	Description
`id`	long	Yes	ID of process definition to rename
`newName`	string	Yes	New name for the process (must be unique)

Response

{
  "isSuccessful": true,
  "message": "Process definition renamed successfully",
  "statusCode": "00",
  "data": {
    "id": 456,
    "oldName": "Loan Approval Workflow",
    "newName": "SME Loan Approval Workflow",
    "version": 2,
    "versionUnchanged": true
  }
}

Response Fields

Field	Type	Description
`id`	long	Process definition ID
`oldName`	string	Previous name
`newName`	string	New name
`version`	int	Version number (unchanged)
`versionUnchanged`	boolean	Indicates no version increment occurred

Error Responses

Process Not Found

{
  "isSuccessful": false,
  "message": "Process definition with ID 456 not found",
  "statusCode": "404"
}

Duplicate Name

{
  "isSuccessful": false,
  "message": "Process definition with name 'SME Loan Approval Workflow' already exists",
  "statusCode": "40",
  "data": {
    "existingProcessId": 789,
    "suggestion": "Choose a different name or update the existing process"
  }
}

Invalid Name

{
  "isSuccessful": false,
  "message": "Invalid process name: Name cannot be empty or whitespace only",
  "statusCode": "40"
}

When to Use This Command

✅ Use RenameProcessDefinitionCommand When:

Fixing Typos

{
  "id": 456,
  "newName": "Loan Approval Workflow"  // Fixed "Apprval" typo
}

Clarifying Names

{
  "id": 456,
  "newName": "SME Loan Approval Workflow"  // Added "SME" for clarity
}

Adding Context

{
  "id": 456,
  "newName": "Loan Approval Workflow - Above 5M"  // Added threshold
}

Standardizing Naming Conventions

{
  "id": 456,
  "newName": "[LENDING] Loan Approval Workflow"  // Added category prefix
}

❌ Use UpdateProcessDefinitionCommand Instead When:

Changing BPMN Logic
Modifying Task Definitions
Updating Process Variables
Changing Trigger Events
Updating Context Loaders
Any Functional Changes

Comparison: Rename vs Update

Aspect	RenameProcessDefinitionCommand	UpdateProcessDefinitionCommand
Version	No version increment	Creates new version
BPMN XML	Unchanged	Can be updated
Active Instances	Unaffected	Continue with old version
Configuration	Unchanged	Can be updated
Use Case	Cosmetic name changes	Functional changes
Speed	Fast (metadata only)	Slower (validation required)

Impact on System

What Changes

✅ Process definition name in database
✅ Display name in UI
✅ Search results
✅ API responses

What Stays the Same

✅ Process definition ID
✅ Version number
✅ BPMN XML
✅ Active instances
✅ Completed instances
✅ Historical data
✅ Trigger events
✅ Context loaders
✅ Scheduled executions

Example Scenarios

Scenario 1: Standardizing Names

Before:

Process 123: "loan approval"
Process 456: "LOAN APPROVAL WORKFLOW"
Process 789: "Loan_Approval_Process"

Standardize:

POST /api/process-definitions/123/rename
{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": { "newName": "[LENDING] Loan Approval Workflow" }
}

POST /api/process-definitions/456/rename
{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": { "newName": "[LENDING] Loan Approval Workflow - High Value" }
}

POST /api/process-definitions/789/rename
{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": { "newName": "[LENDING] Loan Approval Workflow - Standard" }
}

After:

Process 123: "[LENDING] Loan Approval Workflow"
Process 456: "[LENDING] Loan Approval Workflow - High Value"
Process 789: "[LENDING] Loan Approval Workflow - Standard"

Scenario 2: Adding Business Context

Original:

"Account Opening Workflow"

Renamed for Clarity:

{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": {
    "id": 456,
    "newName": "Account Opening Workflow - Corporate Customers Only"
  }
}

Result: Team members immediately understand the process scope without opening documentation.

Scenario 3: Versioning in Name

Some teams prefer version numbers in names:

# Version 1
{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": { "newName": "Credit Check Workflow v1.0" }
}

# Later update BPMN (version increments to 2)
POST /api/process-definitions/456
{
  "cmd": "UpdateProcessDefinitiionCommand",
  "data": { "bpmnXml": "..." }
}  # Version becomes 2

# Rename to match
POST /api/process-definitions/456/rename
{
  "cmd": "RenameProcessDefinitiionCommand",
  "data": { "newName": "Credit Check Workflow v2.0" }
}

Best Practices

✅ Do's

Use Consistent Naming Convention

[CATEGORY] Process Name - Variant

Examples:
[LENDING] Loan Approval Workflow - SME
[DEPOSITS] Account Opening Workflow - Savings
[COMPLIANCE] KYC Verification Workflow - Enhanced

Include Key Identifiers

✅ "Loan Approval - Above 5M"
✅ "Account Opening - Corporate"
✅ "KYC Check - High Risk"

Keep Names Concise But Descriptive

✅ "SME Loan Approval Workflow"
❌ "Small and Medium Enterprise Loan Approval Process for amounts exceeding..."

Document Name Changes

// After renaming, update metadata
{
  "id": 456,
  "metadata": {
    "nameHistory": [
      { "name": "Loan Approval", "date": "2025-01-01" },
      { "name": "SME Loan Approval Workflow", "date": "2026-01-06" }
    ]
  }
}

❌ Don'ts

Don't use ambiguous names

❌ "Process1"
❌ "Workflow"
❌ "New Process"

Don't include version numbers if using auto-versioning

❌ "Loan Approval v1.0" (version is tracked automatically)
✅ "Loan Approval Workflow" (let system track versions)

Don't rename frequently
- Causes confusion for users
- Makes audit trails harder to follow
- Breaks bookmarks/references

Don't use special characters

❌ "Loan Approval <CRITICAL>"
❌ "Account Opening [NEW!]"
✅ "Loan Approval - Critical Priority"
✅ "Account Opening Workflow - New Version"

Naming Convention Examples

By Industry

Banking:

[LENDING] Personal Loan Approval
[DEPOSITS] Savings Account Opening
[CARDS] Credit Card Application
[COMPLIANCE] AML Screening

Healthcare:

[PATIENT] Patient Admission Workflow
[BILLING] Insurance Claim Processing
[PHARMACY] Prescription Fulfillment
[COMPLIANCE] HIPAA Audit

Retail:

[ORDER] Order Fulfillment Workflow
[RETURNS] Return Authorization Process
[INVENTORY] Stock Replenishment
[CUSTOMER] Customer Onboarding

By Priority/Urgency

[CRITICAL] High-Value Transaction Approval
[STANDARD] Regular Account Opening
[BATCH] End-of-Day Reconciliation
[REALTIME] Fraud Detection Workflow

By Region/Branch

[LAGOS] Loan Approval Workflow
[ABUJA] Account Opening Process
[REGIONAL] Branch Reconciliation
[HQ] Executive Approval Required

Bulk Renaming

For standardizing multiple processes:

// Pseudo-code for bulk renaming
const processes = await getProcessDefinitionList();

const renamings = [
  { id: 123, newName: "[LENDING] Loan Approval - Personal" },
  { id: 456, newName: "[LENDING] Loan Approval - SME" },
  { id: 789, newName: "[LENDING] Loan Approval - Corporate" }
];

for (const rename of renamings) {
  await renameProcessDefinition(rename);
  console.log(`Renamed ${rename.id}`);
}

Audit Trail

All rename operations are logged:

{
  "auditLog": {
    "operation": "RENAME_PROCESS_DEFINITION",
    "processId": 456,
    "oldName": "Loan Approval Workflow",
    "newName": "SME Loan Approval Workflow",
    "performedBy": "admin@bank.com",
    "timestamp": "2026-01-06T15:30:00Z",
    "reason": "Standardizing naming conventions"
  }
}

CreateProcessDefinitionCommand - Create with proper name initially
UpdateProcessDefinitionCommand - For functional changes
GetProcessDefinitionByIdQuery - View current name
GetProcessDefinitionListQuery - Search by name

Last Updated: January 6, 2026

Overview​

Purpose​

Command Type​

Request​

Request Fields (data object)​

Response​

Response Fields​

Error Responses​

Process Not Found​

Duplicate Name​

Invalid Name​

When to Use This Command​

✅ Use RenameProcessDefinitionCommand When:​

❌ Use UpdateProcessDefinitionCommand Instead When:​

Comparison: Rename vs Update​

Impact on System​

What Changes​

What Stays the Same​

Example Scenarios​

Scenario 1: Standardizing Names​

Scenario 2: Adding Business Context​

Scenario 3: Versioning in Name​

Best Practices​

✅ Do's​

❌ Don'ts​

Naming Convention Examples​

By Industry​

By Priority/Urgency​

By Region/Branch​

Bulk Renaming​

Audit Trail​

Related Commands​