Omni Content Builder

Créez, mettez à jour et gérez les documents et dashboards Omni par programmation via la CLI Omni — cycle de vie des documents, modèles de classeurs, filtres et contenu des dashboards.

Conseil : Utilisez omni-model-explorer pour comprendre les champs disponibles et omni-content-explorer pour trouver les dashboards existants à modifier ou dont vous inspirer.

Problèmes connus et paramètres par défaut sûrs

• Exécutez toujours la boucle de validation complète — voir Validation Loops ci-dessous. Au minimum : validez le modèle, testez chaque requête via omni query run, vérifiez la cohérence des spécifications de visualisation, et vérifiez le dashboard après sa création en le relisant et en exécutant ses requêtes.
• Rendu des graphiques : Les types de graphiques complexes peuvent afficher « No chart available » dans l'interface Omni si config, visType ou prefersChart sont mal configurés. Utilisez par défaut chartType: "table" pour un rendu fiable, et configurez les visualisations de graphiques dans l'interface Omni.
• Chaque requête doit inclure au moins une mesure — une requête contenant uniquement des dimensions produit des tuiles vides/sans sens (par ex. juste des mois sans données).
• Utilisez identifier et non id pour tous les appels d'API de document — .id est null pour les documents de type classeur et échouera silencieusement.
• Les filtres booléens peuvent être silencieusement supprimés quand un tableau pivots est présent (bug Omni signalé). Si les filtres booléens ne s'appliquent pas, supprimez le pivot et testez à nouveau.
• Les mises à jour de dashboard sont des remplacements complets — PUT /api/v1/documents/{documentId} remplace l'état complet du document. Lisez toujours le document existant d'abord et modifiez-le à partir de là, sinon vous perdrez les tuiles que vous n'avez pas incluses.

Prérequis

# Vérifiez que la CLI Omni est installée — sinon, demandez à l'utilisateur de l'installer
# Voir : https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Affichez les profils disponibles et sélectionnez-en un
omni config show
# S'il existe plusieurs profils, demandez à l'utilisateur lequel utiliser, puis basculez :
omni config use <profile-name>

Découvrir les commandes

omni documents --help           # Document operations
omni dashboards --help          # Dashboard operations
omni models yaml-create --help  # Writing model YAML

Conseil : Utilisez -o json pour forcer une sortie structurée en JSON pour l'analyse programmatique, ou -o human pour des tableaux lisibles. La valeur par défaut est auto (human dans un TTY, JSON quand pipeté).

Architecture des dashboards

Les dashboards Omni sont construits à partir de documents (classeurs). Chacun possède :

• Une vue de dashboard (la disposition publiée et partageable)
• Un ou plusieurs onglets de requête (requêtes sous-jacentes)
• Un modèle de classeur (personnalisations de modèle par dashboard)

Les documents peuvent être créés avec des configurations complètes de requête et visualisation via queryPresentations. Le réglage fin de la disposition des tuiles se fait mieux dans l'interface Omni.

Gestion des documents

Créer un document (nom uniquement)

omni documents create --body '{
  "modelId": "your-model-id",
  "name": "Q1 Revenue Report"
}'

Renvoie l'identifier, workbookId et dashboardId du nouveau document.

Créer un document avec requêtes et visualisations

Utilisez queryPresentations pour créer un document pré-rempli avec des onglets de requête et des configurations de visualisation.

Doc gap : La documentation de l'API create-document mentionne queryPresentations mais ne montre pas la structure complète. Cette section documente le format complet.

omni documents create --body '{
  "modelId": "your-model-id",
  "name": "Q1 Revenue Report",
  "queryPresentations": [
    {
      "name": "Monthly Revenue Trend",
      "topicName": "order_items",
      "prefersChart": true,
      "visType": "basic",
      "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
      "query": {
        "table": "order_items",
        "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
        "sorts": [{ "column_name": "order_items.created_at[month]", "sort_descending": false }],
        "filters": { "order_items.created_at": "this quarter" },
        "limit": 100,
        "join_paths_from_topic_name": "order_items",
        "visConfig": { "chartType": "lineColor" }
      },
      "config": {}
    }
  ]
}'

Conseil : Utilisez par défaut "config": {} pour un rendu fiable — Omni générera automatiquement la configuration du graphique. Pour un style de graphique précis, construisez un dashboard de référence dans l'interface et relisez-le via GET /api/v1/documents/{documentId}. Voir references/queryPresentations.md pour des exemples de configuration complets par type de graphique (KPI, ligne, barre, surface, camembert, scatter, etc.).

Structure de queryPresentation

Voir references/queryPresentations.md pour la référence complète — tableaux de paramètres pour les objets queryPresentation et query, exemples de type de graphique et avertissements lors de la réutilisation de présentations à partir de dashboards existants. Voir references/visConfig.md pour la référence complète des objets visConfig et config — toutes les valeurs chartType acceptées, structure de configuration pour chaque famille de graphiques (cartésienne, KPI, camembert, entonnoir, sankey, heatmap, carte) et exemples pratiques.

Points clés :

• prefersChart doit être true pour afficher un graphique (sinon affiche toujours un tableau)
• visType : "omni-kpi" pour les tuiles KPI, "basic" pour tous les autres graphiques
• visConfig se place dans l'objet query (silencieusement supprimé s'il est placé en tant que frère)
• fields doit être dupliqué aux niveaux queryPresentation et query
• modelId est hérité du document — non nécessaire dans la query
• Utilisez par défaut "config": {} pour un rendu fiable — Omni génère automatiquement la configuration du graphique
• Pour les détails complets du schéma visConfig et config, voir references/visConfig.md

Pour apprendre la structure exacte d'un type de graphique, construisez un dashboard de référence dans l'interface Omni et relisez-le :

omni documents get <documentId>

Lors de la réutilisation de queryPresentations à partir de documents existants, supprimez toujours model_extension_id des objets query (provoque des erreurs « Chart unavailable ») et filtrez pour inclure uniquement les tuiles souhaitées.

Renommer un document

omni documents update <documentId> --name "Q1 Revenue Report (Updated)" --clear-existing-draft true

Passez --clear-existing-draft true si le document a un brouillon existant, sinon l'API renvoie 409 Conflict.

Supprimer un document

omni documents delete <documentId>

Supprime le document de façon réversible (le déplace à la Corbeille).

Déplacer un document

omni documents move <documentId> "/Marketing/Reports" --scope organization

Utilisez "null" comme chemin de dossier pour déplacer à la racine. --scope est optionnel — auto-calculé à partir du dossier de destination.

Dupliquer un document

omni documents duplicate <documentId> "Copy of Q1 Revenue Report" --folder-path "/Marketing/Reports"

Seuls les documents publiés peuvent être dupliqués. Les documents en brouillon retournent 404.

Mettre à jour un dashboard existant

Mettez à jour les tuiles, requêtes, filtres et visualisations sur un dashboard existant via PUT /api/v1/documents/{documentId}. C'est un remplacement complet — vous devez passer l'état complet souhaité du document, pas seulement les champs que vous voulez modifier.

Avertissement : Ce point de terminaison fonctionne uniquement avec les documents de dashboard. Les documents classeur uniquement ne sont pas supportés et retournent 400.

Remarque : Ce point de terminaison est documenté sur docs.omni.co mais peut ne pas apparaître dans l'OpenAPI spec sur /openapi.json pour le moment.

Flux de mise à jour

Étape 1 — Lire le document existant pour obtenir son état actuel :

omni documents get <documentId>

Cela renvoie le document complet incluant queryPresentations, filterConfig, filterOrder, modelId, name et autres champs. Utilisez-le comme point de départ.

Étape 2 — Modifier la réponse selon les besoins :

• Pour ajouter une tuile : ajoutez une nouvelle entrée au tableau queryPresentations
• Pour supprimer une tuile : supprimez-la du tableau queryPresentations
• Pour modifier une tuile : modifiez l'query, config, fields etc. de l'entrée pertinente
• Pour mettre à jour les filtres : modifiez filterConfig et filterOrder

Étape 3 — PUT le document mis à jour :

# Remarque : Le remplacement complet du document via PUT n'est pas encore disponible dans la CLI.
# Utilisez HTTP direct pour le moment, ou utilisez omni documents update pour les mises à jour partielles (PATCH).
# Dérivez OMNI_BASE_URL et OMNI_API_TOKEN du profil actif pour cet appel.
curl -L -X PUT "$OMNI_BASE_URL/api/v1/documents/{documentId}" \
  -H "Authorization: Bearer $OMNI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "your-model-id",
    "name": "Q1 Revenue Report",
    "facetFilters": false,
    "refreshInterval": null,
    "filterConfig": {},
    "filterOrder": [],
    "clearExistingDraft": true,
    "queryPresentations": [ ... ]
  }'

Le tableau queryPresentations utilise la même structure que la création de document — voir ci-dessus.

Champs obligatoires

Champs optionnels

Avertissements

• Remplacement complet : Chaque queryPresentation que vous incluez devient une tuile. Toute tuile que vous omettez du tableau est supprimée. Commencez toujours à partir des queryPresentations du document existant et modifiez à partir de là.
• Conflit de brouillon : Les documents publiés avec des brouillons existants retournent 409 sauf si clearExistingDraft: true est défini.
• Voir aussi Avertissements lors de la réutilisation de queryPresentations (par ex., suppression de model_extension_id).

Mettre à jour le modèle d'un dashboard

Poussez des dimensions et mesures personnalisées vers un dashboard spécifique en écrivant dans son modèle de classeur. Chaque classeur a son propre modèle qui étend le modèle partagé — donc l'ID dans lequel vous écrivez du YAML est un ID de modèle, pas un « ID de classeur » séparé. C'est un flux en deux étapes :

Étape 1 — obtenir le document pour trouver son ID de modèle de classeur :

omni documents get <documentId>
# → utilisez le champ de niveau supérieur « modelId » de la réponse — c'EST l'ID du modèle du classeur

Remarque : La réponse ne contient pas de champ appelé workbook_id. Le modelId de niveau supérieur est le propre modèle du classeur (qui étend le modèle partagé) et c'est ce que vous transmettez à omni models yaml-create.

Étape 2 — POST du YAML vers le modèle du classeur avec mode: "extension" :

omni models yaml-create <workbookModelId> --body '{
  "fileName": "order_items.view",
  "yaml": "dimensions:\n  is_high_value:\n    sql: \"${sale_price} > 100\"\n    label: High Value Order\nmeasures:\n  high_value_count:\n    sql: \"${order_items.id}\"\n    aggregate_type: count_distinct\n    label: High Value Orders",
  "mode": "extension"
}'

Critique : Passez toujours "mode": "extension" lors de l'édition d'une vue existante dans un modèle de classeur. La valeur par défaut est "combined", qui traite votre corps YAML comme la définition complète de la vue et marque tous les champs que vous n'avez pas inclus comme ignored: true — cassant silencieusement les requêtes qui dépendent des champs de la vue de base partagée. Le mode extension superpose vos nouvelles dimensions et mesures sur la vue héritée.

fileName doit être "model", "relationships" ou se terminer par .view ou .topic. La valeur yaml est une chaîne YAML (pas un objet JSON). L'écriture dans un modèle de classeur ignore complètement la synchronisation git — l'autorisation est toujours vérifiée par rapport aux autorisations du modèle de base partagé sous-jacent.

Vérifier que l'extension a fonctionné

Après l'écriture, confirmez que les champs de la vue de base sont toujours disponibles en interrogeant l'un d'eux :

omni query run --body '{
  "query": {
    "modelId": "<workbookModelId>",
    "table": "order_items",
    "fields": ["order_items.id", "order_items.high_value_count"],
    "limit": 1,
    "join_paths_from_topic_name": "order_items"
  }
}'

Si la réponse génère une erreur sur un champ qui existe dans le modèle partagé (par ex. order_items.id), votre écriture a probablement utilisé le mode combined et ignoré les champs hérités. Réexécutez l'étape 2 avec "mode": "extension".

Filtres de dashboard

Obtenir les filtres actuels

omni dashboards get-filters <dashboardId>

Mettre à jour les filtres

Les filtres peuvent être mis à jour via deux approches :

1. PUT /api/v1/documents/{documentId} (recommandé) — mettez à jour les filtres dans le cadre d'une mise à jour complète du document. Incluez filterConfig et filterOrder aux côtés de queryPresentations et d'autres champs obligatoires. Voir la section Mettre à jour un dashboard existant.
2. omni dashboards update-filters <dashboardId> — mise à jour partielle des filtres. A été signalé pour retourner 405 ou 500 dans certaines configurations.

Pour les nouveaux dashboards, la façon la plus fiable est d'inclure filterConfig et filterOrder dans l'appel initial omni documents create. Voir references/filterConfig.md pour des exemples complets de chaque type de filtre.

omni documents create --body '{
  "modelId": "your-model-id",
  "name": "Filtered Dashboard",
  "filterConfig": {
    "date_filter": {
      "type": "date",
      "label": "Date Range",
      "fieldName": "order_items.created_at",
      "kind": "TIME_FOR_INTERVAL_DURATION",
      "ui_type": "PAST",
      "left_side": "6 months ago",
      "right_side": "6 months"
    },
    "state_filter": {
      "type": "string",
      "label": "State",
      "kind": "EQUALS",
      "fieldName": "users.state",
      "values": []
    }
  },
  "filterOrder": ["date_filter", "state_filter"],
  "queryPresentations": [...]
}'

Les clés dans filterConfig (par ex. "date_filter") sont des IDs arbitraires — elles doivent correspondre aux entrées dans filterOrder. Pour apprendre la structure exacte des filtres, lisez les filtres d'un dashboard existant avec omni dashboards get-filters <dashboardId>.

Types de filtres

Plage de dates (relative) — type: "date", kind: "TIME_FOR_INTERVAL_DURATION", nécessite fieldName

Plage de dates (absolue) — type: "date", kind: "WITHIN_RANGE", nécessite fieldName

Menu déroulant de chaîne — type: "string", kind: "EQUALS", nécessite fieldName, values: []

Bascule booléenne — type: "boolean", nécessite fieldName

Filtre masqué — tout filtre avec "hidden": true (appliqué mais non visible)

Critique : Chaque filtre DOIT inclure fieldName avec le nom de champ complètement qualifié (par ex. "order_items.created_at"). Sans lui, le filtre ne se liera à aucune colonne. Pour les filtres de date, n'INCLUEZ PAS de crochet d'intervalle de temps dans fieldName.

Contrôles (séparés des filtres)

Les contrôles changent les champs ou la granularité que les tuiles affichent. Ils se trouvent dans un tableau controls (NON dans filterConfig), mais leurs IDs sont inclus dans filterOrder.

Sélecteur d'intervalle de temps — type: "FIELD_SELECTION", kind: "TIMEFRAME" avec un tableau d'options

Sélecteur de champ — type: "FIELD_SELECTION", kind: "FIELD" avec un tableau d'options

Voir references/filterConfig.md pour des exemples complets de filtres et contrôles.

Modèles d'URL

Après avoir créé ou trouvé du contenu, fournissez toujours à l'utilisateur un lien direct :

Dashboard: {OMNI_BASE_URL}/dashboards/{identifier}
Workbook:  {OMNI_BASE_URL}/w/{identifier}

L'identifier provient du champ identifier du document dans les réponses d'API (pas id, qui est null pour les classeurs).

Boucles de validation

Chaque construction ou mise à jour de dashboard doit inclure une validation avant et après la création. Les tuiles cassées, les références de champs incorrects et les spécifications de visualisation mal configurées sont des défaillances silencieuses — le dashboard s'affiche mais les tuiles affichent « Chart unavailable » ou « No data » sans erreur au niveau de l'API.

Étape 1 : Valider le modèle

Avant de construire des requêtes, confirmez que le modèle sous-jacent est en bon état :

omni models validate <modelId>

Vérifiez la réponse pour les erreurs (pas seulement les avertissements). Si is_warning est false sur un problème, le champ ou la jonction peut être cassé et les requêtes le référençant échoueront silencieusement sur le dashboard.

Étape 2 : Tester chaque requête via l'exécution

Exécutez chaque requête prévue via omni query run avant de l'inclure dans un dashboard. C'est l'étape de validation la plus importante.

omni query run --body '{
  "query": {
    "modelId": "your-model-id",
    "table": "order_items",
    "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
    "filters": { "order_items.created_at": "last 90 days" },
    "limit": 10,
    "join_paths_from_topic_name": "order_items"
  }
}'

Ce qu'il faut vérifier dans la réponse :

• Aucun champ d'erreur — si la réponse contient une clé error, la requête est cassée. Corrigez avant de continuer.
• summary.row_count > 0 — une requête qui retourne zéro ligne s'affichera comme une tuile vide. C'est peut-être correct (pas de données pour la plage de filtre) mais vaut la peine d'être signalé.
• Incluez vos filtres de dashboard — transmettez les mêmes filtres que vous prévoyez d'utiliser dans filterConfig comme filtres au niveau de la requête ici. Cela détecte les mauvaises expressions de filtre (par ex. nom de champ incorrect, syntaxe non supportée) avant qu'elles ne deviennent des problèmes au niveau du dashboard.
• Requêtes longues — si la réponse inclut remaining_job_ids, interrogez avec omni query wait --jobids <ids> jusqu'à complétion, puis vérifiez le résultat final pour les erreurs.

Faites cela pour chaque requête que vous prévoyez d'inclure comme tuile. Un dashboard avec 5 tuiles nécessite 5 requêtes validées.

Étape 3 : Valider la cohérence de la spécification de visualisation

Avant d'assembler les queryPresentations, vérifiez la configuration de visualisation de chaque tuile par rapport à ces règles. Les incohérences causent « No chart available » ou un retour silencieux au rendu en tableau.

Vérifications de cohérence obligatoires :

Conseil : En cas de doute sur une configuration de visualisation, utilisez par défaut "prefersChart": false avec "config": {} pour afficher comme un tableau. Les tableaux fonctionnent toujours. Configurez les graphiques dans l'interface Omni après.

Étape 4 : Vérification post-création

Après avoir créé ou mis à jour un dashboard, lisez toujours le document et vérifiez que les tuiles fonctionnent :

4a. Relire le document :

omni documents get <documentIdentifier>

Vérifiez que :

• La réponse inclut toutes les queryPresentations attendues (le nombre correspond à ce que vous avez envoyé)
• Aucune entrée queryPresentations n'a d'objet query null ou manquant
• L'identifier est présent (vous en aurez besoin pour le lien de partage)

4b. Exécutez les requêtes du dashboard pour vérifier qu'elles s'exécutent :

# Extrayez les requêtes alimentant les tuiles du dashboard
omni documents get-queries <documentIdentifier>

Cela retourne les objets query pour chaque tuile. Exécutez chacun pour confirmer qu'il s'exécute sans erreurs :

# Pour chaque requête retournée, exécutez-la
omni query run --body '{
  "query": <query-object-from-get-queries>,
  "resultType": "csv"
}'

L'utilisation de "resultType": "csv" facilite la vérification rapide que les données semblent raisonnables (colonnes correctes, lignes non vides, plages de valeurs attendues).

Ce qu'il faut vérifier :

• La requête de chaque tuile s'exécute sans erreur
• summary.row_count > 0 pour les tuiles qui doivent afficher des données
• Pas de remaining_job_ids inattendus (qui peuvent indiquer des problèmes de dépassement de délai d'exécution de requête)

4c. Si une requête échoue : Le dashboard a une tuile cassée. Soit mettez à jour le document pour corriger la requête (via PUT /api/v1/documents/{documentId}), soit signalez le problème à l'utilisateur avant de partager le lien.

Résumé de la liste de contrôle de validation

Flux de travail de construction recommandés

Basé sur l'API (Création complètement programmatique)

1. Découvrez les champs — utilisez omni-model-explorer pour trouver le sujet + les champs
2. Validez le modèle — exécutez omni models validate <modelId> et vérifiez les erreurs
3. Testez chaque requête — exécutez chaque requête que vous prévoyez d'inclure via omni query run (en utilisant omni-query) avant de construire le dashboard. Incluez les mêmes filtres que vous prévoyez d'utiliser dans filterConfig comme filtres au niveau de la requête pour confirmer qu'ils s'analysent correctement. Cela détecte les fautes de frappe de nom de champ, les chemins de jonction manquants, les mauvaises expressions de filtre et les erreurs de permission avant qu'elles ne deviennent des tuiles cassées.
4. Validez les spécifications de visualisation — vérifiez les visType/chartType/config/prefersChart de chaque tuile par rapport aux règles de cohérence avant d'assembler le payload
5. Créez le document — un seul omni documents create avec queryPresentations + filterConfig + filterOrder tous dans un appel
6. Vérifiez le dashboard — relisez-le avec omni documents get, confirmez que toutes les tuiles sont présentes, puis exécutez la requête de chaque tuile via omni documents get-queries + omni query run pour vérifier qu'il n'y a pas de tuiles cassées
7. Partagez le lien — retournez {OMNI_BASE_URL}/dashboards/{identifier} à l'utilisateur (uniquement après que la vérification passe)
8. Affinez dans l'interface — la disposition des tuiles, le style des graphiques et la configuration avancée se font mieux dans l'interface Omni

Mettre à jour un dashboard existant

1. Trouvez le dashboard — utilisez omni-content-explorer ou omni documents list pour le localiser
2. Lisez son état actuel — omni documents get <documentId> pour obtenir le document complet incluant queryPresentations, filterConfig, etc.
3. Modifiez — ajoutez, supprimez ou modifiez les entrées du tableau queryPresentations ; mettez à jour filterConfig/filterOrder selon les besoins
4. Validez les modifications — exécutez les requêtes nouvelles ou modifiées via omni query run pour confirmer qu'elles fonctionnent. Vérifiez les spécifications de visualisation modifiées par rapport aux règles de cohérence.
5. PUT la mise à jour — PUT /api/v1/documents/{documentId} avec le document complet modifié et clearExistingDraft: true
6. Vérifiez la mise à jour — relisez le document avec omni documents get et confirmez que les tuiles attendues sont présentes. Exécutez omni documents get-queries + omni query run sur les tuiles modifiées pour vérifier qu'elles s'exécutent sans erreur.
7. Partagez le lien — retournez {OMNI_BASE_URL}/dashboards/{identifier} à l'utilisateur (uniquement après que la vérification passe)

Basé sur l'interface (Approche hybride)

1. Préparez le modèle — utilisez omni-model-builder pour les champs partagés, ou update-model pour les champs spécifiques au dashboard
2. Construisez dans l'interface — ajoutez des tuiles, choisissez les types de visualisation, arrangez la grille, définissez les filtres
3. Itérez via l'API — mettez à jour les champs du modèle, extrayez les requêtes pour réutilisation

Téléchargements de dashboard

# Démarrer le téléchargement asynchrone
omni dashboards download <dashboardId> --body '{ "format": "pdf" }'

# Interroger l'état du travail
omni dashboards download-status <dashboardId> <jobId>

Référence de documentation

• API Documents · Update Document · Dashboard Filters · Dashboard Downloads · Query API · Schedules API · Visualization Types
• Références de skill : queryPresentations.md · visConfig.md · filterConfig.md

Skills associées

• omni-model-explorer — comprendre les champs disponibles
• omni-model-builder — créer des champs de modèle partagé
• omni-query — tester les requêtes avant de les ajouter aux dashboards
• omni-content-explorer — trouver les dashboards existants pour apprendre
• omni-embed — intégrer les dashboards que vous avez construits dans des applications externes