Ações de fluxo de trabalho de código personalizado

Nos fluxos de trabalho, use a ação Código personalizado para gravar e executar o JavaScript ou Python (em beta). Com ações de código personalizado, você pode estender a funcionalidade do fluxo de trabalho dentro e fora do HubSpot. Para saber mais sobre as APIs do HubSpot, você pode consultar a documentação do desenvolvedor para ver as versões mais recentes ou a documentação legada do desenvolvedor para nossas APIs mais antigas. Para ver exemplos de ações comuns de código personalizado, consulte Casos de uso de automação programável da HubSpot.

As ações de código personalizado oferecem suporte a JavaScript usando o framework de tempo de execução do Node 16.x. Se estiver usando o Python para sua ação de código personalizado, a ação de código personalizado usará o framework de tempo de execução do Python 3.9. Quando a ação é executada, o cálculo do tempo de execução é gerenciado por meio de uma função sem servidor pela HubSpot e pelo AWS Lambda.

Se você encontrar problemas gerais na implementação da ação do código personalizado, entre em contato com o suporte da HubSpot. No entanto, se você estiver enfrentando problemas com seu código personalizado escrito, é recomendável pesquisar e publicar no Fórum do desenvolvedor do HubSpot para obter dicas, conselhos ou ajuda para solucionar problemas com seu código.

Bibliotecas compatíveis com Node.js

Se estiver usando Node.js, as seguintes bibliotecas estarão disponíveis para uso na ação de código. Essas bibliotecas podem ser carregadas usando a função require() normal na parte superior do código.

  • @hubspot/api-client ^8
  • async ^3.2.0
  • aws-sdk ^2.744.0
  • axios ^1.2.0
  • lodash ^4.17.20
  • mongoose ^6.8.0
  • mysql ^2.18.1
  • redis" ^4.5.1
  • request" ^2.88.2
  • bluebird ^3.7.2
  • random-number-csprng ^1.0.2
  • googleapis ^67.0.0

Bibliotecas compatíveis com Python

Se você estiver usando o Python, é possível carregar as seguintes bibliotecas com uma declaração de importação na parte superior do código. A declaração de importação deve ser formatada como from [libraryname] import [item], como from redis.client import redis.

  • solicitações 2.28.2
  • @hubspot/api-client ^7
  • google-api-python-client 2.74.0
  • mysql-connector-python 8.0.32
  • redis 4.4.2
  • nltk 3.8.1

Se você estiver usando qualquer coisa da biblioteca padrão, você pode usar import, como import os.

Get started

Use os exemplos de código abaixo para começar a usar ações de fluxo de trabalho de código personalizado. 

Code samples

NODE16X, v8
const hubspot = require('@hubspot/api-client'); exports.main = async (event, callback) => { /***** How to use secrets Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code Each secret needs to be defined like the example below *****/ const hubspotClient = new hubspot.Client({ accessToken: process.env.SECRET_NAME }); let phone; try { const ApiResponse = await hubspotClient.crm.contacts.basicApi.getById(event.object.objectId, ["phone"]); phone = ApiResponse.properties.phone; } catch (err) { console.error(err); // We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. throw err; } /***** How to use inputs Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. Each input needs to be defined like the example below *****/ const email = event.inputFields['email']; /***** How to use outputs Outputs are a way for you to take data from your code and use it in later workflows actions Use the callback function to return data that can be used in later actions. Data won't be returned until after the event loop is empty, so any code after this will still execute. *****/ callback({ outputFields: { email: email, phone: phone } }); } /* A sample event may look like: { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, "inputFields": { // The property name for defined inputs }, // A unique ID for this execution "callbackId": "ap-123-456-7-8" } */
NODE16X, v3
const hubspot = require('@hubspot/api-client'); exports.main = async (event, callback) => { /***** How to use secrets Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code Each secret needs to be defined like the example below *****/ const hubspotClient = new hubspot.Client({ apiKey: process.env.SECRET_NAME }); let phone; try { const ApiResponse = await hubspotClient.crm.contacts.basicApi.getById(event.object.objectId, ["phone"]); phone = ApiResponse.body.properties.phone; } catch (err) { console.error(err); // We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. throw err; } /***** How to use inputs Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. Each input needs to be defined like the example below *****/ const email = event.inputFields['email']; /***** How to use outputs Outputs are a way for you to take data from your code and use it in later workflows actions Use the callback function to return data that can be used in later actions. Data won't be returned until after the event loop is empty, so any code after this will still execute. *****/ callback({ outputFields: { email: email, phone: phone } }); } /* A sample event may look like: { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, "inputFields": { // The property name for defined inputs }, // A unique ID for this execution "callbackId": "ap-123-456-7-8" } */
PYTHON (o mesmo para todas as versões)
import os from hubspot import HubSpot from hubspot.crm.contacts import ApiException def main(event): # How to use secrets # Secrets are a way for you to save API keys or private apps and set them as a variable to use anywhere in your code # Each secret needs to be defined like the example below hubspot = HubSpot(access_token=os.getenv('SECRET_NAME')) phone = '' try: ApiResponse = hubspot.crm.contacts.basic_api.get_by_id(event.get('object').get('objectId'), properties=["phone"]) phone = ApiResponse.properties.get('phone') except ApiException as e: print(e) # We will automatically retry when the code fails because of a rate limiting error from the HubSpot API. raise # How to use inputs # Inputs are a way for you to take data from any actions in your workflow and use it in your code instead of having to call the HubSpot API to get that same data. # Each input needs to be defined like the example below email = event.get('inputFields').get('email') # How to use outputs # Outputs are a way for you to take data from your code and use it in later workflows actions # Use the callback function to return data that can be used in later actions. # Data won't be returned until after the event loop is empty, so any code after this will still execute. return { "outputFields": { "email": email, "phone": phone } } # A sample event may look like: # { # "origin": { # # Your portal ID # "portalId": 1, # # Your custom action definition ID # "actionDefinitionId": 2, # }, # "object": { # # The type of CRM object that is enrolled in the workflow # "objectType": "CONTACT", # # The ID of the CRM object that is enrolled in the workflow # "objectId": 4, # }, # "inputFields": { # # The property name for defined inputs # }, # # A unique ID for this execution # "callbackId": "ap-123-456-7-8" # }

Criar uma ação de código personalizado

Para adicionar uma ação de código personalizado a um fluxo de trabalho:

  • Em sua conta HubSpot, acesse Automatização> Fluxos de Trabalho.
  • Clique no nome de um fluxo de trabalho ou crie um novo fluxo de trabalho. 
  • Clique no ícone + (adição) para adicionar uma ação de fluxo de trabalho.
  • No painel direito, selecione Código personalizado.
 

custom-code-action-select

  • No painel direito, configure sua ação:
    • Por padrão, ações de código personalizadas usarão Node.js 16.x. Se estiver no Python beta e quiser criar sua ação com o Python, clique no menu suspenso Idioma e selecione Python.
    • Para adicionar um novo segredo, como um token de acesso a app privado, clique em Adicionar segredo.O app deve incluir os respectivos escopos de quaisquer dados que você esteja tentando extrair da HubSpot, como contatos ou formulários.  Saiba mais sobre os apps privados da HubSpot.
    • Na caixa de diálogo, insira o Nome do segredo e o Valor do segredo.
    • Clique em Salvar. Agora você pode selecionar esse segredo em ações de código personalizado futuras.
    • Para editar ou excluir segredos existentes, clique em Gerenciar segredos.
  • Para incluir propriedades em seu código personalizado, clique no menu suspensoEscolher propriedade e, em seguida, selecione uma propriedade. Você pode usar propriedades existentes ou valores de propriedade formatados anteriormente no fluxo de trabalho. Depois de selecionar sua propriedade, insira um nome de propriedade para usar em seu código. Saiba como fazer referência a propriedades no código personalizado.
  • Para adicionar outra propriedade, clique em Adicionar propriedade. Cada propriedade somente pode ser adicionada uma vez e deve ter um ID variável único.  Você pode usar até 50 propriedades com o seu código personalizado. 
  • Para excluir uma propriedade, clique no ícone de exclusão.
  • No campo de código, insira seu JavaScript ou Python.
  • Para definir as saídas de dados que podem ser usadas como entradas posteriormente no fluxo de trabalho, por exemplo, com uma ação Copiar valor da propriedade:
    • Em Saídas de dados, clique no menu suspenso Tipo de dados e selecione um tipo de dados.
    • No campo Nome, insira um nome para a saída de dados.
    • Para adicionar várias saídas, clique em Adicionar saída.
  • Clique em Salvar.

workflow-custom-code

 

Observação: o campo de código não exibirá erros de lint ao usar o Python. 

Ao criar ações de código personalizado, saiba que: 

  • A função def main(event): é chamada quando a ação de snippet de código é executada.
  • O argumento event é um objeto que contém detalhes para a execução de fluxo de trabalho.
  • A função callback() é usada para transmitir dados de volta ao fluxo de trabalho. Ela deve ser chamada na função exports.main. Isso só pode ser usado com o Node.js. 

O objeto event conterá os seguintes dados:

//example payload { "origin": { // Your portal ID "portalId": 1, // Your custom action definition ID "actionDefinitionId": 2, }, "object": { // The type of CRM object that is enrolled in the workflow "objectType": "CONTACT", // The ID of the CRM object that is enrolled in the workflow "objectId": 4, }, // A unique ID for this execution. "callbackId": "ap-123-456-7-8" }

Testar a ação

Ao adicionar uma ação de código personalizado a um fluxo de trabalho, você pode testar a ação para garantir que seu código seja executado conforme o esperado antes de ativar o fluxo de trabalho.

Ao testar uma ação de código personalizado, você começará selecionando um registro para testar o código e, em seguida, executar o código. Este teste executará apenas o código na sua ação personalizada, não qualquer uma das outras ações no fluxo de trabalho. Quando o código terminar de ser executado, você poderá visualizar as saídas de código e o registro do seu teste.

Observação: ao testar seu código personalizado, o código será executado e quaisquer alterações serão aplicadas ao registro de teste selecionado. É recomendável criar um registro de teste dedicado se quiser evitar atualizar seus registros em tempo real. 

Para testar uma ação de código personalizado:

  • Na linha do tempo do fluxo de trabalho, clique na ação de código personalizado.
  • Na parte inferior da barra lateral direita, clique em Ação de teste para expandir a seção de teste.
    workflow-custom-code-test-expand
  • Selecione um registro para testar seu código clicando no menu suspenso [Objeto] e selecione um Registro.
    workflow-custom-code-action-test2
  • Se você estiver usando valores de propriedade formatados anteriormente no fluxo de trabalho, insira um valor de teste para os dados formatados.   

  • Para executar o código, clique em Testar.
  • Na caixa de diálogo, confirme que deseja testar seu código em relação ao registro selecionado clicando em Testar.
  • Assim que o seu código for executado, a barra lateral exibirá os resultados do seu teste:
    • Status: o status de sucesso ou falha de sua ação de código personalizado.
    • Saídas de dados: os valores que resultaram para suas saídas de dados definidas. Um alerta será exibido ao lado de quaisquer saídas geradas pelo código que não foram definidas na seção Saídas de dados ou no editor de código. Você precisará adicionar essas saídas para usá-las posteriormente no fluxo de trabalho.
    • Logs: informações sobre o próprio teste, como quantidade de memória usada pela ação para executar e o tempo total de execução. 

      workflow-custom-code-action-test0results0
  • Para atualizar sua ação de código personalizado, clique em Criar ação para expandir o editor de ações. Continue a atualizar e testar seu código conforme necessário.
  • Quando terminar de testar a ação, clique em Salvar para salvar suas alterações.

Segredos

Há momentos em que você deseja que o seu código faça referência a algo que não deve ser amplamente compartilhado. Na maioria das vezes, esse é um meio de autenticação, como um token de acesso ao app privado. Você pode gerenciar os segredos aos quais sua função tem acesso diretamente na definição de ação do fluxo de trabalho. Ao usar vários segredos dentro de um código personalizado, o comprimento total de todos os valores secretos não deve exceder 1.000 caracteres.

workflow-custom-code-secrets

Uma vez adicionados, os segredos estarão disponíveis como variáveis de ambiente, que podem ser acessadas no código personalizado, como mostrado abaixo:

const hubspot = require('@hubspot/api-client'); exports.main = (event, callback) => { return callback(processEvent(event)); };function processEvent(event) { // secrets can be accessed via environment variables const hubspotClient = new hubspot.Client({ accessToken: process.env.secretName }); hubspotClient.crm.contacts.basicApi.getById(event["object"]["objectId"], ["email", "phone"]) .then(results => { let email = results.body["properties"]["email"] let phone = results.body["properties"]["phone"] // ... }) .catch(err => { console.error(err) }) }

Adicione propriedades da HubSpot ao seu código personalizado

Às vezes, pode ser necessário buscar propriedades de objeto na ação de código personalizado. Em vez de usar as APIs do HubSpot, você pode adicionar essas propriedades diretamente na definição de ação do fluxo de trabalho. Adicione propriedades e defina nomes de propriedades para fazer referência a propriedades em seu código. Você pode adicionar até 50 propriedades em cada ação de código personalizado.  

Depois de adicionada, a propriedade pode ser referenciada no código personalizado. 

const email = event.inputFields['email']; email = event.get('inputFields').get('email')

Fazendo login

Uma ferramenta importante para os desenvolvedores é a capacidade de imprimir saídas de seu código. Ela ajuda você a depurar problemas e fornecer melhor suporte para os seus usuários finais. Para ver a saída dos logs, você pode encontrá-los na guia "Histórico" do fluxo de trabalho.  

custom_code_logs

How to Define Outputs

Na função, defina os campos de saída que você deseja usar posteriormente no fluxo de trabalho. Em seguida, na barra lateral direita, selecione o tipo de saída de dados (por exemplo, número, sequência de caracteres, booleano, data e hora, enumeração, número de telefone da data) e insira o campo que deseja exibir.

Os campos de saída devem ser parte de um objeto json formatado de acordo, dependendo do idioma usado:

callback({ outputFields: { email: email, phone: phone } }); return { "outputFields": { "email": email, "phone": phone } }
custom-code-output

Você pode usar a saída de sua ação de código como entrada para a ação Copiar valor de propriedade. Isso remove a necessidade de fazer outra chamada de API para armazenar o valor como uma propriedade no objeto.

Observe o seguinte ao definir sua saída:

  • Se o seu tipo de saída de dados estiver no formato de sequência de caracteres, o limite para valores de saída de sequência de caracteres é de 65 mil caracteres. Ultrapassar esse limite resultará em um erro OUTPUT_VALUES_TOO_LARGE. 
  • Se estiver usando a ação Copiar valor da propriedade, observe também as propriedades de origem e destino compatíveis.
  • Observe também que, se você estiver copiando uma saída para uma propriedade de data e hora, a saída precisará estar no formato de milissegundos do UNIX.
custom_code_actions_output_usage

Limitations

As ações de código personalizado devem terminar a execução em até 20 segundos e somente podem usar até 128 MB de memória. Ultrapassar esses limites resultará em um erro. 

Retries

Pode ser necessário buscar propriedades de objeto usando a API do HubSpot ou chamar outros endpoints da API HubSpot em sua ação de código personalizado. Como qualquer outra chamada de API, você ainda precisará cumprir os limites de taxa de API da HubSpot.

  • Se você estiver usando Node.js e encontrar um erro de limitação de taxa, mas quiser que a HubSpot repita sua chamada, você precisará lançar o erro no bloco de captura da sua ação de código personalizado.

  • Se você estiver usando o Python e encontrar um erro de limitação de taxa, mas quiser que a HubSpot repita sua chamada, será necessário informar o erro no bloco exceção da ação de código personalizado.

Observação: se a chamada falhar devido a um erro de limitação de taxa ou um erro 429 ou 5XX do axios ou @hubspot/api-client, a HubSpot tentará novamente executar sua ação por até três dias, começando um minuto após a falha. As falhas subsequentes serão tentadas novamente em intervalos crescentes, com uma lacuna máxima de oito horas entre as tentativas.

Caveats

Se você estiver usando Node.js para seu código personalizado, observe as seguintes limitações:

  • Geração de números aleatórios: é comum usar Math.random para gerar números aleatórios, mas os mesmos números podem ser gerados em diferentes execuções. Isso ocorre porque o Math.random é espalhado pelo tempo atual. Como a HubSpot pode inscrever muitos objetos em um fluxo de trabalho ao mesmo tempo e limpar o estado em cada execução, diferentes execuções acabam espalhando o Math.random da mesma maneira. Em vez disso, você pode usar a biblioteca random-number-csprng 1.0.2, que garante a geração de números pseudoaleatórios criptograficamente seguros.
  • Reutilização de variáveis: para salvar a memória, quaisquer variáveis declaradas fora da função exports.main podem ser reutilizadas para futuras execuções da ação de código personalizado. Isso é útil ao se conectar a serviços externos, como um banco de dados, mas qualquer lógica ou informação que precise ser exclusiva para cada execução da ação de código personalizado deve estar dentro da função exports.main.

Se você estiver usando Python para seu código personalizado, observe as seguintes limitações:

  • Reutilização de variáveis: semelhante ao acima, quaisquer variáveis declaradas fora da função def main podem ser reutilizadas para futuras execuções da ação de código personalizado.
    • Se você declarou uma variável fora da função def main, mas não planeja alterá-la, você pode referenciar a variável diretamente.
    • Se você planeja alterar uma variável, você pode declarar a variável na função def main com uma palavra-chave global antes de referenciá-la.
a = 1 def main(event): global a a += 1
Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..