Execução de Código

Execução de Código roda um trecho de JavaScript (ou TypeScript) sobre os dados da execução. É a etapa para tudo o que não se deve pedir a um modelo: aritmética, formatação, juntar os resultados de um Mapear, chamar um sistema externo, decidir algo determinístico. Você não precisa ser desenvolvedor para usá-la em coisas simples, e o editor tem um Assistente de Código IA (⌘ L no macOS, Ctrl L nos demais) que escreve ou altera o código a partir de uma descrição. Esta página explica o que o código recebe e o que ele deve devolver, para que você consiga ler e conferir o que o assistente produz. No exemplo desta seção, Normalize Values fica depois de Extract Data e transforma o número extraído em um valor formatado, monta um código de aprovação e marca os contratos acima do limite.

A função execute

O código precisa declarar uma função chamada execute que recebe input e devolve a saída da etapa. A etapa é criada com este modelo:

/**
 * Required main execution function that processes the workflow state data.
 */
async function execute(input: TelaInput) {
    return 'Tela'
}

O que execute devolver vira a saída da etapa: um texto, um número, um objeto ou uma lista. Devolva um objeto com campos nomeados quando as etapas seguintes precisarem escolher valores dele; esses campos aparecem no menu @ das próximas etapas.

// Normalize the values extracted by Extract Data for the routing and the letter.
async function execute(input) {
  const data = input["Extract Data"]
  const total = Number(data.total_value) || 0

  return {
    total_value: total,
    total_formatted: total.toLocaleString("en-US", { style: "currency", currency: "USD" }),
    is_high_value: total > 100000,
    approval_code: `CT-${new Date().getFullYear()}-${String(data.counterparty).slice(0, 3).toUpperCase()}`,
  }
}

Comece o código com um comentário curto dizendo o que a etapa faz, quais entradas usa e o que devolve. Quem abrir o Workflow depois, incluindo o assistente de IA, lê isso antes do código. Se a função não existir ou tiver outro nome, a etapa falha com a mensagem: The execute(input) function was not found in the code and is required.

O que chega em input

input é um objeto com uma chave por Entrada do Workflow e uma chave por etapa que rodou antes desta, usando os nomes exatamente como escritos no editor:

Chave	Valor
`input["contract"]` (uma Entrada de arquivo)	um objeto com `files`, uma lista dos arquivos enviados: `{ name, mimeType, fileUrl, vaultReference }`
`input["requester"]` (uma Entrada de texto)	o texto
`input["Extract Data"]` (um Módulo de IA com Formato de Saída)	o objeto com os atributos: `input["Extract Data"].total_value`
`input["Draft Note"]` (um Módulo de IA sem Formato de Saída)	o texto
`input["Route by value"]` (uma Condição)	o nome da condição que bateu, ou `"Default"`
`input["Split contract"]` (um Dividir ou Recortar)	a lista de pedaços, cada um com `file`, `originalFile`, `pages`…
`input["Extract Page"]` (uma etapa dentro de um Mapear que já terminou)	uma lista, uma entrada por iteração
`input["page"]` (dentro de um Mapear, a Variável de Map)	o item atual

Nomes com espaço precisam da forma com colchetes, input["Extract Data"]; nomes sem espaço podem usar input.requester. O editor conhece a forma do que cada etapa anterior devolve e oferece autocompletar enquanto você digita, então input["Extract Data"]. lista os atributos do Formato de Saída dela.

Adicione um console.log(JSON.stringify(input, null, 2)) na primeira execução. O Terminal abaixo do editor mostra tudo o que o código escreve em stdout e stderr, com o código de saída, então você vê a estrutura real dos dados antes de escrever a lógica.

Devolvendo valores

Devolva um objeto para expor campos nomeados: { total_value, is_high_value }. Cada campo fica selecionável pelas etapas seguintes e por uma Condição.
Devolva uma lista para alimentar um Mapear.
Devolva um texto ou número para um valor único.
Não devolver nada (undefined) produz uma saída vazia; a etapa ainda assim é concluída com sucesso.
Lance um erro (throw new Error("Missing total")) para fazer a etapa falhar de propósito. A execução falha naquela etapa e a mensagem aparece no painel de resultado e em Depurar.

Uma etapa de Execução de Código não tem Formato de Saída para preencher: os campos do objeto que você devolve são o formato de saída dela. O editor os infere a partir do código para que as próximas etapas possam oferecê-los no menu @.

Trabalhando com arquivos

Valores de arquivo chegam como metadados, não como bytes. Para ler o conteúdo de um arquivo, use as bibliotecas disponíveis na etapa:

@meistrari/document-sdk para processar documentos;
@meistrari/vault-sdk para ler e gravar arquivos no Vault;
@meistrari/tela-sdk-js para chamar a API do Tela (por exemplo executar um Canvas) a partir do código.

Essas três vêm instaladas por padrão e aparecem em Bibliotecas Disponíveis. Para adicionar outro pacote (por exemplo xlsx para ler uma planilha ou pdf-lib para montar um PDF), digite o nome em Adicione uma biblioteca e clique em Instalar. A instalação leva alguns segundos e o pacote passa a estar disponível com import ou require.

Como produzir um arquivo como saída de uma etapa de Execução de Código (por exemplo enviar uma planilha gerada ao Vault e devolver a referência dela) depende do SDK do Vault e não está documentado aqui. Para gerar documentos a partir de um template, use o Document Templater.

Usando credenciais

Nunca cole uma chave de API no código. Guarde-a como uma Credencial e leia em tempo de execução:

async function execute(input) {
  const token = credential("CRM_API_TOKEN")
  const response = await fetch("https://crm.example.com/api/contracts", {
    method: "POST",
    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      counterparty: input["Extract Data"].counterparty,
      total: input["Normalize Values"].total_value,
    }),
  })
  if (!response.ok) throw new Error(`CRM answered ${response.status}`)
  return await response.json()
}

credential("NOME") devolve o valor de uma credencial do Workspace ou com escopo do Workflow. Uma credencial ausente faz a etapa falhar com missing_credential. Os valores são omitidos dos logs, mas qualquer coisa que você imprimir com console.log de propósito ainda pode aparecer, então não os imprima. Administradores podem restringir quais credenciais um Workflow pode usar pelo botão Credenciais no cabeçalho; veja Credenciais.

Limites

Limite	Valor
Linguagem	JavaScript ou TypeScript (o TypeScript é transpilado antes de rodar)
Tempo	até 80 minutos por execução, por padrão
Memória	128 MB
Rede	chamadas HTTPS de saída para endereços públicos são permitidas; endereços privados, locais e link-local são bloqueados
Processos	o código não pode iniciar outros programas
Resultado	o que `execute` devolver, serializado como JSON

Uma etapa de Execução de Código nunca usa cache: ela roda em toda execução do Workflow. Uma execução que fica 3 horas sem progresso é marcada como tempo esgotado, então mantenha esperas longas fora do código; uma espera de horas pertence a uma agenda, não a uma etapa.

Depurando

Depois de uma execução, a seção da etapa no painel de resultado mostra o valor devolvido, e Depurar acrescenta o Terminal (stdout, stderr e código de saída) e a mensagem de erro quando o código lançou uma exceção. Quando uma etapa de Execução de Código falha, corrija o código e use Executar Etapa N nela para rodar de novo do início até aquela etapa sem mexer nas seguintes. Veja Executando, testando e publicando.

Para desenvolvedores: a etapa aceita code, language (javascript por padrão; typescript é aceito) e libraries (especificadores de pacotes npm). O sandbox expõe o estado da execução como globais, então input é montado a partir das Entradas (texto reduzido ao conteúdo, arquivos como { files: [...] }) e das saídas das etapas anteriores, cujas chaves são o nome da etapa. Referências {{step://…}} não são expandidas dentro do código.

Primeiros passos

Construir

Testar

Operar

Integrar

Execução de Código

A função execute

O que chega em input

Devolvendo valores

Trabalhando com arquivos

Usando credenciais

Limites

Depurando

​A função execute

​O que chega em input

​Devolvendo valores

​Trabalhando com arquivos

​Usando credenciais

​Limites

​Depurando

A função execute

O que chega em input

Devolvendo valores

Trabalhando com arquivos

Usando credenciais

Limites

Depurando