Em Desenvolvimento
Esta documentação ainda está em desenvolvimento. Agradecemos sua paciência!
Pular para o conteúdo principal
Versão: 03.008.000 🚧 (em desenvolvimento)

Migração do legado

Quando a guarda é ativada, o repositório já tem um acervo antigo, com metadados próprios do cliente (datas, classificações, códigos de destinação) em propriedades que nada têm a ver com o vocabulário da guarda. A migração faz a ponte: lê essas propriedades e as traduz para os dados que a guarda entende (temporalidade, digitalização, conferência e, opcionalmente, campos descritivos), ou delega a decisão inteira a uma classe do plano de classificação.

A migração não altera o conteúdo dos documentos nem os move: só grava metadados, de forma aditiva (nunca sobrescreve o que já existe), sobre documentos que já estão no repositório fora da guarda.

Licença: depende da licença do módulo GCVD e da capacidade Gerenciar a tabela de temporalidade. Ver Licenciamento.

No console, o grupo Migração de metadados tem duas telas:

  • Perfis (de-para): onde se cadastra a regra de tradução, ou seja, qual propriedade do legado vira qual campo da guarda.
  • Aplicar migração: onde se executa a simulação (dry-run) e, depois, a migração de fato sobre um site ou pasta.

Montar o perfil de migração​

Um perfil é a unidade de tradução: "documentos que casam com X, migre assim". Vários perfis podem estar ativos ao mesmo tempo, e cada documento é associado ao primeiro perfil da lista cujo seletor casa; por isso a ordem de cadastro importa quando os seletores se sobrepõem.

Cabeçalho​

  • Nome do perfil: identificação livre.
  • Ativo: perfil inativo é ignorado pela varredura (simulação e aplicação). Serve para desligar um de-para sem apagá-lo.
  • Selector (quais nós casam): define quais documentos o perfil atinge, em três modos:
    • Tipo do nó: lista de tipos de conteúdo; comparação exata.
    • Aspecto: lista de aspectos; casa se o documento tem o aspecto.
    • Propriedade: texto no formato propriedade=valor (por exemplo prefixo:nome=Contrato); casa se o documento tem a propriedade com exatamente aquele valor.

O seletor por propriedade compara por igualdade exata, sensível a maiúsculas e minúsculas: "Contrato" e "contrato" são valores diferentes. Um seletor mal digitado simplesmente não casa nenhum documento, sem aviso.

Destino​

Cada perfil escolhe um de dois caminhos:

  • Retenção (direto): o perfil grava a temporalidade (prazo, data-base, destinação) diretamente no documento.
  • Classe: o perfil delega a temporalidade a uma classe do plano de classificação (ver Classificação), que carrega prazo, destinação e fase intermediária. O documento migrado fica re-aplicável depois, como qualquer documento classificado.

Quando o destino é Classe, aparece a aba Classe; quando é Retenção, valem os campos da aba de temporalidade.

Aba Classe (destino = Classe)​

  • Modo da classe:
    • Classe fixa: todo documento que casar o seletor vai para uma única classe, informada pelo código da classe (por exemplo RH.CONTRATOS).
    • Por valor: a classe varia conforme o valor de um campo do legado. Informa-se a propriedade e um mapa valor para classe, com uma linha por valor, adicionadas e removidas livremente.
  • Se o campo do legado trouxer um valor sem mapeamento, o documento fica para revisão manual, em vez de receber uma classe arbitrária.
  • Também é possível informar uma data-base (fixa ou lida de um campo do legado). Ela não muda prazo nem destinação (que vêm da classe); apenas posiciona o documento na fase correta da linha do tempo pelo tempo já decorrido.

Aba Temporalidade (destino = Retenção)​

  • Propriedade de prazo (legado): campo do legado com a duração da retenção, em meses ou anos (escolha a unidade ao lado).
  • Fase intermediária (meses, fixo): valor fixo do perfil, já que o acervo antigo raramente registra a segunda idade documental. Zero ou vazio significa sem fase intermediária.
  • Propriedade de data-base (legado): campo com a data a partir da qual o prazo conta. Se ficar vazia e sem fallback, o documento entra em guarda aguardando um evento: sem data-base, sem expiração, até alguém registrar o corte (ver Temporalidade e retenção).
    • Fallback para a data de criação: quando marcado e o campo de data-base vier vazio, usa a data de criação do documento no repositório.
  • Data-base fixa: opcional; uma única data (aaaa-mm-dd) aplicada a todos os documentos do perfil. Útil quando todo o lote compartilha o mesmo marco. Prefira um campo de data do legado quando existir.
  • Propriedade de expiração existente (legado): se o legado já registra uma data de vencimento válida, o motor copia esse valor em vez de recalcular, respeitando a retenção já decidida no sistema antigo.
  • Base legal do prazo (legado): campo com a base legal do prazo; se vier vazio, usa o fallback fixo do perfil (uma base legal única para toda a série). O valor é gravado no documento e aparece no relatório de temporalidade e no termo de eliminação.
  • Propriedade de destinação (legado): campo com o destino final do documento.
  • De-para dos valores de destinação: uma linha por par ORIGEM=CANÔNICO, convertendo os códigos do legado para os dois valores da guarda: Eliminar ou Permanente. Diferentemente do seletor, este de-para normaliza maiúsculas, minúsculas e acentuação antes de comparar.
  • Datas sentinela: lista, separada por vírgula, de datas-placeholder (por exemplo 2000-01-01) que o legado usa como "vazio". Qualquer data-base, expiração ou data de classe que coincida com uma sentinela é tratada como vazia.

Se o campo de prazo não estiver preenchido no perfil, a aba de temporalidade não participa da migração daquele perfil, e os documentos recebem apenas metadados (ver "Tipos de plano").

Aba Digitalização​

Porta, de forma opcional, os dados de digitalização, incluindo o tipo documental: Tipo documental, Assunto, Data de digitalização, Digitalizado por, Local de digitalização e Fuso horário. Cada campo pode ser:

  • não migrar: o campo é ignorado;
  • Seletor: lê o valor de uma propriedade do legado; se vier vazia, pode cair num valor fixo de fallback;
  • Valor fixo: grava sempre o mesmo valor (campos de data aceitam now para "agora").

O tipo documental sai desta aba, e não da aba Classe, mesmo quando o destino é Classe.

Aba Conferência​

Porta, de forma opcional, os dados da conferência (mesmo padrão seletor ou fixo): Conferente, Resultado da conferência, Conferido por, Conferido em e Observações da conferência. Serve para tratar o acervo legado como já conferido, evitando que ele entre na fila de conferência junto com a captura nova.

Aba Descritivos (core)​

Porta, de forma opcional, os campos descritivos nativos do repositório: Autor, Título e Descrição (mesmo padrão seletor ou fixo). Fica separada da aba Digitalização porque o autor de um documento é um dado do núcleo do repositório.

Validando o perfil​

Depois de salvar, o perfil aparece na lista com Nome, Selector, Destino, chaves de destinação, prazo e expiração e Ativo preenchidos. Um perfil com destino Classe sem código de classe (modo fixo), ou sem campo do legado e sem nenhum mapeamento de valor (modo por valor), é recusado ao salvar, com aviso de destino incompleto. Um perfil com Ativo igual a Não continua na lista, mas fica de fora da simulação e da aplicação.

Tipos de plano e a ordem de decisão​

Para cada documento que casa um perfil, o motor decide um plano de migração, que é o que faria se fosse aplicado agora. Os rótulos exibidos na tela são: Copiar, Calcular, Por evento, Revisar, Já tem, Metadados e Classificar, além de Sem perfil, quando nenhum perfil casa o documento.

A decisão segue esta ordem, documento a documento:

  1. O documento casa algum perfil ativo? Se nenhum seletor casa, o resultado é Sem perfil.
  2. O perfil tem destino Classe? Se sim, a decisão sai inteiramente deste ramo:
    • resolve o código da classe (fixo ou pelo mapa valor para classe); se não achar uma classe válida, o plano é Revisar;
    • se o documento já está classificado, o plano é Já tem (trocar de classe é reclassificação, não migração);
    • caso contrário, o plano é Classificar: o documento recebe a classe (e a temporalidade dela), a data-base (se mapeada) e os metadados de digitalização, conferência e descritivos do perfil.
  3. O perfil (destino Retenção) não define de-para de temporalidade (sem propriedade de prazo)? Se há metadados de digitalização ou conferência mapeados e ausentes no documento, o plano é Metadados; se não há nada a portar, Revisar.
  4. O documento já está em guarda? Se já tem temporalidade em qualquer estado, inclusive aguardando evento, o plano é Já tem: a guarda já decidida não é recalculada nem sobrescrita. Metadados de digitalização e conferência ausentes ainda são portados.
  5. Resolvidas destinação e prazo, se o legado já tem uma expiração válida, o plano é Copiar.
  6. Sem expiração legada e sem prazo mapeado, o plano é Revisar.
  7. Com prazo e data-base resolvida (do campo, do fallback de criação, ou sem ser descartada como sentinela), o motor calcula data-base mais prazo e o plano é Calcular.
  8. Com prazo e sem data-base, o plano é Por evento: o documento entra em guarda sem expiração, aguardando o corte.
  9. Se a destinação do legado veio preenchida mas não casa nenhuma linha do de-para, o plano vira Revisar. A exceção é quando o passo 4 já havia decidido Já tem.

Um plano que não gravaria temporalidade (Já tem, Revisar, Classificar) ainda pode portar metadados de digitalização ou conferência ausentes; quando esse é o único efeito real, a simulação e o histórico classificam o item como Metadados.

Ler a simulação (dry-run)​

Na tela Aplicar migração, com o escopo escolhido, Rodar dry-run varre os documentos e simula, sem gravar nada, o que a migração faria.

O resumo mostra quantos documentos caíram em cada plano que escreve algo (Classificar, Copiar, Calcular, Por evento, Metadados), além dos totais varridos e de Sem perfil. A tabela de prévia traz: Documento, Pasta, Perfil, Temporalidade (o tipo de plano), Prazo, Data-base, Expiração, Destinação, Base legal, Metadados, Nota (motivo do plano, por exemplo "base vazia: aguarda cutoff") e Detalhes (botão Ver, com o plano completo, incluindo a base legal resolvida).

A tabela lista apenas uma amostra (cerca de 2000 itens); quando o escopo é maior, a tela avisa que a listagem é parcial, mas os contadores do resumo cobrem toda a varredura.

Diagnosticar "Sem perfil"​

  1. O seletor por propriedade não casou por exatidão ou caixa. Diferente do de-para de destinação, o seletor é exato e sensível a maiúsculas e minúsculas.
  2. O item não é um documento elegível. A migração considera apenas conteúdo (não pastas) e exclui artefatos técnicos da guarda, como o arquivo de assinatura destacada. Um documento já assinado fica fora da migração de temporalidade.
  3. Nenhum perfil ativo descreve aquele documento. Verifique se tipo, aspecto ou propriedade do seletor existem, com aquele valor, no acervo.

Aplicar a migração​

Escopo​

  • Site inteiro: aponta para a biblioteca de documentos do site e sempre percorre toda a subárvore. Nunca inclui sites de guarda ou gestão documental.
  • Pasta específica: escolhida por seletor de pasta; a opção recursivo define se a varredura desce às subpastas.

Quando o botão Aplicar é liberado​

O botão só é habilitado quando as três condições valem ao mesmo tempo:

  1. Existe um dry-run para este mesmo escopo (mesmo site ou pasta, com a mesma opção de recursivo). Mudar o escopo invalida a simulação anterior.
  2. A simulação encontrou algo a migrar: a soma de Classificar, Copiar, Calcular, Por evento e Metadados é maior que zero.
  3. Não há outra migração nem preservação em execução. As duas operações compartilham a mesma trava de execução exclusiva.

Se o botão não libera, a tela explica o motivo: pede para rodar a simulação, avisa que não há nada a fazer no escopo ou informa que há uma execução em andamento.

Duas opções acompanham o Aplicar, válidas só para perfis com destino Classe:

  • não exigir conferência nesta carga (legado): ligada por padrão; trata o lote como já revisado, sem empurrar tudo para a fila de conferência;
  • pular documentos já em guarda/dossiê: ligada por padrão; evita reprocessar o que já está sob outra forma de guarda.

Confirmado o Aplicar, a migração roda em segundo plano. A tela pode ser fechada e reaberta sem perder o andamento, e a execução tem log e auditoria.

Validar depois de aplicar​

O Histórico de execuções lista cada rodada com Status e os contadores Total, Aplicados, Pulados e Erros. Em uma execução concluída com sucesso, os números devem bater com a simulação. Pulados cobre os planos Já tem e Revisar; Erros aponta itens que falharam na gravação.

Ressalvas:

  • Documentos "Já tem" ou "Revisar" contam como pulados na temporalidade, mas podem ter ganhado metadados; nesse caso o item aparece como Metadados. São dois efeitos independentes do mesmo perfil.
  • A escrita é aditiva e idempotente: só grava onde o campo está vazio. Reaplicar um perfil não corrige um valor gravado errado. Para corrigir, apague o valor errado antes de reaplicar ou use um segundo perfil dedicado à correção.
  • A data de modificação do documento não muda com a migração. Use a auditoria e o histórico de execuções para saber quais documentos passaram pela carga.

Depois da migração​

Itens em Revisar ou Por evento não fecham o ciclo do documento: ele entrou (ou não) em guarda com temporalidade incompleta. O próximo passo é a fila validade a confirmar (ver Temporalidade e retenção), que lista essas pendências e permite resolver em lote ou documento a documento, registrando o corte dos que aguardam evento ou completando prazo, base e destinação dos que ficaram para revisão.

Capacidade e execução exclusiva​

As duas telas exigem a capacidade Gerenciar a tabela de temporalidade, a mesma usada para prazos e para a fila de pendências. A migração compartilha com a preservação de longo prazo a mesma trava de execução exclusiva: uma migração em curso impede o início de uma preservação, e vice-versa.