Layout Importação Dashboards

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 do gráfico e a coluna da grade 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, totalizar	N
limiteLinhas da grade	0, que usa o limite padrão de 500 linhas.
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), 2 para indicador (preenche a seção indicador) ou 3 para grade (preenche a seção grade).
expressaoSQL	Obrigatória e crua: sem soma, sem agrupamento e sem ordenação. No gráfico e no indicador, a agregação é montada pelo sistema a partir do campoX, do campoSerie e das colunas; na grade, as linhas aparecem como vierem da consulta, sem agrupar.
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, o número do indicador e as colunas de valor da grade.

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.

Seção grade

Exibe as linhas da consulta numa tabela, com o mesmo visual da grade dos cadastros. Cada item de colunas é uma coluna da tabela, na ordem da sequencia.

"grade": {
  "campoOrdenacao": "CONTA",
  "limiteLinhas": 0,
  "colunas": [
    {"sequencia": 1, "legenda": "Conta", "campoValor": "CONTA",
     "corFonteValor": "", "corFonteValor2": "", "exibirPercentual": "N", "totalizar": "N"},
    {"sequencia": 2, "legenda": "Saldo", "campoValor": "SALDO",
     "corFonteValor": "#1D5FB4", "corFonteValor2": "#D1293D", "exibirPercentual": "N", "totalizar": "S"},
    {"sequencia": 3, "legenda": "Saldo previsto", "campoValor": "SALDOPREVISTO",
     "corFonteValor": "#1D5FB4", "corFonteValor2": "#D1293D", "exibirPercentual": "N", "totalizar": "S"}
  ]
}

Campo	Regra
campoOrdenacao	Ordem das linhas: crescente, ou decrescente quando o campo é do tipo valor. Em branco, mantém a ordem em que o banco devolver.
limiteLinhas	Máximo de linhas exibidas. Zero usa o limite padrão de 500. Passando do limite, a grade avisa que está mostrando só as primeiras.
colunas	Ao menos uma coluna. A sequencia é maior que zero e única, e o campoValor é obrigatório e pode ser de qualquer tipo: texto, data ou valor.
colunas.legenda	Título da coluna. Em branco, usa o nome do campo.
colunas.corFonteValor	Cor do texto da coluna. Em branco, usa a cor do tema.
colunas.corFonteValor2	Somente em coluna de valor: cor do valor negativo.
colunas.exibirPercentual	S exibe o percentual sobre o total da coluna, em vez do valor. Somente em campo do tipo valor.
colunas.totalizar	S soma a coluna no rodapé. Somente em campo do tipo valor. O total considera todas as linhas do filtro, mesmo as que passaram do limite.

As cores de barra e de fundo de barra das colunas não se aplicam à grade. Datas aparecem como dd/mm/aaaa, e valores numéricos com o formato do campo.

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. 4 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.
  4) item 3 (widget "TES_SALDO_CONTAS"): "grade.colunas[0]" usa "totalizar" ou
     "exibirPercentual" com o campo "CONTA", que não é do tipo valor ("tipoCampo": 3).

Conclusão

O formato descreve o dashboard por inteiro: itens, widgets, catálogo de Campos, séries de valor, colunas da grade 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

Dashboards

Widgets

Dashboards com IA