Reten Docs

Activity States

Canonical catalog of an activity's operational, display, and result states in Reten — with their valid transitions and projection rules.

An activity exposes two states: an operational one, filterable via the status query param, which reflects the activity's real situation in its execution cycle; and an informational one (lifecycleStatus), computed on every response, with friendlier values meant for user interfaces.

An activity's result (resultStatus) is a separate state, reported by the operator from the Reten platform or from an external provider. A COMPLETED activity only indicates that it was executed, regardless of whether the business outcome was positive or negative: for example, a client visit aimed at closing a sale stays COMPLETED even if the sale does not go through.

This page documents an activity's states: the operational one, the informational one, and the result one.

status (operational, filterable)

This is the activity's real state machine. Transitions between values are restricted by hard backend rules (see the diagram below). It is the only dimension filterable via the status query param on listing endpoints.

READY

Ready

Activity is fully resolved and ready to act on. If the client has a provider configured to dispatch activities, the system's next action attempts the dispatch; otherwise the activity stays READY and an operator can act on it from the internal platform.

filterable

Manual transitions

From: initial state
To: RETRYING, DISPATCHED, CANCELED, FAILED, COMPLETED
RETRYING

Retrying

At least one dispatch attempt has failed; the system will retry automatically. Each retry keeps the activity in this state. It moves to DISPATCHED when an attempt succeeds, or to FAILED when the available retries run out.

filterable

Manual transitions

From: READY, RETRYING
To: DISPATCHED, FAILED, RETRYING, CANCELED
DISPATCHED

Dispatched

Activity was delivered to the external provider. This applies only when the client has a dispatch provider configured for the activity; clients that operate exclusively from Reten's internal platform never pass through this state. Having a dispatch provider does not prevent the result from being recorded internally: the outcome can arrive either from the external provider or from the internal platform.

filterable
From: READY, RETRYING
To: COMPLETED, FAILED
COMPLETED

Completed

Activity reached a successful terminal state through one of three paths: (a) the external provider reported a result; (b) an operator recorded the result from Reten's internal platform; (c) an end-of-day closing process marked as not executed the results of activities left without an outcome at the end of the working day. COMPLETED only indicates that the activity was finalized — that it completed its cycle, regardless of whether the operator recorded a result; the business outcome (positive or negative) is reported separately in the activity result.

filterableterminal
From: READY, DISPATCHED
To: terminal
CANCELED

Canceled

Activity was explicitly canceled from a non-terminal state (READY or RETRYING) because the business reason behind it stopped applying before delivery (for example, the client already took the target action through another channel, opted out, or the recipient stopped being valid). Cancellation is terminal: no result is produced and no dispatch occurs.

filterableterminal

Manual transitions

  • Cancel activity — direct cancellation of the activity (canonical path, used both from Reten's internal platform and from the external system that created the activity)
From: READY, RETRYING
To: terminal
FAILED

Failed

Activity reached a failed terminal state through one of two paths: (a) dispatch attempts ran out without success; or (b) an end-of-day closing process detected an activity left retrying and marked it FAILED with result NOT_EXECUTED. Although terminal, a FAILED activity can be recovered manually via a dedicated endpoint that retries it once; the attempt can end in DISPATCHED, RETRYING, or FAILED again.

filterableterminal

Manual transitions

  • Force retry dispatch — retries the dispatch once; can end in DISPATCHED, RETRYING, or FAILED again(bypasses the state machine)
From: READY, RETRYING, DISPATCHED
To: terminal

Filterable subset (usable as the status query param on listing endpoints):

READY, RETRYING, DISPATCHED, COMPLETED, CANCELED, FAILED

lifecycleStatus (display, read-only)

This state is computed on every response from status plus contextual information about the activity (execution date, whether it has a provider, whether there are errors, whether it is retrying, among others). It is not filterable. It exists to show an enriched state in interfaces — both internal ones and the provider's — although the provider may derive its own state from its own rules if it prefers.

CANCELED

Canceled

Display state shown when the activity was canceled (`status` = CANCELED).

terminal
Projected from: ActivityStatus.CANCELED (no condition)
To: terminal
COMPLETED

Completed

Display state shown when the activity was completed (`status` = COMPLETED).

terminal
Projected from: ActivityStatus.COMPLETED (no condition)
To: terminal
FAILED

Failed

Display state shown when the activity failed definitively (`status` = FAILED).

terminal
Projected from: ActivityStatus.FAILED (no condition)
To: terminal
RETRYING_DISPATCH

Retrying Dispatch

Display state shown when the activity is retrying dispatch (`status` = RETRYING).

Projected from: ActivityStatus.RETRYING (no condition)
To: terminal
SCHEDULED

Scheduled

Display state shown when the activity is scheduled for a future day on the client's calendar. The comparison is at whole-day granularity (not exact time): it only counts as scheduled from tomorrow onwards.

Projected from: ActivityStatus.* (scheduledAt's local day > today in tenant timezone)
To: terminal
READY

Ready

Display state shown when the activity is ready and the client has no dispatch provider configured for it.

Projected from: ActivityStatus.READY (!hasDispatchProvider)
To: terminal
PENDING_DISPATCH

Pending Dispatch

Display state shown when the activity is ready and the client has a dispatch provider configured for it. The system has not attempted the dispatch yet; it will on its next automatic pass.

Projected from: ActivityStatus.READY (hasDispatchProvider)
To: terminal
DISPATCHED

Dispatched

Display state shown when the activity was dispatched to the external provider (`status` = DISPATCHED).

Projected from: ActivityStatus.DISPATCHED (no condition)
To: terminal
UNKNOWN

Unknown

Fallback value used when no other display state applies. It should not occur in normal operation; if it shows up, it points to an unhandled case. To diagnose it, check the activity's operational `status`.

Projected from: ActivityStatus.* (fallback — no rule matched)
To: terminal

These values are NOT filterable. To filter listings, use status with the values from the previous section.

resultStatus (independent)

Terminal state reported by the operator (from the Reten platform or from an external provider) once the activity has been executed — or discarded. It does not derive from status: a COMPLETED activity can carry any result, and the result is tracked separately so the business outcome is not conflated with execution.

COMPLETED

Executed

The activity was executed by the operator — the assigned action was carried out (visiting the commerce, contacting the client, etc.) as planned. It is ALWAYS assigned internally when a result is recorded (both audiences: internal and external operator); the caller never writes it. It does NOT imply the underlying business goal was met: a sales visit ends up COMPLETED whether or not the sale closed, as long as the operator executed the attempt. The more specific outcome (sale yes/no, client response, etc.) is captured in the result detail entity, not in the status.

filterableterminal
From: initial state
To: terminal
NOT_EXECUTED

Not Executed

Terminal result indicating the activity was closed without having been executed by the operator. Sole producer: the end-of-day auto-close job, which records NOT_EXECUTED for activities that crossed the auto-close cutoff without an outcome. No interactive flow produces it. An activity that could not be resolved does not end up as NOT_EXECUTED — that failure happens earlier and is not attributable to the operator.

filterableterminal
From: initial state
To: terminal

Transition diagram

Diagram of the operational state machine (it does not include lifecycleStatus, which is derived, nor the result, which is orthogonal). Only the edges the backend considers valid are shown; any transition not listed is rejected.

  ┌─────────┐
  │  READY  │  (initial state)
  └────┬────┘
       │
       ├────────────► ┌──────────┐
       │              │ CANCELED │ (terminal)
       │              └──────────┘
       │
       │  ┌────────────────────────────────────────────┐
       │  │ from READY:                                │
       │  │   → RETRYING, DISPATCHED, CANCELED,        │
       │  │     FAILED, COMPLETED                      │
       │  └────────────────────────────────────────────┘
       │
       ├─────────────► ┌───────────────┐
       │               │   RETRYING    │
       │               └───────┬───────┘
       │                       │
       │       from RETRYING:  │
       │         → DISPATCHED, │
       │           FAILED,     │
       │           RETRYING,   │
       │           CANCELED    │
       │                       │
       ├──────────────┐        │
       ▼              ▼        ▼
  ┌────────────┐   ┌────────────────┐
  │ DISPATCHED │──►│   COMPLETED    │ (terminal)
  └─────┬──────┘   └────────────────┘
        │
        └──► ┌──────────┐
             │  FAILED  │ (terminal)
             └──────────┘

Literal state machine edges:

  • READY → RETRYING, DISPATCHED, CANCELED, FAILED, COMPLETED (an activity's initial state)
  • RETRYING → DISPATCHED, FAILED, RETRYING, CANCELED
  • DISPATCHED → COMPLETED, FAILED
  • COMPLETED, CANCELED, FAILED → terminal (no outgoing edges)

Manual transitions (cancellations, force-retry-dispatch) are listed per state in the status section — each state card documents its manual transitions.