trilium/docs/User Guide/User Guide/Scripting/Backend scripts/Events.md

Events

Script notes can be triggered by events. Note that these are backend events and thus relation need to point to the "JS backend" code note.

Global events

Global events are attached to the script note via label. Simply create e.g. "run" label with some of these values and script note will be executed once the event occurs.

Label	Description
run	Defines on which events script should run. Possible values are: frontendStartup - when Trilium frontend starts up (or is refreshed), but not on mobile. mobileStartup - when Trilium frontend starts up (or is refreshed), on mobile. backendStartup - when Trilium backend starts up hourly - run once an hour. You can use additional label runAtHour to specify at which hour, on the back-end. daily - run once a day, on the back-end
runOnInstance	Specifies that the script should only run on a particular Trilium instance.
runAtHour	On which hour should this run. Should be used together with #run=hourly. Can be defined multiple times for more runs during the day.

Entity events

Other events are bound to some entity, these are defined as relations - meaning that script is triggered only if note has this script attached to it through relations (or it can inherit it).

Relation	Trigger condition	Origin entity (see below)
runOnNoteCreation	executes when note is created on backend. Use this relation if you want to run the script for all notes created under a specific subtree. In that case, create it on the subtree root note and make it inheritable. A new note created within the subtree (any depth) will trigger the script.	The BNote that got created.
runOnChildNoteCreation	executes when new note is created under the note where this relation is defined	The BNote of the child that got created.
runOnNoteTitleChange	executes when note title is changed (includes note creation as well)	The BNote of the note whose title got changed.
runOnNoteContentChange	executes when note content is changed (includes note creation as well).	The BNote of the note whose content got changed.
runOnNoteChange	executes when note is changed (includes note creation as well). Does not include content changes	The BNote of the note that got changed.
runOnNoteDeletion	executes when note is being deleted	The BNote of the note that got (soft) deleted.
runOnBranchCreation	executes when a branch is created. Branch is a link between parent note and child note and is created e.g. when cloning or moving note.	The BBranch that got created.
runOnBranchChange	executes when a branch is updated. (since v0.62)	The BBranch that got changed.
runOnBranchDeletion	executes when a branch is deleted. Branch is a link between parent note and child note and is deleted e.g. when moving note (old branch/link is deleted).	The BBranch that got (soft) deleted.
runOnAttributeCreation	executes when new attribute is created for the note which defines this relation	The BAttribute that got created.
runOnAttributeChange	executes when the attribute is changed of a note which defines this relation. This is triggered also when the attribute is deleted	The BAttribute that got changed.

Origin entity

When a script is run by an event such as the ones described above, api.originEntity will get populated with the note, branch or attribute that triggered the change.

For example, here's a script with ~runOnAttributeChange which automatically changes the color of a note based on the value of the mycategory label:

const attr = api.originEntity;
if (attr.name !== "mycategory") return;
const note = api.getNote(attr.noteId);
if (attr.value === "Health") {
    note.setLabel("color", "green");
} else {
    note.removeLabel("color");
}