Integração com repositórios de arquivos: diretórios de origem e de saída
Um repositório de arquivos é o lugar onde os sistemas da sua empresa guardam arquivos: um servidor SFTP ou FTP, um bucket do Amazon S3, um container do Azure Blob Storage ou um bucket do Google Cloud Storage. Ligando o repositório a um processo, você deixa de enviar e baixar arquivos à mão:
o Diretório de Origem diz de qual pasta do repositório a execução automática busca os arquivos de cada fonte de dados;
o Diretório de Saída diz em qual pasta do repositório o processo entrega os arquivos gerados pelas etapas de exportação.
As duas telas ficam nas configurações do processo e existem apenas em processos Turbo AI.
Antes de começar
A integração entra no fim da montagem do processo, não no começo. Ela não ajuda a construir o fluxo: só passa a funcionar depois que o fluxo está pronto e publicado.
Cadastre a conexão com o repositório em Configurações › Geral › Credenciais. Veja Repositórios de arquivos: quais a Dattos conecta e como cadastrar.
Monte o fluxo inteiro com um arquivo de amostra que você já tem em mãos. Cada etapa de fonte de arquivo precisa de uma amostra enviada do seu computador para definir colunas e tipos. A integração não serve para trazer essa amostra: não dá para montar a fonte a partir de um arquivo que ainda está só no repositório.
Publique o fluxo. As linhas do Diretório de Origem e do Diretório de Saída são montadas a partir da versão publicada. Enquanto o fluxo não for publicado, as telas aparecem vazias ou sem as etapas novas.
Crie a regra de automação do processo (agendada, por gatilho ou por chamada de API). É ela que faz a plataforma ir até o repositório buscar os arquivos.
Três regras que valem para o Diretório de Origem
Primeiro o fluxo, depois a integração. Sem fluxo publicado, não há fonte para ligar a uma pasta. A integração também não substitui o arquivo de amostra que a montagem do fluxo pede.
A plataforma não mostra o que há na pasta. Ao configurar, você escolhe pastas, nunca arquivos, e não consegue abrir nem pré-visualizar os arquivos que estão no repositório. Para conferir o conteúdo, use as ferramentas do próprio repositório.
Só a execução automática busca os arquivos. Se você executa o processo à mão, a plataforma usa apenas os arquivos que você enviar na tela e ignora o repositório.
Na execução manual, o repositório fica de fora. Para testar a integração, dispare a regra de automação. Uma execução manual com sucesso não prova que a busca no repositório está funcionando.
Diretório de Origem: de onde vêm os arquivos
Cada linha da tela é uma combinação de pasta de execução e fonte de dados de arquivo do fluxo publicado (Excel, texto, OFX, PDF, XML, JSON e similares). Fontes que não são arquivo, como API, banco de dados ou ERP, não aparecem aqui.
Configurar a origem de uma fonte
Nas configurações do processo, abra Diretório de Origem.
Na linha da pasta de execução e da fonte, clique em Editar (ícone de lápis).
Clique em Adicionar destino.
Em Integração de Armazenamento, escolha o repositório cadastrado. O botão … ao lado abre o cadastro de credenciais em outra aba.
Em Pastas de Importação, escolha uma ou mais pastas do repositório.
Defina o que acontece se faltar o arquivo no disparo (veja a seção mais abaixo).
Clique em Salvar. A linha passa a mostrar Configurado.
Uma mesma fonte pode buscar arquivos em mais de um repositório (um destino para cada) e em várias pastas de cada repositório.
Quais arquivos a automação pega
Todos os arquivos da pasta escolhida entram na execução. Não há filtro por nome nem por extensão. Se a pasta tiver três arquivos, os três são carregados na mesma fonte. Use uma pasta exclusiva para cada fonte.
A pasta decide a fonte, não o conteúdo do arquivo. As Regras de Identificação de Arquivos do fluxo valem só no envio manual, na tela de upload. Na busca pelo repositório, todo arquivo da pasta vai para a fonte ligada a ela.
Só os arquivos que estão direto na pasta. As subpastas não são lidas. Se os arquivos ficam em subpastas, escolha cada subpasta em Pastas de Importação.
O conteúdo precisa bater com a extensão. Um arquivo de texto renomeado para
.xlsx, por exemplo, é recusado e a execução daquela pasta termina com erro.
O que acontece com os arquivos no repositório
A plataforma move os arquivos que lê para subpastas criadas dentro da própria pasta de origem:
Subpasta | Quando o arquivo vai para lá |
|---|---|
| Enquanto a execução lê o arquivo |
| Quando a execução da pasta termina com sucesso |
| Quando a execução da pasta termina com erro. Todos os arquivos daquela execução vão para cá, inclusive os que ainda não tinham sido lidos |
Na prática:
a pasta de origem fica vazia depois de cada execução, pronta para receber o próximo arquivo;
para executar de novo um arquivo que deu erro, corrija a causa e mova o arquivo de volta da
.errorpara a pasta de origem;essas subpastas não aparecem na lista de pastas da plataforma, para não serem escolhidas por engano;
se outro sistema da sua empresa também lê aquela pasta, ele não vai mais encontrar o arquivo depois que a Dattos o processar.
Se faltar o arquivo no disparo
Para cada fonte, escolha o que a execução automática faz quando não encontra arquivo na pasta:
Não executar o processo (padrão): o processo não é executado para aquela pasta de execução. Os dados já processados na data de referência ficam preservados.
Executar sem esta fonte: o processo é executado normalmente, sem a fonte que faltou.
A escolha aparece na coluna Se faltar o arquivo no disparo: Processo não executa ou Executa mesmo sem esta fonte.
Por que o padrão é não executar: numa execução automática que substitui os dados da data, uma pasta vazia faria o processo recalcular a data sem aquela fonte e apagar o que já estava conciliado.
A proteção vale apenas quando as três condições se somam:
a fonte é de arquivo;
a execução é automática, disparada por uma regra de automação;
o modo de importação é Substituir.
O modo Atualizar não é bloqueado, porque ele acrescenta dados em vez de recalcular a data.
Para a proteção, conta qualquer arquivo que esteja na pasta no momento do disparo, mesmo que não seja novo. Ela evita a pasta vazia, mas não identifica um arquivo desatualizado.
Quando o processo não é executado
A data de referência aparece na Gestão de importações com o status Não executada, e o motivo indica qual fonte ficou sem arquivo. Nesse caso, nenhum arquivo é movido: coloque o arquivo que faltou na pasta e aguarde o próximo disparo.
Dica: o status Não executada também aparece quando a execução é travada pelo fluxo de aprovação. Leia o motivo para saber qual das duas situações aconteceu.
Quando a data de referência vem do arquivo
Desde a versão 16.6, uma fonte de arquivo pode usar a Data de referência na fonte: você indica uma coluna de data e cada data distinta do arquivo gera um carregamento próprio. Com o repositório, isso muda duas coisas:
A data da regra de automação deixa de valer. O disparo continua seguindo o agendamento, mas as datas processadas são as que estão no arquivo, e não a data calculada pelo calendário da regra. Numa chamada por API, não informe a data de referência: a plataforma recusa a chamada.
Um arquivo pode atualizar várias datas de uma vez. Basta colocar na pasta um arquivo com o período inteiro.
Diretório de Saída: para onde vão os arquivos exportados
Cada linha da tela é uma combinação de pasta de execução e etapa de exportação que gera arquivo no fluxo publicado: Exportação Excel, Exportação Arquivo Texto e Exportação de Documento. A Exportação Banco de Dados grava direto numa tabela e não aparece nesta tela.
Sem Diretório de Saída configurado, o arquivo continua disponível para baixar no painel de exportações da execução. Com ele, o arquivo também é gravado no repositório.
Configurar a saída de uma exportação
Nas configurações do processo, abra Diretório de Saída.
Na linha da pasta de execução e da exportação, clique em Editar.
Clique em Adicionar destino.
Em Integração de Armazenamento, escolha o repositório.
Em Pastas de Exportação, escolha uma ou mais pastas.
Clique em Salvar.
Se você configurar mais de um destino, o mesmo arquivo é gravado em todos eles. Isso atende, por exemplo, quem precisa guardar uma cópia no bucket da empresa e outra no SFTP de um parceiro.
Como o arquivo chega ao repositório
O nome do arquivo vem da etapa de exportação, pelo campo Padrão de nome do arquivo. Se dois arquivos saírem com o mesmo nome, o novo substitui o anterior na pasta. Para guardar o histórico, use variáveis como
{referenceDate:yyyyMMdd}ou{timestamp}no padrão do nome.A entrega acontece a cada vez que a etapa de exportação roda, numa execução manual ou automática.
Com a Data de referência na fonte, cada data gera o seu próprio arquivo de saída. Se o padrão do nome não tiver
{referenceDate}, o arquivo de cada data substitui o da data anterior e só o último fica na pasta.Se a gravação no repositório falhar, a etapa de exportação termina com erro e a mensagem aparece no registro da execução.
Cuidados que evitam surpresas
Configure a origem de todas as fontes de arquivo. Num processo com execução automática, a boa prática é que toda fonte de arquivo do fluxo tenha o seu Diretório de Origem configurado, para que cada execução traga os dados completos.
Renomear uma etapa desfaz a ligação. A configuração fica presa ao nome e ao tipo da etapa. Se você renomear a fonte ou a exportação no fluxo e publicar, a linha antiga passa a mostrar Fonte de dados não encontrada (origem) ou Step não encontrado (saída), e a etapa com o nome novo aparece como Não configurado. Configure a linha nova.
Pastas renomeadas ou apagadas no repositório. Ao abrir o editor, a plataforma avisa quando uma pasta salva na configuração não existe mais no repositório. Escolha a pasta nova e salve.
Repositório indisponível. Se a credencial for desativada ou excluída, ou se você não tiver acesso a ela pelo seu perfil de privacidade, o editor mostra Integração indisponível: credencial excluída, inativa ou sem acesso.
Pasta nova no repositório. A lista de pastas é lida do repositório quando você abre o editor e pode levar alguns instantes para mostrar uma pasta recém-criada. Feche e abra o editor de novo.
Duas execuções ao mesmo tempo para a mesma pasta de execução e data de referência não rodam juntas: a segunda termina com erro de execução simultânea.
Envio manual pendente com o mesmo nome. Se houver um arquivo enviado à mão, ainda não processado, com o mesmo nome de um arquivo encontrado no repositório, a automação descarta o envio manual e usa o do repositório.
Problemas comuns
O que você vê | O que fazer |
|---|---|
A tela do diretório está vazia | Publique o fluxo. Se já está publicado, confira se ele tem fonte de arquivo (origem) ou etapa de exportação que gera arquivo (saída). |
O repositório não aparece em Integração de Armazenamento | Confira se a credencial está ativa e se o seu perfil de privacidade tem acesso a ela no cadastro de credenciais. |
Erro ao carregar as pastas | Os dados de acesso estão errados ou o repositório não aceita a conexão. Revise a credencial seguindo o tutorial do seu tipo de repositório. |
Executei o processo à mão e ele não pegou o arquivo do repositório | É o comportamento esperado: só a execução automática busca arquivos. Na execução manual, envie o arquivo na tela. |
O arquivo sumiu da pasta | Procure nas subpastas |
Status Não executada | Veja o motivo na Gestão de importações: falta de arquivo na pasta ou bloqueio do fluxo de aprovação. |