Histórico da Página
...
CONTEÚDO
- Visão Geral
- Construindo uma API de negócio para uso nos Monitores
- Api de negócio
- Classes Utilitárias (FelicitadoresFalicitadores)
- Criando o seu primeiro monitor
01. VISÃO GERAL
Esse documento possui as informações necessárias para que uma pessoa com conhecimentos em programação na linguagem Progress 4GL possa desenvolver e integrar uma API específica para utilização no painel de Gestão à Vista. Serão detalhados os principais métodos, parâmetros e funções que deverão ser implementados na API para torná-la compatível com a aplicação.
02. CONSTRUINDO UMA API DE NEGÓCIO PARA USO NOS MONITORES EXCUSIVOS
Cada monitor exclusivo deve possuir em seu cadastro uma Api Progress informada. Essa Api deverá ser desenvolvida de forma específica para o Cliente e será responsável pelo retorno tanto das informações , como de como ela será apresentada na e o formato que elas serão apresentadas em tela para o usuário. Essa Essa Api será executada pelo Gestão à Vista automaticamente, portanto o desenvolvedor precisará se dedicar apenas em construir as procedures necessárias de acordo com as orientações desta documentação.
Antes de iniciar o desenvolvimento da API, verifique se o monitor foi corretamente cadastrado no painel de Monitores Exclusivos e já possui todas as suas propriedades (filtros) bem definidas.
03.
...
API DE NEGÓCIO
Para o funcionamento correto do monitor, é necessário que a Api de negócio possua os seguintes métodos:
Nome | Descrição | Obrigatório |
---|---|---|
Realiza a busca dos dados que serão visualizados nos monitores de Gráfico, como os categorias, séries e valores para os gráficos. | Somente p/ tipo Gráfico ou Gauge | |
Realiza a busca dos dados que serão visualizados no monitor de Informação, como tags, linhas, barra de progresso e valores. | Somente p/ tipo Texto | |
Realiza a busca dos dados de detalhes de um monitor (Para apresentação em formato de tabela em uma janela ao detalhar as informações) | Não |
04.
...
CLASSES UTILITÁRIAS (
...
FACILITADORES)
Nome | Descrição |
---|
pi-get-monitor-data-chart
pi-get-monitor-data-info
pi-get-monitor-detail
02.A.1 Monitor tipo INFO
Esse tipo de monitor é bastante flexível, permitindo criar layouts diferenciados conforme necessário. Ele é formado por linhas, cuja aparência, altura, largura e conteúdo mudam conforme o retorno da API. É possível customizar cada uma dessas linhas com classes e estilos nativos do HTML, além de ícones do PO-UI. Se o monitor que você está planejando construir for do tipo INFO (texto), confira as informações abaixo:
Estrutura geral
Obs: As linhas seguem o grid system do PO-UI. Veja mais em https://po-ui.io/guides/grid-system
Implementação
A Procedure pi-get-monitor-data-info deve ser implementada pela API de negócio e deverá retornar um objeto JSON estruturado, ou a tabela RowErrors, caso tenha ocorrido algum erro. É passada como Input a ttVisaoMonitor que contém as informações de qual monitor está sendo processado nesse momento.
Informações | ||
---|---|---|
| ||
Certifique-se que os nomes das Procedures estejam exatamente iguais ao que consta na documentação (pi-get-monitor-data-info e/ou pi-get-monitor-data-chart), caso contrário o painel de Gestão à vista irá emitir um erro e os dados não serão carregados. |
Bloco de código | ||||
---|---|---|---|---|
| ||||
PROCEDURE pi-get-monitor-data-info:
DEFINE INPUT PARAMETER TABLE FOR ttVisaoMonitor.
DEFINE OUTPUT PARAMETER oOutput AS JsonObject.
DEFINE OUTPUT PARAMETER TABLE FOR RowErrors. |
O objeto JSON será construído através da classe utilitária InfoBuilder, que utiliza as seguintes temp-tables:
ttMonitorMetadados (opcional)
Guarda algumas configurações básicas que o monitor irá assumir, como alturas máximas e mínimas e cores do título e do widget principal. Se não forem definidas, serão utilizadas configurações padrões.
...
ttMonitorInfoLinha
Contém as linhas que formarão os dados do monitor. Cada registro da temp-table representa uma linha na aplicação, que será convertida em uma DIV no HTML. É possível customizar cada linha com classes e estilos HTML, além de ícones do PO-UI. Utilizando as classes do grid system do PO-UI, podemos montar um layout bastante flexível para o monitor.
...
ttTags(opcional)
Temp-table com as definições das PO-TAGS que serão exibidas abaixo do título do monitor.
...
Depois de criar os registros necessários nas temp-tables, a API deverá passá-las como parâmetro para o InfoBuilder para que o monitor seja criado, conforme exemplo:
Bloco de código | ||
---|---|---|
| ||
USING cdp.services.gestaoavista.*. //A classe InfoBuilder está definida aqui.
DEFINE VARIABLE InfoBuilder AS InfoBuilder NO-UNDO.
InfoBuilder = NEW InfoBuilder(INPUT TABLE ttVisaoMonitor).
// Setamos as tags, parâmetros e linhas que irão compor o monitor
InfoBuilder:setTags(INPUT TABLE ttTags).
InfoBuilder:setParameters(INPUT TABLE ttMonitorMetadados).
InfoBuilder:setLines(INPUT TABLE ttMonitorInfoLinha).
oOutput = NEW JsonObject().
oOutput = InfoBuilder:createMonitor(). // Chama o método que cria e devolve o monitor pronto
DELETE OBJECT InfoBuilder. |
Exemplo de retorno
Depois que a API de negócio chama o método createMonitor da classe InfoBuilder e o método pi-get-monitor-data-info finaliza sua execução, os dados serão enviá-los para o painel de monitoramento para visualização.
Bloco de código | ||
---|---|---|
| ||
Exemplo de JSON de retorno para um monitor do tipo INFO.
{
"alturaMaximaWidget": null,
"alturaMinimaWidget": null,
"corFundo": "#26BA41",
"corFundoPreenchidoProgresso": "#004e17",
"corFundoProgresso": "#FFFFFF",
"corTextoProgresso": "#FFFFFF",
"corTitulo": "#FFFFFF",
"linhas": [
{
"classeTexto": "po-font-title po-text-center po-sm-12 po-p-1 bold-text",
"icone": "po-icon-manufacture",
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Produzindo",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0 po-pt-1 po-clickable",
"icone": null,
"parametrosDetalhe": "detalhaOrdem:1003",
"styleTexto": "{\"color\":\"white\"}",
"texto": "Ordem <b> 1.003</b> <span class=\"po-icon po-icon-export\"></span>",
"tipo": null,
"tipoDetalhe": "externo",
"tituloProgresso": null,
"urlDetalhe": "html.productionOrder",
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0 no-overflow",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Item <b>sp-item-a</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Operação <b>10 - montar</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-font-text-large po-sm-12 po-p-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": "{\"color\":\"white\"}",
"texto": "Split <b>1</b>",
"tipo": null,
"tipoDetalhe": null,
"tituloProgresso": null,
"urlDetalhe": null,
"valorProgresso": null
},
{
"classeTexto": "po-sm-12 po-pr-1 po-pt-1 po-pl-0",
"icone": null,
"parametrosDetalhe": null,
"styleTexto": null,
"texto": null,
"tipo": "progresso",
"tipoDetalhe": null,
"tituloProgresso": "% Conclusão: 50%",
"urlDetalhe": null,
"valorProgresso": 50
}
],
"tags": [
{
"colorTexto": "white",
"icone": "po-icon-manufacture",
"texto": "CT-SAME"
}
]
} |
Resultado:
02.A.2 Monitor tipo Gráfico (chart)
O monitor do tipo gráfico apresenta as informações de uma maneira visual, através do componente PO-CHART. Dependendo do monitor, podem ser utilizados os tipos Barra, Coluna, Pizza, Linhas ou Rosca. Os tipos de gráficos disponíveis dependem totalmente da API de negócio, portanto fica a cargo do programador prepará-la para suportar um ou mais tipos.
Estrutura geral
A API de negócio precisará implementar o método pi-get-monitor-data-chart que, da mesma forma que ocorre com o monitor do tipo Texto, irá devolver o JSON de retorno com o gráfico já estruturado. Esse objeto terá as mesmas propriedades de um PO-CHART (categorias e series), além das tags.
Bloco de código | ||||
---|---|---|---|---|
| ||||
PROCEDURE pi-get-monitor-data-chart:
DEFINE INPUT PARAMETER TABLE FOR ttVisaoMonitor.
DEFINE OUTPUT PARAMETER oOutput AS JsonObject.
DEFINE OUTPUT PARAMETER TABLE FOR RowErrors. |
O objeto JSON será construído através da classe utilitária ChartBuilder, que utiliza as seguintes temp-tables:
ttTags(opcional)
Temp-table com as definições das PO-TAGS que serão exibidas abaixo do título do monitor.
...
Propriedade na temp-table
...
Descrição
...
SERIALIZE-NAME (JSON)
...
ttCategorias
Define os nomes das categorias que serão plotadas no eixo X do gráfico caso seja do tipo colunas, ou então nos eixos Y do grid de gráficos dos tipos barras e linhas. Para maiores informações, consulte a documentação da propriedade categories do PO-CHART.
...
Propriedade na temp-table
...
Descrição
...
ttSeries
São os objetos de série do gráfico, que representam as colunas/fatias/linhas, conforme o tipo de gráfico. Possui as mesmas propriedades do objeto Series do PO-CHART.
...
Altura (opcional)
Altura que o gráfico terá dentro do widget. Para atribuir a altura, utilize o método setHeight() do ChartBuilder.
Depois de criar as temp-tables necessárias na aplicação, utilizamos a classe ChartBuilder para gerar o gráfico, conforme abaixo:
Bloco de código | ||
---|---|---|
| ||
USING cdp.services.gestaoavista.*. //A classe ChartBuilder está definida aqui.
DEFINE VARIABLE ChartBuilder AS ChartBuilder NO-UNDO.
// Instanciar a classe passando como parâmetro a ttVisaoMonitor, que contém as informações do monitor e visão que estão sendo processados nesse instante
ChartBuilder = NEW ChartBuilder(INPUT TABLE ttVisaoMonitor).
/* Depois que todas as entidades estão criadas, basta setá-las no objeto ChartBuilder */
ChartBuilder:setTags(INPUT TABLE ttTags).
ChartBuilder:setSeries(INPUT TABLE ttSeries).
ChartBuilder:setCategories(INPUT TABLE ttCategorias).
ChartBuilder:setHeight(290).
/* Chama o método para criar e devolver o gráfico completo e guarda o resultado na variável oOutput */
oOutput = ChartBuilder:createChart().
DELETE OBJECT ChartBuilder. |
Bloco de código | ||||
---|---|---|---|---|
| ||||
Exemplo de JSON para monitor do tipo Gráfico de Pizza
{
"altura": 290,
"categorias": [
"Estados dos CTs"
],
"series": [
{
"color": "#F50031",
"data": 1.0,
"label": "Parado",
"tooltip": "",
"type": "pie"
},
{
"color": "#26BA41",
"data": 2.0,
"label": "Produzindo",
"tooltip": "",
"type": "pie"
},
{
"color": "#007acc",
"data": 1,
"label": "Setup",
"tooltip": "",
"type": "pie"
},
{
"color": "#A0B9BF",
"data": 3.0,
"label": "Ocioso",
"tooltip": "",
"type": "pie"
}
],
"tags": [
{
"colorTexto": "",
"icone": "po-icon-pin",
"texto": "Área: 002"
},
{
"colorTexto": "",
"icone": "po-icon-manufacture",
"texto": "Produzido: 8,0000 "
},
{
"colorTexto": "",
"icone": "po-icon-document-filled",
"texto": "Previsto: 220,0000 "
},
{
"colorTexto": "",
"icone": "po-icon-minus-circle",
"texto": "Refugado: 2,0000"
}
]
} |
Resultado
02.B Endpoint api/cdp/v1/monitor/details
Endpoint que é chamado ao clicar na opção Detalhar localizada no drop-down (ícone ... ) ou sobre alguma Série do po-chart em monitores gráficos. Será utilizado quando o monitor possuir tipo de detalhe definido como modal ou detalhe.
O tipo de detalhe modal irá exibir uma janela simples, ocupando apenas parte da tela e sobrepondo o próprio monitor. O tipo detalhe irá navegar para uma nova página dentro do portal de monitoramento, com uma área maior para utilização. Ambos os tipos possuem a mesma estrutura geral, que é:
A API de negócio cadastrada para o monitor deverá possuir um método chamado pi-get-monitor-detail que precisará retornar a estrutura do detalhe. Ela receberá os seguintes parâmetros:
Bloco de código | ||
---|---|---|
| ||
PROCEDURE pi-get-monitor-detail:
DEFINE INPUT PARAM TABLE FOR ttVisaoMonitor.
DEFINE INPUT PARAM iPage AS INTEGER NO-UNDO.
DEFINE INPUT PARAM cSerie AS CHARACTER NO-UNDO.
DEFINE INPUT PARAM cCategory AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAM aItems AS JsonArray NO-UNDO.
DEFINE OUTPUT PARAM lHasNext AS LOGICAL NO-UNDO.
DEFINE OUTPUT PARAM lCanExportXLS AS LOGICAL INITIAL YES NO-UNDO.
DEFINE OUTPUT PARAM cModalMaxWidth AS CHARACTER INITIAL "1440px" NO-UNDO.
DEFINE OUTPUT PARAM TABLE FOR ttColunaDetalhe.
DEFINE OUTPUT PARAM TABLE FOR ttHeadersDetalhe.
DEFINE OUTPUT PARAM TABLE FOR ttMonitorTag.
DEFINE OUTPUT PARAM TABLE FOR RowErrors. |
Parâmetros de entrada
ttVisaoMonitor
Tabela utilizada em várias procedures para identificar qual monitor está sendo processado no momento e que contém os metadados e configurações dele. Se a API de negócio for responsável por mais de um monitor, essa temp-table pode ser usada para redirecionar para os métodos corretos.
...
Utilitário para auxiliar na criação de monitores do tipo Gráficos. | |
Utilitário para auxiliar na criação de monitores do tipo Texto. | |
Utilitário para auxiliar na criação de monitores do tipo Gauge (velocímetro). | |
Utilitário para auxiliar na criação de interfaces de detalhamento dos dados de um monitor. |
05. CRIANDO SEU PRIMEIRO MONITOR
Crie o seu primeiro monitor seguindo este guia de passo a passo: 1. Criando seu primeiro Monitor Exclusivo (Getting Started)
...
iPage
Número da página atual para ser utilizada na paginação da query. Sempre que o usuário clicar em Exibir mais resultados na modal ou página de detalhe genérica, esse número será incrementado em 1.
cSerie
Se o usuário clicar sobre uma série do po-chart de um monitor do tipo gráfico, essa variável conterá o nome dessa série. Ela pode ser usada para aplicar um filtro na query para que sejam exibidos apenas os dados referentes à série na modal/página de detalhe.
cCategory
Se o monitor for do tipo Chart e possuir uma categoria, será passada através dessa variável.
Parâmetros de sáida
aItems
Array com os objetos de negócio que serão exibidos na tabela, que segue a mesma lógica dos itens da PO-TABLE. As propriedades de cada objeto devem bater com a definição de colunas existentes na propriedade Columns.
lHasNext
Utilizado para paginação. Caso o valor dessa propriedade seja True, o botão Buscar mais resultados ficará habilitado, tanto na modal quanto na tela de detalhe genérico.
lCanExportXLS (opcional)
Determina se o botão de Exportar para Planilha ficará habilitado na modal ou tela genérica de detalhe. A exportação é dinâmica e irá gerar um arquivo .csv com as definições de colunas e dados conforme o objeto retornado automaticamente.
cModalMaxWidth (opcional)
Se o detalhamento for via modal, essa propriedade define o tamanho máximo que ela poderá assumir na tela.
ttColunaDetalhe
Temp-table que herda a estrutura do PoTableColumn(https://po-ui.io/documentation/po-table)
e possui algumas propriedades adicionais, que servirão para aplicar a técnica de detalhamento de uma coluna da tabela (opcional). Ao clicar sobre uma coluna que possui detalhamento, será aberta uma tela HTML externa, que deverá estar preparada para verificar a LocalStorage do navegador e capturar os parâmetros que serão inclusos pelo painel de Monitoramento.
...
ttHeadersDetalhe (opcional)
Temp-table contendo registros que serão renderizados no cabeçalho da Modal ou na tela de detalhe genérico na forma de um quadrado que pode ser estilizado através dos campos classe-header e estilo-header. Útil para criar um “cabeçalho” para contextualizar as informações que estão contidas na tabela.
...
ttMonitorTag (opcional)
Temp-table contendo registros que se tornarão PO-TAGS, que pode ser usado para exibir dados importantes e concisos de forma compacta. As tags ficarão abaixo dos headers, se existirem.
...
Depois que a API de negócio retornar as temp-tables detalhadas acima, elas serão convertidas num JSON com o seguinte formato:
Bloco de código |
---|
Query params:
codMonitor=<monitor>&codVisao=<visao>&sequencia=<seq>&pagina=1
&tipo=<tipo>&subtipo=<sub>&serie=<serie>
Estrutura do JSON
{
"canExportXLS": true,
"columns": [
{
"detailUrl": "string (opcional)",
"format": "string (opcional)",
"label": "string",
"property": "string",
"type": "string (opcional)",
"width": "string (opcional)",
"parameterLabels": [
"string (opcional)"
],
"parameterProperty": [
"string (opcional)"
],
}
],
"items": [
{
<Objeto de negócio>
}
],
"headers": [
{
"headerText":"string (opcional)",
"headerClass":"string (opcional)",
"headerStyle":"string (opcional)"
}
],
"tags": [
{
"colorTexto": "string (opcional)",
"icone": "string (opcional)",
"texto": "string (opcional)"
}
],
"modalMaxWidth": "string",
"hasNext": boolean,
} |
Bloco de código |
---|
Exemplo detalhamento via Modal com coluna detalhe externo
{
"columns": [
{
"label": "Ordem",
"property": "productionOrderNumber",
"type": "cellTemplate",
"detailUrl": "html.productionOrder",
"format": null,
"parameterLabels": [
"detalhaOP"
],
"parameterProperty": [
"productionOrderNumber"
],
},
{
"label": "Item",
"property": "itemCode",
"type": null,
"format": null
}
[...]
],
"items": [
{
"itemCode": "me2017a",
"productionOrderNumber": "1035"
[...]
}
],
"tags": [
{
"colorTexto": null,
"icone": null,
"texto": "GGF sem ACA"
}
],
"hasNext": false,
"modalMaxWidth": "1440px",
} |
Resultado:
Repare que o campo Ordem está destacado. Isso acontece quando a coluna correspondente à informação possui o tipo cellTemplate, e indica que o campo é clicável. Caso o usuário clique em alguma ordem, o sistema irá incluir novas entradas no LocalStorage do navegador, com chave:valor conforme as propriedades parameterLabels e parameterProperty da coluna.
Utilizando o exemplo acima, considerando que o usuário clicou na ordem 1051 ficaria:
Bloco de código |
---|
{
"detalhaOP": "1051"
} |
São suportados até 10 parâmetros pra cada coluna. Dessa forma, quando a tela externa for chamada, poderá buscar na localStorage pelos parâmetros e posicionar na listagem/detalhe o registro que foi clicado. Deve-se atentar para que cada chave:valor fique na mesma posição de index em seus respectivos arrays.
Bloco de código |
---|
Exemplo detalhamento via Detalhe genérico
{
"items": [
{
"H6_FILIAL": "01",
"H6_OP": " ",
"H6_PRODUTO": "MOD000000001 ",
"B1_DESC": "MOD000000001 ",
"H6_OPERAC": " ",
"G2_DESCRI": "",
"H6_RECURSO": "000001",
"H1_DESCRI": "RECURSO 000001",
"H6_DTAPONT": "2023-03-29",
"H6_DATAINI": "2023-03-29",
"H6_HORAINI": "10:00",
"H6_DATAFIN": "2023-03-29",
"H6_HORAFIN": "10:30",
"H6_TEMPO": "0.5",
"H6_QTDPROD": 0,
"H6_QTDPERD": 0.5,
"H6_TIPO": "I"
},
{ ...demais itens... }
],
"columns": [
{
"property": "H6_FILIAL",
"label": "Filial",
"type": "string",
"visible": false
},
{
"property": "H6_TIPO",
"label": "Tp Apon",
"type": "cellTemplate",
"labels": [
{
"value": "I",
"color": "rgb(241,143,136)",
"label": "Improdutivo",
"textColor": "rgb(255,255,255)"
},
{
"value": "P",
"color": "rgb(126,226,148)",
"label": "Produtivo",
"textColor": "rgb(255,255,255)"
}
],
"visible": true
},
{
"property": "H6_RECURSO",
"label": "Recurso",
"type": "string",
"visible": true
},
{
"property": "H1_DESCRI",
"label": "Desc Recurso",
"type": "string",
"visible": false
},
{
"property": "H6_OP",
"label": "OP",
"type": "string",
"visible": true
},
{
"property": "H6_PRODUTO",
"label": "Produto",
"type": "string",
"visible": true
},
{
"property": "B1_DESC",
"label": "Desc Produto",
"type": "string",
"visible": false
},
{
"property": "H6_OPERAC",
"label": "Operação",
"type": "string",
"visible": true
},
{
"property": "G2_DESCRI",
"label": "Desc Oper",
"type": "string",
"visible": false
},
{
"property": "H6_TEMPO",
"label": "Tempo",
"type": "string",
"visible": true
},
{
"property": "H6_DTAPONT",
"label": "Dt Apont",
"type": "date",
"visible": false
},
{
"property": "H6_DATAINI",
"label": "Dt Ini",
"type": "date",
"visible": true
},
{
"property": "H6_HORAINI",
"label": "Hora Ini",
"type": "string",
"visible": false
},
{
"property": "H6_DATAFIN",
"label": "Dt Fin",
"type": "date",
"visible": false
},
{
"property": "H6_HORAFIN",
"label": "Hora Fin",
"type": "string",
"visible": false
},
{
"property": "H6_QTDPROD",
"label": "Qtd Prod",
"type": "number",
"visible": false
},
{
"property": "H6_QTDPERD",
"label": "Qtd Perda",
"type": "number",
"visible": false
}
],
"canExportCSV": true,
"tags": [
{
"icone": "po-icon-calendar",
"texto": "12/02/23 - 02/06/23",
"colorTexto": ""
},
{
"icone": "po-icon-calculator",
"texto": "Semanal",
"colorTexto": ""
},
{
"icone": "po-icon-star-filled",
"texto": "Tempo Prod. Total: 31.58 Horas",
"colorTexto": ""
}
],
"hasNext": true
} |
Resultado:
03. TELA XXXXX
Outras Ações / Ações relacionadas
...
04. TELA XXXXX
Principais Campos e Parâmetros
...
Card documentos | ||||
---|---|---|---|---|
|
...