Mapeamento de Dados

Configure o que cada etapa captura, transforma ou calcula, qual ação ela executa em cada elemento e como isso vira variável do processo.

Conceito de Mapeamento

O painel de mapeamento muda de acordo com o tipo de ação da etapa: Preencher, Obter Informação, Navegar, Conectar Serviços e Chamar API Rest têm campos diferentes entre si, cada um com o que faz sentido para aquela ação. O que é comum a todos: cada mapeamento é adicionado e configurado um a um, de acordo com a especificidade daquele elemento ou campo.

De forma geral, cada mapeamento define:

1. O que fazer: capturar um dado, clicar, digitar, ou alimentar um campo de conector/API. Depende do tipo de ação da etapa
2. Onde e como: qual elemento ou campo, com qual transformação (OCR, conversão de tipo, expressões regulares, cálculos)
3. Onde salvar: nome da variável que estará disponível nas etapas seguintes

Campos Gerais

Independente do tipo de ação, todo mapeamento tem:

Mapeamento em Preencher

O mapeamento de uma etapa Preencher define em qual elemento agir e o que fazer com ele:

Bem-vindo, {nome}!

{CPF} != null ? {CPF} : parseInt({COD_Documento})

{tipo} == "PF" ? "CPF" : "CNPJ"

const resultado = await sessionPage[position].evaluate(() => {
  return document.querySelector('#seletor').innerText;
});
globalData.set('{resultado}', resultado);

Mapeamento em Obter Informação

O mapeamento de uma etapa Obter Informação usa o mesmo painel de Seletor / Seleção Customizada de Preencher (veja o callout de código nativo na seção anterior), mas sem Valor nem Tipo de Evento, só captura. O iFrame do Objeto continua valendo, para quando o elemento está dentro de um iframe. Especifique o que extrair em Ler a partir do atributo:

Coleção: Tabulação Automática

Quando o seletor de uma etapa Obter Informação casa com vários elementos ao mesmo tempo, o array capturado vem "achatado": item 1, item 2, item 3... na ordem em que aparecem no HTML, sem separar por coluna. Se o que você está lendo é uma tabela com várias colunas, isso mistura tudo numa lista só.

É pra isso que serve Varrer como Lista?: ative o toggle e, em Tabulação Automática da Lista, adicione um label para cada coluna, na mesma ordem em que elas aparecem no HTML. O runtime distribui o array capturado ciclicamente entre esses labels. O 1º item vai para o 1º label, o 2º para o 2º label, e assim por diante, voltando ao 1º label depois do último. Cada label vira automaticamente uma variável lista própria no processo, já separada por coluna.

Exemplo: uma tabela de fornecedores com 4 colunas: Empresa, CNPJ, Serviço e UF. Um seletor genérico (ex.: td) captura todas as células da tabela em sequência. Com Tabulação Automática da Lista = EMPRESA_LIST, CNPJ_LIST, SERVICO_LIST, UF_LIST, o runtime tabula automaticamente: a 1ª célula de cada linha cai em {EMPRESA_LIST}, a 2ª em {CNPJ_LIST}, e assim por diante. Cada lista termina com uma entrada por linha da tabela original.

Como a distribuição é pela posição do item capturado, use um seletor que alcance só as células das linhas de dados, com uma célula por label em cada linha, como #fornecedores tbody tr.dado td.

As listas da Tabulação Automática acumulam: cada vez que a etapa roda na mesma execução, os itens capturados entram no fim das listas, o que junta as páginas de uma paginação. A variável da própria linha de mapeamento é substituída a cada passagem.

Mapeamento em Navegar: dispositivo e Interação

Esta seção aparece no mapeamento de uma etapa Navegar. Ela é opcional. A grande maioria das automações não precisa dela, porque age em cima de um seletor normalmente. Ela existe para o caso em que não há seletor confiável para usar: telas em canvas/WebGL, componentes gráficos de terceiros, ou qualquer interface onde os elementos não formam um DOM navegável. Nesses casos, em vez de "clicar no elemento X" você faz "clicar na posição X,Y da tela".

Campos adicionais, conforme o dispositivo/ação escolhidos:

• Botão do Mouse (Esquerdo/Direito) e Quantidade de Cliques, só para Mouse.
• Tecla (Enter, Tab, setas, etc.) para Press/Down/Up, ou Texto a digitar para Type. No Keyboard.
• Posição X / Posição Y. Coordenadas do clique ou toque, para Mouse e Touchscreen.
• Posição Final X / Posição Final Y, só para Drag / Drag n Drop: a coordenada de destino do arraste.
• Delay e Aguardar Após Executar. Pausa em milissegundos antes e depois da interação.

Mapeamento em Conectar Serviços

Em vez de seletor, o mapeamento de uma etapa Conectar Serviços mostra as entradas do conector escolhido. Os campos mudam conforme o conector e a ação selecionados. Cada entrada aceita um Valor Fixo (texto literal) ou uma variável do processo (ícone de tag):

No exemplo, um conector de e-mail (Comunicação Padrão): Para recebe a variável {matrix.area_responsavel}, Assunto é um valor fixo digitado, Corpo recebe outra variável, e CC/BCC ficam em branco (opcionais). Campos obrigatórios do conector vêm sinalizados.

Cada entrada é um campo de texto com um seletor de variáveis ao lado. A variável escolhida entra na posição do cursor, então o mesmo campo aceita texto fixo, uma variável, ou os dois juntos (/pedido/{id}/itens). O detalhe das três formas, com exemplos, está em Conectores → Preenchendo os valores na etapa.

O resultado da chamada, ou seja, o que o conector devolve, vira variável com o prefixo fixo connector.; veja Variáveis de Contexto.

Mapeamento em Chamar API Rest

Diferente das outras etapas, aqui não existe seletor: o mapeamento é a própria configuração da chamada HTTP, montada por formulário. Nada de escrever JSON à mão.

Body: o corpo que você envia

A seção Body monta o corpo da requisição, aquilo que o agente manda para a API. Ela não tem nada a ver com a resposta.

Content-Type: a etapa preenche, você troca se precisar

Ao escolher o formato do corpo, a linha Content-Type aparece sozinha na seção Headers, já com o valor certo: application/json no formato body, e no formato texto o tipo que o próprio conteúdo indica (texto começando com < vira application/xml, a=1&b=2 vira urlencoded, e assim por diante).

Essa linha é sua: edite o valor quando a API pedir outro tipo, como application/soap+xml, text/csv ou um tipo próprio do fornecedor. O que estiver escrito ali é o que vai para a API.

Regras da coluna Chave

A Chave não é só um rótulo de tela: ela vira o nome do campo gravado. Uma regra vale em toda seção, as outras duas só no Body.

• Não pode ficar em branco, em nenhuma seção. Linha sem Chave não tem nome de campo. Preencha ou remova a linha.
• No Body, não aceita . # $ / [ ]. Para aninhar um campo, o lugar é a coluna Path, não um ponto dentro da Chave.
• No Body, path é um nome reservado: é ele que identifica o grupo. Use outro nome para o seu campo.

Em Headers, Parâmetros de URL e Query Strings a Chave é livre. É o que permite escrever criteria[0][field], forcedisplay[0] ou filter[name], a notação de array que muitas APIs de busca exigem, e também repetir a mesma chave em duas linhas quando a API espera o parâmetro mais de uma vez.

O formulário confere isso ao salvar e diz qual seção e qual linha precisam de ajuste, apontando o campo em vermelho quando o caractere é o problema.

O que escrever na coluna Valor

O campo Valor tem um botão { } que abre a lista de variáveis disponíveis (mapeamentos anteriores, Matrix e retornos de conector), agrupadas por origem. Variáveis que carregam listas vêm marcadas com um badge. Ao escolher uma, ela é inserida na posição do cursor, então dá para combinar com o que você já digitou. Você também pode digitar tudo à mão, sem abrir a lista.

Resultados: onde a resposta é guardada

Quem lê a resposta da API é a seção Resultados. Cada linha liga um caminho do JSON retornado a uma variável do processo:

Exemplo: para uma API que responde assim...

{
  "data": {
    "invoice": {
      "number": "NF-2024-001",
      "total": 1500.00,
      "status": "approved"
    }
  }
}

...crie três linhas em Resultados:

data.invoice.number  → numero_nf
data.invoice.total   → valor_total
data.invoice.status  → status_nf

Nas etapas seguintes, os valores ficam disponíveis como:

{numero_nf}    → "NF-2024-001"
{valor_total}  → 1500
{status_nf}    → "approved"

Não há limite de linhas, e caminhos com e sem [*] convivem na mesma etapa: todos viram variável. Ser lista é consequência do [*] no caminho, não uma marcação à parte, então não há como a marcação discordar do que a etapa realmente entrega.

Testar a chamada antes de rodar

O botão Testar chamada, no fim da seção Resultados, dispara a requisição a partir da própria tela e mostra o status e a resposta. A chamada é montada exatamente como na execução, então o que funciona no teste funciona no processo.

Clicar num campo do JSON exibido cria a linha de Resultado com o Path já preenchido, o que dispensa digitar o caminho à mão. Em um campo dentro de uma lista, o atalho [*] todos escreve o caminho com [*], e a variável passa a receber o campo de todos os itens.

Se a etapa usa variáveis, o painel pede o valor de cada uma para o teste, já preenchendo as que são parâmetro do agente. Esses valores valem só para a chamada de teste e não alteram o processo. Referência ao Cofre de Senhas é resolvida no servidor, e o segredo não aparece na tela.

Quando o Path não encontra nada

A etapa não falha: a variável fica vazia e o log registra um aviso dizendo qual Path faltou e quais campos a resposta trouxe no primeiro nível. É por ali que se descobre se o caminho está errado ou se a API é que não devolveu o dado.