UpdateSchedulingInformationCommand

Overview

Configures scheduled execution of a process definition using cron expressions.

Purpose

Sets up recurring or scheduled automatic execution of a process, ideal for batch jobs, periodic reports, maintenance workflows, or any automated recurring tasks.

Command Type

CB.Administration.Api.Commands.BPM.Process.UpdateSchedulingInformationCommand

Request

{
  "cmd": "UpdateSchedulingInformationCommand",
  "data": {
    "processDefinitionId": 456,
    "schedulingEnabled": true,
    "cronExpression": "0 0 2 * * ?",
    "timezone": "Africa/Lagos",
    "variables": {
      "reportDate": "${today}",
      "batchSize": 100,
      "notifyEmail": "admin@bank.com"
    },
    "maxConcurrentInstances": 1,
    "description": "Daily loan portfolio report generation"
  }
}

Request Fields (data object)

Field	Type	Required	Default	Description
`processDefinitionId`	long	Yes	-	ID of process definition to schedule
`schedulingEnabled`	boolean	No	false	Enable/disable scheduling
`cronExpression`	string	Yes (if enabled)	-	Cron expression defining schedule
`timezone`	string	No	"UTC"	Timezone for schedule execution
`variables`	object	No		Default variables for scheduled instances
`maxConcurrentInstances`	int	No	1	Maximum concurrent instances allowed
`description`	string	No	""	Description of schedule purpose

Cron Expression Format

Standard cron format: second minute hour day month dayOfWeek

Field Breakdown

Position	Field	Values	Special Characters
1	Second	0-59	, - * /
2	Minute	0-59	, - * /
3	Hour	0-23	, - * /
4	Day of Month	1-31	, - * ? / L W
5	Month	1-12 or JAN-DEC	, - * /
6	Day of Week	0-6 or SUN-SAT	, - * ? / L #

Common Cron Patterns

"0 0 2 * * ?"         // Every day at 2:00 AM
"0 */15 * * * ?"      // Every 15 minutes
"0 0 9 * * MON-FRI"   // Every weekday at 9:00 AM
"0 0 0 1 * ?"         // First day of every month at midnight
"0 30 23 * * SUN"     // Every Sunday at 11:30 PM
"0 0 */4 * * ?"       // Every 4 hours
"0 0 12 1 JAN ?"      // Noon on January 1st every year
"0 0 10 L * ?"        // Last day of every month at 10:00 AM
"0 0 8 ? * MON#1"     // First Monday of every month at 8:00 AM

Response

{
  "isSuccessful": true,
  "message": "Scheduling configured successfully",
  "statusCode": "00",
  "data": {
    "processDefinitionId": 456,
    "schedulingEnabled": true,
    "cronExpression": "0 0 2 * * ?",
    "timezone": "Africa/Lagos",
    "nextRunTime": "2026-01-07T02:00:00Z",
    "lastRunTime": null,
    "jobId": "recurring_job_456",
    "maxConcurrentInstances": 1
  }
}

Response Fields

Field	Type	Description
`processDefinitionId`	long	ID of scheduled process
`schedulingEnabled`	boolean	Whether scheduling is active
`cronExpression`	string	Configured cron expression
`timezone`	string	Timezone used for scheduling
`nextRunTime`	datetime	Next scheduled execution time (UTC)
`lastRunTime`	datetime	Last execution time (null if never run)
`jobId`	string	Hangfire job ID for monitoring
`maxConcurrentInstances`	int	Maximum concurrent executions allowed

Use Cases & Examples

1. Daily Reports

Generate end-of-day reports every night:

{
  "processDefinitionId": 456,
  "schedulingEnabled": true,
  "cronExpression": "0 0 23 * * ?",
  "timezone": "Africa/Lagos",
  "variables": {
    "reportType": "daily_summary",
    "sendToEmail": "reports@bank.com"
  },
  "description": "Daily end-of-day summary report"
}

2. Monthly Processing

Run month-end procedures:

{
  "processDefinitionId": 789,
  "schedulingEnabled": true,
  "cronExpression": "0 0 1 1 * ?",
  "timezone": "Africa/Lagos",
  "variables": {
    "processType": "month_end_closing",
    "fiscalYear": 2026
  },
  "description": "Month-end closing process"
}

3. Periodic Cleanup

Regular maintenance tasks:

{
  "processDefinitionId": 321,
  "schedulingEnabled": true,
  "cronExpression": "0 0 3 * * SUN",
  "timezone": "Africa/Lagos",
  "variables": {
    "retentionDays": 90,
    "archiveOldData": true
  },
  "description": "Weekly data cleanup and archival"
}

4. Real-time Monitoring

Frequent system checks:

{
  "processDefinitionId": 654,
  "schedulingEnabled": true,
  "cronExpression": "0 */5 * * * ?",
  "timezone": "UTC",
  "variables": {
    "alertThreshold": 1000,
    "checkType": "transaction_monitoring"
  },
  "maxConcurrentInstances": 3,
  "description": "Real-time transaction monitoring (every 5 minutes)"
}

5. Quarterly Reports

Quarterly compliance reports:

{
  "processDefinitionId": 987,
  "schedulingEnabled": true,
  "cronExpression": "0 0 9 1 1,4,7,10 ?",
  "timezone": "Africa/Lagos",
  "variables": {
    "reportType": "quarterly_compliance",
    "notifyRegulator": true
  },
  "description": "Quarterly compliance report (Jan, Apr, Jul, Oct)"
}

6. Weekday Batch Processing

Business day processing:

{
  "processDefinitionId": 135,
  "schedulingEnabled": true,
  "cronExpression": "0 0 6 ? * MON-FRI",
  "timezone": "Africa/Lagos",
  "variables": {
    "batchType": "morning_reconciliation",
    "processAccounts": true
  },
  "description": "Morning reconciliation (Monday-Friday)"
}

Disabling Scheduled Execution

To stop scheduled execution without deleting the configuration:

{
  "processDefinitionId": 456,
  "schedulingEnabled": false
}

Note: Configuration is preserved and can be re-enabled later. No other fields need to be provided.

Timezone Considerations

Supported Timezones

Common timezones:

UTC - Coordinated Universal Time
Africa/Lagos - West Africa Time (WAT)
Africa/Johannesburg - South Africa Standard Time
Africa/Cairo - Eastern European Time
America/New_York - Eastern Time
Europe/London - Greenwich Mean Time

Example: Cross-Timezone Scheduling

// Schedule for 2 AM Lagos time
{
  "cmd": "UpdateSchedulingInformationCommand",
  "data": {
    "cronExpression": "0 0 2 * * ?",
    "timezone": "Africa/Lagos",
    "nextRunTime": "2026-01-07T01:00:00Z"  // UTC (Lagos is UTC+1)
  }
}

// Schedule for 2 AM UTC
{
  "cmd": "UpdateSchedulingInformationCommand",
  "data": {
    "cronExpression": "0 0 2 * * ?",
    "timezone": "UTC",
    "nextRunTime": "2026-01-07T02:00:00Z"  // UTC
  }
}

Concurrent Instance Control

Single Instance (Default)

Prevents overlapping executions:

{
  "cmd": "UpdateSchedulingInformationCommand",
  "data": {
    "maxConcurrentInstances": 1,
    "cronExpression": "0 */30 * * * ?"  // Every 30 minutes
  }
}

Behavior: If previous instance is still running when next schedule triggers, the new instance is skipped.

Multiple Instances

Allows parallel executions:

{
  "cmd": "UpdateSchedulingInformationCommand",
  "data": {
    "maxConcurrentInstances": 5,
    "cronExpression": "0 */5 * * * ?"  // Every 5 minutes
  }
}

Behavior: Up to 5 instances can run simultaneously. 6th instance will be queued/skipped.

Monitoring Scheduled Processes

Check Next Run Time

const process = await getProcessDefinitionById({
  id: 456,
  includeScheduling: true
});

console.log(`Next run: ${process.data.scheduling.nextRunTime}`);
console.log(`Cron: ${process.data.scheduling.cronExpression}`);

View Scheduled Instances

const instances = await getProcessInstanceList({
  processDefinitionId: 456,
  businessKey: "SCHEDULED"  // Scheduled instances have this key
});

console.log(`Scheduled executions: ${instances.data.totalRecords}`);

Cron Expression Builder Helper

class CronBuilder {
  static everyDay(hour, minute = 0) {
    return `0 ${minute} ${hour} * * ?`;
  }
  
  static everyWeekday(hour, minute = 0) {
    return `0 ${minute} ${hour} ? * MON-FRI`;
  }
  
  static everyMonthStart(hour, minute = 0) {
    return `0 ${minute} ${hour} 1 * ?`;
  }
  
  static everyMinutes(minutes) {
    return `0 */${minutes} * * * ?`;
  }
  
  static everyHours(hours) {
    return `0 0 */${hours} * * ?`;
  }
}

// Usage
const dailyReport = CronBuilder.everyDay(23);  // "0 0 23 * * ?"
const weekdayBatch = CronBuilder.everyWeekday(6);  // "0 0 6 ? * MON-FRI"
const realTimeMonitoring = CronBuilder.everyMinutes(5);  // "0 */5 * * * ?"

Best Practices

✅ Do's

Use Descriptive Descriptions

{
  "description": "Daily loan portfolio report - runs at 11 PM Lagos time"
}

Set maxConcurrentInstances = 1 for Sequential Jobs

{
  "cronExpression": "0 0 2 * * ?",
  "maxConcurrentInstances": 1  // Prevent overlap
}

Schedule During Off-Peak Hours

{
  "cronExpression": "0 0 3 * * ?",  // 3 AM
  "description": "Nightly cleanup - scheduled during low traffic"
}

Use Appropriate Timezone

{
  "timezone": "Africa/Lagos",  // Match business timezone
  "cronExpression": "0 0 23 * * ?"  // 11 PM local time
}

Provide Default Variables

{
  "variables": {
    "reportDate": "${today}",
    "environment": "production",
    "notifyOnError": true
  }
}

❌ Don'ts

Don't schedule too frequently without maxConcurrentInstances

❌ { "cronExpression": "0 * * * * ?" }  // Every minute, no limit
✅ { "cronExpression": "0 */5 * * * ?", "maxConcurrentInstances": 3 }

Don't forget timezone for business hours scheduling

❌ { "cronExpression": "0 0 9 * * ?", "timezone": "UTC" }  // Wrong!
✅ { "cronExpression": "0 0 9 * * ?", "timezone": "Africa/Lagos" }

Don't schedule heavy processes during business hours

❌ "0 0 14 * * ?"  // 2 PM - peak hours
✅ "0 0 2 * * ?"   // 2 AM - off-peak

Don't use invalid cron expressions

❌ "* * * * *"     // 5 fields (missing seconds)
✅ "0 * * * * ?"   // 6 fields (correct)

Troubleshooting

Schedule Not Triggering

Check:

schedulingEnabled is true
Cron expression is valid
nextRunTime is in the future
Process definition is isActive: true
Hangfire background server is running

Instances Skipped

Possible Causes:

Previous instance still running (check maxConcurrentInstances)
System too busy (check Hangfire queue)
Process definition deactivated

Wrong Execution Time

Check:

Timezone configuration
Server time vs business time
Daylight saving time adjustments

CreateProcessDefinitionCommand - Create process to schedule
GetProcessDefinitionByIdQuery - View scheduling configuration
StartProcessInstanceCommand - Manual execution alternative

Last Updated: January 6, 2026

Overview​

Purpose​

Command Type​

Request​

Request Fields (data object)​

Cron Expression Format​

Field Breakdown​

Common Cron Patterns​

Response​

Response Fields​

Use Cases & Examples​

1. Daily Reports​

2. Monthly Processing​

3. Periodic Cleanup​

4. Real-time Monitoring​

5. Quarterly Reports​

6. Weekday Batch Processing​

Disabling Scheduled Execution​

Timezone Considerations​

Supported Timezones​

Example: Cross-Timezone Scheduling​

Concurrent Instance Control​

Single Instance (Default)​

Multiple Instances​

Monitoring Scheduled Processes​

Check Next Run Time​

View Scheduled Instances​

Cron Expression Builder Helper​

Best Practices​

✅ Do's​

❌ Don'ts​

Troubleshooting​

Schedule Not Triggering​

Instances Skipped​

Wrong Execution Time​

Related Commands​