Manipulação de Variáveis

Como criar, usar e alterar cada tipo de variável do browserMate: as globais (Matrix), as locais (Variáveis do Fluxo), as criadas automaticamente pelas etapas e as de sistema.

Os quatro tipos de variáveis

Toda automação move informação de um ponto a outro: um parâmetro que entra, um dado lido da tela, um resultado calculado, uma resposta de API. No browserMate essa informação viaja em variáveis, e elas se dividem em quatro tipos, conforme o propósito de cada uma:

Cada tipo é explicado abaixo com a mesma divisão: para que serve, como se cria, como se usa, como se altera e o ciclo de vida.

Como escrever uma variável

Qualquer variável é usada escrevendo o nome entre chaves, no formato {variavel}. Ela funciona:

• Em campos de texto de qualquer etapa (URLs, valores, mensagens, corpo de API)
• No mapeamento de conectores, onde o mesmo campo aceita texto fixo, uma variável ou os dois juntos (veja Conectores)
• Nas condições de rota e de execução de qualquer etapa, e não apenas da Decisão (veja Lógicas de Rota e Execução Condicional)
• Nos scripts de Regra Customizada, via bm.get('{variavel}'), e para gravar de volta, pelo segundo parâmetro de bm.done() (veja Código Inline). A variável com tipo chega ao script no tipo dela (uma Moeda chega como número), e o que o script grava numa variável com tipo precisa caber nele, senão a etapa falha dizendo qual variável foi. O que o script grava passa a aparecer nas listas de variáveis (veja Automáticas: Script)

Você não precisa decorar os nomes. Os campos que aceitam variável têm um botão { } que abre a lista de tudo o que existe naquele ponto do fluxo, agrupado por origem: Sistema, Matrix, Conectores e uma seção para cada etapa que produz variáveis, inclusive as que um script grava. Escolher um item insere {nome} na posição do cursor.

Globais (Matrix)

Para que serve

As variáveis globais, chamadas de Matrix, são os parâmetros do agente: a informação que precisa estar pronta antes de a primeira etapa rodar, como o mês a processar, o CNPJ da filial ou o e-mail de quem deve ser avisado. Elas pertencem ao processo inteiro, e por isso qualquer etapa as enxerga.

Use uma variável global quando o valor vem de fora do fluxo ou quando quem dispara a execução precisa poder trocá-lo. É o que permite um único agente atender várias empresas, filiais ou meses, sem duplicar o fluxo.

Como se cria

As variáveis globais ficam numa tela própria, aberta pelo atalho Matrix, no topo da tela do agente:

Cada linha é uma variável, com o nome, o tipo do dado e o valor que vale quando ninguém informa outro. Use + Adicionar variável para criar uma nova e Salvar para gravar:

Como o tipo é aplicado

O tipo escolhido vale em todo o fluxo, para as variáveis da Matrix e para as Variáveis do Fluxo criadas com Tipo. Quem recebe o valor converte pelo tipo que declarou, venha o valor de onde vier: digitado na tela, raspado de uma página, enviado por API, webhook ou por outro agente.

O que cada tipo aceita quando o valor chega:

• A vírgula é o separador decimal. Quando o valor tem ponto e vírgula juntos, o último dos dois é o decimal: 1.234,90 e 1,234.90 dão o mesmo valor.
• Separador único seguido de três dígitos (1.500, 1,500, $1,234) é milhar numa Moeda, porque dinheiro não tem três casas decimais, e decimal num Número (um e meio). Com um ou dois dígitos depois, é decimal nos dois: 1,50.
• Moeda tem duas casas. Para mais casas decimais, use Número.
• Valor vazio não é erro: a variável fica sem valor.
• Valor que não cabe no tipo é recusado pela API e pelo webhook, com o erro para quem enviou. Se ele chegar à execução, ela falha antes da primeira etapa, com o nome da variável e o tipo no erro. O valor em si não aparece no erro.

Como o valor é usado:

Número, Verdadeiro/Falso e Lista seguem o mesmo caminho: são número, verdadeiro/falso e lista em fórmula, condição e script. Numa fórmula que junta texto ("Total: " + {matrix.valor}) a Moeda entra como número. Para o texto formatado, use o modo Variável ou texto (Total: {matrix.valor}).

• Comparação com texto em condição. Numa condição, uma variável Moeda ou Número comparada com um texto entre aspas que é número ({matrix.valor} > "1.000,00") compara pelo número. Texto que não é número continua sendo comparado como texto.
• Retorno de um agente chamado. A variável que recebe o retorno herda o tipo que ela tinha no agente chamado: uma Moeda devolvida continua Moeda.
• Dado sensível. Uma variável Moeda ou Número marcada como sensível fica escondida no log em todas as formas em que aparece: 1234.9, 1234.90 e 1.234,90.

O tipo Secreto

Use o tipo Secreto na variável que carrega uma credencial ou um dado pessoal: a API Key do sistema de destino, um token, um CPF. Dentro do fluxo ela funciona como qualquer outra, com {matrix.nome} devolvendo o valor real, mas o valor é tratado como segredo do começo ao fim da execução:

• Não tem valor padrão. Um padrão ficaria guardado em texto puro na definição do agente, então o campo Valor Padrão fica bloqueado. O valor só existe se quem disparou a execução o enviou.
• Não aparece em log. Onde o valor apareceria, o log mostra «•••», e ele some de todo registro da execução.
• Fica cifrado enquanto espera. Se a execução aguarda na fila, o valor fica cifrado até a etapa usá-lo.
• Desliga a imagem de tela. Depois que o valor chega, as etapas seguintes não geram evidência em imagem, porque uma imagem não consegue esconder só um pedaço do que a página mostra. Se você precisa de evidência visual, gere-a antes.

O valor de um parâmetro Secreto só pode ser informado por caminhos que não deixam o segredo guardado nem exposto numa URL:

Como se usa

Em qualquer campo de texto de uma etapa, escreva {matrix.nome_da_variavel} e ela é trocada pelo valor no momento da execução. Numa URL, por exemplo:

https://sistema.com/relatorio?mes={matrix.mes_referencia}

O prefixo matrix. é obrigatório e é ele que separa a variável global de uma variável local ou automática de mesmo nome.

Como se altera

O valor de uma variável global pode ser trocado em vários pontos, cada um com um alcance. Do mais duradouro para o mais pontual:

Em todos os casos vale a mesma regra: variável enviada substitui o padrão, variável não enviada mantém o padrão, e o cadastro do agente nunca é alterado por uma execução. A exceção é a variável do tipo Secreto, que só recebe valor pela API e pelo webhook (veja O tipo Secreto).

No cadastro

Abra a tela Matrix, altere o nome, o tipo ou o valor padrão e clique em Salvar. É a única alteração que muda o que as próximas execuções recebem quando ninguém informa valor. O cadastro completo está em Criação de Agentes.

No agendamento

Cada agendamento pode ter os seus próprios valores de Matrix, aplicados a cada disparo automático. Assim, o mesmo agente pode rodar todo dia para uma filial e toda semana para outra, cada agendamento com o seu contexto.

1. Em Meus Insights → Control Room, abra a aba Agendamentos e clique em + Novo Agendamento (ou edite um existente).
2. Selecione o processo. Se ele tiver variáveis de Matrix, elas aparecem para preenchimento opcional.
3. Deixe em branco para manter o valor padrão do processo, ou informe o valor específico daquele agendamento.
4. Salve. Os valores informados substituem o padrão só nos disparos daquele agendamento.

Veja o passo a passo completo em Agendamento.

Na API

A API externa altera variáveis globais de duas formas: ao disparar uma execução e ao criar um agendamento. Nas duas, os valores vão no campo matrix do corpo da requisição, um objeto no formato { "variavel": valor }.

POST /v1/processes/1042/start

{
  "matrix": {
    "cnpj_fornecedor": "12.345.678/0001-99",
    "valor_limite": 1500.5,
    "filiais": ["SP", "RJ", "MG"]
  }
}

• Os nomes vêm do próprio processo. A rota GET /v1/processes/:pid/matrix devolve os nomes e os tipos aceitos. Um campo que não existe na Matrix é rejeitado, em vez de ser ignorado em silêncio.
• O valor é lido pelo tipo da variável. Moeda aceita número (1500.5) ou texto ("1.500,50"), Verdadeiro/Falso aceita booleano ou "sim"/"não", Lista aceita um array (cada elemento é um item) ou texto separado por vírgula, e Objeto aceita um objeto JSON. Um valor que não cabe no tipo é recusado com INVALID_MATRIX. Detalhes: Como o tipo é aplicado.
• No disparo, o valor vale para aquela execução. Em POST /v1/schedules, o mesmo campo matrix vira o valor fixo de toda execução agendada.
• A API dispara sempre a versão publicada do processo.

A tabela completa de formatos, os cabeçalhos exigidos e as respostas estão em Rotas de API.

No webhook

No webhook, quem chama é um sistema externo (CRM, ERP, formulário) que envia um JSON. O mapeamento da origem liga cada campo desse JSON a uma variável da Matrix: o valor que chega passa a ser o valor da variável naquela execução.

• O mapeamento é salvo uma vez por origem e vale para todas as chamadas dela.
• Variável da Matrix sem campo mapeado roda com o valor padrão. Não é erro, e permite mapear só o que aquele sistema realmente envia.
• Renomear a variável na Matrix não quebra o mapeamento.

Na execução manual

Ao executar o agente na mão, aparece um diálogo com as variáveis da Matrix para você revisar e alterar antes de confirmar. Os valores digitados valem só para aquela execução.

Dentro do fluxo

Uma etapa também pode mudar o valor de uma variável global no meio da execução, sem código: na seção Variáveis do Fluxo de uma etapa de Regra Customizada, use Atribuir a existente e escolha a variável matrix.nome (veja Locais, como se altera). Por script, a alteração é feita pelo segundo parâmetro de bm.done().

A alteração vale do ponto em que acontece até o fim daquela execução. O cadastro da Matrix não muda.

Ciclo de vida

• Nasce no início da execução, com o valor padrão do cadastro ou com o que o disparo enviou.
• Vive até o fim da execução, visível em todas as etapas.
• Termina com a execução. A próxima começa de novo pelo valor padrão.

Locais (Variáveis do Fluxo)

Para que serve

As variáveis locais servem para o que só faz sentido dentro do fluxo: um valor intermediário, uma mensagem montada com pedaços de outras variáveis, o resultado de um cálculo, um contador, um sinalizador. Colocar isso na Matrix polui o cadastro do agente com coisas que ninguém precisa informar de fora. Para isso existe a seção Variáveis do Fluxo, na etapa de Regra Customizada, e ela dispensa código.

Use uma variável local quando o valor é criado ou transformado no meio do fluxo e não precisa ser informado por quem dispara a execução.

Como se cria

1. Abra uma etapa de Regra Customizada (ou crie uma nova) e, na aba Propriedades, vá até a seção Variáveis do Fluxo, o primeiro bloco do painel.
2. Clique em + Adicionar ou atribuir variável. Cada clique acrescenta uma linha à seção, já com Criar variável marcado.
3. Preencha o Nome da variável (obrigatório) e, se quiser, o Tipo.
4. Escolha como o valor é montado (Fixo, Variável ou texto ou Fórmula) e preencha o campo Valor.
5. Clique em Salvar. A variável passa a existir no fluxo inteiro.

Uma etapa pode ter várias linhas, e o botão ✕ de cada uma a remove.

Numa mesma etapa você pode misturar linhas de Criar variável e de Atribuir a existente, quantas quiser de cada. Elas rodam de cima para baixo, então cada linha só enxerga o que já existe quando ela roda: nos seletores de variável, além das variáveis da Matrix e das outras etapas, aparecem apenas as criadas em linhas acima dela. Por isso uma atribuição a uma variável criada na própria etapa fica sempre abaixo da linha que a cria. Já dentro de uma linha só um dos dois modos é aceito. Para trocar de um para o outro numa linha já preenchida, limpe antes o que é só do modo atual: o nome e o tipo em Criar, ou a variável escolhida em Atribuir. Enquanto houver algo preenchido, o outro modo fica esmaecido e, ao clicar nele, um aviso diz o que limpar. O campo Valor vale para os dois modos, então não bloqueia a troca e continua como estava.

Os três modos de valor

O campo Valor segue o mesmo padrão do mapeamento de conector: texto digitado, uma variável escolhida na lista, ou os dois juntos. A diferença é que aqui você diz explicitamente qual das três formas está usando:

O campo Valor começa com uma linha e cresce com o conteúdo. Shift+Enter quebra a linha (Enter sozinho não quebra). O botão ⤢, no canto do campo, abre o valor em tela cheia, com as {variáveis} destacadas e, fora do modo Fixo, a lista das variáveis do fluxo com busca: um clique insere a variável no cursor. Na Fórmula há também a barra de operadores (+ − × ÷, comparações, e, ou, ? :), que insere o operador do JavaScript (o × entra como *). Concluir ou Esc volta ao formulário com o que foi editado já no campo.

Alguns exemplos de fórmula:

"Instância recuperada: " + {instanceID}          → texto com uma variável de sistema
Number({valor_total}) > 1000                      → verdadeiro ou falso
{status} == 'approved' ? 'liberar' : 'revisar'    → escolhe entre dois textos
Number({tentativas}) + 1                          → soma um a um contador

Tipos

O campo Tipo é opcional e converte o valor depois de montado, com as mesmas regras da Matrix (Como o tipo é aplicado). Deixando em Sem conversão, o valor fica como veio: texto no modo Fixo, o tipo original numa variável sozinha, o resultado da conta numa fórmula. Um valor que não cabe no tipo faz a etapa falhar, e ela entra na Gestão de Erros. No modo Fixo, a tela avisa ao Salvar.

A opção Dado sensível, no cabeçalho de cada linha, esconde o valor dos logs, do estado guardado pelo debug e do arquivo de teste de projetos de script. A variável continua valendo normalmente nas etapas seguintes. Veja Dados Sensíveis.

Com o tipo Objeto ou Lista no modo Fixo, o campo Valor confere o JSON enquanto você escreve, numa faixa abaixo do campo e também no editor em tela cheia (⤢).

Em texto de várias linhas, a linha e a coluna apontam para o ponto exato. Nos modos Variável ou texto e Fórmula e em outros tipos não há conferência. A faixa é um aviso: o valor que não cabe no tipo também é avisado ao Salvar.

Guia de fórmulas

A Fórmula é uma expressão JavaScript: uma linha que devolve um valor. Você escreve o JavaScript normalmente e usa {variavel} no lugar onde o valor de uma variável deve entrar. Todos os exemplos abaixo foram executados no motor do browserMate, e o resultado mostrado é o que ele devolve.

Como a fórmula lê o que você escreve

• {nome} é o valor da variável, com o tipo dele: número, texto, lista ou objeto. Não é texto colado, então {preco} * 2 faz uma conta com o número.
• É uma expressão só. Não coloque ; no meio. Um ; no fim é aceito.
• As chaves { } que não são de variável funcionam como JavaScript: objetos ({ style: "currency" }), expressões regulares (\d{3}), ${...} de template e funções com corpo (x => { return x }).
• Variável dentro de aspas não é substituída: "Olá {nome}" é recusada, com um aviso ao salvar. Junte com + ("Olá " + {nome}) ou use o modo Variável ou texto.
• O que vem de uma página ou de uma API costuma ser texto. Para contas, converta com Number(), parseInt() ou parseFloat(). Variável com Tipo Número ou Moeda já entra como número.
• Conta impossível, como um texto multiplicado por 2 ou uma divisão por zero, faz a etapa falhar com o aviso do motivo.
• A fórmula trabalha com uma cópia de listas e objetos: .sort() ou .push() dentro dela não alteram a variável de origem.
• Variável que não existe vale undefined. Dois atalhos das condições continuam valendo: {lista}[] é o primeiro item, e {lista} == 0 compara o tamanho da lista.

Valores usados nos exemplos

Cada exemplo usa estas variáveis, com estes valores:

Contas

Converter e arredondar

As conversões de texto em formato brasileiro valem para o que chega como texto, como o valor lido de uma página. Uma variável do tipo Moeda ou Número já entra na fórmula como número: {valor} * 2 funciona direto.

Texto

Decisões (verdadeiro/falso e valor padrão)

Listas

Objetos e JSON

Datas

Como se usa

Assim que a etapa é salva, a variável local passa a existir para o fluxo inteiro, exatamente como o retorno de uma API ou de um conector. Você a escreve como {nome} e ela aparece:

• em todos os seletores de variáveis do editor: campos de texto, mapeamentos, mapeamento de conectores e condições de rota e de execução;
• no autocomplete dos scripts e no seletor de Iterações de Listas, quando o tipo é Lista;
• no console do debug, na aba Variáveis.

Nos seletores, as variáveis de uma etapa vêm agrupadas sob o nome dela, com o ícone de Regra Customizada.

Como se altera

Gravar um novo valor numa variável que já existe

Para gravar um novo valor numa variável que já existe, em vez de criar outra, use o modo Atribuir a existente na linha. O campo Variável que recebe o valor lista tudo o que pode ser alterado: as globais da Matrix, as automáticas criadas por outras etapas e as locais. Das criadas nesta mesma etapa, entram só as de linhas acima da linha que você está editando.

O valor é montado exatamente como na criação (Fixo, Variável ou texto ou Fórmula). Como a fórmula pode usar a própria variável, é assim que se faz um contador:

Etapa "Iniciar":   Criar variável  tentativas   Tipo: Número   Fixo: 0
Etapa "Contar":    Atribuir a existente  tentativas   Fórmula: Number({tentativas}) + 1
Rota da etapa "Verificar":   Number({tentativas}) < 3   → volta para "Tentar de novo"

As variáveis de sistema não podem ser alteradas: elas não aparecem na lista de Atribuir a existente.

O valor é convertido para o tipo da variável que recebe. Quando o alvo tem tipo (uma variável da Matrix, ou uma local criada com Tipo), o valor atribuído passa pelas mesmas regras da tabela de Tipos. Assim, gravar true (Fixo) numa variável Verdadeiro/Falso deixa a variável verdadeira, e gravar 5 (Fixo) numa variável Número grava o número 5, e não o texto "5". Variáveis sem tipo, como as automáticas de mapeamento e de API, ficam com o valor exatamente como ele veio.

Renomear, remover e duplicar

• Renomear. O nome novo vale na hora. Revise os lugares onde o nome antigo foi usado, principalmente os textos digitados à mão (URLs, corpo de API, mapeamento de conector). O seletor de variáveis sempre mostra os nomes atuais.
• Remover. A variável deixa de existir no fluxo, e os campos que ainda a usam deixam de receber valor. Uma linha de Atribuir a existente que gravava nela é avisada ao clicar em Salvar: escolha outra variável ou remova a linha.
• Duplicar a etapa. A cópia leva as mesmas variáveis, com identidade própria. Renomeie as da cópia se as duas etapas precisarem guardar valores diferentes, porque nomes iguais gravam no mesmo lugar.

Ciclo de vida

• Nasce quando a etapa que a define roda. Antes disso, a variável não existe: uma etapa anterior que a use não encontra valor.
• As variáveis da etapa rodam de cima para baixo, e uma linha pode usar a variável criada pela linha anterior.
• Rodam antes dos scripts da mesma etapa. O Script de Sessão e o código customizado já encontram tudo pronto e leem com bm.get('{nome}'). A iteração de listas roda depois.
• A condição Executar esta Etapa somente se é avaliada antes da etapa, então não enxerga as variáveis que a própria etapa define. Já a condição Definir a próxima Etapa após execução enxerga.
• Se a etapa rodar de novo, por um desvio de rota ou por uma nova tentativa, as variáveis são calculadas de novo. Uma fórmula que depende do valor anterior, como o contador, avança a cada passagem.
• Termina com a execução.

Regras e limites

Quem não cumpre uma dessas regras é avisado ao clicar em Salvar, com o número da linha e o motivo.

Quando algo dá errado

• Fórmula inválida. A etapa falha e entra na Gestão de Erros e Exceções. A mensagem diz qual variável não pôde ser calculada. Nenhuma variável da etapa é gravada quando uma delas falha, para a nova tentativa não partir de um estado pela metade.
• Variável inexistente dentro de um texto. O {nome} fica no texto como foi escrito, e o log da execução avisa qual variável não foi encontrada.
• Log. A execução registra o nome das variáveis definidas em cada etapa, nunca os valores. Para ver os valores, use a aba Variáveis do debug (veja Conferindo os valores).

Exemplos

Criar variável   mensagem   Tipo: Texto
Modo: Variável ou texto
Valor: Olá {nome_cliente}, recebemos o pedido {numero_pedido} no valor de {valor_total}.

Criar variável   aprovado   Tipo: Verdadeiro/Falso
Modo: Fórmula
Valor: Number({valor_total}) <= Number({matrix.limite_aprovacao})

Rota:  {aprovado} == true   → Aprovar Pedido
       true                 → Encaminhar para Revisão

Criar variável   filiais   Tipo: Lista
Modo: Fixo
Valor: SP, RJ, MG

Depois, em Iterações de Listas, escolha "filiais": a etapa consome um item a cada passagem.

Automáticas (criadas pelas etapas)

Para que serve

As variáveis automáticas levam adiante o que uma etapa, um conector, um serviço ou um script devolveu: o preço lido de uma página, o número da nota que uma API respondeu, o e-mail que um conector encontrou, o total que um script calculou. Elas são as que você não cria: nascem sozinhas quando a etapa roda. O que você define é só o nome, na configuração da etapa (ou, num script, na chave que ele devolve).

Quando a etapa roda, o browserMate guarda o dado nessa variável, e ela fica disponível nas etapas seguintes, como qualquer outra.

Como se cria

Cada origem tem o seu lugar para dar o nome:

Captura da tela

Numa etapa Obter Informação, cada linha de mapeamento lê um elemento da página. O nome que você dá à linha é o nome da variável: uma linha chamada preco grava o valor lido em {preco}, disponível em qualquer etapa seguinte.

Quando o seletor casa com vários elementos, a variável guarda uma lista, e cada item é acessado por posição, dentro de uma fórmula: {preco}[0], {preco}[1]. Com Varrer como Lista e a Tabulação Automática da Lista, cada coluna de uma tabela vira uma variável lista própria:

O detalhe está em Mapeamento de Dados e em Coleção: Tabulação Automática.

Resposta de uma API

Na etapa Chamar API Rest, a seção Resultados liga um caminho do JSON de resposta a uma variável. Cada linha tem o Path (onde está o dado na resposta) e a Variável (o nome que ele terá no fluxo):

data.invoice.number  → numero_nf      usado como {numero_nf}
data.invoice.total   → valor_total     usado como {valor_total}

O [*] no caminho percorre uma lista e faz a variável ser uma lista. O passo a passo, com o teste da chamada, está em Mapeamento em Chamar API Rest.

Retorno de um conector

Toda ação de conector devolve uma resposta. Você escolhe quais partes dela viram variável no mapeamento do retorno do conector: o teste da ação mostra a resposta como uma árvore, e um clique num valor cria a variável de saída.

Nas etapas, essas variáveis usam sempre o prefixo connector., seguido do Nome da linha de saída, não do rótulo do conector: {connector.nome_da_variavel}. Veja Mapeamento do Retorno.

Script (Node.js e Python)

Numa etapa Regra Customizada, o script inline devolve valores ao fluxo pelo segundo parâmetro de bm.done(). Cada chave é o nome de uma variável, escrito entre chaves:

bm.done('processado', {
    '{numero_nf}':   'NF-001',
    '{valor_total}': '1500.00'
})

bm.done('processado', {
  '{numero_nf}':   'NF-001',
  '{valor_total}': '1500.00'
});

Depois que você salva a etapa, o browserMate lê o texto do script e passa a listar numero_nf e valor_total nas etapas seguintes: no botão { } dos campos, no autocomplete dos outros scripts e no Copilot. Não há nada a declarar: o nome que está no código é o nome que aparece na lista.

Tipo. A variável gravada por script não tem tipo declarado: ela guarda o valor como o script o entregou. Uma lista (list no Python, array no Node.js) fica lista, um dicionário ou objeto fica objeto, um texto fica texto e um número fica número. Nos seletores ela aparece sem o selo [ ], porque o tipo só existe na execução, e mesmo assim pode ser a lista de Iterações de Listas e de Disparar por cada item de uma lista. Para fixar o tipo, crie a variável com o mesmo nome em Variáveis do Fluxo, na mesma etapa do script, com o Tipo desejado: o que o script gravar nela passa a ser lido nesse tipo (um valor que não cabe nele faz a etapa falhar), e com o Tipo Lista ela ganha o selo nos seletores.

No Script de Sessão, a escrita é globalData.set('{nome}', valor). O nome também precisa vir entre chaves: globalData.set('nome', valor) grava uma chave que nenhuma referência {nome} do fluxo enxerga.

O que entra na lista e o que não entra:

Arquivo, OCR e evidência

Alguns recursos acrescentam variáveis extras, com um sufixo, ao lado da variável do mapeamento:

Como se usa

Da mesma forma que qualquer outra variável: {nome} (ou {connector.nome}) em qualquer campo de texto, condição ou mapeamento das etapas seguintes à que a produziu. Elas aparecem nos seletores de variáveis, agrupadas sob o nome da etapa (ou do conector) de origem, e no autocomplete dos scripts.

Como se altera

• O nome e a origem do dado mudam na própria etapa que a produz: o nome da linha de mapeamento, o Path e a Variável em Resultados, ou o mapeamento do retorno do conector.
• Num script, o nome muda na própria chave do bm.done(). Os campos que já usavam o nome antigo não são atualizados sozinhos: troque a referência neles.
• O valor é gravado de novo toda vez que a etapa roda (as listas da Tabulação Automática acrescentam itens, em vez de substituir).
• Para corrigir ou normalizar o valor depois (tirar espaços, converter em número, trocar um formato), use uma variável local com Atribuir a existente numa etapa seguinte de Regra Customizada, sem precisar de código (veja Locais, como se altera).

Ciclo de vida

• Nasce quando a etapa que a produz roda. Antes disso, não existe.
• Numa variável de script, o valor só é gravado quando o script chega ao bm.done(). Se o script falhar antes, ou terminar sem chamá-lo, a variável não é criada nem atualizada.
• Numa etapa que roda várias vezes, por exemplo dentro de um loop, a variável guarda o valor da última passagem. A exceção são as listas da Tabulação Automática: elas acumulam os itens a cada passagem, em vez de serem sobrescritas.
• Termina com a execução.

De sistema

Para que serve

As variáveis de sistema informam o que está acontecendo na execução: qual processo e qual instância estão rodando, quem iniciou, em que etapa está, se houve erro e há quanto tempo tudo começou. São o que permite montar uma mensagem de falha, encerrar uma execução longa demais ou reagir a uma navegação inesperada.

Como se cria

Não se cria: o runtime mantém essas variáveis automaticamente em toda execução, sem configurar nada. Elas já existem antes de a primeira etapa rodar.

Como se usa

Do mesmo jeito que as outras, com o nome entre chaves: {processName}, {errorDescription}. Funcionam em qualquer campo de texto, nas condições de rota e de execução de qualquer etapa e nos scripts de Regra Customizada, via bm.get('{variavel}').

Como se altera

Não se altera. As variáveis de sistema pertencem ao runtime: elas não aparecem na lista de Atribuir a existente, e o nome delas não pode ser usado por uma variável que você cria (variável local, nome de mapeamento, variável de Resultados de API ou retorno de agente chamado): a tela recusa o nome ao salvar. Só o próprio runtime as atualiza, ao longo da execução.

Ciclo de vida

Nascem no início da execução e são atualizadas pelo runtime conforme ela avança: {lastStep} muda a cada etapa, {elapsedSeconds} a cada segundo, {errorDescription} a cada falha. Terminam com a execução.

Durante uma execução em modo debug, todas elas aparecem com o valor do momento na gaveta Variáveis de sistema, no rodapé da aba Variáveis do console. É a maneira mais direta de conferir o que uma delas carrega numa execução real, em vez de deduzir. Veja A aba Variáveis.

Referência das variáveis de sistema

Identificação da execução

Fluxo e etapas

Validações e página

Erro e evidência

Tempo

Exemplos com variáveis de sistema

Rota de recuperação que reporta o erro

O processo {processName} (instância {instanceID}) falhou na etapa {errorStep}.
Erro: {errorDescription}
Iniciado por {currentUser} em {startTime}, após {execSteps} etapas.

Encerrar execuções longas demais

Rota 1: Number({elapsedSeconds}) > 1800   → Encerrar por Tempo
Rota 2: true                               → Continuar Processamento

Detectar navegação inesperada

Rota 1: {urlChanged} == false   → Tratar Clique Sem Efeito
Rota 2: true                      → Próxima Ação

Decidir pela página em que o agente está

Rota 1: {currentUrl}.includes('/login')   → Tratar Login Recusado
Rota 2: true                               → Próxima Ação

Qual tipo usar

Na dúvida, a pergunta é: de onde vem essa informação e quem precisa poder mudá-la?

Conferindo os valores na execução

Em modo debug, o console mostra a aba Variáveis, com o valor de cada variável no momento de cada etapa, incluindo as locais e as automáticas, além da gaveta das variáveis de sistema. É a forma mais rápida de confirmar se uma fórmula produziu o que você esperava.

Duas ações do debug dependem diretamente das variáveis. Fixar a saída (📌) guarda o que uma etapa produziu, com uma linha por variável, para você testar as etapas seguintes sem repetir a chamada; uma variável local aparece ali como qualquer outra, e cada variável tem a sua própria linha. Reiniciar daqui retoma a execução de uma etapa com os valores que as anteriores já tinham produzido. O detalhe de cada uma está em Ações de debug em cada etapa.