Licensed to be used in conjunction with basebox, only.
// integration
Write access
Applies to
Product: Cloud · Server · Audience: Developer / Integrator · Administrator
Tools that change something in an external system: confirmation patterns, idempotency and what basebox expects before a write operation. In basebox, all write-capable tools are disabled per app by default; an administrator must enable them explicitly. Design them so that this enablement is easy.
Principle: writing is a class of its own
- Dedicated tools for changes –
create_issue,update_page,add_comment– clearly separate from read tools. Never a tool that reads or writes depending on a parameter. - Descriptive names by which basebox and administrators recognise the class:
create_*,update_*,delete_*. - The description names the effect: "Creates a new issue. Changes data in the ticket system."
That way an app can be shared widely with read tools while write tools are active only in a narrowly shared app – see Connector permissions.
Always with the person's credentials
A change is made as the user whose token is in the Authorization header. In the target system it appears under their name; the target system checks whether they may perform it. Write tools via a service account are an anti-pattern: changes would be attributable to nobody, and the service account would need write rights for everyone.
Patterns for safe write tools
Explicit, complete parameters. A write tool guesses nothing. update_issue needs the issue ID and exactly the fields to change; no "adjust the issue the user means".
Small effect per call. One object per call. No bulk operations (delete_all, update_matching) – if ten issues are to be changed, that is ten traceable calls.
Idempotency. A repeated call with the same parameters must not have a second effect. Use the target system's idempotency keys, check for duplicates before creating, or offer update instead of create where the target system allows.
Return state. The result contains what was changed – ID, link, the new field values, ideally before/after. The model can report exactly to the user with it, and the user can verify.
Avoid deleting. Where possible, "archive", "close" or "mark as done" instead of deleting. If deleting is necessary, only individually, only by ID, with full feedback.
Offer a preview. A dry_run parameter or a separate preview_* tool shows what would happen – and the model can ask the user before it writes.
What basebox expects before a write operation
- The connector is active organisation-wide and the write tool is explicitly enabled in the current app.
- The user has stored their own credentials; without them the tool is not offered to the model.
- The call carries the user's header; the target system decides whether the change is allowed.
- The result is framed as data and shown to the user; the call is in the audit log (user, tool, target, result, timestamp).
An additional human approval before the call (human-in-the-loop) is announced but not yet available. Until then, confirmation lies in the design of your tools: small effect, preview, clear feedback.
Errors and conflicts
| Situation | Behaviour |
|---|---|
| Target system refuses (403) | Report as result; circumvent nothing |
| Object changed in the meantime (conflict, 409) | Report, return current version, do not overwrite |
| Validation error (400) | Name missing or invalid fields so the model can ask |
| Timeout after sending | Do not blindly retry; check status via get, then report |
| Partially successful | Say exactly what succeeded and what did not |
Example: result of a write tool
{
"action": "update_issue",
"id": "PROJ-123",
"url": "https://tickets.example.com/issue/PROJ-123",
"changed": {
"state": {"from": "Open", "to": "In Progress"},
"assignee": {"from": null, "to": "m.mueller"}
}
}
Checklist before enabling
- Write tools separate and named as such
- Only with personal credentials
- One object per call, no bulk operations
- Idempotent; duplicates avoided
- Full feedback with ID, link, changed fields
- Deleting avoided or narrowly bounded
- Documented in which apps the tool should be enabled
Next: Permissions · Examples