Activity Injection
How Reten dispatches activities to external providers via cron scheduling and pluggable dispatchers.
Reten handles activity dispatch automatically — you configure a provider and channel, and the platform sends activities to your system on a regular schedule.
How Dispatch Works
When activities are created with READY status, Reten's dispatch system picks them up and sends them to the configured external provider:
- A cron job runs every 30 seconds, processing all tenants sequentially
- For each tenant, up to 100 READY activities are dispatched per batch
- Each activity is sent to the provider configured for its channel
- On success, the activity transitions to
DISPATCHED - On failure, the activity retries (up to 3 attempts) before being marked
FAILED
Dispatch Providers
Providers are pluggable implementations that handle the actual delivery:
| Provider | Code | Description |
|---|---|---|
| YOM | YOM | REST dispatch via POST {baseUrl}/activities with x-api-key header |
| Mock | MOCK | Returns success with random UUID (development/testing) |
Configuring a Provider
To receive activities from Reten, you need to configure a Dispatch Provider Channel Config that links a provider to a specific channel for your tenant.
Channel Config Properties
| Property | Description |
|---|---|
| Base URL | Your provider's endpoint URL |
| Encrypted credentials | Authentication details (encrypted at rest with AES-256-GCM) |
| Settings | Additional provider-specific configuration (JSON) |
Use the Dispatch Config endpoints to manage configurations.
Channel Definitions
Each dispatch provider declares which channels it supports via Channel Definitions. These define the required credential and settings fields per channel, enabling dynamic configuration.
Dispatch Flow Detail
For each activity being dispatched:
- Optimistic lock — Increment
dispatch_attempt_countatomically; skip if another process already locked it - Load activity with relations (task details, operator, commerce assignment)
- Resolve dispatch config — Find the channel config matching the activity's channel
- Decrypt credentials using AES-256-GCM
- Look up provider code from the config
- Invoke dispatcher — Call the registered dispatcher for the provider
- On success — Set status to
DISPATCHED, storeproviderActivityIdanddispatchConfigId - On failure — If attempts >= 3, set status to
FAILED; otherwise keepREADYfor retry
Constants
| Constant | Value | Description |
|---|---|---|
| Max dispatch attempts | 3 | Retries before marking FAILED |
| Batch size | 100 | Activities per cron batch per tenant |
| Cron interval | 30 seconds | How often the scheduler runs |
What You Receive
When Reten dispatches an activity to your provider, the payload includes:
- Activity details (type, channel, reason, scheduling)
- Commerce information (assignment, target users)
- Operator details (for TASK type)
- Activity attributes (key-value data)
Your provider endpoint should accept this payload and return a provider activity ID that Reten stores for tracking.
Submitting Results Back
After processing an activity, submit results back to Reten via the Activity Results API. Link results using either the Reten activityId or your providerActivityId.