app-dashboard

Tipo

Referência

Para

Desenvolvedor, Analista

app-dashboard é o formato de cada Dashboard da Aplicação. Ele não tem arquivo próprio: cada Dashboard é um item da lista dashboards: no arquivo da Aplicação, com um header e um body. O que é um Dashboard e como os Widgets se configuram está em Widgets e opções comuns de Widget.

Campos

A tabela descreve o Dashboard isolado. No arquivo da Aplicação, o header leva só o id: appId, tenantId, kind e lumo vêm do cabeçalho da Aplicação no push.

• fileName
  string · opcional · valores: regex ^[a-z0-9-]+--\d+\.yaml$
• header
  object · obrigatório
• header.id
  integer · obrigatório · valores: ≥ 0
  A dashboard header id. 0 means "create a new dashboard" on push; a positive value addresses an existing one. Kept separate from #/$defs/id (minimum 1) because 0 is a valid, meaningful value here and nowhere else.
• header.kind
  string · obrigatório · valores: app-dashboard (fixo)
• header.lumo
  string · obrigatório · valores: v2 (fixo)
• header.tenantId
  integer · obrigatório · valores: ≥ 1
• header.appId
  integer · obrigatório · valores: ≥ 1
• body
  object · obrigatório
• body.criado_em
  string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
  Somente leitura: o servidor preenche.
• body.criado_por
  string ou integer ou null · opcional
  Somente leitura: o servidor preenche.
• body.publicado_em
  string ou null · opcional · valores: regex ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$
  Somente leitura: o servidor preenche.
• body.publicado_por
  string ou integer ou null · opcional
  Somente leitura: o servidor preenche.
• body.nome
  string · obrigatório · valores: não vazio
• body.ordem
  integer · opcional · valores: ≥ 0
• body.widget_columns
  integer · opcional · valores: ≥ 1
• body.widget_float
  boolean · opcional
• body.version
  integer ou null · opcional · valores: ≥ 0
  Somente leitura: o servidor preenche. Server-managed resource version.
• body.filters
  array de object ou null · opcional
  Filtros de inicialização desta aba, só relevantes quando o app está em modo 'per_dashboard' (body.filter_mode do app). null (ou chave ausente) = aba nunca configurou filtro próprio - equivale a [] com allow_new_filters liberado, e é o que o CLI emite para toda aba que nunca usou o recurso (o hash de drift descarta chave null, então essa aba não muda de hash entre versões do CLI). Ver shared.schema.json#/$defs/filterDefinition para o contrato de cada item, inclusive value: false como campo declarado vazio.
• body.filters[].column
  object · obrigatório
• body.filters[].column.column_id
  string ou integer · obrigatório
  Normalmente inteiro; dado real em circulação às vezes serializa como string numérica (ex.: YAML pré-existente) - aceito nas duas formas.
• body.filters[].column.expression
  string ou null · opcional
• body.filters[].operator
  string ou null · opcional
• body.filters[].value
  qualquer valor · opcional
  false é o marcador de campo declarado vazio (vaga): a aba assume a coluna como filtrável mas sem valor próprio, e herda o que estava aplicado na aba anterior. Qualquer outro valor (inclusive array, para múltipla escolha) é o valor efetivamente aplicado.
• body.filters[].comparativeValues
  qualquer valor · opcional
• body.filters[].required
  integer ou null · opcional · valores: 0, 1, 2, 3
  0 = opcional, múltiplos valores (padrão). 1 = obrigatório, um ou mais valores. 2 = obrigatório, valor único. 3 = opcional, valor único.
• body.filters[].mergeStrategy
  string ou null · opcional
• body.allow_new_filters
  boolean ou null · opcional
  Se quem usa a aba pode adicionar filtro além da lista declarada em filters. null = herda o padrão (true); só false explícito bloqueia.
• body.widgets
  array de object · opcional
  Optional: an absent key means a brand-new, still-empty tab (the server defaults it to [] too). Create it, fill in widgets on a later push.
• body.widgets[].id
  integer · opcional · valores: ≥ 1
• body.widgets[].guid
  string · opcional · valores: não vazio
• body.widgets[].nome
  string · opcional
• body.widgets[].type
  string · obrigatório · valores: Kpi, Barline, Pie, Table, Matrix, ComposedMatrix, Map, Gauge, Punchcard, Sankey, Forecast, Calendar, ListBox, Text, Diagram, Svelte, ParametricSvelte, App
• body.widgets[].display_nome
  boolean · opcional
• body.widgets[].x
  number · obrigatório
• body.widgets[].y
  number · obrigatório
• body.widgets[].w
  number ou null · opcional · valores: > 0
• body.widgets[].h
  number ou null · opcional · valores: > 0
• body.widgets[].mobileY
  number · opcional
• body.widgets[].mobileH
  number · opcional · valores: > 0
• body.widgets[].mobileVisible
  boolean · opcional
• body.widgets[].chart
  object · opcional

Exemplo

Um item da lista dashboards: da Aplicação, com a indentação tirada. No arquivo, ele vem precedido de - sob dashboards:.

header:
  id: 9101                 # Dashboard que já existe: mantenha o id que veio do pull
                           # 0 = criar um Dashboard novo no próximo push
body:
  nome: Visão geral
  ordem: 0                 # ordem da aba: o menor vem primeiro
  widget_columns: 12       # grade de 12, 24, 36 ou 60 colunas
  widgets:
    - nome: Faturamento
      type: Kpi
      w: 3                 # largura, em colunas da grade
      h: 1
      x: 0
      y: 0
      chart:
        primaryData:
          dataSource: "70011:SUM"   # <id da coluna>:<agregação>, de lumo info app:<id> --full
          title:
            value: Faturamento
          filter: []

lumo scaffold widget <tipo> mostra a configuração de cada tipo de Widget (Kpi, Barline, Pie, Table, Matrix e os outros), comentada. Para conferir o resultado, lumo app dashboard-preview app:<id> devolve os dados de cada Widget e lumo app export app:<id> gera a imagem.

Limites

• O push substitui a lista inteira. Um Dashboard que está no servidor e falta em dashboards: é apagado. Um Dashboard reescrito sem o header.id é recriado com outro id, o que quebra lumo app export --dashboard <id> e as Apresentações que apontam para ele.
• A ordem das abas vem de ordem, não da posição no array.
• filters e allow_new_filters de cada Dashboard só valem quando a Aplicação tem filter_mode: per_dashboard.
• No Widget Kpi, o filtro fica em filter, no singular. filters não é lido.
• Uma aba sem widgets é válida: nasce vazia e recebe Widgets num push seguinte.
• Numa Aplicação publicada, mudar Widgets, nomes ou abas pede clone. Só filters e allow_new_filters de cada Dashboard passam direto.