Advanced : Event Hooks

Attaching listeners to these events can allow automation of operations/workflows

This is an early-stage feature. Use at your own risk, and only if you're familiar with JavaScript programming.

The extension emits custom events when certain operations have taken place. These events use the prefix zotero-roam:, and the details they contain can provide a basis for automation.

Events

metadata-added	Metadata has been added to an item's page
notes-added	Notes have been added to an item's page
tags-deleted	Tags have been deleted from Zotero
tags-modified	Tags have been modified in Zotero
update	A data update request has completed
update-collections
write	A write request to Zotero has completed

Schemas

zotero-roam:metadata-added

{
    args: {
        // The blocks received for insertion into the page.
        // Defined only if the default formatter or a JavaScript function was used.
        blocks?: [...],
        // The SmartBlock configuration received. 
        // Defined only if a SmartBlock was used.
        smartblock?: {
            param: "srcUid" | "srcName",
            paramValue: "some value"
        }
        uid: "some_uid",
    },
    error: null | Error, // The error thrown, if any
    page: {
        new: true | false, // Indicates if the Roam page was created during the operation
        title: "@citekey", // The title of the Roam page
        uid: "some_uid" // The UID of the Roam page
    },
    raw: {
        item: {...}, // The item's full Zotero metadata
        pdfs: [...], // The item's linked PDFs
        notes: [...] // The item's linked notes/annotations
    },
    success: null | true | false // The outcome of the operation
}

zotero-roam:notes-added

{
    args: {
        // The blocks received for insertion into the page.
        blocks: [...],
        uid: "some_uid",
    },
    error: null | Error, // The error thrown, if any
    page: {
        new: true | false, // Indicates if the Roam page was created during the operation
        title: "@citekey", // The title of the Roam page
        uid: "some_uid" // The UID of the Roam page
    },
    raw: {
        item: {...}, // The item's full Zotero metadata
        notes: [...] // The item's linked notes/annotations
    },
    success: null | true | false // The outcome of the operation
}

zotero-roam:tags-deleted

{
    data: *,
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456", // The path of the targeted library
    tags: ["a tag", "another tag"] // The tags provided to be deleted
}

zotero-roam:tags-modified

{
    args: {
        into: "new tag name", // The value provided to rename the tags with
        tags: ["a tag", "another tag"] // The list of tags provided to be renamed
    },
    data: {
        successful: [...], // The list of items successfully modified in Zotero
        failed: [...] // The failed requests' reason for failing
    },
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456" // The path of the targeted library
}

zotero-roam:update

{
    data: [...] | null, // The data received from the update
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456", // The path of the targeted library
    since: 0, // The version since which items were retrieved
    success: true | false // The outcome of the operation,
    type: "items"|"collections" // The type of data that was updated
}

zotero-roam:write

{
    args: {
        collections: [...], // The collections provided to be added to the items
        items: [...], // The items received to be added to Zotero
        tags: [...] // The tags provided to be added to the items
    },
    data: {
        successful: [...], // The items that were successfully added to Zotero
        failed: [...] // The items that could not be added to Zotero
    },
    error: null | AxiosError, // The error thrown, if any
    library: "users/123456" // The path of the targeted library
}