wentorai/zotero-actions-tags-guide

Zotero Actions & Tags Guide

Overview

Zotero Actions & Tags is a powerful Zotero plugin that enables workflow automation through event-triggered actions. Define custom rules that execute when items are added, modified, opened, or tagged — such as auto-tagging by collection, running scripts on PDF open, auto-renaming attachments, or sending notifications. Transforms Zotero from a passive reference manager into an active research workflow engine.

Installation

# Download .xpi from GitHub releases
# In Zotero 7: Tools → Add-ons → Install Add-on From File

Core Concepts

### Event → Condition → Action

**Events** (triggers):
- Item added to library
- Item added to collection
- Item modified
- Tag added/removed
- Attachment opened
- Item selected

**Conditions** (filters):
- Item type (article, book, etc.)
- Collection membership
- Tag presence/absence
- Field value match (regex)
- Date range

**Actions** (responses):
- Add/remove tags
- Set field values
- Run JavaScript
- Open URLs
- Copy to clipboard
- Show notifications

Action Examples

Auto-Tag by Collection

{
  "name": "Auto-tag ML papers",
  "event": "add_to_collection",
  "condition": {
    "collection": "Machine Learning"
  },
  "actions": [
    {"type": "add_tag", "tag": "#ml"},
    {"type": "add_tag", "tag": "#to-read"}
  ]
}

Mark as Read on Open

{
  "name": "Track reading",
  "event": "open_attachment",
  "condition": {
    "attachment_type": "application/pdf"
  },
  "actions": [
    {"type": "remove_tag", "tag": "#to-read"},
    {"type": "add_tag", "tag": "#reading"},
    {"type": "set_field", "field": "extra",
     "value": "LastOpened: ${date}"}
  ]
}

Auto-Prioritize Highly Cited

{
  "name": "Flag high-impact",
  "event": "item_modified",
  "condition": {
    "field": "extra",
    "regex": "Citations:\\s*(\\d{3,})"
  },
  "actions": [
    {"type": "add_tag", "tag": "#high-impact"},
    {"type": "add_tag", "tag": "#priority"}
  ]
}

Custom Script Action

// Run custom JavaScript on trigger
// Example: Auto-format author names
{
  "name": "Format authors",
  "event": "item_added",
  "action": {
    "type": "script",
    "code": `
      const creators = item.getCreators();
      // Log to Zotero debug console
      Zotero.debug('New item by: ' +
        creators.map(c => c.lastName).join(', '));
    `
  }
}

Workflow Recipes

Reading Pipeline

[
  {
    "name": "New → To-Read",
    "event": "item_added",
    "actions": [{"type": "add_tag", "tag": "#to-read"}]
  },
  {
    "name": "To-Read → Reading",
    "event": "open_attachment",
    "condition": {"has_tag": "#to-read"},
    "actions": [
      {"type": "remove_tag", "tag": "#to-read"},
      {"type": "add_tag", "tag": "#reading"}
    ]
  },
  {
    "name": "Reading → Done",
    "event": "tag_added",
    "condition": {"tag": "#done"},
    "actions": [
      {"type": "remove_tag", "tag": "#reading"}
    ]
  }
]

Auto-Organization

[
  {
    "name": "Tag by journal",
    "event": "item_added",
    "condition": {
      "field": "publicationTitle",
      "regex": "Nature|Science|Cell"
    },
    "actions": [
      {"type": "add_tag", "tag": "#top-journal"}
    ]
  },
  {
    "name": "Flag recent papers",
    "event": "item_added",
    "condition": {
      "field": "date",
      "after": "2024-01-01"
    },
    "actions": [
      {"type": "add_tag", "tag": "#recent"}
    ]
  }
]

Configuration

### Settings (Edit → Preferences → Actions & Tags)

- **Enable/disable** individual actions
- **Action priority** — execution order when multiple match
- **Logging** — debug action execution
- **Import/Export** — share action sets with collaborators
- **Keyboard shortcuts** — trigger actions manually

Use Cases

1. Reading workflow: Auto-track reading status via tags
2. Auto-organization: Tag by collection, journal, or date
3. Priority flagging: Highlight high-impact or recent papers
4. Team workflows: Shared tag-based review pipelines
5. Custom scripts: Extend Zotero with JavaScript actions

References

• Zotero Actions & Tags GitHub
• Zotero JavaScript API
• Zotero Plugin Development