Actions
Three things share the name, and telling them apart is most of the work:
- An action is one operation of an integration against one object:
"NetSuite upsert customer", "Enrich name". The catalogue is the
resource; each has an and an .
- An action column is an action wired into a table: which action, its
, and the mapping that says which of the row's columns
feed it. It lives in the table's (the tables skill covers
adding and changing one).
- An action run is one execution of one action column against one row.
Its status is one of , , , ,
. Runs are kept for 14 days.
You reach them through the RevOS MCP server's generic tools:
| Call | What it does |
|---|
api_read { "resource": "actions", "params": { "fields": "id,name,integrationName" } }
| the catalogue; add for the ones a table uses |
api_read { "resource": "actions", "id": "<action id>" }
| one action: , , |
api_read { "resource": "action-runs", "params": { … } }
| list runs: , , , |
api_read { "resource": "action-runs", "id": "<run id>" }
| one run, with its and |
api_write { "resource": "action-runs", "data": { "tableId": "…", "columnId": "…" } }
| run an action column — see references/run.md first |
api_details({ resource: "action-runs" })
is the authority on the filter
and field names; this skill covers what that schema can't tell you.
Something failed: start from the run
Most questions here are "why did this fail". Work in levels and stop at
the first one that answers the question: a failure whose cause is already
named in the run's own result doesn't need the table's schema, and pulling
it anyway costs the user a slower answer buried in detail they didn't ask
for.
Find the run. The user may hand you a run id straight from the
action-run drawer in the UI. Otherwise list, without the payloads:
json
api_read { "resource": "action-runs",
"params": { "filter": "status == \"FAILED\" && modelId == \"<table id>\"",
"orderBy": "createdAt desc", "pageSize": 10,
"fields": "id,actionId,columnId,modelId,objectId,objectName,status,attemptsMade,createdAt" } }
is the table's id. Narrow with
or
when you
know them.
Read the run by id. One call, and it carries the spine as well as both
payloads:
,
,
,
,
,
,
,
and
.
Where the error lives. There is no separate error column.
holds the whole run result, a union discriminated by
. On
a failure it carries:
- — the message to trust and to quote;
- — a generated rewording, present only if the
explain-error flow ran. Never present it as the system's own error;
- — a normalized object with , , ,
and .
error.isUnrecoverable: true
means the framework deliberately stopped
retrying: the condition is permanent (rejected credentials, a validation
the target system will never accept), so suggesting a re-run unchanged is
wrong.
A large share of failures are fully explained right here — credentials the
target system rejected, a rate limit, a permission, a validation message
that already names the field and the reason. When
says something
the user can act on,
that is the answer: quote it, say what to do, stop.
When the id doesn't resolve. A table cell goes on showing a failure
long after the run behind it was removed, so an id can name a run older
than the 14-day window. Say so and stop — no page of
can
contain it. If the user quoted the error text, that text is still worth
reading back to them. Then offer what does work: re-run the action and
diagnose the fresh failure.
When the run alone doesn't answer — the error is about a value that was
missing, empty or malformed, or the user asks where a value should have
come from — go on to references/debug.md: the
mapping, the lineage, and how to say where the fault is.
The organization's own instructions
Organizations write down how their integrations behave: what a particular
NetSuite error really means for them, who fixes what, how a link to their
CRM is built. These are served by the same MCP server as skills named
, at three breadths:
- — applies to everything in this organization;
- — everything involving that integration;
org/<integrationName>/<actionId>
Take
from the action (
on
with the
run's
). Call
, then
on
every one of
the three that exists for the run's scope. They add up rather than
override one another: the action-level text assumes you've read the
integration-level one.
Read them once you know which action is involved and before you tell the
user what to do. They are where a convention that makes your obvious
recommendation wrong lives, and they often map an error message straight to
its cause and fix. When they give wording, a link format, or an owner for
the fix, use theirs.
If the server has no
tool, or lists nothing under
,
there are no such instructions; carry on without them.
Running an action
Running acts on connected systems — it creates and updates records in the
customer's CRM or ERP — so only do it when the user asks, and read
references/run.md before the first
on
.
Adding or changing an action column
That is a change to the table, not to the action: the tables skill, its
column reference. The catalogue here tells you which
to use and,
through the action's
, what input it expects.
Reporting back
Lead with the cause in the user's terms, then what to do about it and who
does it. Quote
verbatim when the fix involves a
third party — a paraphrased vendor error is worse than useless when the
user takes it to that vendor's support. Name the row by
, not
by id. Don't dump
or
.