Acciones de flujo de trabajo personalizadas
Los workflows de Hub Spot se utilizan para automatizar procesos de negocio y permitir que los clientes de HubSpot sean más eficaces. Puedes crear acciones personalizadas de workflow para integrar tu servicio con workflows de HubSpot
Primero, definirás tu acción personalizada, incluidas las entradas que debe completar el usuario que crea un workflow y la URL que se solicitará cuando se ejecute la acción personalizada. Luego, cuando los clientes instalan tu aplicación, pueden agregar tu acción personalizada a sus flujos de trabajo. Cuando se ejecutan esos flujos de trabajo, las solicitudes HTTPS se enviarán a la URL configurada con la carga que se configure. En este artículo, descubre cómo:
- Define tu acción personalizada
- Validar la fuente de solicitud
- Configurar la capacidad de carga predeterminada
- Personalizar la carga
- Publica tu acción personalizada
- Probar tu acción personalizada
- Ejecutar tu acción personalizada
- Bloquear la ejecución de acciones personalizadas
- Completar una acción bloqueada
- Añadir mensajes de ejecución personalizados
Antes de empezar, ten en cuenta lo siguiente:
- Necesitarás una cuenta de desarrollador de HubSpot con una aplicación de HubSpot. El logotipo de tu aplicación se utilizará como el icono para la acción personalizada.
- Al realizar solicitudes a los puntos finales de la acción del workflow personalizado, debes incluir la clave de tu cuenta de desarrollador de HubSpot en la URL de solicitud. Por ejemplo:
https://api.hubspot.com/automation/v4/actions/{appId}?hapikey={API_key}
Define tu acción personalizada
Para crear una acción de flujo de trabajo personalizada, deberás definir la acción usando los siguientes campos. Esta definición también especifica el formato de solicitud para solicitudes procedentes de HubSpot, así como el manejo de respuestas de tu servicio.
- actionUrl: la URL donde se envía una solicitud HTTPS cuando se ejecuta la acción. El cuerpo de la solicitud contiene información sobre a nombre de qué usuario se está ejecutando la acción y qué valores se ingresaron para los campos de entrada.
- inputFields: esto define el conjunto de valores válidos para los datos de la acción, ya sea una lista estática o una URL de webhook. Si se proporciona una URL de webhook, las opciones se recuperan desde esa URL cuando la acción se edita por un cliente en la herramienta Workflows. Estos son opcionales para cada campo.
- outputFields: los valores que se mostrarán en la acción que se pueden usar más tarde en el flujo de trabajo. Una acción personalizada puede tener cero, una o muchas salidas.
- executionRules: una lista de definiciones que puedes especificar para exponer errores de tu servicio al usuario que crea el workflow.
- etiquetas: copia que describe al usuario lo que representa los campos de la acción y lo que hace la acción. Se requieren etiquetas en inglés, pero éstas también pueden especificarse en cualquiera de los siguientes idiomas compatibles: Francés (
fr
), alemán (de
), japonés (ja
), español (es
), portugués de Brasil (pt-br
) y holandés (nl
). La especificación de cada idioma incluye los siguientes campos:
- actionName: el nombre de la acción que aparece en el panel Elegir una acción en el editor de flujos de trabajo.
- actionDescription: una descripción detallada de la acción que se muestra cuando el usuario está configurando la acción personalizada.
- actionCardContent: una descripción resumida que se muestra en la tarjeta de la acción.
- inputFieldLabels: un objeto que mapea las definiciones de inputFields a las etiquetas correspondientes que el usuario verá cuando configure la acción.
- outputFieldLabels: un objeto que mapea las definiciones de outputFields a las etiquetas correspondientes que se muestran en la herramienta de workflows.
- inputFieldDescriptions: un objeto que mapea las definiciones de inputFields a las descripciones debajo de las etiquetas correspondientes.
- executionRules: un objeto que mapea las definiciones de tus executionRules a los mensajes de error que se le mostrarán al usuario si desconecta una acción personalizada. Esto permite especificar mensajes personalizados para los resultados de la ejecución de la acción en el historial del flujo de trabajo.
Se especifica un ejemplo de una definición de acción básica a continuación:
Validar la fuente de solicitud
Las solicitudes realizadas para tu acción personalizada usarán la versión v2 del X-HubSpot-Signature. Más información sobre cómo validar solicitudes de HubSpot.
Carga predeterminada
Hay dos tipos de llamadas realizadas para acciones de flujo de trabajo personalizadas:
- Recuperaciones de opciones de campo: se completa una lista de opciones válidas cuando un usuario está configurando un campo.
- Solicitud de ejecución de acción: se realiza cuando una acción se ejecuta por un flujo de trabajo que incluye tu acción personalizada.
Recuperación de opciones de campo
Las solicitudes de recuperación de opciones se realizan cuando un usuario está configurando su acción personalizada en su flujo de trabajo.
Formato de solicitud:
Formato de respuesta esperado:
Para limitar el número de opciones que se devuelven por una recuperación de opciones, puedes establecer un cursor de paginación, que le indicará a los flujos de trabajo que se pueden cargar más opciones. Si quieres que sea posible buscar en la lista de opciones, puedes volver a "searchable": true
para permitir que los resultados se filtren por una consulta de búsqueda.
Solicitudes de ejecución de acciones
Las solicitudes de ejecución se realizan cuando un flujo de trabajo está ejecutando tu acción personalizada contra un objeto inscrito.
Formato de solicitud:
Personaliza la carga con funciones
Puedes personalizar las solicitudes que se realizan para tu acción personalizada configurando funciones sin servidor para tu acción personalizada.
Personalizar las recuperaciones de opciones de campo
Hay dos ganchos para personalizar el ciclo de vida de recuperación de la opción de campo:
- PRE_FETCH_OPTIONS: esto te permite configurar la solicitud enviada desde HubSpot.
- POST_FETCH_OPTIONS: esto te permite transformar la respuesta de tu servicio en un formato que comprende flujos de trabajo.
PRE_FETCH_OPTIONS
Formato de argumento de entrada de función:
Formato de salida de la función esperada:
POST_FETCH_OPTIONS
Formato de argumento de entrada de función:
Formato de salida de la función esperada:
Personalizar las solicitudes de ejecución
Hay un gancho al ciclo de ejecución de la acción, una función PRE_ACTION_EXECUTION. Esta función te permite configurar la solicitud que se envía desde HubSpot.
Formato de argumento de entrada de función:
Formato de salida de la función esperada:
Publica tu acción personalizada
Por opción predeterminada, tu acción personalizada se crea en un estado sin publicar y sólo será visible en el portal de desarrolladores asociado con tu aplicación de HubSpot. Para que tu acción personalizada sea visible para los clientes, actualiza la bandera publicada
en tu definición de acción a verdadero
.
Prueba tu acción personalizada
Puedes probar tu acción personalizada creando un workflow en la herramienta de workflows y agregar tu acción personalizada.
Ejecutar tu acción personalizada
El éxito de una acción se determina examinando el código de estado devuelto por tu servicio:
- Códigos de estado 2xx: esto indica que la acción se ha completado correctamente.
- Códigos de estado 4xx: esto indica que la acción falló.
- La excepción aquí son los códigos de estado Tasa limitada
429
; estos se vuelven a tratar como reintentos y se respeta el encabezado Reintentar después.
- La excepción aquí son los códigos de estado Tasa limitada
- Códigos de estado 5xx: esto indica que hubo un problema temporal con tu servicio y tu acción se volverá a intentar más tarde.
Bloquear la ejecución de acciones personalizadas
Las acciones personalizadas pueden bloquear la ejecución del flujo de trabajo. En lugar de ejecutar la siguiente acción en el flujo de trabajo después de la acción personalizada tras recibir una respuesta "completada" (2xx o 4xx) de tu servicio, el flujo de trabajo dejará de ejecutar ("bloquear") esa inscripción hasta que el flujo de trabajo continúe.
Para bloquear una acción personalizada asíncronamente, la respuesta de ejecución de tu acción debe tener el siguiente formato:
Opcionalmente, puedes especificar un valor para el campo hs_default_expiration, después de que tu acción personalizada se considere vencida. La ejecución del flujo de trabajo se reanudará y la acción que sigue a la acción personalizada se ejecutará, aunque no le hayas indicado al flujo de trabajo que continúe.
Completar una ejecución bloqueada
Para completar la ejecución de una acción personalizada bloqueada, utiliza el siguiente punto final: /callbacks/{appId}/{callbackId}/complete
.
El formato del cuerpo de la solicitud es:
Añadir mensajes de ejecución personalizados
Reglas específicas sobre tu acción que determinan qué mensaje aparece en la página de historial del flujo de trabajo cuando se ejecuta la acción. Las reglas se emparejarán con los valores de salida de tu acción. Estos valores de salida se deben proporcionar en el cuerpo de la respuesta del webhook, en el siguiente formato:
Las executionRules
se probarán en el orden proporcionado. Si hay varias coincidencias, solo el mensaje de la primera regla que coincida se muestra al usuario.
La regla coincide cuando la salida de ejecución corresponde a un valor especificado en la regla. Por ejemplo, considera este conjunto de executionRules
:
Se producirían las siguientes coincidencias:
{"errorCode": "ALREADY_EXISTS", "widgetName": "Test widget"}
: Esto coincidirá con la primera regla, ya queerrorCode
es igual aALREADY_EXISTS
. En este caso, aunque haya una salidawidgetName
, no se utiliza en la definición de regla, por lo que se permite cualquier valor.{"errorCode": "WIDGET_SIZE", "sizeError": "TOO_SMALL"}
: Esto coincidirá con la segunda regla, ya queTOO_SMALL
es uno de los valores desizeErrorque
coinciden, yerrorCode
esWIDGET_SIZE
.{"errorCode": "WIDGET_SIZE", "sizeError": "NOT_A_NUMBER"}
: Esto coincidirá con la tercera regla, ya que aunque elerrorCode
esWIDGET_SIZE
, elsizeError
no coincide con ninguno de los valores especificados por la segunda regla(TOO_SMALL
oTOO_BIG
).
Este mecanismo de coincidencia te permite especificar errores de reserva, por lo que puedes tener errores específicos para casos de error importantes, pero regresa a mensajes de error genéricos para errores más comunes.
Ejemplo 1
Un ejemplo básico con los siguientes campos de entrada, creados para los flujos de trabajo de los contactos y las transacciones:
- un campo de entrada estático
- un campo desplegable con opciones
- un campo cuyo valor es un propietario de HubSpot
- un campo cuyo valor se extrae de una propiedad (que el usuario que crea el flujo de trabajo selecciona) en el objeto inscrito.
Ejemplo 2
La siguiente acción personalizada utiliza una función sin servidor para transformar la carga que se envía a la acción configurada actionUrl. Dado que no se especifican objectTypes ,esta acción estará disponible en todos los tipos de flujos de trabajo.
Ejemplo 3
La siguiente acción personalizada tiene dependencias y opciones de campo que se recuperan desde una API. Debido a que el tamaño del widget depende del color del widget, el usuario no podrá introducir un valor para el tamaño del widget hasta que se elija un color del widget
El coste del widget también depende del color del widget, pero está condicionado al valor que el usuario seleccione para el color del widget; el usuario no podrá introducir un valor para el coste del widget, a menos que Red esté seleccionada como el color del widget.
Ejemplo 4
El siguiente ejemplo es una acción personalizada de bloqueo. La API de devolución de llamadas se puede usar para indicarle a HubSpot que complete la acción y hacer que el objeto inscrito pase a la siguiente acción en el flujo de trabajo
No necesitarás especificar que la acción se bloquee en el momento en que creas la acción; eso estará determinado por la respuesta de tu actionUrlconfigurada.
Gracias por tus comentarios, son muy importantes para nosotros.