> For the complete documentation index, see [llms.txt](https://docs.rubica.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rubica.au/workflow-automation/admin-and-troubleshooting.md).

# Admin & Troubleshooting

Rollout status, one-time setup, and known rough edges — for whoever owns this system, not day-to-day builders.

This page is for the person responsible for the Job Workflow Engine itself, not for someone building a template. It covers what actually runs the automation, and the handful of known gaps worth knowing about before you rely on something.

## How the engine actually runs — four separate paths

```mermaid
flowchart LR
    A["Job created or\nmoves stage"] -->|real-time| E["Dispatcher fires\nstage-entry actions immediately"]
    B["Hourly sweep"] -->|catches offset/recurring\nactions becoming due| E
    C["External call\n(e.g. a Workato recipe)"] -->|POST /rubica/job-workflow-engine| E
    D["Adviser clicks an outcome\nor Launch Workflow"] -->|manual| E
```

* **Real-time** — a Job being created or changing stage fires an immediate pass. This is an optimistic accelerator, not the source of truth — if it fails silently for any reason, the sweep below still catches everything eventually.
* **Hourly sweep** — a scheduled job catches offset-timed and recurring actions as they become due, independent of any Job event. **Live cron name: "Rubica Job Workflow Engine — hourly scan," running every hour on the hour.** ⚠️ Some internal documentation/code comments describe this as a *daily* 6am job — that's out of date; check Setup → Scheduled Jobs directly if you need to confirm the current cadence rather than trusting a comment.
* **External call** — a REST endpoint (`/services/apexrest/rubica/job-workflow-engine`) exists specifically for an external scheduler like Workato to call. `GET` previews without dispatching anything; `POST` actually runs it.
* **Manual** — an adviser picking an outcome, or using [Launch Workflow](/workflow-automation/launch-workflow.md), triggers dispatch for that one Job immediately.

## Known gaps — don't document (or promise) these as fully solved

* **`Execution_Status__c` is missing "Pending" as a defined picklist value.** The engine writes `Pending` correctly and it displays fine, but because it isn't a real picklist value, it won't show up in list-view filters or report groupings until an admin adds it to the field's value set.
* **The Service Mappings engine's own scheduled job wasn't found running** at time of writing, despite the code supporting self-scheduling. If Service Mapping-driven Jobs seem to be missing delay-based ones specifically, check whether that scheduler needs to be (re-)started.
* **"Undo" on a Job's stage progression is cosmetic.** It marks the log row as reversed for UI/reporting purposes — it does not actually undo whatever the action already did (an email that was sent stays sent). Good for correcting the *record*, not for taking back an action.
* **SMS doesn't have its own history object** the way email does — text message history lives only as a text blob on the log, not a structured, reportable record.
* **A couple of custom objects exist with zero real usage yet** (Stage Outcome sub-statuses, a designed-but-not-yet-live recurring-Job-schedule feature) — if you spot them in Setup, they're not a bug, just ahead of the UI that will eventually use them.
* [**Parallel Sub-Jobs**](/workflow-automation/parallel-sub-jobs.md) **isn't deployed everywhere yet.** Live in Forbes, Lume, Hartmann, Intergen, Caveo and Annex. CSBA and Treysta are blocked — not by this feature specifically, but because both orgs' default namespace is already near Salesforce's platform ceiling on total compiled Apex code (roughly 10.4M of a 6,000,000-character limit once dependent classes are pulled into one compile), which will block most future engine changes there until it's raised. That needs a Salesforce Support case, not a code fix.

## Naming collisions worth knowing about

Several similarly-named things are **not** the same feature — easy to conflate:

| Name                    | What it actually is                                                                                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow Trigger        | The real, live date-based Job-creation trigger (this doc's main subject)                                                                                      |
| Automation Trigger      | The Calendly-booking-specific trigger covered in [Service Mappings and Automation Triggers](/workflow-automation/service-mappings-and-automation-triggers.md) |
| Service Workflow Engine | The separate sale-based engine behind Service Mappings — its own log object, its own scheduler                                                                |
| Service *Model* Config  | Unrelated — an Account-level "next meeting date" calculator, nothing to do with Job automation                                                                |

## Reporting a problem

If a client-facing message went out wrong, or an expected action never fired, the fastest place to start is the Job's own **pending/completed actions** panel (each row is a `Job_Automation_Log__c`) — not Setup, and not this doc. Escalate with the specific Job and action name once you've confirmed what actually happened there.