Novos métodos e passo a passo

Foi implementado na integração com o Smart View a possibilidade de criação de objetos de negócios aninhados.

Um objeto de negócio aninhado consiste em um objeto de negócio que possui propriedades multiníveis e relações de dados, permitindo assim que os dados sejam enviados em um mesmo objeto, mas com grupos separados.

Objetos aninhados

As propriedades aninhadas (formato array) devem ser utilizados apenas em relatórios. Na visão de dados e tabela dinâmica as mesmas não trarão resultados dentro do objeto. Essas propriedades, incluindo suas subpropriedades, não são filtráveis.

Novos Métodos na classe totvs.framework.treports.integratedprovider.IntegratedProvider

addNestedProperty()

Adiciona uma propriedade aninhado no objeto de negócio.

Utilizar esse método caso o objeto aninhado seja o objeto principal.

Parâmetros:

Nome

Tipo

Obrigatório

Default

Descrição

cIdCaractereX
Id da propriedade
cDescriptionCaractereX
Descrição da propriedade
cDisplaynameCaractereX
Nome de exibição
cAliasCaractere

Indica o alias da propriedade
xFieldVariantX
Caractere ou Array contendo a estrutura/campos do objeto aninhado

Para adicionar em uma única propriedade aninhada campos de várias tabelas, é necessário mandar o 5º parâmetro com a estrutura dos campos com 4 posições e o cAlias nulo:

1-Id | 2-Descrição | 3-Tipo | 4-DisplayName

Exemplo completo:

aFields := {}

aAdd(aFields , {"A2_NOME", "Nome", "string", "Nome"})

aAdd(aFields , {"A1_COD", "Código", "string", "Código"})

self:addNestedProperty("Aninhado", "Aninhado", "Aninhado", , aFields)

Adicionando uma propriedade para fazer 2 níveis de objetos aninhados:

aFields := {} 

aAdd(aFields , {"A2_NOME", "Nome", "string", "Nome"})
aAdd(aFields , {"A1_COD", "Código", "string", "Código"})
aAdd(aFields , {"NIVEL2", "Nível 2", "array", "Nível 2"}) //Posso enviar o tipo como "array" já que irei transformar em objeto aninhado

self:addNestedProperty("Aninhado", "Aninhado", "Aninhado", , aFields)

aFields2 := {} 
aAdd(aFields2 , {"A2_COD", "Código", "string", "Código"}) 
self:transformInNested("NIVEL2", "", aFields2) //Transformo em objeto aninhado e já indico os campos que irão ficar dentro

Desta forma acima o objeto "Aninhado" terá dentro dele um outro objeto chamado "NIVEL2"

Exemplo de uso:

self:addNestedProperty("Fornecedores", "Fornecedores (SA2)", "Fornecedores (SA2)", "SA2", {"A2_NATUREZ", "A2_CGC"})

Sintaxe: self:addNestedProperty() → nil


transformInNested()

Transforma a propriedade em uma propriedade aninhada no objeto de negócio.

Utilizar esse método caso o objeto aninhado sejá nível 2 ou +, primeiro ele deve ser adicionado no objeto principal.

Parâmetros:

Nome

Tipo

Obrigatório

Default

Descrição

cIdCaractereX
Id da propriedade
cAliasCaractere

Indica o alias da propriedade
xFieldVariantX
Caractere ou Array contendo a estrutura/campos do objeto aninhado

Exemplo de uso:

self:transformInNested("EnderecoDetalhes", "SA2", {"A2_END", "A2_BAIRRO"})

Sintaxe: self:transformInNested() → nil


getStructNestedFields()

Retorna a estrutura dos campos aninhados.

Exemplo de uso:

self:getStructNestedFields()

Sintaxe: self:getStructNestedFields() → array

Como utilizar

Objetos aninhados com campos do SX3 e campos manuais (virtuais)

Schema

method getSchema() as object class CustomTReportsBusinessObject
	local aNested as array  
	local aNestedManual as array  
	
	aNested := {"A2_NATUREZ", "A2_CGC"}
	self:addNestedProperty("Fornecedores", "Fornecedores (SA2)", "Fornecedores (SA2)", "SA2", aNested)

	//Propriedade aninhada com campos manuais
	aNestedManual := Array(0)

	//Posições do array = 1-Id | 2-Descrição | 3-Tipo | 4-DisplayName
	//O array deverá ter exatamente 4 posições como demonstrado abaixo
	aAdd(aNestedManual, {"Informacao1", "Informação 1", "string", "Informação 1"})
	aAdd(aNestedManual, {"Informacao2", "Informação 2", "string", "Informação 2"})

	self:addNestedProperty("Info", "Info", "Info",, aNestedManual)

	//Exemplo adicionando uma propriedade manual e depois transformando em aninhado
	self:addProperty("EnderecoDetalhes", "Detalhes do Endereço", "string", "Detalhes do Endereço", "EnderecoDetalhes")
	self:transformInNested("EnderecoDetalhes", "SA2", {"A2_END", "A2_BAIRRO"})
	self:transformInNested("A2_BAIRRO", "SA2", {"A2_MUN", "A2_CEP"}) //Transformando a A2_BAIRRO em aninhada, fazendo assim mais um nível 

return self:oSchema

Data

Atenção

  • O objeto aninhado deverá ser utilizado apenas em objetos de negócios que executem a própria query e enviam os dados através do método appendData
  • Não deve ter paginação ao retornar os dados do objeto aninhado, ele deve ser entregue por completo, por isso o desenvolvedor deve se atentar ao utilizar esse recurso para não dar timeout na requisição enquanto estiver buscando os dados.
method getData() as object class CustomTReportsBusinessObject
(...)

//Ao indicar os campos da query utilizando o método getSQLFields com o 4º parâmetro como .T., trará os campos que estão dentro de objetos aninhados e que existem no SX3, independente do nível em que o campo esta
cQuery := "SELECT " + self:getSQLFields(,,,.T.) + " FROM " + RetSQLName("SA5")

(...)
while !(cAlias)->(Eof())
    jItems := JsonObject():new()
 
    for nX := 1 To Len(aAllFields)
        //Enquanto esta no while da query, antes do appendData, indicar os valores dos objetos aninhados
        formatNestedJson(cAlias, @jItems)
    next nX
 
    self:oData:appendData(jItems)
 
    (cAlias)->(DBSkip())
    nCount++
  
    //Sai do loop quando chegar no tamanho de itens da página
    if nCount == self:getPageSize()
      exit
    endif
enddo 

(...)
return self:oData

//-------------------------------------------------------------------
/*{Protheus.doc} formatNestedJson
Formato o json dos objetos aninhados
 
@param cAlias charactere: Alias aberto na query
@param jItems json: Json de resposta na requisição
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//------------------------------------------------------------------- 
static function formatNestedJson(cAlias as character, jItems as json)

//Como o desenvolvedor conhece a estrutura de objetos aninhados que foram criados, basta retornar corretamente no formato json
jItems["Fornecedores"] := {}
aAdd(jItems["Fornecedores"], {"A2_NATUREZ": (cAlias)->&("A2_NATUREZ"), "A2_CGC": (cAlias)->&("A2_CGC")})

jItems["Info"] := {}
aAdd(jItems["Info"], {"Informacao1":"Info 1", "Informacao2":"Info 2"})

jItems["EnderecoDetalhes"] := {}
aAdd(jItems["EnderecoDetalhes"], {"A2_END": (cAlias)->&("A2_END"), "A2_BAIRRO":{{"A2_MUN": (cAlias)->&("A2_MUN"), "A2_CEP": (cAlias)->&("A2_CEP")}}})
return

Retorno esperado dos objetos aninhados no json do método getData (busca de dados)

Json
{
    "data": [
        {
            "Fornecedores": [
                {
                    "A2_NATUREZ": "IRGCT     ",
                    "A2_CGC": "              "
                }
            ],
            "Info": [                 
				{
                    "Informacao1": "Info 1",
                    "Informacao2": "Teste 1"
                },
                {
                    "Informacao1": "Info 2",
                    "Informacao2": "Teste 2"
                },
                {
                    "Informacao1": "Info 3",
                    "Informacao2": "Teste 3"
                }             
			],
            "EnderecoDetalhes": [
                {
                    "A2_END": "TESTE IT",
                    "A2_BAIRRO": [
                        {
                            "A2_MUN": "SP",
							"A2_CEP":"00000-00"
                        }
                    ]
                }
            ],
(...)
}

Resultado esperado no Smart View


Como utilizar no design

1 - Inserir a banda demonstrada abaixo:

Inserindo uma nova banda ao relatório

2 - Selecionar a banda que foi adicionada e inserir qual objeto aninhado deseja utilizar, aqui no meu exemplo selecionei o objeto "Info":

Adicionando um objeto aninhado na banda criada

3 - Adicionar os campos do objeto aninhado ao design:

Adicionando os campos do objeto aninhado no design

4 - Resultado:

Resultado no relatório

Exemplo completo
#include "msobject.ch"
#include "protheus.ch"
#include "totvs.framework.treports.integratedprovider.th"
    
namespace custom.smartview
 
@totvsFrameworkTReportsIntegratedProvider(active=.T., team="Framework", tables="SA5,SA2", name="Produto X Fornecedor", country="ALL", initialRelease="12.1.033", customTables="All")
//-------------------------------------------------------------------
/*{Protheus.doc} CustomTReportsBusinessObject
Classe para criação do Objeto de Negócio de Prod  x Forn para o TReports
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------  
class CustomTReportsBusinessObject from totvs.framework.treports.integratedprovider.IntegratedProvider
    public method new() as object
    public method getDisplayName() as character
    public method getDescription() as character
    public method getData() as object
    public method getSchema() as object

    protected data aFields as array
    protected data aNested as array
    protected data aStruct as array
 
endclass
 
//-------------------------------------------------------------------
/*{Protheus.doc} new
Método de instância da classe
 
@return object: self
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------   
method new() class CustomTReportsBusinessObject
_Super:new()
self:appendArea("Framework - Custom")
 
self:aFields := {"A5_FILIAL", "A5_FORNECE", "A5_LOJA", "A5_NOMEFOR", "A5_PRODUTO", "A5_NOMPROD", "A5_CODPRF"} 
self:aNested := {"A2_NATUREZ", "A2_CGC"}
self:aStruct := u_getStruct(self:aFields)
 
return self
 
//-------------------------------------------------------------------
/*{Protheus.doc} getDisplayName
Retorna o nome de exibição do objeto de negócio
 
@return string
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------   
method getDisplayName() as character class CustomTReportsBusinessObject
return "Produtos x Fornecedores - Aninhado"
 
//-------------------------------------------------------------------
/*{Protheus.doc} getDescription
Retorna a descrição do objeto de negócio
 
@return string
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------  
method getDescription() as character class CustomTReportsBusinessObject
return "Produtos x Fornecedores - Aninhado"
 
//-------------------------------------------------------------------
/*{Protheus.doc} getData
Retorna os dados do objeto de negócio
 
@param nPage, numérico, indica a página atual do relatório
@param oFilter, objeto, contém o filtro do TReports
 
@return object: self:oData
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------   
method getData(nPage as numeric, oFilter as object) as object class CustomTReportsBusinessObject
local cQuery as character
local cAlias as character
local nSkip as numeric
local nCount as numeric
local nX as numeric
local jItems as json
local aPDFields as array
local aAllFields as array
local cRealName as character
local cId as character
local oExec as object
  
nCount := 0
aAllFields := {}

//Verifica se o Smart View retornou os campos utilizados
if oFilter:hasFields()
    cQuery := "SELECT " + ArrTokStr(self:getFields(), ",") + " FROM " + RetSQLName("SA5")
else
    //Manda todos os campos do schema
    cQuery := "SELECT " + self:getSQLFields(,,,.T.) + " FROM " + RetSQLName("SA5")
endif

cQuery += " SA5 LEFT JOIN " + RetSQLName("SA2") + " SA2 ON SA5.A5_FORNECE = SA2.A2_COD WHERE SA2.D_E_L_E_T_ = ' '"
 
//Os filtros serão setados na interface do novo TReports
if oFilter:hasFilter()
    cQuery += " AND " + oFilter:getSQLExpression()
endif

self:setPageSize(150)    

oExec  := FwExecStatement():New(ChangeQuery(cQuery))
cAlias := oExec:OpenAlias()    

if nPage > 1
    //Default 100
    //Encontra a quantidade de itens que irá pular de acordo com a página atual
    nSkip := ((nPage - 1) * self:getPageSize())     
  
    (cAlias)->(dbSkip(nSkip))
endif  
  
//Verifica se precisa fazer o tratamento para LGPD
aPDFields := FwProtectedDataUtil():UsrAccessPDField(__cUserID, self:getArrayFields())
lObfuscated := len( aPDFields ) != Len(self:getArrayFields())
aAllFields := self:getStructFields()

while !(cAlias)->(Eof())
    jItems := JsonObject():new()
 
    for nX := 1 To Len(aAllFields)
        cId := aAllFields[nX]:getName()
        cRealName := aAllFields[nX]:getRealName()
        if lObfuscated .and. aScan(aPDFields, cRealName) == 0
            jItems[cId] := FwProtectedDataUtil():ValueAsteriskToAnonymize((cAlias)->&(cRealName))
        else
            if aAllFields[nX]:getType() == "date"
                jItems[cId] := totvs.framework.treports.date.stringToTimeStamp((cAlias)->&(cRealName))
            else
                jItems[cId] := (cAlias)->&(cRealName)
            endif
        endif

        //Campos aninhados
        formatNestedJson(cAlias, @jItems)
    next nX
 
    self:oData:appendData(jItems)
 
    (cAlias)->(DBSkip())
    nCount++
  
    //Sai do loop quando chegar no tamanho de itens da página
    if nCount == self:getPageSize()
      exit
    endif
enddo 
  
//Se não for o último registro indica que terá próxima página
self:setHasNext(!(cAlias)->(Eof())) 
  
(cAlias)->(DBCloseArea())
    
return self:oData
 
//-------------------------------------------------------------------
/*{Protheus.doc} getSchema
Retorna a estrutura dos campos
 
@return object: self:oSchema
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//-------------------------------------------------------------------   
method getSchema() as object class CustomTReportsBusinessObject
local nX as numeric
local aNestedManual as array
 
for nX := 1 To Len(self:aStruct)
    self:addProperty(self:aStruct[nX][1], self:aStruct[nX][2], self:aStruct[nX][3], self:aStruct[nX][4], self:aStruct[nX][5])
next nX

//Propriedade aninhada com campos do SX3
self:addNestedProperty("Fornecedores", "Fornecedores (SA2)", "Fornecedores (SA2)", "SA2", self:aNested)

//Propriedade aninhada com campos manuais
aNestedManual := Array(0)
//Posições do array = 1-Id | 2-Description 3-Type 4-DisplayName
aAdd(aNestedManual, {"Informacao1", "Informação 1", "string", "Informação 1"})
aAdd(aNestedManual, {"Informacao2", "Informação 2", "string", "Informação 2"})

self:addNestedProperty("Info", "Info", "Info",, aNestedManual)

//Exemplo adicionando uma propriedade manual e depois transformando em aninhado
self:addProperty("EnderecoDetalhes", "Detalhes do Endereço", "string", "Detalhes do Endereço", "A6_MOEDA")
self:transformInNested("EnderecoDetalhes", "SA2", {"A2_END", "A2_BAIRRO"})
self:transformInNested("A2_BAIRRO", "SA2", {"A2_MUN", "A2_CEP"})

return self:oSchema
 
//-------------------------------------------------------------------
/*{Protheus.doc} getStruct
Prepara a estrutura dos campos
 
@param aCpos array: Array com os campos do relatório
 
@return array: Array com a estrutura dos campos
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//------------------------------------------------------------------- 
user function getStruct(aCpos)
Local aDeParaCpo as array
Local aCpoTmp    as array
Local cCampo     as character
Local cCpoQry    as character
Local cTipR      as character
Local nPos       as numeric
Local nC         as numeric
 
aDeParaCpo := {{"C", "string"}, {"D", "date"}, {"N", "number"}, {"L", "boolean"}, {"M", "memo"}}
aCpoTmp    := {}
 
for nC := 1 to Len(aCpos)
    cCpoQry := aCpos[nC]
    nPos    := AT(".", aCpos[nC]) + 1
     
    if nPos > 0
        cCampo := Substr(cCpoQry, nPos)
    else
        cCampo := cCpoQry
    endif
     
    cTipo := GetSx3Cache(cCampo, "X3_TIPO")
     
    if (nPos := aScan(aDeParaCpo, {|c| c[01] = cTipo})) > 0
        cTipR := aDeParaCpo[nPos, 02]
    else
        cTipR := "string"
    endif
 
    AAdd(aCpoTmp, {strTran(cCampo, "_", ""), FWSX3Util():GetDescription(cCampo), cTipR, FWSX3Util():GetDescription(cCampo), cCampo})
next nC
 
return (aCpoTmp)

//-------------------------------------------------------------------
/*{Protheus.doc} formatNestedJson
Formato o json dos objetos aninhados
 
@param cAlias charactere: Alias aberto na query
@param jItems json: Json de resposta na requisição
 
@author Vanessa Ruama
@since 02/03/2023
@version 1.0
*/
//------------------------------------------------------------------- 
static function formatNestedJson(cAlias as character, jItems as json)

jItems["Fornecedores"] := {}
aAdd(jItems["Fornecedores"], {"A2_NATUREZ": (cAlias)->&("A2_NATUREZ"), "A2_CGC": (cAlias)->&("A2_CGC")})  jItems["Info"] := {}
aAdd(jItems["Info"], {"Informacao1":"Info 1", "Informacao2":"Teste 1"})
aAdd(jItems["Info"], {"Informacao1":"Info 2", "Informacao2":"Teste 2"})
aAdd(jItems["Info"], {"Informacao1":"Info 3", "Informacao2":"Teste 3"})

jItems["EnderecoDetalhes"] := {}
aAdd(jItems["EnderecoDetalhes"], {"A2_END": (cAlias)->&("A2_END"), "A2_BAIRRO":{{"A2_MUN": (cAlias)->&("A2_MUN"), "A2_CEP": (cAlias)->&("A2_CEP")}}})
return
  • Sem rótulos