rules-rule-async-jobscheduler

name	rules-rule-async-jobscheduler
description	Schema and authoring guide for Pega Job Scheduler rules (Rule-Async-JobScheduler), including schedule types, scope, and examples

Prerequisite: Load methodology-rule-authoring first

When to use Job Scheduler vs Queue Processor:

Pattern	Use
Recurring task at a fixed time or interval	Job Scheduler
Large-volume batch (100 000+ records)	JS + QP Hybrid — JS dispatches; QP processes in parallel
Per-node cache initialisation at startup	JS ASSOCIATED_NODE scope + Startup frequency
Event-driven processing	Queue Processor — never use JS for event-driven
"Background job" that processes "items in the queue" or "waiting records"	Ambiguous — ask before proceeding

Disambiguating "background job" + "queue" requests

When the user says they want a "background job" (or "scheduled job") that processes "items in the queue", "waiting records", or similar, the architecture depends on how items enter the queue. Ask before creating any rule:

"When items are added — are they pushed immediately when an event occurs (e.g. a case reaches a certain status), or do they wait in the database until a scheduled sweep picks them up?"

• Event-pushed → Queue Processor only. Items are enqueued via Queue-For-Processing; no Job Scheduler is needed.
• Schedule-swept → Job Scheduler + Queue Processor hybrid. The JS activity browses and dispatches; the QP processes each item in parallel.

Authoring Notes

pyPurpose and pyRuleName

Ask the user for the rule name. Use it for pyPurpose; the server auto-derives pyRuleName from it. The builder's auto-derivation from pyLabel is unreliable and returns empty strings, producing a malformed instance key (double space in the key where the name should be). If pyPurpose is omitted, the builder fills an empty string and the rule is created without a proper name or identity key. If the user provides a description rather than a name, derive a CamelCase identifier (e.g. "check for latest tickets" → CheckForLatestTickets).

pyStartTime is local time in pyUseTimeZone — never pre-convert to UTC

pyStartTime must be the wall-clock time in the timezone named by pyUseTimeZone. Do not convert to UTC before sending. If the user wants a job at 17:00 IST (Asia/Calcutta), send "170000" — not "113000". The server normalises to UTC internally when it saves the rule; the stored value will differ from what you sent, but that is correct and expected. Pre-converting to UTC will cause the job to fire at the wrong local time.

update-rule and pyRecurrencePattern

Never include pyRecurrencePattern in an update-rule payload unless you explicitly intend to change the schedule. Deep merge will overwrite the existing pyStartTime even if the only intended change was to a different field (e.g., pyNodeTypes).

References

Skill	When to load
jobscheduler-checkpoint-pattern	Resumable JS activity design — NEW/IN-PROGRESS/PROCESSED pattern
jobscheduler-legacy-agent-replacement	Migrating Rule-Async-Agent to JS or QP
jobscheduler-alerts	Alert IDs and recommended actions

Examples

Rule-level

Skill	Description
Stub Job Scheduler	Minimal valid create payload — required fields only
Cluster-Scoped Daily Job Scheduler	Cluster scope, daily at 02:00, using the Checkpoint Pattern
Per-Node Startup Job Scheduler	Associated node scope, Startup frequency — per-node initialisation
JS + QP Hybrid — High-Volume Batch Dispatch	Cluster scope JS dispatch activity — see Enqueue and Dispatch for the activity design