The flow
1
Preview
Call
preview_setup with the file text. It writes nothing, and a read-only connection can use it.2
Ask the user
Show the preview and ask. The digest ties an apply to a preview of the same decisions. It doesn’t show that anyone read the preview.
3
Apply
Call
apply_setup with the same file, the same portfolio_id and the preview’s digest.4
Undo, if asked
Call
undo_setup. It shows what would go unless dry_run is false.Tools
read
Shows what an
ALLOCAIT.md setup file would add to your account and what stays yours. Writes nothing, and a read-only connection can use it. The result opens with digest and can_apply, then file (its id, name, author, revision, description and disclosure, and your newest earlier import of it), note (Allocait’s own sentence about the numbers in a file), target (the portfolio its playbooks, monitors and charts go to), counts (new, update, same, kept and left_out), items (each with its kind, name, status and reason, and the details that explain it), issues (warnings), unlisted_symbols and key, which says what each status and reason means. With several portfolios and a file that has a portfolio block, choose_portfolio lists them; ask the user which. A file with errors comes back as INVALID_INPUT with every error in issues. Rules text is refused, with a pointer to preview_rules. Key arguments: setup (the whole file text, from the opening ---), optional portfolio_id.write, destructive
Applies a setup file exactly as
preview_setup showed it. It adds what the preview marked new, and updates only what an earlier import of the same file made and you haven’t changed. It never overwrites something you made, deletes an item, or writes a holding, cash, price, recorded value or active scenario. Returns a receipt_id for undo_setup, and each item it created carries its object_id. It never makes a scenario active: save_portfolio does that, when you ask. If your account changed since the preview, it writes nothing and returns CONFIRMATION_REQUIRED with a fresh preview. The digest ties an apply to a preview of the same decisions; it doesn’t show that anyone read the preview. Ask the user first, and don’t apply with no one to ask. Key arguments: setup and portfolio_id (as previewed), digest (from preview_setup).write, destructive
Undoes an applied setup file: removes what it added that you haven’t changed or used, puts back what it updated, and keeps the rest. Recorded values stay. Only a file’s newest import can be undone; a later import of the same file blocks it with
IN_USE and later_receipt_id. It shows what would go unless dry_run is false. Key arguments: optional receipt_id (default: the newest import), optional dry_run (default true).Next steps
ALLOCAIT.md
What a setup file holds and how the review works.
Rule tools
Change one class or a whole scenario’s rules.