nextcloud / nextcloud/metavox

Expose per-folder default values via OCS API

Open
#82 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
PHP
Stars
25
Forks
6
PR merge metrics
No merged PRs in 30d

Description

Summary

The per-folder default values feature (added in v2.2.0) is configurable through the web UI but has no OCS API. External integrations (scripts, migrations, automation using an app-password / Bearer token) cannot read or set field defaults — the existing endpoints are CSRF-protected web routes only.

Current state

The defaults endpoints live in the web routes surface, not the ocs surface, in appinfo/routes.php:

Endpoint Verb Purpose
/api/groupfolders/{id}/defaults GET get configured defaults (by field id)
/api/groupfolders/{id}/defaults POST set/clear a field default — { fieldId, value }
/api/groupfolders/{id}/defaults/trigger POST queue a discovery/backfill run
/api/groupfolders/{id}/defaults/status GET poll whether backfill is still running

These are handled by DefaultsController (extends BaseController, #[NoAdminRequired], requires manage_fields on the folder) and are CSRF-protected — usable only from an authenticated browser session, not from an external client.

There is no OCS equivalent (verified: the ocs route block has zero default entries). The only non-UI path today is the occ metavox:apply-defaults command, which applies existing defaults but does not configure them.

Proposal

Expose the defaults functionality on the OCS API, mirroring the existing Api*Controller pattern (ApiFieldController / ApiFilterController / ApiViewController + BaseOCSController):

  • GET /api/v1/groupfolders/{groupfolderId}/defaults — list configured defaults
  • POST /api/v1/groupfolders/{groupfolderId}/defaults — set/clear a default ({ fieldId, value })
  • POST /api/v1/groupfolders/{groupfolderId}/defaults/trigger — queue backfill
  • GET /api/v1/groupfolders/{groupfolderId}/defaults/status — backfill status

Implementation notes:

  • Add an ApiDefaultsController extends BaseOCSController that delegates to the existing DefaultsService (so behaviour stays identical to the web controller — no logic duplication).
  • Keep the same authorization: require manage_fields permission on the groupfolder.
  • Reuse the same value validation as the web setDefault (type-correct per field type, null = clear).
  • Document the new endpoints under docs/ (and the NL docs/*.nl.md source-of-truth), consistent with how the other OCS endpoints are documented.

Why

This enables SharePoint-style bulk provisioning use cases — e.g. a migration script that creates Team folders, defines fields, and seeds their default values end-to-end without a human clicking through Personal/Admin settings. It rounds out the API parity that fields, metadata, filters and views already have on OCS.

Acceptance criteria

  • OCS endpoints for get/set/trigger/status of folder defaults
  • Authorized via app-password/Bearer (no CSRF requirement), gated on manage_fields
  • Shared logic with the web controller (via DefaultsService), no behavioural drift
  • Docs updated (EN + NL source)

Spun off from the v2.2.0 release work — targeted at a future release.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with appinfo/routes.php, DefaultsController, DefaultsService, and the ApiFieldController, ApiFilterController, and ApiViewController patterns. Add the four OCS routes and document them under docs/ and the corresponding docs/*.nl.md sources, preserving manage_fields authorization and shared validation. Done means app-password or Bearer clients can get, set or clear, trigger, and check default values without CSRF.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
api, backend, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.