Histórico da Página

CONTEÚDO

01.  Visão Geral

Implementação das Consultas padrão utilizando os dados de Formulários durante a edição dos registros no Totvs Departamento Jurídico. 

O documento visa demonstrar como deve ser feita a implementação das consultas padrão ( SXB ) caso o cliente decida por utilizar dados em tempo de execução sem ter de salvar o registro.

02. Rotinas com a funcionalidade disponível

Abaixo seguem as rotinas e tabelas que podem usar o filtro de consulta padrão com dados de formulários.

03. Utilização de filtros

A seguir veremos como será a utilização dos filtros nas consultas a partir da JURSXB onde podemos utilizar das seguintes formas:

• Filtro por posição do registro na memória
  • Expressão: JURSXB("NT9","JURCST",{"NT9_NOME","NT9_CODENT"},.T.,.T.,"NT9->NT9_CAJURI==NSZ->NSZ_COD")
  • Explicação: O Filtro por posição será convertido para uma condição que irá comparar ao menos dois campos na consulta, realizando o filtro desejado. Importante ressaltar que apenas filtros complementares com a NSZ estão disponíveis.

• Filtro por função
  • Expressão: JURSXB("CT1","JURFNC",{"CT1_CONTA","CT1_DESC01"},.T.,.T.,"@#U_CT1JUR_NW()")
  • Explicação: O filtro por função executará a função inserida, tal função deverá retornar uma condição que por sua vez será utilizada para complementar a busca pelo registro. Importante ressaltar que é necessário a indicação do @# antes da função.
    Exemplo de retorno de uma função: " CT1_CLASSE == '2' And CT1_BLOQ <> '1' ".

• Filtro por campo do formulário
  • Expressão: JURSXB("SB1","SB1T10",{"B1_DESC","B1_COD"},.T.,.T.,"@#U_JQRYF301(oJson)")
  • Explicação: O filtro por campo do formulário executará a função inserida, passando os valores do formulário via parâmetro, tal função deverá retornar uma condição que por sua vez será utilizada para complementar a busca pelo registro. Importante ressaltar que é necessário a indicação do @# antes da função e seu parâmetro oJson.
    Exemplo de retorno de uma função: " B1_DESC like '%PRODUTO%' ".

04. Utilização de filtros por posicionamento na memória ( Somente posicionamento da NSZ )

1. Consulta da JURSXB - Consulta padrão
   1. Nessa etapa estaremos criando a consulta que o campo customizado executará.
   2. Nesse exemplo o posicionamento ocorrerá baseado no código do assunto jurídico em que o usuário estiver editando.
   3. Exemplo de consulta JURSXB considerando o filtro de campos:
      Image Added
   4. Observações: 
      
      1. Após criar / editar a consulta padrão, é necessário vincular ao campo que executará a consulta.
2. Exemplo de uso:
   1. Por meio do posicionamento da NSZ pelo código do assunto jurídico, o campo de consulta executará a condição da JURSXB, onde os envolvidos (NT9) que serão retornados são apenas os envolvidos do processo em que o usuário está editando.
   2. Envolvidos cadastrados no processo.
      Image Added
   3. Já o campo de consulta, está realizando esse filtro retornando os envolvidos vinculados nesse processo.
      Image Added

05. Utilização de filtros

...

03. Utilização de filtros pelos campos do formulário

por função

1. Consulta da JURSXB - Consulta padrão
   1. Nessa etapa estaremos criando a consulta que o campo customizado executará.
   2. Esse filtro está disponível apenas para funções compiladas, incluindo customizações.
   3. Exemplo de consulta JURSXB considerando o filtro de campos:
      Image Added
   4. Observações: 
      
      1. Após criar / editar a consulta padrão, é necessário vincular ao campo que executará a consulta.
2. Função com filtro de campos
   1. Nessa etapa estaremos tratando do filtro que será executado ao consultar o campo.
   2. Seguindo a mesma regra da etapa anterior, precisamos criar a função que executará o filtro.
   3. A partir disso o usuário pode criar a condição SQL desejada.
   4. Importante: O retorno dessa função deve ser uma condição SQL, sem a necessidade do AND no início

   5. Exemplo de função e retorno:

      Bloco de código
      language java theme RDark linenumbers true
      //------------------------------------------------------------------- /*/{Protheus.doc} CT1JUR_NW Função montagem da query que será usada para filtrar os registros da consulta padrão @return cQuery - Condição da Query sem AND no início /*/ //--------------------------------------------------------------------   User Function CT1JUR_NW() Local cQuery := "" Local c_Ccusto := IIF(Empty(M->NSZ_CCUSTO),NSZ->NSZ_CCUSTO,M->NSZ_CCUSTO)   cQuery := "CT1_RES = '" + c_Ccusto +"' AND CT1_BLOQ <> '1' AND CT1_NORMAL <> '2'" Return cQuery

   6. Observações:

      1. A função deve ser a mesma que foi inserida na consulta, na etapa anterior.
      2. A função deve retornar uma condição SQL sem o AND no início.
      3. Essa função deve estar compilada no ambiente.
3. Exemplo de uso:
   1. Quando for realizada a pesquisa por meio do campo de consulta, será executado a condição retornada da função que o usuário definiu na consulta padrão.
      Image Added
   2. Importante: Essa funcionalidade não contempla a atualização de filtros em tempo real pelo formulário, para utilizar os dados do formulário é necessário configurar a consulta padrão citada na seção 06.

06. Utilização de filtros pelos campos do formulário

1. Consulta da JURSXB - Consulta padrão
   1. Nessa etapa estaremos criando a consulta que o campo customizado executará.
   2. Esse filtro está disponível apenas para funções compiladas, incluindo customizações.
   3. Para isso é necessário passar como parâmetro da função o oJson, esse será o parâmetro que armazenará os dados do formulário. Importante: Sem a passagem do parâmetro, a função não terá acesso aos dados do formulário.
   4. Exemplo de consulta JURSXB considerando o filtro de campos:
      Image Added
   5. Observações: 
      1. Esse filtro está disponível apenas para campos customizados.
      2. Após criar / editar a consulta padrão, é necessário vincular ao campo que executará a consulta.
2. Função com filtro de campos
   1. Nessa etapa estaremos tratando do filtro que será executado ao consultar o campo customizado.
   2. Seguindo a mesma regra da etapa anterior, precisamos criar a função com um parâmetro oJson, o mesmo que receberá os campos e seus valores.
   3. A partir disso o usuário pode criar a condição SQL desejada, utilizando ou não os campos do formulário.
   4. Importante: O retorno dessa função deve ser uma condição SQL, sem a necessidade do AND no início

   5. Exemplo de função e retorno, considerando o filtro de campos:

      Bloco de código
      language java theme RDark linenumbers true
      //------------------------------------------------------------------- /*/{Protheus.doc} JQRYF301 Função montagem da query que será usada para filtrar os registros da consulta padrão @param oJson - Objeto JSON contendo os campos do formulário para Totvs Departamento Jurídico. Esse Objeto vem por padrão NIL no caso de execução via Protheus. @return cQuery - Condição da Query sem AND no início /*/ //-------------------------------------------------------------------- USER FUNCTION JQRYF301(oJson) Local cQuery := "" Local oModel := FWModelActive() Default oJson := Nil If oJson == Nil .Or. Empty(oJson:toJson()) If isBlind() // Caso seja Totvs Departamento Jurídico e Visualização do GRID, usar o posicione da tabela (NUQ) cQuery := retWhere(AllTrim(NUQ->NUQ_XCARAC), AllTrim(NUQ->NUQ_XNATUR)) Else // Caso seja Protheus, usar o modelo para pegar o valor do campo atualizado cQuery := retWhere(AllTrim(oModel:GetValue("NUQDETAIL", "NUQ_XCARAC"))) EndIf Else // Caso seja Totvs Departamento Jurídico, usar campos do formulário pelo oJson If !Empty(oJson["NUQ_XCARAC"]) cQuery := retWhere(UPPER(oJson["NUQ_XCARAC"]), AllTrim(oJson["NUQ_XNATUR"])) EndIf EndIf Return cQuery   //------------------------------------------------------------------- /*/{Protheus.doc} retWhere Função para centralizar a regra de negócio na montagem da Query @param cNUQXCarac - Campo customizado de descrição @param cNatut - Campo customizado de natureza @return cReturn - Condição da Query sem AND no início /*/ //-------------------------------------------------------------------- Static Function retWhere(cNUQXCarac, cNatut) Local cReturn := "" Default cNUQXCarac := "" Default cNatut := "" If cNatut == "0001" .Or. cNatut == "0002" cReturn := "O0N_CSLDOC like '%" + cNUQXCarac + "%' and O0N_TIPO = '1'" ElseIf cNatut == "0003" .Or. cNatut == "0004" cReturn := "O0N_CSLDOC like '%" + cNUQXCarac + "%' and O0N_TIPO = '2'" Else cReturn := "O0N_CSLDOC like '%" + cNUQXCarac + "%'" EndIf Return cReturn

   6. Observações:

      1. A função deve ser a mesma que foi inserida na consulta, na etapa anterior.
      2. A função deve retornar uma condição SQL sem o AND no início.
      3. Essa função deve estar compilada no ambiente.
      4. Para filtrar pelos valores do formulário, utilizamos o parâmetro oJson[<nome_do_campo>], como no exemplo onde está sendo filtrado pelo campo customizado NT3_XCARAC.
      5. Importante: Apenas campos caractere estão disponíveis para serem usados como filtro. Campos com X3_TIPO = 'C'.
      6. A função "retWhere" é utilizada como boas práticas para evitar a repetição da regra de negócio que envolva a montagem da query, centralizando esse comportamento. Obs: A função estática "retWhere" não precisa ser nomeada dessa forma, o nome dessa função é livre para a implementação.
   7. Observações sobre os cenários possíveis de uso:
      1. A função isBlind() verifica a existência de uma interface Protheus na execução, caso exista a interface o valor retornado será .F., caso contrário será .T. como em cenários do Totvs Departamento Jurídico.
      2. Se o oJson estiver vazio e isBlind() = verdadeiro: Indica ambiente Totvs Departamento Jurídico e Visualização pelo GRID, utilizando posicionamento via tabela desejada (No exemplo acima é NUQ) para obter os valores dos campos.
      3. Se o oJson estiver vazio e isBlind() = falso: Indica ambiente Protheus, utilizando o modelo ativo (FWModelActive) para obter os campos atualizados.
      4. Se o oJson estiver preenchido: Indica ambiente Totvs Departamento Jurídico, utilizando os campos do formulário através do parâmetro oJson.
      5. Para todos os cenários indicamos o uso da função Empty() para validar o valor antes de inserir na query, evitando comportamentos indesejados.
3. Exemplo de uso:
   1. Ao acessar a tela de despesa, nenhum dado foi preenchido, assim o campo de consulta retorna todos os valores. Importante: Por padrão é filtrado os registros não deletados e que estejam na filial correspondente ao do usuário.
      Image Added
   2. Ao digitar no campo de caractere (NT3_XCARAC), onde foi digitado a palavra "requeijao" e ao consultar novamente é retornado os produtos que contenham "REQUEIJAO" em sua descrição
      Image Added
4. Exemplo de uso considerando grid: 

a. Ao acessar a tela de instâncias, sem nenhum dado preenchido, o campo de consulta retorna com todos os valores disponíveis:

Image Added

b. Ao digitar no campo de caractere (NUQ_XCARAC), inserindo a palavra "Banco" e consultando novamente, são retornados os dados que contenham "BANCO" em sua descrição:

Image Added

c. Ao "alterar instância", é possível visualizar os campos customizados no grid de instâncias, nos detalhes do processo:

Image Added

07. Restrições

Atualmente essas configurações da JURSXB estão disponíveis para qualquer campo F3 que implemente as configurações citadas na seção 03.

1. Filtro por posicione:
   1. Restrição por posicionamento pela NSZ apenas.
2. Filtro por funções:
   1. Necessário que a função customizada retorne uma condição SQL sem o AND no início. 
3. Filtro por funções com formulário:
   1. Necessário que a função customizada retorne uma condição SQL sem o AND no início. 
   2. Apenas campos caracteres, sendo de campos padrão e/ou campos customizados.
   3. Está disponível apenas para campos customizados.
   4. Esse filtro necessita de algumas proteções para visualização por grid, execução por protheus e quando executado pelo Totvs Departamento Jurídico.
   5. Os campos disponíveis para filtro em cada entidade foram sinalizados no documento técnico de cada entidade, indicado na Seção 02.

08. Assuntos relacionados

Consultas Específicas

JURSXB() - Configurações para consulta específica

JUR0093_Campos adicionais no TOTVS Jurídico Departamentos

...