Active Window Status Synchronization

This guide covers the sync_active_window_statuses CakePHP console command and the generic cron runner script cronScripts/runCakeCommand.sh. Use these tools to keep ActiveWindowBaseEntity-derived records up to date and automate recurring maintenance jobs across UAT/PROD environments.

---

🎯 Purpose

• Re-evaluates all entities extending ActiveWindowBaseEntity (e.g., Warrants) and transitions:
  • Upcoming → Current when start_on <= now
  • Current → Expired when expires_on is populated and in the past
• Sets modified_by = 1 (super user) on any records touched, preserving audit history
• Skips tables lacking the required status/start_on schema

---

🧱 Prerequisites

1. Application environment (UAT/PROD/etc.) bootstrapped with CakePHP 5.x.
2. CLI user must have write access to app/logs/ and read access to config/version.txt.
3. PHP binary with required extensions (default path /usr/local/php83/bin/php).
4. cronScripts/runCakeCommand.sh deployed alongside the application source tree.

---

🚀 Running the Command Manually

From any environment, the generic wrapper can launch the command:

# Dry run (no database writes)
bash cronScripts/runCakeCommand.sh \
  --workdir /home/vscribe/amp-uat.ansteorra.org \
  sync_active_window_statuses --dry-run

# Execute and persist status transitions
bash cronScripts/runCakeCommand.sh \
  --workdir /home/vscribe/amp-prod.ansteorra.org \
  sync_active_window_statuses

Options & Overrides

Flag	Description
--workdir PATH	Application root containing bin/cake.php (required unless CAKE_WORKDIR env var provided).
--php-bin PATH	PHP executable to use (default /usr/local/php83/bin/php or CAKE_PHP_BIN).
--cake-bin PATH	Override path to Cake console if not bin/cake.php.
--help	Display usage banner.
--	Stop option parsing; pass remaining args to Cake (e.g., add --dry-run).

Environment variable fallbacks:

• CAKE_WORKDIR
• CAKE_PHP_BIN
• CAKE_CAKE_BIN

Example using environment defaults:

CAKE_WORKDIR=/home/vscribe/amp-uat.ansteorra.org \
CAKE_PHP_BIN=/usr/local/php83/bin/php \
bash cronScripts/runCakeCommand.sh sync_active_window_statuses --dry-run

---

⏱ Cron Job Configuration

We leverage DreamHost-style cron entries with setlock to prevent overlaps. Place the script under /home/vscribe/cronJobScripts/ (or symlink it there) and reference it with the correct work directory.

Example: AMP UAT (runs every 5 minutes)

*/5 * * * * /usr/bin/setlock -n /tmp/cronlock.vscribe-AMP_UAT_SyncActive \
  sh -c 'bash /home/vscribe/cronJobScripts/runCakeCommand.sh \
    --workdir /home/vscribe/amp-uat.ansteorra.org \
    sync_active_window_statuses --dry-run'

Example: AMP PROD (runs nightly at 01:30 and writes changes)

30 1 * * * /usr/bin/setlock -n /tmp/cronlock.vscribe-AMP_PROD_SyncActive \
  sh -c 'bash /home/vscribe/cronJobScripts/runCakeCommand.sh \
    --workdir /home/vscribe/amp-prod.ansteorra.org \
    sync_active_window_statuses'

💡 Tip: Add --php-bin /usr/local/php83/bin/php if the host default differs from our shared server paths.

---

🔍 Monitoring & Troubleshooting

• Inspect /app/logs/cli-error.log and /app/logs/cli-debug.log for command output. Ensure the CLI user has write permissions.
• A non-zero exit status propagates through runCakeCommand.sh thanks to set -euo pipefail, which aids alerting and setlock scripts.
• Use --dry-run when validating new deployments or before enabling the PROD cron.
• If config/version.txt warnings appear, add an empty file or adjust bootstrap config for the environment.

---

📚 Related References

• cronScripts/runCakeCommand.sh (generic launcher)
• app/src/Command/SyncActiveWindowStatusesCommand.php
• /docs/3.2-model-behaviors.md (ActiveWindow behavior overview)
• /docs/4.3-warrant-lifecycle.md (impacted entity example)

Keep this document updated whenever new ActiveWindow-based entities or cron workflows are introduced.