Skip to main content
Version: 1.3.0

Auto-attributes (Phase 1)

Overview​

Structured metadata for documents deposited by automatic services (Tower v2, n8n, future agents), separate from manual user attributes. Powers Smart Lists (Listes Automatiques) in IP Magic Box and platform ops tooling.

Canonical repo guide: neo-backend/docs/auto-attributes.md.

How it works​

  • Ingest: POST /documents requires Bcyip-Agent. The value must match apitokens.agent. bcyip:agent is that header; bcyip:agent-version is Bcyip-Version when non-empty. fileId is optional only for iptower; every other agent must link a RemoteFile.
  • Manual deposit unchanged: IP Magic Box upload stays on legacy POST /files/upload. Creating the neo document still needs the agent header and, except for Tower, a fileId.
  • Folder v0: folder=tower matches bcyip:agent against agent_codes rows with automatic: true. folder=ipb is the inverse. The bcyip-tower tag is not used. Existing agents are not backfilled.
  • Custom folders: companies.folders[].type = manual | auto; auto folders filter by targetAttributeCodes or targetAutoAttributes.
  • Allowed codes: reads use allowedAttributeRefs only. Create and update still accept allowedCodes and write refs.
  • Platform ops: /platform/* routes use X-Platform-Admin-Token (PLATFORM_ADMIN_TOKEN env).

Key files​

  • src/domains/document/document.service.ts — ingest validation, idempotence, folder resolver
  • src/domains/document/templates/document-folder-v0.ts — automatic vs manual folder match
  • src/domains/platform/agents/ — agent CRUD, automatic, allowedAttributeRefs
  • src/domains/platform/auto-attribute-codes/ — global catalogue + LOV
  • src/core/auth/auth.service.ts — apiTokenAgent from apitokens.agent

Technical decisions​

  • Separate arrays: autoAttributes[] vs attributes[] — manual workflows untouched.
  • No seed scripts: catalogue and agents bootstrapped via platform API.
  • fileId: optional only for iptower. Other agents must link a RemoteFile uploaded by the legacy API.
  • automatic flag: folder membership is catalogue-driven. No backfill of existing agent rows.

Known issues​

  • Tower tokens need apitokens.agent: 'iptower' and agent_codes.automatic: true or deposits stay in the manual folder.
  • IP Magic Box tokens need apitokens.agent set to ipmagicbox before POST /documents, and a fileId.

Next steps​

  • GET /platform/auto-attribute-codes/:code/observed-values for ops label editor
  • Phase 2: folder write rules, migration tooling