Passer au contenu principal
Une spécification d’ingestion est le contrat complet qui transforme un fichier entrant en lignes dans le modèle analytique de Solya. Cette référence en documente chaque partie. Pour l’introduction orientée utilisateur, voir le guide de couche données.

​
Comment un fichier circule dans une spécification

1

Détection

Solya décide quelle spécification s’applique à un fichier entrant, en utilisant les règles de détection de la spécification.
2

Analyse

Le fichier est lu sous forme tabulaire et ses colonnes sont mappées à des champs typés, en utilisant la configuration d’analyse.
3

Promotion

Un ou plusieurs pipelines de promotion transforment les données analysées et les écrivent dans les tables silver/gold.

​
Forme de premier niveau

Une spécification est rédigée en JSON (clés en snake_case). Ses champs :
ChampRequisDescription
spec_id✓Identifiant canonique, stable entre les versions (ex. polaris_sav, ginkoia_tickets).
spec_version✓Numéro de version monotone. Unique par (spec_id, spec_version).
name–Nom d’affichage.
description–À quoi sert la spécification.
pos_system–Identifiant du système source (ex. polaris, ginkoia).
status✓DRAFT · ACTIVE · DEPRECATED · ARCHIVED.
scope✓GLOBAL (seeds de la plateforme, partagée) ou ORG (possédée par l’organisation).
organization_idconditionnelRequis pour la portée ORG ; null pour GLOBAL.
is_default✓Indique si c’est la spécification par défaut pour son pos_system + scope.
priority✓Brise-égalité quand plusieurs spécifications correspondent (plus haut gagne). Par défaut 0.
detection✓La configuration de détection.
parsing✓La configuration d’analyse.
promotions–Un tableau de pipelines de promotion, un par dataset de sortie.
promotion–Forme de promotion unique dépréciée ; utiliser promotions.
tags✓{ "systems": [...], "formats": [...] } pour le filtrage UI.
{
  "spec_id": "ginkoia_tickets",
  "spec_version": 2,
  "name": "Ginkoia — Tickets",
  "pos_system": "ginkoia",
  "status": "ACTIVE",
  "scope": "GLOBAL",
  "is_default": true,
  "priority": 0,
  "detection": { "match_mode": "composite", "rules": [ /* … */ ] },
  "parsing":   { "parser": { /* … */ }, "mapping": { /* … */ } },
  "promotions": [ { /* … */ } ],
  "tags": { "systems": ["ginkoia"], "formats": ["excel"] }
}

​
Portée : GLOBAL vs ORG

  • Les spécifications GLOBAL sont fournies par la plateforme et disponibles pour chaque organisation. Elles couvrent les formats POS standards (Polaris, Ginkoia, Kezia, …).
  • Les spécifications ORG appartiennent à une seule organisation (organization_id défini) et ne sont visibles que pour elle.

​
Déploiement

L’existence n’est pas la même que l’activation pour une organisation. Une spécification est déployée vers une organisation via un enregistrement d’activation (flag enabled) — ainsi une organisation peut activer/désactiver les spécifications sans que personne n’édite la spécification elle-même. Dans l’API/DTO cela apparaît comme isDeployed sur chaque spécification.

​
Priorité et résolution de conflits

Quand plus d’une spécification correspond à un fichier :
  1. Les spécifications sont classées par priority (décroissant).
  2. La spec_version plus récente prend préséance.
  3. La première spécification correspondante est appliquée.

​
Cycle de vie et versioning

DRAFT → ACTIVE ⇄ DEPRECATED → ARCHIVED
  • Un spec_id peut avoir plusieurs versions ; (spec_id, spec_version) est unique.
  • Le seeding est idempotent (upsert sur cette paire) ; les spécifications GLOBAL supprimées de l’ensemble de seeds sont archivées, non supprimées, pour préserver l’historique.
Continuez vers les trois éléments constitutifs : Détection, Analyse, et le catalogue Étapes de promotion — puis voir les exemples complets.