Route your App's own steps to a role task¶
You can give a step that is particular to your App, such as "design approved", its own code, point that code at the role task that says what to do next, and record the step as an event your whole team can read. After that, a worker who records the step is told which task it leads to. Recording from the CLI as yourself gets the code only (see step 3).
You will need the CLI for the recording step. Recording an action is a CLI or GraphQL call; at the server revision this page names, no agent tool and no portal screen records one. Writing the mapping can be done in the portal, with no terminal. Reading the events back is a CLI read.
Needs CLI v0.37.0 or later
hadron app action record and team events --code-prefix first shipped in
CLI release v0.37.0, and recordAppAction is on hadron-server main (see
App-defined actions for the revisions).
Check hadron app action --help before you start. If it is unknown, your
CLI is older than v0.37.0.
What a code is, and how the register finds its task, is explained in The action register index. The exact grammar, limits and refusals are on the reference page.
Illustrative
The App acme.com:eng, its code and its task are made up, and the
receipt below is shown as the reference describes it. This page's
steps have not been run against a deployed server.
1. Choose a code¶
A code is app.<appSlug>.<name>, where the slug is your App's current
slug. For the App acme.com:eng, the slug is eng:
Use lower-case letters, digits and -, and keep the whole code to 64
characters or fewer. If you later rename the App, recording this code is
refused and you need a new code and a new mapping, so pick a name you expect
to keep.
2. Map the code to a role task¶
The mapping is a node in your Team Agent's system memory, named
register:<code>. It names the place of a task, and each role finds its own
task at that place through its own Agent chain.
In the portal, open the Team Agent's system memory and choose New node. The
Loc field must be register:app.eng.design.approved. The portal fills in
a Loc from the Name and drops the colon and the dot, so type the Loc yourself.
Then open the node's Data tab, choose Source, and enter:
The same steps, with a longer explanation, are under Writing the mapping for tickers; an App code is mapped the same way.
3. Record the step¶
hadron app action record app.eng.design.approved --app acme.com:eng \
--task AT0.7 --payload '{"review":"done"}'
app: acme.com:eng (from --app)
event 01a1…
action app.eng.design.approved WITHHELD
task loc — task URN —
The last two lines are the register's answer for the caller. The CLI
records as you, a person with no Agent, and attaches no worker session, so you
get WITHHELD and the code only. Either way the event is recorded. A worker
that records the step through a worker-aware GraphQL call gets the task its
own Agent chain finds (MAPPED, with the task loc and URN).
- Put nothing secret in
--payload. Everyone in the App can read it, and so can the App's key. --taskties the event to a task for reading. It does not count as acting on that task, and the task's wakes stay due.- The command sends once and never retries. If it times out, read the events (next step) before you try again, or you may record the step twice.
4. Read it back¶
app.eng. returns only your App's recorded actions. A bare app. also
returns three events the platform writes itself.
When it goes wrong¶
| You see | Why |
|---|---|
APP_ACTION_CODE_INVALID, exit 2 |
The code is not app.<current slug>.<name>, is over 64 characters, or the App was renamed. |
TASK_NOT_FOUND, exit 4 |
--task is not a task you can read in this App. A bare handle may need qualifying when you belong to several Apps. |
UNMAPPED |
No entry named for this exact code is readable on the Team Agent's chain. Check the Loc spelling in step 2. |
UNRESOLVED |
The entry is there, but no role task exists at its taskLoc for your Agent chain. |
WITHHELD |
You have no Agent, so you were given the code only. This is expected for a person, and for every CLI call. |
APP_NOT_FOUND, exit 4 |
You lack the authority to create tasks in this App. The server conceals that refusal as not-found. |
Related¶
- App-defined actions: the grammar, payload, register states and refusals.
- The action register index: what the register is and how a code finds its task.
- Read the action register index: see every code in your App and where it lands.
- Hand work to your team as tasks: the role tasks a code points at.