Add a docs for Cron Jobs

[HardikGoyal2003]

Add a detailed wiki page that guides to the new contributors about the cron jobs.

• What are cron jobs
• How to write the cron jobs
• How to test them locally
• How it works on the prod

[rohitt-pandey]

Hi @HardikGoyal2003, I’d like to work on this issue.
I’ll add a detailed documentation page covering cron jobs overview, implementation, local testing, and production behavior.
Please let me know if that works. Thanks!

[HardikGoyal2003]

Hi @rohitt-pandey Can you please a draft of the documentation that you are proposing for this issue?

[rohanmalhotracodes]

here is my draft, it may be errorful and I am totally open to learning sir @HardikGoyal2003 sir,

Cron Jobs in Oppia

This page explains how cron jobs work in Oppia and how to add, test, and deploy them.

---

Overview

A cron job in Oppia is a scheduled backend task triggered by Google App Engine.

Cron jobs:

• Are defined in cron.yaml
• Trigger HTTP GET requests to /cron/... endpoints
• Are implemented in core/controllers/cron.py
• Must use the @acl_decorators.can_perform_cron_tasks decorator

They are typically used for:

• Cleaning up datastore models
• Triggering background processing
• Running periodic maintenance
• Starting deletion workflows
• Launching Beam or taskqueue jobs

---

Where Cron Jobs Are Defined

Cron jobs are defined in two places:

1. cron.yaml

Located at the root of the repository.

Each entry defines:

• description
• url
• schedule

Example:

cron:
- description: Clean up deleted models
  url: /cron/models/cleanup
  schedule: every sunday 03:00

The url must match a registered backend handler.

---

2. Backend Handler (core/controllers/cron.py)

Each cron endpoint must have a corresponding handler class.

Example structure:

class CronExampleHandler(base.BaseHandler[Dict[str, str], Dict[str, str]]):
    GET_HANDLER_ERROR_RETURN_TYPE = feconf.HANDLER_TYPE_JSON
    URL_PATH_ARGS_SCHEMAS = {}
    HANDLER_ARGS_SCHEMAS = {'GET': {}}

    @acl_decorators.can_perform_cron_tasks
    def get(self) -> None:
        example_services.run_periodic_task()
        return self.render_json({})

Important:

• The handler must be protected with
  @acl_decorators.can_perform_cron_tasks
• Business logic should be placed in a domain service
• The handler should remain lightweight

---

How to Add a New Cron Job

Follow the steps below.

Step 1: Add Handler

Add a new handler in:

core/controllers/cron.py

Use this structure:

@acl_decorators.can_perform_cron_tasks
def get(self) -> None:
    your_domain_service.run_job()
    return self.render_json({})

Keep the handler minimal and move heavy logic to:

core/domain/<your_service>.py

---

Step 2: Add Entry in cron.yaml

Add a new entry:

- description: Run example maintenance task
  url: /cron/example/maintenance
  schedule: every 24 hours

Schedule examples:

• every 24 hours
• every monday 09:00
• every day 02:00

---

Step 3: Ensure Route Is Registered

Verify that the /cron/... URL is properly mapped to your handler.

---

How to Test Cron Jobs Locally

Cron jobs can be tested locally in development mode.

Method 1: Run as Super Admin (Recommended)

The decorator allows super admins to execute cron endpoints locally.

Steps:

1. Start the dev server
2. Log in as super admin
3. Visit:

http://localhost:8181/cron/<your-endpoint>

4. Check terminal logs for execution

---

Method 2: Add Temporary Logging

Add logging inside your cron logic:

logging.info("Cron job started")

Trigger the endpoint and confirm output in logs.

---

Running Backend Tests

To run cron-related tests:

python -m scripts.run_backend_tests --test_target=core.controllers.cron_test

If adding new cron functionality, add corresponding backend tests.

---

How Cron Jobs Work in Production

In production:

1. App Engine reads cron.yaml
2. The scheduler triggers an HTTP GET request
3. The request includes header:

X-AppEngine-Cron: true

4. Oppia verifies the request using
   @can_perform_cron_tasks
5. The handler executes

Notes:

• Only internal App Engine requests include the cron header
• Cron jobs must return HTTP 2xx to be considered successful
• Failed jobs may be retried
• Cron jobs must be idempotent

---

Summary

Cron jobs in Oppia are scheduled backend tasks triggered via App Engine and executed through /cron/... endpoints. They must be secure, idempotent, lightweight at the handler level, and properly tested.

[jayam04]

@rohanmalhotracodes Are you still interested?

[rohanmalhotracodes]

@jayam04 How is the above draft sir, please let me know if any changes are required or would you like me to raise a PR and modify according to review there accordingly.