Classe criada para a execução de recursos do Smart View no Protheus.

Disponível a partir da LIB Label 20240226

É possível ver os logs da classe 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, caso utilize a importação automática - Smart View - Importação Automática de Recursos

Unificando o Menu/Rotina com recursos diferentes

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 (no caso da importação automática, com o cadastro manual também é possível criar os Id's) 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 (cProtheusId) no método new() desta classe 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.

Para utilizar o recurso individual o ID enviado na classe deverá ser o nome completo do layout, ex.: framework.sv.framework.product.synthetic.rep.bra

Métodos

New()

Método de instância da classe.

Parâmetros:

Nome

Tipo

Obrigatório

Default

Descrição

cProtheusId

Caractere

X

Id do recurso que será impresso (relacionado ao nome do arquivo .trp ou registro na tabela de amarração).

Obs.: Não pode conter espaços, acentos ou caracteres especiais, com exceção do ponto (.) e sublinhado (_)

cType

Caractere

Apenas quando for a execução de recurso único

Tipo do recurso (report, pivot-table ou data-grid)

Exemplos de uso:

oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product.default.rep.bra", "report")

oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product")

Sintaxe: New() → objeto self

setRunInJob()

Indica se executa o relatório em job

Esse método deverá ser utilizado apenas para relatórios.

Utilizando a geração em job o método executeSmartView da classe sempre retornará .T., pois será iniciado um startJob, sendo possível verificar a geração a partir do console.log com a chave FwTraceLog=1 ligada.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lIsJob	Lógico	X	.F.	Indica se o recurso será executado em job

Exemplo de uso:

oSmartView:setRunInJob(.T.)

Sintaxe: setRunInJob(<lIsJob>) → nil

setNoInterface()

Indica se executa o relatório sem a interface.

Esse método deverá ser utilizado apenas para relatórios.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lNoInterface	Lógico	X	.F.	Indica se o recurso será executado sem interface

Exemplo de uso:

oSmartView:setNoInterface(.T.)

Sintaxe: setNoInterface(<lNoInterface>) → nil

setShowWizard()

Indica se exibe o wizard de configuração caso o ambiente esteja despreparado para o uso da integração.

Esse método deverá ser utilizado apenas para relatórios.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lShowWizard	Lógico	X	.F.	Indica se abre o wizard de configuração

Exemplo de uso:

oSmartView:setShowWizard(.T.)

Sintaxe: setShowWizard(<lShowWizard>) → nil

setShowParams()

Indica se exibe o botão de parâmetros para que o usuário edite.

Esse método deverá ser utilizado apenas para relatórios.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lShowParams	Lógico	X	.T.	Indica irá mostrar o botão de parâmetros

Exemplo de uso:

oSmartView:setShowParams(.T.)

Sintaxe: setShowParams(<lShowParams>) → nil

setParameters()

Indica os parâmetros do recurso.

Neste método é considerado o envio de todos os parâmetros de uma vez, para enviar um de cada, pode-se utilizar o método setParam(), não é possível utilizar os dois métodos ao mesmo tempo, pois um sobrescreve o outro.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
jParams	Json	X		Parâmetros que serão setados no recurso

Formato esperado:

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

Propriedade force:

Caso seja enviado como .T. indica que irá sobrescrever o profile do usuário com os parâmetros enviados, caso alguns parâmetros não sejam enviados ficarão com o valor do profile.

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

Exemplo de uso:

jParams := JsonObject():new()
jParams["parameters"] := Array(2)
jParams["force"] := .T. //Indica se força o valor
jParams["parameters"][1] := JsonObject():New()
jParams["parameters"][1]["name"] := "MV_PAR01"
jParams["parameters"][1]["value"] := ""
jParams["parameters"][1]["visibility"] := "Disabled"
    
jParams["parameters"][2] := JsonObject():New()
jParams["parameters"][2]["name"] := "MV_PAR02"
jParams["parameters"][2]["value"] := "ZZZZ"
jParams["parameters"][2]["visibility"] := "Disabled"

oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product")
oSmartView:setParameters(jParams)

Sintaxe: setParameters(<jParams>) → nil

setParam()

Indica o valor de um parâmetro do relatório.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
cName	Caractere	X		Identificação do parâmetro, ex.: MV_PAR01
xValue	Variante	X		Valor do parâmetro
cVisibility	Caractere		Default	Visibilidade do Parâmetro

Exemplo de uso:

oSmartView:setParam("MV_PAR01", "", "Disabled")
oSmartView:setParam("MV_PAR02", "ZZZZZ")
oSmartView:setParam("MV_PAR03", 2, "Hidden")
oSmartView:setParam("MV_PAR04", totvs.framework.treports.date.stringToTimeStamp("20240130"))

Sintaxe: setParam(<cName>, <xValue>, <cVisibility>) → nil

setForceParams()

Indica se irá forçar o preenchimento dos parâmetros com o valores enviados.

Com o force ativado o profile do usuário sempre será sobrescrito com os valores dos parâmetros enviados, aqueles que não forem enviados, será preenchido pelo profile, caso exista.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lForce	Lógico	X	.F.	Indica se força os valores dos parâmetros

Exemplo de uso:

oSmartView:setForceParams(.T.)

Sintaxe: setForceParams(<lForce>) → nil

setPrintType()

Indica o tipo de impressão.

Esse método deverá ser utilizado apenas para relatórios.

Parâmetros:

Nome

Tipo

Obrigatório

Default

Descrição

nPrintType

Numérico

X

1

Tipo de impressão, sendo elas:

1 - Arquivo

2 - E-mail

Exemplo de uso:

oSmartView:setPrintType(1)

Sintaxe: setPrintType(<nPrintType>) → nil

setPrintInfo()

Indica os valores de impressão do recurso.

Esse método deverá ser utilizado apenas para relatórios.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
jPrintInfo	Json	X		Informações de impressão.

Formato esperado:

É necessário o envio de algumas informações sobre a impressão a partir do jPrintInfo, sendo elas:

Opção 1 - Impressão em arquivo

Propriedades:

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

Evitar utilizar alguns caracteres especiais no nome do relatório, alguns exemplos:
\ / : * ? " < > |

Isso pode gerar erro ao gravar o mesmo.

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		MV_RELT	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.

Exemplo de uso:

jPrintInfo := jsonObject():new()
jPrintInfo["extension"] := "xlsx"
jPrintInfo["name"] := "product" + FWTimeStamp()
oSmartView:setPrintInfo(jPrintInfo)

Sintaxe: setPrintInfo(<jPrintInfo>) → nil

executeSmartView()

Executa o recurso escolhido.

Retorno:

Nome	Tipo	Descrição
lSuccess	Lógico	Indica o erro na execução

Exemplo de uso:

lSuccess := oSmartView:executeSmartView()

Sintaxe: oSmartView:executeSmartView() → lSuccess

setOpenFile()

Indica se abre o arquivo após a impressão.

Disponível a partir da LIB Label 20250113

Arquivos não serão abertos se gerados via job;

Arquivos não serão abertos se gerados na pasta Spool;

Para abrir arquivos no WebApp, é obrigatório o uso do agent.

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
lOpenFile	Lógico	X	.T.	Indica se abre o arquivo gerado

Exemplo de uso:

oSmartView:setForceParams(.T.)

Sintaxe: oSmartView:setForceParams(.T.) → nil

getError()

Retorna o erro na geração.

Retorno:

Nome	Tipo	Descrição
cError	Caractere	Indica o erro na execução

Exemplo de uso:

cError := oSmartView:getError()

Sintaxe: oSmartView:getError() → cError

destroy()

Remove os recursos que podem prender memória.Exemplo de uso:

oSmartView:destroy()

Sintaxe: oSmartView:destroy() → nil

loadParamsProfile()

Retorna o profile do usuário.

Disponível a partir da LIB Label 20251117

Parâmetros:

Nome	Tipo	Obrigatório	Default	Descrição
cBusinessObjectName	Caractere	X		Nome do objeto de negócio (namespace + classe) em lowercase
oProfile	Objeto			Objeto do profile da classe FWProfile, retornado caso o profile exista (referência)

Retorno:

Nome	Tipo	Descrição
lHasProfile	Lógico	Indica se o profile existe

Exemplo de uso:

oSmartView := totvs.framework.smartview.callSmartView():new()
lHasParams := oSmartView:loadParamsProfile("custom.framework.businessobject.test", @oProfile)

//Se existir, é possível manipular através da classe FwProfile
If lHasParams
    oProfile:Delete()
EndIf

Sintaxe: oSmartView:loadParamsProfile(cBusinessObjectName, @oProfile) → lHasProfile

Exemplos completos

#include "protheus.ch"

user function sv_job()
	local oSmartView as object
    
    RpcSetEnv('T1', 'D MG 01', "admin", "1234") //Necessário ter o ambiente inicializado
	
	//Para geração em job sempre deverá ser setado um recurso único
    oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product.default.rep.bra", "report")
    oSmartView:setRunInJob(.T.)
    oSmartView:setParam("MV_PAR01", "", "Disabled")
    oSmartView:setParam("MV_PAR02", "ZZZZZ")
	oSmartView:setPrintType(1)
    oSmartView:executeSmartView() //A geração deverá ser acompanhada via logs pelo server
    oSmartView:destroy()
return

#include "protheus.ch"

user function sv_noInterface()
    local lSuccess as logical
	local oSmartView as object
	local jPrint as json
    
    RpcSetEnv('T1', 'D MG 01', "admin", "1234") //Necessário ter o ambiente inicializado
	
	//Para geração sem interface sempre deverá ser setado um recurso único
    oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product.default.rep.bra", "report")
    oSmartView:setNoInterface(.T.)
    oSmartView:setParam("MV_PAR01", "", "Disabled")
    oSmartView:setParam("MV_PAR02", "ZZZZZ")
	oSmartView:setPrintType(1) 

    jPrint := jsonObject():new()
    jPrint["extension"] := "xlsx"
    jPrint["name"] := "teste_print" + FWTimeStamp()
    oSmartView:setPrintInfo(jPrint)  
  
 	lSuccess := oSmartView:executeSmartView()  

 	If !lSuccess
		Conout(oSmartView:getError())
	EndIf	
	   
	oSmartView:destroy()
return

#include "protheus.ch"

user Function callSV()
	local lSuccess As logical
    local jParams as json
	local oSmartView as object

    jParams := JsonObject():new()
    jParams["parameters"] := Array(2)
    jParams["force"] := .T. //Indica se força o valor
    jParams["parameters"][1] := JsonObject():New()
    jParams["parameters"][1]["name"] := "MV_PAR01"
    jParams["parameters"][1]["value"] := ""
    jParams["parameters"][1]["visibility"] := "Disabled"
    
    jParams["parameters"][2] := JsonObject():New()
    jParams["parameters"][2]["name"] := "MV_PAR02"
    jParams["parameters"][2]["value"] := "ZZZZ"
    jParams["parameters"][2]["visibility"] := "Disabled"

    oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product.synt.rep.bra", "report")
    oSmartView:setParameters(jParams)
    lSuccess := oSmartView:executeSmartView()

	If !lSuccess
		Conout(oSmartView:getError())
	EndIf	

    oSmartView:destroy()
return .T.

#include "protheus.ch"

user Function callMultiSV()
	local lSuccess As logical
	local oSmartView as object

    oSmartView := totvs.framework.smartview.callSmartView():new("framework.sv.framework.product")
    oSmartView:setParam("MV_PAR01", "")
    oSmartView:setParam("MV_PAR02", "ZZZZZ")
	oSmartView:setParam("MV_PAR03", 2) 
	oSmartView:setParam("MV_PAR04", totvs.framework.treports.date.dateToTimeStamp(date()))
    
	lSuccess := oSmartView:executeSmartView()

	If !lSuccess
		Conout(oSmartView:getError())
	EndIf	

    oSmartView:destroy()
return .T.