Overview

This document describes how to configure Google Cloud Scheduler jobs for TendSocial's automated tasks.

Prerequisites

• Google Cloud Project with Cloud Tasks/Scheduler API enabled
• Service account with appropriate permissions
• Webhook endpoints properly secured with webhook secret

Environment Variables Required

GCP_PROJECT_ID=your-project-id
GCP_LOCATION=us-central1
GCP_TASKS_QUEUE=tendsocial-tasks
WEBHOOK_URL=https://your-domain.com
WEBHOOK_SECRET=your-webhook-secret

Jobs to Configure

1. Daily Analytics Aggregation

Schedule: Daily at 2:00 AM UTC Endpoint: POST /api/jobs/daily-aggregationDescription: Fetches daily metrics from all connected social accounts.

gcloud scheduler jobs create http daily-aggregation \
  --schedule="0 2 * * *" \
  --time-zone="UTC" \
  --uri="${WEBHOOK_URL}/api/jobs/daily-aggregation" \
  --http-method=POST \
  --oidc-service-account-email=your-service-account@project.iam.gserviceaccount.com \
  --headers="X-Webhook-Secret=${WEBHOOK_SECRET}"

2. Best Times Recomputation

Schedule: Weekly on Sunday at 3:00 AM UTC Endpoint: POST /api/jobs/best-times-computationDescription: Recalculates optimal posting times based on historical performance.

gcloud scheduler jobs create http best-times-weekly \
  --schedule="0 3 * * 0" \
  --time-zone="UTC" \
  --uri="${WEBHOOK_URL}/api/jobs/best-times-computation" \
  --http-method=POST \
  --oidc-service-account-email=your-service-account@project.iam.gserviceaccount.com \
  --headers="X-Webhook-Secret=${WEBHOOK_SECRET}"

3. Scheduled Reports Generation

Schedule: Hourly Endpoint: POST /api/jobs/scheduled-reportsDescription: Checks for and generates reports that are due based on user schedules.

gcloud scheduler jobs create http scheduled-reports \
  --schedule="0 * * * *" \
  --time-zone="UTC" \
  --uri="${WEBHOOK_URL}/api/jobs/scheduled-reports" \
  --http-method=POST \
  --oidc-service-account-email=your-service-account@project.iam.gserviceaccount.com \
  --headers="X-Webhook-Secret=${WEBHOOK_SECRET}"

4. Queue Scheduler (Existing)

Schedule: Every 5 minutes Endpoint: POST /api/jobs/queue-schedulerDescription: Processes queue items that are ready to publish.

gcloud scheduler jobs create http queue-scheduler \
  --schedule="*/5 * * * *" \
  --time-zone="UTC" \
  --uri="${WEBHOOK_URL}/api/jobs/queue-scheduler" \
  --http-method=POST \
  --oidc-service-account-email=your-service-account@project.iam.gserviceaccount.com \
  --headers="X-Webhook-Secret=${WEBHOOK_SECRET}"

Verification

After creating the jobs, verify they are properly configured:

# List all scheduler jobs
gcloud scheduler jobs list

# Test a job manually
gcloud scheduler jobs run daily-aggregation

# View job execution history
gcloud scheduler jobs describe daily-aggregation

Monitoring

Monitor job execution through:

• Google Cloud Console > Cloud Scheduler
• Application logs for webhook endpoint calls
• Database records for job execution results

Security Notes

1. Always use OIDC authentication with a dedicated service account
2. Rotate webhook secrets regularly
3. Implement webhook signature verification in endpoint handlers
4. Use HTTPS for all webhook URLs
5. Monitor for failed executions and implement alerting

Troubleshooting

Job Not Executing

• Verify service account permissions
• Check webhook secret matches between scheduler and application
• Ensure endpoint is publicly accessible
• Review Cloud Scheduler logs

Rate Limiting

• Daily aggregation may hit platform API limits for companies with many accounts
• Implement exponential backoff in job handlers
• Consider spreading execution across different times for large tenants

Cost Optimization

• Cloud Scheduler charges per job per month
• Consider consolidating less critical jobs
• Use appropriate retry policies to avoid unnecessary executions
• Monitor execution times and optimize job performance