⚡ AutoSponsor — InvenTree Plugin

Automatically link and synchronize Manufacturer parts to Supplier parts for sponsored manufacturers with zero overhead.

---

Overview

AutoSponsor is a plugin for InvenTree designed to bridge the gap between manufacturer part definitions and supplier sourcing. For organizations that have sponsor manufacturers or direct supply partnerships, this plugin completely automates the manual work of matching and creating supplier parts.

It runs in two distinct, complementary modes:

1. Reactive (Zero-Touch): Automatically detects newly saved manufacturer parts. If their manufacturer is on your sponsor list, it instantly creates a corresponding SupplierPart and flags the manufacturer company as a supplier.
2. Proactive (Global Sync): A background-threaded sync engine that audits your entire database against your current sponsor mapping, automatically resolving discrepancies by adding missing links and soft-deactivating stale ones.

---

Key Features

🔄 Reactive Auto-Linking

• Signal-Driven: Hooked into Django’s post_save signal on ManufacturerPart to capture part creation events in real-time.
• Instant Sourcing: Automatically flags the manufacturer company as a Supplier if not already configured, and instantly generates a linked SupplierPart with the correct SKU/MPN and description.

⚙️ Proactive Background Sync Engine

• Full Database Auditing: Evaluates all existing manufacturer parts against the configuration.
• Daemonized Threading: Large sync operations are dispatched to a background thread (threading.Thread(daemon=True)), ensuring that the InvenTree web server never hangs or times out.
• State & Progress Tracking: Real-time job statistics are cached in-memory and served via lightweight JSON REST endpoints.

🛡️ Strict Data Safety Guarantees

• Soft-Deactivation Only: To protect your historical records, purchase orders, and audit trails, the sync engine never hard-deletes SupplierPart records. Stale parts are gracefully deactivated (active = False).
• Plugin Isolation: The plugin only modifies or deactivates SupplierPart entries that it originally created, identified via a secure description sentinel: "Auto-generated Sponsorship Link".
• Purchase Order Safeguard: Before deactivating any stale link, the engine checks for open/active Purchase Order lines. If any are found, the deactivation is aborted, logged as a warning, and highlighted on the dashboard.

---

Installation

UI Installation (Recommended)

You can install the plugin directly through the InvenTree web interface:

1. Navigate to Settings -> Plugins in InvenTree.
2. Click on the Install Plugin button.
3. Fill in the installation form:
   • Package Name: inventree-auto-sponsor
   • Source URL: git+https://github.com/0neShot/AutoSponsor.git#egg=inventree-auto-sponsor
4. Click Install.
5. Restart your InvenTree server containers:

   docker restart inventree-server inventree-worker

6. Enable the plugin via the Admin → Plugins configuration list.

---

Configuration

Navigate to InvenTree → Admin → Plugins → AutoSponsor → Settings to customize:

Setting	Type	Default	Description
SPONSOR_LIST	String	"Würth Elektronik"	Comma-separated list of manufacturer names (e.g. "Würth Elektronik, Texas Instruments"). Matches are case-insensitive.
CLEANUP_STALE_ON_SYNC	Boolean	True	Automatically soft-deactivates SupplierPart entries for manufacturers that were removed from your sponsor list during a full sync.

---

Usage & Workflow

1. Zero-Touch Sourcing (Reactive)

When you add or import a new ManufacturerPart (e.g., using SmartParts or standard admin interfaces) under a sponsored manufacturer (e.g. Würth Elektronik):

1. InvenTree saves the manufacturer part.
2. AutoSponsor intercepts the event, flags Würth Elektronik as a supplier in InvenTree, and links a new SupplierPart to the main part with the SKU matching the MPN.
3. The part is instantly purchase-ready.

2. Manual Global Sync (Proactive)

When you update your sponsor list, or want to audit a newly imported database:

1. Open the Auto Sponsor Linker Dashboard (/plugin/autosponsor/).
2. Click Start Sync or toggle options like "Cleanup Stale Links".
3. Watch the progress bar in real-time as the background thread processes every manufacturer part in the database.
4. Review the detailed log table at the bottom of the page showing exact actions taken for each part.

---

REST API Reference

The plugin registers several API endpoints under the namespace /plugin/autosponsor/api/:

1. Trigger Full Sync

• URL: /plugin/autosponsor/api/sync/run/
• Method: POST
• Permission required: company.change_company
• Payload (JSON, optional):

  {
    "cleanup_stale": true
  }

• Response:

  {
    "success": true,
    "job_id": "a1b2c3d4",
    "message": "Sync started for 2 sponsor(s).",
    "sponsors": ["Würth Elektronik", "Texas Instruments"]
  }

2. Get Job Status

• URL: /plugin/autosponsor/api/sync/status/<job_id>/
• Method: GET
• Response:

  {
    "job_id": "a1b2c3d4",
    "status": "completed",
    "started_at": "2026-05-30T13:45:00.123456",
    "completed_at": "2026-05-30T13:45:05.654321",
    "total_manufacturer_parts": 1420,
    "processed": 1420,
    "progress_percent": 100,
    "created": 15,
    "already_exist": 1400,
    "deactivated": 5,
    "skipped": 0,
    "errors": 0,
    "error_details": [],
    "results": [
      {
        "manufacturer_part_id": 12,
        "mpn": "744311100",
        "part_name": "Inductor 10uH 2.5A",
        "manufacturer_name": "Würth Elektronik",
        "action": "created",
        "success": true,
        "message": "Created SupplierPart #56"
      }
    ]
  }

3. Fetch Pre-flight Statistics

• URL: /plugin/autosponsor/api/sync/stats/
• Method: GET
• Response:

  {
    "sponsors": ["Würth Elektronik"],
    "stats": {
      "total_manufacturer_parts": 1420,
      "sponsor_parts_ok": 1400,
      "sponsor_parts_missing": 20,
      "stale_supplier_parts": 5,
      "unmapped_manufacturers": ["Samsung", "Yageo"]
    }
  }

4. Fetch Sync History

• URL: /plugin/autosponsor/api/sync/jobs/
• Method: GET
• Response: Returns a history list of all sync jobs executed since the plugin server started.

---

Directory Structure

InventreeAutoSponsor/
├── setup.py                          # Setuptools packaging script
├── MANIFEST.in                       # Asset packaging manifest
├── README.md                         # This documentation file
├── CHANGELOG.md                      # Version history
├── LICENSE                           # MIT License
├── __init__.py                       # Package initializer
│
└── inventree_auto_sponsor/           # Main source package
    ├── __init__.py                   # Core initializer & crash-safe loader
    ├── plugin.py                     # Main plugin class, settings & signal listener
    ├── sync_engine.py                # Threaded background sync manager & data safety rules
    ├── views.py                      # Django dashboard rendering & JSON API endpoints
    │
    ├── static/                       # Static frontend assets
    │   └── inventree_auto_sponsor/ui/
    │       └── autosponsor_panel.js  # Contextual UI injection panel script
    │
    └── templates/                    # Django-rendered HTML templates
        └── inventree_auto_sponsor/
            └── dashboard.html        # Interactive admin sync control dashboard

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

Credits

Developed with passion by 0neShot / StarkStrom Augsburg e.V. Powered by InvenTree.