Log de registros: quem incluiu e quem alterou um cadastro

Quem tenta descobrir “quem mudou este produto?” com um SELECT no campo de log leva um susto: o que volta é um texto embaralhado, sem login nem data legível. E quem procura o campo pelo nome às vezes não acha, porque ele se chama B1_USERLGI no cadastro de produtos, mas CT2_USERGI nos lançamentos contábeis. As duas coisas têm explicação, e as duas têm saída.

Os campos são dois, na própria tabela: um guarda quem incluiu o registro e quando; o outro, quem fez a última alteração e quando. Para lê-los sem programar, existe a rotina Log de Registros (CFGX025), que não vem no menu do Configurador do Protheus 12 e precisa ser adicionada à mão. Para lê-los num fonte, existe a função FWLeUserlg.

Limites que vale saber antes de começar:

• é um usuário por campo. Você sabe quem incluiu e quem alterou por último, não o histórico de todas as alterações;
• a tabela precisa ter os campos. Tabela sem eles não tem o que mostrar;
• o que aconteceu antes de os campos existirem não aparece. Registro antigo fica sem log;
• inclusão dentro de transação pode aparecer em dobro. A documentação da TOTVS explica: se um registro é inserido no início de uma transação (BEGIN TRANSACTION) e o número do registro (RECNO()) é solicitado, o DBAccess inclui o registro marcado como excluído e o recupera em seguida. A rotina de log grava então dois registros, um de inclusão e outro de alteração, e a TOTVS trata isso como comportamento esperado, não erro.

São campos reservados do dicionário, do tipo caractere, com 17 posições e reais (existem no banco). No dicionário padrão, quase todos ficam fora do browse (X3_BROWSE = N), com poucas exceções, e o título mais comum é “Log de Inclu” e “Log de Alter”. Há tabelas com variações, como “Log Inclusao” e “Log Alteraca”, por isso a consulta abaixo procura pelo nome do campo, e não pelo título.

O nome muda conforme o prefixo da tabela, porque nome de campo no Protheus tem no máximo 10 caracteres:

B1_USERLGI tem 10 caracteres. CT2_USERLGI teria 11 e não cabe, por isso o padrão usa CT2_USERGI.

A mesma conta vale para uma tabela customizada. No cadastro de motoristas ZA1 desta série, os campos são ZA1_USERGI e ZA1_USERGA.

Passo 1: ver quais tabelas já têm log

Antes de ativar qualquer coisa, pergunte ao dicionário. A consulta lista as tabelas com os campos de log nos dois formatos de nome. O sufixo 010 é o da empresa: troque pelo do seu ambiente, porque ele varia por empresa.

SELECT X3_ARQUIVO, X3_CAMPO, X3_TAMANHO, X3_TITULO, X3_CONTEXT
  FROM SX3010
 WHERE (X3_CAMPO LIKE '%USERLGI' OR X3_CAMPO LIKE '%USERLGA'
     OR X3_CAMPO LIKE '%USERGI'  OR X3_CAMPO LIKE '%USERGA')
   AND D_E_L_E_T_ = ' '
 ORDER BY X3_ARQUIVO, X3_CAMPO

Confira se a tabela que você quer auditar aparece com as duas linhas, uma de inclusão e outra de alteração, com X3_TAMANHO 17 e X3_CONTEXT R. Não conte com isso: no dicionário padrão há tabelas com só um dos dois campos, quase sempre o de inclusão.

• Nenhuma linha: a tabela não tem log. Siga para o passo 2.
• Só uma linha: o log está pela metade. Siga para o passo 2 e crie o que falta.
• As duas linhas: pule para o passo 3.

Passo 2: criar os campos na tabela

A ativação é pelo dicionário. O roteiro da TOTVS:

1. No Configurador, em Base de Dados > Dicionário > Bases de Dados, acesse a tabela que terá os registros auditados.
2. Em Campos, clique no último botão, Campos Reservados.
3. Marque Log de Inclusão e clique em Finalizar.
4. Abra de novo os Campos Reservados, marque Log de Alteração e clique em Finalizar.
5. Na listagem de campos, clique em Confirmar. Na listagem de tabelas, clique em Atualizar base de dados e avance até Finalizar.

Os outros campos reservados (bloqueio e imagem) e o que cada um faz estão em Campos reservados: log de inclusão e alteração, bloqueio e imagem. Para tabela nova, veja antes Tabela customizada no Protheus.

Por que o SELECT mostra caracteres sem sentido

A primeira tentativa de quase todo mundo é consultar o campo direto no banco:

SELECT B1_COD, B1_USERLGI, B1_USERLGA
  FROM SB1010
 WHERE D_E_L_E_T_ = ' '

O que volta não é um login nem uma data legível. É um texto embaralhado, com caracteres que não formam palavra. Customizações antigas desembaralhavam o campo com Subs(Embaralha(A1_USERLGI, 1), 1, 15). A documentação da TOTVS diz que a função FWLeUserlg substitui esse comando, e que a troca é necessária para ler corretamente o campo quando o que está gravado é o ID do usuário ou o nome.

Para ler, há dois caminhos: a rotina Log de Registros (passo 3) ou a função FWLeUserlg num fonte (passo 4).

No Protheus 12, a rotina CFGX025 precisa ser adicionada manualmente ao menu do Configurador. O roteiro de personalização de menu da TOTVS, aplicado ao próprio Configurador:

1. No Configurador, acesse Ambiente > Cadastros > Menus.
2. No rodapé, clique em Todos os menus para desmarcar tudo, marque só o módulo do Configurador e clique em OK.
3. Na coluna do meio, clique em Adicionar.
4. Do lado direito, clique na pasta e na subpasta onde o item vai ficar e clique em Novo item. Preencha Descrição, Programa (CFGX025), Módulo e Tabelas e clique em OK.
5. Clique em Gerar. Em Arquivo, informe SIGACFG para sobrescrever o menu padrão, ou outro nome para criar um menu novo, e clique em Gerar.

Os detalhes de cada campo do item de menu estão em Menus do Protheus: como incluir uma rotina.

Recomendação: crie uma subpasta própria para auditoria e ponha ali o Log de Registros. Não existe nome obrigatório, mas uma pasta separada deixa claro que aquilo não é rotina de uso diário.

Com o item no menu:

1. Abra a rotina e selecione a tabela em que você ativou os campos de log. O relatório só é exibido se houve alguma inclusão ou alteração na tabela depois da configuração.
2. Na tela seguinte, selecione o registro e clique em Visualizar. Abre a janela do log do registro, com o último usuário que incluiu ou alterou, a data, e se o registro foi excluído.

Passo 4: ler o log num fonte com FWLeUserlg

Quando a informação precisa aparecer num relatório ou numa tela própria, use FWLeUserlg. Pela documentação da TOTVS, ela recebe o nome do campo e, opcionalmente, o tipo de informação: 1 para o usuário e 2 para a data. O retorno é caractere.

#Include "Protheus.ch"

/*/{Protheus.doc} ZLOGPRD
Mostra quem incluiu e quem alterou por último um produto.
@type user function
@param cCodProd, character, código do produto (B1_COD)
/*/
User Function ZLOGPRD(cCodProd)

    Local aArea  := GetArea()
    Local cTexto := ""

    SB1->(DbSetOrder(1)) // B1_FILIAL + B1_COD
    If SB1->(DbSeek(xFilial("SB1") + cCodProd))
        cTexto := "Incluído por " + FWLeUserlg("SB1->B1_USERLGI", 1) + ;
                  " em " + FWLeUserlg("SB1->B1_USERLGI", 2) + CRLF + ;
                  "Alterado por " + FWLeUserlg("SB1->B1_USERLGA", 1) + ;
                  " em " + FWLeUserlg("SB1->B1_USERLGA", 2)
        MsgInfo(cTexto, "Log do produto " + AllTrim(cCodProd))
    EndIf

    RestArea(aArea)

Return

Dois detalhes do exemplo:

• O campo é passado como texto, com o alias na frente ("SB1->B1_USERLGI"), e o registro precisa estar posicionado. É assim que rotinas da própria TOTVS chamam a função. A documentação também mostra a forma sem alias ("A1_USERLGI").
• A função devolve o que está gravado no campo, não o usuário logado. Para saber quem está usando o sistema agora, a função é outra.

O exemplo segue a assinatura documentada e o uso das rotinas da TOTVS, mas não foi executado para este artigo. Rode em homologação antes de levar para produção. GetArea e RestArea estão explicados em GetArea e RestArea.

O log de registros responde “quem foi o último”. Se a pergunta é “o que mudou, de quanto para quanto, e quem mexeu antes”, ele não resolve: o campo de alteração é sobrescrito a cada gravação.

A ferramenta para essa pergunta é o Embedded Audit Trail. A TOTVS o descreve como uma das principais ferramentas de auditoria do Protheus, capaz de rastrear logs de uso e modificações em tabelas, dicionários e usuários. Nas releases mais recentes, ele passa a ser a ferramenta central de auditoria e substitui as demais, inclusive o Log de Campos (CFGX052, consultado pela CFGX053), que foi descontinuado.

Três diferenças documentadas em relação às rotinas antigas ajudam a decidir:

• a auditoria é feita por gatilho no banco de dados, então qualquer alteração feita direto no banco também é auditada;
• campos cujo conteúdo não mudou não são auditados;
• a auditoria é da operação no campo, e não da rotina.

Por onde começar, para uma tabela de cadastro sua:

1. Na Política (CFGA500), as auditorias de dicionário e de usuário são ligadas nas regras de auditoria, e pela documentação passam a ser feitas pelo Embedded Audit Trail. Elas cobrem dicionário e usuários, não os seus cadastros.
2. Para os seus cadastros, o primeiro passo é selecionar a tabela na rotina FWCFGAUDIT, a seleção manual de tabelas para auditoria. A documentação avisa que, com a auditoria de dicionário ou de usuário marcada, as tabelas dessas auditorias não podem ser selecionadas manualmente.
3. Para consultar, o relatório CFGR710 traz as alterações de dicionários, de usuários e das outras tabelas marcadas para auditoria.

A configuração completa (aplicador, tablespaces, relatórios) está na documentação do Embedded Audit Trail, nas referências.