Essa função será depreciada a parte da LIB Label 20240226, utilizar a nova classe: Classe para execução dos recursos no Protheus

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

É 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

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 os arquivos .trp com o padrão de nomenclatura correto - Padrão para nomenclatura dos arquivos .trp (layouts)
Ter compilados os arquivos .trp no RPO - Smart View - Importação Automática de Recursos

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 o recurso sem interface		Tipo do impressão (Arquivo=1, Email=2)
jPrintInfo	json	Apenas se for utilizada o recurso sem interface		Informações para a impressão do relatório
jParams	json	Se houver parâmetros no relatório		Parâmetros do relatório
lRunNoInterface	lógico		.T.	Indica se irá executar sem interface
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 sem interface 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]

Ao utilizar a geração sem interface 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

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

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

Funcionalidade disponível a partir da LIB Label 20231009

Com o Padrão para nomenclatura dos arquivos .trp (layouts) correto, é 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:

#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 sem a interface
 	//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.

Para a chamada de recursos individuais utilizar o exemplo abaixo.

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

#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 sem interface, 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

User Function treportsNoInterface()
	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

User Function treportsNoInterface()
	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:

{
   "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:

    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:

    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 sem interface.
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 sem interface. A sugestão é colocar o nome + FWTimeStamp()