Histórico da Página
CONTEÚDO
- Visão Geral
- Construindo uma API de negócio para uso nos Monitores
- Tela XXX
- Outras Ações / Ações relacionadas
- Outras Ações / Ações relacionadas
- Tela XXX
- Principais Campos e Parâmetros
- Principais Campos e Parâmetros
- Tabelas utilizadas
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
Cada monitor possui em seu cadastro de metadados uma API Progress vinculada. Essa API será responsável pela busca dos dados e processamento das informações que serão exibidas no painel. A API será executada pelo Gestão à Vista de forma transparente e automática, portanto o desenvolvedor só precisa se preocupar em implementar os métodos necessários seguindo as diretrizes deste documento e a integração irá funcionar. Antes de iniciar o desenvolvimento da API, verifique se o monitor foi corretamente cadastrado e já possui todas as suas propriedades bem definidas.
MÉTODOS PRINCIPAIS
O painel de Gestão à Vista possui dois endpoints principais: api/cdp/v1/monitor/monitorDataSchema e cdp/v1/monitor/details. Ambos estão localizados na API cdp/api/v1/monitor.p e são chamados durante a atualização dos dados dos monitores e o detalhamento de suas informações, respectivamente.
Esses endpoints irão chamar certas procedures na API de negócio que está cadastrada na tabela Monitor, campo api-negocio, do monitor em questão para que ela retorne os dados necessários para a apresentação.
02.A Endpoint api/cdp/v1/monitor/monitorDataSchema
Esse endpoint é responsável por buscar as informações que serão exibidas no monitor, assim como o layout no caso dos monitores do tipo Texto (Info). Ele chama os métodos pi-get-monitor-data-info
ou pi-get-monitor-data-chart
, dependendo se o monitor é do tipo "Info" (texto) ou "Gráfico". Portanto, a API de negócio cadastrada para o monitor deve implementá-los conforme necessário.
O retorno esperado da API muda conforme o tipo do monitor.
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 implementado pela API de negócio e deverá retornar as TEMP-TABLES ttMonitorMetadados, ttMonitorInfoLinha e ttMonitorTag, além da RowErrors. A definição das três primeiras pode ser consultada na include apiMonitorV1.i. É passada como Input a ttVisaoMonitor que contém as informações de qual monitor está sendo processado nesse momento.
...
Essas temp-tables serão incorporadas automaticamente no JSON de retorno da aplicação, sendo que os nomes dos campos serão substituídos pelo SERIALIZE-NAME conforme tabelas abaixo.
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.
...
Propriedade na temp-table | Descrição | SERIALIZE-NAME (JSON) |
---|---|---|
cor-fundo (opcional) | Cor de fundo do widget do monitor. Aceita tanto o nome direto da cor, por exemplo “red”, quanto o código hash: #FFFFF. Cor padrão branco. | corFundo |
cor-titulo (opcional) | Cor que o título do monitor irá assumir. Cor padrão preto. | corTitulo |
cor-texto-progresso (opcional) | Se o monitor tiver uma linha com tipo “progresso”, será criado um PO-PROGRESS. Essa propriedade define a cor do texto desse componente. Cor padrão preto. | corTextoProgresso |
cor-fundo-progresso (opcional) | Cor de fundo do PO-PROGRESS, se existir. Cor padrão azul claro. | corFundoProgresso |
cor-fundo-preenchido-progresso (opcional) | Cor da barra de progresso do PO-PROGRESS. Cor padrão azul escuro. | corFundoPreenchidoProgresso |
altura-minima-widget (opcional) | Define a altura mínima do monitor. Por padrão, os monitores trabalham com alturas fixas de 350px. | alturaMinimaWidget |
altura-maxima-widget (opcional) | Define a altura máxima do monitor. Padrão 350px. | alturaMaximaWidget |
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.
...
Propriedade na temp-table | Descrição | SERIALIZE-NAME (JSON) |
---|---|---|
tipo (opcional) | Serve para definir se a linha é do tipo texto ou progresso. Algumas propriedades serão ignoradas caso o tipo da linha não seja compatível. Se não for informado, será considerado o tipo texto. | tipo |
texto | Conteúdo a ser apresentado na linha com tipo texto. | texto |
style-texto (opcional) | Permite informar os styles do HTML que serão atribuídos à linha com tipo texto. | styleTexto |
classe-texto (opcional) | Classe da linha, podendo ser qualquer classe existente no HTML padrão ou PO-UI (somente linha texto) | classeTexto |
icone (opcional) | Ícone do PO-UI que será exibido no início da linha (somente linha texto). | icone |
titulo-progresso (opcional) | Se a linha for do tipo progresso, esse será o título (label) do PO-PROGRESS. | tituloProgresso |
valor-progresso (opcional) | Valor atual do PO-PROGRESS. | valorProgresso |
url-detalhe (opcional) | Nome da tela HTML que servirá para detalhar a linha clicada. Deve ser usado com tipo-detalhe igual à externo. | urlDetalhe |
tipo-detalhe (opcional) | Aceita os tipos: “modal”, “detalhe” e “externo”. Define se o detalhe aberto ao clicar na linha será uma modal, página genérica de detalhe ou um programa HTML externo. | tipoDetalhe |
parametros-detalhe (opcional) | String com os parâmetros que serão passados para a modal/página/programa externo quando for acionado o detalhe. O formato deve ser chave:valor separados por “;”. Exemplo: ”detalhaOrdem: 1001;codEstabel: ‘MBS’” | parametrosDetalhe |
ttMonitorTag (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) |
---|---|---|
texto | Texto a ser exibido na tag | texto |
cor-texto (opcional) | Cor da tag. Aceita os padrões do PO-UI, como “color-01”, o nome da cor (blue, red) ou o código hexadecimal. | colorTexto |
icone (opcional) | Aceita os ícones conforme https://po-ui.io/guides/icons. | icone |
Exemplo de retorno
Depois que a API de negócio cria os registros necessários nas temp-tables citadas acima e o método pi-get-monitor-data-info finaliza sua execução, a cdp/api/v1/monitor.p se encarregará de transformar esses dados em formato JSON para 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:
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, ao contrário do monitor do tipo Texto que trabalha com temp-tables, precisará devolver o JSON de retorno diretamente. Esse objeto terá as mesmas propriedades de um PO-CHART (categorias e series), além das tags.
...
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": 4.0, "label": "Produzindo", "tooltip": "", "type": "pie" }, { "color": "#007acc", "data": 0.0, "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: 58,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.
...
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.
...
Propriedade | Descrição |
---|---|
cod-monitor | Código do monitor que está sendo processado. |
cod-visao | Código da Visão onde o monitor está incluso. |
posicao | Posição do monitor dentro da visão. |
sequencia | Campo de Sequência, utilizado para diferenciar monitores iguais dentro da mesma visão. |
subtipo | Se o monitor for do tipo gráfico, esse campo irá identificar qual subtipo (pizza, barra, colunas, rosca, linhas) está parametrizado para este monitor. |
opcoesSubtipo | Determina quais subtipos de gráfico podem ser selecionados para este monitor. |
tamanho | Tamanho (largura) definida para o monitor pelo usuário. Valores de 1 a 12. |
opcoesTipo | Lista quais tipos, sendo Texto (info) e Gráfico (chart) que o monitor pode assumir. |
tipo | É o tipo atual selecionado para o monitor, podendo ser info ou chart. |
titulo | Título do monitor. |
tipo-detalhe | Determina qual tipo de detalhamento será usado pelo monitor, podendo ser modal, externo ou detalhe (tela genérica). |
url-detalhe | Se o tipo de detalhe for externo, esse campo indica qual o nome do programa HTML que será chamado ao detalhar o monitor. |
atualiza-automatico | Determina se o monitor deve atualizar automaticamente os dados sempre que o tempo de atualização definido passar. |
tempo-atualizacao | Tempo definido pelo usuário para atualização automática do monitor. |
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.
...
Propriedade | Descrição |
---|---|
cod-label | Nome que será exibido na coluna. |
propriedade | Nome da propriedade que será exibida nessa coluna. Ela deverá existir dentro dos objetos passados no array aItems. |
tipo (opcional) | Tipo da coluna. Verificar documentação do PO-UI para maiores informações. Padrão será texto. |
formato (opcional) | Formato (máscara) que o campo deverá assumir. |
url-detalhe (opcional) | Contém o endereço de um programa HTML que será chamado ao clicar sobre essa coluna. Precisa ser utilizada em conjunto com as propriedades parameterLabels, parameterProperty e o format da coluna precisa ser cellTemplate. |
label-parametros (opcional) | Array de strings que contém os nomes das propriedades que serão inclusas no LocalStorage do navegador quando o usuário clicar numa coluna que possui url-detalhe informado. |
propriedade-parametros (opcional) | Array de strings que determina qual campo será usado como base para o valor do parâmetro que será incluso no LocalStorage. |
largura (opcional) | Largura que a coluna irá assumir na tabela. |
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.
...
Propriedade | Descrição |
---|---|
classe-header | Classes HTML que serão atribuídas ao elemento. Aceita as classes do PO-UI, por exemplo po-p-1, po-font-text-center etc. |
estilo-header | Estilo HTML que será atribuído ao objeto. Usar a sintaxe padrão do HTML, ex: background-color: red;text-align: center; |
texto-header | Texto que será exibido dentro do quadrado. |
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.
...
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
Ação | Descrição |
---|---|
04. TELA XXXXX
Principais Campos e Parâmetros
...
Card documentos | ||||
---|---|---|---|---|
|