Docs / Features

Temporal Workflows

Temporal IO Workflows

Laravel Mail Platform utilizes Temporal IO for robust, durable execution of complex workflows. Temporal ensures that critical processes like product imports and AI content generation run reliably, even in the presence of failures.

Overview

We use Temporal to manage long-running and multi-step processes.

  • Durable: Workflows can run for seconds or years. State is persisted.
  • Reliable: Automatic retries for failed activities.
  • Scalable: Independent workers scale with load.

Configured Workflows

The platform currently implements the following workflows:

1. Product Import Workflow (ProductImportWorkflow)

Handles the import of products from CSV files or external APIs.

  • Workflow ID: product-import-{uuid}
  • Input: Source URL (or file path), detailed options.
  • Activities:
    • downloadFile: Fetches the remote CSV/JSON.
    • parseContent: Processes the data structure.
    • upsertProduct: Creates or updates products in the database.
    • notifyAdmin: Sends a completion notification.

2. AI Content Generation (AiGenerationWorkflow)

Orchestrates the generation of marketing content using AI models.

  • Workflow ID: ai-gen-{uuid}
  • Activities:
    • generateSubjectLine: Generates email subjects.
    • generateBody: Drafts email body copy.
    • optimizeContent: Refines content based on SEO/engagement rules.

Architecture

The Worker

A dedicated artisan command runs the Temporal worker:

php artisan temporal:worker

This command connects to the Temporal server and polls for tasks. It registers:

  • ProductImportWorkflow
  • AiGenerationWorkflow
  • TaskActivity
  • ProductImportActivity
  • AiGenerationActivity

Infrastructure (Docker)

Our docker-compose.yaml includes:

  • temporal: The Temporal server (auto-setup image).
  • temporal-ui: The web dashboard, accessible at port 8080.

Managing Workflows

Starting the Worker

In a production environment, the worker should be managed by Supervisor (similar to queue workers).

Supervisor Config Example:

[program:temporal-worker]
command=php /var/www/artisan temporal:worker
autostart=true
autorestart=true
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/storage/logs/temporal-worker.log

Monitoring

You can monitor workflow execution via the Temporal UI:

  1. Open http://localhost:8080 (or your server's mapped port).
  2. View Workflows to see running, completed, and failed executions.
  3. Click a Run ID to view the event history, stack trace, and pending activities.

Development & Troubleshooting

Starting Temporal Locally: Ensure the temporal service is running in Docker:

docker-compose up -d temporal temporal-ui

Common Issues:

  • Connection Refused: Ensure TEMPORAL_ADDRESS in .env matches your Docker service name (default temporal:7233).
  • Workflow Timed Out: Check if your worker is running (php artisan temporal:worker). If the worker isn't running, workflows will sit in a "Running" state indefinitely until a worker picks them up.