GetProcessDefinitionListQuery

Overview

Retrieves a paginated list of process definitions with filtering, searching, and sorting capabilities.

Purpose

Lists all process definitions in the system with flexible querying options for finding and organizing workflows.

Command Type

CB.Administration.Api.Commands.BPM.Process.GetProcessDefinitiionListQuery

---

Request

{
  "cmd": "GetProcessDefinitiionListQuery",
  "data": {
    "pageNumber": 1,
    "pageSize": 20,
    "searchText": "loan",
    "category": "Lending",
    "isActive": true,
    "sortBy": "name",
    "sortDirection": "asc"
  }
}

---

Request Fields (data object)

Field	Type	Required	Default	Description
pageNumber	int	No	1	Page number (1-based indexing)
pageSize	int	No	20	Items per page (max 100)
searchText	string	No	null	Search in name and description
category	string	No	null	Filter by category
isActive	boolean	No	null	Filter by active status (null = all)
sortBy	string	No	"name"	Sort field: name, category, createdDate, version, updatedDate
sortDirection	string	No	"asc"	Sort direction: asc or desc

---

Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "data": {
    "items": [
      {
        "id": 456,
        "name": "Loan Approval Workflow",
        "description": "Multi-stage loan approval process",
        "category": "Lending",
        "version": 2,
        "isActive": true,
        "createdDate": "2026-01-06T10:30:00Z",
        "updatedDate": "2026-01-10T15:45:00Z",
        "triggerEvents": ["OnLoanCreation"],
        "contextLoaderType": "LoanApplicationContext",
        "activeInstanceCount": 5,
        "totalInstanceCount": 150
      },
      {
        "id": 789,
        "name": "SME Loan Processing",
        "description": "Automated SME loan processing",
        "category": "Lending",
        "version": 1,
        "isActive": true,
        "createdDate": "2026-01-08T14:20:00Z",
        "updatedDate": null,
        "triggerEvents": [],
        "contextLoaderType": null,
        "activeInstanceCount": 0,
        "totalInstanceCount": 0
      }
    ],
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 3,
    "totalRecords": 45,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

---

Response Fields

Pagination Metadata

Field	Type	Description
pageNumber	int	Current page number
pageSize	int	Items per page
totalPages	int	Total number of pages
totalRecords	int	Total number of matching records
hasNextPage	boolean	Whether next page exists
hasPreviousPage	boolean	Whether previous page exists

Item Fields

Field	Type	Description
id	long	Process definition ID
name	string	Process name
description	string	Process description
category	string	Logical category
version	int	Current version
isActive	boolean	Active status
createdDate	datetime	Creation timestamp
updatedDate	datetime	Last update timestamp (null if never updated)
triggerEvents	array	Configured trigger events
contextLoaderType	string	Context loader type (null if none)
activeInstanceCount	int	Number of currently active instances
totalInstanceCount	int	Total instances ever created

---

Query Examples

1. Get All Active Processes

{
  "isActive": true,
  "pageSize": 100
}

2. Search by Name or Description

{
  "searchText": "approval",
  "isActive": true
}

Matches:

• "Loan Approval Workflow"
• "Account Approval Process"
• "Process requiring manager approval" (in description)

3. Get Processes by Category

{
  "category": "Compliance",
  "sortBy": "createdDate",
  "sortDirection": "desc"
}

4. Get Recently Updated Processes

{
  "sortBy": "updatedDate",
  "sortDirection": "desc",
  "pageSize": 10
}

5. Find Inactive Processes

{
  "isActive": false,
  "sortBy": "name"
}

6. Paginate Through All Processes

// Page 1
{ "pageNumber": 1, "pageSize": 20 }

// Page 2
{ "pageNumber": 2, "pageSize": 20 }

// etc.

---

Filtering Logic

Search Text Behavior

The searchText parameter performs case-insensitive search across:

• ✅ Process definition name
• ✅ Process definition description

{ "searchText": "loan" }

Matches:

• Name: "Loan Approval Workflow"
• Name: "SME Loan Processing"
• Description: "Process for loan applications"

Category Filtering

Exact match (case-sensitive):

{ "category": "Lending" }

Matches: Category = "Lending"
Does NOT Match: Category = "lending" or "LENDING"

Active Status Filtering

{ "isActive": true }   // Only active processes
{ "isActive": false }  // Only inactive processes
{ }                    // All processes (isActive omitted)

---

Sorting Options

Available Sort Fields

Field	Description	Example
name	Alphabetical by name	A-Z or Z-A
category	Alphabetical by category	Compliance → Lending
createdDate	By creation timestamp	Oldest → Newest
updatedDate	By update timestamp	Recently updated first
version	By version number	V1 → V2 → V3

Sort Direction

• asc - Ascending (A-Z, 0-9, oldest first)
• desc - Descending (Z-A, 9-0, newest first)

---

Pagination Best Practices

✅ Recommended Approach

async function getAllProcesses() {
  const allProcesses = [];
  let pageNumber = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await getProcessDefinitionList({
      pageNumber,
      pageSize: 50  // Efficient batch size
    });
    
    allProcesses.push(...response.data.items);
    hasMore = response.data.hasNextPage;
    pageNumber++;
  }
  
  return allProcesses;
}

❌ Anti-Patterns

1. Don't use pageSize > 100

   { "pageSize": 1000 }  // ❌ Will be capped at 100

2. Don't fetch all at once without pagination

   { "pageSize": 999999 }  // ❌ Performance issue

3. Don't use 0-based page numbers

   { "pageNumber": 0 }  // ❌ Use pageNumber: 1

---

Example: Building a Process Dashboard

// Get summary by category
async function getProcessSummary() {
  const categories = ['Lending', 'Deposits', 'Compliance', 'Operations'];
  const summary = {};
  
  for (const category of categories) {
    const response = await getProcessDefinitionList({
      cmd: "GetProcessDefinitiionListQuery",
      data: {
        category,
        pageSize: 100
      }
    });
    
    summary[category] = {
      total: response.data.totalRecords,
      active: response.data.items.filter(p => p.isActive).length,
      inactive: response.data.items.filter(p => !p.isActive).length,
      withActiveInstances: response.data.items.filter(p => p.activeInstanceCount > 0).length
    };
  }
  
  return summary;
}

// Output:
// {
//   "Lending": {
//     "total": 15,
//     "active": 12,
//     "inactive": 3,
//     "withActiveInstances": 8
//   },
//   ...
// }

---

Example: Process Search UI

// Search processes as user types
async function searchProcesses(searchTerm, filters) {
  return await getProcessDefinitionList({
    cmd: "GetProcessDefinitiionListQuery",
    data: {
      searchText: searchTerm,
      isActive: filters.activeOnly ? true : null,
      category: filters.category || null,
      sortBy: 'name',
      pageNumber: filters.page || 1,
      pageSize: 20
    }
  });
}

// Usage:
const results = await searchProcesses('approval', {
  activeOnly: true,
  category: 'Lending',
  page: 1
});

console.log(`Found ${results.data.totalRecords} processes`);
results.data.items.forEach(p => {
  console.log(`- ${p.name} (v${p.version}) - ${p.activeInstanceCount} active`);
});

---

Performance Considerations

Query Performance

Filter Combination	Performance	Notes
No filters	Fast	Simple SELECT with pagination
+ isActive filter	Fast	Indexed column
+ category filter	Fast	Indexed column
+ searchText	Medium	Text search on name/description
+ searchText + category	Fast	Combined index usage

Response Size Optimization

// Small pages for UI
{ "pageSize": 10 }   // ~5-10 KB response

// Medium pages for processing
{ "pageSize": 50 }   // ~25-50 KB response

// Large pages for exports
{ "pageSize": 100 }  // ~50-100 KB response

---

Common Use Cases

1. Process Catalog UI

// Display paginated process list
const page1 = await getProcessDefinitionList({
  isActive: true,
  sortBy: 'category',
  sortDirection: 'asc',
  pageNumber: 1,
  pageSize: 20
});

2. Process Selection Dropdown

// Get all active processes for dropdown
const processes = await getProcessDefinitionList({
  isActive: true,
  sortBy: 'name',
  pageSize: 100
});

const dropdown = processes.data.items.map(p => ({
  value: p.id,
  label: p.name
}));

3. Process Health Monitoring

// Find processes with active instances
const response = await getProcessDefinitionList({
  isActive: true,
  sortBy: 'activeInstanceCount',
  sortDirection: 'desc',
  pageSize: 50
});

// Alert on high active instance count
response.data.items.forEach(p => {
  if (p.activeInstanceCount > 100) {
    console.warn(`⚠️ ${p.name}: ${p.activeInstanceCount} active instances`);
  }
});

4. Orphaned Process Detection

// Find inactive processes with active instances
const response = await getProcessDefinitionList({
  isActive: false,
  pageSize: 100
});

const orphaned = response.data.items.filter(p => p.activeInstanceCount > 0);

orphaned.forEach(p => {
  console.error(`❌ Inactive process "${p.name}" has ${p.activeInstanceCount} active instances`);
});

---

Related Commands

• GetProcessDefinitionByIdQuery - Get details of specific process from list
• CreateProcessDefinitionCommand - Create new process to appear in list
• UpdateProcessDefinitionCommand - Update process from list
• DeleteProcessDefinitionCommand - Remove process from list

---

Last Updated: January 6, 2026