Skip to content

Sidecars (comments, attachments)

A sidecar is a panel beside a document: comments on one tab, files on another. The records live in their own doctypes in the core domain, and the host doctype declares which panels it carries. One declaration serves every doctype that wants the panel — you never copy the comment logic into your domain.

Add the comments panel when people discuss a record. Add the attachments panel when people keep files with a record. Both panels are declared on the doctype, so you can give them to any doctype in your domain.

  • A draft domain. You edit the host doctype in a draft domain. See Designing doctypes.
  • Nothing to create. The sidecar doctypes core.Comment and core.Attachment exist on every instance. You declare them on your host; you do not create them.
  • A free segment name. A segment name (the panel’s route segment, such as comments) cannot collide with a children relationship of the same name.

1. Add the sidecars map to the host doctype

Section titled “1. Add the sidecars map to the host doctype”

Each entry names the panel: the key is the route segment, and the value names the sidecar doctype plus the reference column that points back at the host.

"sidecars": {
"comments": { "doctype": "core.Comment", "column": "target" },
"attachments": { "doctype": "core.Attachment", "column": "target" }
}

Two optional keys refine the panel: label changes the tab text, for example "Notes" instead of “Comments”, and order sets the tab order when the default alphabetical order does not fit.

A nested sidecar grant follows the host path. In practice:

Caller right What it allows
read on hr.Employee Read the comments and attachments.
create on hr.Employee Write comments and attach files.
create on hr.Employee.Comment Comment as a read-only user.

That last line is how you let a viewer comment: keep their host rights read-only and add the explicit nested line for the action.

Open a document. The panel stands beside the page and shows one tab per declared sidecar, with a count per tab. Comments take markdown, support replies, and notify a person when you mention them. Attachments show type, size, uploader, and time.

The definition below gives an employee record both panels, with a renamed comments tab.

{
"domain": "hr",
"doctype": "Employee",
"aggregate_root": true,
"schema_version": 1,
"fields": {
"job_title": { "type": "string", "required": true }
},
"sidecars": {
"comments": { "doctype": "core.Comment", "column": "target", "label": "Notes" },
"attachments": { "doctype": "core.Attachment", "column": "target" }
}
}

The API creates a comment through the host path:

Terminal window
curl -k -X POST "https://facet.localhost:3443/Api/hr/Employee/01HQ2F5WX8K4M3PZC6NRB9TJVA/comments" \
-H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"body": "Welcome aboard"}'

-k skips the certificate check of the local development address. Facet sets the target from the path. A target key in the body answers 400.

The doctype carries no sidecars map, or the doctype was edited after the page was opened. Check the definition and reload.

Your role can read the host but holds no create right on the host path and no explicit nested line. Ask the domain author for create on the host, or for the nested line shown in step 2.

Sidecar records are created through the host document, never through the flat route. Use the nested path shown in the example.

Facet removes sidecar records when their host is deleted. The removal is separate from the host, so it is not undone when the host document itself is restored.