MetaVox integratie-gids¶
Deze gids beschrijft het integreren van MetaVox met externe systemen, migreren vanaf andere platforms en het benutten van Nextcloud's ecosysteem.
Nextcloud-integratie¶
Group Folders¶
MetaVox vereist de Group Folders-app en integreert diep:
- Folder-detectie: detecteert automatisch tot welke group folder een bestand behoort
- Permissie-overerving: respecteert Group folder-ACL-instellingen
- Metadata-scoping: elke group folder kan unieke metadata-schema's hebben
Nextcloud Flow¶
MetaVox registreert zich bij de Workflow Engine voor metadata-gebaseerde automatisering.
Hoe het werkt:
- MetaVox implementeert
ICheck-interface - Registreert via
RegisterChecksEvent - Levert Vue-component voor voorwaarde-configuratie
- Evalueert metadata-voorwaarden wanneer Flow triggert
De controle is alleen beschikbaar in admin-Flow-regels, en matcht alleen bestanden in een teammap (geen mappen, geen persoonlijke bestanden).
Voorbeeld Flow-regel:
Trigger: Bestand geopend
Voorwaarde: MetaVox > classification = confidential
Actie: Blokkeer toegang
Zie Flow-integratie voor configuratie-details.
Nextcloud Search¶
Metadata-waarden zijn doorzoekbaar via Nextcloud's unified search. Vrij zoeken gebruikt een woordindex per teammap, zodat elk lid bestanden vindt op hun metadata; resultaten bevatten alleen bestanden die de gebruiker mag lezen. Datum-, nummer-, selectievakje- en bestandslinkvelden staan niet in de woordindex; die vind je met een veldfilter of een field:value-zoekopdracht. Zie Architectuur-overzicht.
SharePoint-migratie¶
MetaVox is ontworpen om migraties vanaf Microsoft SharePoint te ondersteunen door document-metadata te behouden.
Migratie-aanpak¶
SharePoint MetaVox API Nextcloud
┌─────────┐ ┌──────────────┐ ┌──────────┐
│Documenten│──────▶│batch-update │───────▶│Group │
│+Metadata│ │-endpoint │ │Folders │
└─────────┘ └──────────────┘ └──────────┘
Migratie-stappen¶
- Exporteer SharePoint-metadata — extract document-metadata naar JSON/CSV
- Maak veld-definities aan — zet equivalente velden op in MetaVox
- Upload bestanden — verplaats documenten naar Nextcloud-group folders
- Map metadata — transformeer SharePoint-velden naar MetaVox-format
- Batch-importeer — gebruik API om metadata te vullen
Veld-mapping voorbeeld¶
| SharePoint-veld | MetaVox-equivalent |
|---|---|
| Content Type | select-veld met opties |
| Modified By | user-veld |
| Retention Label | select-veld |
| Custom-kolommen | Diverse veldtypen |
API voor migratie¶
Gebruik het batch-update-endpoint voor efficiënte imports:
POST /ocs/v2.php/apps/metavox/api/v1/files/metadata/batch-update
{
"updates": [
{
"file_id": 123,
"groupfolder_id": 1,
"metadata": {
"file_gf_status": "Goedgekeurd",
"file_gf_department": "Juridisch",
"file_gf_retention": "7 jaar"
}
},
// ... meer bestanden
]
}
Zie API-referentie voor complete documentatie.
Migratie-tips¶
- Batch-grootte: beperk tot 100 bestanden per API-call
- Veld-aanmaak: maak velden eerst via API of importeer JSON-template
- Validatie: test met kleine batch vóór volledige migratie
- Error-handling: check response op partiële mislukkingen
Externe-systeem-integratie¶
Via OCS API¶
Externe systemen kunnen met MetaVox interacteren via de OCS REST API:
Authenticatie:
- Basic auth met app-wachtwoord
- Bearer token (bij gebruik van OAuth)
Veelvoorkomende operaties:
- Metadata ophalen voor een bestand
- Metadata bijwerken
- Batch-operaties
- Statistieken ophalen
Webhook-integratie¶
Combineer MetaVox met Nextcloud Flow om externe systemen te triggeren:
- Flow-regel detecteert metadata-voorwaarde
- Flow roept webhook-actie aan
- Extern systeem ontvangt notificatie
Voorbeeld: notificeer document-management-systeem wanneer documentstatus naar "Gepubliceerd" verandert.
Custom-app-integratie¶
PHP-apps kunnen MetaVox-services direct gebruiken. Deze services controleren de rechten van de gebruiker niet; dat doet de aanroepende app.
use OCA\MetaVox\Service\FieldService;
$fieldService = \OCP\Server::get(FieldService::class);
// Haal metadata op voor een bestand
$metadata = $fieldService->getGroupfolderFileMetadata($groupfolderId, $fileId);
// Update metadata: bestands-id => [veldnaam => waarde]
$fieldService->saveValues($groupfolderId, [$fileId => [$fieldName => $value]]);
Het metadatapaneel insluiten¶
Een andere app kan het eigen metadatapaneel van MetaVox tonen, hetzelfde als in
de zijbalk van Bestanden, als custom element <metavox-metadata-form>. De
host krijgt de veldkiezers, het bewerkvenster, de teammapvelden en de lijst
"Gelinkt vanuit", zonder afhankelijk te zijn van de Vue-versie van MetaVox.
Laad de bundel tijdens het opbouwen van de pagina. MetaVox is optioneel voor de host, dus bewaak de aanroep:
if (class_exists(\OCA\MetaVox\Embed\MetadataFormEmbed::class)) {
\OCP\Server::get(\OCA\MetaVox\Embed\MetadataFormEmbed::class)->load();
}
isAvailable($userId) zegt of MetaVox voor een gebruiker aan staat.
Plaats daarna het element met een bestands-id:
const el = document.createElement('metavox-metadata-form')
el.fileId = node.fileid
container.appendChild(el)
Het attribuut file-id werkt ook. MetaVox zoekt zelf de teammap en bepaalt of
de gebruiker mag bewerken, met dezelfde regel als bij elke opslag: de host geeft
geen teammap of rechten mee. Een bestand buiten een teammap toont een melding in
plaats van velden.
Events borrelen op vanaf het element:
| Event | Detail |
|---|---|
metavox:loaded |
{ fileId, fields } |
metavox:saved |
{ fileId, metadata } (de gewijzigde velden) |
metavox:error |
{ message } |
Data-uitwisselings-formaten¶
JSON veld-definitie¶
[
{
"field_name": "status",
"field_label": "Document-status",
"field_type": "select",
"field_description": "Huidige status van het document",
"field_options": [
{"value": "Concept"},
{"value": "In review"},
{"value": "Goedgekeurd"},
{"value": "Gearchiveerd"}
],
"is_required": true
}
]
CSV-export¶
Bulk-editor exporteert metadata als CSV. De kolommen zijn het bestandspad, de bestandsnaam en één kolom per veld, met het veldlabel als kop (in de taal van de gebruiker):
Bestandspad,Bestandsnaam,Status,Afdeling,Herzieningsdatum
/Documenten/rapport.pdf,rapport.pdf,Goedgekeurd,Juridisch,2025-01-15
/Documenten/memo.docx,memo.docx,Concept,HR,
Integratie-patronen¶
Event-driven¶
Use case: automatische classificatie, notificaties, toegangscontrole.
Scheduled¶
Use case: compliance-rapportage, sync met externe systemen.
On-demand¶
Use case: custom UI, mobile apps, integraties.
Third-party-tools¶
MetaVox kan integreren met:
| Tool | Integratie-methode |
|---|---|
| n8n | OCS API-calls |
| Windmill | OCS API-calls |
| Zapier | Webhooks via Flow |
| Power Automate | OCS API (met custom connector) |
| Custom scripts | OCS API, PHP-SDK |
Best practices¶
- Gebruik batch-operaties voor bulk-wijzigingen
- Valideer veldnamen vóór API-calls
- Handel fouten netjes af — check op partiële mislukkingen
- Cache veld-definities in integraties
- Test in staging vóór productie-migraties
Zie ook¶
- API-referentie — Complete API-documentatie
- Architectuur-overzicht — Systeem-design
- Privacy & beveiliging — Databescherming