Layout Importação Dashboards
Índice
Conceito
Esta página descreve o formato dos arquivos de exportação e importação de dashboards e widgets. Serve de referência para quem precisa gerar esses arquivos fora do sistema — inclusive para orientar um agente de IA (veja Assuntos Relacionados).
Os arquivos
São dois arquivos no formato JSON, ambos gravados em UTF-8, lidos pelos botões Importar dos respectivos cadastros.
| Arquivo | Extensão | Cadastro |
|---|---|---|
| Dashboard | .phdashapp | Dashboards |
| Widget avulso | .phwidget | Widgets |
O arquivo de dashboard já traz os widgets embutidos: importar um dashboard cria ou atualiza também os widgets que ele utiliza, o catálogo de Campos de cada um e os Filtros do Item.
Regras gerais
- Identificação pelo Nome: a importação cria o que não existe e atualiza o que existe. O dashboard é identificado pelo nome; o widget pelo nome mais o tipoWidget; o item pela sequencia dentro do dashboard; a série pela sequencia dentro do widget. Reimportar o mesmo arquivo atualiza no lugar, sem duplicar.
- Validação antes de gravar: o arquivo é conferido por inteiro antes de qualquer gravação. Havendo problema, nada é importado e é devolvida a lista completa das correções, numerada e identificando o item e o widget de cada uma.
- Formulário: quando o dashboard tem filtro, o Formulário é referenciado pelo nome e precisa já existir na base de destino — ele não vai dentro do arquivo.
- Cores: aceitam o formato #RRGGBB ou o número inteiro usado pelo sistema. Em branco, vale a cor padrão do tema.
Campos omitidos
Campo que não for informado grava o padrão abaixo. Não é necessário repetir as opções que valem "não".
| Campo | Padrão |
|---|---|
| tipoSerie | F (série fixa). Somente D liga a série dinâmica. |
| posicaoLegenda | D (direita). |
| exibirTitulo, exibirValores, destacarDiferenca, exibirFundoBarra, os quatro arredondamento, exibirPercentual | N |
| ehSistema (dashboard, item, widget, campo e filtro) | N |
| titulo do item | O título do widget daquele item. |
Arquivo de dashboard
{
"versao": 2,
"nome": "DASH_RECEITAS",
"legenda": "Receitas",
"ehSistema": "N",
"formulario": "",
"itens": [
{
"sequencia": 1,
"titulo": "",
"altura": 7,
"largura": 16,
"ehSistema": "N",
"widget": { },
"filtros": []
}
]
}
| Campo | Regra |
|---|---|
| nome | Obrigatório. É a chave de importação. |
| legenda | Obrigatória. Texto exibido ao usuário. |
| formulario | Nome de um Formulário existente na base. Obrigatório quando algum item tiver filtros; em branco para dashboard sem filtro. |
| itens | Ao menos um item. |
| itens.sequencia | Maior que zero e única dentro do dashboard. |
| itens.largura | De 1 a 16 colunas da grade. |
| itens.altura | Maior que zero, em linhas da grade. |
| itens.titulo | Em branco assume o título do widget. |
| itens.widget | O widget completo, no mesmo formato do arquivo avulso. |
Filtro do item
Liga um campo do Formulário do dashboard a um Campo do widget daquele item.
{"formularioCampo": "DATAINICIAL", "widgetCampo": "DATAEMISSAO", "operacao": 3, "ehSistema": "N"}
| Operação | Significado |
|---|---|
| 1 | Igual |
| 2 | Diferente |
| 3 | Maior ou igual |
| 4 | Menor ou igual |
| 5 | Contém |
| 6 | Está na lista |
O formularioCampo precisa existir no Formulário do dashboard, e o widgetCampo precisa estar em campos do widget daquele item.
Arquivo de widget
{
"versao": 2,
"nome": "REC_EVOLUCAO_MENSAL",
"tipoWidget": 1,
"titulo": "Evolução Mensal das Receitas",
"exibirTitulo": "S",
"tamanhoFonteTitulo": 14,
"ehSistema": "N",
"expressaoSQL": "select ... from documentos a where ...",
"campos": [
{"nome": "ANO_MES", "tipoCampo": 1, "formato": "", "ehSistema": "N"},
{"nome": "DATAEMISSAO", "tipoCampo": 2, "formato": "", "ehSistema": "N"},
{"nome": "VALOR", "tipoCampo": 3, "formato": "###,##0.00", "ehSistema": "N"}
],
"grafico": { }
}
| Campo | Regra |
|---|---|
| nome | Obrigatório. Chave de importação junto com o tipoWidget. |
| tipoWidget | 1 para gráfico (preenche a seção grafico) ou 2 para indicador (preenche a seção indicador). |
| expressaoSQL | Obrigatória e crua: sem soma, sem agrupamento e sem ordenação. A agregação é montada pelo sistema a partir do campoX, do campoSerie e das colunas. |
| campos | Catálogo das colunas devolvidas pela consulta. Ao menos um, sem nomes repetidos. Todo campo citado em campoX, campoSerie, campoOrdenacao, colunas, indicador e nos filtros precisa estar aqui. |
| campos.tipoCampo | 1 texto, 2 data, 3 valor. |
| campos.formato | Máscara de exibição, como ###,##0.00. É ela que formata o rótulo do gráfico e o número do indicador. |
Seção grafico
"grafico": {
"tipoGrafico": "BH",
"campoX": "ANO_MES",
"campoSerie": "",
"campoOrdenacao": "ANO_MES",
"tipoSerie": "",
"exibirValores": "S",
"escala": 0,
"destacarDiferenca": "N",
"tamanhoFonteX": 13,
"posicaoLegenda": "D",
"corBarra": "#3E3E3E",
"corFundoBarra": "#FBF1E6",
"exibirFundoBarra": "S",
"arredondamentoInicial": "S",
"arredondamentoFinal": "S",
"arredondamentoFundoInicial": "N",
"arredondamentoFundoFinal": "S",
"colunas": [
{"sequencia": 1, "legenda": "Valor", "campoValor": "VALOR",
"corFonteValor": "", "corFonteValor2": "#FFFFFF", "exibirPercentual": "N"}
]
}
| Campo | Regra |
|---|---|
| tipoGrafico | BH para colunas verticais, BV para barras horizontais, LI para linhas e PI para pizza. |
| campoX | Obrigatório. É a categoria do eixo. |
| campoSerie | Usado apenas com tipoSerie D: cada valor distinto do campo vira uma série. |
| campoOrdenacao | Ordena as categorias por este campo, em vez da ordem alfabética. |
| tipoSerie | D para série dinâmica, que exige o campoSerie. Em branco, as séries são as informadas em colunas. |
| exibirValores | S mostra o valor em cada ponto, E mostra a escala no eixo e N não mostra nenhum. |
| posicaoLegenda | T, B, E, D ou I. Somente o gráfico de pizza desenha legenda. |
| colunas | Ao menos uma série. A sequencia é maior que zero e única, e o campoValor é obrigatório e precisa ser um campo do tipo valor. |
| colunas.exibirPercentual | S exibe o percentual sobre o total da série, em vez do valor. |
Seção indicador
"indicador": {
"campoValor": "VALOR",
"corFundo": "#D66815",
"corValor": "#FFFFFF",
"corDestaque": "#EFA55F",
"corIdentificacao": "#FFFFFF"
}
O campoValor é obrigatório, precisa estar em campos e ser do tipo valor — é o campo somado no cartão. O formato exibido vem do formato desse campo.
| Campo | Aplica-se a |
|---|---|
| corFundo | Fundo do cartão. |
| corValor | Número em destaque. |
| corIdentificacao | Rótulo acima do número. |
| corDestaque | Realce do cartão. |
O indicador sempre soma o campo escolhido. Média, contagem ou maior valor precisam vir resolvidos dentro da própria consulta — uma coluna 1 as quantidade, por exemplo, quando somada resulta na contagem de linhas.
Mensagens de erro
Quando o arquivo tem problemas, nada é importado e a mensagem traz todos de uma vez:
Não foi possível importar o dashboard. 3 problemas encontrados:
1) item 1 (widget "REC_EVOLUCAO_MENSAL"): "grafico.campoX" "ANOMES" não está
em "campos". Todo campo usado precisa estar catalogado lá.
2) item 2 (widget "REC_POR_CC"): "grafico.colunas[0].campoValor" "CENTROCUSTO"
precisa ser do tipo valor ("tipoCampo": 3) em "campos", e está como 1.
3) item 2 (widget "REC_POR_CC"): "sequencia" 1 já foi usada em outro item --
ela identifica o item no dashboard.
Conclusão
O formato descreve o dashboard por inteiro: itens, widgets, catálogo de Campos, séries de valor e filtros. Por ser texto estruturado com regras conhecidas e validação completa na importação, o mesmo arquivo pode ser gerado fora do sistema, revisado e aplicado em qualquer base.
Assuntos Relacionados
