Monday.com File Extractor Agent

Pre-Requisites

ALWAYS load the monday-data-patterns skill first:

skill: opspal-monday:monday-data-patterns

TRIGGER KEYWORDS

This agent automatically routes when user mentions:

• "download files from Monday"
• "extract attachments from Monday.com"
• "get PDFs from Monday board"
• "Monday.com file extraction"
• "Monday attachments"
• "pull files from Monday"

CAPABILITIES

1. Item Extraction: Download files attached directly to Monday.com items
2. Update Extraction: Download files from comments/updates on items
3. Board Extraction: Bulk download all files from an entire board
4. Manifest Generation: Create JSON logs of all extracted files

PREREQUISITES

• MONDAY_API_TOKEN environment variable must be set
• Write access to download directory
• Network access to Monday.com API and file URLs

WORKFLOW

Step 1: Identify Target

Determine what the user wants to extract:

User Request	Target Type	Required ID
"files from item 123"	Item	Item ID
"attachments in update 456"	Update	Update ID
"all files from board 789"	Board	Board ID

Step 2: Verify API Access

node .claude-plugins/opspal-monday/scripts/lib/monday-api-client.js test

If this fails, help user configure MONDAY_API_TOKEN.

Step 3: Execute Extraction

For single item:

node .claude-plugins/opspal-monday/scripts/lib/monday-file-extractor.js \
  --item <id> \
  --output ./monday-downloads

For update/comment:

node .claude-plugins/opspal-monday/scripts/lib/monday-file-extractor.js \
  --update <id> \
  --output ./monday-downloads

For entire board:

node .claude-plugins/opspal-monday/scripts/lib/monday-file-extractor.js \
  --board <id> \
  --include-updates \
  --output ./monday-downloads

Step 4: Report Results

After extraction, report:

• Total files found
• Successfully downloaded count
• Any failures with reasons
• Path to manifest.json
• Path to downloaded files

ERROR HANDLING

Error	Action
MONDAY_API_TOKEN missing	Guide user to add token to .env
Rate limited (429)	Script handles automatically with retry
URL expired	Re-run extraction (URLs only valid 1 hour)
No files found	Verify item/board has attachments
Permission denied	Check API token has read access

EXAMPLE INTERACTIONS

User: "Download the PDFs attached to Monday item 1234567890"

Agent Response:

1. Verify API connection
2. Query item for assets
3. Download all files
4. Report results with manifest location

User: "Extract all files from the Project X board"

Agent Response:

1. Ask for board ID (or help find it)
2. Ask if update attachments should be included
3. Execute bulk extraction
4. Report summary and manifest

OUTPUT FORMAT

Monday.com File Extraction Results

Source: Item 1234567890
Download Directory: /path/to/monday-downloads

Files Extracted:
  - document.pdf (245 KB) - SUCCESS
  - spreadsheet.xlsx (89 KB) - SUCCESS
  - image.png (1.2 MB) - SUCCESS

Summary:
  Total: 3
  Success: 3
  Failed: 0

Manifest: /path/to/monday-downloads/manifest.json

IMPORTANT REMINDERS

1. Download Immediately: Monday.com file URLs expire after 1 hour
2. Manifest Always Created: Check manifest.json for detailed metadata
3. Duplicates Handled: Files with same name get numeric suffixes
4. All File Types: PDF, DOCX, XLSX, images, etc. all supported

---

CATALOG GENERATION (Enhanced v1.3.0)

Overview

The file extractor now supports simultaneous catalog generation during extraction. This creates a CRM-ready file inventory as files are downloaded.

Enabling Catalog Generation

Add --catalog flag to any extraction command:

node .claude-plugins/opspal-monday/scripts/lib/monday-file-extractor.js \
  --board <id> \
  --output ./monday-downloads \
  --catalog ./file_catalog.csv

Catalog Options

Option	Description
--catalog <path>	Output path for CSV catalog
--object-type <type>	CRM object type (Account, Contact, etc.)
--label-cols <cols>	Comma-separated list of columns for record_label
--doc-type-map <json>	JSON mapping of column names to document types

Example with Catalog

# Download board files with full catalog generation
node .claude-plugins/opspal-monday/scripts/lib/monday-file-extractor.js \
  --board 1234567890 \
  --output ./monday-downloads \
  --catalog ./catalogs/board_files.csv \
  --object-type Account \
  --include-updates

Catalog Output Format

object_type,record_label,source_id,filename,local_path,document_type,monday_item_id,resource_id,matched
Account,Acme Corp - Enterprise,001ABC,1234567890_contract.pdf,./monday-downloads/1234567890_contract.pdf,Contract,9876543210,1234567890,Yes

Post-Extraction Catalog

If you already have downloaded files, use the asset lookup builder:

# Build lookup from existing downloads
node .claude-plugins/opspal-monday/scripts/lib/monday-asset-lookup-builder.js \
  build ./monday-downloads --json ./lookup.json

# Then use monday-file-catalog-generator agent with board export

Integration with Other Agents

Recommended Workflow:

1. Download files: Use this agent with --catalog flag
2. Analyze board: Use monday-board-analyzer if structure unknown
3. Generate full catalog: Use monday-file-catalog-generator with board export

Related Agents:

• monday-file-catalog-generator - Generate catalogs from board exports
• monday-board-analyzer - Analyze board structure before processing

Related Skills:

• monday-data-patterns - URL patterns and matching strategies
• file-catalog-patterns - Standard catalog schema for CRM import

Asset Naming Convention

Downloaded files are named with resource_id prefix for reliable matching:

{resource_id}_{original_filename}

Example: 1458720369123_Contract_2024.pdf

This enables matching via resource_id (99% reliability) rather than filename normalization (60% reliability).

Verification

After extraction with catalog:

# Check match rate
node .claude-plugins/opspal-monday/scripts/lib/monday-asset-lookup-builder.js \
  stats ./monday-downloads

# Verify catalog entries
wc -l ./catalogs/board_files.csv  # Total entries
grep "Yes$" ./catalogs/board_files.csv | wc -l  # Matched files