Skip to main content
Version: 1.1.0

Auto-attributes (Phase 1 — metadata-only)

Version: 1.1.0 Date: 2026-07-15

Goal: Let automatic services (Tower v2, n8n, future agents) deposit structured metadata separate from manual user attributes, with smart lists ("Listes Automatiques") filtering documents dynamically by attribute codes in IP Magic Box.

Solution: New documents.autoAttributes[] field, folder type: auto, platform admin API for global catalogue and ingestion agents, universal POST /documents ingest with strict agent validation. Canonical guide: neo-backend/docs/auto-attributes.md.

Features:

  • POST /documents — manual (attributes) and auto (autoAttributes) metadata; optional fileId for legacy upload + neo document two-step flow (n8n/Airtable)
  • GET /documents — top-level autoAttributes counts + per-document values; X-Mock: true for front-first development
  • Platform API — /platform/agents, /platform/auto-attribute-codes, /platform/folder-templates, /platform/companies/:id/* via X-Platform-Admin-Token
  • apitokens.agent read as apiTokenAgent for Bcyip-Agent header validation on ingest
  • Technical codes bcyip:agent and bcyip:agent-version auto-injected (not configurable on agents)
  • Idempotent ingest: merge autoAttributes by code on duplicate hash + jobRef
  • Tower hall (folder=tower): union Tower v1 tags + any agent deposit (bcyip:agent in autoAttributes, any value)
  • Catalogue LOV with optional valueLabel on read paths (additive for IP Magic Box)

Schema changes:

  • documents.autoAttributes[] — {code, value}[]
  • companies.folders[].type — 'manual' | 'auto'
  • companies.folders[].targetAttributeCodes[], targetAutoAttributes[], displayedCodes[]
  • attributes.code? on global catalogue entries
  • agent_codes collection — agentName, allowedAttributeRefs[]
  • auto_folder_templates — global smart-list templates
  • users.agents runtime map updated on agent deposits

Implementation Details:

  • buildDocumentFolderFilter() — manual ObjectId folders vs auto code filters vs Tower union
  • filtersAutoAttributesTemplate — aggregation counts for filter bar
  • Ingestion normalizes legacy bcyip-agent / unprefixed codes during transition
  • No seed scripts — catalogue and agents managed via platform HTTP API

Files Modified:

  • src/domains/document/document.service.ts - Ingest validation, idempotence, folder resolver
  • src/domains/document/document.controller.ts - POST /documents, mock header, OpenAPI
  • src/domains/document/templates/documents.ts - Folder filters, Tower hall
  • src/domains/document/templates/filters_auto_attributes.ts - Filter aggregation (new)
  • src/domains/platform/agents/ - Agent CRUD (new)
  • src/domains/platform/auto-attribute-codes/ - Global catalogue (new)
  • src/domains/platform/folder-templates/ - Smart-list templates (new)
  • src/domains/platform/companies/platform-companies.controller.ts - Cross-company ops (new)
  • src/core/auth/auth.service.ts - apiTokenAgent, recordUserAgentRuntime
  • src/shared/middleware/agent.middleware.ts - Agent telemetry on authenticated requests
  • docs/auto-attributes.md - Canonical reference

Prod setup:

  • Set PLATFORM_ADMIN_TOKEN on Clever Cloud
  • Bootstrap catalogue + iptower agent via /platform/*
  • Tag Tower API tokens with apitokens.agent: 'iptower' (Retool) — not required for IP Magic Box manual deposit

Release fragment: feat-auto-attributes