Skip to content

Home Information - Your home, your data, organized.

Python

Paperless-ngx integration (ATTRIBUTE_REFERENCE capability) (#375)

Tony C40f932e0889b
diff --git a/docs/Integrations.md b/docs/Integrations.md
index 0ffa6faf..a3679527 100644
--- a/docs/Integrations.md
+++ b/docs/Integrations.md
@@ -14,8 +14,16 @@ enter it.
## Enabling an integration
+Most integrations are configured from the **Connectors** tab on the
+Configure page. Paperless-ngx is configured from the **Content
+Sources** tab instead, because it contributes searchable document
+references rather than importing items — see its own page for the
+walkthrough.
+
+For a Connectors-tab integration:
+
1. In HI, click **CONFIGURE** at the bottom of the screen.
-2. Select the **Integrations** tab.
+2. Select the **Connectors** tab.
3. Open the integrations picker:
- If no integrations are configured yet, click **CONFIGURE
INTEGRATIONS** in the main panel.
@@ -39,6 +47,11 @@ enter it.
- **[HomeBox](integrations/homebox.md)** — home inventory tracking.
Imports HomeBox items as read-only HI items with custom fields and
attached files (manuals, receipts, photos).
+- **[Paperless-ngx](integrations/paperless-ngx.md)** — document
+ management. Does not import items; instead lets you search
+ paperless from inside HI and attach matching documents (warranty
+ PDFs, manuals, receipts) as link references on items and
+ Locations you already have.
More integrations will be added as demand arises. The per-integration
pages each carry their own troubleshooting section that accretes
@@ -46,8 +59,11 @@ real-world fixes over time — start there if something is not working.
## Integrations vs. Data Import
-Integrations on this page are live: HI mirrors the upstream system
-continuously and changes flow in via the update action.
+Most integrations on this page are live: HI mirrors the upstream
+system continuously and changes flow in via the update action.
+Paperless-ngx is a different shape — it contributes attachable
+document references rather than importing items, and it talks to
+paperless only when the operator opens the picker.
A separate feature, [Data Import](DataImport.md), is a one-time
copy with no ongoing upstream link. Some integrations (HomeBox
diff --git a/docs/dev/integrations/integration-guidelines.md b/docs/dev/integrations/integration-guidelines.md
index 295eca35..fa5b2a2a 100644
--- a/docs/dev/integrations/integration-guidelines.md
+++ b/docs/dev/integrations/integration-guidelines.md
@@ -10,12 +10,15 @@ Each integration is a Django app in `hi/services/` directory. The `hi.integratio
- **detail_attrs**: Opaque data blob - only the integration uses this data
### Capability model
-Each integration declares its `IntegrationCapability` set on `IntegrationMetaData.capabilities` (`hi/integrations/enums.py`). Two capabilities exist today:
+Each integration declares its `IntegrationCapability` set on `IntegrationMetaData.capabilities` (`hi/integrations/enums.py`). Three capabilities exist today:
-- **`CONNECT`** — live mirror of an upstream system. Realized by an `IntegrationConnector` subclass returned from `IntegrationGateway.get_connector()`. All four production integrations (HA, ZM, Frigate, HomeBox) declare CONNECT.
-- **`IMPORT`** — one-shot copy of upstream items into HI as locally-owned entities. Realized by an `IntegrationImporter` subclass returned from `IntegrationGateway.get_importer()`. HomeBox is the first integration to declare IMPORT alongside CONNECT (see [`docs/dev/integrations/data-import.md`](data-import.md) for the developer surface).
+- **`CONNECT`** — live mirror of an upstream system. Realized by an `IntegrationConnector` subclass returned from `IntegrationGateway.get_connector()`. All four "Connectors"-tab integrations (HA, ZM, Frigate, HomeBox) declare CONNECT.
+- **`IMPORT`** — one-shot copy of upstream items into HI as locally-owned entities. Realized by an `IntegrationImporter` subclass returned from `IntegrationGateway.get_importer()`. HomeBox is the only integration to declare IMPORT alongside CONNECT today (see [`docs/dev/integrations/data-import.md`](data-import.md) for the developer surface).
+- **`ATTRIBUTE_REFERENCE`** — search-and-attach surface that contributes URL attributes to existing Entity / Location records (no entity import, no live mirror). Realized by an `IntegrationAttributeReferencer` subclass returned from `IntegrationGateway.get_attribute_referencer()`. Paperless-ngx is the only integration to declare ATTRIBUTE_REFERENCE today. ATTRIBUTE_REFERENCE-only integrations are configured on a sibling tab labeled "Content Sources" instead of "Connectors" — the page chrome differs because there's no monitor / sync lifecycle.
-The two abstractions don't share a base class — commonality is composed through shared helpers (`hi/integrations/entity_operations.py`, `hi/integrations/placement_request.py`, etc.). The `connector/` and `importer/` sub-packages live as peers under `hi/integrations/`.
+The three per-capability classes (`IntegrationConnector`, `IntegrationImporter`, `IntegrationAttributeReferencer`) share a common base `CapabilityGateway` (`hi/integrations/capability_gateway.py`). Each declares a `capability` class attribute identifying the `IntegrationCapability` it realizes, and overrides cross-capability concerns: `get_metadata()` (abstract), `get_description()` (operator-facing one-line description), and `get_attribute_actions_template_name()` (optional template fragment for the attribute form's action bar). Capability-specific concerns (sync, import, search) stay on the subclass. Adding a new capability means subclassing `CapabilityGateway`, declaring the `capability` class attribute, and overriding only the methods that apply to the new shape.
+
+The `connector/`, `importer/`, and `referencer/` sub-packages live as peers under `hi/integrations/`.
Per-attribute `IntegrationAttributeType` declarations may carry an optional `capabilities` set to restrict which capability's UI surfaces the attribute. Default is `ALL_CAPABILITIES`.
@@ -79,7 +82,9 @@ Each integration is a self-contained Django app under `hi/services/<integration_
- `monitors.py` — `PeriodicMonitor` subclass(es) for polling and health probes
- `apps.py`, `urls.py`, `views.py` — standard Django wiring
-`<prefix>` is a short integration mnemonic (`hass_`, `zm_`, `hb_`). Keep it consistent across all files within the integration.
+`<prefix>` is a short integration mnemonic (`hass_`, `zm_`, `hb_`, `pl_`). Keep it consistent across all files within the integration.
+
+ATTRIBUTE_REFERENCE-only integrations (paperless-ngx today) don't need all the role-files above — they have no monitors, no sync, no converter, and no manager singleton (the capability has no live state to own). They still ship `integration.py`, `<prefix>_metadata.py`, `<prefix>_client.py`, plus a `<prefix>_referencer.py` for the `IntegrationAttributeReferencer` subclass and `<prefix>_models.py` (or `_constants.py`) for the wire-format strings.
### Centralize wire-format strings
Every integration centralizes its wire-format strings — domain/endpoint names, attribute keys, device-class names, service names, special-state sentinels — in a single class per integration. The exemplar is `HassApi` in `hi/services/hass/hass_models.py`; ZoneMinder's equivalent is `hi/services/zoneminder/constants.py`. The converter, sync, controller, and service composer all import their wire strings from this single source.
@@ -113,17 +118,24 @@ cd src/hi/services
- Set fully qualified name in `apps.py`: `name = 'hi.services.myintegration'`
- Add to `INSTALLED_APPS` in `hi/settings/base.py`
-### 3. Define Integration Type
-Add to `IntegrationType` enum in appropriate enums file
+### 3. Declare Metadata and Capabilities
+Create a module-level `IntegrationMetaData` instance (in `<prefix>_metadata.py`) declaring the integration's `integration_id`, label, logo path, attribute-type enum, and `capabilities` set. The `capabilities` set is what binds the integration to its UI surfaces — CONNECT puts it on the Connectors tab; IMPORT adds it to the Data Import tab; ATTRIBUTE_REFERENCE puts it on the Content Sources tab.
### 4. Create Gateway Class
-Implement `IntegrationGateway` with required methods:
-- `activate(integration_instance)` - Setup and validation
-- `deactivate(integration_instance)` - Cleanup and shutdown
-- `manage(request, integration_instance)` - Management interface
+Implement `IntegrationGateway` (in `integration.py`) with the methods that apply to the declared capabilities:
+
+- `get_metadata()` — return the `IntegrationMetaData` instance. Required.
+- `get_connector()` — return an `IntegrationConnector` subclass instance when CONNECT is advertised; default `None`.
+- `get_importer()` — return an `IntegrationImporter` subclass instance when IMPORT is advertised; default `None`.
+- `get_attribute_referencer()` — return an `IntegrationAttributeReferencer` subclass instance when ATTRIBUTE_REFERENCE is advertised; default `None`.
+- `validate_configuration(integration_attributes)` — schema-only validation of the attribute set. Required (no network operations).
+- `validate_access(integration_attributes, timeout_secs)` — bounded live probe against the configured credentials. Required (used by the configure flow and by health-check helpers).
+- `notify_settings_changed()` — invoked by the framework after the operator saves attributes. Reload your manager / re-init clients here. Default no-op.
-### 5. Register with Factory
-Add gateway mapping in `hi/integrations/integration_factory.py`
+The per-capability work (sync, candidate-listing, search) lives on the capability subclass returned from the matching `get_*` method.
+
+### 5. Auto-Discovery
+No factory registration is needed. `IntegrationManager.discover_defined_integrations()` walks `INSTALLED_APPS` for `hi.services.*` apps, imports each app's `integration.py`, and registers any `IntegrationGateway` subclass it finds. As long as the app is in `INSTALLED_APPS` and `integration.py` exposes a gateway subclass, it shows up automatically.
### 6. Write Per-Integration Documentation
Every user-configured integration MUST ship with two short docs based
@@ -152,15 +164,13 @@ the user-facing landing page at [`docs/Integrations.md`](../../Integrations.md).
## Gateway Implementation Patterns
### Gateway Methods
-**activate()**: Validate config, validate access, initialize resources
-**deactivate()**: Clean up entities, close connections, update status
-**manage()**: Handle POST actions (sync, test, config), render management UI
+See "4. Create Gateway Class" above for the full method list. Highlights:
+
+- **`validate_configuration(attrs)`** — schema check only. Returns `IntegrationValidationResult`. Must not perform network operations.
+- **`validate_access(attrs, timeout_secs)`** — live probe against the proposed credentials. Returns `ConnectionTestResult`. Must respect the timeout. Used at attribute-save time and before relaunching monitors on Resume.
+- **`get_<capability>()`** — return the capability instance the framework consults for capability-specific work. Returning `None` opts the integration out of that capability's UI surfaces even if the capability is in `IntegrationMetaData.capabilities` (defensive disable).
-### Return Format
-All gateway methods return dict with:
-- `status`: 'success' or 'error'
-- `message`: User-friendly status message
-- `redirect`: Optional redirect URL
+The framework owns the surrounding workflow (configure modal, save lifecycle, sync UI, picker UI). The gateway and its capability instances supply the integration-specific bits.
## Integration Patterns
@@ -175,27 +185,29 @@ All gateway methods return dict with:
- **Cleanup**: Remove entities no longer in external system
### Error Handling
-Custom exception hierarchy:
-- `IntegrationError` - Base class
-- `ConnectionError` - Network/connectivity issues
-- `AuthenticationError` - Auth/authorization failures
-- `DataValidationError` - Invalid data from external source
+Custom exception hierarchy (`hi/integrations/exceptions.py`):
+- `IntegrationError` — base class.
+- `IntegrationDisabledError` — operation attempted against a disabled integration.
+- `IntegrationAttributeError` — required attribute missing or invalid.
+- `IntegrationConnectionError` — upstream unreachable / auth rejected during a live operation.
## Key Base Classes & Modules
### Core Classes
-- `hi.integration.integration_gateway.IntegrationGateway` - Base gateway class
-- `hi.utils.singleton.Singleton` - Singleton pattern for gateways
-- `hi.integrations.enums.IntegrationStatus` - Status enumeration
-
-### Factory Pattern
-- `hi.integrations.integration_factory.py` - Gateway registration
-- `hi.integrations.exceptions.py` - Custom exception classes
+- `hi.integrations.integration_gateway.IntegrationGateway` — per-integration entry point; auto-discovered from each `hi.services.*` app's `integration.py`.
+- `hi.integrations.capability_gateway.CapabilityGateway` — shared base of the three per-capability classes; carries `capability`, `get_metadata`, `get_description`, `get_attribute_actions_template_name`.
+- `hi.integrations.connector.integration_connector.IntegrationConnector` — CONNECT capability surface (sync, monitor, controller, health).
+- `hi.integrations.importer.integration_importer.IntegrationImporter` — IMPORT capability surface (candidate list, run, discard).
+- `hi.integrations.referencer.integration_referencer.IntegrationAttributeReferencer` — ATTRIBUTE_REFERENCE capability surface (search).
+- `hi.integrations.integration_manager.IntegrationManager` — discovery and lifecycle singleton.
+- `hi.apps.common.singleton.Singleton` — singleton base used by `IntegrationManager` and many per-integration managers.
### Example Integrations
-- `hi.services.hass/` - Home Assistant integration
-- `hi.services.zoneminder/` - ZoneMinder integration
-- `hi.services.homebox/` - HomeBox integration
+- `hi.services.hass/` — Home Assistant (CONNECT).
+- `hi.services.zoneminder/` — ZoneMinder (CONNECT).
+- `hi.services.frigate/` — Frigate (CONNECT).
+- `hi.services.homebox/` — HomeBox (CONNECT + IMPORT).
+- `hi.services.paperless/` — paperless-ngx (ATTRIBUTE_REFERENCE-only). Slimmer file layout — no manager singleton, no monitors, no converter — because the capability has no live state to own.
## Related Documentation
- [Service Patterns](service-patterns.md)
diff --git a/docs/dev/integrations/paperless-ngx.md b/docs/dev/integrations/paperless-ngx.md
new file mode 100644
index 00000000..6c917873
--- /dev/null
+++ b/docs/dev/integrations/paperless-ngx.md
@@ -0,0 +1,56 @@
+# Paperless-ngx
+
+## Capability shape
+
+Paperless declares only the `ATTRIBUTE_REFERENCE` capability — no
+connector, no importer, no manager singleton, no monitors. The
+gateway returns a referencer, and the referencer translates
+paperless's documents-search response into `AttributeReferenceResult`
+rows. Per-search HTTP happens inline; there is no cached client.
+
+## Key design decisions
+
+- **Thumbnail proxy, not URL passthrough**. The picker embeds
+ `<img src=…>` inside HI, so the browser cannot supply the
+ paperless API token. The referencer emits HI's proxy URL as
+ `thumbnail_url`, and the proxy view fetches upstream with the
+ configured token. Same problem HomeBox solves with
+ `homebox_attachment_proxy`.
+- **Source URL is NOT proxied**. The persisted `source_url` is
+ paperless's own per-document web URL. Operators authenticate with
+ paperless's own session when they click — same UX as cut-and-paste.
+ Proxying would couple the link's lifetime to HI's session.
+- **No manager singleton**. ATTRIBUTE_REFERENCE has no monitors and
+ no cached state, so there is no `pl_manager.py`. The client is
+ built per-call from the stored attributes; `build_client` is the
+ entry point to refactor through if a reason to cache emerges.
+- **Snippet extraction client-side**. Paperless's search endpoint
+ returns full document `content` per hit, not pre-built excerpts.
+ The referencer extracts a short window around the matched query,
+ falling back to a leading window when the query does not match
+ verbatim (e.g., paperless matched on a stemmed form).
+- **Single deployment**. The framework discovers one paperless
+ integration per app directory. Multiple paperless instances are
+ not supported; if that ever matters, the gateway's metadata id
+ and the proxy URL would both need to become per-instance.
+
+## Upstream surfaces touched
+
+Wire-format strings live in `pl_models.py`; the integration touches
+three paperless endpoints — the documents-search API, the per-document
+thumbnail API (streamed through HI's proxy view), and the per-document
+web URL (persisted unchanged as `source_url`). Auth is
+`Authorization: Token <value>` on every upstream call.
+
+## Testing
+
+Tests live in `src/hi/services/paperless/tests/` and mock all upstream
+HTTP. For end-to-end exercise without a real paperless install, use
+the simulator at `src/hi/simulator/services/paperless/` — it supports
+parametric response shapes (result count, mime mix, thumbnails on/off,
+snippets on/off, artificial latency).
+
+## References
+
+- Upstream API: <https://docs.paperless-ngx.com/api/>
+- Capability framework: [Integration Guidelines](integration-guidelines.md)
diff --git a/docs/integrations/paperless-ngx.md b/docs/integrations/paperless-ngx.md
new file mode 100644
index 00000000..d93e62ab
--- /dev/null
+++ b/docs/integrations/paperless-ngx.md
@@ -0,0 +1,118 @@
+<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">
+
+# Paperless-ngx
+
+## Overview
+
+This integration lets **Home Information (HI)** search a
+**paperless-ngx (paperless)** server and attach documents from it as
+references on existing HI items and Locations. Unlike the other
+integrations on the integrations page, paperless does not import any
+items into HI — it contributes searchable references that get saved
+as link attributes (title + URL) on items you already have. Typical
+use case: link a dishwasher's warranty PDF, a thermostat's manual,
+or a property's deed to the matching HI item or Location.
+
+## Prerequisites
+
+- A reachable paperless-ngx server (1.x or 2.x). The HI server must
+ be able to reach paperless over HTTP or HTTPS at the URL you will
+ configure; cross-origin browser fetches are not used, so reverse
+ proxies are fine as long as the HI server can reach the address.
+- A paperless user account with an API token. The token's user
+ determines which documents the integration can see — give it a
+ user that has the document-list permissions you want exposed
+ through HI.
+
+## Obtaining credentials
+
+1. Sign in to paperless as the user whose document visibility you
+ want to expose through HI.
+2. Open the user's profile page (top-right user menu in the
+ paperless web UI).
+3. Click **Create token** (or **Regenerate token** if one already
+ exists). Copy the generated token.
+4. Keep paperless's per-user / per-group permissions in mind — the
+ token sees only what its user can see.
+
+## Configuration values
+
+| Field | What to enter | Notes |
+|-------|---------------|-------|
+| API URL | Base URL of your paperless server, e.g. `https://paperless.example.com/` | Either form works (trailing slash optional). Use the same scheme + host you use in the browser. The integration appends `/api/documents/` and other paths internally. |
+| API Token | The token copied from paperless's user profile | Sent as `Authorization: Token <value>` on every upstream call. Treated as a secret. |
+
+## Setup walkthrough
+
+Paperless is configured from the **Content Sources** tab on the
+Configure page (it is not on the Connectors tab — see
+[Integrations](../Integrations.md) for the distinction).
+
+1. In HI, click **CONFIGURE** at the bottom of the screen.
+2. Select the **Content Sources** tab.
+3. Choose **Paperless-ngx** and fill in the two configuration values
+ above. **Test Connection** issues a small probe against your
+ paperless server and reports back; **Save** records the values.
+
+Once paperless is configured, use it from any item or Location edit
+page:
+
+1. Click **Link Content** in the action bar to open the picker.
+2. Type a query, tick the documents you want, and click **Add
+ Links** (the button shows the running count, e.g. "Add 3 Links").
+
+Each selection becomes a new attribute on the item — the attribute's
+name is the document title and its value is the per-document URL on
+your paperless server. Clicking the saved link later takes you to
+paperless directly (you authenticate with paperless's own session).
+
+## Troubleshooting
+
+### Test Connection fails with "Paperless auth rejected"
+
+The token was rejected (HTTP 401 or 403). Verify the token in
+paperless's user profile and re-paste it. Tokens are sensitive to
+leading/trailing whitespace.
+
+### Test Connection fails with "Paperless unreachable"
+
+The HI server cannot reach the configured URL. Check the scheme
+(`http` vs. `https`), hostname, and port; from a shell on the HI
+server, try `curl -I <API URL>` to confirm reachability.
+
+### Picker returns no results
+
+Confirm the query against paperless's own search UI as the same user
+whose token you configured. If paperless's search returns nothing
+for the same query, the token's user lacks visibility into the
+documents you expect. If paperless's UI returns results but the
+picker does not, increase the per-page count in the picker.
+
+### Thumbnails do not load in the picker
+
+Thumbnails are fetched through HI so the browser does not need a
+paperless session. If thumbnails appear broken, check the HI logs
+for `Paperless thumb proxy` warnings — the upstream URL or token
+is likely misconfigured. The picker still works without thumbnails;
+the fallback icon is used.
+
+### Saved links open paperless's login page
+
+The saved link points to paperless's per-document URL; clicking it
+takes you to paperless directly, not through HI. You authenticate
+with paperless's own session. If you are not signed in to paperless
+when you click, paperless will prompt you.
+
+## Known limitations
+
+- Saved attribute links point to your paperless server's URL. If you
+ later disable or reconfigure paperless (different host), those
+ saved links will not automatically follow.
+- There is no continuous sync. The integration only fetches when an
+ operator opens the picker and searches. No background polling, no
+ monitor health UI.
+- The integration does not create HI items of its own. Documents are
+ only attachable to items / Locations that already exist in HI.
+- Search uses paperless's own full-text engine; ranking and matching
+ semantics are whatever paperless provides. The picker preserves
+ paperless's ordering.
diff --git a/src/hi/apps/attribute/templatetags/attribute_extras.py b/src/hi/apps/attribute/templatetags/attribute_extras.py
index cad883a0..497af1e1 100644
--- a/src/hi/apps/attribute/templatetags/attribute_extras.py
+++ b/src/hi/apps/attribute/templatetags/attribute_extras.py
@@ -1,24 +1,29 @@
import re
+from urllib.parse import urlparse
from django import template
-from django.core.exceptions import ValidationError
-from django.core.validators import URLValidator
from django.utils.html import escape, format_html
from django.utils.safestring import mark_safe
register = template.Library()
-_url_validator = URLValidator()
_URL_IN_TEXT_PATTERN = re.compile(r'https?://[^\s<>"\']+')
_TRAILING_PUNCTUATION = '.,;:!?)]}'
def _is_valid_url(value):
- """Return True when value passes Django URL validation."""
+ """Return True when value looks like an http(s) URL with a host.
+
+ Single-label intranet hostnames (e.g. ``http://cassandra:4100/…``)
+ are accepted; Django's URLValidator rejects those because they
+ lack a TLD, but they're common on LANs.
+ """
try:
- _url_validator(value)
- except ValidationError:
+ parsed = urlparse(value)
+ except ValueError:
+ return False
+ if parsed.scheme not in ('http', 'https'):
return False
- return True
+ return bool(parsed.netloc)
def _split_url_and_trailing_punctuation(candidate):
diff --git a/src/hi/apps/attribute/tests/test_templatetags.py b/src/hi/apps/attribute/tests/test_templatetags.py
index 7f7f5a1f..1e56d460 100644
--- a/src/hi/apps/attribute/tests/test_templatetags.py
+++ b/src/hi/apps/attribute/tests/test_templatetags.py
@@ -185,8 +185,8 @@ class TestAttributeTextUrlFilters(TestCase):
def test_attribute_text_has_url_detects_url_with_wrapping_punctuation(self):
self.assertTrue(attribute_text_has_url("Open this (https://example.com/docs)."))
- def test_attribute_text_has_url_ignores_invalid_http_candidates(self):
- self.assertFalse(attribute_text_has_url("Broken candidate: https://bad"))
+ def test_attribute_text_has_url_accepts_single_label_intranet_host(self):
+ self.assertTrue(attribute_text_has_url("Internal: http://cassandra:4100/documents/8/details/"))
def test_attribute_text_linkify_renders_multiple_links_inline(self):
rendered = attribute_text_linkify(
@@ -217,9 +217,15 @@ class TestAttributeTextUrlFilters(TestCase):
rendered,
)
- def test_attribute_text_linkify_does_not_link_invalid_candidates(self):
- rendered = attribute_text_linkify('Broken: https://bad and valid: https://example.com')
- self.assertIn('Broken: https://bad', rendered)
+ def test_attribute_text_linkify_links_single_label_intranet_host(self):
+ rendered = attribute_text_linkify(
+ 'Intranet: http://cassandra:4100/documents/8/details/ and public: https://example.com'
+ )
+ self.assertIn(
+ '<a href="http://cassandra:4100/documents/8/details/" target="_blank" rel="noopener noreferrer">'
+ 'http://cassandra:4100/documents/8/details/</a>',
+ rendered,
+ )
self.assertIn(
'<a href="https://example.com" target="_blank" rel="noopener noreferrer">https://example.com</a>',
rendered,
diff --git a/src/hi/apps/common/templatetags/icons.py b/src/hi/apps/common/templatetags/icons.py
index a9ac3342..f4f27e04 100644
--- a/src/hi/apps/common/templatetags/icons.py
+++ b/src/hi/apps/common/templatetags/icons.py
@@ -48,6 +48,7 @@ AVAILABLE_ICONS = {
'info-circle',
'layers',
'lightbulb',
+ 'link',
'lock',
'map-pin',
'minus-circle',
diff --git a/src/hi/apps/config/enums.py b/src/hi/apps/config/enums.py
index 393edd55..f893b657 100644
--- a/src/hi/apps/config/enums.py
+++ b/src/hi/apps/config/enums.py
@@ -16,11 +16,12 @@ class ConfigPageType(LabeledEnum):
self.url_name = url_name
return
- SETTINGS = ('Settings' , '' , 'config_settings' )
- INTEGRATIONS_CONNECT = ('Integrations' , '' , 'integrations_connect_home' )
- EVENTS = ('Triggers' , '' , 'event_definitions' )
- INTEGRATIONS_IMPORT = ('Data Import' , '' , 'integrations_import_home' )
- SYSTEM_INFO = ('System Info' , '' , 'system_info' )
+ SETTINGS = ('Settings' , '' , 'config_settings' )
+ EVENTS = ('Triggers' , '' , 'event_definitions' )
+ INTEGRATIONS_CONNECT = ('Connectors' , '' , 'integrations_connect_home' )
+ INTEGRATIONS_REFERENCE = ('Content Sources' , '' , 'integrations_reference_home' )
+ INTEGRATIONS_IMPORT = ('Data Import' , '' , 'integrations_import_home' )
+ SYSTEM_INFO = ('System Info' , '' , 'system_info' )
@classmethod
def default(cls):
diff --git a/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html b/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html
index cf7d69ae..b50c6aa6 100644
--- a/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html
+++ b/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html
@@ -1,9 +1,22 @@
{% extends "attribute/components/edit_content_body.html" %}
+{% load icons %}
+{% load integration_tags %}
{% comment %}
Entity V2 Content Body Fragment
Extends the generic attribute edit content body with entity-specific field layout.
{% endcomment %}
+{% block additional_actions %}
+{% has_attribute_referencers as has_referencers %}
+{% if has_referencers and attr_page_context.allow_internal_attributes %}
+<a href="{% url 'integrations_attribute_reference_picker' %}?item_type=ENTITY&item_id={{ attr_item_context.owner.id }}"
+ data-async="modal"
+ class="btn btn-sm btn-outline-primary mb-0">
+ {% icon "link" size="sm" css_class="hi-icon-left" %}Link Content
+</a>
+{% endif %}
+{% endblock %}
+
{% block owner_fields %}
<!-- Entity-specific fields: Name and Type fields for modal editing -->
<div class="row">
@@ -44,4 +57,4 @@ Extends the generic attribute edit content body with entity-specific field layou
</div>
</div>
</div>
-{% endblock %}
\ No newline at end of file
+{% endblock %}
diff --git a/src/hi/apps/location/templates/location/panes/location_edit_content_body.html b/src/hi/apps/location/templates/location/panes/location_edit_content_body.html
index ff7b5550..0773788d 100644
--- a/src/hi/apps/location/templates/location/panes/location_edit_content_body.html
+++ b/src/hi/apps/location/templates/location/panes/location_edit_content_body.html
@@ -1,9 +1,22 @@
{% extends "attribute/components/edit_content_body.html" %}
+{% load icons %}
+{% load integration_tags %}
{% comment %}
Location V2 Content Body Fragment
Extends the generic attribute edit content body with location-specific field layout.
{% endcomment %}
+{% block additional_actions %}
+{% has_attribute_referencers as has_referencers %}
+{% if has_referencers and attr_page_context.allow_internal_attributes %}
+<a href="{% url 'integrations_attribute_reference_picker' %}?item_type=LOCATION&item_id={{ attr_item_context.owner.id }}"
+ data-async="modal"
+ class="btn btn-sm btn-outline-primary mb-0">
+ {% icon "link" size="sm" css_class="hi-icon-left" %}Link Content
+</a>
+{% endif %}
+{% endblock %}
+
{% block owner_fields %}
<!-- Location-specific fields: Only name field for modal editing -->
<div class="row">
@@ -24,4 +37,4 @@ Extends the generic attribute edit content body with location-specific field lay
</div>
</div>
</div>
-{% endblock %}
\ No newline at end of file
+{% endblock %}
diff --git a/src/hi/constants.py b/src/hi/constants.py
index a97e9086..faa6b7b6 100644
--- a/src/hi/constants.py
+++ b/src/hi/constants.py
@@ -161,6 +161,39 @@ DIVID = {
# Entity Picker - Filter values
'ENTITY_PICKER_FILTER_ALL': 'all',
+ # ATTRIBUTE_REFERENCE picker — DOM classes / data attributes
+ # / wire-format field names shared between the picker templates,
+ # the picker views, and attr-picker.js. Mirror these in
+ # ``src/hi/static/js/main.js`` (``Hi.ATTR_PICKER_*``).
+ 'ATTR_PICKER_ROOT_CLASS': 'hi-attr-picker',
+ 'ATTR_PICKER_CHIPS_CLASS': 'hi-attr-picker-chips',
+ 'ATTR_PICKER_CHIPS_EMPTY_CLASS': 'hi-attr-picker-chips-empty',
+ 'ATTR_PICKER_CHIP_REMOVE_CLASS': 'hi-attr-picker-chip-remove',
+ 'ATTR_PICKER_RESULTS_CLASS': 'hi-attr-picker-results',
+ 'ATTR_PICKER_SEARCH_FORM_CLASS': 'hi-attr-picker-search-form',
+ 'ATTR_PICKER_ATTACH_FORM_CLASS': 'hi-attr-picker-attach-form',
+ 'ATTR_PICKER_ATTACH_BTN_CLASS': 'hi-attr-picker-attach-btn',
+ 'ATTR_PICKER_ATTACH_LABEL_CLASS': 'hi-attr-picker-attach-label',
+ 'ATTR_PICKER_RESULT_CHECKBOX_CLASS': 'hi-attr-picker-result-checkbox',
+ 'ATTR_PICKER_SEARCH_URL_ATTR': 'data-attr-picker-search-url',
+ 'ATTR_PICKER_TITLE_ATTR': 'data-attr-picker-title',
+ 'ATTR_PICKER_SOURCE_URL_ATTR': 'data-attr-picker-source-url',
+ 'ATTR_PICKER_QUERY_FIELD': 'query',
+ 'ATTR_PICKER_LIMIT_FIELD': 'limit',
+ 'ATTR_PICKER_ITEM_TYPE_FIELD': 'item_type',
+ 'ATTR_PICKER_ITEM_ID_FIELD': 'item_id',
+ 'ATTR_PICKER_INTEGRATION_ID_FIELD': 'integration_id',
+ 'ATTR_PICKER_SELECTIONS_JSON_FIELD': 'selections_json',
+ 'ATTR_PICKER_SELECTION_TITLE_KEY': 'title',
+ 'ATTR_PICKER_SELECTION_URL_KEY': 'source_url',
+ 'ATTR_PICKER_SOURCE_BANNER_CLASS': 'hi-attr-picker-source-banner',
+ 'ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS': 'hi-attr-picker-source-banner-logo',
+ 'ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS': 'hi-attr-picker-source-banner-label',
+ 'ATTR_PICKER_SOURCE_OPTION_CLASS': 'hi-attr-picker-source-option',
+ 'ATTR_PICKER_SOURCE_ID_ATTR': 'data-attr-picker-source-id',
+ 'ATTR_PICKER_SOURCE_LOGO_ATTR': 'data-attr-picker-source-logo',
+ 'ATTR_PICKER_SOURCE_LABEL_ATTR': 'data-attr-picker-source-label',
+
# Location SVG Editor Grid Structure
'LOCATION_SVG_EDIT_TOP': 'hi-location-svg-editor-top',
'LOCATION_SVG_EDIT_BOTTOM': 'hi-location-svg-editor-bottom',
diff --git a/src/hi/integrations/capability_gateway.py b/src/hi/integrations/capability_gateway.py
new file mode 100644
index 00000000..9a8ae3f2
--- /dev/null
+++ b/src/hi/integrations/capability_gateway.py
@@ -0,0 +1,59 @@
+"""Common base for the per-capability gateway peers.
+
+``IntegrationConnector``, ``IntegrationImporter``, and
+``IntegrationAttributeReferencer`` are the three per-capability
+gateway classes today: each is the framework-facing surface for a
+specific ``IntegrationCapability``. They are conceptually peers but
+historically shared no base, leaving cross-capability concerns with
+no natural home.
+
+``CapabilityGateway`` is the shared base. Things that apply to *any*
+capability (capability identification, operator-facing description,
+attribute-form action extensions, etc.) live here. Things that are
+genuinely capability-specific (sync, import, search) stay on the
+subclass.
+
+Adding a new capability means subclassing here, declaring the
+``capability`` class attribute, and overriding only the methods that
+make sense for the new shape.
+"""
+from typing import Optional
+
+from .enums import IntegrationCapability
+from .transient_models import IntegrationMetaData
+
+
+class CapabilityGateway:
+ """Base for per-capability gateway peers."""
+
+ # Subclasses declare which ``IntegrationCapability`` they
+ # realize. The framework reads this when iterating an
+ # integration's capability gateways uniformly.
+ capability: IntegrationCapability
+
+ def get_metadata(self) -> IntegrationMetaData:
+ """Return the integration's ``IntegrationMetaData`` constant
+ (the same object the integration's ``IntegrationGateway``
+ exposes via ``get_metadata()``). The framework reads
+ ``.integration_id`` and ``.label`` from it for shared
+ operations like the auto-reconnect pre-pass and the
+ entity-removal helper, so each subclass declares the source
+ of truth in one place instead of repeating the values at
+ every call site."""
+ raise NotImplementedError('Subclasses must override this method')
+
+ def get_description(self) -> Optional[str]:
+ """One-line operator-facing description of what this
+ capability does for this integration. Surfaces in
+ capability-specific UI (Content Sources header, future
+ per-source descriptions, etc.). Default None — UI omits the
+ description when not provided."""
+ return None
+
+ def get_attribute_actions_template_name(self) -> Optional[str]:
+ """Optional template fragment to render in the integration
+ attribute form's action bar. Default None — the action bar
+ shows only the framework's free buttons. Subclasses override
+ to provide capability-specific actions (status badges,
+ lifecycle buttons, etc.)."""
+ return None
diff --git a/src/hi/integrations/connector/integration_connector.py b/src/hi/integrations/connector/integration_connector.py
index b13ad2c2..9c6c7673 100644
--- a/src/hi/integrations/connector/integration_connector.py
+++ b/src/hi/integrations/connector/integration_connector.py
@@ -24,17 +24,19 @@ from hi.apps.monitor.periodic_monitor import PeriodicMonitor
from hi.apps.sense.transient_models import SensorResponse
from hi.apps.system.health_status_provider import HealthStatusProvider
+from hi.integrations.capability_gateway import CapabilityGateway
from hi.integrations.entity_operations import EntityIntegrationOperations
+from hi.integrations.enums import IntegrationCapability
from .external_view_data import ExternalViewData
from .integration_controller import IntegrationController
from .sync_check import IntegrationSyncCheck, SyncDelta
from .sync_result import IntegrationSyncResult
-from hi.integrations.transient_models import IntegrationKey, IntegrationMetaData
+from hi.integrations.transient_models import IntegrationKey
logger = logging.getLogger(__name__)
-class IntegrationConnector:
+class IntegrationConnector( CapabilityGateway ):
"""
Base class for per-integration connectors.
@@ -52,11 +54,13 @@ class IntegrationConnector:
integration genuinely needs concurrent sync.
"""
+ capability = IntegrationCapability.CONNECT
+
# Single shared lock name across all integration syncs. See class
# docstring above for the rationale.
SYNCHRONIZATION_LOCK_NAME = 'integrations_sync'
- def get_description(self, is_initial_connect: bool) -> Optional[str]:
+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:
"""
Optional copy describing what this integration's sync will do,
surfaced to the operator in the framework's pre-sync
@@ -106,6 +110,14 @@ class IntegrationConnector:
availability."""
raise NotImplementedError('Subclasses must override this method')
+ def get_attribute_actions_template_name(self) -> Optional[str]:
+ """Per-capability template fragment to render in the
+ integration attribute form's action bar. CONNECT contributes
+ the health-status badge that links to the health-detail
+ modal. Individual integrations can override to substitute
+ their own fragment."""
+ return 'integrations/connector/panes/connect_attribute_actions.html'
+
def get_entity_video_stream(self, entity: Entity) -> Optional[VideoStream]:
"""Return the live video stream for ``entity``, or ``None`` when
the integration cannot produce one. Opt-in capability — most
@@ -210,7 +222,7 @@ class IntegrationConnector:
if result.error_list:
return
try:
- metadata = self.get_integration_metadata()
+ metadata = self.get_metadata()
except NotImplementedError:
return
try:
@@ -268,19 +280,9 @@ class IntegrationConnector:
"""
return None
- def get_integration_metadata(self) -> IntegrationMetaData:
- """
- Subclasses return their integration's ``IntegrationMetaData``
- constant (the same object the gateway exposes via
- ``get_metadata()``). The framework reads ``.integration_id``
- and ``.label`` from it for shared operations like the
- auto-reconnect pre-pass and the entity-removal helper, so
- each subclass declares the source of truth in one place
- instead of repeating the values at every call site.
- """
- raise NotImplementedError(
- f'{self.__class__.__name__} must override get_integration_metadata()'
- )
+ # ``get_metadata`` is inherited from CapabilityGateway. CONNECT
+ # subclasses must implement it; the base raises NotImplementedError
+ # via the inherited abstract.
def reconnect_disconnected_items(
self,
@@ -332,7 +334,7 @@ class IntegrationConnector:
if not unmatched_upstream_keys:
return
- metadata = self.get_integration_metadata()
+ metadata = self.get_metadata()
candidates = EntityIntegrationOperations.find_reconnect_candidates(
integration_id = metadata.integration_id,
upstream_keys = unmatched_upstream_keys,
@@ -430,7 +432,7 @@ class IntegrationConnector:
"""
EntityIntegrationOperations.remove_entities_with_closure(
seed_entity_ids = { entity.id },
- integration_name = self.get_integration_metadata().label,
+ integration_name = self.get_metadata().label,
preserve_user_data = getattr( self, '_preserve_user_data', True ),
result = result,
)
diff --git a/src/hi/integrations/connector/views.py b/src/hi/integrations/connector/views.py
index b3152de8..abbdd90b 100644
--- a/src/hi/integrations/connector/views.py
+++ b/src/hi/integrations/connector/views.py
@@ -124,7 +124,7 @@ class IntegrationPreSyncView( HiModalView, IntegrationViewMixin ):
context = {
'integration_data': integration_data,
'is_initial_connect': is_initial_connect,
- 'sync_description': connector.get_description(
+ 'sync_description': connector.get_sync_description(
is_initial_connect = is_initial_connect,
),
'sync_url': sync_url,
@@ -179,6 +179,9 @@ class ConnectorConfigureView( CapabilityConfigureView, ConnectorViewMixin ):
template_name = 'integrations/connector/modals/integration_enable.html'
error_title = 'Cannot configure integration.'
+ def get_capability_gateway( self, integration_data ):
+ return integration_data.integration_gateway.get_connector()
+
def handle_post_success(self, request, integration_data):
IntegrationManager().enable_integration(
integration_data = integration_data,
@@ -334,7 +337,7 @@ class ConnectorManageView( ConfigPageView, IntegrationViewMixin, AttributeEditVi
attr_item_context = IntegrationAttributeItemEditContext(
integration_data = integration_data,
- capability = IntegrationCapability.CONNECT,
+ capability_gateway = integration_data.integration_gateway.get_connector(),
health_status = health_status_provider.health_status,
)
integration_data_list = self.get_integration_data_list(
@@ -406,7 +409,7 @@ class ConnectorManageView( ConfigPageView, IntegrationViewMixin, AttributeEditVi
attr_item_context = IntegrationAttributeItemEditContext(
integration_data = integration_data,
- capability = IntegrationCapability.CONNECT,
+ capability_gateway = integration_data.integration_gateway.get_connector(),
health_status = health_status_provider.health_status,
)
diff --git a/src/hi/integrations/enums.py b/src/hi/integrations/enums.py
index b01103cb..e930823d 100644
--- a/src/hi/integrations/enums.py
+++ b/src/hi/integrations/enums.py
@@ -8,6 +8,10 @@ class IntegrationCapability( LabeledEnum ):
CONNECT = ( 'Connect', 'Live mirror of an upstream system.' )
IMPORT = ( 'Import', 'One-shot pull of upstream items into HI.' )
+ ATTRIBUTE_REFERENCE = (
+ 'Attribute Reference',
+ 'Search-and-attach external documents as Entity/Location attributes.',
+ )
ALL_CAPABILITIES = frozenset( IntegrationCapability )
diff --git a/src/hi/integrations/importer/integration_importer.py b/src/hi/integrations/importer/integration_importer.py
index 394b47a2..27953037 100644
--- a/src/hi/integrations/importer/integration_importer.py
+++ b/src/hi/integrations/importer/integration_importer.py
@@ -11,11 +11,10 @@ candidate-listing, item ingest, and discard operations.
"""
from typing import List
+from hi.integrations.capability_gateway import CapabilityGateway
+from hi.integrations.enums import IntegrationCapability
from hi.integrations.models import IntegrationAttribute
-from hi.integrations.transient_models import (
- IntegrationMetaData,
- IntegrationValidationResult,
-)
+from hi.integrations.transient_models import IntegrationValidationResult
from .transient_models import (
CandidateItem,
@@ -24,10 +23,9 @@ from .transient_models import (
)
-class IntegrationImporter:
+class IntegrationImporter( CapabilityGateway ):
- def get_metadata(self) -> IntegrationMetaData:
- raise NotImplementedError('Subclasses must override this method')
+ capability = IntegrationCapability.IMPORT
def validate_configuration(
self,
diff --git a/src/hi/integrations/importer/views.py b/src/hi/integrations/importer/views.py
index 6aeb45fd..d4a21706 100644
--- a/src/hi/integrations/importer/views.py
+++ b/src/hi/integrations/importer/views.py
@@ -75,6 +75,9 @@ class ImporterConfigureView( CapabilityConfigureView ):
template_name = 'integrations/importer/modals/importer_configure.html'
error_title = 'Cannot configure import.'
+ def get_capability_gateway( self, integration_data ):
+ return integration_data.integration_gateway.get_importer()
+
def handle_post_success(self, request, integration_data):
# Synchronously refresh the integration's singleton manager so
# the freshly-saved credentials are visible before the importer
diff --git a/src/hi/integrations/integration_attribute_edit_context.py b/src/hi/integrations/integration_attribute_edit_context.py
index e52fa6a0..259e435d 100644
--- a/src/hi/integrations/integration_attribute_edit_context.py
+++ b/src/hi/integrations/integration_attribute_edit_context.py
@@ -14,7 +14,7 @@ from hi.apps.attribute.forms import AttributeUploadForm
from hi.apps.attribute.models import AttributeModel
from hi.apps.system.health_status import HealthStatus
-from hi.integrations.enums import IntegrationCapability
+from hi.integrations.capability_gateway import CapabilityGateway
from hi.integrations.forms import IntegrationAttributeRegularFormSet
from hi.integrations.models import Integration, IntegrationAttribute
from hi.integrations.transient_models import IntegrationKey
@@ -25,14 +25,20 @@ from .integration_data import IntegrationData
class IntegrationAttributeItemEditContext(AttributeItemEditContext):
"""
Integration-specific context provider for attribute editing templates.
-
+
This class encapsulates Integration-specific knowledge while providing
the generic interface expected by attribute editing templates.
+
+ Construction takes the active ``CapabilityGateway`` directly (rather
+ than the capability enum). The instance carries both the capability
+ identity (``capability_gateway.capability``) used for attribute
+ filtering and the capability-specific UI hooks (description,
+ attribute-form action template) the rendered templates consult.
"""
-
+
def __init__( self,
integration_data : IntegrationData,
- capability : IntegrationCapability,
+ capability_gateway : Optional[ CapabilityGateway ],
health_status : HealthStatus = None,
update_button_label : str = 'UPDATE',
suppress_history : bool = False,
@@ -40,7 +46,15 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):
) -> None:
super().__init__( owner_type = 'integration', owner = integration_data.integration )
self.integration_data = integration_data
- self._capability = capability
+ self._capability_gateway = capability_gateway
+ # capability_gateway may be None in legacy paths (e.g., an
+ # integration declares a capability metadata-side but
+ # exposes no implementation instance). The attribute
+ # queryset falls back to "no capability filter" in that
+ # case, which preserves existing behavior.
+ self._capability = (
+ capability_gateway.capability if capability_gateway is not None else None
+ )
self._health_status = health_status
self._update_button_label = update_button_label
self._suppress_history = suppress_history
@@ -99,7 +113,7 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):
integration_name = str( member ),
).integration_key_str
for member in AttributeType
- if self._capability in member.capabilities
+ if self._capability is None or self._capability in member.capabilities
]
return self.integration.attributes.filter(
integration_key_str__in = key_strs,
@@ -120,5 +134,6 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):
template_context.update({
'integration_data': self.integration_data,
'health_status': self._health_status,
+ 'capability_gateway': self._capability_gateway,
})
return template_context
diff --git a/src/hi/integrations/integration_gateway.py b/src/hi/integrations/integration_gateway.py
index 53ef16ab..91a093e8 100644
--- a/src/hi/integrations/integration_gateway.py
+++ b/src/hi/integrations/integration_gateway.py
@@ -6,6 +6,9 @@ from hi.apps.entity.entity_placement import (
)
from hi.apps.entity.models import Entity
+from hi.integrations.referencer.integration_referencer import (
+ IntegrationAttributeReferencer,
+)
from hi.integrations.connector.integration_connector import IntegrationConnector
from hi.integrations.importer.integration_importer import IntegrationImporter
from hi.integrations.models import IntegrationAttribute
@@ -59,6 +62,17 @@ class IntegrationGateway:
"""
return None
+ def get_attribute_referencer(self) -> Optional[IntegrationAttributeReferencer]:
+ """
+ Return the integration's attribute-referencer when it
+ supports the ATTRIBUTE_REFERENCE capability; None otherwise.
+ Parallel to get_connector() and get_importer(). The
+ framework owns the picker UI and the TEXT-attribute attach
+ lifecycle; the referencer supplies the integration-specific
+ search-against-upstream operation.
+ """
+ return None
+
def validate_configuration(
self,
integration_attributes: List[IntegrationAttribute]
diff --git a/src/hi/integrations/referencer/__init__.py b/src/hi/integrations/referencer/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/hi/integrations/referencer/integration_referencer.py b/src/hi/integrations/referencer/integration_referencer.py
new file mode 100644
index 00000000..180c4e51
--- /dev/null
+++ b/src/hi/integrations/referencer/integration_referencer.py
@@ -0,0 +1,70 @@
+"""
+Per-integration ATTRIBUTE_REFERENCE base class.
+
+Parallel to ``IntegrationConnector`` (CONNECT capability) and
+``IntegrationImporter`` (IMPORT capability). Each integration that
+advertises ``IntegrationCapability.ATTRIBUTE_REFERENCE`` provides a
+concrete subclass and returns an instance from
+``IntegrationGateway.get_attribute_referencer()``. The framework
+owns the picker UI, attach lifecycle, and TEXT-attribute creation;
+the integration participates by translating a search query into a
+list of ``AttributeReferenceResult`` candidates.
+"""
+
+from typing import List, Optional
+
+from hi.integrations.capability_gateway import CapabilityGateway
+from hi.integrations.enums import IntegrationCapability
+from hi.integrations.models import IntegrationAttribute
+from hi.integrations.transient_models import IntegrationValidationResult
+
+from .transient_models import AttributeReferenceResult
+
+
+class IntegrationAttributeReferencer( CapabilityGateway ):
+
+ """Search-and-attach surface contributed by integrations that
+ expose a queryable corpus of linkable resources (documents,
+ pages, files in an external CMS, etc.). The framework calls
+ ``search_references`` from the picker view and presents the
+ returned candidates to the operator for multi-select attach."""
+
+ capability = IntegrationCapability.ATTRIBUTE_REFERENCE
+
+ def validate_configuration(
+ self,
+ integration_attributes: List[IntegrationAttribute],
+ ) -> IntegrationValidationResult:
+ """Schema-only validation of the proposed configuration.
+ Must NOT perform network operations. Mirrors the contract
+ for the same operation on the Connect / Import sides."""
+ raise NotImplementedError('Subclasses must override this method')
+
+ def search_references(
+ self,
+ query: str,
+ limit: int = 20,
+ ) -> List[AttributeReferenceResult]:
+ """Query the upstream corpus and return up to ``limit``
+ candidates. Operators see the returned list rendered as
+ cards (thumbnail/mime-icon + title + snippet + clickable
+ source URL); multi-selecting any subset attaches them as
+ TEXT attributes on the host Entity or Location.
+
+ Implementations should:
+ - Return an empty list when the query yields no matches.
+ - Honor ``limit`` as an upper bound (the picker uses a
+ user-selectable page-size 20/50/100).
+ - Order results by upstream relevance (most-relevant
+ first); the picker preserves this order.
+ - Not raise on empty/whitespace queries; return [].
+ """
+ raise NotImplementedError('Subclasses must override this method')
+
+ def get_attribute_actions_template_name(self) -> Optional[str]:
+ """Per-capability template fragment to render in the
+ integration attribute form's action bar. ATTRIBUTE_REFERENCE
+ contributes the enabled/disabled status badge plus the
+ Disable button. Individual integrations can override to
+ substitute their own fragment."""
+ return 'integrations/referencer/panes/attribute_actions.html'
diff --git a/src/hi/integrations/referencer/transient_models.py b/src/hi/integrations/referencer/transient_models.py
new file mode 100644
index 00000000..f5165cb5
--- /dev/null
+++ b/src/hi/integrations/referencer/transient_models.py
@@ -0,0 +1,34 @@
+"""
+Transient (non-persisted) models for the ATTRIBUTE_REFERENCE
+capability.
+
+``AttributeReferenceResult`` is the picker-only view of an upstream
+document or other linkable resource: shown in the search modal,
+selected by the operator, and discarded once the resulting
+``EntityAttribute`` / ``LocationAttribute`` row is created. Only
+``title`` and ``source_url`` survive into persistent storage; the
+remaining fields exist solely for picker UX.
+
+Wire-format strings (form field names, JSON record keys) shared
+between the picker views, templates, and ``attr-picker.js`` live in
+``hi.constants.DIVID`` (mirrored in ``static/js/main.js``). See the
+``ATTR_PICKER_*`` entries there.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class AttributeReferenceResult:
+ """One row in the picker's result list.
+
+ ``title`` and ``source_url`` are the only fields that survive
+ the attach step — they become the attribute's ``name`` and
+ ``value`` respectively. Everything else is picker chrome.
+ """
+ title: str
+ source_url: str
+ thumbnail_url: Optional[str] = None
+ mime_type: Optional[str] = None
+ snippet: Optional[str] = None
diff --git a/src/hi/integrations/referencer/urls.py b/src/hi/integrations/referencer/urls.py
new file mode 100644
index 00000000..c02313ed
--- /dev/null
+++ b/src/hi/integrations/referencer/urls.py
@@ -0,0 +1,26 @@
+from django.urls import path, re_path
+
+from . import views
+
+
+urlpatterns = [
+ path( 'picker/',
+ views.AttributeReferencePickerView.as_view(),
+ name='integrations_attribute_reference_picker' ),
+
+ path( 'picker/search/',
+ views.AttributeReferenceSearchView.as_view(),
+ name='integrations_attribute_reference_search' ),
+
+ path( 'picker/attach/',
+ views.AttributeReferenceAttachView.as_view(),
+ name='integrations_attribute_reference_attach' ),
+
+ path( 'home/',
+ views.ReferenceHomeView.as_view(),
+ name='integrations_reference_home' ),
+
+ re_path( r'^manage/(?P<integration_id>[\w\-]*)$',
+ views.ReferenceManageView.as_view(),
+ name='integrations_reference_manage' ),
+]
diff --git a/src/hi/integrations/referencer/views.py b/src/hi/integrations/referencer/views.py
new file mode 100644
index 00000000..3c753873
--- /dev/null
+++ b/src/hi/integrations/referencer/views.py
@@ -0,0 +1,577 @@
+"""
+ATTRIBUTE_REFERENCE picker — one HiModal view backed by antinode
+partial swaps.
+
+Workflow:
+
+ - GET ``/integrations/referencer/picker/`` with ``item_type`` +
+ ``item_id`` query params renders the full picker modal. The
+ action-bar "LINK" button in EntityEdit / LocationEdit opens
+ the modal via ``data-async="modal"``. The view discovers all
+ currently-enabled ATTRIBUTE_REFERENCE integrations and lets
+ the operator choose between them via an in-modal selector
+ when more than one is configured.
+
+ - POST to the same URL re-renders the picker body. The form
+ carries ``integration_id`` as a hidden field so the view knows
+ which referencer to drive the search against. The form's
+ ``data-async="#picker-body-<uuid>"`` + ``data-stay-in-modal``
+ keeps the modal open while the body partial swaps in.
+
+ - When the operator submits with ``action=attach``, the view
+ creates one TEXT attribute per current selection on the host
+ Entity / Location and returns ``antinode.refresh_response()`` to
+ reload the parent page (modal closes via page reload).
+
+Multi-select state is server-driven via three form fields:
+``selections_json`` (canonical existing list, hidden), ``visible_url``
+(hidden per result; identifies what was rendered), and ``result_url``
+(checkbox value per result; only submitted when checked). The view
+computes the new selection list each POST: existing + newly checked
+- unchecked visibles ± an explicit ``remove_url`` if the operator
+clicked a chip's × button.
+"""
+
+import json
+import logging
+from typing import Dict, List
+
+from django.core.exceptions import BadRequest
+from django.db import transaction
+from django.http import Http404, HttpResponse
+from django.template.loader import render_to_string
+from django.urls import reverse
+from django.views.generic import View
+
+from hi.apps.attribute.edit_form_handler import AttributeEditFormHandler
+from hi.apps.attribute.edit_response_renderer import AttributeEditResponseRenderer
+from hi.apps.attribute.enums import AttributeType, AttributeValueType
+from hi.apps.attribute.view_mixins import AttributeEditViewMixin
+from hi.apps.common import antinode
+from hi.apps.config.enums import ConfigPageType
+from hi.apps.config.views import ConfigPageView
+from hi.apps.entity.models import Entity, EntityAttribute
+from hi.apps.location.models import Location, LocationAttribute
+from hi.constants import DIVID
+from hi.enums import ItemType
+from hi.exceptions import ForceRedirectException
+from hi.hi_async_view import HiModalView
+
+from hi.integrations.enums import IntegrationCapability
+from hi.integrations.integration_attribute_edit_context import (
+ IntegrationAttributeItemEditContext,
+)
+from hi.integrations.integration_data import IntegrationData
+from hi.integrations.integration_manager import IntegrationManager
+from hi.integrations.view_mixins import IntegrationViewMixin
+
+from .integration_referencer import IntegrationAttributeReferencer
+from .transient_models import AttributeReferenceResult
+
+
+logger = logging.getLogger(__name__)
+
+
+_PAGE_SIZE_CHOICES = (20, 50, 100)
+_DEFAULT_LIMIT = 20
+_MAX_LIMIT = 100
+
+# ItemType → (owner model, attribute model, owner FK field name).
+_ATTRIBUTE_OWNER_MODELS = {
+ ItemType.ENTITY: (Entity, EntityAttribute, 'entity'),
+ ItemType.LOCATION: (Location, LocationAttribute, 'location'),
+}
+
+
+def _get_referencer_integration_data_list() -> List[ IntegrationData ]:
+ """All currently-enabled integrations that advertise the
+ ATTRIBUTE_REFERENCE capability. Returned in label order
+ (the manager already sorts by label)."""
+ return IntegrationManager().get_integration_data_list(
+ enabled_only=True,
+ capabilities=frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),
+ )
+
+
+def _resolve_integration_data(
+ integration_data_list: List[ IntegrationData ],
+ integration_id: str,
+) -> IntegrationData:
+ """Map the form's posted integration_id to one of the
+ currently-enabled referencer integrations. Rejects unknown
+ or now-disabled ids so a stale modal can't drive a search
+ against an integration the operator has turned off."""
+ if not integration_id:
+ raise BadRequest(
+ f'Missing {DIVID["ATTR_PICKER_INTEGRATION_ID_FIELD"]}.',
+ )
+ for candidate in integration_data_list:
+ if candidate.integration_id == integration_id:
+ return candidate
+ raise BadRequest(
+ f'Unknown {DIVID["ATTR_PICKER_INTEGRATION_ID_FIELD"]}: '
+ f'{integration_id!r}',
+ )
+
+
+def _require_referencer(
+ integration_data: IntegrationData,
+ request,
+) -> IntegrationAttributeReferencer:
+ referencer = integration_data.integration_gateway.get_attribute_referencer()
+ if referencer is None:
+ raise Http404( request )
+ return referencer
+
+
+def _parse_item_type(raw_value: str) -> ItemType:
+ try:
+ item_type = ItemType.from_name( raw_value )
+ except ValueError:
+ raise BadRequest(
+ f'Unsupported {DIVID["ATTR_PICKER_ITEM_TYPE_FIELD"]}: {raw_value!r}',
+ )
+ if item_type not in _ATTRIBUTE_OWNER_MODELS:
+ raise BadRequest(
+ f'Unsupported {DIVID["ATTR_PICKER_ITEM_TYPE_FIELD"]}: {raw_value!r}',
+ )
+ return item_type
+
+
+def _parse_item_id(raw_value) -> int:
+ try:
+ return int( raw_value )
+ except (TypeError, ValueError):
+ raise BadRequest(
+ f'Invalid {DIVID["ATTR_PICKER_ITEM_ID_FIELD"]}.',
+ )
+
+
+def _parse_limit(raw_limit) -> int:
+ try:
+ limit = int( raw_limit )
+ except (TypeError, ValueError):
+ return _DEFAULT_LIMIT
+ if limit not in _PAGE_SIZE_CHOICES:
+ return _DEFAULT_LIMIT
+ return min( limit, _MAX_LIMIT )
+
+
+def _resolve_owner(item_type: ItemType, item_id: int):
+ owner_model, _attribute_model, _owner_field = _ATTRIBUTE_OWNER_MODELS[ item_type ]
+ try:
+ return owner_model.objects.get( id=item_id )
+ except owner_model.DoesNotExist:
+ raise Http404( f'{item_type.label} not found.' )
+
+
+def _search_upstream(
+ referencer: IntegrationAttributeReferencer,
+ query: str,
+ limit: int,
+) -> List[ AttributeReferenceResult ]:
+ if not query:
+ return []
+ try:
+ return referencer.search_references( query=query, limit=limit )
+ except Exception:
+ logger.exception( 'Attribute-reference search failed.' )
+ return []
+
+
+def _parse_selections_json(raw: str) -> List[ Dict[str, str] ]:
+ """Parse the JS-built ``selections_json`` payload submitted on
+ attach. Skips records with missing title or source_url and
+ falls back to an empty list on any decode error."""
+ if not raw:
+ return []
+ try:
+ decoded = json.loads( raw )
+ except json.JSONDecodeError:
+ return []
+ if not isinstance( decoded, list ):
+ return []
+ parsed: List[ Dict[str, str] ] = []
+ for item in decoded:
+ if not isinstance( item, dict ):
+ continue
+ title = ( item.get( DIVID['ATTR_PICKER_SELECTION_TITLE_KEY'] ) or '' ).strip()
+ url = ( item.get( DIVID['ATTR_PICKER_SELECTION_URL_KEY'] ) or '' ).strip()
+ if not title or not url:
+ continue
+ parsed.append( {
+ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: title,
+ DIVID['ATTR_PICKER_SELECTION_URL_KEY']: url,
+ } )
+ return parsed
+
+
+def _create_attributes(
+ item_type: ItemType,
+ owner,
+ selections: List[ Dict[str, str] ],
+) -> List[ int ]:
+ if not selections:
+ return []
+ _owner_model, attribute_model, owner_field = _ATTRIBUTE_OWNER_MODELS[ item_type ]
+ created_ids: List[ int ] = []
+ with transaction.atomic():
+ for selection in selections:
+ attr = attribute_model.objects.create( **{
+ owner_field: owner,
+ 'name': selection[ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY'] ][:64],
+ 'value': selection[ DIVID['ATTR_PICKER_SELECTION_URL_KEY'] ],
+ 'value_type_str': str( AttributeValueType.TEXT ),
+ 'attribute_type_str': str( AttributeType.CUSTOM ),
+ 'is_editable': True,
+ 'is_required': False,
+ } )
+ created_ids.append( attr.id )
+ return created_ids
+
+
+class AttributeReferencePickerView( HiModalView ):
+ """GET the picker modal. Initial render is empty — no results,
+ no selections. Selection state lives in JS (see
+ ``static/js/attr-picker.js``); subsequent search results arrive
+ via async POST to ``integrations_attribute_reference_search``,
+ and the final commit posts to
+ ``integrations_attribute_reference_attach``."""
+
+ MODAL_TEMPLATE_NAME = 'integrations/referencer/modals/attr_picker.html'
+
+ def get_template_name(self) -> str:
+ return self.MODAL_TEMPLATE_NAME
+
+ def get(self, request, *args, **kwargs):
+ integration_data_list = _get_referencer_integration_data_list()
+ if not integration_data_list:
+ raise Http404( request )
+
+ item_type = _parse_item_type(
+ request.GET.get( DIVID['ATTR_PICKER_ITEM_TYPE_FIELD'] ),
+ )
+ item_id = _parse_item_id(
+ request.GET.get( DIVID['ATTR_PICKER_ITEM_ID_FIELD'] ),
+ )
+ owner = _resolve_owner( item_type=item_type, item_id=item_id )
+
+ # Default to the first configured referencer. The operator
+ # can switch via the picker's integration <select> when more
+ # than one referencer is configured.
+ integration_data = integration_data_list[0]
+
+ # Seed the picker with a query based on the owner's name so
+ # the operator opens to relevant results without retyping
+ # what they're already configuring. Goes through the same
+ # ``_search_upstream`` the search endpoint uses; the body
+ # template's results container renders the same
+ # ``attr_picker_results.html`` partial the search response
+ # returns.
+ query = owner.name
+ referencer = integration_data.integration_gateway.get_attribute_referencer()
+ results = _search_upstream(
+ referencer=referencer,
+ query=query,
+ limit=_DEFAULT_LIMIT,
+ ) if referencer is not None else []
+
+ context = {
+ 'integration_data_list': integration_data_list,
+ 'integration_data': integration_data,
+ 'item_type_value': str( item_type ),
+ 'item_id': owner.id,
+ 'limit': _DEFAULT_LIMIT,
+ 'page_size_choices': _PAGE_SIZE_CHOICES,
+ 'query': query,
+ 'results': results,
+ }
+ return self.modal_response( request, context=context )
+
+
+class AttributeReferenceSearchView( View ):
+ """POST endpoint that runs an upstream search and returns only
+ the result-cards HTML partial. The attr-picker JS swaps the
+ returned markup into the picker's results container, then
+ re-applies checkbox state from its in-memory selection set.
+
+ Empty / whitespace queries short-circuit to an empty result
+ partial (no upstream call)."""
+
+ RESULTS_TEMPLATE_NAME = 'integrations/referencer/panes/attr_picker_results.html'
+
+ def post(self, request, *args, **kwargs):
+ integration_data_list = _get_referencer_integration_data_list()
+ if not integration_data_list:
+ raise Http404( request )
+ integration_data = _resolve_integration_data(
+ integration_data_list=integration_data_list,
+ integration_id=request.POST.get(
+ DIVID['ATTR_PICKER_INTEGRATION_ID_FIELD'],
+ ),
+ )
+ referencer = _require_referencer( integration_data, request )
+ query = (
+ request.POST.get( DIVID['ATTR_PICKER_QUERY_FIELD'] ) or ''
+ ).strip()
+ limit = _parse_limit(
+ request.POST.get( DIVID['ATTR_PICKER_LIMIT_FIELD'] ),
+ )
+ results = _search_upstream(
+ referencer=referencer, query=query, limit=limit,
+ )
+ html = render_to_string(
+ self.RESULTS_TEMPLATE_NAME,
+ {
+ 'query': query,
+ 'results': results,
+ },
+ request=request,
+ )
+ return HttpResponse( html )
+
+
+class AttributeReferenceAttachView( View ):
+ """POST endpoint that creates TEXT attributes for the operator's
+ selected references. The JS module serializes its in-memory
+ selection set into ``selections_json`` just before the form
+ submits.
+
+ Returns ``antinode.refresh_response()`` so the parent page
+ reloads and the modal closes naturally."""
+
+ def post(self, request, *args, **kwargs):
+ item_type = _parse_item_type(
+ request.POST.get( DIVID['ATTR_PICKER_ITEM_TYPE_FIELD'] ),
+ )
+ item_id = _parse_item_id(
+ request.POST.get( DIVID['ATTR_PICKER_ITEM_ID_FIELD'] ),
+ )
+ owner = _resolve_owner( item_type=item_type, item_id=item_id )
+ selections = _parse_selections_json(
+ request.POST.get( DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD'] ) or '',
+ )
+ _create_attributes(
+ item_type=item_type, owner=owner, selections=selections,
+ )
+ return antinode.refresh_response()
+
+
+# ----------------------------------------------------------------------
+# Reference-capability management page
+# ----------------------------------------------------------------------
+#
+# Parallel to the Connectors page (CONNECT capability) and the Data
+# Import page (IMPORT capability). The operator-facing tab label is
+# "Content Sources"; code-side naming uses ``reference`` to align
+# with the capability and the surrounding referencer/ directory.
+
+
+class ReferenceHomeView( ConfigPageView, IntegrationViewMixin ):
+ """Landing route for the reference-management page. Picks the
+ first ATTRIBUTE_REFERENCE integration (enabled or not) and
+ redirects to its manage URL. Returns the empty-state template
+ when none are discovered (defensive — currently can't happen
+ at runtime as long as the paperless app is installed)."""
+
+ def config_page_type(self) -> ConfigPageType:
+ return ConfigPageType.INTEGRATIONS_REFERENCE
+
+ def get_main_template_name( self ) -> str:
+ return 'integrations/referencer/pages/no_integrations.html'
+
+ def get_main_template_context( self, request, *args, **kwargs ):
+ integration_data_list = IntegrationManager().get_integration_data_list(
+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),
+ )
+ if not integration_data_list:
+ return dict()
+ redirect_url = reverse(
+ 'integrations_reference_manage',
+ kwargs = { 'integration_id': integration_data_list[0].integration_id },
+ )
+ raise ForceRedirectException( redirect_url )
+
+
+class ReferenceManageView( ConfigPageView, IntegrationViewMixin, AttributeEditViewMixin ):
+ """Per-integration attribute-form page for ATTRIBUTE_REFERENCE
+ integrations.
+
+ Differences from ``ConnectorManageView``:
+ - Filters by ATTRIBUTE_REFERENCE (not CONNECT).
+ - Does not read health status / sync-check state /
+ has_entities; ATTRIBUTE_REFERENCE has no monitors and no
+ sync cycle.
+ - Passes ``capability = ATTRIBUTE_REFERENCE`` to the attribute
+ edit context so the attribute queryset is filtered to the
+ attributes the capability declares.
+ - Tolerates ``is_enabled = False`` integrations — the operator
+ configures credentials here before the integration is
+ enabled.
+ """
+
+ def config_page_type(self) -> ConfigPageType:
+ return ConfigPageType.INTEGRATIONS_REFERENCE
+
+ def get_main_template_name( self ) -> str:
+ return 'integrations/referencer/pages/integration_manage.html'
+
+ def get_main_template_context( self, request, *args, **kwargs ):
+ integration_data, integration_data_list = self._resolve(
+ kwargs.get( 'integration_id' )
+ )
+ attr_item_context = self._build_attr_item_context( integration_data )
+
+ template_context = self.create_initial_template_context(
+ attr_item_context = attr_item_context,
+ )
+ template_context.update({
+ 'core': {
+ 'integration_data_list': integration_data_list,
+ 'integration_data': integration_data,
+ },
+ })
+ return template_context
+
+ ACTION_DISABLE = 'disable'
+
+ def post( self, request, *args, **kwargs ):
+ integration_data, _ = self._resolve( kwargs.get( 'integration_id' ) )
+ if request.POST.get( 'action' ) == self.ACTION_DISABLE:
+ return self._handle_disable( request, integration_data )
+ return self._handle_save( request, integration_data )
+
+ def _handle_disable( self, request, integration_data ):
+ """Flip ``is_enabled`` to False; credentials remain in the DB
+ so a future ENABLE is one click. Re-renders the form area in
+ place so the badge and the submit-button label update via
+ antinode partial swap without a full page reload."""
+ if integration_data.integration.is_enabled:
+ integration_data.integration.is_enabled = False
+ integration_data.integration.save(
+ update_fields = [ 'is_enabled' ],
+ )
+ attr_item_context = self._build_attr_item_context( integration_data )
+ renderer = AttributeEditResponseRenderer()
+ return renderer.render_form_success_response(
+ attr_item_context = attr_item_context,
+ request = request,
+ message = None,
+ )
+
+ def _handle_save( self, request, integration_data ):
+ # Capture pre-save enabled state so we can flip it on a
+ # successful first-time save (the ``ENABLE`` flow).
+ was_enabled = integration_data.integration.is_enabled
+ attr_item_context = self._build_attr_item_context( integration_data )
+
+ form_handler = AttributeEditFormHandler()
+ renderer = AttributeEditResponseRenderer()
+ edit_form_data = form_handler.create_edit_form_data(
+ attr_item_context = attr_item_context,
+ form_data = request.POST,
+ )
+
+ forms_valid = form_handler.validate_forms( edit_form_data = edit_form_data )
+ if forms_valid:
+ # Schema + access check via the shared helper; populates
+ # ``_non_form_errors`` on failure so the next is_valid()
+ # call returns False.
+ self.validate_attributes_extra(
+ attr_item_context = attr_item_context,
+ regular_attributes_formset = edit_form_data.regular_attributes_formset,
+ request = request,
+ )
+ forms_valid = edit_form_data.regular_attributes_formset.is_valid()
+
+ if not forms_valid:
+ return renderer.render_form_error_response(
+ attr_item_context = attr_item_context,
+ edit_form_data = edit_form_data,
+ request = request,
+ )
+
+ form_handler.save_forms(
+ attr_item_context = attr_item_context,
+ edit_form_data = edit_form_data,
+ request = request,
+ )
+ if not was_enabled:
+ # First-time ENABLE: credentials just validated upstream
+ # via the helper's access probe, so flipping is_enabled
+ # to True reflects what's now true on the wire.
+ integration_data.integration.is_enabled = True
+ integration_data.integration.save(
+ update_fields = [ 'is_enabled' ],
+ )
+ # Rebuild the edit context so the response renders the
+ # post-flip state: ``update_button_label`` flips from
+ # ENABLE to UPDATE and the action-bar fragment reads
+ # ``is_enabled = True``.
+ attr_item_context = self._build_attr_item_context( integration_data )
+
+ return renderer.render_form_success_response(
+ attr_item_context = attr_item_context,
+ request = request,
+ message = None,
+ )
+
+ def validate_attributes_extra( self, attr_item_context,
+ regular_attributes_formset, request ):
+ # The shared helper runs both gateway.validate_configuration
+ # (schema) and gateway.validate_access (live probe) and
+ # decorates the formset with the failure message on either
+ # failure. We deliberately want the access probe on every
+ # save so a credential typo on UPDATE-while-enabled is
+ # rejected (atomic semantics — nothing changes on failure).
+ self.validate_attributes_extra_helper(
+ attr_item_context,
+ regular_attributes_formset,
+ error_title = 'Cannot save settings.',
+ )
+ return
+
+ def _resolve( self, integration_id ):
+ integration_data_list = IntegrationManager().get_integration_data_list(
+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),
+ )
+ if not integration_data_list:
+ raise Http404( 'No reference integrations are installed.' )
+ integration_data = self._find_integration_data(
+ integration_data_list = integration_data_list,
+ integration_id = integration_id,
+ )
+ if integration_data is None:
+ raise Http404(
+ f'Unknown reference integration: {integration_id!r}'
+ )
+ return integration_data, integration_data_list
+
+ def _build_attr_item_context( self, integration_data ):
+ # Button label flips with enabled state: ``ENABLE`` is the
+ # first-time activation path; ``UPDATE`` is the
+ # already-enabled re-validate-and-save path. Both share the
+ # same form-submission endpoint and the same validation
+ # gates — only the label and the post-save bookkeeping
+ # differ.
+ update_label = (
+ 'UPDATE' if integration_data.integration.is_enabled else 'ENABLE'
+ )
+ return IntegrationAttributeItemEditContext(
+ integration_data = integration_data,
+ capability_gateway = integration_data.integration_gateway.get_attribute_referencer(),
+ health_status = None,
+ update_button_label = update_label,
+ )
+
+ @staticmethod
+ def _find_integration_data(
+ integration_data_list: List[ IntegrationData ],
+ integration_id: str,
+ ) -> IntegrationData:
+ for candidate in integration_data_list:
+ if candidate.integration_id == integration_id:
+ return candidate
+ return None
+
+
diff --git a/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html b/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html
index 5cc38989..ab68de16 100644
--- a/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html
+++ b/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html
@@ -15,13 +15,14 @@
{% endblock %}
{% block body %}
-<h4>Disable {{ integration_data.label }} Integration?</h4>
+ {% include "integrations/panes/integration_modal_header.html" %}
+<h4>Disable {{ integration_data.label }} Connector?</h4>
{% if removal_summary.total_count == 0 %}
-<p>This integration has no attached items.</p>
+<p>This connector has no attached items.</p>
{% elif removal_summary.has_mixed_state %}
<p>
- This integration has <strong>{{ removal_summary.total_count }}</strong>
+ This connector has <strong>{{ removal_summary.total_count }}</strong>
{% if removal_summary.total_count == 1 %}item{% else %}items{% endif %}.
<strong>{{ removal_summary.user_data_count }}</strong> of
{% if removal_summary.user_data_count == 1 %}them has{% else %}them have{% endif %}
@@ -32,7 +33,7 @@
<strong>DELETE SAFE</strong> — delete the {{ removal_summary.deletable_count }}
{% if removal_summary.deletable_count == 1 %}item{% else %}items{% endif %}
without custom data, and preserve the {{ removal_summary.user_data_count }} with custom
- data (detached from this integration; the items will show as
+ data (detached from this connector; the items will show as
<em>Detached from {{ integration_data.label }}</em> in the entity-detail UI,
with custom attributes and layout retained).
</li>
@@ -45,14 +46,14 @@
</ul>
{% else %}
<p>
- This integration has <strong>{{ removal_summary.total_count }}</strong>
+ This connector has <strong>{{ removal_summary.total_count }}</strong>
{% if removal_summary.total_count == 1 %}item{% else %}items{% endif %}.
None have custom data you've added, so all will be deleted.
</p>
{% endif %}
<p class="text-muted small">
- Configuration values are retained. If you re-configure this integration
+ Configuration values are retained. If you re-configure this connector
later, it will start fresh without reconnecting to any preserved items.
</p>
{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html b/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html
index 53df3ed9..5375a187 100644
--- a/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html
+++ b/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html
@@ -2,9 +2,11 @@
{% load icons %}
{% block modal_dialog_class %}hi-modal-dialog-600{% endblock %}
-{% block title_text %}{{ integration_data.label }} Integration{% endblock %}
+{% block title_text %}{{ integration_data.label }} Connector{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
<!-- Root container for this attribute editing context -->
<div id="{{ attr_page_context.container_html_id }}"
class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}">
diff --git a/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html b/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html
index 94f030aa..8dddf148 100644
--- a/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html
+++ b/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html
@@ -4,7 +4,7 @@
{% block modal_dialog_class %}hi-modal-dialog-700{% endblock %}
{% block title_text %}
-All Integrations
+All Connectors
{% endblock %}
{% block body %}
@@ -48,6 +48,6 @@ All Integrations
</div>
</div>
{% empty %}
-<div class="alert alert-warning"> No integrations found.</div>
+<div class="alert alert-warning"> No connectors found.</div>
{% endfor %}
{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html b/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html
index ce301e50..c0277f42 100644
--- a/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html
+++ b/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html
@@ -30,7 +30,7 @@ Context:
(initial CONNECT); False for subsequent
update-check operations.
sync_description : Optional[str] — per-integration text from
- IntegrationConnector.get_description.
+ IntegrationConnector.get_sync_description.
sync_url : str (required) — URL the form posts to.
removal_summary : Optional[IntegrationRemovalSummary] —
integration's user-data classification.
@@ -53,6 +53,8 @@ Check {{ integration_data.label }} for updates?
{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
{% if is_initial_connect %}
<p>
Connect will pull items from <strong>{{ integration_data.label }}</strong>
@@ -67,7 +69,7 @@ Check {{ integration_data.label }} for updates?
</p>
{% if removal_summary.has_mixed_state %}
<p>
- This integration has <strong>{{ removal_summary.user_data_count }}</strong>
+ This connector has <strong>{{ removal_summary.user_data_count }}</strong>
{% if removal_summary.user_data_count == 1 %}item{% else %}items{% endif %}
with custom data you've added. If an update would drop
{% if removal_summary.user_data_count == 1 %}that item{% else %}any of them{% endif %}:
@@ -75,7 +77,7 @@ Check {{ integration_data.label }} for updates?
<ul>
<li>
<strong>RETAIN MISSING</strong> — preserve any missing items with custom data
- (detached from this integration; they will show as
+ (detached from this connector; they will show as
<em>Detached from {{ integration_data.label }}</em> in the entity-detail UI,
with custom attributes and layout retained).
</li>
diff --git a/src/hi/integrations/templates/integrations/connector/modals/sync_result.html b/src/hi/integrations/templates/integrations/connector/modals/sync_result.html
index 4a97b6fd..eb967e67 100644
--- a/src/hi/integrations/templates/integrations/connector/modals/sync_result.html
+++ b/src/hi/integrations/templates/integrations/connector/modals/sync_result.html
@@ -38,16 +38,7 @@
{% endblock %}
{% block body %}
-{% if integration_data %}
-<div class="d-flex align-items-center mb-3 pb-2 border-bottom">
- <img class="mr-2 hi-integration-logo"
- src="{% static integration_data.integration_metadata.logo_static_path %}"
- alt="{{ integration_data.label }} Logo">
- <div class="text-muted small text-uppercase hi-uppercase-label">
- {{ integration_data.label }}
- </div>
-</div>
-{% endif %}
+{% include "integrations/panes/integration_modal_header.html" %}
{% comment %}
Hero headline — the operator's first read of the modal. Errors
diff --git a/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html b/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html
index 073de00a..46b07301 100644
--- a/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html
+++ b/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html
@@ -8,7 +8,7 @@
<a class="btn btn-outline-primary w-100" role="button"
href="{% url 'integrations_connect_select' %}"
data-async="modal">
- {% icon "settings" size="sm" css_class="hi-icon-left" %}INTEGRATIONS
+ {% icon "settings" size="sm" css_class="hi-icon-left" %}CONNECTORS
</a>
</div>
{% for item in core.sidebar_items %}
diff --git a/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html b/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html
index 9bfd2011..8258e9f3 100644
--- a/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html
+++ b/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html
@@ -1,13 +1,13 @@
{% extends "config/pages/config_base.html" %}
{% block config_content %}
<div class="alert alert-info text-center m-4">
- There are no integrations currently configured.
+ There are no connectors currently configured.
</div>
<div class="text-center m-4 p-4">
<a class="btn btn-primary btn-lg" role="button"
href="{% url 'integrations_connect_select' %}"
data-async="modal">
- CONFIGURE INTEGRATIONS
+ CONFIGURE CONNECTORS
</a>
</div>
{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.html b/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.html
new file mode 100644
index 00000000..f668bc1c
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.html
@@ -0,0 +1,20 @@
+{% comment %}
+Attribute-form action-bar fragment for the CONNECT capability:
+health-status badge linking to the health-detail modal. Rendered
+when ``health_status`` is in scope (the CONNECT manage view passes
+it; modals that include this body do not).
+
+Context (inherited from the surrounding edit body):
+ health_status : HealthStatus (optional)
+ integration_data : IntegrationData (required)
+{% endcomment %}
+{% if health_status %}
+<div class="ml-3">
+ <a href="{% url 'integrations_connect_health_status' integration_id=integration_data.integration_id %}"
+ class="btn btn-link p-0 d-flex align-items-center text-decoration-none"
+ data-async="modal"
+ title="View health status details">
+ {% include "system/panes/health_status_badge.html" with health_status=health_status %}
+ </a>
+</div>
+{% endif %}
diff --git a/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html b/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html
index 4e32ef8e..a5e83b4f 100644
--- a/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html
+++ b/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html
@@ -3,23 +3,17 @@
{% block modal_dialog_class %}hi-modal-dialog-600{% endblock %}
{% block title_text %}
-Data Import vs. Integration
+Data Import vs. Connector
{% endblock %}
{% block body %}
<p>
<strong>Data Import</strong> is a one-time copy of items from an
- upstream system into Home Information. Once imported, the items
- are HI-owned: you can edit them freely, and they no longer depend
- on the upstream source.
+ external system into Home Information. Once imported: you can edit them freely,
+ but changes will not be reflected in the external system.
</p>
<p>
- An <a href="{% url 'integrations_connect_home' %}">Integration</a>, in
- contrast, mirrors the upstream system live — the upstream
- remains the source of truth, and changes flow in via Update.
-</p>
-<p>
- An integration may offer both modes (HomeBox today), but only
- one mode's data should be active at a time for a given upstream.
+ A <strong>Connector</strong>, in contrast, tracks and displays the data live — the
+ external system remains the source of truth.
</p>
{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html b/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html
index 42464e30..24780fce 100644
--- a/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html
+++ b/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html
@@ -15,6 +15,8 @@
{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
<h4>Discard imported {{ integration_data.label }} items?</h4>
{% if imported_count == 0 %}
diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_preview.html b/src/hi/integrations/templates/integrations/importer/modals/import_preview.html
index a0d2da6e..a55b717d 100644
--- a/src/hi/integrations/templates/integrations/importer/modals/import_preview.html
+++ b/src/hi/integrations/templates/integrations/importer/modals/import_preview.html
@@ -12,6 +12,8 @@ Import from {{ integration_data.label }}?
{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
{% if error_message %}
<div class="alert alert-warning">{{ error_message }}</div>
{% elif new_count == 0 %}
diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_result.html b/src/hi/integrations/templates/integrations/importer/modals/import_result.html
index 55408ad3..ca9b1278 100644
--- a/src/hi/integrations/templates/integrations/importer/modals/import_result.html
+++ b/src/hi/integrations/templates/integrations/importer/modals/import_result.html
@@ -8,14 +8,7 @@
{% endblock %}
{% block body %}
-<div class="d-flex align-items-center mb-3 pb-2 border-bottom">
- <img class="mr-2 hi-integration-logo"
- src="{% static integration_data.integration_metadata.logo_static_path %}"
- alt="{{ integration_data.label }} Logo">
- <div class="text-muted small text-uppercase hi-uppercase-label">
- {{ integration_data.label }}
- </div>
-</div>
+{% include "integrations/panes/integration_modal_header.html" %}
{% if result.error_list and not result.has_imports %}
<div class="text-center mb-4">
diff --git a/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html b/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html
index 688bdb92..ddff6b35 100644
--- a/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html
+++ b/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html
@@ -5,6 +5,8 @@
{% block title_text %}Import from {{ integration_data.label }}{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
<div id="{{ attr_page_context.container_html_id }}"
class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}">
diff --git a/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html b/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html
index fec9250b..b5039ba4 100644
--- a/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html
+++ b/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html
@@ -20,7 +20,7 @@
data-async="modal"
title="What's the difference?"
class="d-block text-muted small text-decoration-none mb-3">
- Also available as an Integration.
+ Also available as a Connector.
{% icon "info-circle" size="sm" %}
</a>
{% endif %}
@@ -42,7 +42,7 @@
{% empty %}
<div class="col-12">
<div class="alert alert-info">
- No integrations support Data Import.
+ No data importers currently defined.
</div>
</div>
{% endfor %}
diff --git a/src/hi/integrations/templates/integrations/modals/capability_blocked.html b/src/hi/integrations/templates/integrations/modals/capability_blocked.html
index dbb7989d..a2a93535 100644
--- a/src/hi/integrations/templates/integrations/modals/capability_blocked.html
+++ b/src/hi/integrations/templates/integrations/modals/capability_blocked.html
@@ -8,6 +8,8 @@
{% endblock %}
{% block body %}
+{% include "integrations/panes/integration_modal_header.html" %}
+
<h5 class="mb-3">Cannot configure as {{ my_label }}.</h5>
<p>
{{ integration_data.label }} {{ existing_mode_clause }}
diff --git a/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html b/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html
index 8bb8b05c..5b964cb1 100644
--- a/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html
+++ b/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html
@@ -12,17 +12,18 @@
</a>
{% endif %}
-<!-- Integration Health Status Display -->
-{% if health_status %}
-<div class="ml-3">
- <a href="{% url 'integrations_connect_health_status' integration_id=integration_data.integration_id %}"
- class="btn btn-link p-0 d-flex align-items-center text-decoration-none"
- data-async="modal"
- title="View health status details">
- {% include "system/panes/health_status_badge.html" with health_status=health_status %}
- </a>
-</div>
+{% comment %}
+Capability-owned action fragment. The active CapabilityGateway
+returns its own template path; the framework template stays
+capability-agnostic. Each capability's fragment renders its own
+status / lifecycle controls (CONNECT health badge, REFERENCE
+enable/disable, etc.).
+{% endcomment %}
+{% with capability_actions_template=capability_gateway.get_attribute_actions_template_name %}
+{% if capability_actions_template %}
+{% include capability_actions_template %}
{% endif %}
+{% endwith %}
{% endblock %}
{% block file_upload_button %}{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/panes/integration_modal_header.html b/src/hi/integrations/templates/integrations/panes/integration_modal_header.html
new file mode 100644
index 00000000..3ea71775
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/panes/integration_modal_header.html
@@ -0,0 +1,11 @@
+{% load static %}
+{% if integration_data %}
+<div class="d-flex align-items-center mb-3 pb-2 border-bottom">
+ <img class="mr-2 hi-integration-logo"
+ src="{% static integration_data.integration_metadata.logo_static_path %}"
+ alt="{{ integration_data.label }} Logo">
+ <div class="text-muted small text-uppercase hi-uppercase-label">
+ {{ integration_data.label }}
+ </div>
+</div>
+{% endif %}
diff --git a/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.html b/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.html
new file mode 100644
index 00000000..2c3a0e5c
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.html
@@ -0,0 +1,89 @@
+{% extends "modals/action_with_cancel.html" %}
+{% load icons %}
+
+{% comment %}
+ATTRIBUTE_REFERENCE picker modal.
+
+Selection state lives in attr-picker.js (one selection set per open
+modal instance, keyed by the picker-root DOM node — i.e., this
+modal-dialog). attr-picker.js attaches its handlers as delegated
+listeners at document level, so antinode-injected modal content
+wires up automatically — no init step in this template.
+
+Layout:
+
+ - Modal dialog gets ``modal-dialog-scrollable`` (Bootstrap-native
+ opt-in: the modal-body scrolls, while modal-header and
+ modal-footer stay anchored). The selection chip row + Add
+ button live in the footer alongside Cancel, so they remain
+ visible regardless of how far the operator scrolls through
+ search results.
+ - The picker-root class lives on the modal-dialog so JS handlers
+ can ``closest()`` from either body (search row, result cards)
+ or footer (chips, attach form) and find the same picker.
+
+Context:
+ integration_data_list : list[IntegrationData]
+ integration_data : IntegrationData (initially-selected source)
+ item_type_value : str(ItemType.ENTITY) or str(ItemType.LOCATION)
+ item_id : int (host record id)
+ limit : int (initial page size)
+ page_size_choices : tuple[int]
+
+Wire-format strings (DOM class names, data-attribute names, form
+field names) come from ``hi.constants.DIVID`` (mirrored in
+``static/js/main.js`` under ``Hi.ATTR_PICKER_*``).
+{% endcomment %}
+
+{% block modal_dialog_class %}modal-dialog-scrollable hi-modal-dialog-700 {{ DIVID.ATTR_PICKER_ROOT_CLASS }}{% endblock %}
+
+{% block title_text %}
+Link Content
+{% endblock %}
+
+{% block body %}
+{% include "integrations/referencer/panes/attr_picker_body.html" %}
+{% endblock %}
+
+{% block footer %}
+<div class="w-100">
+
+ {# ----- Chip row + empty-state hint ----- #}
+ <div class="d-flex flex-wrap align-items-center mb-2 mt-1">
+ <div class="{{ DIVID.ATTR_PICKER_CHIPS_EMPTY_CLASS }} small text-muted">
+ No content selected yet.
+ </div>
+ <div class="{{ DIVID.ATTR_PICKER_CHIPS_CLASS }} d-flex flex-wrap"></div>
+ </div>
+
+ {# ----- Cancel + Add row ----- #}
+ <div class="d-flex justify-content-between align-items-center">
+ <a id="hi-modal-cancel" role="button"
+ class="btn btn-outline-tertiary" href="#" data-dismiss="modal">
+ {% icon "cancel" size="sm" css_class="hi-icon-left" %}CANCEL
+ </a>
+ {% comment %}
+ No ``data-async`` here: attr-picker.js owns the submit so it can
+ populate ``selections_json`` and POST through antinode's public
+ API (``AN.hideModalIfNeeded`` + ``AN.post``). Letting antinode
+ also bind via ``data-async`` would race the field-population —
+ antinode reads the form at the <body> level before attr-picker's
+ document-level submit handler fires.
+ {% endcomment %}
+ <form class="{{ DIVID.ATTR_PICKER_ATTACH_FORM_CLASS }} m-0"
+ method="post"
+ action="{% url 'integrations_attribute_reference_attach' %}">
+ {% csrf_token %}
+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_ITEM_TYPE_FIELD }}" value="{{ item_type_value }}">
+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_ITEM_ID_FIELD }}" value="{{ item_id }}">
+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_SELECTIONS_JSON_FIELD }}" value="">
+ <button type="submit"
+ class="btn btn-primary {{ DIVID.ATTR_PICKER_ATTACH_BTN_CLASS }}"
+ disabled>
+ {% icon "check-circle" size="sm" css_class="hi-icon-left" %}<span class="{{ DIVID.ATTR_PICKER_ATTACH_LABEL_CLASS }}">Add 0 Links</span>
+ </button>
+ </form>
+ </div>
+
+</div>
+{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.html b/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.html
new file mode 100644
index 00000000..3516e58c
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.html
@@ -0,0 +1,86 @@
+{% extends "config/pages/config_base.html" %}
+{% load icons static %}
+
+{% block config_content %}
+<div id="hi-integration-settings" class="d-flex">
+ <nav class="nav flex-column hi-vertical-nav">
+ <div class="hi-vertical-nav-header">
+ <span class="d-flex align-items-center justify-content-center w-100 font-weight-bold text-muted py-2"
+ style="white-space: nowrap;">
+ {% icon "collection" size="sm" css_class="hi-icon-left" %}CONTENT SOURCES
+ </span>
+ </div>
+ {% for item in core.integration_data_list %}
+ <a class="nav-link hi-vertical-nav-link {% if core.integration_data.integration_id == item.integration_id %}active{% endif %}"
+ href="{% url 'integrations_reference_manage' integration_id=item.integration_id %}"
+ data-async="true">
+ <div class="d-flex justify-content-between align-items-center">
+ <span class="d-flex align-items-center" style="white-space: nowrap;">
+ <img src="{% static item.integration_metadata.logo_static_path %}"
+ alt="{{ item.label }}"
+ style="max-height: 18px; width: auto; margin-right: 6px; flex-shrink: 0;">
+ {{ item.label }}
+ </span>
+ </div>
+ </a>
+ {% endfor %}
+ </nav>
+ <div class="flex-column flex-grow-1" style="min-width: 0;">
+ <div class="tab-content m-3">
+
+ <div id="{{ attr_item_context.container_html_id }}"
+ class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}" >
+
+ <div class="border-bottom mb-2 pb-2">
+ <div class="d-flex justify-content-between">
+ <div class="h3 integration-title mb-0">
+ <img class="img-fluid"
+ src="{% static core.integration_data.integration_metadata.logo_static_path %}"
+ alt="{{ core.integration_data.integration_metadata.label }} Logo">
+ {{ core.integration_data.integration_metadata.label }}
+ </div>
+ </div>
+ <div class="text-muted small mt-1">
+ Find related content in {{ core.integration_data.integration_metadata.label }} and link to it.
+ </div>
+ </div>
+
+ <div class="{{ DIVID.ATTR_V2_FORM_CLASS }}">
+ <form id="{{ attr_item_context.form_html_id }}"
+ action="{% url 'integrations_reference_manage' integration_id=core.integration_data.integration_id %}"
+ method="post"
+ class="{{ DIVID.ATTR_V2_FORM_CLASS }} form"
+ enctype="multipart/form-data">
+ {% csrf_token %}
+
+ <div id="{{ attr_item_context.content_html_id }}"
+ class="{{ DIVID.ATTR_V2_CONTENT_CLASS }}">
+ {% include "integrations/panes/integration_edit_content_body.html" %}
+ </div>
+ </form>
+ </div>
+
+ {% if messages %}
+ <div class="{{ DIVID.ATTR_V2_MESSAGES }}" id="{{ DIVID.ATTR_V2_MESSAGES }}">
+ {% for message in messages %}
+ <div class="alert alert-{{ message.tags }} alert-dismissible fade show" role="alert">
+ {{ message }}
+ <button type="button" class="close" data-dismiss="alert" aria-label="Close">
+ <span aria-hidden="true">&times;</span>
+ </button>
+ </div>
+ {% endfor %}
+ </div>
+ {% endif %}
+ </div>
+
+ </div>
+ </div>
+</div>
+
+<script>
+ if (window.Hi && window.Hi.attr && window.Hi.attr.initializeContainer) {
+ window.Hi.attr.initializeContainer('#{{ attr_item_context.container_html_id }}');
+ }
+</script>
+{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.html b/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.html
new file mode 100644
index 00000000..ea7b528f
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.html
@@ -0,0 +1,6 @@
+{% extends "config/pages/config_base.html" %}
+{% block config_content %}
+<div class="alert alert-info text-center m-4">
+ No content sources are installed.
+</div>
+{% endblock %}
diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.html b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.html
new file mode 100644
index 00000000..bead3e1c
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.html
@@ -0,0 +1,115 @@
+{% load icons static %}
+{% comment %}
+Picker modal body. Holds the search controls and a placeholder
+container for result cards (server-rendered partial swapped in on
+each search by attr-picker.js).
+
+The chip row, Cancel button, and Add button live in the modal
+footer (see attr_picker.html). The footer stays anchored when the
+body scrolls because the modal opts into Bootstrap's
+``modal-dialog-scrollable`` behavior.
+
+The picker-root class lives on the modal-dialog, not on this body,
+so JS handlers in both body and footer can ``closest()`` to the
+same picker instance.
+
+DOM classes, data-attribute names, and wire-format field names
+come from ``hi.constants.DIVID`` (mirrored in ``static/js/main.js``
+under ``Hi.ATTR_PICKER_*``).
+
+Context:
+ integration_data_list : list[IntegrationData]
+ integration_data : IntegrationData (the default-selected source)
+ item_type_value : str (ItemType serialized)
+ item_id : int
+ limit : int (initial page size)
+ page_size_choices : tuple[int]
+{% endcomment %}
+
+{# ----- Search form ----- #}
+<form class="{{ DIVID.ATTR_PICKER_SEARCH_FORM_CLASS }}"
+ {{ DIVID.ATTR_PICKER_SEARCH_URL_ATTR }}="{% url 'integrations_attribute_reference_search' %}">
+ {% csrf_token %}
+
+ {% comment %}
+ Source banner: always rendered so the UI shape is identical
+ whether one source or many. Bootstrap dropdown shows
+ ``[logo] [name] [caret]``; the caret + dropdown are disabled
+ via CSS when only one source is configured. The current source
+ is carried in a sibling hidden input that attr-picker.js
+ updates on dropdown selection.
+ {% endcomment %}
+ <div class="dropdown mb-3
+ {% if integration_data_list|length == 1 %}hi-attr-picker-source-banner-single{% endif %}">
+ <button type="button"
+ class="btn btn-light btn-block dropdown-toggle text-left d-flex align-items-center {{ DIVID.ATTR_PICKER_SOURCE_BANNER_CLASS }}"
+ data-toggle="dropdown"
+ aria-haspopup="true"
+ aria-expanded="false"
+ {% if integration_data_list|length == 1 %}disabled{% endif %}>
+ <img class="mr-2 {{ DIVID.ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS }}"
+ src="{% static integration_data.integration_metadata.logo_static_path %}"
+ alt="">
+ <span class="flex-grow-1 {{ DIVID.ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS }}">
+ {{ integration_data.label }}
+ </span>
+ </button>
+ <div class="dropdown-menu w-100">
+ {% for option in integration_data_list %}
+ <a href="#"
+ class="dropdown-item d-flex align-items-center {{ DIVID.ATTR_PICKER_SOURCE_OPTION_CLASS }}"
+ {{ DIVID.ATTR_PICKER_SOURCE_ID_ATTR }}="{{ option.integration_id }}"
+ {{ DIVID.ATTR_PICKER_SOURCE_LOGO_ATTR }}="{% static option.integration_metadata.logo_static_path %}"
+ {{ DIVID.ATTR_PICKER_SOURCE_LABEL_ATTR }}="{{ option.label }}">
+ <img class="mr-2" src="{% static option.integration_metadata.logo_static_path %}" alt="">
+ <span>{{ option.label }}</span>
+ </a>
+ {% endfor %}
+ </div>
+ </div>
+ <input type="hidden"
+ name="{{ DIVID.ATTR_PICKER_INTEGRATION_ID_FIELD }}"
+ value="{{ integration_data.integration_id }}">
+
+ <div class="form-row align-items-end mb-3">
+ <div class="col">
+ <label for="hi-attr-picker-query" class="small text-muted mb-1">
+ Search
+ </label>
+ <input type="text"
+ id="hi-attr-picker-query"
+ name="{{ DIVID.ATTR_PICKER_QUERY_FIELD }}"
+ value="{{ query }}"
+ placeholder="Type to search and press Enter"
+ class="form-control form-control-sm"
+ autofocus>
+ </div>
+ <div class="col-auto">
+ <label for="hi-attr-picker-limit" class="small text-muted mb-1">
+ Page size
+ </label>
+ <select id="hi-attr-picker-limit"
+ name="{{ DIVID.ATTR_PICKER_LIMIT_FIELD }}"
+ class="form-control form-control-sm">
+ {% for choice in page_size_choices %}
+ <option value="{{ choice }}" {% if choice == limit %}selected{% endif %}>{{ choice }}</option>
+ {% endfor %}
+ </select>
+ </div>
+ <div class="col-auto">
+ <button type="submit" class="btn btn-sm btn-outline-primary">
+ {% icon "zoom" size="sm" css_class="hi-icon-left" %}Search
+ </button>
+ </div>
+ </div>
+</form>
+
+{# ----- Results container ----- #}
+{% comment %}
+The initial render uses the same partial the search endpoint
+returns; attr-picker.js swaps the container's contents on each
+subsequent search.
+{% endcomment %}
+<div class="{{ DIVID.ATTR_PICKER_RESULTS_CLASS }}">
+ {% include "integrations/referencer/panes/attr_picker_results.html" %}
+</div>
diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.html b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.html
new file mode 100644
index 00000000..56187c13
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.html
@@ -0,0 +1,52 @@
+{% load icons %}
+{% comment %}
+Result-cards partial returned by the search endpoint and swapped
+into the picker's results container by attr-picker.js. Each card
+carries the source title and URL as data attributes so the JS can
+read them on checkbox change without parsing the DOM.
+
+DOM classes / data-attribute names come from ``hi.constants.DIVID``
+(mirrored in ``static/js/main.js`` under ``Hi.ATTR_PICKER_*``).
+
+Context:
+ query : str (the search query that produced these results;
+ used only for the no-results message)
+ results : list[AttributeReferenceResult]
+{% endcomment %}
+{% if query and not results %}
+<div class="text-muted small">No results.</div>
+{% endif %}
+{% if results %}
+<div class="list-group">
+ {% for r in results %}
+ <label class="list-group-item d-flex align-items-start mb-0">
+ <input type="checkbox"
+ class="{{ DIVID.ATTR_PICKER_RESULT_CHECKBOX_CLASS }} mt-1 mr-3"
+ {{ DIVID.ATTR_PICKER_TITLE_ATTR }}="{{ r.title }}"
+ {{ DIVID.ATTR_PICKER_SOURCE_URL_ATTR }}="{{ r.source_url }}">
+ {% if r.thumbnail_url %}
+ <img src="{{ r.thumbnail_url }}"
+ alt=""
+ class="mr-3 rounded"
+ style="width: 56px; height: 56px; object-fit: cover;">
+ {% else %}
+ <div class="mr-3 d-flex align-items-center justify-content-center bg-light rounded text-muted"
+ style="width: 56px; height: 56px;">
+ {% icon "info-circle" size="sm" %}
+ </div>
+ {% endif %}
+ <div class="flex-grow-1" style="min-width: 0;">
+ <div class="font-weight-bold text-truncate">{{ r.title }}</div>
+ {% if r.snippet %}
+ <div class="small text-muted text-truncate">{{ r.snippet }}</div>
+ {% endif %}
+ <a href="{{ r.source_url }}" target="_blank" rel="noopener"
+ class="small text-truncate d-block"
+ onclick="event.stopPropagation();">
+ {{ r.source_url }}
+ </a>
+ </div>
+ </label>
+ {% endfor %}
+</div>
+{% endif %}
diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.html b/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.html
new file mode 100644
index 00000000..17bb94ae
--- /dev/null
+++ b/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.html
@@ -0,0 +1,33 @@
+{% load icons %}
+{% comment %}
+Attribute-form action-bar fragment for the ATTRIBUTE_REFERENCE
+capability: ENABLED / DISABLED status badge plus the DISABLE
+button (only when enabled). The framework re-renders this
+fragment as part of the attribute form's post-save response, so
+the badge and button update in place on every successful save.
+
+Context (inherited from the surrounding edit body):
+ integration_data : IntegrationData (required)
+{% endcomment %}
+{% if integration_data.integration.is_enabled %}
+<span class="badge badge-success ml-3 px-2 py-1 align-self-center">
+ {% icon "check-circle" size="sm" css_class="hi-icon-left" %}ENABLED
+</span>
+{% comment %}
+DISABLE shares the surrounding attribute form (HTML forbids nested
+forms; the attr.js wiring reads the outer form's ``action`` and
+ignores ``formaction``). Dispatch is via the ``action`` POST field
+— the manage view's POST handler branches on it.
+{% endcomment %}
+<button type="submit"
+ name="action"
+ value="disable"
+ formnovalidate
+ class="btn btn-outline-danger ml-2">
+ {% icon "close" size="sm" css_class="hi-icon-left" %}DISABLE
+</button>
+{% else %}
+<span class="badge badge-secondary ml-3 px-2 py-1 align-self-center">
+ {% icon "info-circle" size="sm" css_class="hi-icon-left" %}DISABLED
+</span>
+{% endif %}
diff --git a/src/hi/integrations/templatetags/integration_tags.py b/src/hi/integrations/templatetags/integration_tags.py
index 8b4b3887..6b68c3ad 100644
--- a/src/hi/integrations/templatetags/integration_tags.py
+++ b/src/hi/integrations/templatetags/integration_tags.py
@@ -1,6 +1,7 @@
import logging
from django import template
+from hi.integrations.enums import IntegrationCapability
from hi.integrations.models import IntegrationDetailsModel
from hi.integrations.integration_manager import IntegrationManager
@@ -65,6 +66,17 @@ def previous_integration_logo_path( model : IntegrationDetailsModel ) -> str:
return metadata.logo_static_path if metadata else ''
+def has_attribute_referencers() -> bool:
+ """True iff at least one currently-enabled integration advertises
+ the ATTRIBUTE_REFERENCE capability. Used by Entity/Location edit
+ surfaces to decide whether to show the "LINK" action-bar button."""
+ return bool( IntegrationManager().get_integration_data_list(
+ enabled_only = True,
+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),
+ ) )
+
+
@register.inclusion_tag( 'integrations/connector/panes/integration_health_banner.html' )
def integration_health_banner( integration_id : str, context_message : str = None ):
"""Render a banner when the integration is in a non-healthy state.
diff --git a/src/hi/integrations/tests/test_importer_views.py b/src/hi/integrations/tests/test_importer_views.py
index 6f8cd07d..3ba60ac4 100644
--- a/src/hi/integrations/tests/test_importer_views.py
+++ b/src/hi/integrations/tests/test_importer_views.py
@@ -162,7 +162,7 @@ class DataImportPageViewTests(TestCase):
)),
])
response = self.client.get(reverse('integrations_import_home'))
- self.assertIn('Also available as an', response.content.decode())
+ self.assertIn('Also available as a Connector', response.content.decode())
class ImporterConfigureViewTests(TestCase):
@@ -256,7 +256,7 @@ class ImporterConfigureViewTests(TestCase):
response = self.client.get(self._url())
body = response.content.decode()
self.assertIn('Cannot configure', body)
- self.assertIn('GO TO INTEGRATIONS', body)
+ self.assertIn('GO TO CONNECTORS', body)
self.assertIn(reverse('integrations_connect_home'), body)
def test_get_import_not_blocked_for_single_capability_integration(self):
diff --git a/src/hi/integrations/tests/test_integration_attribute_edit_context.py b/src/hi/integrations/tests/test_integration_attribute_edit_context.py
index c54f7d12..6eb5335f 100644
--- a/src/hi/integrations/tests/test_integration_attribute_edit_context.py
+++ b/src/hi/integrations/tests/test_integration_attribute_edit_context.py
@@ -7,6 +7,8 @@ import logging
from django.test import TestCase
from hi.apps.attribute.enums import AttributeValueType
+from hi.integrations.connector.integration_connector import IntegrationConnector
+from hi.integrations.importer.integration_importer import IntegrationImporter
from hi.integrations.integration_attribute_edit_context import (
IntegrationAttributeItemEditContext,
)
@@ -85,10 +87,10 @@ class CapabilityFilteredFormsetTests(TestCase):
integration=self.integration,
)
- def _attribute_names_for(self, capability):
+ def _attribute_names_for(self, capability_gateway):
edit_context = IntegrationAttributeItemEditContext(
integration_data=self.integration_data,
- capability=capability,
+ capability_gateway=capability_gateway,
)
return sorted(
attr.integration_key.integration_name
@@ -97,12 +99,12 @@ class CapabilityFilteredFormsetTests(TestCase):
def test_connect_context_excludes_import_only(self):
self.assertEqual(
- self._attribute_names_for(IntegrationCapability.CONNECT),
+ self._attribute_names_for(IntegrationConnector()),
['connect_field', 'shared_field'],
)
def test_import_context_excludes_connect_only(self):
self.assertEqual(
- self._attribute_names_for(IntegrationCapability.IMPORT),
+ self._attribute_names_for(IntegrationImporter()),
['import_field', 'shared_field'],
)
diff --git a/src/hi/integrations/tests/test_integration_connector.py b/src/hi/integrations/tests/test_integration_connector.py
index cdad2d96..b5ec4bce 100644
--- a/src/hi/integrations/tests/test_integration_connector.py
+++ b/src/hi/integrations/tests/test_integration_connector.py
@@ -48,7 +48,7 @@ class TestSynchronizer(IntegrationConnector):
abstract hooks so the class can be instantiated; sync() itself
is not exercised here."""
- def get_integration_metadata(self):
+ def get_metadata(self):
return _stub_integration_metadata()
def get_result_title(self, is_initial_connect=False):
@@ -1254,7 +1254,7 @@ class ReconnectDisconnectedItemsFrameworkTests(TestCase):
integration_label = self.INTEGRATION_LABEL
class RecordingSynchronizer(IntegrationConnector):
- def get_integration_metadata(self):
+ def get_metadata(self):
return _stub_integration_metadata(
integration_id=integration_id,
label=integration_label,
@@ -1361,7 +1361,7 @@ class ReconnectDisconnectedItemsFrameworkTests(TestCase):
# _rebuild_integration_components hook (the missing
# override under test) rather than tripping on the
# earlier metadata abstract-hook check.
- def get_integration_metadata(_self):
+ def get_metadata(_self):
return _stub_integration_metadata(
integration_id=self.INTEGRATION_ID,
label=self.INTEGRATION_LABEL,
@@ -1417,7 +1417,7 @@ class IntegrationConnectorReconnectCycleTests(TestCase):
integration_label = self.INTEGRATION_LABEL
class TestE2ESynchronizer(IntegrationConnector):
- def get_integration_metadata(self):
+ def get_metadata(self):
return _stub_integration_metadata(
integration_id=integration_id,
label=integration_label,
diff --git a/src/hi/integrations/tests/test_reference_manage_views.py b/src/hi/integrations/tests/test_reference_manage_views.py
new file mode 100644
index 00000000..91e43eb3
--- /dev/null
+++ b/src/hi/integrations/tests/test_reference_manage_views.py
@@ -0,0 +1,293 @@
+"""View tests for the Content Sources management page.
+
+Covers the GET-render, the Save/Enable submission flow (validate +
+save + flip ``is_enabled`` on first activation), and the Disable
+endpoint (flip ``is_enabled`` to False, credentials preserved).
+"""
+import logging
+
+from django.urls import reverse
+
+from hi.apps.attribute.enums import AttributeType, AttributeValueType
+from hi.integrations.integration_data import IntegrationData
+from hi.integrations.integration_manager import IntegrationManager
+from hi.integrations.models import Integration, IntegrationAttribute
+from hi.integrations.transient_models import (
+ ConnectionTestResult,
+ IntegrationKey,
+)
+from hi.services.paperless.enums import PlAttributeType
+from hi.services.paperless.integration import PaperlessGateway
+from hi.services.paperless.pl_metadata import PaperlessMetaData
+from hi.testing.view_test_base import ViewTestBase
+
+
+logging.disable(logging.CRITICAL)
+
+
+def _seed_manager( *integration_data ):
+ """Seed the IntegrationManager singleton's in-memory data map.
+ The manager is singletoned across the test process, so this
+ explicit seed is the supported way for view tests to inject the
+ integration data the views look up."""
+ manager = IntegrationManager()
+ manager._integration_data_map = {
+ data.integration_id: data for data in integration_data
+ }
+
+
+def _make_attr( integration, attr_type, value ):
+ attr = IntegrationAttribute.objects.create(
+ integration = integration,
+ name = attr_type.label,
+ value = value,
+ value_type_str = str(AttributeValueType.TEXT),
+ attribute_type_str = str(AttributeType.PREDEFINED),
+ is_editable = attr_type.is_editable,
+ is_required = attr_type.is_required,
+ )
+ attr.integration_key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str(attr_type),
+ )
+ attr.save()
+ return attr
+
+
+class TestReferenceManageGet( ViewTestBase ):
+
+ def setUp(self):
+ super().setUp()
+ self.client.force_login(self.user)
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = False,
+ )
+ _seed_manager(IntegrationData(
+ integration_gateway = PaperlessGateway(),
+ integration = self.integration,
+ ))
+
+ def _url(self):
+ return reverse(
+ 'integrations_reference_manage',
+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },
+ )
+
+ def test_renders_with_disabled_status(self):
+ response = self.client.get(self._url())
+ self.assertEqual(response.status_code, 200)
+ body = response.content.decode()
+ self.assertIn('Paperless-ngx', body)
+ # Disabled-state hallmarks: badge + ENABLE button label.
+ self.assertIn('DISABLED', body)
+ self.assertIn('ENABLE', body)
+ # No DISABLE button rendered when already disabled.
+ self.assertNotIn('integrations_reference_deactivate', body)
+
+ def test_renders_with_enabled_status(self):
+ self.integration.is_enabled = True
+ self.integration.save()
+ response = self.client.get(self._url())
+ self.assertEqual(response.status_code, 200)
+ body = response.content.decode()
+ self.assertIn('ENABLED', body)
+ # When enabled, the form button reverts to UPDATE and the
+ # DISABLE button is wired in the header.
+ self.assertIn('UPDATE', body)
+ self.assertIn('DISABLE', body)
+
+
+class TestReferenceManagePost( ViewTestBase ):
+
+ def setUp(self):
+ super().setUp()
+ self.client.force_login(self.user)
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = False,
+ )
+ _seed_manager(IntegrationData(
+ integration_gateway = PaperlessGateway(),
+ integration = self.integration,
+ ))
+ # Required-by-framework predefined attribute rows. The
+ # formset edits these in place rather than creating new
+ # rows on submit.
+ self.url_attr = _make_attr(self.integration, PlAttributeType.API_URL, '')
+ self.token_attr = _make_attr(self.integration, PlAttributeType.API_TOKEN, '')
+
+ def _url(self):
+ return reverse(
+ 'integrations_reference_manage',
+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },
+ )
+
+ def _form_payload(self, api_url, api_token):
+ # Formset wire shape: prefix is f'{owner_type}-{owner.id}'
+ # (see ``AttributeItemEditContext.formset_prefix``). The
+ # inline IntegrationAttribute formset wraps existing rows
+ # by id; we re-post each row's name + value to keep the
+ # formset valid.
+ prefix = f'integration-{self.integration.id}'
+ return {
+ f'{prefix}-TOTAL_FORMS': '2',
+ f'{prefix}-INITIAL_FORMS': '2',
+ f'{prefix}-MIN_NUM_FORMS': '0',
+ f'{prefix}-MAX_NUM_FORMS': '100',
+
+ f'{prefix}-0-id': str(self.url_attr.id),
+ f'{prefix}-0-name': self.url_attr.name,
+ f'{prefix}-0-value': api_url,
+
+ f'{prefix}-1-id': str(self.token_attr.id),
+ f'{prefix}-1-name': self.token_attr.name,
+ f'{prefix}-1-value': api_token,
+ }
+
+ def _patch_validate_access(self, success: bool, message: str = ''):
+ from unittest.mock import patch
+ result = (
+ ConnectionTestResult.success() if success
+ else ConnectionTestResult.failure(message or 'probe failed')
+ )
+ return patch(
+ 'hi.services.paperless.integration.PaperlessGateway.validate_access',
+ return_value = result,
+ )
+
+ def test_save_with_valid_creds_enables_disabled_integration(self):
+ with self._patch_validate_access(success = True):
+ response = self.client.post(self._url(), data = self._form_payload(
+ api_url = 'https://paperless.example.com/',
+ api_token = 'good-token',
+ ))
+
+ self.integration.refresh_from_db()
+ self.url_attr.refresh_from_db()
+ self.token_attr.refresh_from_db()
+ self.assertEqual(response.status_code, 200)
+ self.assertTrue(self.integration.is_enabled)
+ self.assertEqual(self.url_attr.value, 'https://paperless.example.com/')
+ self.assertEqual(self.token_attr.value, 'good-token')
+
+ def test_save_on_already_enabled_keeps_enabled(self):
+ # UPDATE flow: integration is enabled; save should keep
+ # is_enabled=True and persist any credential changes.
+ self.integration.is_enabled = True
+ self.integration.save()
+ self.url_attr.value = 'https://old.example.com/'
+ self.url_attr.save()
+
+ with self._patch_validate_access(success = True):
+ response = self.client.post(self._url(), data = self._form_payload(
+ api_url = 'https://new.example.com/',
+ api_token = 'rotated-token',
+ ))
+
+ self.integration.refresh_from_db()
+ self.url_attr.refresh_from_db()
+ self.assertEqual(response.status_code, 200)
+ self.assertTrue(self.integration.is_enabled)
+ self.assertEqual(self.url_attr.value, 'https://new.example.com/')
+
+ def test_save_with_bad_access_does_not_save_or_enable(self):
+ # Atomic semantics: failed probe blocks the save entirely.
+ # Neither attributes nor is_enabled change. Operator sees
+ # the access failure inline on the form (framework error
+ # response renders the form again with errors).
+ self.url_attr.value = 'https://old.example.com/'
+ self.url_attr.save()
+
+ with self._patch_validate_access(
+ success = False, message = 'auth rejected',
+ ):
+ response = self.client.post(self._url(), data = self._form_payload(
+ api_url = 'https://new.example.com/',
+ api_token = 'bad-token',
+ ))
+
+ self.integration.refresh_from_db()
+ self.url_attr.refresh_from_db()
+ # Framework returns 400 on form errors (the antinode
+ # response carries the re-rendered form for swap-in).
+ self.assertEqual(response.status_code, 400)
+ self.assertFalse(self.integration.is_enabled)
+ self.assertEqual(self.url_attr.value, 'https://old.example.com/')
+
+ def test_save_with_bad_access_when_enabled_keeps_old_state(self):
+ # The (a) post-condition: an UPDATE-while-enabled with a bad
+ # probe leaves the integration enabled with its previously
+ # working creds. Nothing partially changes.
+ self.integration.is_enabled = True
+ self.integration.save()
+ self.url_attr.value = 'https://old.example.com/'
+ self.url_attr.save()
+
+ with self._patch_validate_access(
+ success = False, message = 'auth rejected',
+ ):
+ response = self.client.post(self._url(), data = self._form_payload(
+ api_url = 'https://new.example.com/',
+ api_token = 'rotated-token',
+ ))
+
+ self.integration.refresh_from_db()
+ self.url_attr.refresh_from_db()
+ self.assertEqual(response.status_code, 400)
+ # Still enabled, still old URL.
+ self.assertTrue(self.integration.is_enabled)
+ self.assertEqual(self.url_attr.value, 'https://old.example.com/')
+
+
+class TestReferenceDisableAction( ViewTestBase ):
+ """Disable rides the manage URL as an in-form action — the
+ DISABLE button submits the surrounding attribute form with
+ ``action=disable`` in the POST body, which the view dispatches
+ on. No separate URL."""
+
+ def setUp(self):
+ super().setUp()
+ self.client.force_login(self.user)
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = True,
+ )
+ _seed_manager(IntegrationData(
+ integration_gateway = PaperlessGateway(),
+ integration = self.integration,
+ ))
+
+ def _url(self):
+ return reverse(
+ 'integrations_reference_manage',
+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },
+ )
+
+ def test_disable_action_flips_is_enabled(self):
+ response = self.client.post(self._url(), data = { 'action': 'disable' })
+ self.assertEqual(response.status_code, 200)
+ self.integration.refresh_from_db()
+ self.assertFalse(self.integration.is_enabled)
+
+ def test_disable_action_already_disabled_is_no_op(self):
+ self.integration.is_enabled = False
+ self.integration.save()
+ response = self.client.post(self._url(), data = { 'action': 'disable' })
+ self.assertEqual(response.status_code, 200)
+ self.integration.refresh_from_db()
+ self.assertFalse(self.integration.is_enabled)
+
+ def test_disable_action_skips_credential_validation(self):
+ # Disable bypasses the access probe — operators must be able
+ # to disable a misconfigured integration without first
+ # fixing the credentials.
+ from unittest.mock import patch
+ with patch(
+ 'hi.services.paperless.integration.PaperlessGateway.validate_access',
+ ) as mock_probe:
+ response = self.client.post(self._url(), data = { 'action': 'disable' })
+ self.assertEqual(response.status_code, 200)
+ mock_probe.assert_not_called()
+ self.integration.refresh_from_db()
+ self.assertFalse(self.integration.is_enabled)
diff --git a/src/hi/integrations/tests/test_referencer_views.py b/src/hi/integrations/tests/test_referencer_views.py
new file mode 100644
index 00000000..d3a89e46
--- /dev/null
+++ b/src/hi/integrations/tests/test_referencer_views.py
@@ -0,0 +1,534 @@
+"""View tests for the ATTRIBUTE_REFERENCE picker.
+
+The picker is split into three endpoints:
+
+ - ``integrations_attribute_reference_picker`` — GET, renders the
+ initial empty modal.
+ - ``integrations_attribute_reference_search`` — POST, returns the
+ result-cards partial. The attr-picker.js module swaps the
+ returned HTML into the picker's results container.
+ - ``integrations_attribute_reference_attach`` — POST, reads the
+ JS-built ``selections_json`` payload, creates one TEXT
+ attribute per record, returns ``antinode.refresh_response()``.
+
+Selection state lives in JS during the session; the server is
+consulted only at search time (per-query) and at attach time (the
+single final commit).
+"""
+import json
+import logging
+
+from django.urls import reverse
+
+from hi.apps.attribute.enums import AttributeType, AttributeValueType
+from hi.apps.entity.enums import EntityType
+from hi.apps.entity.models import Entity, EntityAttribute
+from hi.apps.location.models import Location, LocationAttribute
+from hi.enums import ItemType, ViewMode
+from hi.integrations.enums import IntegrationAttributeType, IntegrationCapability
+from hi.integrations.integration_data import IntegrationData
+from hi.integrations.integration_gateway import IntegrationGateway
+from hi.integrations.integration_manager import IntegrationManager
+from hi.integrations.models import Integration
+from hi.integrations.referencer.integration_referencer import (
+ IntegrationAttributeReferencer,
+)
+from hi.constants import DIVID
+from hi.integrations.referencer.transient_models import (
+ AttributeReferenceResult,
+)
+from hi.integrations.transient_models import (
+ ConnectionTestResult,
+ IntegrationMetaData,
+ IntegrationValidationResult,
+)
+from hi.testing.view_test_base import ViewTestBase
+
+
+logging.disable(logging.CRITICAL)
+
+
+# ---- fixtures ----------------------------------------------------
+
+
+class _RefAttributeType(IntegrationAttributeType):
+ TEST_ATTR = (
+ 'Test Attr', '',
+ AttributeValueType.TEXT, {}, True, True, 'default',
+ )
+
+
+class _StubReferencer(IntegrationAttributeReferencer):
+ """In-memory referencer the tests inject via the gateway.
+ Captures search args so tests can assert dispatch shape."""
+
+ def __init__(self, integration_id='ref', label='Ref Test',
+ results=None, raises=None):
+ self._integration_id = integration_id
+ self._label = label
+ self._results = results or []
+ self._raises = raises
+ self.last_query = None
+ self.last_limit = None
+
+ def get_metadata(self):
+ return IntegrationMetaData(
+ integration_id=self._integration_id,
+ label=self._label,
+ attribute_type=_RefAttributeType,
+ allow_entity_deletion=True,
+ capabilities=frozenset({IntegrationCapability.ATTRIBUTE_REFERENCE}),
+ )
+
+ def validate_configuration(self, integration_attributes):
+ return IntegrationValidationResult.success()
+
+ def search_references(self, query, limit=20):
+ self.last_query = query
+ self.last_limit = limit
+ if self._raises is not None:
+ raise self._raises
+ return list(self._results)
+
+
+class _ReferencerCapableGateway(IntegrationGateway):
+ """Gateway that advertises ATTRIBUTE_REFERENCE and returns the
+ test's stub referencer from ``get_attribute_referencer``."""
+
+ def __init__(self, integration_id='ref', label='Ref Test', referencer=None):
+ self.integration_id = integration_id
+ self.label = label
+ self._referencer = referencer
+
+ def get_metadata(self):
+ return IntegrationMetaData(
+ integration_id=self.integration_id,
+ label=self.label,
+ attribute_type=_RefAttributeType,
+ allow_entity_deletion=True,
+ capabilities=frozenset({IntegrationCapability.ATTRIBUTE_REFERENCE}),
+ )
+
+ def validate_configuration(self, integration_attributes):
+ return IntegrationValidationResult.success()
+
+ def validate_access(self, integration_attributes, timeout_secs):
+ return ConnectionTestResult.success()
+
+ def get_attribute_referencer(self):
+ return self._referencer
+
+
+def _populate_manager(pairs, enabled=True):
+ """Seed the IntegrationManager with the given (id, gateway) pairs.
+ By default the integrations are marked enabled so the picker view
+ sees them through its ``enabled_only=True`` filter."""
+ manager = IntegrationManager()
+ manager._integration_data_map = {}
+ for integration_id, gateway in pairs:
+ integration, _ = Integration.objects.get_or_create(
+ integration_id=integration_id,
+ defaults={'is_enabled': enabled},
+ )
+ if integration.is_enabled != enabled:
+ integration.is_enabled = enabled
+ integration.save()
+ manager._integration_data_map[integration_id] = IntegrationData(
+ integration_gateway=gateway,
+ integration=integration,
+ )
+
+
+def _result(title='Doc', source_url='https://example.com/doc/1',
+ thumbnail_url=None, mime_type=None, snippet=None):
+ return AttributeReferenceResult(
+ title=title,
+ source_url=source_url,
+ thumbnail_url=thumbnail_url,
+ mime_type=mime_type,
+ snippet=snippet,
+ )
+
+
+# ---- gateway default --------------------------------------------
+
+
+class TestIntegrationGatewayAttributeReferencerDefault(ViewTestBase):
+ """Default ``IntegrationGateway`` advertises no ATTRIBUTE_REFERENCE
+ referencer — only integrations that explicitly opt in do."""
+
+ def test_default_returns_none(self):
+ self.assertIsNone(IntegrationGateway().get_attribute_referencer())
+
+
+# ---- picker GET ----------------------------------------------------
+
+
+class TestAttributeReferencePickerView(ViewTestBase):
+ """GET renders the initial empty modal. Search and attach are
+ sibling endpoints (tested separately below)."""
+
+ INTEGRATION_ID = 'ref'
+
+ def setUp(self):
+ super().setUp()
+ IntegrationManager()._instances = {}
+ IntegrationManager._initialized_instance = None
+ self.client.force_login(self.user)
+ self.setSessionViewMode(ViewMode.EDIT)
+ self.referencer = _StubReferencer(integration_id=self.INTEGRATION_ID)
+ self.gateway = _ReferencerCapableGateway(
+ self.INTEGRATION_ID, referencer=self.referencer,
+ )
+ _populate_manager([(self.INTEGRATION_ID, self.gateway)])
+
+ def _entity(self, name='Dishwasher'):
+ return Entity.objects.create(
+ name=name,
+ entity_type_str=str(EntityType.DISHWASHER),
+ )
+
+ def _url(self):
+ return reverse('integrations_attribute_reference_picker')
+
+ def test_get_renders_modal_with_integration_label(self):
+ entity = self._entity()
+ response = self.client.get(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertIn('Ref Test', response.content.decode())
+
+ def test_get_with_no_enabled_referencer_returns_404(self):
+ _populate_manager([])
+ entity = self._entity()
+ response = self.client.get(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 404)
+
+ def test_get_unknown_item_type_returns_400(self):
+ response = self.client.get(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: 'banana',
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 1,
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 400)
+
+ def test_get_missing_owner_returns_404(self):
+ response = self.client.get(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 99999,
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 404)
+
+ def test_get_with_multiple_referencers_renders_selector(self):
+ other_ref = _StubReferencer(integration_id='other', label='Other Ref')
+ other_gw = _ReferencerCapableGateway(
+ 'other', label='Other Ref', referencer=other_ref,
+ )
+ _populate_manager([
+ (self.INTEGRATION_ID, self.gateway),
+ ('other', other_gw),
+ ])
+ entity = self._entity()
+ response = self.client.get(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ decoded = response.content.decode()
+ self.assertIn('Ref Test', decoded)
+ self.assertIn('Other Ref', decoded)
+
+
+# ---- search endpoint ----------------------------------------------
+
+
+class TestAttributeReferenceSearchView(ViewTestBase):
+ """POST returns the result-cards partial. The picker JS swaps
+ the returned HTML into the results container."""
+
+ INTEGRATION_ID = 'ref'
+
+ def setUp(self):
+ super().setUp()
+ IntegrationManager()._instances = {}
+ IntegrationManager._initialized_instance = None
+ self.client.force_login(self.user)
+ self.setSessionViewMode(ViewMode.EDIT)
+ self.referencer = _StubReferencer(integration_id=self.INTEGRATION_ID)
+ self.gateway = _ReferencerCapableGateway(
+ self.INTEGRATION_ID, referencer=self.referencer,
+ )
+ _populate_manager([(self.INTEGRATION_ID, self.gateway)])
+
+ def _url(self):
+ return reverse('integrations_attribute_reference_search')
+
+ def _payload(self, query='', limit=20, integration_id=None):
+ return {
+ DIVID['ATTR_PICKER_QUERY_FIELD']: query,
+ DIVID['ATTR_PICKER_LIMIT_FIELD']: str(limit),
+ DIVID['ATTR_PICKER_INTEGRATION_ID_FIELD']: integration_id or self.INTEGRATION_ID,
+ }
+
+ def test_empty_query_does_not_call_referencer(self):
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query=' '),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertIsNone(self.referencer.last_query)
+
+ def test_search_dispatches_with_clamped_limit(self):
+ self.referencer._results = [_result()]
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query='dishwasher', limit=50),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(self.referencer.last_query, 'dishwasher')
+ self.assertEqual(self.referencer.last_limit, 50)
+
+ def test_search_returns_result_cards_html(self):
+ self.referencer._results = [
+ _result(title='Warranty', source_url='https://p/doc/1'),
+ _result(title='Manual', source_url='https://p/doc/2'),
+ ]
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query='dishwasher'),
+ **self.async_http_headers,
+ )
+ body = response.content.decode()
+ self.assertIn('Warranty', body)
+ self.assertIn('Manual', body)
+ self.assertIn('https://p/doc/1', body)
+ # Cards carry data attributes so JS can read title + URL on
+ # checkbox change without parsing the DOM.
+ self.assertIn('data-attr-picker-source-url', body)
+ self.assertIn('data-attr-picker-title', body)
+
+ def test_search_with_no_results_returns_empty_message(self):
+ self.referencer._results = []
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query='nothing-matches'),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertIn('No results', response.content.decode())
+
+ def test_search_invalid_limit_falls_back_to_default(self):
+ self.referencer._results = [_result()]
+ payload = self._payload(query='q')
+ payload[DIVID['ATTR_PICKER_LIMIT_FIELD']] = 'not-a-number'
+ self.client.post(
+ self._url(), data=payload, **self.async_http_headers,
+ )
+ self.assertEqual(self.referencer.last_limit, 20)
+
+ def test_search_unknown_integration_id_returns_400(self):
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query='q', integration_id='nope'),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 400)
+
+ def test_search_referencer_exception_yields_empty_results(self):
+ self.referencer._raises = RuntimeError('upstream down')
+ response = self.client.post(
+ self._url(),
+ data=self._payload(query='q'),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ # Failure path renders the no-results message rather than
+ # surfacing a 5xx — the picker stays usable.
+ self.assertIn('No results', response.content.decode())
+
+
+# ---- attach endpoint ----------------------------------------------
+
+
+class TestAttributeReferenceAttachView(ViewTestBase):
+ """POST reads the JS-built ``selections_json`` payload and
+ creates one TEXT attribute per record on the named owner."""
+
+ def setUp(self):
+ super().setUp()
+ IntegrationManager()._instances = {}
+ IntegrationManager._initialized_instance = None
+ self.client.force_login(self.user)
+ self.setSessionViewMode(ViewMode.EDIT)
+
+ def _url(self):
+ return reverse('integrations_attribute_reference_attach')
+
+ @staticmethod
+ def _entity(name='Dishwasher'):
+ return Entity.objects.create(
+ name=name,
+ entity_type_str=str(EntityType.DISHWASHER),
+ )
+
+ @staticmethod
+ def _location(name='Kitchen'):
+ return Location.objects.create(
+ name=name,
+ svg_fragment_filename='kitchen.svg',
+ svg_view_box_str='0 0 100 100',
+ )
+
+ @staticmethod
+ def _selections_json(*pairs):
+ return json.dumps([
+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: title, DIVID['ATTR_PICKER_SELECTION_URL_KEY']: url}
+ for title, url in pairs
+ ])
+
+ def _payload(self, owner, selections_json):
+ item_type = ItemType.ENTITY if isinstance(owner, Entity) else ItemType.LOCATION
+ return {
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(item_type),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: owner.id,
+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: selections_json,
+ }
+
+ def test_attach_creates_text_attributes_on_entity(self):
+ entity = self._entity()
+ response = self.client.post(
+ self._url(),
+ data=self._payload(entity, self._selections_json(
+ ('Warranty', 'https://p/doc/1'),
+ ('Manual', 'https://p/doc/2'),
+ )),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ body = json.loads(response.content)
+ self.assertTrue(body.get('refresh'))
+
+ attrs = list(EntityAttribute.objects.filter(entity=entity).order_by('id'))
+ self.assertEqual(len(attrs), 2)
+ self.assertEqual(attrs[0].name, 'Warranty')
+ self.assertEqual(attrs[0].value, 'https://p/doc/1')
+ self.assertEqual(attrs[0].value_type, AttributeValueType.TEXT)
+ self.assertEqual(attrs[0].attribute_type, AttributeType.CUSTOM)
+ self.assertEqual(attrs[1].name, 'Manual')
+
+ def test_attach_creates_text_attribute_on_location(self):
+ location = self._location()
+ response = self.client.post(
+ self._url(),
+ data=self._payload(location, self._selections_json(
+ ('Floor Plan', 'https://p/doc/floor-plan'),
+ )),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ attrs = list(LocationAttribute.objects.filter(location=location))
+ self.assertEqual(len(attrs), 1)
+ self.assertEqual(attrs[0].name, 'Floor Plan')
+
+ def test_attach_with_empty_selections_creates_nothing(self):
+ entity = self._entity()
+ response = self.client.post(
+ self._url(),
+ data=self._payload(entity, json.dumps([])),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(
+ EntityAttribute.objects.filter(entity=entity).count(), 0,
+ )
+
+ def test_attach_with_malformed_json_creates_nothing(self):
+ # Defensive: malformed JSON yields no attributes rather than
+ # a 500. The JS contract submits valid JSON; this guards
+ # against a manual replay.
+ entity = self._entity()
+ response = self.client.post(
+ self._url(),
+ data=self._payload(entity, 'not-json'),
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(
+ EntityAttribute.objects.filter(entity=entity).count(), 0,
+ )
+
+ def test_attach_skips_records_with_missing_fields(self):
+ entity = self._entity()
+ payload = self._payload(entity, json.dumps([
+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: '', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/1'},
+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: 'Good', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/2'},
+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: 'No URL', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: ''},
+ ]))
+ self.client.post(self._url(), data=payload, **self.async_http_headers)
+ attrs = list(EntityAttribute.objects.filter(entity=entity).order_by('id'))
+ self.assertEqual(len(attrs), 1)
+ self.assertEqual(attrs[0].name, 'Good')
+
+ def test_attach_long_title_truncated_to_max_length(self):
+ entity = self._entity()
+ long_title = 'X' * 100
+ payload = self._payload(entity, json.dumps([{
+ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: long_title,
+ DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/1',
+ }]))
+ response = self.client.post(
+ self._url(), data=payload, **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 200)
+ attr = EntityAttribute.objects.get(entity=entity)
+ self.assertEqual(len(attr.name), 64)
+
+ def test_attach_unsupported_item_type_returns_400(self):
+ response = self.client.post(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.COLLECTION),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 1,
+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: self._selections_json(('A', 'https://p/1')),
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 400)
+
+ def test_attach_unknown_owner_returns_404(self):
+ response = self.client.post(
+ self._url(),
+ data={
+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),
+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 99999,
+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: self._selections_json(('A', 'https://p/1')),
+ },
+ **self.async_http_headers,
+ )
+ self.assertEqual(response.status_code, 404)
diff --git a/src/hi/integrations/tests/test_sync_check.py b/src/hi/integrations/tests/test_sync_check.py
index 8d7ba3bf..5cfaf719 100644
--- a/src/hi/integrations/tests/test_sync_check.py
+++ b/src/hi/integrations/tests/test_sync_check.py
@@ -664,7 +664,7 @@ class IntegrationConnectorPostSyncHookTests(TestCase):
class _TestSynchronizer(IntegrationConnector):
SYNCHRONIZATION_LOCK_NAME = 'sync_check_test_lock'
- def get_integration_metadata(self):
+ def get_metadata(self):
return IntegrationMetaData(
integration_id=IntegrationConnectorPostSyncHookTests.INTEGRATION_ID,
label=IntegrationConnectorPostSyncHookTests.INTEGRATION_LABEL,
diff --git a/src/hi/integrations/tests/test_views.py b/src/hi/integrations/tests/test_views.py
index 6ed0f873..cbdcd3e9 100644
--- a/src/hi/integrations/tests/test_views.py
+++ b/src/hi/integrations/tests/test_views.py
@@ -194,11 +194,16 @@ class _SyncTestSynchronizer:
unit tests; the views only need methods the framework actually
calls on it.
"""
+
+ # Duck-typed CapabilityGateway surface: the framework reads this
+ # when building the attribute edit context.
+ capability = IntegrationCapability.CONNECT
+
def __init__(self, description='Test integration sync description.'):
self._description = description
self.sync_called = False
- def get_description(self, is_initial_connect):
+ def get_sync_description(self, is_initial_connect):
self.last_is_initial_connect = is_initial_connect
return self._description
@@ -571,11 +576,14 @@ class _PlacementTestSynchronizer:
enough to exercise group default, drill-down override, and
ungrouped per-item paths.
"""
+
+ capability = IntegrationCapability.CONNECT
+
def __init__(self, sync_result):
self._sync_result = sync_result
self.sync_called = False
- def get_description(self, is_initial_connect):
+ def get_sync_description(self, is_initial_connect):
return None
def get_result_title(self, is_initial_connect):
diff --git a/src/hi/integrations/urls.py b/src/hi/integrations/urls.py
index 7f58d3cd..e5c1c1bf 100644
--- a/src/hi/integrations/urls.py
+++ b/src/hi/integrations/urls.py
@@ -10,6 +10,7 @@ from . import views
urlpatterns = [
path( 'connect/', include( 'hi.integrations.connector.urls' )),
path( 'import/', include( 'hi.integrations.importer.urls' )),
+ path( 'referencer/', include( 'hi.integrations.referencer.urls' )),
re_path( r'^placement/(?P<integration_id>[\w\-]+)$',
views.IntegrationPlacementView.as_view(),
diff --git a/src/hi/integrations/view_mixins.py b/src/hi/integrations/view_mixins.py
index c11d51b3..e5b2ac64 100644
--- a/src/hi/integrations/view_mixins.py
+++ b/src/hi/integrations/view_mixins.py
@@ -63,17 +63,17 @@ class CapabilityBlockViewMixin:
'my_label': 'Import',
'existing_count': existing_count,
'existing_mode_clause': (
- 'has data configured as Integration with'
+ 'already configured as a Connector with'
),
'desired_action_clause': (
- f'use {integration_data.label} as Import'
+ f'use {integration_data.label} as a Data Importer'
),
'remediation_clause': (
f'disable the {integration_data.label} '
- f'Integration'
+ f'Connector'
),
'link_url': reverse( 'integrations_connect_home' ),
- 'link_label': 'GO TO INTEGRATIONS',
+ 'link_label': 'GO TO CONNECTORS',
},
template_name = 'integrations/modals/capability_blocked.html',
)
diff --git a/src/hi/integrations/views.py b/src/hi/integrations/views.py
index 46756912..46dc38dd 100644
--- a/src/hi/integrations/views.py
+++ b/src/hi/integrations/views.py
@@ -57,10 +57,18 @@ class CapabilityConfigureView( HiModalView,
def get_template_name( self ) -> str:
return self.template_name
+ def get_capability_gateway( self, integration_data ):
+ """Return the ``CapabilityGateway`` instance for this configure
+ view's capability. Subclasses implement by calling the
+ appropriate per-capability getter on the gateway. The base
+ class deliberately does not enumerate capabilities — each
+ subclass already knows its own."""
+ raise NotImplementedError('Subclasses must override this method')
+
def _build_attr_item_context( self, integration_data ):
return IntegrationAttributeItemEditContext(
integration_data = integration_data,
- capability = self.capability,
+ capability_gateway = self.get_capability_gateway( integration_data ),
update_button_label = self.button_label,
suppress_history = True,
show_secrets = True,
@@ -302,9 +310,12 @@ class IntegrationAttributeHistoryInlineView( View,
integration_data = IntegrationManager().get_integration_data(
integration_id = attribute.integration.integration_id,
)
+ # History inline ops target a specific attribute by id; the
+ # capability filter inside the edit context is not consulted
+ # here, so no capability gateway is needed.
attr_item_context = IntegrationAttributeItemEditContext(
integration_data = integration_data,
- capability = IntegrationCapability.CONNECT,
+ capability_gateway = None,
)
return self.get_history(
request = request,
@@ -331,9 +342,12 @@ class IntegrationAttributeRestoreInlineView( View,
integration_id = attribute.integration.integration_id,
)
+ # Restore inline ops target a specific attribute by id; the
+ # capability filter inside the edit context is not consulted
+ # here, so no capability gateway is needed.
attr_item_context = IntegrationAttributeItemEditContext(
integration_data = integration_data,
- capability = IntegrationCapability.CONNECT,
+ capability_gateway = None,
)
return self.post_restore(
request = request,
diff --git a/src/hi/services/frigate/frigate_connector.py b/src/hi/services/frigate/frigate_connector.py
index e85052ec..601b020a 100644
--- a/src/hi/services/frigate/frigate_connector.py
+++ b/src/hi/services/frigate/frigate_connector.py
@@ -39,7 +39,7 @@ class FrigateConnector( IntegrationConnector, FrigateMixin ):
CAMERA_SNAPSHOT_STREAM_FPS = 1.0
- def get_integration_metadata(self):
+ def get_metadata(self):
return FrigateMetaData
def get_monitor(self) -> FrigateMonitor:
@@ -118,7 +118,7 @@ class FrigateConnector( IntegrationConnector, FrigateMixin ):
metadata = { 'event_id': event_id },
)
- def get_description(self, is_initial_connect : bool) -> Optional[ str ]:
+ def get_sync_description(self, is_initial_connect : bool) -> Optional[ str ]:
if is_initial_connect:
return (
'Each Frigate camera becomes a HI camera entity with'
diff --git a/src/hi/services/hass/hass_connector.py b/src/hi/services/hass/hass_connector.py
index 291beb5d..0f5f9acc 100644
--- a/src/hi/services/hass/hass_connector.py
+++ b/src/hi/services/hass/hass_connector.py
@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
class HassConnector( IntegrationConnector, HassMixin ):
- def get_integration_metadata(self):
+ def get_metadata(self):
return HassMetaData
def get_monitor(self) -> HassMonitor:
@@ -74,7 +74,7 @@ class HassConnector( IntegrationConnector, HassMixin ):
return VideoSnapshot( source_url = source_url )
- def get_description(self, is_initial_connect: bool) -> Optional[str]:
+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:
if is_initial_connect:
return 'Only items matching your Allowed Item Types setting will be imported.'
return 'Only items matching your Allowed Item Types setting are compared.'
diff --git a/src/hi/services/homebox/connector/homebox_connector.py b/src/hi/services/homebox/connector/homebox_connector.py
index f21baac2..0a0efdf8 100644
--- a/src/hi/services/homebox/connector/homebox_connector.py
+++ b/src/hi/services/homebox/connector/homebox_connector.py
@@ -30,7 +30,7 @@ logger = logging.getLogger(__name__)
class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):
- def get_integration_metadata(self):
+ def get_metadata(self):
return HbMetaData
def get_monitor(self) -> HomeBoxMonitor:
@@ -45,7 +45,7 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):
def get_external_view_data(self, entity: Entity) -> Optional[ExternalViewData]:
return HomeBoxExternalViewResolver().get_external_view_data(entity)
- def get_description(self, is_initial_connect: bool) -> Optional[str]:
+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:
return (
'HomeBox Labels and Locations are kept as metadata on '
'each item, not as separate organizational concepts in HI.'
diff --git a/src/hi/services/paperless/__init__.py b/src/hi/services/paperless/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/hi/services/paperless/apps.py b/src/hi/services/paperless/apps.py
new file mode 100644
index 00000000..c8db2bba
--- /dev/null
+++ b/src/hi/services/paperless/apps.py
@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class PaperlessConfig(AppConfig):
+ default_auto_field = 'django.db.models.BigAutoField'
+ name = 'hi.services.paperless'
diff --git a/src/hi/services/paperless/enums.py b/src/hi/services/paperless/enums.py
new file mode 100644
index 00000000..66c94f99
--- /dev/null
+++ b/src/hi/services/paperless/enums.py
@@ -0,0 +1,30 @@
+from hi.apps.attribute.enums import AttributeValueType
+
+from hi.integrations.enums import IntegrationAttributeType
+
+
+class PlAttributeType( IntegrationAttributeType ):
+ """Operator-configurable settings for the paperless integration.
+
+ Two required fields drive the entire ATTRIBUTE_REFERENCE surface:
+ the base URL of the paperless server (used by the referencer's
+ HTTP client and by the thumbnail proxy) and the API token sent
+ as ``Authorization: Token <value>`` on every upstream call.
+ """
+
+ API_URL = (
+ 'API URL',
+ 'e.g., https://paperless.example.com/',
+ AttributeValueType.TEXT,
+ None,
+ True,
+ True,
+ )
+ API_TOKEN = (
+ 'API Token',
+ 'Paperless token sent as Authorization: Token <value>.',
+ AttributeValueType.SECRET,
+ None,
+ True,
+ True,
+ )
diff --git a/src/hi/services/paperless/integration.py b/src/hi/services/paperless/integration.py
new file mode 100644
index 00000000..2c8a96bf
--- /dev/null
+++ b/src/hi/services/paperless/integration.py
@@ -0,0 +1,99 @@
+"""Gateway registration entry point for the paperless integration.
+
+ATTRIBUTE_REFERENCE-only: no Connector, no Importer, no monitors.
+The gateway returns the referencer and answers configuration /
+access validation; the referencer carries the actual search logic.
+"""
+import logging
+from typing import List, Optional
+from urllib.parse import urljoin
+
+import requests
+
+from hi.integrations.integration_gateway import IntegrationGateway
+from hi.integrations.models import IntegrationAttribute
+from hi.integrations.transient_models import (
+ ConnectionTestResult,
+ IntegrationKey,
+ IntegrationMetaData,
+ IntegrationValidationResult,
+)
+
+from .enums import PlAttributeType
+from .pl_metadata import PaperlessMetaData
+from .pl_models import PaperlessApi
+from .pl_referencer import PaperlessAttributeReferencer
+from .pl_validation import validate_attributes
+
+
+logger = logging.getLogger(__name__)
+
+
+class PaperlessGateway( IntegrationGateway ):
+
+ def get_metadata( self ) -> IntegrationMetaData:
+ return PaperlessMetaData
+
+ def get_attribute_referencer( self ) -> PaperlessAttributeReferencer:
+ return PaperlessAttributeReferencer()
+
+ def validate_configuration(
+ self,
+ integration_attributes : List[ IntegrationAttribute ],
+ ) -> IntegrationValidationResult:
+ return validate_attributes( integration_attributes )
+
+ def validate_access(
+ self,
+ integration_attributes : List[ IntegrationAttribute ],
+ timeout_secs : Optional[float],
+ ) -> ConnectionTestResult:
+ """Live access probe: a single tiny request against
+ ``/api/documents/?page_size=1`` with the configured auth.
+ Returns success on 200; the body is irrelevant."""
+ schema_result = validate_attributes( integration_attributes )
+ if not schema_result.is_valid:
+ return ConnectionTestResult.failure( schema_result.error_message )
+
+ attrs_by_key = {
+ attr.integration_key: attr for attr in integration_attributes
+ }
+ api_url = self._attribute_value( attrs_by_key, PlAttributeType.API_URL )
+ token = self._attribute_value( attrs_by_key, PlAttributeType.API_TOKEN )
+ # Normalize the same way the client does so the probe matches
+ # the runtime behavior.
+ normalized = api_url.rstrip('/') + '/'
+ probe_url = urljoin( normalized, PaperlessApi.DOCUMENTS_PATH )
+ try:
+ response = requests.get(
+ probe_url,
+ params = { PaperlessApi.PAGE_SIZE_PARAM: 1 },
+ headers = {
+ PaperlessApi.AUTH_HEADER: f'{PaperlessApi.AUTH_SCHEME} {token}',
+ },
+ timeout = timeout_secs if timeout_secs is not None else 5.0,
+ )
+ except requests.RequestException as e:
+ return ConnectionTestResult.failure(
+ f'Paperless unreachable: {e}'
+ )
+ if response.status_code == 200:
+ return ConnectionTestResult.success()
+ if response.status_code in (401, 403):
+ return ConnectionTestResult.failure(
+ f'Paperless auth rejected (HTTP {response.status_code}).'
+ )
+ return ConnectionTestResult.failure(
+ f'Paperless responded HTTP {response.status_code}.'
+ )
+
+ @staticmethod
+ def _attribute_value( attrs_by_key, attr_type : PlAttributeType ) -> str:
+ key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str( attr_type ),
+ )
+ attr = attrs_by_key.get( key )
+ if attr is None:
+ return ''
+ return ( attr.value or '' ).strip()
diff --git a/src/hi/services/paperless/pl_client.py b/src/hi/services/paperless/pl_client.py
new file mode 100644
index 00000000..37c87b63
--- /dev/null
+++ b/src/hi/services/paperless/pl_client.py
@@ -0,0 +1,150 @@
+"""HTTP client for the paperless-ngx ATTRIBUTE_REFERENCE integration.
+
+The client is intentionally small: a single thin wrapper over
+``requests.Session`` plus a factory that constructs one from the
+stored ``Integration`` attributes. There is no manager singleton —
+ATTRIBUTE_REFERENCE has no monitors and no cached state to own, so
+each call builds a fresh client from current DB state.
+
+The browser-facing thumbnail URL is built by the *referencer*, not
+the client; the client just knows how to fetch upstream once the
+caller has a document id.
+"""
+import logging
+from typing import Any, Dict, Optional
+from urllib.parse import urljoin
+
+import requests
+
+from hi.integrations.exceptions import IntegrationAttributeError
+from hi.integrations.models import Integration
+from hi.integrations.transient_models import IntegrationKey
+
+from .enums import PlAttributeType
+from .pl_metadata import PaperlessMetaData
+from .pl_models import PaperlessApi
+
+
+logger = logging.getLogger(__name__)
+
+
+class PaperlessClient:
+ """Thin paperless-ngx HTTP client. Constructed with the
+ configured base URL and API token; both are required and
+ non-empty (the factory enforces this).
+ """
+
+ DEFAULT_TIMEOUT_SECS = 5.0
+
+ def __init__(
+ self,
+ api_url : str,
+ token : str,
+ timeout_secs : Optional[float] = None,
+ ):
+ # Normalize once at construction so the API_URL is forgiving
+ # whether the operator pasted with or without a trailing
+ # slash. urljoin then composes paths predictably.
+ self.api_url = api_url.rstrip('/') + '/'
+ self.token = token
+ self._timeout_secs = (
+ timeout_secs if timeout_secs is not None
+ else self.DEFAULT_TIMEOUT_SECS
+ )
+ self._session = requests.Session()
+ self._session.headers.update({
+ PaperlessApi.AUTH_HEADER: f'{PaperlessApi.AUTH_SCHEME} {self.token}',
+ })
+
+ def search_documents(
+ self,
+ query : str,
+ page_size : int,
+ ) -> Dict[str, Any]:
+ """``GET <api_url>/api/documents/?query=<q>&page_size=<n>``;
+ returns the parsed JSON envelope (count + results + …)."""
+ url = urljoin( self.api_url, PaperlessApi.DOCUMENTS_PATH )
+ response = self._session.get(
+ url,
+ params = {
+ PaperlessApi.QUERY_PARAM: query,
+ PaperlessApi.PAGE_SIZE_PARAM: page_size,
+ },
+ timeout = self._timeout_secs,
+ )
+ response.raise_for_status()
+ return response.json()
+
+ def download_thumbnail( self, document_id : int ) -> Dict[str, Any]:
+ """Fetch the per-document thumbnail bytes from
+ ``/api/documents/<id>/thumb/``. Returns
+ ``{'content': bytes, 'mime_type': str}`` — the shape the
+ proxy view streams back to the browser."""
+ path = PaperlessApi.DOCUMENT_THUMB_PATH.format( id = document_id )
+ url = urljoin( self.api_url, path )
+ response = self._session.get( url, timeout = self._timeout_secs )
+ response.raise_for_status()
+ return {
+ 'content': response.content,
+ 'mime_type': response.headers.get(
+ 'Content-Type', 'application/octet-stream',
+ ),
+ }
+
+ def build_document_details_url( self, document_id : int ) -> str:
+ """Per-document web UI URL on the configured paperless server.
+ Persisted as the saved attribute's value so an operator
+ clicking the link later goes directly to paperless (no HI
+ proxy in the path)."""
+ path = PaperlessApi.DOCUMENT_DETAILS_PATH.format( id = document_id )
+ return urljoin( self.api_url, path )
+
+
+def build_client( timeout_secs : Optional[float] = None ) -> PaperlessClient:
+ """Construct a PaperlessClient from the configured paperless
+ Integration. Looks up the single (per-deployment) paperless
+ integration row and reads its API_URL + API_TOKEN attributes.
+
+ Raises:
+ Integration.DoesNotExist — paperless integration has never been
+ configured.
+ IntegrationAttributeError — required attribute is missing,
+ empty, or the integration is
+ disabled.
+ """
+ integration = Integration.objects.get(
+ integration_id = PaperlessMetaData.integration_id,
+ )
+ if not integration.is_enabled:
+ raise IntegrationAttributeError(
+ 'Paperless integration is disabled.'
+ )
+
+ attrs_by_key = integration.attributes_by_integration_key
+ api_url = _required_attribute_value(
+ attrs_by_key, PlAttributeType.API_URL,
+ )
+ token = _required_attribute_value(
+ attrs_by_key, PlAttributeType.API_TOKEN,
+ )
+ return PaperlessClient(
+ api_url = api_url,
+ token = token,
+ timeout_secs = timeout_secs,
+ )
+
+
+def _required_attribute_value(
+ attrs_by_key : Dict[IntegrationKey, Any],
+ attr_type : PlAttributeType,
+) -> str:
+ key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str( attr_type ),
+ )
+ attr = attrs_by_key.get( key )
+ if attr is None or not (attr.value or '').strip():
+ raise IntegrationAttributeError(
+ f'Missing paperless attribute: {attr_type.label}'
+ )
+ return attr.value.strip()
diff --git a/src/hi/services/paperless/pl_metadata.py b/src/hi/services/paperless/pl_metadata.py
new file mode 100644
index 00000000..fd8f188f
--- /dev/null
+++ b/src/hi/services/paperless/pl_metadata.py
@@ -0,0 +1,25 @@
+from hi.integrations.enums import IntegrationCapability
+from hi.integrations.transient_models import IntegrationMetaData
+
+from .enums import PlAttributeType
+
+
+PaperlessMetaData = IntegrationMetaData(
+ # ``paperless`` (not ``paperless-ngx``) for internal naming, in
+ # line with how zoneminder / homebox use the short form. The
+ # human label keeps the ``-ngx`` suffix.
+ integration_id = 'paperless',
+ label = 'Paperless-ngx',
+ attribute_type = PlAttributeType,
+ # Paperless documents become TEXT attributes on existing
+ # Entity / Location records via ATTRIBUTE_REFERENCE; the
+ # integration never creates HI Entities of its own, so deletion
+ # behavior is moot. Internal attributes (those created by HI
+ # outside the integration's settings) are not supported here.
+ allow_entity_deletion = False,
+ allow_internal_attributes = False,
+ logo_static_path = 'img/integrations/paperless.png',
+ capabilities = frozenset({
+ IntegrationCapability.ATTRIBUTE_REFERENCE,
+ }),
+)
diff --git a/src/hi/services/paperless/pl_models.py b/src/hi/services/paperless/pl_models.py
new file mode 100644
index 00000000..3c5264f9
--- /dev/null
+++ b/src/hi/services/paperless/pl_models.py
@@ -0,0 +1,45 @@
+"""Paperless wire-format constants.
+
+Every string that crosses the wire to a paperless-ngx server lives
+here: API path templates, JSON field names in responses, and the
+authorization scheme. The client and referencer pull from this
+single class so a wire-side rename is a one-file edit.
+"""
+
+
+class PaperlessApi:
+ """Wire-format strings shared between the client and the
+ referencer. Paths are appended to the configured ``API_URL``
+ base; ``{id}`` is the per-document substitution token."""
+
+ # ---- URL paths (relative to the configured API_URL) ----
+
+ DOCUMENTS_PATH = 'api/documents/'
+ DOCUMENT_THUMB_PATH = 'api/documents/{id}/thumb/'
+ # Per-document web UI route. Used unchanged as the persisted
+ # attribute value; operators clicking the saved link land on
+ # paperless's own page (authenticated by their paperless session,
+ # not by HI).
+ DOCUMENT_DETAILS_PATH = 'documents/{id}/details/'
+
+ # ---- Query parameters ----
+
+ QUERY_PARAM = 'query'
+ PAGE_SIZE_PARAM = 'page_size'
+
+ # ---- Authorization ----
+
+ AUTH_HEADER = 'Authorization'
+ AUTH_SCHEME = 'Token' # ``Authorization: Token <value>``
+
+ # ---- Documents-list response JSON keys ----
+
+ RESPONSE_COUNT = 'count'
+ RESPONSE_RESULTS = 'results'
+
+ # ---- Per-document JSON keys ----
+
+ DOC_ID = 'id'
+ DOC_TITLE = 'title'
+ DOC_CONTENT = 'content'
+ DOC_MIME_TYPE = 'mime_type'
diff --git a/src/hi/services/paperless/pl_referencer.py b/src/hi/services/paperless/pl_referencer.py
new file mode 100644
index 00000000..e34630d3
--- /dev/null
+++ b/src/hi/services/paperless/pl_referencer.py
@@ -0,0 +1,172 @@
+"""ATTRIBUTE_REFERENCE implementation for paperless-ngx.
+
+Translates each paperless documents-search hit into a single
+``AttributeReferenceResult``:
+
+ - ``title`` → document title (verbatim)
+ - ``source_url`` → upstream per-document URL on the configured
+ paperless server. Persisted as the saved
+ attribute's value; operators clicking the
+ saved link go directly to paperless and
+ authenticate via their own paperless session.
+ - ``thumbnail_url`` → HI's thumbnail-proxy URL. The picker renders
+ this as <img src=…>; the browser's request
+ carries the HI session (not the paperless
+ API token), and HI fetches the upstream
+ thumbnail server-side.
+ - ``mime_type`` → upstream document MIME (drives the picker's
+ fallback-icon path when no thumbnail).
+ - ``snippet`` → ~160-char window around the query match in
+ the document's content. Paperless's search
+ endpoint returns full ``content`` per hit;
+ we extract a window client-side rather than
+ persist or display the whole document text.
+"""
+import logging
+from typing import List, Optional
+
+from django.urls import reverse
+from requests import HTTPError
+
+from hi.integrations.exceptions import IntegrationAttributeError
+from hi.integrations.referencer.integration_referencer import (
+ IntegrationAttributeReferencer,
+)
+from hi.integrations.referencer.transient_models import (
+ AttributeReferenceResult,
+)
+from hi.integrations.transient_models import (
+ IntegrationMetaData,
+ IntegrationValidationResult,
+)
+
+from .pl_client import PaperlessClient, build_client
+from .pl_metadata import PaperlessMetaData
+from .pl_models import PaperlessApi
+from .pl_validation import validate_attributes
+
+
+logger = logging.getLogger(__name__)
+
+
+class PaperlessAttributeReferencer( IntegrationAttributeReferencer ):
+
+ # Window cap matches the picker's snippet rendering — long
+ # enough to carry useful context, short enough to keep cards
+ # compact and the query visible.
+ SNIPPET_WINDOW = 160
+ # Characters before the matched query to include as leading
+ # context. The trailing context fills the remainder up to
+ # ``SNIPPET_WINDOW``.
+ SNIPPET_LEAD = 40
+
+ def get_metadata( self ) -> IntegrationMetaData:
+ return PaperlessMetaData
+
+ def validate_configuration(
+ self,
+ integration_attributes,
+ ) -> IntegrationValidationResult:
+ return validate_attributes( integration_attributes )
+
+ def search_references(
+ self,
+ query : str,
+ limit : int = 20,
+ ) -> List[ AttributeReferenceResult ]:
+ if not query or not query.strip():
+ return []
+ try:
+ client = build_client()
+ except IntegrationAttributeError as e:
+ logger.warning( f'Paperless search aborted: {e}' )
+ return []
+ except Exception as e:
+ logger.exception( f'Paperless client build failed: {e}' )
+ return []
+
+ try:
+ envelope = client.search_documents(
+ query = query.strip(), page_size = limit,
+ )
+ except HTTPError as e:
+ status = getattr( e.response, 'status_code', None )
+ logger.warning(
+ f'Paperless search HTTP {status} for query '
+ f'{query!r}: {e}'
+ )
+ return []
+ except Exception as e:
+ logger.warning(
+ f'Paperless search failed for query {query!r}: {e}'
+ )
+ return []
+
+ documents = envelope.get( PaperlessApi.RESPONSE_RESULTS, [] ) or []
+ return [
+ self._translate( client = client, document = doc, query = query )
+ for doc in documents
+ ]
+
+ def _translate(
+ self,
+ client : PaperlessClient,
+ document : dict,
+ query : str,
+ ) -> AttributeReferenceResult:
+ document_id = document.get( PaperlessApi.DOC_ID )
+ title = document.get( PaperlessApi.DOC_TITLE ) or ''
+ content = document.get( PaperlessApi.DOC_CONTENT ) or ''
+ mime_type = document.get( PaperlessApi.DOC_MIME_TYPE )
+ return AttributeReferenceResult(
+ title = title,
+ source_url = client.build_document_details_url( document_id ),
+ thumbnail_url = self._proxy_thumbnail_url( document_id ),
+ mime_type = mime_type,
+ snippet = self._extract_snippet( content = content, query = query ),
+ )
+
+ @staticmethod
+ def _proxy_thumbnail_url( document_id : int ) -> str:
+ # HI-internal URL that streams the upstream thumbnail through
+ # the configured token. The picker renders <img src=…> so the
+ # browser fetches this under HI's session.
+ return reverse(
+ 'paperless_thumbnail',
+ kwargs = { 'document_id': document_id },
+ )
+
+ @classmethod
+ def _extract_snippet(
+ cls, content : str, query : str,
+ ) -> Optional[str]:
+ """Return a short window around the query match inside the
+ document content. Falls back to the document's leading
+ characters when the query isn't found verbatim (e.g.,
+ paperless matched on a stemmed form). Returns None when
+ there is no content at all so the picker leaves the snippet
+ row out entirely."""
+ if not content:
+ return None
+ if not query:
+ return cls._truncate( content, cls.SNIPPET_WINDOW )
+
+ lowered_content = content.lower()
+ lowered_query = query.strip().lower()
+ idx = lowered_content.find( lowered_query )
+ if idx < 0:
+ return cls._truncate( content, cls.SNIPPET_WINDOW )
+
+ start = max( 0, idx - cls.SNIPPET_LEAD )
+ end = min( len(content), start + cls.SNIPPET_WINDOW )
+ snippet = content[ start : end ]
+ prefix = '…' if start > 0 else ''
+ suffix = '…' if end < len(content) else ''
+ return f'{prefix}{snippet}{suffix}'
+
+ @staticmethod
+ def _truncate( content : str, max_chars : int ) -> str:
+ stripped = content.strip()
+ if len(stripped) <= max_chars:
+ return stripped
+ return stripped[:max_chars].rstrip() + '…'
diff --git a/src/hi/services/paperless/pl_validation.py b/src/hi/services/paperless/pl_validation.py
new file mode 100644
index 00000000..4c210dfe
--- /dev/null
+++ b/src/hi/services/paperless/pl_validation.py
@@ -0,0 +1,77 @@
+"""Configuration validation for the paperless integration.
+
+Shared between the referencer (``validate_configuration``) and the
+gateway (``validate_configuration`` + ``validate_access``). Pure
+schema-level checks live in ``validate_attributes``; the
+network-probing access check is in the gateway proper.
+"""
+from typing import Dict, List
+from urllib.parse import urlparse
+
+from hi.apps.system.enums import HealthStatusType
+from hi.integrations.models import IntegrationAttribute
+from hi.integrations.transient_models import (
+ IntegrationKey,
+ IntegrationValidationResult,
+)
+
+from .enums import PlAttributeType
+from .pl_metadata import PaperlessMetaData
+
+
+_VALID_SCHEMES = frozenset({ 'http', 'https' })
+
+
+def validate_attributes(
+ integration_attributes : List[ IntegrationAttribute ],
+) -> IntegrationValidationResult:
+ """Schema-only validation: required attributes present and
+ non-empty; API_URL has http(s) scheme and a netloc. Does NOT
+ perform network operations."""
+ attrs_by_key = _attributes_by_key( integration_attributes )
+
+ api_url = _value( attrs_by_key, PlAttributeType.API_URL )
+ if not api_url:
+ return IntegrationValidationResult.error(
+ status = HealthStatusType.WARNING,
+ error_message = f'Missing required attribute: {PlAttributeType.API_URL.label}',
+ )
+
+ parsed = urlparse( api_url )
+ if parsed.scheme not in _VALID_SCHEMES or not parsed.netloc:
+ return IntegrationValidationResult.error(
+ status = HealthStatusType.WARNING,
+ error_message = (
+ f'{PlAttributeType.API_URL.label} must be an http(s) URL '
+ f'with a hostname; got {api_url!r}.'
+ ),
+ )
+
+ token = _value( attrs_by_key, PlAttributeType.API_TOKEN )
+ if not token:
+ return IntegrationValidationResult.error(
+ status = HealthStatusType.WARNING,
+ error_message = f'Missing required attribute: {PlAttributeType.API_TOKEN.label}',
+ )
+
+ return IntegrationValidationResult.success()
+
+
+def _attributes_by_key(
+ integration_attributes : List[ IntegrationAttribute ],
+) -> Dict[ IntegrationKey, IntegrationAttribute ]:
+ return { attr.integration_key: attr for attr in integration_attributes }
+
+
+def _value(
+ attrs_by_key : Dict[ IntegrationKey, IntegrationAttribute ],
+ attr_type : PlAttributeType,
+) -> str:
+ key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str( attr_type ),
+ )
+ attr = attrs_by_key.get( key )
+ if attr is None:
+ return ''
+ return ( attr.value or '' ).strip()
diff --git a/src/hi/services/paperless/tests/__init__.py b/src/hi/services/paperless/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/hi/services/paperless/tests/test_pl_client.py b/src/hi/services/paperless/tests/test_pl_client.py
new file mode 100644
index 00000000..86162e25
--- /dev/null
+++ b/src/hi/services/paperless/tests/test_pl_client.py
@@ -0,0 +1,152 @@
+"""Tests for the paperless HTTP client and its factory.
+
+The client is a thin requests wrapper; tests cover URL composition,
+auth header, the documents-search + thumbnail-download calls, and
+the trailing-slash forgiving normalization. The factory tests cover
+the DB-driven config lookup, including the disabled-integration and
+missing-attribute paths that should refuse to hand back a client.
+"""
+import logging
+from unittest.mock import Mock, patch
+
+from django.test import TestCase
+
+from hi.apps.attribute.enums import AttributeValueType
+from hi.integrations.exceptions import IntegrationAttributeError
+from hi.integrations.models import Integration, IntegrationAttribute
+from hi.integrations.transient_models import IntegrationKey
+
+from hi.services.paperless.enums import PlAttributeType
+from hi.services.paperless.pl_client import PaperlessClient, build_client
+from hi.services.paperless.pl_metadata import PaperlessMetaData
+
+
+logging.disable(logging.CRITICAL)
+
+
+def _make_attr(integration, attr_type, value):
+ attr = IntegrationAttribute(
+ integration = integration,
+ name = attr_type.label,
+ value = value,
+ value_type_str = str(AttributeValueType.TEXT),
+ attribute_type_str = 'PREDEFINED',
+ )
+ attr.integration_key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str(attr_type),
+ )
+ attr.save()
+ return attr
+
+
+class TestPaperlessClient(TestCase):
+
+ def test_trailing_slash_normalized(self):
+ # The factory forgives operators who paste with or without a
+ # trailing slash; both should yield the same upstream URLs.
+ c1 = PaperlessClient(api_url = 'https://p.example.com', token = 't')
+ c2 = PaperlessClient(api_url = 'https://p.example.com/', token = 't')
+ self.assertEqual(c1.api_url, 'https://p.example.com/')
+ self.assertEqual(c2.api_url, 'https://p.example.com/')
+
+ def test_auth_header_set_on_session(self):
+ client = PaperlessClient(api_url = 'https://p.example.com', token = 'abc')
+ self.assertEqual(
+ client._session.headers['Authorization'],
+ 'Token abc',
+ )
+
+ def test_search_documents_dispatches_and_returns_json(self):
+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')
+ envelope = {'count': 2, 'results': [{'id': 1}, {'id': 2}]}
+ response = Mock()
+ response.json.return_value = envelope
+ response.raise_for_status = Mock()
+ with patch.object(client._session, 'get', return_value = response) as mock_get:
+ result = client.search_documents(query = 'dishwasher', page_size = 50)
+
+ self.assertEqual(result, envelope)
+ args, kwargs = mock_get.call_args
+ # URL composes against the normalized base.
+ self.assertEqual(args[0], 'https://p.example.com/api/documents/')
+ self.assertEqual(kwargs['params']['query'], 'dishwasher')
+ self.assertEqual(kwargs['params']['page_size'], 50)
+
+ def test_download_thumbnail_returns_bytes_and_mime(self):
+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')
+ response = Mock()
+ response.content = b'PNG-BYTES'
+ response.headers = {'Content-Type': 'image/png'}
+ response.raise_for_status = Mock()
+ with patch.object(client._session, 'get', return_value = response) as mock_get:
+ result = client.download_thumbnail(document_id = 42)
+
+ self.assertEqual(result, {'content': b'PNG-BYTES', 'mime_type': 'image/png'})
+ args, _ = mock_get.call_args
+ self.assertEqual(args[0], 'https://p.example.com/api/documents/42/thumb/')
+
+ def test_download_thumbnail_default_mime_when_missing(self):
+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')
+ response = Mock()
+ response.content = b'raw'
+ response.headers = {}
+ response.raise_for_status = Mock()
+ with patch.object(client._session, 'get', return_value = response):
+ result = client.download_thumbnail(document_id = 1)
+ self.assertEqual(result['mime_type'], 'application/octet-stream')
+
+ def test_build_document_details_url(self):
+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')
+ self.assertEqual(
+ client.build_document_details_url(document_id = 7),
+ 'https://p.example.com/documents/7/details/',
+ )
+
+
+class TestBuildClient(TestCase):
+
+ def setUp(self):
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = True,
+ )
+
+ def test_returns_configured_client(self):
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com')
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'abc')
+ client = build_client()
+ self.assertIsInstance(client, PaperlessClient)
+ # Trailing slash normalized.
+ self.assertEqual(client.api_url, 'https://paperless.example.com/')
+ self.assertEqual(client.token, 'abc')
+
+ def test_no_integration_row_raises(self):
+ # Wipe the row created in setUp.
+ Integration.objects.all().delete()
+ with self.assertRaises(Integration.DoesNotExist):
+ build_client()
+
+ def test_disabled_integration_raises(self):
+ self.integration.is_enabled = False
+ self.integration.save()
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com')
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'abc')
+ with self.assertRaises(IntegrationAttributeError):
+ build_client()
+
+ def test_missing_attribute_raises(self):
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com')
+ # API_TOKEN deliberately omitted.
+ with self.assertRaises(IntegrationAttributeError):
+ build_client()
+
+ def test_empty_attribute_value_raises(self):
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com')
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, ' ')
+ with self.assertRaises(IntegrationAttributeError):
+ build_client()
diff --git a/src/hi/services/paperless/tests/test_pl_gateway.py b/src/hi/services/paperless/tests/test_pl_gateway.py
new file mode 100644
index 00000000..8c9a7e11
--- /dev/null
+++ b/src/hi/services/paperless/tests/test_pl_gateway.py
@@ -0,0 +1,123 @@
+"""Gateway tests: capability registration + validate_access probe.
+
+Schema validation is exercised in detail in test_pl_validation; this
+file covers the gateway's wiring to the referencer and the network
+probe it runs for the "Test Connection" path.
+"""
+import logging
+from unittest.mock import Mock, patch
+
+from django.test import TestCase
+from requests import RequestException
+
+from hi.apps.attribute.enums import AttributeValueType
+from hi.integrations.enums import IntegrationCapability
+from hi.integrations.models import Integration, IntegrationAttribute
+from hi.integrations.transient_models import IntegrationKey
+
+from hi.services.paperless.enums import PlAttributeType
+from hi.services.paperless.integration import PaperlessGateway
+from hi.services.paperless.pl_metadata import PaperlessMetaData
+from hi.services.paperless.pl_referencer import PaperlessAttributeReferencer
+
+
+logging.disable(logging.CRITICAL)
+
+
+def _make_attr(integration, attr_type, value):
+ attr = IntegrationAttribute(
+ integration = integration,
+ name = attr_type.label,
+ value = value,
+ value_type_str = str(AttributeValueType.TEXT),
+ attribute_type_str = 'PREDEFINED',
+ )
+ attr.integration_key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str(attr_type),
+ )
+ return attr
+
+
+class TestPaperlessGatewayWiring(TestCase):
+
+ def test_metadata_declares_attribute_reference(self):
+ meta = PaperlessGateway().get_metadata()
+ self.assertEqual(meta.integration_id, 'paperless')
+ self.assertEqual(meta.label, 'Paperless-ngx')
+ self.assertIn(IntegrationCapability.ATTRIBUTE_REFERENCE,
+ meta.capabilities)
+
+ def test_returns_referencer(self):
+ referencer = PaperlessGateway().get_attribute_referencer()
+ self.assertIsInstance(referencer, PaperlessAttributeReferencer)
+
+
+class TestValidateAccess(TestCase):
+
+ def setUp(self):
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = True,
+ )
+ self.attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com'),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),
+ ]
+
+ @patch('hi.services.paperless.integration.requests.get')
+ def test_200_response_returns_success(self, mock_get):
+ mock_get.return_value = Mock(status_code = 200)
+ result = PaperlessGateway().validate_access(
+ integration_attributes = self.attrs,
+ timeout_secs = 1.0,
+ )
+ self.assertTrue(result.is_success)
+ # Probe issues a single tiny request — page_size=1 keeps the
+ # upstream cost minimal.
+ _, kwargs = mock_get.call_args
+ self.assertEqual(kwargs['params']['page_size'], 1)
+ self.assertEqual(kwargs['headers']['Authorization'], 'Token token-abc')
+
+ @patch('hi.services.paperless.integration.requests.get')
+ def test_401_returns_auth_failure(self, mock_get):
+ mock_get.return_value = Mock(status_code = 401)
+ result = PaperlessGateway().validate_access(
+ integration_attributes = self.attrs, timeout_secs = 1.0,
+ )
+ self.assertFalse(result.is_success)
+ self.assertIn('auth', result.message.lower())
+
+ @patch('hi.services.paperless.integration.requests.get')
+ def test_5xx_returns_failure(self, mock_get):
+ mock_get.return_value = Mock(status_code = 503)
+ result = PaperlessGateway().validate_access(
+ integration_attributes = self.attrs, timeout_secs = 1.0,
+ )
+ self.assertFalse(result.is_success)
+ self.assertIn('503', result.message)
+
+ @patch('hi.services.paperless.integration.requests.get',
+ side_effect = RequestException('refused'))
+ def test_unreachable_returns_failure(self, _mock_get):
+ result = PaperlessGateway().validate_access(
+ integration_attributes = self.attrs, timeout_secs = 1.0,
+ )
+ self.assertFalse(result.is_success)
+ self.assertIn('unreachable', result.message.lower())
+
+ def test_schema_invalid_short_circuits(self):
+ # When attributes don't even pass schema validation we must
+ # not attempt the network call. patch.object on requests.get
+ # asserts no call.
+ bad_attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL, ''),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'tok'),
+ ]
+ with patch('hi.services.paperless.integration.requests.get') as mock_get:
+ result = PaperlessGateway().validate_access(
+ integration_attributes = bad_attrs, timeout_secs = 1.0,
+ )
+ self.assertFalse(result.is_success)
+ mock_get.assert_not_called()
diff --git a/src/hi/services/paperless/tests/test_pl_proxy_views.py b/src/hi/services/paperless/tests/test_pl_proxy_views.py
new file mode 100644
index 00000000..377c2c9b
--- /dev/null
+++ b/src/hi/services/paperless/tests/test_pl_proxy_views.py
@@ -0,0 +1,81 @@
+"""Tests for the paperless thumbnail proxy view.
+
+Mirrors the HomeBox attachment-proxy test shape: unconfigured
+integration → 404; upstream 404 → 404; other upstream failures →
+502; success → 200 with passthrough bytes + content-type.
+"""
+import logging
+from unittest.mock import Mock, patch
+
+from django.test import TestCase
+from django.urls import reverse
+from requests import HTTPError, RequestException
+
+from hi.integrations.exceptions import IntegrationAttributeError
+
+
+logging.disable(logging.CRITICAL)
+
+
+class TestThumbnailProxyView(TestCase):
+
+ def _url(self, document_id: int = 1) -> str:
+ return reverse(
+ 'paperless_thumbnail',
+ kwargs = {'document_id': document_id},
+ )
+
+ @patch('hi.services.paperless.views.build_client',
+ side_effect = IntegrationAttributeError('not configured'))
+ def test_unconfigured_returns_404(self, _mock_build):
+ response = self.client.get(self._url())
+ self.assertEqual(response.status_code, 404)
+
+ @patch('hi.services.paperless.views.build_client')
+ def test_successful_download_returns_bytes_and_mime(self, mock_build):
+ client = Mock()
+ client.download_thumbnail.return_value = {
+ 'content': b'PNG-BYTES',
+ 'mime_type': 'image/png',
+ }
+ mock_build.return_value = client
+
+ response = self.client.get(self._url(document_id = 42))
+
+ self.assertEqual(response.status_code, 200)
+ self.assertEqual(response.content, b'PNG-BYTES')
+ self.assertEqual(response['Content-Type'], 'image/png')
+ client.download_thumbnail.assert_called_once_with(document_id = 42)
+
+ @patch('hi.services.paperless.views.build_client')
+ def test_upstream_404_returns_404(self, mock_build):
+ client = Mock()
+ response = Mock()
+ response.status_code = 404
+ client.download_thumbnail.side_effect = HTTPError('404', response = response)
+ mock_build.return_value = client
+
+ result = self.client.get(self._url())
+ self.assertEqual(result.status_code, 404)
+
+ @patch('hi.services.paperless.views.build_client')
+ def test_upstream_401_returns_502(self, mock_build):
+ # Auth-level failures still get the bad-gateway treatment;
+ # the browser sees "upstream trouble", not "doc missing".
+ client = Mock()
+ response = Mock()
+ response.status_code = 401
+ client.download_thumbnail.side_effect = HTTPError('401', response = response)
+ mock_build.return_value = client
+
+ result = self.client.get(self._url())
+ self.assertEqual(result.status_code, 502)
+
+ @patch('hi.services.paperless.views.build_client')
+ def test_connection_error_returns_502(self, mock_build):
+ client = Mock()
+ client.download_thumbnail.side_effect = RequestException('boom')
+ mock_build.return_value = client
+
+ result = self.client.get(self._url())
+ self.assertEqual(result.status_code, 502)
diff --git a/src/hi/services/paperless/tests/test_pl_referencer.py b/src/hi/services/paperless/tests/test_pl_referencer.py
new file mode 100644
index 00000000..b0a7e679
--- /dev/null
+++ b/src/hi/services/paperless/tests/test_pl_referencer.py
@@ -0,0 +1,247 @@
+"""Tests for the ATTRIBUTE_REFERENCE referencer.
+
+Covers the two surfaces that matter for picker UX: snippet
+extraction (window around the matched query, with paperless-style
+fallbacks when no match) and the end-to-end translation of a
+paperless documents-search response into AttributeReferenceResult
+rows the framework can hand to the picker.
+"""
+import logging
+from unittest.mock import Mock, patch
+
+from django.test import TestCase
+from requests import HTTPError
+
+from hi.apps.attribute.enums import AttributeValueType
+from hi.integrations.exceptions import IntegrationAttributeError
+from hi.integrations.models import Integration, IntegrationAttribute
+from hi.integrations.transient_models import IntegrationKey
+
+from hi.services.paperless.enums import PlAttributeType
+from hi.services.paperless.pl_metadata import PaperlessMetaData
+from hi.services.paperless.pl_referencer import PaperlessAttributeReferencer
+
+
+logging.disable(logging.CRITICAL)
+
+
+def _make_attr(integration, attr_type, value):
+ attr = IntegrationAttribute(
+ integration = integration,
+ name = attr_type.label,
+ value = value,
+ value_type_str = str(AttributeValueType.TEXT),
+ attribute_type_str = 'PREDEFINED',
+ )
+ attr.integration_key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str(attr_type),
+ )
+ attr.save()
+ return attr
+
+
+class TestSnippetExtraction(TestCase):
+
+ def test_none_for_empty_content(self):
+ # Empty content => omit the snippet row entirely in the
+ # picker rather than render an empty placeholder.
+ self.assertIsNone(
+ PaperlessAttributeReferencer._extract_snippet(
+ content = '', query = 'q',
+ )
+ )
+
+ def test_short_content_returned_verbatim(self):
+ self.assertEqual(
+ PaperlessAttributeReferencer._extract_snippet(
+ content = 'Short doc text.', query = 'missing',
+ ),
+ 'Short doc text.',
+ )
+
+ def test_long_content_without_match_truncates(self):
+ result = PaperlessAttributeReferencer._extract_snippet(
+ content = 'A' * 500, query = 'missing',
+ )
+ self.assertLessEqual(len(result), 161) # 160 + the ellipsis
+ self.assertTrue(result.endswith('…'))
+
+ def test_match_in_middle_emits_leading_and_trailing_ellipses(self):
+ content = 'x' * 200 + ' DISHWASHER ' + 'y' * 200
+ result = PaperlessAttributeReferencer._extract_snippet(
+ content = content, query = 'dishwasher',
+ )
+ self.assertIn('DISHWASHER', result)
+ self.assertTrue(result.startswith('…'))
+ self.assertTrue(result.endswith('…'))
+
+ def test_match_at_start_no_leading_ellipsis(self):
+ result = PaperlessAttributeReferencer._extract_snippet(
+ content = 'Warranty info follows.', query = 'warranty',
+ )
+ self.assertFalse(result.startswith('…'))
+
+ def test_case_insensitive_match(self):
+ result = PaperlessAttributeReferencer._extract_snippet(
+ content = 'The DISHWASHER manual.', query = 'dishwasher',
+ )
+ self.assertIn('DISHWASHER', result)
+
+
+class TestSearchReferences(TestCase):
+ """End-to-end search via a mocked PaperlessClient."""
+
+ def setUp(self):
+ self.referencer = PaperlessAttributeReferencer()
+
+ def _envelope(self, *docs):
+ return {'count': len(docs), 'results': list(docs)}
+
+ def _doc(self, doc_id, **kwargs):
+ d = {
+ 'id': doc_id,
+ 'title': f'Doc {doc_id}',
+ 'content': 'Some content text.',
+ 'mime_type': 'application/pdf',
+ }
+ d.update(kwargs)
+ return d
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_empty_query_returns_empty_without_dispatch(self, mock_build):
+ # Short-circuit so the picker can render a blank initial
+ # modal without provoking an upstream call.
+ result = self.referencer.search_references(query = '', limit = 20)
+ self.assertEqual(result, [])
+ mock_build.assert_not_called()
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_whitespace_query_returns_empty(self, mock_build):
+ result = self.referencer.search_references(query = ' ', limit = 20)
+ self.assertEqual(result, [])
+ mock_build.assert_not_called()
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_translates_paperless_documents_to_results(self, mock_build):
+ client = Mock()
+ client.search_documents.return_value = self._envelope(
+ self._doc(1, title = 'Warranty',
+ content = 'Warranty terms for the unit.'),
+ self._doc(2, title = 'Manual',
+ content = 'Installation manual.', mime_type = 'text/plain'),
+ )
+ client.build_document_details_url.side_effect = (
+ lambda id: f'https://p.example.com/documents/{id}/details/'
+ )
+ mock_build.return_value = client
+
+ results = self.referencer.search_references(
+ query = 'warranty', limit = 20,
+ )
+
+ self.assertEqual(len(results), 2)
+ self.assertEqual(results[0].title, 'Warranty')
+ self.assertEqual(
+ results[0].source_url,
+ 'https://p.example.com/documents/1/details/',
+ )
+ # Thumbnail is the HI proxy URL, NOT the upstream URL — the
+ # browser fetches via HI's session and HI fetches upstream
+ # with the configured token.
+ self.assertIn('/integration/services/paperless/documents/1/thumb/',
+ results[0].thumbnail_url)
+ self.assertEqual(results[0].mime_type, 'application/pdf')
+ self.assertIn('Warranty', results[0].snippet)
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_limit_is_passed_through_as_page_size(self, mock_build):
+ client = Mock()
+ client.search_documents.return_value = self._envelope()
+ client.build_document_details_url.side_effect = (
+ lambda id: f'https://p.example.com/documents/{id}/details/'
+ )
+ mock_build.return_value = client
+
+ self.referencer.search_references(query = 'q', limit = 50)
+ client.search_documents.assert_called_once_with(
+ query = 'q', page_size = 50,
+ )
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_missing_results_key_yields_empty(self, mock_build):
+ # Defensive: don't blow up if upstream's envelope omits the
+ # results key (or sends null).
+ client = Mock()
+ client.search_documents.return_value = {'count': 0}
+ client.build_document_details_url.side_effect = (
+ lambda id: f'https://p.example.com/documents/{id}/details/'
+ )
+ mock_build.return_value = client
+ self.assertEqual(
+ self.referencer.search_references(query = 'q', limit = 20),
+ [],
+ )
+
+ @patch('hi.services.paperless.pl_referencer.build_client',
+ side_effect = IntegrationAttributeError('not configured'))
+ def test_unconfigured_integration_returns_empty(self, _mock_build):
+ # Operator opens the picker before configuring the
+ # integration — referencer must fail soft so the modal can
+ # render an empty result list rather than 500.
+ self.assertEqual(
+ self.referencer.search_references(query = 'q', limit = 20),
+ [],
+ )
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_upstream_http_error_returns_empty(self, mock_build):
+ client = Mock()
+ response = Mock()
+ response.status_code = 401
+ error = HTTPError('401', response = response)
+ client.search_documents.side_effect = error
+ mock_build.return_value = client
+ self.assertEqual(
+ self.referencer.search_references(query = 'q', limit = 20),
+ [],
+ )
+
+ @patch('hi.services.paperless.pl_referencer.build_client')
+ def test_unexpected_exception_returns_empty(self, mock_build):
+ client = Mock()
+ client.search_documents.side_effect = RuntimeError('boom')
+ mock_build.return_value = client
+ self.assertEqual(
+ self.referencer.search_references(query = 'q', limit = 20),
+ [],
+ )
+
+
+class TestValidateConfiguration(TestCase):
+ """``validate_configuration`` is the schema check delegated to
+ ``pl_validation.validate_attributes`` (covered there in detail).
+ Smoke-test that the referencer forwards correctly."""
+
+ def setUp(self):
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = True,
+ )
+
+ def test_success_when_attributes_valid(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com/'),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),
+ ]
+ result = PaperlessAttributeReferencer().validate_configuration(attrs)
+ self.assertTrue(result.is_valid)
+
+ def test_error_when_token_missing(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com/'),
+ ]
+ result = PaperlessAttributeReferencer().validate_configuration(attrs)
+ self.assertFalse(result.is_valid)
diff --git a/src/hi/services/paperless/tests/test_pl_validation.py b/src/hi/services/paperless/tests/test_pl_validation.py
new file mode 100644
index 00000000..734ec88d
--- /dev/null
+++ b/src/hi/services/paperless/tests/test_pl_validation.py
@@ -0,0 +1,104 @@
+"""Schema-only validation for paperless integration attributes.
+
+Validation is shared between the gateway's
+``validate_configuration`` and the referencer's, so tests target the
+helper directly. Network probes belong to ``validate_access`` —
+covered separately.
+"""
+import logging
+
+from django.test import TestCase
+
+from hi.apps.attribute.enums import AttributeValueType
+from hi.apps.system.enums import HealthStatusType
+from hi.integrations.models import Integration, IntegrationAttribute
+from hi.integrations.transient_models import IntegrationKey
+
+from hi.services.paperless.enums import PlAttributeType
+from hi.services.paperless.pl_metadata import PaperlessMetaData
+from hi.services.paperless.pl_validation import validate_attributes
+
+
+logging.disable(logging.CRITICAL)
+
+
+def _make_attr(integration, attr_type, value):
+ attr = IntegrationAttribute(
+ integration = integration,
+ name = attr_type.label,
+ value = value,
+ value_type_str = str(AttributeValueType.TEXT),
+ attribute_type_str = 'PREDEFINED',
+ )
+ attr.integration_key = IntegrationKey(
+ integration_id = PaperlessMetaData.integration_id,
+ integration_name = str(attr_type),
+ )
+ return attr
+
+
+class TestValidateAttributes(TestCase):
+
+ def setUp(self):
+ self.integration = Integration.objects.create(
+ integration_id = PaperlessMetaData.integration_id,
+ is_enabled = True,
+ )
+
+ def test_all_present_and_valid_returns_success(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com/'),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertTrue(result.is_valid)
+ self.assertEqual(result.status, HealthStatusType.HEALTHY)
+
+ def test_missing_api_url_returns_error(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertFalse(result.is_valid)
+ self.assertIn('API URL', result.error_message)
+
+ def test_missing_token_returns_error(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'https://paperless.example.com/'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertFalse(result.is_valid)
+ self.assertIn('API Token', result.error_message)
+
+ def test_empty_value_treated_as_missing(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL, ' '),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertFalse(result.is_valid)
+ self.assertIn('API URL', result.error_message)
+
+ def test_invalid_scheme_returns_error(self):
+ # File / FTP / scheme-less URLs are rejected; the client uses
+ # requests' HTTP-only session, so allowing them would surface
+ # as a cryptic runtime failure rather than a config-time one.
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL,
+ 'ftp://paperless.example.com/'),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertFalse(result.is_valid)
+ self.assertIn('http(s)', result.error_message)
+
+ def test_missing_netloc_returns_error(self):
+ attrs = [
+ _make_attr(self.integration, PlAttributeType.API_URL, 'https://'),
+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),
+ ]
+ result = validate_attributes(attrs)
+ self.assertFalse(result.is_valid)
+ self.assertIn('hostname', result.error_message)
diff --git a/src/hi/services/paperless/urls.py b/src/hi/services/paperless/urls.py
new file mode 100644
index 00000000..2a02cfda
--- /dev/null
+++ b/src/hi/services/paperless/urls.py
@@ -0,0 +1,20 @@
+"""Per-integration URL extension point.
+
+Mounts under ``services/paperless/`` via the framework's
+auto-discovery (see hi/integrations/urls.py). One route: a thumbnail
+proxy used by the ATTRIBUTE_REFERENCE picker so browser-rendered
+<img> tags can fetch paperless thumbnails through HI's session
+instead of requiring the upstream paperless API token.
+"""
+from django.urls import path
+
+from .views import ThumbnailProxyView
+
+
+urlpatterns = [
+ path(
+ 'documents/<int:document_id>/thumb/',
+ ThumbnailProxyView.as_view(),
+ name = 'paperless_thumbnail',
+ ),
+]
diff --git a/src/hi/services/paperless/views.py b/src/hi/services/paperless/views.py
new file mode 100644
index 00000000..881790a4
--- /dev/null
+++ b/src/hi/services/paperless/views.py
@@ -0,0 +1,62 @@
+"""Browser-facing paperless views.
+
+Only a thumbnail proxy lives here. Document source links go directly
+to paperless's web UI (the operator authenticates with paperless via
+their own session), but thumbnails are embedded inside the HI picker
+modal so the browser cannot supply the upstream API token. The proxy
+fetches server-side with the configured token and streams bytes back
+under HI's session — same approach HomeBox uses for its attachments.
+"""
+import logging
+
+from django.http import Http404, HttpResponse
+from django.views import View
+from requests import HTTPError
+
+from hi.integrations.exceptions import IntegrationAttributeError
+from hi.integrations.models import Integration
+
+from .pl_client import build_client
+
+logger = logging.getLogger(__name__)
+
+
+class ThumbnailProxyView( View ):
+
+ def get( self, request, document_id : int ):
+ try:
+ client = build_client()
+ except (Integration.DoesNotExist, IntegrationAttributeError):
+ raise Http404('Paperless integration not configured.')
+
+ try:
+ downloaded = client.download_thumbnail(
+ document_id = document_id,
+ )
+ except HTTPError as e:
+ status = getattr( e.response, 'status_code', None )
+ if status == 404:
+ raise Http404('Thumbnail not found.')
+ logger.warning(
+ f'Paperless thumb proxy HTTP {status} '
+ f'for document {document_id}: {e}'
+ )
+ return HttpResponse(
+ status = 502, content = 'Paperless upstream error.',
+ )
+ except Exception as e:
+ # Upstream connectivity / auth / parse failure. Surface
+ # as 502 so the browser distinguishes upstream trouble
+ # from a missing document.
+ logger.warning(
+ f'Paperless thumb proxy failed '
+ f'for document {document_id}: {e}'
+ )
+ return HttpResponse(
+ status = 502, content = 'Paperless upstream error.',
+ )
+
+ return HttpResponse(
+ content = downloaded['content'],
+ content_type = downloaded['mime_type'],
+ )
diff --git a/src/hi/services/zoneminder/zm_connector.py b/src/hi/services/zoneminder/zm_connector.py
index 719fb9a2..7faca9eb 100644
--- a/src/hi/services/zoneminder/zm_connector.py
+++ b/src/hi/services/zoneminder/zm_connector.py
@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)
class ZmConnector( IntegrationConnector, ZoneMinderMixin ):
- def get_integration_metadata(self):
+ def get_metadata(self):
return ZmMetaData
def get_monitor(self) -> ZoneMinderMonitor:
@@ -180,7 +180,7 @@ class ZmConnector( IntegrationConnector, ZoneMinderMixin ):
'Nodect': 'Nodect',
}
- def get_description(self, is_initial_connect: bool) -> Optional[str]:
+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:
if is_initial_connect:
return (
'Each monitor becomes a camera with motion and'
diff --git a/src/hi/settings/base.py b/src/hi/settings/base.py
index cb04fe71..076361d8 100644
--- a/src/hi/settings/base.py
+++ b/src/hi/settings/base.py
@@ -128,6 +128,7 @@ INSTALLED_APPS = [
'hi.services.hass',
'hi.services.homebox',
'hi.services.frigate',
+ 'hi.services.paperless',
'hi.apps.profiles',
]
@@ -292,6 +293,7 @@ PIPELINE = {
'js/video-timeline.js',
'js/attr.js',
'js/attr-dirty-tracking.js',
+ 'js/attr-picker.js',
),
'output_filename': 'js/js_hi_grid_header_content.js',
},
diff --git a/src/hi/settings/simulator.py b/src/hi/settings/simulator.py
index 28e9f984..c7eb2f1b 100644
--- a/src/hi/settings/simulator.py
+++ b/src/hi/settings/simulator.py
@@ -21,6 +21,7 @@ INSTALLED_APPS = [
'hi.simulator.services.frigate',
'hi.simulator.services.hass',
'hi.simulator.services.homebox',
+ 'hi.simulator.services.paperless',
'hi.simulator.services.zoneminder',
'hi.simulator.weather_sources.nws',
]
diff --git a/src/hi/simulator/services/paperless/__init__.py b/src/hi/simulator/services/paperless/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/src/hi/simulator/services/paperless/apps.py b/src/hi/simulator/services/paperless/apps.py
new file mode 100644
index 00000000..9745c6cf
--- /dev/null
+++ b/src/hi/simulator/services/paperless/apps.py
@@ -0,0 +1,7 @@
+from django.apps import AppConfig
+
+
+class PaperlessConfig( AppConfig ):
+ default_auto_field = 'django.db.models.BigAutoField'
+ name = 'hi.simulator.services.paperless'
+ simulator_module_label = 'Paperless-ngx'
diff --git a/src/hi/simulator/services/paperless/simulator.py b/src/hi/simulator/services/paperless/simulator.py
new file mode 100644
index 00000000..b910f48b
--- /dev/null
+++ b/src/hi/simulator/services/paperless/simulator.py
@@ -0,0 +1,127 @@
+"""Paperless-ngx simulator: parametric document-search responses.
+
+Unlike the entity-shaped simulators (HASS, HomeBox, ZoneMinder),
+paperless-ngx has no 1-to-1 mapping onto HI Entities — its
+contribution is the ATTRIBUTE_REFERENCE capability, which produces
+TEXT attributes on existing Entity / Location records, not new
+entities. So this simulator has no SimEntities and no persistent
+corpus. Instead it generates synthetic search results on the fly,
+shaped by a small set of operator-tunable knobs held on the
+singleton:
+
+ - result_count : how many documents each search returns (chosen
+ to exercise empty / single / multi-page picker
+ rendering paths)
+ - mime_mix : which mime-type mix populates result rows (PDF
+ only, images only, plain text only, or mixed)
+ - thumbnails : whether the simulator's
+ ``/api/documents/<id>/thumb/`` endpoint serves
+ a thumbnail (when off, the endpoint 404s and
+ the picker falls back to its icon)
+ - snippets : whether each result carries a content snippet
+ (exercises picker layout with / without it)
+ - latency_ms : artificial latency on the documents-list
+ endpoint, for surfacing any debounce or
+ loading-state issues in the picker
+
+Settings live in memory on the singleton (same lifecycle as
+HomeBox's ``_api_version``) — lost on server restart, survives
+SimProfile switches.
+"""
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List
+
+from hi.simulator.services.base_models import SimEntityDefinition
+from hi.simulator.services.service_simulator import ServiceSimulator
+
+
+class MimeMix( Enum ):
+ """Which mime types populate generated search results. Drives
+ the picker's thumbnail / fallback-icon path through different
+ code branches."""
+
+ PDF_ONLY = 'PDF only'
+ IMAGE_ONLY = 'Images only'
+ TEXT_ONLY = 'Plain text only'
+ MIXED = 'Mixed'
+
+ @classmethod
+ def default(cls) -> 'MimeMix':
+ return cls.MIXED
+
+ @property
+ def label(self) -> str:
+ return self.value
+
+
+# Discrete result counts the operator can pick from the extras form.
+# Chosen to exercise distinct picker rendering paths: empty,
+# single-result, small-multi, scroll-into-view, and large-page.
+RESULT_COUNT_CHOICES = ( 0, 1, 3, 10, 50 )
+
+
+@dataclass
+class PaperlessSimSettings:
+ """Knobs that parametrize every documents-search response. Held
+ on the PaperlessSimulator singleton; ephemeral."""
+
+ result_count : int = 3
+ mime_mix : MimeMix = MimeMix.MIXED
+ thumbnails : bool = True
+ snippets : bool = True
+ latency_ms : int = 0
+
+
+class PaperlessSimulator( ServiceSimulator ):
+ """Stub paperless-ngx server. Responds to any documents query
+ with a parametrically-generated result list shaped by the
+ operator-tuned ``PaperlessSimSettings``."""
+
+ def __init_singleton__( self ):
+ # Set BEFORE initialize() so a SimProfile switch does NOT
+ # reset operator-tuned settings (same lifecycle as
+ # ``_fault_mode`` on the base class).
+ self._settings = PaperlessSimSettings()
+ super().__init_singleton__()
+ return
+
+ @property
+ def id(self) -> str:
+ return 'paperless'
+
+ @property
+ def label(self) -> str:
+ return 'Paperless-ngx'
+
+ @property
+ def integration_urls(self) -> List[ tuple ]:
+ return [ ( 'Paperless API base', 'services/paperless/' ) ]
+
+ @property
+ def settings(self) -> PaperlessSimSettings:
+ return self._settings
+
+ def set_settings( self, settings : PaperlessSimSettings ) -> None:
+ self._settings = settings
+ return
+
+ @property
+ def sim_entity_definition_list(self) -> List[ SimEntityDefinition ]:
+ # Paperless contributes only via ATTRIBUTE_REFERENCE — no
+ # SimEntity rows ever, so the service page's entity-list
+ # area renders empty. The extras pane carries the operator
+ # UI.
+ return []
+
+ @property
+ def extras_template_name(self) -> str:
+ return 'paperless/panes/settings_form.html'
+
+ @property
+ def extras_context(self) -> Dict:
+ return {
+ 'settings': self._settings,
+ 'result_count_choices': RESULT_COUNT_CHOICES,
+ 'mime_mix_choices': list( MimeMix ),
+ }
diff --git a/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.html b/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.html
new file mode 100644
index 00000000..41055134
--- /dev/null
+++ b/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.html
@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>Paperless-ngx Simulator — Document #{{ document_id }}</title>
+ <style>
+ body { font-family: sans-serif; max-width: 40em; margin: 4em auto; color: #212529; }
+ .doc-id { font-size: 3em; color: #6c757d; }
+ .hint { color: #6c757d; margin-top: 2em; font-size: 0.9em; }
+ </style>
+</head>
+<body>
+ <div class="doc-id">Document #{{ document_id }}</div>
+ <p>This is the paperless-ngx simulator's stand-in for the per-document view. The real paperless web UI would show the document's metadata and content here.</p>
+ <p class="hint">Source URLs from the ATTRIBUTE_REFERENCE picker link to pages like this one; close the tab to return to the picker modal.</p>
+</body>
+</html>
diff --git a/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.html b/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.html
new file mode 100644
index 00000000..069e16d4
--- /dev/null
+++ b/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.html
@@ -0,0 +1,101 @@
+{% comment %}
+ Operator-tuned knobs for the paperless-ngx simulator's parametric
+ search response. Each control submits the form on change (no
+ submit button) so toggles take effect immediately, in the same
+ style as the HomeBox API-version pane.
+
+ Antinode: the form posts back to itself via data-async and the
+ view returns the same template fragment, so the pane swaps in
+ place with no page reload.
+
+ Context:
+ settings : PaperlessSimSettings
+ result_count_choices : tuple[int]
+ mime_mix_choices : list[MimeMix]
+{% endcomment %}
+<form id="hi-paperless-settings-form"
+ method="post"
+ action="{% url 'paperless_settings_set' %}"
+ class="mb-3"
+ data-async data-mode="replace">
+ {% csrf_token %}
+
+ <div class="form-row align-items-end">
+
+ <div class="form-group col-auto">
+ <label for="hi-paperless-result-count" class="small text-muted mb-1">
+ Result count
+ </label>
+ <select id="hi-paperless-result-count"
+ name="result_count"
+ class="form-control form-control-sm"
+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">
+ {% for choice in result_count_choices %}
+ <option value="{{ choice }}"
+ {% if choice == settings.result_count %}selected{% endif %}>
+ {{ choice }}
+ </option>
+ {% endfor %}
+ </select>
+ </div>
+
+ <div class="form-group col-auto">
+ <label for="hi-paperless-mime-mix" class="small text-muted mb-1">
+ Mime mix
+ </label>
+ <select id="hi-paperless-mime-mix"
+ name="mime_mix"
+ class="form-control form-control-sm"
+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">
+ {% for choice in mime_mix_choices %}
+ <option value="{{ choice.name }}"
+ {% if choice == settings.mime_mix %}selected{% endif %}>
+ {{ choice.label }}
+ </option>
+ {% endfor %}
+ </select>
+ </div>
+
+ <div class="form-group col-auto">
+ <label for="hi-paperless-latency" class="small text-muted mb-1">
+ Latency (ms)
+ </label>
+ <input type="number"
+ id="hi-paperless-latency"
+ name="latency_ms"
+ value="{{ settings.latency_ms }}"
+ min="0" max="10000" step="50"
+ class="form-control form-control-sm"
+ style="width: 8em;"
+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">
+ </div>
+
+ <div class="form-group col-auto mb-0">
+ <div class="form-check">
+ <input type="checkbox"
+ id="hi-paperless-thumbnails"
+ name="thumbnails"
+ value="on"
+ class="form-check-input"
+ {% if settings.thumbnails %}checked{% endif %}
+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">
+ <label class="form-check-label small" for="hi-paperless-thumbnails">
+ Thumbnails
+ </label>
+ </div>
+ <div class="form-check">
+ <input type="checkbox"
+ id="hi-paperless-snippets"
+ name="snippets"
+ value="on"
+ class="form-check-input"
+ {% if settings.snippets %}checked{% endif %}
+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">
+ <label class="form-check-label small" for="hi-paperless-snippets">
+ Snippets
+ </label>
+ </div>
+ </div>
+
+ </div>
+</form>
diff --git a/src/hi/simulator/services/paperless/urls.py b/src/hi/simulator/services/paperless/urls.py
new file mode 100644
index 00000000..c406c738
--- /dev/null
+++ b/src/hi/simulator/services/paperless/urls.py
@@ -0,0 +1,23 @@
+from django.urls import path
+
+from . import views
+
+
+urlpatterns = [
+
+ path( 'api/documents/',
+ views.DocumentsListView.as_view(),
+ name = 'paperless_documents_list' ),
+
+ path( 'api/documents/<int:document_id>/thumb/',
+ views.ThumbnailView.as_view(),
+ name = 'paperless_document_thumbnail' ),
+
+ path( 'documents/<int:document_id>/details/',
+ views.PreviewView.as_view(),
+ name = 'paperless_document_preview' ),
+
+ path( 'settings/set/',
+ views.SetSettingsView.as_view(),
+ name = 'paperless_settings_set' ),
+]
diff --git a/src/hi/simulator/services/paperless/views.py b/src/hi/simulator/services/paperless/views.py
new file mode 100644
index 00000000..464f913c
--- /dev/null
+++ b/src/hi/simulator/services/paperless/views.py
@@ -0,0 +1,283 @@
+"""Paperless-ngx simulator views.
+
+Three endpoint families:
+
+ - ``DocumentsListView`` — the parametric search endpoint. The
+ integration's referencer hits this for every search. Response
+ shape mirrors the real paperless ``GET /api/documents/?query=q``
+ (DRF pagination envelope + per-doc dict).
+
+ - ``ThumbnailView`` and ``PreviewView`` — mirror real paperless's
+ per-document endpoints so the picker's thumbnail / source-URL
+ handling can be exercised. ``ThumbnailView`` 404s when the
+ operator has thumbnails turned off so the picker's fallback-icon
+ path runs.
+
+ - ``SetSettingsView`` — POST target for the extras form. Mutates
+ the singleton's PaperlessSimSettings and re-renders the form
+ fragment (the form posts via antinode ``data-async`` so the
+ extras pane swaps in place).
+"""
+import hashlib
+import random
+import time
+from dataclasses import replace
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from django.core.exceptions import BadRequest
+from django.http import HttpResponse, JsonResponse
+from django.shortcuts import render
+from django.views import View
+
+from .simulator import (
+ MimeMix,
+ PaperlessSimSettings,
+ PaperlessSimulator,
+ RESULT_COUNT_CHOICES,
+)
+
+
+# ---- generator ---------------------------------------------------
+
+
+_MIME_PALETTE = {
+ MimeMix.PDF_ONLY: ( 'application/pdf', ),
+ MimeMix.IMAGE_ONLY: ( 'image/png', 'image/jpeg' ),
+ MimeMix.TEXT_ONLY: ( 'text/plain', ),
+ MimeMix.MIXED: ( 'application/pdf', 'image/png', 'text/plain' ),
+}
+
+_EXTENSION_BY_MIME = {
+ 'application/pdf' : 'pdf',
+ 'image/png' : 'png',
+ 'image/jpeg' : 'jpg',
+ 'text/plain' : 'txt',
+}
+
+# Filler phrases for synthetic snippets. The query is interleaved so
+# the picker's snippet rendering carries a visible breadcrumb of the
+# search input.
+_SNIPPET_FRAGMENTS = (
+ 'Annual maintenance record for {query} including replacement schedule.',
+ 'Warranty terms for {query}; refer to section 4 for exclusions.',
+ 'Installation manual for the {query} unit. Calibration steps follow.',
+ 'Service receipt covering parts and labor on the {query} repair.',
+ 'Compliance certificate issued for the {query} system this cycle.',
+)
+
+
+def _stable_document_id( query : str, index : int ) -> int:
+ """Map (query, index) to a stable, distinct, positive document
+ id. Different queries produce distinct ids; the same query
+ repeated yields the same ids. Real paperless uses unbounded
+ integer document ids, so a 7-hex-digit hash (~268M range) is a
+ safe stand-in."""
+ digest = hashlib.sha256( f'{query}\x00{index}'.encode() ).hexdigest()
+ return int( digest[:7], 16 )
+
+
+def _pick_mime( mix : MimeMix, index : int ) -> str:
+ """Deterministic per-index mime pick. Cycles through the palette
+ so a multi-result page rendered with MIXED visits each type."""
+ palette = _MIME_PALETTE[ mix ]
+ return palette[ index % len(palette) ]
+
+
+def _generate_results(
+ settings : PaperlessSimSettings, query : str,
+) -> List[dict]:
+ """Build ``settings.result_count`` synthetic paperless documents
+ for the given query. RNG is seeded from the query so a repeated
+ search returns the same set — predictable for the operator."""
+ rng = random.Random( query or '' )
+ now_iso = datetime.now(timezone.utc).isoformat()
+ documents = []
+ for index in range( settings.result_count ):
+ mime_type = _pick_mime( settings.mime_mix, index )
+ extension = _EXTENSION_BY_MIME[ mime_type ]
+ # Document id is derived from (query, index) so different
+ # queries produce distinct ids — the picker uses the resulting
+ # source URL as the per-result identity, and repeating ids
+ # across queries would make the picker think different docs
+ # were the same. (query, index) repeats stay stable, matching
+ # real paperless's "same document re-found in multiple
+ # searches" behavior.
+ document_id = _stable_document_id( query or '', index )
+ content = (
+ rng.choice( _SNIPPET_FRAGMENTS ).format( query = query or 'document' )
+ if settings.snippets else ''
+ )
+ # Titles use a human-readable index, not the hashed id, so
+ # operators see "Result 1, Result 2, ..." regardless of
+ # whatever id the URL ends up with.
+ title = f'{query or "document"} — Result {index + 1}'
+ documents.append({
+ 'id' : document_id,
+ 'correspondent' : None,
+ 'document_type' : None,
+ 'storage_path' : None,
+ 'title' : title,
+ 'content' : content,
+ 'tags' : [],
+ 'created' : now_iso,
+ 'modified' : now_iso,
+ 'added' : now_iso,
+ 'archive_serial_number': None,
+ 'original_file_name' : f'doc-{index + 1}.{extension}',
+ 'archived_file_name' : None,
+ 'mime_type' : mime_type,
+ 'is_shared_by_requester': False,
+ 'notes' : [],
+ 'custom_fields' : [],
+ })
+ return documents
+
+
+# ---- endpoints ---------------------------------------------------
+
+
+class DocumentsListView( View ):
+ """``GET /api/documents/?query=...`` — paginated documents
+ search, matching paperless-ngx's response envelope."""
+
+ def get( self, request, *args, **kwargs ):
+ simulator = PaperlessSimulator()
+ settings = simulator.settings
+ if settings.latency_ms > 0:
+ time.sleep( settings.latency_ms / 1000.0 )
+ query = request.GET.get( 'query', '' ).strip()
+ results = _generate_results( settings, query )
+ # Mirrors the DRF pagination envelope the real paperless
+ # API uses — single page, no next/previous.
+ return JsonResponse({
+ 'count' : len( results ),
+ 'next' : None,
+ 'previous' : None,
+ 'all' : [ r['id'] for r in results ],
+ 'results' : results,
+ })
+
+
+def _thumbnail_svg( document_id : int ) -> bytes:
+ """Tiny SVG placeholder. Avoids shipping a binary thumbnail just
+ so the picker can render *something* in the thumbnail slot."""
+ return (
+ f'<svg xmlns="http://www.w3.org/2000/svg" width="120" height="160" '
+ f'viewBox="0 0 120 160">'
+ f'<rect width="120" height="160" fill="#e9ecef" stroke="#adb5bd"/>'
+ f'<text x="60" y="86" text-anchor="middle" font-family="sans-serif" '
+ f'font-size="20" fill="#495057">#{document_id}</text>'
+ f'</svg>'
+ ).encode('utf-8')
+
+
+class ThumbnailView( View ):
+ """``GET /api/documents/<id>/thumb/`` — serves an SVG placeholder
+ when thumbnails are enabled; 404s otherwise so the picker's
+ fallback-icon path can be exercised."""
+
+ def get( self, request, *args, **kwargs ):
+ simulator = PaperlessSimulator()
+ if not simulator.settings.thumbnails:
+ return HttpResponse( status = 404 )
+ try:
+ document_id = int( kwargs.get( 'document_id' ) )
+ except (TypeError, ValueError):
+ return HttpResponse( status = 404 )
+ return HttpResponse(
+ _thumbnail_svg( document_id ),
+ content_type = 'image/svg+xml',
+ )
+
+
+class PreviewView( View ):
+ """``GET /documents/<id>/details/`` — minimal preview page
+ representing the per-document view in paperless's web UI. The
+ picker links here as the result's source URL."""
+
+ TEMPLATE_NAME = 'paperless/pages/document_preview.html'
+
+ def get( self, request, *args, **kwargs ):
+ try:
+ document_id = int( kwargs.get( 'document_id' ) )
+ except (TypeError, ValueError):
+ return HttpResponse( status = 404 )
+ return render(
+ request,
+ self.TEMPLATE_NAME,
+ { 'document_id': document_id },
+ )
+
+
+class SetSettingsView( View ):
+ """POST target for the extras form. Validates each field,
+ updates the singleton, and re-renders the settings fragment."""
+
+ TEMPLATE_NAME = 'paperless/panes/settings_form.html'
+
+ def post( self, request, *args, **kwargs ):
+ simulator = PaperlessSimulator()
+ current = simulator.settings
+ new_settings = replace(
+ current,
+ result_count = self._parse_result_count(
+ request.POST.get( 'result_count' ), current.result_count,
+ ),
+ mime_mix = self._parse_mime_mix(
+ request.POST.get( 'mime_mix' ),
+ ),
+ thumbnails = self._parse_bool(
+ request.POST.get( 'thumbnails' ),
+ ),
+ snippets = self._parse_bool(
+ request.POST.get( 'snippets' ),
+ ),
+ latency_ms = self._parse_latency_ms(
+ request.POST.get( 'latency_ms' ), current.latency_ms,
+ ),
+ )
+ simulator.set_settings( new_settings )
+ return render(
+ request,
+ self.TEMPLATE_NAME,
+ {
+ 'settings' : new_settings,
+ 'result_count_choices' : RESULT_COUNT_CHOICES,
+ 'mime_mix_choices' : list( MimeMix ),
+ },
+ )
+
+ @staticmethod
+ def _parse_result_count( raw : Optional[str], fallback : int ) -> int:
+ try:
+ value = int( raw )
+ except (TypeError, ValueError):
+ return fallback
+ if value not in RESULT_COUNT_CHOICES:
+ raise BadRequest( f'Invalid result_count: {raw!r}' )
+ return value
+
+ @staticmethod
+ def _parse_mime_mix( raw : Optional[str] ) -> MimeMix:
+ try:
+ return MimeMix[ raw ]
+ except (KeyError, TypeError):
+ raise BadRequest( f'Invalid mime_mix: {raw!r}' )
+
+ @staticmethod
+ def _parse_bool( raw : Optional[str] ) -> bool:
+ # An unchecked checkbox is absent from the POST body, so the
+ # mere presence of the field name (with any truthy value) is
+ # the signal.
+ return bool( raw )
+
+ @staticmethod
+ def _parse_latency_ms( raw : Optional[str], fallback : int ) -> int:
+ try:
+ value = int( raw )
+ except (TypeError, ValueError):
+ return fallback
+ if value < 0 or value > 10000:
+ raise BadRequest( f'latency_ms out of range: {raw!r}' )
+ return value
diff --git a/src/hi/simulator/services/templates/services/pages/service.html b/src/hi/simulator/services/templates/services/pages/service.html
index 5b33d8b6..1231098f 100644
--- a/src/hi/simulator/services/templates/services/pages/service.html
+++ b/src/hi/simulator/services/templates/services/pages/service.html
@@ -3,7 +3,19 @@
{% block main_attrs %} data-states-url="{% url 'simulator_api_states' %}"{% endblock %}
{% block tab_body %}
+{% comment %}
+Simulators with no SimEntity definitions are ephemeral — they can't
+have entities, so profile CRUD (which only varies entity persistence),
+the ADD ENTITY menu (which would be empty), and the entity list (plus
+its "no entities defined" empty-state) are all gated on
+``sim_entity_definition_list``. Connect-shaped simulators with zero
+*current* entities still have definitions, so the {% empty %} alert
+still fires for them — empty is a valid Connect test scenario.
+
+Integration URLs and the fault-mode form remain unconditional.
+{% endcomment %}
<div class="d-flex align-items-center justify-content-between mb-2">
+ {% if simulator.sim_entity_definition_list %}
{% include "profile/panes/profile_selector.html" with module=module profile_list=profile_list current_profile=current_profile %}
<div class="dropdown">
@@ -26,6 +38,7 @@
{% endfor %}
</div>
</div>
+ {% endif %}
{% if simulator.integration_urls %}
<div class="text-muted small mx-3 flex-grow-1 text-center">
@@ -45,9 +58,11 @@
{% include simulator.extras_template_name %}
{% endif %}
+{% if simulator.sim_entity_definition_list %}
{% for sim_entity in simulator.sim_entities %}
{% include "services/panes/sim_entity.html" with simulator=simulator sim_entity=sim_entity %}
{% empty %}
<div class="alert alert-info">No {{ simulator.label }} simulator entities defined.</div>
{% endfor %}
+{% endif %}
{% endblock %}
diff --git a/src/hi/static/css/attribute.css b/src/hi/static/css/attribute.css
index 08823763..452f0a11 100644
--- a/src/hi/static/css/attribute.css
+++ b/src/hi/static/css/attribute.css
@@ -64,13 +64,22 @@
margin-left: auto; /* Push to right */
}
-.attr-v2-action-buttons button {
+.attr-v2-action-buttons button,
+.attr-v2-action-buttons a.btn {
min-height: 44px; /* Touch-friendly minimum */
padding: 0.375rem 0.75rem;
font-size: 0.875rem;
border-radius: 0.25rem;
}
+/* <a class="btn"> doesn't vertically center its content the way
+ <button> does; force-center so anchor-styled buttons line up
+ with their button-element siblings in the action bar. */
+.attr-v2-action-buttons a.btn {
+ display: inline-flex;
+ align-items: center;
+}
+
.attr-v2-status-message {
font-size: 0.875rem;
color: var(--secondary-text-color);
@@ -643,6 +652,7 @@
/* Button Transitions */
.attr-v2-action-buttons button,
+.attr-v2-action-buttons a.btn,
.attr-v2-file-actions button,
.attr-v2-attribute-actions button,
.attr-v2-reorder-controls button,
@@ -651,6 +661,7 @@
}
.attr-v2-action-buttons button:hover,
+.attr-v2-action-buttons a.btn:hover,
.attr-v2-file-actions button:hover,
.attr-v2-attribute-actions button:hover,
.attr-v2-reorder-controls button:hover:not(:disabled),
@@ -676,6 +687,7 @@
/* Enhanced focus states for buttons and interactive elements */
.attr-v2-action-buttons button:focus,
+.attr-v2-action-buttons a.btn:focus,
.attr-v2-file-actions button:focus,
.attr-v2-attribute-actions button:focus,
.attr-v2-reorder-controls button:focus,
@@ -883,6 +895,7 @@
.attr-v2-attribute-card:hover,
.attr-v2-file-thumbnail:hover,
.attr-v2-action-buttons button:hover,
+ .attr-v2-action-buttons a.btn:hover,
.attr-v2-file-actions button:hover,
.attr-v2-attribute-actions button:hover {
transform: none;
@@ -906,6 +919,7 @@
.attr-v2-file-card,
.attr-v2-attribute-card,
.attr-v2-action-buttons button,
+ .attr-v2-action-buttons a.btn,
.attr-v2-file-actions button,
.attr-v2-attribute-actions button,
.attr-v2-reorder-controls button,
@@ -984,7 +998,8 @@
vertical-align: middle;
}
-.attr-v2-action-buttons button .hi-icon-left {
+.attr-v2-action-buttons button .hi-icon-left,
+.attr-v2-action-buttons a.btn .hi-icon-left {
margin-right: 0.5rem;
}
}
@@ -1742,3 +1757,70 @@
padding-left: 0;
}
+/* ====================================================================== */
+/* ATTRIBUTE_REFERENCE picker */
+/* ====================================================================== */
+
+/* Bootstrap's modal-dialog-scrollable shrinks the flex children of
+ modal-content to fit the constrained height. The default Bootstrap
+ markup has .modal-header / .modal-footer with flex-shrink:0 so only
+ .modal-body shrinks; this project uses .modal-title in place of
+ .modal-header, so we re-establish the contract here for any modal
+ that opts into scrollable behavior. */
+.modal-dialog-scrollable .modal-title,
+.modal-dialog-scrollable .modal-footer {
+ flex-shrink: 0;
+}
+
+/* The picker modal opts into Bootstrap's modal-dialog-scrollable so the
+ modal-body is the scroll container while the header and footer stay
+ anchored. Pin the search controls to the top edge of the body so the
+ operator can refine their query at any scroll position without
+ scrolling back up to find the search row. */
+.hi-attr-picker-search-form {
+ position: sticky;
+ top: 0;
+ z-index: 1;
+ background-color: var(--background-color, #fff);
+ padding-top: 0.5rem;
+ padding-bottom: 0.5rem;
+}
+
+/* Zero the modal-body's top padding so the sticky search form is flush
+ against the title — otherwise modal-body's default padding-top shows
+ scrolling content through the gap above the sticky element. The
+ search form supplies its own padding-top for breathing room. */
+.hi-attr-picker .modal-body {
+ padding-top: 0;
+}
+
+/* Source banner — always rendered. With one source the button is
+ disabled (no caret, no hover affordance) so the visual matches
+ the multi-source case structurally but doesn't invite a click
+ that does nothing useful. The button face shows the source's
+ logo on a light background; native logos meant for white render
+ correctly here. */
+.hi-attr-picker-source-banner {
+ background-color: #fff;
+ border: 1px solid var(--line-color, #dee2e6);
+ padding: 0.5rem 0.75rem;
+}
+.hi-attr-picker-source-banner-logo {
+ max-height: 24px;
+ width: auto;
+}
+.hi-attr-picker-source-banner-label {
+ font-weight: 500;
+}
+.hi-attr-picker-source-banner-single .dropdown-toggle::after {
+ display: none;
+}
+.hi-attr-picker-source-banner-single .dropdown-toggle:disabled {
+ opacity: 1;
+ cursor: default;
+}
+.hi-attr-picker-source-option img {
+ max-height: 20px;
+ width: auto;
+}
+
diff --git a/src/hi/static/img/integrations/paperless.png b/src/hi/static/img/integrations/paperless.png
new file mode 100644
index 00000000..718d2d86
Binary files /dev/null and b/src/hi/static/img/integrations/paperless.png differ
diff --git a/src/hi/static/js/attr-picker.js b/src/hi/static/js/attr-picker.js
new file mode 100644
index 00000000..d1eb8fcc
--- /dev/null
+++ b/src/hi/static/js/attr-picker.js
@@ -0,0 +1,292 @@
+/*
+ * Home Information - Attribute-reference picker UI state
+ *
+ * Multi-select picker for ATTRIBUTE_REFERENCE integrations (e.g.,
+ * paperless-ngx). The picker lets the operator search an upstream
+ * source and accumulate a set of references (title + URL) across
+ * multiple searches, then commit the whole set as TEXT attributes
+ * in one final submit.
+ *
+ * Responsibilities owned by this module:
+ *
+ * - Hold the current attribute-selection set in JS state, keyed
+ * by picker-DOM-node so multiple modals would not collide.
+ * - Render the chip row from that state. Chips are the only HTML
+ * this module generates; everything else is server-rendered.
+ * - Update the Add button's label and enabled state to reflect
+ * the current selection count.
+ * - Drive an async Search request: POST query parameters, receive
+ * result-cards HTML, swap into the results container. After
+ * swap, re-apply checkbox state to any newly-visible result
+ * whose URL is already in the selection set.
+ * - On Add submit: serialize the selection set into the hidden
+ * ``selections_json`` input and POST through antinode's public
+ * API (``AN.hideModalIfNeeded`` + ``AN.post``) so the modal
+ * close and the ``{refresh: true}`` response flow through the
+ * framework.
+ *
+ * Handlers are delegated at the document level so dynamically-
+ * inserted modal content (the antinode-loaded picker body) wires
+ * up automatically — no per-modal init step. State is lazily
+ * created per picker DOM node and garbage-collected when the
+ * modal is removed.
+ *
+ * DOM classes, data-attribute names, and wire-format field names
+ * all come from ``Hi.ATTR_PICKER_*`` in ``main.js``, mirrored
+ * server-side in ``hi.constants.DIVID``.
+ */
+(function() {
+ 'use strict';
+
+ const EventNs = '.attr-picker';
+
+ // Per-picker selection state, keyed by the picker-root DOM node
+ // so multiple open modals would not collide. State is lazily
+ // created on first access and garbage-collected when the modal
+ // element is removed.
+ const _stateByPicker = new WeakMap();
+
+ function _state(pickerRoot) {
+ let state = _stateByPicker.get(pickerRoot);
+ if (!state) {
+ state = { attrSelections: [] };
+ _stateByPicker.set(pickerRoot, state);
+ }
+ return state;
+ }
+
+ function _classSelector(className) {
+ return '.' + className;
+ }
+
+ function _hasSelection(state, sourceUrl) {
+ const key = Hi.ATTR_PICKER_SELECTION_URL_KEY;
+ return state.attrSelections.some(s => s[key] === sourceUrl);
+ }
+
+ function _addSelection(state, title, sourceUrl) {
+ if (_hasSelection(state, sourceUrl)) return;
+ const record = {};
+ record[Hi.ATTR_PICKER_SELECTION_TITLE_KEY] = title;
+ record[Hi.ATTR_PICKER_SELECTION_URL_KEY] = sourceUrl;
+ state.attrSelections.push(record);
+ }
+
+ function _removeSelection(state, sourceUrl) {
+ const key = Hi.ATTR_PICKER_SELECTION_URL_KEY;
+ state.attrSelections = state.attrSelections.filter(
+ s => s[key] !== sourceUrl
+ );
+ }
+
+ function _renderChips($pickerRoot, state) {
+ const $chipsContainer = $pickerRoot.find(
+ _classSelector(Hi.ATTR_PICKER_CHIPS_CLASS)
+ );
+ const $emptyHint = $pickerRoot.find(
+ _classSelector(Hi.ATTR_PICKER_CHIPS_EMPTY_CLASS)
+ );
+ $chipsContainer.empty();
+ if (state.attrSelections.length === 0) {
+ $emptyHint.removeClass('d-none');
+ return;
+ }
+ $emptyHint.addClass('d-none');
+ const titleKey = Hi.ATTR_PICKER_SELECTION_TITLE_KEY;
+ const urlKey = Hi.ATTR_PICKER_SELECTION_URL_KEY;
+ state.attrSelections.forEach(function(sel) {
+ const $chip = $('<span>')
+ .addClass('badge badge-secondary mr-2 mb-2 d-inline-flex align-items-center');
+ $('<span>')
+ .addClass('mr-1 text-truncate')
+ .css('max-width', '220px')
+ .attr('title', sel[titleKey])
+ .text(sel[titleKey])
+ .appendTo($chip);
+ $('<button type="button">')
+ .addClass('btn btn-link btn-sm p-0 text-white ml-1')
+ .addClass(Hi.ATTR_PICKER_CHIP_REMOVE_CLASS)
+ .attr('title', 'Remove from selection')
+ .attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR, sel[urlKey])
+ .text('×') // ×
+ .appendTo($chip);
+ $chipsContainer.append($chip);
+ });
+ }
+
+ function _renderAttachButton($pickerRoot, state) {
+ const count = state.attrSelections.length;
+ const $btn = $pickerRoot.find(
+ _classSelector(Hi.ATTR_PICKER_ATTACH_BTN_CLASS)
+ );
+ const noun = count === 1 ? 'Link' : 'Links';
+ const $label = $btn.find(
+ _classSelector(Hi.ATTR_PICKER_ATTACH_LABEL_CLASS)
+ );
+ const text = 'Add ' + count + ' ' + noun;
+ if ($label.length) {
+ $label.text(text);
+ } else {
+ $btn.text(text);
+ }
+ $btn.prop('disabled', count === 0);
+ }
+
+ function _renderAll($pickerRoot, state) {
+ _renderChips($pickerRoot, state);
+ _renderAttachButton($pickerRoot, state);
+ }
+
+ function _syncCheckboxesToState($pickerRoot, state) {
+ $pickerRoot.find(
+ _classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS)
+ ).each(function() {
+ const $cb = $(this);
+ const sourceUrl = $cb.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);
+ if (sourceUrl == null) return;
+ $cb.prop('checked', _hasSelection(state, sourceUrl));
+ });
+ }
+
+ // ---- Delegated handlers ------------------------------------
+
+ $(document).on(
+ 'change' + EventNs,
+ _classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS),
+ function() {
+ const $cb = $(this);
+ const $pickerRoot = $cb.closest(
+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)
+ );
+ if ($pickerRoot.length === 0) return;
+ const state = _state($pickerRoot[0]);
+ const title = $cb.attr(Hi.ATTR_PICKER_TITLE_ATTR);
+ const sourceUrl = $cb.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);
+ if (sourceUrl == null) return;
+ if ($cb.is(':checked')) {
+ _addSelection(state, title, sourceUrl);
+ } else {
+ _removeSelection(state, sourceUrl);
+ }
+ _renderAll($pickerRoot, state);
+ }
+ );
+
+ $(document).on(
+ 'click' + EventNs,
+ _classSelector(Hi.ATTR_PICKER_CHIP_REMOVE_CLASS),
+ function() {
+ const $btn = $(this);
+ const $pickerRoot = $btn.closest(
+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)
+ );
+ if ($pickerRoot.length === 0) return;
+ const sourceUrl = $btn.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);
+ if (sourceUrl == null) return;
+ const state = _state($pickerRoot[0]);
+ _removeSelection(state, sourceUrl);
+ // Uncheck any visible result card whose URL matches.
+ $pickerRoot
+ .find(_classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS))
+ .filter(function() {
+ return $(this).attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR) === sourceUrl;
+ })
+ .prop('checked', false);
+ _renderAll($pickerRoot, state);
+ }
+ );
+
+ $(document).on(
+ 'submit' + EventNs,
+ _classSelector(Hi.ATTR_PICKER_SEARCH_FORM_CLASS),
+ function(e) {
+ e.preventDefault();
+ const $form = $(this);
+ const $pickerRoot = $form.closest(
+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)
+ );
+ if ($pickerRoot.length === 0) return;
+ const searchUrl = $form.attr(Hi.ATTR_PICKER_SEARCH_URL_ATTR);
+ $.ajax({
+ url: searchUrl,
+ method: 'POST',
+ data: $form.serialize(),
+ headers: { 'X-Requested-With': 'XMLHttpRequest' }
+ }).done(function(html) {
+ $pickerRoot.find(
+ _classSelector(Hi.ATTR_PICKER_RESULTS_CLASS)
+ ).html(html);
+ _syncCheckboxesToState($pickerRoot, _state($pickerRoot[0]));
+ });
+ }
+ );
+
+ $(document).on(
+ 'submit' + EventNs,
+ _classSelector(Hi.ATTR_PICKER_ATTACH_FORM_CLASS),
+ function(e) {
+ // Own the submit lifecycle so the in-memory selection set
+ // is populated into the hidden input BEFORE the form is
+ // read. The form deliberately omits ``data-async`` so
+ // antinode's body-level submit handler doesn't race us —
+ // we instead route through antinode's public API (modal
+ // close + POST) so the ``{refresh: true}`` response and
+ // the modal cleanup still flow through the framework.
+ e.preventDefault();
+ const $form = $(this);
+ const $pickerRoot = $form.closest(
+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)
+ );
+ if ($pickerRoot.length === 0) return;
+ const state = _state($pickerRoot[0]);
+ const fieldName = Hi.ATTR_PICKER_SELECTIONS_JSON_FIELD;
+ $form.find('input[name="' + fieldName + '"]')
+ .val(JSON.stringify(state.attrSelections));
+ if (!window.AN) {
+ // Defensive: antinode is part of the base bundle, but
+ // if it ever fails to load we fall back to a plain
+ // submit so the operator's click is not lost.
+ $form[0].submit();
+ return;
+ }
+ window.AN.hideModalIfNeeded($form[0]);
+ window.AN.post($form.attr('action'), $form.serialize());
+ }
+ );
+
+ $(document).on(
+ 'click' + EventNs,
+ _classSelector(Hi.ATTR_PICKER_SOURCE_OPTION_CLASS),
+ function(e) {
+ // Switch the active source: update the banner face, set
+ // the hidden integration_id input, and re-issue the
+ // current search against the new source. Selections
+ // already in state stay put — they're keyed by URL, not
+ // by source.
+ e.preventDefault();
+ const $option = $(this);
+ const $pickerRoot = $option.closest(
+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)
+ );
+ if ($pickerRoot.length === 0) return;
+ const sourceId = $option.attr(Hi.ATTR_PICKER_SOURCE_ID_ATTR);
+ const sourceLogo = $option.attr(Hi.ATTR_PICKER_SOURCE_LOGO_ATTR);
+ const sourceLabel = $option.attr(Hi.ATTR_PICKER_SOURCE_LABEL_ATTR);
+ if (sourceId == null) return;
+ $pickerRoot
+ .find(_classSelector(Hi.ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS))
+ .attr('src', sourceLogo);
+ $pickerRoot
+ .find(_classSelector(Hi.ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS))
+ .text(sourceLabel);
+ const fieldName = Hi.ATTR_PICKER_INTEGRATION_ID_FIELD;
+ $pickerRoot
+ .find('input[name="' + fieldName + '"]')
+ .val(sourceId);
+ $pickerRoot
+ .find(_classSelector(Hi.ATTR_PICKER_SEARCH_FORM_CLASS))
+ .trigger('submit');
+ }
+ );
+
+})();
diff --git a/src/hi/static/js/attr.js b/src/hi/static/js/attr.js
index a80ea488..28935999 100644
--- a/src/hi/static/js/attr.js
+++ b/src/hi/static/js/attr.js
@@ -172,7 +172,8 @@
_updateOrderIndexes($container);
}
- const formData = new FormData($form[0]);
+ const submitter = options.submitter || null;
+ const formData = new FormData($form[0], submitter);
const url = $form.attr('action');
const method = $form.attr('method') || 'POST';
@@ -649,8 +650,13 @@
// Add custom Ajax submission handler
$form.on(`submit.${ATTR_V2_INTERNAL.AJAX_EVENT_NAMESPACE}`, function(e) {
e.preventDefault();
-
- _ajax.submitFormWithAjax(form);
+
+ // Pass the submitter so the clicked button's name/value
+ // is included in FormData — matches native browser
+ // behavior for multi-submit-button forms (e.g., a form
+ // with both SAVE and DISABLE buttons).
+ const submitter = (e.originalEvent && e.originalEvent.submitter) || null;
+ _ajax.submitFormWithAjax(form, { submitter });
});
});
diff --git a/src/hi/static/js/main.js b/src/hi/static/js/main.js
index cf8c6870..5588e643 100644
--- a/src/hi/static/js/main.js
+++ b/src/hi/static/js/main.js
@@ -160,7 +160,40 @@
ENTITY_PICKER_STATUS_UNUSED: 'unused',
// Entity Picker - Filter values
- ENTITY_PICKER_FILTER_ALL: 'all'
+ ENTITY_PICKER_FILTER_ALL: 'all',
+
+ // ATTRIBUTE_REFERENCE picker — DOM classes / data attributes
+ // / wire-format field names shared with the server. Mirror
+ // of the ``ATTR_PICKER_*`` entries in
+ // ``src/hi/constants.py:DIVID``.
+ ATTR_PICKER_ROOT_CLASS: 'hi-attr-picker',
+ ATTR_PICKER_CHIPS_CLASS: 'hi-attr-picker-chips',
+ ATTR_PICKER_CHIPS_EMPTY_CLASS: 'hi-attr-picker-chips-empty',
+ ATTR_PICKER_CHIP_REMOVE_CLASS: 'hi-attr-picker-chip-remove',
+ ATTR_PICKER_RESULTS_CLASS: 'hi-attr-picker-results',
+ ATTR_PICKER_SEARCH_FORM_CLASS: 'hi-attr-picker-search-form',
+ ATTR_PICKER_ATTACH_FORM_CLASS: 'hi-attr-picker-attach-form',
+ ATTR_PICKER_ATTACH_BTN_CLASS: 'hi-attr-picker-attach-btn',
+ ATTR_PICKER_ATTACH_LABEL_CLASS: 'hi-attr-picker-attach-label',
+ ATTR_PICKER_RESULT_CHECKBOX_CLASS: 'hi-attr-picker-result-checkbox',
+ ATTR_PICKER_SEARCH_URL_ATTR: 'data-attr-picker-search-url',
+ ATTR_PICKER_TITLE_ATTR: 'data-attr-picker-title',
+ ATTR_PICKER_SOURCE_URL_ATTR: 'data-attr-picker-source-url',
+ ATTR_PICKER_QUERY_FIELD: 'query',
+ ATTR_PICKER_LIMIT_FIELD: 'limit',
+ ATTR_PICKER_ITEM_TYPE_FIELD: 'item_type',
+ ATTR_PICKER_ITEM_ID_FIELD: 'item_id',
+ ATTR_PICKER_INTEGRATION_ID_FIELD: 'integration_id',
+ ATTR_PICKER_SELECTIONS_JSON_FIELD: 'selections_json',
+ ATTR_PICKER_SELECTION_TITLE_KEY: 'title',
+ ATTR_PICKER_SELECTION_URL_KEY: 'source_url',
+ ATTR_PICKER_SOURCE_BANNER_CLASS: 'hi-attr-picker-source-banner',
+ ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS: 'hi-attr-picker-source-banner-logo',
+ ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS: 'hi-attr-picker-source-banner-label',
+ ATTR_PICKER_SOURCE_OPTION_CLASS: 'hi-attr-picker-source-option',
+ ATTR_PICKER_SOURCE_ID_ATTR: 'data-attr-picker-source-id',
+ ATTR_PICKER_SOURCE_LOGO_ATTR: 'data-attr-picker-source-logo',
+ ATTR_PICKER_SOURCE_LABEL_ATTR: 'data-attr-picker-source-label'
};
window.Hi = Hi;
diff --git a/src/hi/templates/icons/link.html b/src/hi/templates/icons/link.html
new file mode 100644
index 00000000..6e7feaf7
--- /dev/null
+++ b/src/hi/templates/icons/link.html
@@ -0,0 +1,3 @@
+<svg class="{{ class_attr }}" viewBox="0 0 24 24" fill="currentColor" {{ accessibility_attrs }}>
+ <path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/>
+</svg>