Workflows | Acciones con código personalizado

​

Bibliotecas compatibles con Node.js

• @hubspot/api-client ^10
• 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 compatibles con Python

• requests 2.28.2
• @hubspot/api-client ^8
• google-api-python-client 2.74.0
• mysql-connector-python 8.0.32
• redis 4.4.2
• nltk 3.8.1

​

Primeros pasos

​

Ejemplos de código

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"
}

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"

# }

​

Crear una acción con código personalizado

• En tu cuenta de HubSpot, navega a Automatización > Workflows.
• Haz clic en el nombre de un workflow o crea un nuevo workflow.
• Haz clic en el ícono + más para agregar una acción de workflow.
• En el panel izquierdo, busca y selecciona Código personalizado.

• Por defecto, las acciones con código personalizado utilizarán Node.js. Si estás en la prueba beta con Python y quieres crear una acción con este lenguaje, haz clic en el menú desplegable Lenguaje y selecciona Python.
• En el campo Descripción, introduce una descripción para tu acción personalizada de workflow. Esta descripción aparecerá en la tarjeta de acción del workflow correspondiente.
• Puedes utilizar un secreto con la acción de código personalizado, como un token de acceso a una aplicación privada. La aplicación también debe incluir los respectivos ámbitos para los datos que estés intentando extraer de HubSpot, como contacts o forms. Más información sobre las aplicaciones privadas de HubSpot.
  • Para utilizar un secreto existente, haz clic en Añadir secreto. Luego, selecciona las casillas de verificación situadas junto a las imágenes que deseas guardar.
  • Para agregar un nuevo secreto, haz clic en Agregar secreto. En el cuadro de diálogo, escribe el nombre del secreto y el valor del secreto. Luego, haz clic en Guardar. Ahora puedes seleccionar este secreto en futuras acciones con código personalizado.
  • Para cambiar o eliminar los secretos existentes, haz clic en Administrar secretos.
• Para incluir propiedades en tu código personalizado:
  • Haz clic en el enlace Selecciona una propiedad y luego selecciona una propiedad del panel de datos. Puedes utilizar propiedades existentes o valores de propiedad formateados antes en el workflow. Después de seleccionar la propiedad, introduce un nombre para usarla en el código. Descubre cómo hacer referencia a las propiedades en tu código personalizado.
  • Para agregar otra propiedad, haz clic en Agregar propiedad. Cada propiedad solo puede agregarse una vez y debe tener un ID de variable único. Puedes usar hasta 50 propiedades con tu código personalizado.
  • Para eliminar una propiedad, haz clic en el ícono de eliminación.
• En el campo del código, introduce el código en JavaScript o Python.
• Para definir los datos de output que se pueden usar como datos de input en el workflow, por ejemplo, con la acción Editar registros:
  • En Outputs de datos, haz clic en Añadir output.
  • Haz clic en el menú desplegable Tipo de datos y selecciona un tipo de datos.
  • En el campo Nombre, introduce un nombre para el output de datos.
  • Para agregar varias salidas, haz clic en Agregar salida.
• En la parte superior, haz clic en Guardar.

• Hay una llamada a la función def main(event): cuando se ejecuta la acción del fragmento de código.
• El argumento event es un objeto que contiene detalles sobre la ejecución del workflow.
• La función callback() se utiliza para transferir datos de vuelta al workflow. Se debe llamar en la función exports.main. Esto solo se puede usar con Node.js.

//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"
}

​

Establece un límite de frecuencia para la acción (BETA)

• En la cronología del workflow, haz clic en la acción con código personalizado.
• En la parte inferior, haz clic en Configurar límite de frecuencia para ampliar la sección de límite de frecuencia.
• Haz clic para activar el interruptor Activar la limitación de frecuencia. Por opción predeterminada, esta opción está desactivada.
• Ajusta el límite de frecuencia:
  • Ejecuciones de acciones: ajusta el número máximo de ejecuciones por periodo de tiempo.
  • Plazo: ajusta el plazo para su límite de tarifa. Puedes ajustar esta franja horaria en Segundos, Minutos u Horas.

​

Probar la acción

• En la vista previa del workflow, haz clic en la acción con código personalizado.
• En la parte inferior de la barra lateral derecha, haz clic en Probar acción para expandir la sección de prueba.
• Selecciona un registro con el que probar el código haciendo clic en el menú desplegable Objeto y luego, selecciona un registro.
• Si usas valores de propiedad formateados previamente en el workflow, introduce un valor de prueba para los datos con formato.

• Para ejecutar el código, haz clic en Prueba.
• En el cuadro de diálogo, confirma que quieres probar el código con respecto al registro seleccionado haciendo clic en Prueba.
• Una vez que tu código haya terminado de ejecutarse, la barra lateral mostrará los resultados de la prueba:
  • Estado: El estado de acierto o error de la acción con código personalizado.
  • Salida de datos: Los valores resultantes para la salida de datos definida. Aparecerá una alerta junto a los resultados que el código haya generado y que no se hayan definido en la sección Salida de datos ni en el editor de código. Deberás agregar esos resultados para usarlos más adelante en el workflow.
  • Registros: Información sobre la prueba en sí, como cuánta memoria usó la acción para ejecutarse y el tiempo de ejecución total.
• Cuando termines de probar la acción, haz clic en Guardar para guardar los cambios.

​

Secretos

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);
});
}

​

Agregar propiedades de HubSpot al código personalizado

const email = event.inputFields['email'];

​

Registros

​

Cómo definir los datos de salida

callback({
outputFields: {
email: email,
phone: phone,
},
});

• Si el tipo de datos de salida está en formato de cadena, el límite para los valores de la cadena es de 65.000 caracteres. Exceder este límite ocasionará un error OUTPUT_VALUES_TOO_LARGE.
• Si utilizas la acción Editar registros, toma nota de las propiedades de origen y destino compatibles.
• Al actualizar las propiedades de fecha:
  • Si estás copiando los datos de output de una propiedad de fecha y hora, esos datos deberán estar en formato Unix en milisegundos.
  • Si estás copiando los datos de output de una propiedad de fecha en lugar de fecha y hora, esos datos deberán estar en formato Unix en milisegundos y la hora de la fecha deberá fijarse en la medianoche de la zona horaria UTC.

​

Limitaciones

​

Reintentos

• Si estás usando Node.js y encuentras un error de límite de frecuencia, pero quieres que HubSpot vuelva a intentar la llamada, deberás incluir el error en el bloque catch de la acción con código personalizado.

• Si usas Python y encuentras un error de límite de frecuencia, pero quieres que HubSpot vuelva a intentar la llamada, deberás generar el error en el bloque except de la acción con código personalizado.

​

Advertencias

• Generación de números aleatorios: es común usar Math.random para generar números aleatorios, pero los usuarios pueden ver los mismos números generados en diferentes ejecuciones. Esto se debe a que Math.random funciona según la hora actual. Dado que HubSpot puede inscribir muchos objetos en un workflow al mismo tiempo y borrar el estado en cada ejecución, cada ejecución termina alimentando Math.random de la misma manera. En cambio, puedes usar la biblioteca random-number-csprng 1.0.2, que garantiza la generación de números pseudoaleatorios criptográficamente seguros.
• Reutilización de variables: para ahorrar memoria, cualquier variable introducida fuera de la función exports.main se puede reutilizar para futuras ejecuciones de la acción con código personalizado. Esto es útil cuando se hace una conexión con servicios externos, como una base de datos, pero cualquier lógica o información que deba ser única para cada ejecución de la acción con código personalizado debe estar dentro de la función exports.main.

• Reutilización de variables: al igual que en el caso anterior, toda variable introducida fuera de la función def main se puede reutilizar para futuras ejecuciones de la acción con código personalizado.
  • Si introdujiste una variable fuera de la función def main, pero no planeas modificarla, puedes hacer referencia a la variable directamente.
  • Si planeas modificar una variable, puedes introducir la variable dentro de la función def main con una clave global antes de hacer la referencia.

a = 1
def main(event):
  global a
  a += 1