Appearance
BDD-135 — Ajout d’une source API dans un workflow
1. User Story
En tant qu’administrateur, je veux configurer un nœud source d’un workflow avec une connexion API (formulaire ou endpoint), afin de récupérer des données externes et les faire circuler dans mon pipeline de traitement.
2. Critères d’acceptance
| # | Critère | Statut |
|---|---|---|
| 1 | Le nœud source du workflow permet de choisir entre Document (existant) ou Source API | ✅ |
| 2 | En mode API : sélection d’une connexion ACTIVE + formulaire ou endpoint | ✅ |
| 3 | Un aperçu des données API est affiché avant confirmation | ✅ |
| 4 | Le workflow charge les données de l’API et les fait circuler dans le pipeline | ✅ |
| 5 | La configuration est sauvegardée avec le workflow | ✅ |
3. Périmètre fonctionnel
Frontend
| Fichier | Rôle |
|---|---|
front/src/components/workflows/WorkflowSourceSelectorPanel.vue | Sélecteur source (document vs API) avec toggle |
front/src/components/workflows/WorkflowInputSourcePanel.vue | Panneau de configuration API : connexion, formulaire/endpoint, preview |
front/src/components/workflows/WorkflowApiSourcePreview.vue | Aperçu des données API (tableau, limité à N lignes) |
front/src/components/workflows/WorkflowSourcePreviewTable.vue | Composant réutilisable de tableau de preview |
front/src/composables/useWorkflowActiveSourceBindings.ts | Gestion des liaisons source active et config API |
front/src/pages/admin/workflows/useWorkflowSourcePreview.ts | Chargement des données de preview (document ou API) |
front/src/stores/workflow-store.js | Action setWorkflowSourceConfig (unifiée document/API) |
front/e2e/pages/admin/workflows/workflow-api-source.spec.js | Tests E2E configuration source API |
Backend
| Fichier | Rôle |
|---|---|
back/src/api/workflows/workflow-source-api-config.ts | Service de résolution config API (connexion + formulaire) |
back/src/api/workflows/workflow-canvas-api-bindings.ts | Mapping canvas → données API runtime |
back/src/api/workflows/staging/workflow-api-input.service.ts | Chargement des données API au lancement (similaire à document staging) |
back/src/api/workflows/staging/workflow-run-staging-execution.service.ts | Exécution du staging avec source API (unifiée document/API) |
back/src/api/workflows/workflows.service.ts | setWorkflowSourceConfig avec validation API |
back/src/api/workflows/workflow.presenter.ts | Mapping sourceConfig (document vs API dans la réponse) |
back/src/api/workflows/workflows.controller.ts | Endpoint POST /workflows/:uuid/source-config (unifiée) |
Base de données
| Changement | Détail |
|---|---|
Schema workflows → sourceConfig JSONB | Stockage document ou API (XOR : documentUuid ou sourceApiConfig) |
sourceApiConfig structure | { connectionUuid, formUuid, formTitle } |
4. Endpoints API
| Méthode | Chemin | Guards | Description |
|---|---|---|---|
POST | /workflows/:uuid/source-config | AuthGuard, AdminGuard | Configure la source (document ou API) |
GET | /workflows/:uuid/source-preview | AuthGuard, AdminGuard | Aperçu des données (document ou API) |
Corps POST /workflows/:uuid/source-config — mode document
json
{
"sourceType": "document",
"documentUuid": "uuid-doc"
}Corps POST /workflows/:uuid/source-config — mode API
json
{
"sourceType": "api",
"connectionUuid": "uuid-connexion",
"formUuid": "uuid-formulaire",
"formTitle": "Réponses Formulaire"
}Réponse GET /workflows/:uuid/source-preview?sourceType=api&connectionUuid=...&formUuid=...
json
{
"columns": [
{ "name": "email", "type": "text" },
{ "name": "date_inscription", "type": "date" }
],
"data": [
{ "email": "[email protected]", "date_inscription": "2026-01-15" },
{ "email": "[email protected]", "date_inscription": "2026-02-01" }
],
"rowCount": 2,
"isSample": true
}Erreurs courantes
| Code | Cas |
|---|---|
400 | sourceType manquant ou invalide, documentUuid / connectionUuid incohérent |
401 | Jeton absent / invalide |
403 | Rôle non admin |
404 | Document, connexion ou formulaire introuvable |
5. Règles métier implémentées
- Périmètre entreprise
- Administrateur : document / connexion limitée à son
enterprise_id. - Super-admin : voit toutes les entreprises.
- Administrateur : document / connexion limitée à son
- Modèle unifié :
workflows.sourceConfigJSONB contient exactement une source (document ou API).- Lors du lancement, le staging résout l’origine (document S3 ou API formulaire) et charge les données.
- Validation au runtime :
- Connexion doit être
ACTIVE. - Formulaire doit contenir au moins une colonne.
- Document doit exister et être accessible.
- Connexion doit être
- Preview limité :
- Maximum N lignes (ex. 20) pour éviter les surcharges.
- Permet l’affichage des colonnes et d’un échantillon de données.
6. Points de vérification
- Éditeur workflow : accès au sélecteur source (Document vs API).
- Bascule en mode API : liste des connexions
ACTIVEchargée, sélection → liste des formulaires. - Sélection formulaire : preview affiché avec colonnes détectées.
- Sauvegarde de la config : workflow persisté avec
sourceConfig.connectionUuid,sourceConfig.formUuid. - Lancement workflow : données API chargées et circulant dans le pipeline (même comportement que document).
- Erreurs : connexion ou formulaire introuvable → message explicite, workflow non sauvegardé.
7. Tests associés
Backend (unitaires)
back/src/api/workflows/workflow-source-api-config.spec.ts- Résolution connexion + formulaire : happy path, connexion introuvable, formulaire sans colonnes, connexion non ACTIVE.
- Validation périmètre entreprise.
back/src/api/workflows/staging/workflow-api-input.service.spec.ts- Chargement des données API avec limite de preview.
- Inférence des colonnes depuis réponses.
back/src/api/workflows/staging/workflow-run-staging-execution.service.spec.ts- Staging unifié document / API : chargement source, construction schema.
- Cas erreur : connexion inactive, formulaire sans données.
back/src/api/workflows/workflows.service.spec.tssetWorkflowSourceConfigdocument & API (validation, sauvegarde).
Backend (e2e)
back/test/e2e/workflows-controller.e2e-spec.tsPOST /workflows/:uuid/source-configmode document / API.GET /workflows/:uuid/source-previewavecsourceType=api.- Erreurs : 400 (config invalide), 401, 403, 404.
Frontend (unitaires)
front/src/__tests__/components/workflows/WorkflowSourceSelectorPanel.spec.js- Toggle document / API.
- Affichage conditionnel formulaires / endpoints.
front/src/__tests__/components/workflows/WorkflowInputSourcePanel.spec.js- Chargement connexions.
- Sélection formulaire → appel preview.
- Erreurs : connexion introuvable.
front/src/__tests__/composables/useWorkflowActiveSourceBindings.spec.js- Gestion état source active.
- Synchronisation config document / API.
front/src/__tests__/pages/admin/workflows/useWorkflowSourcePreview.spec.js- Chargement preview document et API.
- Limite de lignes respectée.
Frontend (e2e Playwright)
front/e2e/pages/admin/workflows/workflow-canvas.spec.js- Ouverture sélecteur source, bascule API, sélection formulaire, preview affiché.
- Sauvegarde et relecture de la config API.
- Lancement workflow avec source API : données circulant.
8. Documentation technique
9. Hors périmètre
- Endpoint non-formulaire (API REST générique) — reporté.
- Synchronisation périodique des sources API — reporté (ticket dédié).
- Transformation des données API avant chargement — hors scope staging.