Contents show

Why this matters

ColdFusion Scheduled tasks (often called Cron jobs, timers, or the scheduler) are the heartbeat behind data syncs, report generation, cache warmups, emails, and Maintenance routines. Moving them cleanly during a Server Migration, Version upgrade, data center shift, or Containerization avoids duplicate executions, missed runs, broken HTTPS calls, and Security regressions. A careful approach keeps your SLAs intact while improving reliability and observability.

Prerequisites / Before You Start

Inventory and scope

List every scheduled task: name, schedule/frequency, endpoint URL or file, HTTP method, Authentication, start date/time, timezone, notification settings, and “paused/enabled” state.
Identify whether a task runs in:
- Adobe ColdFusion (ACF) or Lucee scheduler.
- OS-level schedulers: Linux crontab or Windows Task Scheduler.
- External schedulers (Jenkins, enterprise orchestrators).
Document dependencies: datasources, CF mappings, environment variables, proxies, DNS, and firewall rules.

Backups and exports

Adobe ColdFusion:
- Configuration files (per instance):
  - neo-cron.xml
  - neo-Security.xml, neo-runtime.xml (encryption seed/related config)
  - logs/scheduler.log
- Application code for task targets (CFM/CFML templates).
Lucee:
- scheduler.xml (and server/context configs).
OS-level:
- Linux: crontab -l > crontab.backup
- Windows: schtasks /Query /XML > tasks.xml (or export per task)
CommandBox/CFConfig users:
- cfconfig export to=cfconfig.json

Version matrix and compatibility

Note ACF/Lucee Version differences:
- Attributes supported by .
- TLS versions supported by the JVM.
- Default time zone and DST handling.
If crossing major versions, test on a staging server first.

Access and credentials

Admin credentials to source and target CF Admin (or Admin API).
File system access to instance directories.
Service account credentials for basic/digest auth, proxies, or database connections.
SSL/TLS keystores/truststores if tasks call HTTPS endpoints.

Maintenance window and rollback

Plan a window to disable tasks on source before enabling on target.
Define a rollback procedure (restore configs, re-enable source tasks).
Create monitoring/alerting to detect missed or duplicate runs.

Step-by-Step Migration guide

Step 1: Freeze the schedulers on the source

Prevent duplicate executions during migration.

Adobe ColdFusion / Lucee
- Option A: Pause/disable tasks via Administrator UI.
- Option B: Programmatic pause with cfschedule (ACF supports paused attribute when updating):

Linux cron
- Temporarily comment tasks: crontab -e and add “#” on task lines; or move crontab aside:
  crontab -l > crontab.migration && crontab -r
Windows Task Scheduler
- Disable tasks:
  schtasks /Change /TN “NightlyReindex” /Disable

Document which tasks are paused/disabled and when.

Step 2: Export the current Configuration

A. Adobe ColdFusion or Lucee – via

List all tasks programmatically to JSON or CSV you can re-import.

Example (simplified) to list tasks:

Note: returns a query named cfschedule on ACF/Lucee; exact columns vary by version.

B. Admin API (ACF)

Use the CF Admin API to enumerate and later create tasks. You will still capture plaintext credentials only if you explicitly include them.

C. CFConfig (CommandBox)

If you run CF via CommandBox or simply want a repeatable export/import:

Export:
cfconfig export to=cfconfig.json
Import later:
cfconfig import from=cfconfig.json

CFConfig supports both Adobe ColdFusion and Lucee and includes scheduler tasks.

D. Copying XML directly (last resort)

ACF tasks live in: [instanceHome]/lib/neo-cron.xml (varies for WAR deployments).
Lucee tasks live in: [server/context]/scheduler.xml.

Caution: Encrypted passwords won’t decrypt on a different server without the same encryption seed/crypto config. Copying only neo-cron.xml can break credentials. If you choose this route, copy the relevant security/crypto files too and validate Licensing and security implications. Generally safer to recreate tasks via API or with fresh credentials.

E. OS-level schedulers

Linux:
crontab -l > crontab.backup
Windows:
schtasks /Query /XML > alltasks.xml
Or per task:
schtasks /Query /TN “NightlyReindex” /XML > NightlyReindex.xml

Step 3: Prepare the target environment

Match or deliberately choose a new time zone. Scheduled tasks execute in the JVM/server time zone.
Ensure network access and DNS resolution to target endpoints. Update firewall rules and security groups as needed.
Import SSL/TLS certificates (if tasks hit internal HTTPS services):

keytool -importcert -trustcacerts -alias myinternalca \
-file internal_ca.crt \
-keystore /path/to/jre/lib/security/cacerts \
-storepass changeit

Create required CF mappings, datasources, JVM heap sizing, and environment variables.
Configure proxy settings if tasks use a corporate proxy.

Step 4: Import or recreate scheduled tasks

Method A: Using

Example: Create or update a task to run daily:

For cron expressions (if supported in your version), you can specify cron instead of interval:

Note: Cron Syntax varies (5 vs. 6 fields). Verify your engine’s documentation.

Method B: Using the Admin API (ACF)

admin = createObject(“component”,”cfide.adminapi.administrator”);
admin.login(“YOUR_CFADMIN_PASSWORD”);

sched = createObject(“component”,”cfide.adminapi.schedule”);

// Example: create a daily task
sched.create(
task = “NightlyReindex”,
startDate = “10/02/2025”,
startTime = “02:00”,
url = “https://new.example.com/tasks/reindex.cfm“,
operation = “HTTPRequest”, // depends on version
httpMethod = “POST”,
interval = “daily”,
publish = false,
resolveURL = true,
username = “svc_scheduler”,
password = “REENTER_THIS”,
requestTimeout = 900
);

Method names and arguments differ by version; consult the Admin API browser for your ACF build.

Method C: Copy XML with encryption caveats

If you must copy neo-cron.xml (ACF) or scheduler.xml (Lucee), replicate supporting crypto/seed files and ensure identical ownership/permissions.
After copying, open Admin UI and re-save each task that has credentials, or re-enter credentials via code to avoid decryption issues.

Method D: Using CFConfig (CommandBox)

Import full config:
cfconfig import from=cfconfig.json
Or import only scheduler subset by filtering (see CFConfig docs).
Start the server and verify tasks exist and are enabled.

Method E: OS-level cron and Windows Task Scheduler

Linux:
- On the new host:
  crontab crontab.backup
- Validate environment (PATH, JAVA_HOME), and ensure commands like curl or cfexecute targets exist.
Windows:
- Import tasks:
  schtasks /Create /XML NightlyReindex.xml /TN “NightlyReindex”

If your OS-level entries call ColdFusion URLs, validate that new hostnames and ports are correct.

Step 5: Adjust endpoints, credentials, and schedules

Replace old base URLs with new ones (staging → production). If you exported JSON, a simple find/replace works before import.
Re-enter passwords rather than copying encrypted strings.
Confirm cron expressions behave as intended; pay attention to DST transitions. Consider using fixed UTC schedules or guardrails in code.
Clustered environments:
- In ACF Enterprise, prefer clustered tasks to run once per cluster rather than per node. Confirm cluster membership before enabling.
- On Lucee/ACF Standard, use a single “primary” node or an external scheduler to avoid duplication.

Step 6: Dry run and validate

Force a manual run:
- Temporarily set a schedule to run in the next minute; or expose an authenticated URL that triggers the job logic.
- Observe logs:
  - ACF: [instance]/logs/scheduler.log
  - Lucee: [server]/logs/scheduler.log
  - Application logs or custom Audit logs.
Verify side effects:
- Database changes, files written to disk, emails sent, cache warmed.
Check HTTP response codes and timeouts. Increase requesttimeout for long tasks.

Step 7: Cutover

Keep source disabled.
Enable tasks on target.
Watch monitoring dashboards and logs for the first 24–72 hours.
Communicate completion to stakeholders; keep rollback plan handy until you’re confident.

Risks, Common Issues, and How to Avoid Them

Duplicate runs during migration
- Mitigation: Pause/disable source first; enable target after validation; consider cluster-aware scheduling.
Password encryption mismatch
- Mitigation: Re-enter credentials via or Admin API; avoid copying encrypted values across servers; if copying XML, ensure crypto/seed files match.
TLS/SSL failures to HTTPS endpoints
- Mitigation: Import internal CA certs into JVM truststore; verify TLS versions and ciphers; test with curl -v.
Proxy or firewall restrictions
- Mitigation: Configure proxy attributes; open egress rules; update allow-lists at the target.
Time zone and DST shifts
- Mitigation: Standardize on UTC where feasible; document intended behavior during DST changes; test cron expressions around transition dates.
Missing CF mappings, datasources, or environment variables
- Mitigation: Recreate all dependencies before importing tasks; include them in CFConfig exports.
Path and case-sensitivity differences (Windows vs. Linux)
- Mitigation: Normalize paths; avoid case-sensitive file name assumptions; test file writes and reads.
Long-running tasks overlapping
- Mitigation: Add application-level locking or idempotency checks; use a “task lock” in the database; tune requesttimeout and concurrency.
Cluster misconfiguration
- Mitigation: Use ACF’s clustered tasks or designate a single executor node; disable duplicates on other nodes.
Silent failures due to notifications disabled
- Mitigation: Configure onComplete hooks or error notifications; integrate with logging/alerting platforms (email, Slack, PagerDuty).

Post-Migration Checklist

Tasks exist on target with correct:
- Names, intervals/cron expressions, start dates/times, time zone, enabled/paused status.
Endpoints and HTTP methods are updated; credentials re-entered and validated.
SSL handshakes succeed; no certificate errors in logs.
Logs:
- No errors in scheduler.log or application logs during initial runs.
- Expected INFO entries for trigger times and durations.
Dependencies:
- Datasources reachable; CF mappings, file paths, environment variables set.
- Proxy configuration applied and tested.
Performance:
- No unexpected CPU/memory spikes; GC logs stable during heavy tasks.
- Request timeouts appropriate for task duration.
Idempotency and locking:
- Long jobs don’t overlap; locking strategies validated.
Monitoring:
- Synthetic checks or alerts for missed runs are enabled.
- Dashboards show expected cadence and outcomes.
Documentation:
- Updated runbooks, credentials management, and escalation paths.
Backups:
- New configuration backups taken (e.g., cfconfig export, scheduler.xml copy).
Rollback:
- Source remains disabled; rollback procedure verified but not needed.

Reference: Where are schedulers stored?

Adobe ColdFusion (standalone)
- Tasks: [instanceHome]/lib/neo-cron.xml (e.g., cfusion/lib/neo-cron.xml)
- Logs: [instanceHome]/logs/scheduler.log
- Note: For additional instances, paths use the instance name.
Adobe ColdFusion (WAR/J2EE)
- Under the deployed context: WEB-INF/cfusion/lib/neo-cron.xml
Lucee
- Tasks: [server or web context]/scheduler.xml
- Logs: [server]/logs/scheduler.log
CommandBox + CFConfig
- Export/import: cfconfig export|import (scheduler included)
Linux cron
- Per-user crontab: crontab -l
- System-wide: /etc/crontab, /etc/cron.d/*, /etc/cron.{hourly,daily,weekly,monthly}
Windows Task Scheduler
- Export/import via schtasks and MMC; tasks stored in the OS, not CF.

Example configurations

Create a ColdFusion task with

Admin API (ACF) example in CFScript

admin = createObject(“component”,”cfide.adminapi.administrator”);
admin.login(“YOUR_CFADMIN_PASSWORD”);
sched = createObject(“component”,”cfide.adminapi.schedule”);

sched.create(
task = “CacheWarm”,
startDate = “10/02/2025”,
startTime = “03:00”,
url = “https://app.example.com/cache/warm.cfm“,
httpMethod = “GET”,
interval = “daily”,
requestTimeout = 600,
resolveURL = true
);

CFConfig export/import

Export from source:
cfconfig export from=/opt/coldfusion/cfusion to=/tmp/cfconfig.json
Import to target:
cfconfig import to=/opt/coldfusion/cfusion from=/tmp/cfconfig.json

Optionally sanitize credentials in the JSON and re-enter them post-import.

Linux crontab calling a CF endpoint

m h dom mon dow user command

5 www-data /usr/bin/curl -fsS https://app.example.com/maintenance/cleanup.cfm?token=SECURETOKEN >> /var/log/cron-cleanup.log 2>&1

Windows Task Scheduler import

schtasks /Create /XML C:\migrate\NightlyReindex.xml /TN “NightlyReindex”
schtasks /Change /TN “NightlyReindex” /Enable

FAQ

Puis-je simplement copier neo-cron.xml vers le nouveau serveur ?

Copying neo-cron.xml alone often fails for tasks with credentials because password encryption keys differ across servers. Prefer recreating tasks via , the Admin API, or CFConfig, and re-enter credentials. If you must copy XML, also migrate the related crypto/seed configuration and validate Licensing/security impact.

Comment éviter l’exécution en double pendant la migration ?

Pause/disable tasks on the source first, validate imports on the target with a forced dry run, then enable on the target. In clusters, use ColdFusion’s clustered tasks (Enterprise) or designate a single executor node.

Que faire si un job HTTPS échoue après la migration ?

Import the server’s root/intermediate certificates into the JVM truststore used by ColdFusion. Verify with curl, check TLS versions/ciphers, and confirm proxy and firewall rules.

Puis-je convertir un job du scheduler ColdFusion en cron Linux ou tâche Windows ?

Yes. Recreate the same frequency using crontab or Windows Task Scheduler and call the ColdFusion endpoint with curl or PowerShell Invoke-WebRequest. Be sure to include Authentication tokens, timeouts, and logging.

Comment gérer les changements d’heure (DST) pour mes tâches planifiées ?

Use UTC for server/JVM time zone where possible, or choose cron expressions known to behave predictably in your engine. For critical tasks, add application-level guards (idempotent processing, “last run” checks) to prevent duplicates or skips during DST transitions.