Campos múltiplos — telefones, e-mails, etiquetas — armazenam vários valores ao mesmo tempo, e os robôs também retornam listas: por exemplo, as partes de uma string dividida. As ações nativas dos processos de negócios do Bitrix24 (Alaio) lidam mal com listas: a inserção cola todos os valores em uma única string, e a gravação em um campo múltiplo apaga o que havia nele. Os robôs da Roboteka cobrem o trabalho com arrays: pegar um elemento por índice, contar os elementos, verificar a presença de um valor, adicionar e remover um valor de campo múltiplo, e também deduplicar, ordenar, somar, excluir um elemento da lista e exibir a lista como tabela.

De onde vêm os arrays no processo de negócios?

Três fontes. Os campos múltiplos das entidades: telefones e e-mails do contato, campos de usuário com o atributo «múltiplo» — etiquetas, categorias, lista de filiais. As variáveis múltiplas do processo, nas quais os valores se acumulam ao longo dos ramos. E os resultados de outros robôs: a divisão de uma string por separador retorna uma lista de partes, a extração por padrão — uma lista de coincidências. De forma nativa, dá para fazer pouco com essa lista: a inserção em texto colará os valores por vírgula, e a condição verificará a presença pela colagem. Pegar justamente o segundo telefone, contar as etiquetas ou acrescentar com cuidado um valor sem tocar nos demais — já são tarefas para os robôs abaixo.

Como pegar o primeiro, o último ou o N-ésimo elemento?

O robô «Obter elemento do array por índice» recebe um array de valores e um índice: 0 — o primeiro elemento, 1 — o segundo, −1 — o último, −2 — o penúltimo. Saída: o elemento e o indicador «O elemento existe» (Y/N); se o índice estiver fora dos limites do array, retorna um valor vazio e o indicador N — o processo não para, e o ramo da condição trata a falta de dados. Combinações típicas: dividiu a string com o nome completo por espaço — pegou o primeiro elemento como sobrenome; dividiu o endereço por vírgula — pegou o último elemento como número da casa; da lista de coincidências de uma expressão regular pegou a primeira. O resultado é gravado em um campo simples comum ou em uma variável para os passos seguintes.

Como contar os elementos e verificar a presença de um valor?

Dois robôs-pergunta. O «Tamanho do array / número de elementos» retorna a quantidade e o indicador «O array está vazio» (Y/N); strings vazias por padrão não são contadas — uma posição vazia acidental em um campo múltiplo não estraga a contagem. O «Verificar se um valor existe no array» procura a coincidência exata do elemento — não uma substring — sem diferenciar maiúsculas de minúsculas, e uma opção ativa a comparação estrita. Saída: o indicador «Encontrado» (Y/N) e o índice da primeira coincidência, menos um se não houver coincidências. Aplicação nas condições do processo: «o negócio já tem a etiqueta VIP — pular a concessão do desconto», «o contato tem zero telefones — tarefa para o gerente completar a ficha antes de passar à campanha de ligações».

Como adicionar um valor a um campo múltiplo sem apagar os demais?

A principal dor dos campos múltiplos: a alteração nativa do documento grava o campo por inteiro e, ao adicionar uma etiqueta, é fácil apagar as existentes. O robô «Adicionar valor a um campo múltiplo» acrescenta o valor com cuidado: lê o conteúdo atual do campo da entidade e adiciona o novo aos existentes. Entrada: o tipo da entidade — negócio, contato, empresa ou lead —, o ID da entidade por inserção a partir do documento atual, o código do campo (por exemplo, UF_CRM_TAGS ou PHONE) e o próprio valor. A opção «não adicionar se já existir» está ativada por padrão: a reexecução do processo não gera duplicatas do valor. Saída: o indicador «Sucesso» (Y/N) e a quantidade final de elementos no campo.

Como remover um valor de um campo múltiplo?

A operação inversa — tirar uma etiqueta, remover um telefone obsoleto. Manualmente, isso significa abrir a ficha e editar o campo; com a ação nativa — reescrever o campo por inteiro com todos os riscos. O robô «Remover valor de um campo múltiplo» recebe o tipo da entidade, o ID, o código do campo e o valor a remover. Todas as ocorrências desse valor são removidas, e os demais elementos permanecem no lugar. Saída: o indicador «Sucesso» (Y/N), quantas ocorrências foram removidas e a quantidade final de elementos no campo. Receita: o negócio foi fechado com sucesso — o processo tira da empresa a etiqueta «em atendimento» e, com o robô vizinho de adição, acrescenta a etiqueta «cliente»; a ficha sempre reflete o status atual sem edição manual.

Como obter o último valor adicionado?

O Bitrix24 armazena os valores de um campo múltiplo na ordem em que foram adicionados, portanto «o último adicionado» é simplesmente o último elemento da lista. O robô «Obter elemento do array por índice» com o índice −1 o retorna sem precisar contar o tamanho; −2 dá o anterior a ele. Uma nuance para campos dos tipos «lista» e «vínculo com elemento do CRM»: esse campo chega ao processo de negócios como uma lista de IDs — dos valores da lista ou dos elementos vinculados —, e não de nomes. O índice −1 dá o ID do último elemento; para ler seu nome, telefone ou qualquer outro campo, encadeie o robô «Obter o valor de um campo de uma entidade relacionada» — ele recebe o tipo da entidade, esse ID e o código do campo. Exemplo: o negócio tem um campo múltiplo «Aprovadores» vinculado a contatos — o processo pega o último adicionado e puxa o e-mail dele para a notificação.

Como transformar uma string separada por vírgulas em um campo múltiplo?

Valores de um formulário ou de uma integração muitas vezes chegam como uma única string: «instalação, entrega, garantia». O robô «Dividir cadeia por separador» a corta em uma lista de partes; o separador é interpretado literalmente, então, para uma string com vírgula e espaço, defina «vírgula mais espaço» como separador, senão as partes ficam com um espaço no início. O resultado é um array comum: grave-o por inteiro em um campo múltiplo com a ação nativa «Modificar documento» (o campo é sobrescrito — para um campo vazio é exatamente o que se quer) ou acrescente os valores um a um aos existentes com «Adicionar valor a um campo múltiplo». Mais sobre dividir e juntar no artigo sobre strings nos processos de negócios.

Como excluir um elemento do array ou limpar a lista?

Dois casos diferentes. Se o valor precisa sair de um campo da ficha, isso é «Remover valor de um campo múltiplo» — ele edita a própria entidade. Se a lista está em uma variável do processo ou veio de outro robô e a ficha deve permanecer intocada, use «Excluir elemento do array». Dois modos: por valor — todas as coincidências são removidas, sem diferenciar maiúsculas de minúsculas por padrão; por índice — um elemento, 0 o primeiro, −1 o último. Saída: o array após a exclusão, quantos elementos foram removidos e a quantidade final. Limpar uma variável múltipla por inteiro é mais fácil com as ferramentas nativas — a ação «Modificar variáveis» com um valor vazio; um campo múltiplo da ficha é esvaziado pelo robô «Limpar um campo», porque uma string vazia na ação nativa «Modificar documento» não funciona para esses campos. O robô de exclusão é para quando um valor sai da lista: o primeiro telefone da fila foi tratado — remova-o pelo índice 0 e passe o restante adiante.

Como remover duplicatas e comparar duas listas?

O «Remover duplicatas do array» mantém apenas os valores únicos e preserva a ordem das primeiras ocorrências; a comparação por padrão não diferencia maiúsculas de minúsculas, com opção de comparação estrita. Saída: o array sem duplicatas, o número de elementos únicos e quantas repetições foram descartadas. Caso típico: os telefones de uma empresa e dos seus contatos reunidos em uma variável antes de um envio em massa — depois do robô, nenhum número recebe duas mensagens. O mesmo robô ajuda a comparar dois campos múltiplos. Elemento por elemento — «Verificar se um valor existe no array» dentro da construção nativa «Ciclo»: um valor do campo A é procurado no campo B. Como um todo — reúna as duas listas em uma variável e execute a deduplicação: se nenhum dos campos repetir valores internamente e o número de repetições descartadas for igual ao número de elementos do campo B, o campo B está totalmente contido no campo A.

Como somar os valores de um array?

Um campo múltiplo «Pagamentos» ou uma lista de valores de uma string dividida é somado pelo robô «Soma dos elementos do array». Ele entende a vírgula como separador decimal e espaços dentro dos números («1 500,50»), pula os elementos não numéricos e informa separadamente quantos foram pulados — uma condição do processo sobre esse contador pega «entrou texto no campo». Saída: a soma e o número de elementos contados. Normalmente a soma é arredondada em seguida e colocada em um campo do negócio ou em um e-mail — arredondamento e porcentagens têm artigo próprio sobre cálculos nos processos de negócios.

Como ordenar um array?

As ferramentas nativas não ordenam uma lista, e ordenar números como strings dá a ordem «1, 10, 2». O robô «Ordenar array» organiza os elementos em ordem crescente ou decrescente; o tipo é detectado automaticamente — todos os elementos numéricos significa comparação numérica, caso contrário alfabética como strings — e pode ser forçado. Saída: o array ordenado e a quantidade de elementos. Em par com a obtenção por índice, ele responde «o maior pagamento»: ordene em ordem decrescente, pegue o elemento 0; «as três datas mais antigas»: ordene em ordem crescente, pegue 0, 1 e 2.

Como exibir uma lista como tabela em um e-mail ou notificação?

A inserção de um campo múltiplo em texto resulta nos valores separados por vírgula. Para um e-mail legível, use o robô «Tabela HTML a partir de um array»: cada elemento do array vira uma linha da tabela, um separador dentro do elemento (ponto e vírgula por padrão) o divide em colunas, e um campo à parte define a linha de cabeçalho. Saída: o código HTML pronto da tabela, o número de linhas e de colunas. Receita: a lista de itens «nome;quantidade;valor», acumulada em uma variável ao longo do processo, vai ao cliente por e-mail como tabela. Como entregar esse e-mail ou notificação está no artigo sobre notificações a partir do processo de negócios.

Conclusão

Os robôs cobrem o ciclo de vida do array: pegar um elemento — «Obter elemento do array por índice», contar — «Tamanho do array / número de elementos», verificar — «Verificar se um valor existe no array», alterar um campo múltiplo da ficha — «Adicionar valor a um campo múltiplo» e «Remover valor de um campo múltiplo», processar uma lista sem gravar na ficha — «Excluir elemento do array», «Remover duplicatas do array», «Ordenar array», «Soma dos elementos do array», «Tabela HTML a partir de um array». Todos estão no catálogo da Roboteka, gratuitos a partir do Bitrix24.Marketplace. Não há a operação com arrays de que você precisa — descreva a tarefa, fazemos o robô de graça.