Função criada para execução dos relatórios do Smart View a partir do cadastro na tabela de De/Para ( FW_TREP_CONTROLLER )

Informações

title	Disponível

Disponível a partir da LIB Label 20230227

Informações

title	Logs

É possível ver os logs da função ligando a chave FwTraceLog=1 no INI do ambiente utilizado, para mais informações sobre a chave: Chaves para controle de logs

Índice

exclude	Índice

Pré-requisitos

Já ter feito a instalação e integração com o Smart View, mais informações nos links:

Instalação do Smart View

Requisitos Mínimos

Necessário utilizar o REST 2.0 - Entendendo as novidades do REST
Ter conhecimento da linguagem TL++ - Rest - Ambiente de compilação do TLPP
Cadastrar os relatórios na rotina de De/Para Protheus x Smart View - Amarração Protheus x Smart View
Ter compilados os arquivos .trp no RPO - Smart View - Importação Automática de Recursos

Padrão para nomenclatura dos arquivos .trp

Os arquivos .trp são os layouts exportados do Smart View e que servem para a Importação Automática de Recursos dentro do Protheus, esse processo é possível através da rotina Amarração Protheus x Smart View e utilizando a função totvs.framework.treports.callTReports.

Definimos um padrão de nomenclatura para esse arquivo para que possamos unificar recursos que utilizem o mesmo objeto de negócio, para que o usuário possa escolher diferentes recursos em uma única chamada de menu/rotina.

Irei exemplificar a nomenclatura de um layout de relatório abaixo:

framework.sv.framework.product.subtitle.rep.bra.trp

Onde:

framework: Nome da área/tribe responsável;
sv: Agrupador de inovação;
framework: Módulo Responsável;
product: Nome do ON;
subtitle: Nome complementar do ON (Ex: Analítico, Sintético...);
rep: Tipo de Layout (rep=Report/pv=Pivot Table/dg=Data Grid);
bra: País do ON;

Exemplo de como seria a nomenclatura de um layout de tabela dinâmica:

framework.sv.framework.product.default.pv.trp

Todos os complementos da nomenclatura são obrigatórios, com exceção do país do ON.

Se a nomenclatura do layout não tiver o país, como no exemplo acima, consideramos que esse layout é para todos os países.

Aviso

title	Arquivo .trp

Para criar o arquivo .trp deve ser seguido os passos demonstrados no gif abaixo:

Não deverão ser utilizados programas para compactar, podendo dar problemas na descompactação do arquivo.

Basta exportar o layout do Smart View e renomear de acordo com o padrão demonstrado acima e mudar a extensão para .trp

Função totvs.framework.treports.callTReports

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
cIdProt	caractere	X		Id do relatório que será impresso (relacionado ao nome do arquivo .trp)
cType	caractere	Apenas se for um recurso individual		Tipo de dado (report, pivot-table ou data-grid)
nPrintType	numérico	Apenas se for utilizada em job		Tipo do impressão (Arquivo=1, Email=2)
jPrintInfo	json	Apenas se for utilizada em job		Informações para a impressão do relatório
jParams	json	Se houver parâmetros no relatório		Parâmetros do relatório
lRunInJob	lógico		.T.	Indica se irá executar em job
lShowParams (Disponível a partir da LIB Label 20230807)	lógico		.T.	Indica se irá mostrar a tela de parâmetros (se for geração em job esse parâmetro sempre é .F.)
lWizard (Disponível a partir da LIB Label 20231009)	lógico		.F.	Indica se exibe o wizard de configuração do Smart View, caso o ambiente não esteja preparado
cError (Disponível a partir da LIB Label 20231009)	caractere			Indica o erro na execução [referência]

Informações

title	Parâmetros

Ao utilizar a geração em job o desenvolvedor deve ter conhecimento dos parâmetros cadastrados no Smart View, pois os mesmos serão enviados a partir do jParams

Propriedades do json jPrintInfo

É necessário o envio de algumas informações sobre a impressão a partir do jPrintInfo (4º parâmetro da função), sendo elas:

Opção 1 - Impressão em arquivo

Propriedades:

Propriedades	Default	Descrição
name	Nome do relatório na tabela (TR__IDREL) + Data/Hora	Nome do arquivo
extension	pdf	Extensão
path	\Spool\	Pasta onde será salvo

Opção 2 - Impressão por E-mail

Propriedades:

Propriedades	Obrigatório	Default	Descrição
to	X		Destinatário do E-mail
subject		Relatório Smart View	Assunto do E-mail
body		Descrição do relatório (TR__DESCRI)	Corpo do -email
name		Nome do relatório na tabela (TR__IDREL) + Data/Hora	Nome do arquivo
extension		pdf	Extensão
path		\Spool\	Pasta onde será salvo

Informações
Necessário ter configurado o SMTP para envio de e-mail - Configurar o SMTP para envio de relatórios por e-mail

Aviso

title	Extensões disponíveis

O tWebEngine possui uma proteção para não realizar download de arquivos maliciosos. Por padrão é possível realizar download de arquivos do Smart View com as seguintes extensões: pdf, xls, xlsx, rtf, docx, mht, html, txt, csv e png.

Caso seja necessário realizar o download de outras extensões deve ser realizado tratamento pelo ponto de entrada AddLexList (https://tdn.totvs.com/display/PROT/AdDLExList). Para utilizar este ponto de entrada é necessário o fonte FwDLExList.prw mais atual.

Unificando o Menu/Rotina com recursos diferentes

Informações

title	Disponibilidade

Funcionalidade disponível a partir da LIB Label 20231009

Com o padrão de nomenclatura definido acima, é possível unificar os recursos em apenas uma chamada, sendo:

Múltiplos Relatórios
Múltiplas Tabelas Dinâmicas
Múltiplas Visões de Dados

Para isso preciso ter os 4 .trp's compilados e com as nomenclaturas corretas, como no exemplo abaixo:

Relatório 1 - framework.sv.framework.product.synthetic.rep.bra.trp
Relatório 2 - framework.sv.framework.product.analytical.rep.bra.trp
Tabela Dinâmica - framework.sv.framework.product.default.pv.trp
Visão de Dados - framework.sv.framework.product.default.dg.trp

Para a chamada do recurso o ID enviado na função totvs.framework.treports.callTReports deverá ser o seguinte: framework.sv.framework.product (área responsável + agrupador + modulo + nome do ON) e não deve ser mandado o parâmetro que indica o tipo do recurso, já que o recurso deverá ser escolhido pelo usuário.

Exemplo completo com chamada de múltiplos recursos:

Bloco de código

title	Unificação do Menu
collapse	true

#include "protheus.ch"
#include "fwmvcdef.ch"

//-------------------------------------------------------------------
/*/{Protheus.doc} poc_mvc
Exemplo de um modelo e view baseado em uma unica tabela com chamada
de um relatório no treports pela função totvs.framework.treports.callTReports

@author  Vanessa Ruama
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
User Function poc_mvc()
    Local oBrowse As Object
	
	oBrowse := FWMBrowse():New()
	oBrowse:SetAlias('SC7')
	oBrowse:SetDescription('Pedido de Compras')
	oBrowse:Activate()
		
Return

//-------------------------------------------------------------------
/*/{Protheus.doc} MenuDef
Função para carregamento do menu.

@return aRotina, array, array com as opções de menu.

@author  Vanessa Ruama
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
Static Function MenuDef()
    Local aRotina As Array
    Local aMedicao As Array

    aRotina := {}
    aMedicao := {}

    ADD OPTION aRotina TITLE 'Visualizar'           ACTION 'VIEWDEF.poc_mvc' OPERATION 2 ACCESS 0
    ADD OPTION aRotina TITLE 'Incluir'              ACTION 'VIEWDEF.poc_mvc' OPERATION 3 ACCESS 0
    ADD OPTION aRotina TITLE 'Alterar'              ACTION 'VIEWDEF.poc_mvc' OPERATION 4 ACCESS 0
    ADD OPTION aRotina TITLE 'Excluir'              ACTION 'VIEWDEF.poc_mvc' OPERATION 5 ACCESS 0
    ADD OPTION aRotina TITLE 'Imprimir Multi'       ACTION 'callMulti'       OPERATION 8 ACCESS 0
Return aRotina

//-------------------------------------------------------------------
/*/{Protheus.doc} ModelDef
Definição do model referente aos pedidos

@return oModel, objeto, objeto do modelo

@author  Vanessa Ruama
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
Static Function ModelDef()
    Local oModel As Object
    Local oStruSC7 As Object

    oStruSC7 := FWFormStruct(1,"SC7")

	oModel := MPFormModel():New("PEDIDO")
	oModel:SetDescription("Pedido de Compras")
	
	oModel:addFields('MASTERSC7',,oStruSC7)
	oModel:getModel('MASTERSC7'):SetDescription('Pedido de Compras')
	 
Return oModel

//-------------------------------------------------------------------
/*{Protheus.doc} ViewDef
Interface do modelo de dados

@return oView , objeto, retorna a view do modelo

@author  Vanessa Ruama
@since   01/12/2022
@version 1.0
*/
//-------------------------------------------------------------------
Static Function ViewDef()
Local oModel := ModelDef()
Local oView
Local oStrSC7:= FWFormStruct(2, 'SC7')
	
	oView := FWFormView():New()
	oView:SetModel(oModel)

	oView:AddField('FORM_PROD' , oStrSC7,'MASTERSC7' ) 
	oView:CreateHorizontalBox( 'BOX_FORM_PROD', 100)
	oView:SetOwnerView('FORM_PROD','BOX_FORM_PROD')	
	
Return oView

//-------------------------------------------------------------------
/*{Protheus.doc} callMulti
Chamada de múltiplos recursos do Smart View

@author  Vanessa Ruama
@since   15/09/2023
@version 1.0
*/
//-------------------------------------------------------------------
Function callMulti()
	Local lSuccess As logical
    Local cError as character

    //1º parâmetro = Relatório cadastrado na tabela de De/Para (Campo TR__IDREL)
    //2º parâmetro = Tipo do relatório ("reports" = relatório comum, "data-grid" = visão de dados, "pivot-table" = tabela dinâmica)
    //3º parâmetro = Tipo do impressão (Arquivo=1, Email=2)
    //4º parâmetro = Informações de impressão
    //5º parâmetro = Parâmetros do relatório
    //6º parâmetro = Indica se executa em job
 	//7º parâmetro = Indica se exibe os parâmetros para preenchimento
	//8º parâmetro = Indica se exibe o wizard de configuração do Smart View
 	//9º parâmetro = Erro da execução
	
	//Disponível a partir da LIB Label 20231009
	lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product",,,,,.F.,,.T., @cError)

	If !lSuccess
		Conout(cError)
	EndIf	
Return .T.

Tela de seleção dos recursos:

Seleção de recursos do Smart View

Após a seleção segue o processo padrão para executar o recurso.

Informações

title	Atenção

Para a chamada de recursos individuais utilizar o exemplo abaixo.

Utilização da função (Recurso individual)

Bloco de código

title	Exemplo com interface e executando em job
collapse	true

#include "protheus.ch"
#include "fwmvcdef.ch"

//-------------------------------------------------------------------
/*/{Protheus.doc} poc_mvc
Exemplo de um modelo e view baseado em uma unica tabela com chamada
de um relatório no Smart View pela função totvs.framework.treports.callTReports  

@author  Framework
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
User Function poc_mvc()
    Local oBrowse As Object
	
	oBrowse := FWMBrowse():New()
	oBrowse:SetAlias('SB1')
	oBrowse:SetDescription('Cadastro de Produtos')
	oBrowse:Activate()
		
Return

//-------------------------------------------------------------------
/*/{Protheus.doc} MenuDef
Função para carregamento do menu.

@return aRotina, array, array com as opções de menu.

@author  Framework
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
Static Function MenuDef()
    Local aRotina As Array

    aRotina := {}

    ADD OPTION aRotina TITLE 'Visualizar'           ACTION 'VIEWDEF.poc_mvc' OPERATION 2 ACCESS 0
    ADD OPTION aRotina TITLE 'Incluir'              ACTION 'VIEWDEF.poc_mvc' OPERATION 3 ACCESS 0
    ADD OPTION aRotina TITLE 'Alterar'              ACTION 'VIEWDEF.poc_mvc' OPERATION 4 ACCESS 0
    ADD OPTION aRotina TITLE 'Excluir'              ACTION 'VIEWDEF.poc_mvc' OPERATION 5 ACCESS 0
    ADD OPTION aRotina TITLE 'Imprimir'             ACTION 'VIEWDEF.poc_mvc' OPERATION 8 ACCESS 0
    ADD OPTION aRotina TITLE 'Imprimir Smart View'  ACTION 'callTrep'        OPERATION 8 ACCESS 0
    ADD OPTION aRotina TITLE 'Copiar'               ACTION 'VIEWDEF.poc_mvc' OPERATION 9 ACCESS 0

Return aRotina

//-------------------------------------------------------------------
/*/{Protheus.doc} ModelDef
Definição do model referente aos produtos

@return oModel, objeto, objeto do modelo

@author  Framework
@since   01/12/2022
@version 1.0
/*/
//-------------------------------------------------------------------
Static Function ModelDef()
    Local oModel As Object
    Local oStruSB1 As Object

    oStruSB1 := FWFormStruct(1,"SB1")

	oModel := MPFormModel():New("PRODUTOS")
	oModel:SetDescription("Produtos - SB1")
	
	oModel:addFields('MASTERSB1',,oStruSB1)
	oModel:getModel('MASTERSB1'):SetDescription('Produtos - SB1')
	 
Return oModel

//-------------------------------------------------------------------
/*{Protheus.doc} ViewDef
Interface do modelo de dados

@return oView , objeto, retorna a view do modelo

@author  Framework
@since   01/12/2022
@version 1.0
*/
//-------------------------------------------------------------------
Static Function ViewDef()
Local oModel := ModelDef()
Local oView
Local oStrSB1:= FWFormStruct(2, 'SB1')
	
	oView := FWFormView():New()
	oView:SetModel(oModel)

	oView:AddField('FORM_PROD' , oStrSB1,'MASTERSB1' ) 
	oView:CreateHorizontalBox( 'BOX_FORM_PROD', 100)
	oView:SetOwnerView('FORM_PROD','BOX_FORM_PROD')	
	
Return oView

//-------------------------------------------------------------------
/*{Protheus.doc} callTReports Função para chamada do relatório do Smart View

@author  Framework
@since   01/12/2022
@version 1.0
*/
//-------------------------------------------------------------------
Function callTrep()
    Local lSuccess As Logical

    //1º parâmetro = Relatório cadastrado na tabela de De/Para (Campo TR__IDREL)
    //2º parâmetro = Tipo do relatório ("reports" = relatório, "data-grid" = visão de dados, "pivot-table" = tabela dinâmica)
	//Como não foi mandado o 6º parâmetro como .F. o relatório será gerado em job, caso esse parâmetro seja enviado será aberta a tela de opções
	lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product.default.pv", "pivot-table")      
    If !lSuccess
        Conout("Erro na geração, verificar logs")
    EndIf

Return

Bloco de código

title	Exemplo sem interface e geração de arquivo
collapse	true

User Function treportsJob()
	Local lSuccess As Logical
	Local jParams As Json
    Local jPrintInfo As Json

    RpcSetEnv('T1', 'M PR 02', "admin", "1234") //Caso não tenha ambiente aberto

    //Preencher os parâmetros do relatório, caso o mesmo tenha parâmetro
	jParams := JsonObject():New()
	jParams['filial'] := "M PR 02"
	jParams['periodo'] := "201601"
	jParams['matriculade'] := "000003"
	jParams['matriculaate'] := "000003"

    jPrintInfo := JsonObject():New()  
    jPrintInfo['name'] := "GPER040_" + FwTimeStamp() //Adicionado o timestamp para não ter conflito no nome do arquivo 
    jPrintInfo['path'] := "C:\relatórios\"
	jPrintInfo['extension'] := "pdf"

    //1º parâmetro = Relatório cadastrado na tabela de De/Para (Campo TR__IDREL)
    //2º parâmetro = Tipo do relatório ("reports" = relatório, "data-grid" = visão de dados, "pivot-table" = tabela dinâmica)
	//3º parâmetro = Tipo de impressão (1 = Arquivo, 2 = E-mail )   
    //4º parâmetro = Informações de impressão    
    //5º parâmetro = Parâmetros do relatório
    lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product.synthetic.rep.bra", "report", 1, jPrintInfo, jParams)

    If !lSuccess
        Conout("Erro na geração, verificar logs")
    EndIf 
Return

Bloco de código

title	Exemplo sem interface e envio por e-mail
collapse	true

User Function treportsJob()
	Local lSuccess As Logical
    Local jPrintInfo As Json

    RpcSetEnv('T1', 'M PR 02', "admin", "1234") //Necessário identificar o usuário no rpcsetenv ou após       

    jPrintInfo := JsonObject():New()     
    jPrintInfo['to'] := "[email protected]" //Obrigatório setar o destinatário
    jPrintInfo['name'] := "Produtos - " + FWTimeStamp()

    //1º parâmetro = Relatório cadastrado na tabela de De/Para (Campo TR__IDREL)
    //2º parâmetro = Tipo do relatório ("reports" = relatório, "data-grid" = visão de dados, "pivot-table" = tabela dinâmica)
	//3º parâmetro = Tipo de impressão (1 = Arquivo, 2 = E-mail )   
    //4º parâmetro = Informações de impressão    
    lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product.analytical.rep.bra", "report", 2, jPrintInfo)

    If !lSuccess
        Conout("Erro na geração e envio do e-mail, verificar logs")
    EndIf 
Return

Enviando os parâmetros para os viewers externos

A partir da LIB Label 20240226 será possível enviar os parâmetros para os viewers externos do Smart View que são abertos no Protheus através do 5º parâmetro da função, isso facilitará o preenchimento feito pelo usuário que terão as opções carregadas do seu Profile/SX1 e também dos parâmetros enviados a partir da função.

Com esse recurso, também será possível bloquear parâmetros e também não exibi-los em tela.

Para isso o 5º parâmetro da função deverá seguir o formato esperado, sendo ele:

Bloco de código

title	Formato JSON
collapse	true

{
   "parameters":[
      {
         "name":"MV_PAR01",
         "value":"",
		 "visibility":"Default"
      },
      {
         "name":"MV_PAR02",
         "value":"ZZZZ"
      },
      {
         "name":"MV_PAR03",
         "value":"D MG 03, M SP 01",
         "visibility":"Hidden"
      }
   ],
   "force":false
}

Opções da propriedade visibility:

Default - O parâmetro é exibido e pode ter seu valor alterado pelo usuário;
Hidden - O parâmetro não é exibido no viewer;
Disabled - O parâmetro é exibido no viewer, porém o usuário não pode alterar seu valor.

Caso a mesma não seja enviada, terá o valor 'Default'

Parâmetros multivalores:

Deverão ser enviados como string e separados por ';'. Ex.: "D MG 01; D MG 02"

Parâmetros do tipo data:

Utilizar as funções de conversão disponibilizadas na lib para enviar o formato correto. Doc: Smart View - Conversão de datas

1º Exemplo de um json preenchendo os parâmetros:

Bloco de código

title	Exemplo jParams
collapse	true

    jParams := JsonObject():new()
    jParams["parameters"] := Array(2) //Os valores deverão sempre vir dentro do array 'parameters'
    jParams["force"] := .T. //Indica se força o valor, atenção ao utilizar essa propriedade, com isso não segue o profile do usuário
    jParams["parameters"][1] := JsonObject():New()
    jParams["parameters"][1]["name"] := "MV_PAR01" //Identificação do parâmetro
    jParams["parameters"][1]["value"] := ""
    jParams["parameters"][1]["visibility"] := "Disabled" //Desabilita o parâmetro
    
    jParams["parameters"][2] := JsonObject():New()
    jParams["parameters"][2]["name"] := "MV_PAR02"
    jParams["parameters"][2]["value"] := "ZZZZ"
    jParams["parameters"][2]["visibility"] := "Disabled" //Desabilita o parâmetro

	lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product",,,,jParams,.F.,,.T., @cError)

No exemplo acima envio apenas o preenchimento de 2 parâmetros, ambos ficarão desabilitados e como enviei a propriedade force como true, todas as vezes que esse recurso for consumido esses valores serão iguais, tenha cuidado ao utilizar essa propriedade, pois com ela não irá seguir o profile salvo do usuário.

Em tela teremos o seguinte resultado:

Tela de parâmetros com os valores preenchidos

Com a propriedade force igual a false, será sempre seguido o que esta no profile do usuário, serão preenchidos com os parâmetros da função apenas aqueles que não possuem valores do profile.

2º Exemplo de um json preenchendo os parâmetros:

Bloco de código

title	Exemplo jParams
collapse	true

    jParams := JsonObject():new()
    jParams["parameters"] := {} //Os valores deverão sempre vir dentro do array 'parameters'     
	jParams["force"] := .F. //Indica se força o valor ou segue o profile

    Pergunte("ABSENT",.F.,,.F.,,,@aPergunta,,) //pergunte do objeto de negócio

    For nX := 1 To Len(aPergunta)
        jValues := JsonObject():new()
        jValues["name"] := "MV_PAR"+StrZero(nX,2)

        if aPergunta[nX, 02] == "D" //Converte o tipo data
            jValues["value"] := totvs.framework.treports.date.dateToTimeStamp(aPergunta[nX, 08])
        elseif aPergunta[nX, 06] == "R"
            //Se for Range, considera o campo especifico de range
            jValues["value"] := aPergunta[nX, 20]
        elseif aPergunta[nX, 06] == "C" .And. aPergunta[nX, 08] == 0
            jValues["value"] := 1 //Envia o valor do combo sempre preenchido
        else
            jValues["value"] := aPergunta[nX, 08]
        endif

        jValues["visibility"] := "Default" 

        if jValues["name"] == "MV_PAR03"
            jValues["visibility"] := "Hidden"
        endif

        if jValues["name"] == "MV_PAR05"             
			jValues["visibility"] := "Disabled"
        endif

        aAdd(jParams["parameters"], jValues)
    Next nX    

	lSuccess := totvs.framework.treports.callTReports("framework.sv.framework.product.synt.rep.bra", "report", 1,,jParams,.F.,,,@cError)

No exemplo acima pego o preenchimento de um pergunte do SX1 e repasso para o viewer nos formatos corretos.

Em tela teremos o seguinte resultado:

Tela de parâmetros com os valores preenchidos

Observações

Os tipos de relatório pivot-table e data-grid serão gerados apenas com interface.
Os parâmetros do relatório deverão ser enviados pela função, caso seja geração em job.
Ao enviar o nome do relatório na propriedade 'name', enviada pelo json jPrintInfo, deverá se atentar a nomes iguais, caso a função seja chamada em job. A sugestão é colocar o nome + FWTimeStamp()

Páginas filhas

Versões comparadas

Versão antiga 67

Nova versão 68

Chave

Índice

Pré-requisitos

Padrão para nomenclatura dos arquivos .trp

Função totvs.framework.treports.callTReports

Propriedades do json jPrintInfo

Unificando o Menu/Rotina com recursos diferentes

Utilização da função (Recurso individual)

Enviando os parâmetros para os viewers externos

Observações

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 67

Nova versão 68

Chave

Índice

Pré-requisitos

Padrão para nomenclatura dos arquivos .trp

Função totvs.framework.treports.callTReports

Propriedades do json jPrintInfo

Unificando o Menu/Rotina com recursos diferentes

Utilização da função (Recurso individual)

Enviando os parâmetros para os viewers externos

Observações