Se você ainda perde horas digitando cadastro por cadastro no Protheus, vale fazer uma pausa e conhecer um recurso que muita gente simplesmente ignora no dia a dia: o M.I.L.E..
Essa ferramenta padrão do TOTVS Protheus permite importar dados em massa de forma nativa, basta apenas configurar um layout de importação diretamente no configurador e, em muitos cenários, sem escrever uma linha de código AdvPL.
Na prática, isso significa sair de um processo manual e demorado para uma rotina muito mais rápida, segura e escalável. Principalmente em implantações, carga inicial de cadastros ou integrações simples com arquivos texto.
O que é o M.I.L.E. no Protheus
M.I.L.E. é a sigla para Motor de Layout para Integração de Modelos.
O nome pode parecer mais complexo do que realmente é. A ideia é bem simples: você define um layout de arquivo, informa como cada campo do TXT deve ser interpretado e o Protheus processa esse conteúdo como se alguém estivesse preenchendo a rotina manualmente.
Pense em um cadastro de clientes. Em vez de abrir a rotina e preencher código, loja, nome, tipo de pessoa, endereço, estado, município e assim por diante, você organiza essas informações em um arquivo texto. Depois, entrega esse arquivo ao M.I.L.E., que lê o layout, interpreta os campos e grava os registros no banco.
É exatamente esse tipo de recurso que faz diferença quando você precisa incluir dezenas, centenas ou até milhares de registros.
Quando o M.I.L.E. faz mais sentido
O uso do M.I.L.E. é especialmente útil em situações como:
- Implantação de ambiente novo, quando há muitos cadastros iniciais para subir.
- Migração de dados vindos de outro sistema ou base legada.
- Carga em massa de registros como clientes, fornecedores e outros cadastros.
- Redução de esforço manual, evitando digitação repetitiva.
- Padronização da importação, mantendo o processo replicável.
Em resumo: se você está fazendo inclusão em massa no braço, provavelmente está deixando tempo e dinheiro na mesa.
Os dois formatos de arquivo que o M.I.L.E. aceita
Na configuração do layout, um dos primeiros pontos importantes é definir como o arquivo TXT será interpretado. De forma prática, há dois formatos principais:
- Arquivo de layout fixo
- Arquivo com separador
1. Arquivo de layout fixo
No layout fixo, cada informação ocupa sempre a mesma quantidade de posições dentro da linha. Não há delimitadores visíveis entre os campos. O sistema entende o conteúdo com base na posição inicial e final de cada trecho.
Exemplo simples de cadastro com três campos:
- A1_COD: posições 1 a 6
- A1_NOME: posições 7 a 26
- A1_PESSOA: posição 27
Se o código tiver 6 caracteres e o nome tiver até 20, a linha precisa respeitar exatamente esse padrão. Quando um campo não usa todo o espaço disponível, ele deve ser completado com espaços.
Esse formato costuma aparecer quando os dados vêm de sistemas antigos ou bases legadas que já exportam arquivos em posições fixas.
Vantagem: funciona bem quando o padrão já vem pronto e é rígido.
Desvantagem: qualquer desalinhamento quebra a leitura. Se faltar espaço em um campo, o próximo valor pode “escorregar” para a posição errada e causar erro de processamento.
2. Arquivo com separador
No arquivo com separador, os campos são divididos por um caractere específico, como:
- ponto e vírgula ;
- vírgula ,
- pipe |
- tabulação
Esse é o modelo mais comum para trabalhar com o M.I.L.E., principalmente quando os dados vêm de planilhas, exportações do Excel ou quando o arquivo foi montado manualmente.
Nesse caso, em vez de contar posições fixas, você informa ao sistema a ordem das colunas. Por exemplo:
- 1ª coluna: código
- 2ª coluna: nome
- 3ª coluna: tipo de pessoa
Um exemplo ficaria assim:
000001;João da Silva;F
Repare que não existe preenchimento com espaços para completar tamanho. O separador já faz esse trabalho.
Mas aqui existe um cuidado importante: o separador escolhido não pode conflitar com os próprios dados.
Se você usa vírgula como delimitador e o nome de algum registro também contém vírgula, o sistema pode entender que aquilo é o início de um novo campo e gerar erro na leitura. Por isso, em muitos cenários, o ponto e vírgula acaba sendo a opção mais segura.
Os tipos de adaptadores do M.I.L.E.
Depois de definir o formato do arquivo, entra outra decisão importante: qual “engine” de processamento será usada.
No M.I.L.E., isso é feito pelos adaptadores. São três possibilidades principais:
- MsExecAuto
- MVC
- Função customizada
MsExecAuto
Esse é o modo mais comum e direto. Ele aproveita as rotinas automáticas já existentes no Protheus para fazer a inclusão dos registros.
Ou seja, você aponta o layout para a rotina padrão correspondente e o sistema executa a inclusão com base nas validações nativas daquela rotina.
É ideal quando você quer importar dados usando a lógica padrão do cadastro, sem inventar moda e sem precisar programar.
Um ponto importante: nesse contexto, o MsExecAuto é voltado para inclusão. Ele não é a escolha para cenários que exigem edição, exclusão ou tratamentos mais avançados.
MVC
O adaptador MVC entra quando você precisa de mais flexibilidade.
Ele faz sentido quando a rotina de destino já segue a arquitetura Model View Controller ou quando há necessidade de aplicar validações adicionais, regras específicas ou um fluxo mais controlado.
Se a importação precisa fazer mais do que simplesmente incluir, o MVC passa a ser uma opção mais apropriada.
Função customizada
Essa é a abordagem mais aberta e personalizável dentro do M.I.L.E.
Nela, o conteúdo do TXT é lido e repassado como um array de informações para uma função AdvPL desenvolvida por você. A partir daí, toda a validação, tratamento de dados, regras de negócio e retorno de erro ficam sob responsabilidade da sua rotina.
É o caminho ideal quando a lógica de importação foge do padrão e exige controle total.
Os três modelos de processamento no Protheus
Além do adaptador, é importante entender o modelo da rotina que será integrada. O M.I.L.E. trabalha com os modelos clássicos de tela do Protheus.
Modelo 1
É o mais simples. Existe apenas uma estrutura principal de campos, normalmente associada a uma única tabela.
Exemplo típico: cadastro de clientes, usando a tabela SA1.
Nesse cenário, você configura os campos e importa um registro por linha, sem grid de itens.
Modelo 2
No modelo 2, a tela possui campos e grid, mas as informações ficam na mesma tabela.
Um exemplo citado é o pedido de compra, em que a interface é dividida entre parte superior e grade inferior, mesmo trabalhando com a mesma tabela de armazenamento.
Modelo 3
Aqui a separação é mais clara: a parte superior grava em uma tabela e a grade inferior grava em outra.
O exemplo clássico é o pedido de venda:
- SC5 no cabeçalho
- SC6 nos itens
Entender isso é essencial porque a configuração de canais, ocorrências e mapeamento muda conforme o modelo.
Configuração prática do M.I.L.E. para importar clientes no Protheus
Agora vamos ao que realmente interessa, uma breve explicação de como montar uma importação do zero para cadastro de clientes, usando um exemplo de modelo 1 com MsExecAuto. Para conferir todas as configurações citadas a seguir de forma completa sugiro que assista o vídeo no inicio da página
Acessando a rotina do M.I.L.E.
No configurador (SIGACFG), o caminho apresentado foi:
- Ambientes
- Aceleradores
- M.I.L.E.
Ao abrir a rotina, você encontra a tela padrão com opções para:
- Incluir
- Alterar
- Visualizar
- Outras Ações
Criando um novo layout de importação
Na inclusão de um layout, existem duas opções:
- Importação
- Exportação
O foco aqui é a importação.
Já na tela do sistema, você deve iniciar pela configuração geral do layout, onde devem ser preenchidos os seguintes campos:
- Layout: utilizado para informar o código identificador
- Descrição: um identificador criado para nomear o layout de importação
- Tipo de adaptador: Qual o motor será utilizado (MsExecAuto)
- Adapter: Qual a rotina padrão utilizada (CRMA980)
- Tabela principal: Qual a tabela principal dessa rotina (SA1)
- Ordem: Qual índice de ordenação da tabela será utilizado (1)
Definindo o formato do arquivo
Avançado devemos definir o tipo de arquivo, para isso deve ser configurado os seguintes campos:
- Arquivo TXT: Se é fixo ou com Separador
- Separador: Qual separador será utilizado
- Permite separador entre aspas: Se entre os separadores terá aspas
- Separador inicial: Se a cada inicio de linha iniciara com um separador
- Separador final: Se a cada final de linha encerará com um separador
- Formato de data: Tipo da data utilizada
- Separador decimal: Se o campo decimal é separado por virgula ou ponto
Prosseguindo com o cadastro você vai encontrar outras configurações de processamento e validação. Para esse caso de modelo 1 com rotina automática, não foi necessário alterar nada além do essencial, citado anteriormente.
Configurando os canais
Depois da formatação, vem a configuração dos canais.
Para o exemplo do vídeo estamos utilizando o cadastro de clientes, essa rotina usa apenas a tabela SA1, assim foi criado um único canal correspondente a essa tabela.
O ID de Saída foi definido como Master, representando o cabeçalho.
Já a Ocorrência foi configurada como única, porque estamos lidando com um cadastro simples de modelo 1, sem múltiplas linhas de itens. Esse conceito de ocorrência é importante para modelos 2 e 3, onde pode existir relação um para muitos, especialmente em grids com vários itens.
Mapeando os campos do arquivo TXT
A próxima etapa é uma das mais importantes: dizer ao M.I.L.E. qual campo do Protheus corresponde a qual posição no arquivo TXT.
Devemos preencher as seguintes informações:
- Campo: Código do campo da tabela, A1_CODIGO por exemplo
- Descrição: Descrição do campo
- Tipo: Qual tipo de dado esse campo suporta
- Origem: Qual coluna do seu arquivo TXT armazena informações do campo.
Dica: Na tela de campos por coluna, o sistema lista os campos da rotina, mas eles nem sempre aparecem na ordem ideal para o preenchimento. A recomendação é abrir a rotina real do cadastro em outro SmartClient e usar isso como referência.
Isso ajuda em dois pontos:
- entender a sequência natural dos campos
- identificar quais campos são obrigatórios
No caso do MsExecAuto, isso faz ainda mais diferença porque a validação respeita as regras da rotina padrão. Se um campo obrigatório não estiver contemplado corretamente, a importação vai falhar.
Entre os campos mapeados no exemplo do vídeo, estavam:
- código do cliente
- loja
- nome
- tipo de pessoa física ou jurídica
- endereço
- número
- nome reduzido
- tipo de cliente
- estado
- município
Um detalhe importante: o campo de filial não foi mapeado, porque no uso com MsExecAuto o sistema já considera a filial do ambiente logado.
Recursos úteis na tela de campos
A grade de mapeamento também possui alguns atalhos que ajudam bastante:
- subir e descer campos na lista
- inserir no início
- inserir no fim
- preencher todos os campos da rotina
Esse último recurso exige cuidado. Ele pode trazer todos os campos disponíveis da rotina, inclusive campos que você não pretende usar. Em vez de ajudar, isso pode deixar o processamento mais pesado e a configuração mais confusa.
Preparando o arquivo TXT para importação
Com o layout configurado, o próximo passo é disponibilizar o arquivo no servidor do Protheus.
Primeiramente você precisa criar uma pasta dentro do ambiente de dados do Protheus, em seguida coloque o arquivo dentro dela, para que o sistema possa abrir o arquivo na rotina do M.I.L.E.
Como processar o TXT no M.I.L.E.
Com tudo pronto, a execução é bem direta.
- Selecione o layout cadastrado no M.I.L.E.
- Acesse Outras Ações.
- Escolha a opção de processar TXT.
- Informe a partir de qual linha o sistema deve iniciar a leitura.
- Selecione o arquivo dentro do servidor.
- Confirme o processamento.
Depois disso, o sistema executa a carga dos registros de acordo com o layout configurado.
Consultando logs de processamento
Se houver erro, o próprio M.I.L.E. disponibiliza a consulta de logs.
Você pode abrir os registros da última operação ou consultar todos os logs do layout, verificando com mais clareza:
- qual linha apresentou problema
- qual campo falhou
- qual foi o motivo do erro
Esse ponto é fundamental para ajuste fino de layout, obrigatoriedade de campos e validações da rotina padrão.
Resultado da importação no cadastro de clientes
Após o processamento, a conferência no cadastro mostrou os novos registros criados em sequência, do MILE001 ao MILE006.
Ou seja: o layout foi configurado, o TXT foi processado e os clientes foram incluídos com sucesso no Protheus usando recurso nativo do sistema.
Sem gambiarra, sem rotina improvisada e sem precisar programar para esse cenário.
Boas práticas para usar o M.I.L.E. com mais segurança
Mesmo em processos simples, algumas boas práticas fazem toda a diferença:
- Confirme os campos obrigatórios diretamente na rotina do cadastro.
- Escolha bem o separador para não conflitar com os dados.
- Evite mapear campos desnecessários, principalmente ao usar preenchimento automático da lista.
- Valide o tipo dos campos antes da carga.
- Teste primeiro com poucos registros antes de processar um arquivo maior.
- Consulte os logs sempre que houver inconsistência.
- Entenda o modelo da rotina antes de configurar canais e ocorrências.
O que foi feito com clientes pode ser replicado para outras tabelas
Esse é um dos pontos mais interessantes do M.I.L.E.: depois que você entende a lógica, o processo se repete.
O exemplo foi feito com cadastro de clientes, mas a mesma ideia pode ser aplicada a várias outras tabelas do Protheus, como:
- fornecedores
- produtos
- transportadoras
- naturezas
- e muitos outros cadastros
Claro, respeitando sempre a arquitetura da rotina, os campos obrigatórios e o adaptador correto.
Conclusão
O M.I.L.E. é um daqueles recursos nativos do Protheus que, quando bem compreendidos, mudam completamente a forma de trabalhar com carga e migração de dados.
Em vez de depender sempre de programação AdvPL para qualquer necessidade de importação, muitas demandas podem ser resolvidas com configuração de layout, mapeamento de campos e processamento nativo.
O ganho é claro:
- mais agilidade
- menos trabalho manual
- mais aderência ao padrão do sistema
- mais produtividade para analistas, consultores e desenvolvedores
Se você trabalha com TOTVS Protheus e ainda não explora esse recurso, vale começar pelo básico: montar um layout simples de modelo 1, testar com um TXT pequeno e sentir na prática como o processo fica mais eficiente.
Depois que a lógica encaixa, muita coisa deixa de ser um problema operacional e passa a ser apenas uma configuração bem feita.
Este este artigo foi uma breve explicação sobre o M.I.L.E no TOTVS Protheus, para conferir o processo completo de forma prática sugerimos que assista o vídeo no início da página.
Cursos
Se você está buscando se tornar um desenvolvedor completo no Protheus, dominar REST, PO-UI e as demais tecnologias relacionadas ao Protheus, não fique de fora da nossa turma de alunos, clique aqui para mais detalhes.
Sobre nós:
A RFB Sistemas é uma consultoria e escola há mais de 15 anos no mercado e já atuamos em diferentes setores e portes de empresas ajudando a implantar a melhor solução para gerenciar os seus negócios, o que possibilita que sua empresa consiga tomar decisões mais rápidas, assertivas e claro otimizando resultados. Além disso já capacitamos mais de 1.600 profissionais a utilizarem as ferramentas, como: TOTVS Protheus e RM, Microsoft Power BI e Excel.
