1. Qué es#
La definición de un dashboard — visuales, filtros, páginas, bookmarks, modelo (tablas, relaciones, columnas calculadas, KPI) y dependencias — exportada como un único archivo JSON determinístico, que puede versionarse en Git, revisarse en un Pull Request y reimportarse sin perder identidad. Es el equivalente al PBIP / la integración con Git de Fabric.
2. Cuándo usarlo#
- Quieres un historial real de quién cambió qué en un panel, con revisión en PR.
- Vas a promover un panel entre entornos (dev → test → prod) sin copiar datos — mira Entornos y promoción.
- Necesitas probar lo que construiste sin exponer datos: la Ingestia Academy corrige los desafíos prácticos a partir de este archivo.
- Quieres un respaldo legible de la estructura del panel.
3. Cómo funciona#
El formato (ProjetoBI)
{
"formatVersion": 2,
"dashboard": {
"id": "…", // preservado en el round-trip
"name": "Vendas 2026",
"widgets": [ { "id": "w…", "viz": "line", "sql": "…" } ],
"pages": { … } | null, // canvas + pestañas
"filters": [ { "id": "…", "type": "select", … } ],
"bookmarks": [ { "id": "…", "name": "…" } ]
},
"model": { "tables": [], "relations": [], "calcColumns": [], "kpis": [] },
"dependencies": {
"savedQueryIds": [],
"semanticModelId": "…", // cuando hay vínculo con el modelo central
"tabelasReferenciadas": [ "dataset.tabela", … ]
}
}Determinismo (byte a byte). La exportación ordena las claves de objeto (recursivo, alfabético) y preserva el orden de los arrays (el orden de los widgets y de los filtros es semántico). El mismo proyecto genera exactamente los mismos bytes; el diff de Git solo aparece cuando el contenido cambia de verdad.
IDs preservados. Exportar nunca regenera un id: los widgets (w…), las columnas
calculadas, los KPI y las jerarquías salen con el id que tienen en la base. Las relaciones no tienen
id — la identidad es el propio vínculo (tabla.columna → tabla.columna). Por eso
reimportar el mismo archivo es idempotente: todo aparece como inalterado.
El flujo Git
Exportar
Abre Dashboards → [panel] → Compartir y, en la tarjeta Proyecto (BI-as-code), usa Exportar proyecto. Descarga
<nombre>-projeto.json.Commitear
Guarda el archivo en el repositorio de la empresa (ej.:
bi/<panel>/projeto.json):bashgit add bi/vendas/projeto.json git commit -m "bi(vendas): ajusta KPI de receita" git push
--- Revisar en el PR Como el archivo está ordenado y es multilínea, cada campo alterado es una línea del diff. Sin ruido de reordenamiento. --- Reimportar En la misma tarjeta Proyecto (BI-as-code), elige el archivo revisado (hasta 1 MB, leído en tu navegador) y haz clic en Previsualizar (dry-run): el producto muestra la clasificación de cada entidad antes de grabar. Importar proyecto solo se habilita después de esa previsualización.
### Import: dry-run + resolución explícita de conflictos
| status | significado |
| ------------- | ------------------------------------------------------- |
| `novo` | el id solo existe en el proyecto importado |
| `inalterado` | mismo id, contenido idéntico al actual |
| `conflito` | mismo id, **contenido diferente** (con diff legible en el idioma de quien lee) |
**Un conflicto nunca se resuelve en silencio.** Sin una estrategia elegida, el import
**aborta y no graba nada**. Estrategias (en el selector **Estrategia en caso de
conflicto**): **`manter_meu`** — "Mantener el mío" (queda el contenido actual),
**`usar_deles`** — "Usar el del archivo" (entra el del archivo), y
**`abortar_em_conflito`** — "Abortar en conflicto", que es el **valor por defecto de la pantalla**.
El merge es **aditivo**: lo que solo existe en tu panel se preserva — importar nunca
borra lo que no enviaste.
## 4. Requisitos previos
- Ser el **dueño del workspace**: exportar, previsualizar e importar el proyecto
definen el panel entero (definición + modelo), como duplicarlo o eliminarlo — la
tarjeta está en la página **Compartir**, y el formulario de import aparece solo para
el dueño.
- El panel necesita estar **guardado** (la exportación lee lo que está en la base, no lo que
está en la pantalla sin guardar).
- Para promover entre entornos: workspaces hermanos en la misma
[organización](../administracao/organizacao-e-workspaces.md).
## 5. Cómo validar
1. Exporta el panel; guarda el archivo A.
2. Reimporta A **sin cambiar nada**: el dry-run tiene que mostrar **solo `inalterado`**.
3. Exporta de nuevo (archivo B). `A` y `B` deben ser **idénticos byte a byte**
(`diff A B` vacío).
4. Cambia el título de un widget en el archivo y reimporta: el dry-run muestra **un**
`conflito`, con el diff de ese campo; cambia la estrategia a **"Usar el del
archivo"** (`usar_deles`) y haz clic en **Importar proyecto**. Con la estrategia
por defecto (abortar), el import rechaza y nada se graba.
## 6. Límites y advertencias
**Viaja en el proyecto (la definición):** ids de widgets, columnas calculadas, KPI y
jerarquías; visuales (tipo + SQL/configuración), filtros, bookmarks, página/canvas;
modelo; dependencias declaradas (`savedQueryIds`, `semanticModelId`,
`tabelasReferenciadas`).
**Queda en el entorno (NO migra):**
- **Datos y snapshots** — solo la definición viaja; el refresh repuebla los datos en el destino.
- **Secretos y credenciales** — conexiones, claves y tokens nunca entran en el archivo.
- **Programaciones e historial de ejecución** — cron, próximos disparos, ejecuciones.
- **Estado por persona** — vistas personales y favoritos.
Compatibilidad: `formatVersion` **corriente = 2**; la lectura acepta **2 y 1** (la
anterior sufre un _upgrade_ automático, `page` → `pages`). Un `formatVersion`
desconocido, un JSON roto o sin `formatVersion` es **rechazado** (fail-closed).
Los **pipelines** no entran en este formato — tienen su propio
[versionado](../orquestracao/publicar-e-versionar.md).
## 7. Datos de ejemplo (sintéticos)
Workspace **Aurora Varejo**: panel "Comercial Aurora" sobre `aurora_gold.vendas`,
`produtos`, `filiais` y `calendario`, con las medidas `Receita`, `Pedidos` y
`Ticket médio`. El archivo exportado tiene `dependencies.tabelasReferenciadas`
apuntando a esas cuatro tablas y `model.relations` con
`vendas.produto_id → produtos.id` y `vendas.filial_id → filiais.id`.
## 8. Evidencia
Suite determinística de **round-trip** (exportar → importar → exportar devuelve los
mismos bytes), de **ordenamiento canónico** (claves en cualquier orden → misma salida),
de **clasificación del dry-run** (nuevo / sin cambios / conflicto) y de **rechazo**
de un `formatVersion` desconocido.
**Relacionado:** [Editor, canvas, páginas y temas](editor-canvas-paginas-temas.md) ·
[Publicar y compartir](tutorial-publicar-e-compartilhar.md) ·
[Entornos y promoción](../administracao/ambientes-e-promocao.md).