Advanced : Event Hooks

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

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
}

Last updated

Was this helpful?